n8n 中文文档

日志流

提示

Feature availability 功能可用性

日志流可用于:

  • n8n Cloud: Enterprise
  • Self-hosted: Enterprise

日志流允许您将事件从 n8n 发送到您自己的日志工具。这使您能够在自己的警报和日志记录流程中管理 n8n 监控。

设置日志流

要使用日志流,您必须添加一个流目的地。

  1. 导航到 Settings 设置 > Log Streaming 日志流。
  2. 选择 Add new destination 添加新目的地。
  3. 选择您的目的地类型。n8n 打开 New Event Destination 新事件目的地 模态框。
  4. 在 New Event Destination 新事件目的地 模态框中,输入事件目的地的配置信息。这些取决于您使用的目的地类型。
  5. 选择 Events 事件 以选择要流式传输的事件。
  6. 选择 Save 保存。

提示

Self-hosted users 自托管用户

如果您自行托管 n8n,则可以使用环境变量 配置其他日志流行为。您还可以从环境变量管理目标,请参阅使用环境变量配置日志流目标。

每进程事件日志文件

n8n 会先将每个发出的事件持久化到本地日志文件中,再转发到日志流目标。该文件在重启后仍会保留,并允许 n8n 重新发送之前尚未投递成功的事件。

默认情况下,n8n 会将事件日志写入 <n8n-user-folder>/n8nEventLog.log,其中 worker 或 webhook processor 进程会自动附加 -worker 或 -webhook-processor 后缀。当一个事件日志文件只由单个 n8n 进程持有时,这一默认行为没有问题。

警告

Shared writable filesystems 共享可写文件系统

如果多个 n8n 进程共享一个可写卷,例如由 NFS 或 EFS 上的共享持久卷支持的队列模式 工作线程,则它们不得写入同一事件日志文件。来自多个进程的并发追加可能会交错或损坏文件,从而导致恢复失败和丢失事件。

为了避免这种情况,请将每个进程上的 N8N_EVENTBUS_LOGWRITER_LOGFULLPATH 设置为以 .log 结尾的唯一绝对路径。 n8n 逐字使用配置的路径,并且不附加进程类型后缀,因此您的编排器拥有跨进程的唯一性。

伴随变量 N8N_EVENTBUS_LOGWRITER_MAXTOTALMESSAGESPERFILE 限制 n8n 在恢复期间从单个事件日志文件解析的行数,因此损坏的文件无法耗尽进程内存。

注意:

  • 当未设置 N8N_EVENTBUS_LOGWRITER_LOGFULLPATH 时,默认行为保持不变。
  • 设置该变量后,n8n 不会自动为路径附加后缀。每个进程都必须拿到自己的独立值。
  • 如果此前部署中已存在共享的 n8nEventLog-worker.log 文件,请在启用此配置前手动隔离处理。n8n 不会自动删除旧文件。

事件

