配置#

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

认证#

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

n8n 支持 LDAP 和 SAML。

凭据覆盖#

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

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

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

使用环境变量#

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

Warning

虽然这种方法可行，但不推荐使用。因为环境变量在 n8n 中不受保护，数据可能会泄露给用户。

使用 REST API#

推荐的方式是通过自定义 REST 端点加载数据。将 CREDENTIALS_OVERWRITE_ENDPOINT 设置为该端点应提供的路径。

Note

出于安全考虑，这些端点一次只能调用一个。

例如：

通过在 n8n 运行环境中设置环境变量来激活端点：
1
export CREDENTIALS_OVERWRITE_ENDPOINT=send-credentials

然后需要一个包含待覆盖凭据的 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

Note

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

环境变量#

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]`	在保存现有工作流前调用。

注册钩子#

通过注册包含钩子函数的钩子文件来设置钩子。要注册钩子，需设置环境变量 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(
                        '激活的工作流数量已达上限。'
                    );
                }
            }
        ]
    }
}

后端钩子函数#

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

如果钩子函数的参数是对象，可以通过修改该参数的数据来改变 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) {
        // 执行某些操作
      },
    ],
    createNodeActiveChanged: [
      function (store, meta) {
        // 执行某些操作
      },
      function (store, meta) {
        // 执行其他操作
      },
    ],
    addNodeButton: [
      function (store, meta) {
        // 执行某些操作
      },
    ],
  },
};

前端钩子函数#

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

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