配置#

¥Configuration

Feature availability

Embed requires an embed license. For more information about when to use Embed, as well as costs and licensing processes, refer to Embed on the n8n website.

验证#

¥Authentication

你可以通过设置 n8n 的内置身份验证功能用户管理来保护 n8n。

¥You can secure n8n by setting up User management, n8n's built-in authentication feature.

n8n 支持 LDAP 和 SAML 格式。

¥n8n supports LDAP and SAML.

凭据覆盖#

¥Credential overwrites

要为用户提供 OAuth 登录，可以全局覆盖 credentials。此凭据数据对用户不可见，但后端会自动使用它。

¥To offer OAuth login to users, it's possible to overwrite credentials on a global basis. This credential data isn't visible to users but the backend uses it automatically.

在编辑器 UI 中，n8n 默认隐藏所有已覆盖的字段。这意味着用户可以通过点击凭据上的 "connect" 按钮使用 OAuth 进行身份验证。

¥In the Editor UI, n8n hides all overwritten fields by default. This means that users are able to authenticate using OAuth by pressing the "connect" button on the credentials.

n8n 提供两种凭据覆盖方式：使用环境变量和 REST API。

¥n8n offers two ways to apply credential overwrites: using Environment Variable and using the REST API.

使用环境变量#

¥Using environment variables

你可以通过将 CREDENTIALS_OVERWRITE_DATA 设置为 { CREDENTIAL_NAME: { PARAMETER: VALUE }} 来使用环境变量设置凭据覆盖。

¥You can set credential overwrites using environment variable by setting the CREDENTIALS_OVERWRITE_DATA to { CREDENTIAL_NAME: { PARAMETER: VALUE }}.

Warning

尽管这样做是可行的，但不建议这样做。n8n 中未对环境变量进行保护，因此数据可能会泄露给用户。

¥Even though this is possible, it isn't recommended. Environment variables aren't protected in n8n, so the data can leak to users.

使用 REST API#

¥Using REST APIs

推荐的方法是使用自定义 REST 端点加载数据。将 CREDENTIALS_OVERWRITE_ENDPOINT 设置为此端点的可用路径。你可以设置 CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN，使其需要令牌才能访问端点。配置此令牌后，只有当令牌作为 Bearer 令牌包含在 Authorization 标头中时，才能访问该端点。

¥The recommended way is to load the data using a custom REST endpoint. Set the CREDENTIALS_OVERWRITE_ENDPOINT to a path under which this endpoint should be made available. You can set CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN to require a token for accessing the endpoint. When this token is configured, the endpoint is only accessible if the token is included in the Authorization header as a Bearer token.

Note

出于安全原因，除非设置了 CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN，否则端点只能调用一次。

¥The endpoint can be called just once for security reasons, unless CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN is set.

例如：

¥For example:

通过在 n8n 运行的环境中设置环境变量来激活端点：

¥Activate the endpoint by setting the environment variable in the environment n8n runs under:

export CREDENTIALS_OVERWRITE_ENDPOINT=send-credentials

然后需要一个包含要覆盖的凭据的 JSON 文件。例如，用于覆盖 Asana 和 GitHub 凭据的 oauth-credentials.json 文件可能如下所示：

¥A JSON file with the credentials to overwrite is then needed. For example, a oauth-credentials.json file to overwrite credentials for Asana and GitHub could look like this:

{
    "asanaOAuth2Api": {
        "clientId": "<id>",
        "clientSecret": "<secret>"
    },
    "githubOAuth2Api": {
        "clientId": "<id>",
        "clientSecret": "<secret>"
    }
}

然后使用 curl 命令将其应用到实例：

¥Then apply it to the instance by sending it using curl:

curl -H "Content-Type: application/json" --data @oauth-credentials.json http://localhost:5678/send-credentials

Note