以下事件可用。您可以在Settings 设置 > Log Streaming 日志流 > Events 事件中选择要流式传输的事件。

  • 工作流
    • 已开始
    • 成功
    • 失败
    • 已取消
  • 节点执行
    • 已开始
    • 已完成
  • 审计
    • 用户登录成功
    • 用户登录失败
    • 用户登录电子邮件冲突
    • 用户已注册
    • 用户更新
    • 用户已删除
    • 用户已邀请
    • 已接受用户邀请
    • 重新邀请用户
    • 用户邮箱发送失败
    • 请求用户重置
    • 用户重置
    • 创建用户凭据
    • 共享用户凭据
    • 更新了用户凭据
    • 用户凭据已删除
    • 已创建用户 API
    • 已删除用户 API
    • 启用用户 MFA
    • 用户 MFA 已禁用
    • 已删除用户执行
    • 已显示执行数据
    • 执行数据显示失败
    • 已安装包
    • 包已更新
    • 包已删除
    • n8n package 导入成功
    • n8n package 导出成功
    • n8n package 导出失败
    • n8n package 导入失败
    • 已创建工作流
    • 工作流已删除
    • 工作流已更新
    • 工作流已归档
    • 工作流已取消归档
    • 工作流已激活
    • 工作流已停用
    • 工作流版本已更新
    • 工作流已执行
    • 工作流正在等待
    • 工作流已恢复
    • 创建变量
    • 变量更新
    • 变量已删除
    • 已保存外部密钥提供程序设置
    • 已重新加载外部密钥提供程序
    • 已创建外部密钥连接
    • 已更新外部密钥连接
    • 已删除外部密钥连接
    • 已测试外部密钥连接
    • 已重新加载外部密钥连接
    • 已创建 Environments 提供方
    • 已更新 Environments 提供方
    • 已删除 Environments 提供方
    • 已创建环境
    • 已更新环境
    • 已删除环境
    • 个人发布受限启用
    • 个人发布受限禁用
    • 启用个人共享限制
    • 个人共享受限禁用
    • 启用 2FA 强制执行
    • 2FA 强制执行已禁用
    • 公共 API 速率限制已启用
    • 公共 API 速率限制已禁用
    • 公共 API 速率限制已更新
    • token 交换成功
    • token 交换失败
    • token 交换嵌入式登录
    • token 交换嵌入式登录失败
    • token 交换身份已关联
    • token 交换用户已配置
    • token 交换角色已更新
    • 角色映射角色已解决
    • 创建角色映射规则
    • 更新角色映射规则
    • 删除角色映射规则
    • 角色映射规则批量删除
    • MCP OAuth 已完成
    • MCP 工具已调用
    • MCP 访问已更新
  • Worker 工作进程
    • 已启动
    • 已停止
  • AI 节点日志
    • Memory 获取消息
    • Memory 已添加消息
    • Output Parser 解析完成
    • Retriever 获取相关文档
    • Embeddings 已嵌入文档
    • Embeddings 已嵌入查询
    • 文档已处理
    • Text Splitter 已分割
    • Tool 已调用
    • Vector Store 已搜索
    • LLM 已生成
    • LLM 错误
    • Vector Store 已填充
    • Vector Store 已更新
  • Runner 任务运行器
    • 已请求任务
    • 已收到响应
  • 队列
    • 作业已排队
    • 作业出队
    • 作业已完成
    • 作业失败
    • 作业停滞

审计事件中有两组都提到了 package,但二者并不相关。Package installed 已安装包、Package updated 包已更新 和 Package deleted 包已删除 指实例上安装的社区节点。n8n package 事件指 n8n packages,也就是用于在实例之间迁移工作流的可移植归档文件。

工作流事件

四个 Workflow 工作流 事件涵盖单次工作流执行的生命周期。

事件名称 发送时机
n8n.workflow.started 工作流开始执行。
n8n.workflow.success 工作流执行完成且没有错误。
n8n.workflow.failed 工作流执行因错误而结束。
n8n.workflow.cancelled 有人或某项操作取消正在运行的执行。

要流式传输全部四个事件,请让目标订阅 n8n.workflow。在 Settings 设置 > Log Streaming 日志流 > Events 事件 中,它们位于 Workflow 工作流 组。

每个事件都包含 executionId、workflowId 和 workflowName。

n8n.workflow.started、n8n.workflow.success 和 n8n.workflow.failed 还包含:

字段 说明
userId 执行所属的用户。当执行由 n8n 自行启动时(例如通过计划触发器启动),此字段不存在。
mode 执行模式,例如 trigger、manual、webhook 或 retry。
isManual 有人从编辑器手动启动执行时为 true。
projectId、projectName 工作流所属的项目(如果工作流属于某个项目)。

n8n.workflow.success 和 n8n.workflow.failed 还包含布尔值 success:在成功事件中为 true,在失败事件中为 false。

n8n.workflow.failed 还包含:

字段 说明
lastNodeExecuted 执行失败时正在运行的节点名称。
errorNodeType 该节点的类型,例如 n8n-nodes-base.httpRequest。
errorMessage 字符串形式的错误消息。

n8n.workflow.cancelled 还包含 reason,这是一个说明执行取消原因的字符串。

提供方和环境事件

