配置#

功能可用性

Embed功能需要Embed许可证。有关何时使用Embed、成本及授权流程的详细信息，请参阅n8n官网上的Embed页面。

认证#

您可以通过设置n8n内置的认证功能——用户管理来保护n8n。

n8n支持LDAP和SAML。

凭据覆盖#

为向用户提供OAuth登录功能，可在全局范围内覆盖凭据。这些凭据数据对用户不可见，但后端会自动使用。

在编辑器界面中，n8n默认隐藏所有被覆盖的字段。这意味着用户可以通过点击凭据上的"连接"按钮使用OAuth进行认证。

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

使用环境变量#

可通过设置环境变量CREDENTIALS_OVERWRITE_DATA为{ CREDENTIAL_NAME: { PARAMETER: VALUE }}来配置凭据覆盖。

警告

虽然此方法可行，但不推荐使用。环境变量在n8n中不受保护，可能导致数据泄露给用户。

使用REST API#

推荐的方式是通过自定义REST端点加载数据。将CREDENTIALS_OVERWRITE_ENDPOINT设置为该端点对应的访问路径。您可设置CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN来要求访问端点时需提供令牌。配置此令牌后，仅当Authorization头中包含Bearer令牌时方可访问端点。

注意

出于安全考虑，除非设置了CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN，否则端点仅可被调用一次。

例如：

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

export CREDENTIALS_OVERWRITE_ENDPOINT=send-credentials

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

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

随后使用curl命令将其发送并应用到实例上：

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

注意

存在凭据基于其他凭据的情况。例如，googleSheetsOAuth2Api 继承自 googleOAuth2Api。在此情况下，您可以在父凭据（googleOAuth2Api）上设置参数，供所有子凭据（googleSheetsOAuth2Api）使用。

若 CREDENTIALS_OVERWRITE_ENDPOINT_AUTH_TOKEN 设置为 secure-token，curl 命令将为：

使用以下命令发送 OAuth 凭据至本地服务器：
sh curl -H "Content-Type: application/json" -H "Authorization: Bearer secure-token" --data @oauth-credentials.json http://localhost:5678/send-credentials

持久化存储#

若需将凭据覆盖设置存储至数据库，并在多实例/队列模式下自动同步至所有工作节点，请启用以下配置：

export CREDENTIALS_OVERWRITE_PERSISTENCE=true

启用时，n8n会将加密的覆盖凭据存储于settings表中，并广播reload-overwrite-credentials事件使工作进程重新加载最新值。禁用时，覆盖凭据仅保留在加载它们的进程内存中，既不会传播到工作进程，也不会在重启后持久保存。

环境变量#

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

变量	类型	默认值	说明
`EXECUTIONS_TIMEOUT`	数值	`-1`	为所有工作流设置默认超时（秒），超时后n8n将停止执行。用户可在`EXECUTIONS_TIMEOUT_MAX`设置的时间范围内为单个工作流覆盖此值。设为`-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相同的端点和响应结构。详见工作流模板。

后端钩子#

可定义外部钩子，当特定操作运行时n8n会自动执行。例如可用于记录数据、修改数据，或通过抛出错误禁止操作。

可用钩子#

钩子	参数	说明
`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]`	从归档恢复工作流后触发。

注册钩子#

通过注册包含钩子函数的钩子文件进行设置。需设置环境变量EXTERNAL_HOOK_FILES来注册钩子。

可设置为单个文件：

EXTERNAL_HOOK_FILES=/data/hook.js

或多个分号分隔的文件：

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

后端钩子文件#

钩子文件为符合以下格式的常规JavaScript文件：

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.'
                    );
                }
            }
        ]
    }
}

后端钩子函数#

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

若钩子函数的参数为对象，可通过修改该参数的数据来改变 n8n 的行为。

在任意钩子函数中均可通过 this.dbCollections 访问数据库（参考后端钩子文件中的代码示例）。

前端外部钩子#

与后端外部钩子类似，可以在前端代码中定义外部钩子，当用户执行特定操作时由 n8n 触发执行。例如，可用于记录数据和修改数据。

可用钩子#

钩子名称	描述
`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`	当用户保存工作流设置时触发

注册钩子#

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

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

前端钩子文件#

前端外部钩子文件是符合以下格式的常规JavaScript文件：

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
      },
    ],
  },
};

前端钩子函数#

每个钩子可定义多个钩子函数。每个钩子函数调用时会接收以下参数：

store：Vuex 存储库对象。可用于从存储库中修改或获取数据
metadata：包含该钩子所提供数据的对象。要查看具体传递内容，请在 editor-ui 包中搜索对应钩子

认证#​

凭据覆盖#​

使用环境变量#​

使用REST API#​

持久化存储#​

环境变量#​

后端钩子#​

可用钩子#​

注册钩子#​

后端钩子文件#​

后端钩子函数#​

前端外部钩子#​

可用钩子#​

注册钩子#​

前端钩子文件#​

前端钩子函数#​

认证#

凭据覆盖#

使用环境变量#

使用REST API#

持久化存储#

环境变量#

后端钩子#

可用钩子#

注册钩子#

后端钩子文件#

后端钩子函数#

前端外部钩子#

可用钩子#

注册钩子#

前端钩子文件#

前端钩子函数#