有些情况下，凭证会基于其他环境。例如，googleSheetsOAuth2Api 扩展了 googleOAuth2Api。在这种情况下，你可以为所有子凭据 (googleSheetsOAuth2Api) 设置父凭据 (googleOAuth2Api) 的参数。

¥There are cases when credentials are based on others. For example, the googleSheetsOAuth2Api extends the googleOAuth2Api. In this case, you can set parameters on the parent credentials (googleOAuth2Api) for all child-credentials (googleSheetsOAuth2Api) to use.

如果 CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN 设置为 secure-token，则 curl 命令将为：

¥In case CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN is set to secure-token, the curl command will be:

```sh
curl -H "Content-Type: application/json" -H "Authorization: Bearer secure-token" --data @oauth-credentials.json http://localhost:5678/send-credentials
```

持久性#

¥Persistence

要在数据库中存储凭据覆盖并将其自动传播到多实例/队列模式下的所有工作节点，请启用：

¥To store credential overwrites in the database and propagate them automatically to all workers in multi-instance/queue mode, enable:

export CREDENTIALS_OVERWRITE_PERSISTENCE=true

启用后，n8n 会将加密覆盖存储在 settings 表中，并广播 reload-overwrite-credentials 事件，以便工作进程重新加载最新值。禁用后，覆盖操作将保留在加载它们的进程的内存中，不会传播到工作进程，也不会在重启后保留。

¥When enabled, n8n stores the encrypted overwrites in the settings table and broadcasts a reload-overwrite-credentials event so that workers reload the latest values. When disabled, overwrites remain in memory on the process that loaded them and aren't propagated to workers or preserved across restarts.

环境变量#

¥Environment variables

n8n 提供多个可配置的环境变量。以下是托管解决方案中最相关的环境变量：

¥n8n has many environment variables you can configure. Here are the most relevant environment variables for your hosted solution:

变量	类型	默认	描述
`EXECUTIONS_TIMEOUT`	数字	`-1`	为所有工作流设置默认超时时间（以秒为单位），超过此时间后 n8n 将停止执行。用户可以针对单个工作流覆盖此设置，但持续时间不得超过 `EXECUTIONS_TIMEOUT_MAX` 中设定的时长。将 `EXECUTIONS_TIMEOUT` 设置为 `-1` 以禁用此功能。
`EXECUTIONS_DATA_PRUNE`	布尔值	`true`	是否滚动删除过去执行的数据。
`EXECUTIONS_DATA_MAX_AGE`	数字	`336`	执行结束时间（以小时为单位），超过小时后将被删除。
`EXECUTIONS_DATA_PRUNE_MAX_COUNT`	数字	`10000`	数据库中保留的最大执行次数。0 = 无限制
`NODES_EXCLUDE`	字符串数组	*	指定不加载哪些节点。例如，要阻止可能存在安全风险（例如用户不可信）的节点：`NODES_EXCLUDE: "[\"n8n-nodes-base.executeCommand\", \"n8n-nodes-base.readWriteFile\"]"`
`NODES_INCLUDE`	字符串数组	*	指定要加载的节点。
`N8N_TEMPLATES_ENABLED`	布尔值	`true`	启用工作流模板（true）或禁用（false）。
`N8N_TEMPLATES_HOST`	字符串	`https://api.n8n.io`	如果你正在创建自己的工作流模板库，请更改此项。请注意，要使用你自己的工作流模板库，你的 API 必须提供与 n8n 相同的端点和响应结构。有关更多信息，请参阅工作流模板。

后端钩子#

¥Backend hooks

可以定义外部钩子，n8n 会在特定操作运行时执行这些钩子。例如，你可以使用这些凭据来记录数据、更改数据或通过抛出错误来禁止操作。

¥It's possible to define external hooks that n8n executes whenever a specific operation runs. You can use these, for example, to log data, change data, or forbid an action by throwing an error.

可用钩子#

¥Available hooks