这六个审计事件记录 Environments 功能中对提供方和环境的成功更改。提供方存储 n8n 用于连接 Git 主机的凭据。环境使用一个提供方和一个仓库,来定义 n8n 将工作流发送到哪里或从哪里获取工作流。

事件名称 发送时机
n8n.audit.promotions.provider.created 用户创建提供方。
n8n.audit.promotions.provider.updated 用户更新提供方。
n8n.audit.promotions.provider.deleted 用户删除提供方。
n8n.audit.promotions.environment.created 用户创建环境。
n8n.audit.promotions.environment.updated 用户更新环境。
n8n.audit.promotions.environment.deleted 用户删除环境。

要流式传输全部六个事件,请让目标订阅 n8n.audit.promotions。在 Settings > Log Streaming > Events 中,它们显示在 Audit 分组下。

公共 API 速率限制事件

提示

功能可用性

enabled 和 disabled 事件从 n8n 2.47.0 起可用。updated 事件从 n8n 2.49.0 起可用。

这些审计事件记录实例 Owner 或 Admin 开启或关闭 API 速率限制,或者更改某个限制或时间窗口的操作。这些更改可以来自 Settings > Policies,也可以来自 n8n 公共 API。

事件名称 发送时机
n8n.audit.public-api-rate-limit.enabled 实例 Owner 或 Admin 开启速率限制。包含执行操作的用户。
n8n.audit.public-api-rate-limit.disabled 实例 Owner 或 Admin 关闭速率限制。包含执行操作的用户。
n8n.audit.public-api-rate-limit.updated 实例 Owner 或 Admin 更改至少一个限制或时间窗口。包含执行操作的用户,以及只含已更改值的 before 和 after。

例如,将所有端点的读取限制从 1,200 改为 100 时,事件会包含 "before": { "globalReadLimit": 1200 } 和 "after": { "globalReadLimit": 100 }。一次既开启速率限制又更改某个限制的保存操作会发送两个事件:enabled 和 updated。

在以下情况下,n8n 不会发送事件:

  • 通过环境变量开启速率限制或设置某个值。
  • 保存操作没有更改任何内容。
  • n8n 以 429 响应拒绝请求。

要流式传输全部三个事件,请让目标订阅 n8n.audit.public-api-rate-limit。在 Settings > Log Streaming > Events 中,它们显示在 Audit 分组下。

MCP 事件

提示

功能可用性

MCP 审计事件从 n8n 2.34.0 开始提供。

三个 MCP 审计事件涵盖实例 MCP 服务器,你可以在 Settings 设置 > Instance-level MCP 实例级 MCP 中将其开启。它们不涵盖使用 MCP Server Trigger 节点的工作流。有关二者的区别,请参阅连接到 n8n MCP 服务器。

事件名称 发送时机
n8n.audit.mcp.oauth.completed 用户完成通过 OAuth 授权 MCP 客户端。包含 userId、clientId 和 clientName。
n8n.audit.mcp.tool.called MCP 客户端调用工具。请参阅下方字段。
n8n.audit.mcp.access.updated 有人开启或关闭实例 MCP 访问。包含执行操作的用户和新的 enabled 值。

要流式传输全部三个事件,请让目标订阅 n8n.audit.mcp。在 Settings 设置 > Log Streaming 日志流 > Events 事件 中,它们位于 Audit 审计 组。

n8n.audit.mcp.tool.called 包含以下字段:

字段 说明
userId 客户端使用其凭据进行身份验证的用户。
_email、_firstName、_lastName、globalRole 该用户的详细信息。
toolName 调用的工具,例如 execute_workflow。
workflowId 工具操作的工作流(如适用)。
status success 或 error。
errorMessage 调用失败的原因。仅在 status 为 error 时存在。
authType oauth 或 api_key。api_key 涵盖不是 OAuth access token 的所有 bearer token。authType 从 n8n 2.34.0 开始提供。
clientId 此调用进行身份验证时使用的 OAuth 客户端,即向实例注册的客户端。当 authType 为 oauth 时存在。clientId 从 n8n 2.34.0 开始提供。
clientName 客户端报告的自身名称。