钩子	参数	描述
`credentials.create`	`[credentialData: ICredentialsDb]`	在创建新凭据之前调用。用于限制凭据的数量。
`credentials.delete`	`[id: credentialId]`	在删除凭据之前调用。
`credentials.update`	`[credentialData: ICredentialsDb]`	在保存现有凭据之前调用。
`frontend.settings`	`[frontendSettings: IN8nUISettings]`	在 n8n 启动时调用。例如，允许你覆盖前端数据，如显示的 OAuth URL。
`n8n.ready`	`[app: App]`	n8n 准备就绪后调用。例如，用于注册自定义 API 端点。
`n8n.stop`		n8n 进程停止时调用。允许你保存一些流程数据。
`oauth1.authenticate`	`[oAuthOptions: clientOAuth1.Options, oauthRequestData: {oauth_callback: string}]`	在 OAuth1 身份验证之前调用。用于覆盖 OAuth 回调 URL。
`oauth2.callback`	`[oAuth2Parameters: {clientId: string, clientSecret: string \\| undefined, accessTokenUri: string, authorizationUri: string, redirectUri: string, scopes: string[]}]`	在 OAuth2 回调中调用。用于覆盖 OAuth 回调 URL。
`workflow.activate`	`[workflowData: IWorkflowDb]`	工作流激活前调用用于限制活动工作流的数量。
`workflow.afterDelete`	`[workflowId: string]`	工作流删除后调用
`workflow.afterUpdate`	`[workflowData: IWorkflowBase]`	现有工作流保存后调用
`workflow.create`	`[workflowData: IWorkflowBase]`	工作流创建前调用用于限制已保存工作流的数量。
`workflow.delete`	`[workflowId: string]`	工作流删除前调用
`workflow.postExecute`	`[run: IRun, workflowData: IWorkflowBase]`	工作流执行后调用
`workflow.preExecute`	`[workflow: Workflow: mode: WorkflowExecuteMode]`	工作流执行前调用允许你统计或限制工作流执行次数。
`workflow.update`	`[workflowData: IWorkflowBase]`	在保存现有工作流之前调用。
`workflow.afterArchive`	`[workflowId: string]`	工作流归档后调用
`workflow.afterUnarchive`	`[workflowId: string]`	从归档恢复工作流后调用

正在注册钩子#

¥Registering hooks

通过注册包含钩子函数的钩子文件来设置钩子。要注册钩子，请设置环境变量 EXTERNAL_HOOK_FILES。

¥Set hooks by registering a hook file that contains the hook functions. To register a hook, set the environment variable EXTERNAL_HOOK_FILES.

你可以将变量设置为单个文件：

¥You can set the variable to a single file:

EXTERNAL_HOOK_FILES=/data/hook.js

或者，包含多个以冒号分隔的文件：

¥Or to contain multiple files separated by a colon:

EXTERNAL_HOOK_FILES=/data/hook1.js:/data/hook2.js

后端钩子文件#

¥Backend hook files

钩子文件是常规的 JavaScript 文件，格式如下：

¥Hook files are regular JavaScript files that have the following format:

module.exports = {
    "frontend": {
        "settings": [
            async function (settings) {
                settings.oauthCallbackUrls.oauth1 = 'https://n8n.example.com/oauth1/callback';
                settings.oauthCallbackUrls.oauth2 = 'https://n8n.example.com/oauth2/callback';
            }
        ]
    },
    "workflow": {
        "activate": [
            async function (workflowData) {
                const activeWorkflows = await this.dbCollections.Workflow.count({ active: true });

                if (activeWorkflows > 1) {
                    throw new Error(
                        'Active workflow limit reached.'
                    );
                }
            }
        ]
    }
}

后端钩子函数#

¥Backend hook functions

钩子或钩子文件可以包含多个钩子函数，所有函数按顺序执行。

¥A hook or a hook file can contain multiple hook functions, with all functions executed one after another.

如果钩子函数的参数是对象，则可以更改该参数的数据来更改 n8n 的行为。

¥If the parameters of the hook function are objects, it's possible to change the data of that parameter to change the behavior of n8n.

你还可以使用 this.dbCollections 在任何钩子函数中访问数据库（请参阅后端钩子文件中的代码示例）。

¥You can also access the database in any hook function using this.dbCollections (refer to the code sample in Backend hook files.

前端外部钩子#

¥Frontend external hooks

与后端外部钩子类似，可以在前端代码中定义外部钩子，当用户执行特定操作时，n8n 将执行这些钩子。例如，你可以使用它们来记录数据和更改数据。

¥Like backend external hooks, it's possible to define external hooks in the frontend code that get executed by n8n whenever a user performs a specific operation. You can use them, for example, to log data and change data.

可用钩子#

¥Available hooks

钩子	描述
`credentialsEdit.credentialTypeChanged`	现有凭据类型更改时调用。
`credentials.create`	有人创建新凭据时调用。
`credentialsList.dialogVisibleChanged`
`dataDisplay.nodeTypeChanged`
`dataDisplay.onDocumentationUrlClick`	当用户点击帮助文档链接时调用。
`execution.open`	现有执行打开时调用。
`executionsList.openDialog`	当用户从现有工作流执行列表中选择执行项时调用。
`expressionEdit.itemSelected`
`expressionEdit.dialogVisibleChanged`
`nodeCreateList.filteredNodeTypesComputed`
`nodeCreateList.nodeFilterChanged`	有人更改节点面板筛选器时调用。
`nodeCreateList.selectedTypeChanged`
`nodeCreateList.mounted`
`nodeCreateList.destroyed`
`nodeSettings.credentialSelected`
`nodeSettings.valueChanged`
`nodeView.createNodeActiveChanged`
`nodeView.addNodeButton`
`nodeView.createNodeActiveChanged`
`nodeView.mount`
`pushConnection.executionFinished`
`showMessage.showError`
`runData.displayModeChanged`
`workflow.activeChange`
`workflow.activeChangeCurrent`
`workflow.afterUpdate`	当用户更新现有工作流时调用。
`workflow.open`
`workflowRun.runError`
`workflowRun.runWorkflow`	工作流执行时调用。
`workflowSettings.dialogVisibleChanged`
`workflowSettings.saveSettings`	有人保存工作流设置时调用。

正在注册钩子#

¥Registering hooks

你可以通过在页面上加载钩子脚本来设置钩子。一种方法是在项目中创建一个 hooks 文件，并在 editor-ui/public/index.html 文件中添加一个 script 标签：

¥You can set hooks by loading the hooks script on the page. One way to do this is by creating a hooks file in the project and adding a script tag in your editor-ui/public/index.html file:

<script src="frontend-hooks.js"></script>

前端钩子文件#

¥Frontend hook files

前端外部钩子文件是常规的 JavaScript 文件，格式如下：

¥Frontend external hook files are regular JavaScript files which have the following format:

window.n8nExternalHooks = {
  nodeView: {
    mount: [
      function (store, meta) {
        // do something
      },
    ],
    createNodeActiveChanged: [
      function (store, meta) {
        // do something
      },
      function (store, meta) {
        // do something else
      },
    ],
    addNodeButton: [
      function (store, meta) {
        // do something
      },
    ],
  },
};

前端钩子函数#

¥Frontend hook functions

每个钩子可以定义多个钩子函数。每个钩子函数都会使用以下参数调用：

¥You can define multiple hook functions per hook. Each hook function is invoked with the following arguments arguments:

store：Vuex store 对象。你可以使用此方法更改存储中的数据或从中获取数据。

¥store: The Vuex store object. You can use this to change or get data from the store.

metadata：包含钩子提供的任何数据的对象。要查看传递的内容，请在 editor-ui 包中搜索钩子。

¥metadata: The object that contains any data provided by the hook. To see what's passed, search for the hook in the editor-ui package.