要衡量每个客户端的使用情况,请按 clientId 分组。它标识一个客户端注册,因此同一客户端的每次调用(包括 token 刷新后的调用)都会保持相同值。同一产品的两个安装会分别注册并获得不同值,因此 clientId 统计的是注册数而不是产品数。clientName 未经验证且不唯一,因此不要将它用作键。

在目标上设置 anonymizeAuditMessages 会掩盖用户的电子邮件地址和姓名,但不会掩盖 userId、authType 或 clientId,因此仍可按这些字段分组和计数。

目的地

n8n 支持三种目的地类型:

  • syslog 服务器
  • 通用 webhook
  • Sentry 客户端

使用环境变量进行配置

如果您自行托管 n8n,则可以从环境变量而不是 UI 管理日志流目标。此功能从 n8n 2.19.0 起可用。将 N8N_LOG_STREAMING_MANAGED_BY_ENV 设置为 true 并以 N8N_LOG_STREAMING_DESTINATIONS 中的 JSON 数组形式提供您的目的地。n8n 在每次启动时重新应用这些并将 Log Streaming 日志流 UI 锁定为只读。有关完整模式,请参阅使用环境变量管理实例设置。

变量 类型 默认 描述
N8N_LOG_STREAMING_MANAGED_BY_ENV Boolean false 设为 true 后,可通过环境变量管理日志流。启用后,n8n 会在每次启动时应用日志流相关变量,并锁定对应的 UI 控件。
N8N_LOG_STREAMING_DESTINATIONS JSON string - 日志流目标的 JSON 数组。每个目标都是一个对象,type 可为 webhook、syslog 或 sentry,并附带该类型对应的配置。

常用字段

无论 type 是什么,每个目标都支持以下字段。

字段 类型 必填 说明
type "webhook" | "syslog" | "sentry" 是 目标类型。它决定了还会使用哪些该类型专属字段。
label string 否 UI 中显示的名称。
enabled boolean 否 是否让该目标转发事件。
subscribedEvents string[] 否 要转发的事件名或事件组前缀(例如 n8n.audit、n8n.workflow)。
anonymizeAuditMessages boolean 否 是否从 n8n.audit.* 事件中剥离敏感 payload 数据。
circuitBreaker object 否 失败保护设置。请参阅熔断器。

Webhook

字段 类型 必填 默认值 说明
url string (URL) 是 - 接收事件 payload 的端点。
method "GET" | "POST" | "PUT" 否 "POST" 投递时使用的 HTTP 方法。
sendQuery boolean 否 false 是否发送查询参数。
specifyQuery "keypair" | "json" 否 "keypair" 当 sendQuery 为 true 时,查询参数的格式。
queryParameters { parameters: [{ name, value }] } 否 - 以键值对形式表示的查询参数。当 specifyQuery 为 "keypair" 时使用。
jsonQuery string 否 "" 以 JSON 字符串表示的查询参数。当 specifyQuery 为 "json" 时使用。
sendHeaders boolean 否 false 是否发送 headers。
specifyHeaders "keypair" | "json" 否 "keypair" 当 sendHeaders 为 true 时,headers 的格式。
headerParameters { parameters: [{ name, value }] } 否 - 以键值对形式表示的 headers。当 specifyHeaders 为 "keypair" 时使用。
jsonHeaders string 否 "" 以 JSON 字符串表示的 headers。当 specifyHeaders 为 "json" 时使用。
options object 否 {} 连接级选项。请参阅Webhook 选项。

Webhook 选项

字段 类型 必填 默认值 说明
allowUnauthorizedCerts boolean 否 false 忽略 SSL 证书校验。
queryParameterArrays "repeat" | "brackets" | "indices" 否 "brackets" 查询参数中数组的编码格式。当 sendQuery 为 true 时使用。
redirect { redirect: { followRedirects, maxRedirects } } 否 { redirect: {} } 是否跟随 HTTP 重定向。followRedirects 默认值为 false;maxRedirects 默认值为 21。
proxy { proxy: { protocol, host, port } } 否 { proxy: {} } HTTP/HTTPS 代理。protocol 可为 "https" 或 "http";host 默认为 "127.0.0.1";port 默认为 9000。
timeout integer ≥ 1 (ms) 否 5000 在中止前等待服务器开始响应的时间,单位为毫秒。
socket { keepAlive, maxSockets, maxFreeSockets } 否 { keepAlive: true, maxSockets: 50, maxFreeSockets: 5 } socket 池配置。maxSockets 和 maxFreeSockets 都必须是大于等于 1 的整数。
[
  {
    "type": "webhook",
    "label": "Audit",
    "subscribedEvents": ["n8n.audit", "n8n.workflow"],
    "anonymizeAuditMessages": true,
    "url": "https://hooks.example.com/n8n",
    "method": "POST",
    "sendHeaders": true,
    "specifyHeaders": "keypair",
    "headerParameters": {
      "parameters": [
        { "name": "Authorization", "value": "Bearer s3cret" }
      ]
    },
    "options": {
      "timeout": 5000,
      "redirect": { "redirect": { "followRedirects": true, "maxRedirects": 5 } }
    }
  }
]

Syslog

字段 类型 必填 默认值 说明
host string 是 - Syslog 服务器主机名或 IP。
port number 否 514 Syslog 服务器端口。
protocol "udp" | "tcp" | "tls" 否 "udp" 传输协议。
tlsCa string 当 protocol 为 "tls" 时必填 "" TLS 连接使用的 PEM 格式 CA 证书。
facility number 否 16 Syslog facility 代码。允许值包括:0(Kernel)、1(User)、3(System)、13(Audit)、14(Alert)、16 到 23(Local0 到 Local7)。
app_name string 否 "n8n" 用作 syslog APP-NAME 的值。
[
  {
    "type": "syslog",
    "label": "SIEM",
    "subscribedEvents": ["n8n.audit", "n8n.workflow"],
    "host": "syslog.example.com",
    "port": 514,
    "protocol": "tls",
    "tlsCa": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----",
    "facility": 16,
    "app_name": "n8n"
  }
]

Sentry

字段 类型 必填 默认值 说明
dsn string (URL) 是 - Sentry DSN client key。
[
  {
    "type": "sentry",
    "label": "Sentry prod",
    "subscribedEvents": ["n8n.workflow"],
    "dsn": "https://[email protected]/1"
  }
]

熔断器

熔断器会在连续失败达到阈值后,暂时停止向某个目标投递,从而避免继续给异常的下游服务施压。所有目标类型都支持此功能。

字段 类型 必填 默认值 说明
maxFailures integer ≥ 1 否 5 当 failureWindow 时间窗内的失败次数达到该值时,n8n 会停止向该目标发送请求。
failureWindow integer ≥ 100 (ms) 否 60000 用于统计失败次数的滑动时间窗。更早的失败会过期。
{ "circuitBreaker": { "maxFailures": 3, "failureWindow": 30000 } }

完整示例

N8N_LOG_STREAMING_MANAGED_BY_ENV=true
N8N_LOG_STREAMING_DESTINATIONS='[
  {
    "type": "webhook",
    "label": "Ops webhook",
    "enabled": true,
    "subscribedEvents": ["n8n.workflow", "n8n.audit"],
    "anonymizeAuditMessages": true,
    "url": "https://hooks.example.com/n8n",
    "method": "POST",
    "sendHeaders": true,
    "specifyHeaders": "keypair",
    "headerParameters": {
      "parameters": [
        { "name": "Authorization", "value": "Bearer s3cret" }
      ]
    },
    "circuitBreaker": { "maxFailures": 5, "failureWindow": 60000 }
  },
  {
    "type": "sentry",
    "label": "Sentry prod",
    "subscribedEvents": ["n8n.workflow"],
    "dsn": "https://[email protected]/1"
  }
]'

如果使用 terraform-aws-n8n 模块在 AWS 上部署 n8n,请参阅在 AWS 上配置 Enterprise 功能。

相关资源

不想自己部署和维护 n8n?n8ncn 托管 n8n 云服务:开通账号即可使用,不用买服务器;也可以在 n8ncn 工作流库 找现成的中文工作流。