在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

n8n-io/n8n

菜单

CLI 命令和配置

相关源文件

本文档概述了 n8n 中可用的命令行接口 (CLI) 命令以及控制从基本服务器设置到高级工作流执行行为的广泛配置选项。配置值可以通过环境变量或配置文件进行设置。

有关使用 Docker 部署 n8n 的信息，请参阅 Docker 部署。

CLI 命令概述

n8n 提供了几个命令行命令来启动和管理系统的不同组件。主要命令包括：

  1. start - 启动主要的 n8n 进程，包含 Web UI 和 API
  2. worker - 启动一个工作进程，用于在队列模式下处理工作流执行
  3. webhook - 启动一个专用的 webhook 进程，用于处理生产环境的 webhook

来源：packages/cli/src/commands/start.ts39-46 packages/cli/src/commands/worker.ts17-21 packages/cli/src/commands/webhook.ts13-16

配置系统概述

n8n 使用强类型配置系统，从环境变量和文件中加载设置。配置分为逻辑类别，例如数据库、执行、工作流等。

来源：packages/@n8n/config/src/decorators.ts packages/@n8n/config/src/index.ts packages/cli/src/config/index.ts39-70

CLI 命令参考

Start 命令

start 命令启动主要的 n8n 进程，包括 Web UI、API 和工作流管理。

选项

  • --tunnel - 通过 hooks.n8n.cloud 隧道服务器运行 webhooks (用于测试/开发)
  • --open, -o - 自动在浏览器中打开 UI
  • --reinstallMissingPackages - 如果缺少节点包，尝试自我修复 n8n

start 命令初始化所有核心组件，包括：

  • 用于 UI 和 API 的 Web 服务器
  • 用于触发工作流的活动工作流管理器
  • 数据库连接
  • 许可证管理
  • 用于内部通信的事件总线

来源：packages/cli/src/commands/start.ts40-62 packages/cli/src/commands/start.ts174-246

Worker 命令

worker 命令启动一个工作进程，该进程在队列模式下处理工作流执行。

选项

  • --concurrency=<number> - 可以并行运行多少个作业 (默认值：10)

当 n8n 在启用队列模式的分布式设置中运行时，使用 worker 命令。Worker 连接到与主进程相同的 Redis 实例，并从队列中拉取执行作业。

来源：packages/cli/src/commands/worker.ts17-28 packages/cli/src/commands/worker.ts135-147

Webhook 命令

webhook 命令启动一个专用进程来处理生产环境的 webhooks。

webhook 命令在队列模式下使用，用于将 webhook 处理与主进程分离。这使得 webhook 端点可以更好地扩展和提高可靠性。

来源：packages/cli/src/commands/webhook.ts13-16 packages/cli/src/commands/webhook.ts44-60

设置配置值

n8n 中的配置可以通过四种方式设置：

  1. 环境变量：直接在您的环境中设置 (例如：export N8N_PORT=5678)
  2. 配置文件：通过 N8N_CONFIG_FILES 环境变量指定的 JSON 文件
  3. 秘密文件：对于敏感数据，创建带有该值的文件，并使用 _FILE 后缀引用它 (例如：N8N_USER_MANAGEMENT_JWT_SECRET_FILE=/path/to/secret)
  4. 默认值：如果未另行指定，n8n 将使用配置类中编码的默认值

当提供无效值时，n8n 将记录警告并改用默认值。

来源：packages/@n8n/config/src/decorators.ts99-117 packages/cli/src/config/index.ts39-94 packages/@n8n/config/test/config.test.ts415-426

核心配置选项

这些选项控制您的 n8n 实例的基本服务器设置

选项环境变量默认描述
路径N8N_PATH/n8n 部署的路径
主机N8N_HOSTlocalhostn8n 可访问的主机名
端口N8N_PORT5678n8n 可访问的 HTTP 端口
监听地址N8N_LISTEN_ADDRESS::n8n 应监听的 IP 地址
协议N8N_PROTOCOLhttpHTTP 协议 (http 或 https)
SSL 密钥N8N_SSL_KEY``HTTPS 协议的 SSL 密钥
SSL 证书N8N_SSL_CERT``HTTPS 协议的 SSL 证书
编辑器基础 URLN8N_EDITOR_BASE_URL``可访问编辑器的公共 URL
代理跳数N8N_PROXY_HOPS0n8n 运行所在的反向代理数量

来源：packages/@n8n/config/src/index.ts86-103 packages/cli/src/config/schema.ts105-122

进程模式和部署模式

n8n 可以根据各种扩展和可靠性要求以不同的模式部署

来源： packages/cli/src/commands/start.ts203-214 packages/cli/src/commands/worker.ts62-65 packages/cli/src/commands/webhook.ts46-59

执行配置

这些选项控制工作流的执行方式

选项环境变量默认描述
执行模式EXECUTIONS_MODEregular执行模式（regular 或 queue）
最大超时时间EXECUTIONS_TIMEOUT-1最大执行时间（秒），超过此时间将停止执行（使用 -1 禁用超时）
最大可配置超时时间EXECUTIONS_TIMEOUT_MAX3600每个工作流可设置的最大超时时间（秒）
出错时保存数据EXECUTIONS_DATA_SAVE_ON_ERRORall出错时保存的执行数据（all 或 none）
成功时保存数据EXECUTIONS_DATA_SAVE_ON_SUCCESSall成功时保存的执行数据（all 或 none）
保存执行进度EXECUTIONS_DATA_SAVE_ON_PROGRESSfalse是否保存每个已执行节点的进度
保存手动执行EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONStrue保存通过编辑器启动的执行数据
队列恢复间隔N8N_EXECUTIONS_QUEUE_RECOVERY_INTERVAL180检查队列恢复的频率（分钟）
队列恢复批次大小N8N_EXECUTIONS_QUEUE_RECOVERY_BATCH100检查队列恢复的执行批次大小

来源： packages/cli/src/config/schema.ts5-102 packages/cli/src/commands/start.ts365-398

并发设置

选项环境变量默认描述
生产环境限制N8N_CONCURRENCY_PRODUCTION_LIMIT-1在主进程（regular 模式）或工作进程（queue 模式）中允许同时运行的最大生产环境执行数
评估限制N8N_CONCURRENCY_EVALUATION_LIMIT-1允许同时运行的最大评估执行数
Worker 并发数CLI 参数 --concurrency10每个 Worker 可以并行运行的任务数（仅限 worker 命令）

Worker 并发设置对于性能调优尤其重要。设置过低可能导致资源利用不足，而设置过高可能使系统过载。

来源： packages/cli/src/config/schema.ts13-25 packages/cli/src/commands/worker.ts23-28 packages/cli/src/commands/worker.ts135-147

数据库配置

n8n 支持多种数据库后端

选项环境变量默认描述
数据库类型DB_TYPEsqlite要使用的数据库类型（sqlite、postgresdb、mysqldb、mariadb）
表前缀DB_TABLE_PREFIX``数据库表名称的前缀

来源： packages/@n8n/config/src/configs/database.config.ts139-150 packages/cli/src/commands/start.ts286-293

SQLite 配置

选项环境变量默认描述
数据库DB_SQLITE_DATABASEdatabase.sqliteSQLite 数据库文件名
连接池大小DB_SQLITE_POOL_SIZE0连接池大小（设置为 0 可禁用连接池）
启用 WALDB_SQLITE_ENABLE_WALfalse启用 SQLite 的 Write-Ahead Logging 模式
启动时执行 VACUUMDB_SQLITE_VACUUM_ON_STARTUPfalse启动时运行 VACUUM 以优化数据库

来源： packages/@n8n/config/src/configs/database.config.ts114-137 packages/cli/src/commands/start.ts286-293

PostgreSQL 配置

选项环境变量默认描述
主机DB_POSTGRESDB_HOSTlocalhostPostgreSQL 数据库主机
端口DB_POSTGRESDB_PORT5432PostgreSQL 数据库端口
数据库DB_POSTGRESDB_DATABASEn8nPostgreSQL 数据库名
用户DB_POSTGRESDB_USERpostgresPostgreSQL 数据库用户
密码DB_POSTGRESDB_PASSWORD``PostgreSQL 数据库密码
SchemaDB_POSTGRESDB_SCHEMA公开PostgreSQL 数据库 Schema
连接池大小DB_POSTGRESDB_POOL_SIZE2连接池大小
连接超时DB_POSTGRESDB_CONNECTION_TIMEOUT20000连接超时时间（毫秒）

来源： packages/@n8n/config/src/configs/database.config.ts53-88

PostgreSQL SSL 配置

选项环境变量默认描述
SSL 已启用DB_POSTGRESDB_SSL_ENABLEDfalse为 PostgreSQL 连接启用 SSL
CA 证书DB_POSTGRESDB_SSL_CA``SSL 证书颁发机构文件
证书DB_POSTGRESDB_SSL_CERT``SSL 客户端证书文件
键DB_POSTGRESDB_SSL_KEY``SSL 客户端密钥文件
拒绝未经授权的连接DB_POSTGRESDB_SSL_REJECT_UNAUTHORIZEDtrue是否拒绝未经授权的 SSL 连接

来源： packages/@n8n/config/src/configs/database.config.ts27-51 packages/@n8n/config/test/config.test.ts285-290

队列配置

当使用 queue 模式（EXECUTIONS_MODE=queue）时，这些选项控制队列系统

选项环境变量默认描述
Redis 主机QUEUE_BULL_REDIS_HOSTlocalhost队列的 Redis 主机
Redis 端口QUEUE_BULL_REDIS_PORT6379队列的 Redis 端口
Redis 密码QUEUE_BULL_REDIS_PASSWORD``队列的 Redis 密码
Redis 用户名QUEUE_BULL_REDIS_USERNAME``队列的 Redis 用户名
Redis 数据库QUEUE_BULL_REDIS_DB0要使用的 Redis 数据库编号
Redis 集群节点QUEUE_BULL_REDIS_CLUSTER_NODES``逗号分隔的 Redis 集群节点
队列前缀QUEUE_BULL_PREFIXbull队列名称的前缀
优雅关闭超时QUEUE_BULL_GRACEFUL_SHUTDOWN_TIMEOUT30优雅关闭的间隔时间（秒）

来源： packages/@n8n/config/test/config.test.ts214-226

Worker 配置

当运行 queue 模式时，这些选项配置 worker 进程

选项环境变量默认描述
并发不适用 (CLI 参数)10Worker 可以并行运行的任务数
Worker 超时QUEUE_WORKER_TIMEOUT30Worker 超时时间（秒）（已弃用，使用 N8N_GRACEFUL_SHUTDOWN_TIMEOUT）

来源： packages/cli/src/commands/worker.ts22-28 packages/cli/src/commands/worker.ts142-148

安全配置

这些选项控制安全相关设置

选项环境变量默认描述
JWT 密钥N8N_USER_MANAGEMENT_JWT_SECRET自动生成用于 JWT 令牌生成的密钥
JWT 有效期N8N_USER_MANAGEMENT_JWT_DURATION_HOURS168JWT 令牌有效期（小时）
JWT 刷新超时N8N_USER_MANAGEMENT_JWT_REFRESH_TIMEOUT_HOURS0JWT 过期前刷新时间（小时）（0 表示持续时间的 25%）
认证方法不适用 (系统设置)email认证方法（email、ldap 或 saml）
安全 CookieN8N_SECURE_COOKIEtrue为认证 Cookie 设置 Secure 标志
Same-site CookieN8N_SAMESITE_COOKIElaxSame-site Cookie 策略（strict、lax 或 none）
限制文件访问N8N_RESTRICT_FILE_ACCESS_TO``将文件访问限制在特定目录
阻止访问 n8n 文件N8N_BLOCK_ACCESS_TO_N8N_FILEStrue阻止从 Function 节点访问 n8n 文件

来源： packages/cli/src/config/schema.ts132-165 packages/@n8n/config/src/configs/auth.config.ts10-17 packages/@n8n/config/test/config.test.ts285-290

用户管理

电子邮件通知配置

选项环境变量默认描述
邮件模式N8N_EMAIL_MODEsmtp如何发送电子邮件
SMTP 主机N8N_SMTP_HOST``SMTP 服务器主机
SMTP 端口N8N_SMTP_PORT465SMTP 服务器端口
SMTP 安全N8N_SMTP_SSLtrue是否为 SMTP 使用 SSL
SMTP StartTLSN8N_SMTP_STARTTLStrue当 SSL 禁用时是否使用 STARTTLS
SMTP 发件人N8N_SMTP_SENDER``发件人电子邮件地址
SMTP 用户N8N_SMTP_USER``SMTP 用户名
SMTP 密码N8N_SMTP_PASS``SMTP 密码

来源： packages/@n8n/config/src/configs/user-management.config.ts6-48 packages/@n8n/config/src/configs/user-management.config.ts69-76

邮件模板

选项环境变量默认描述
邀请模板N8N_UM_EMAIL_TEMPLATES_INVITE``用于邀请的自定义 HTML 模板路径
密码重置模板N8N_UM_EMAIL_TEMPLATES_PWRESET``用于密码重置的自定义 HTML 模板路径
工作流共享模板N8N_UM_EMAIL_TEMPLATES_WORKFLOW_SHARED``用于工作流共享的自定义 HTML 模板路径
凭证共享模板N8N_UM_EMAIL_TEMPLATES_CREDENTIALS_SHARED``用于凭证共享的自定义 HTML 模板路径

来源： packages/@n8n/config/src/configs/user-management.config.ts50-66

工作流配置

选项环境变量默认描述
默认名称WORKFLOWS_DEFAULT_NAME我的工作流新工作流的默认名称
调用者策略N8N_WORKFLOW_CALLER_POLICY_DEFAULT_OPTIONworkflowsFromSameOwner哪些工作流可以调用当前工作流的默认选项
激活批次大小N8N_WORKFLOW_ACTIVATION_BATCH_SIZE1启动时同时激活的工作流数量

来源： packages/@n8n/config/src/configs/workflows.config.ts9-21

日志配置

选项环境变量默认描述
日志级别N8N_LOG_LEVELinfo日志级别（error, warn, info, debug, silent）
日志输出N8N_LOG_OUTPUTconsole日志输出位置（console, file 或两者以逗号分隔）
文件数量N8N_LOG_FILE_COUNT_MAX100要保留的最大日志文件数量
文件大小N8N_LOG_FILE_SIZE_MAX16每个日志文件的最大大小（MiB）
日志位置N8N_LOG_FILE_LOCATIONlogs/n8n.log日志文件的位置

来源： packages/@n8n/config/src/configs/logging.config.ts24-94

缓存配置

选项环境变量默认描述
缓存后端N8N_CACHE_BACKEND自动版 (auto)用于缓存的后端（memory, redis, auto）
内存最大大小N8N_CACHE_MEMORY_MAX_SIZE3145728内存缓存的最大大小（字节）
内存 TTLN8N_CACHE_MEMORY_TTL3600000内存缓存的生存时间（毫秒）
Redis 前缀N8N_CACHE_REDIS_KEY_PREFIXcacheRedis 缓存键的前缀
Redis TTLN8N_CACHE_REDIS_TTL3600000Redis 缓存的生存时间（毫秒）

来源： packages/@n8n/config/src/configs/cache.config.ts8-41

端点配置

选项环境变量默认描述
REST 端点N/A (内部)restREST API 的端点
Webhook 端点N8N_ENDPOINT_WEBHOOKwebhookWebhook 的端点
Webhook 测试端点N8N_ENDPOINT_WEBHOOK_TESTwebhook-test测试 Webhook 的端点
表单端点N8N_ENDPOINT_FORMform表单的端点
禁用 UIN8N_DISABLE_UIfalse是否禁用 UI
最大载荷大小N8N_PAYLOAD_SIZE_MAX16最大载荷大小（MB）

来源： packages/@n8n/config/test/config.test.ts193-196

外部存储配置（S3）

选项环境变量默认描述
S3 主机N8N_EXTERNAL_STORAGE_S3_HOST``兼容 S3 存储的主机
S3 协议N8N_EXTERNAL_STORAGE_S3_PROTOCOLhttpsS3 连接的协议（http 或 https）
S3 存储桶名称N8N_EXTERNAL_STORAGE_S3_BUCKET_NAME``S3 存储桶的名称
S3 存储桶区域N8N_EXTERNAL_STORAGE_S3_BUCKET_REGION``S3 存储桶的区域
S3 访问密钥N8N_EXTERNAL_STORAGE_S3_ACCESS_KEY``S3 的访问密钥
S3 访问密钥N8N_EXTERNAL_STORAGE_S3_ACCESS_SECRET``S3 的密钥

来源： packages/@n8n/config/src/configs/external-storage.config.ts9-51

时区和区域设置

选项环境变量默认描述
时区GENERIC_TIMEZONEAmerica/New_Yorkn8n 实例的默认时区
默认区域N8N_DEFAULT_LOCALEenUI 的默认区域

来源： packages/@n8n/config/src/configs/generic.config.ts9-20 packages/cli/src/config/schema.ts244-249

表达式计算器配置

选项环境变量默认描述
计算器N8N_EXPRESSION_EVALUATORtournament要使用的表达式计算器（tmpl 或 tournament）
报告差异N8N_EXPRESSION_REPORT_DIFFERENCEfalse是否报告计算器输出的差异

来源： packages/cli/src/config/schema.ts289-301

诊断和遥测设置

选项环境变量默认描述
启用诊断N8N_DIAGNOSTICS_ENABLEDtrue是否启用诊断/遥测
个性化N8N_PERSONALIZATION_ENABLEDtrue是否启用个性化
招聘横幅N8N_HIRING_BANNER_ENABLEDtrue是否在浏览器控制台中启用招聘横幅

来源： packages/cli/src/config/schema.ts226-242 packages/cli/src/config/schema.ts235-242

高级配置结构

来源： packages/@n8n/config/src/index.ts47-156

许可证配置

n8n 使用许可证系统来启用企业功能。许可证配置控制着许可证的管理方式。

选项环境变量默认描述
服务器 URLN8N_LICENSE_SERVER_URLhttps://license.n8n.io/v1许可证服务器 URL
自动续订N8N_LICENSE_AUTO_RENEWAL_ENABLEDtrue是否自动续订许可证
分离浮动许可证N8N_LICENSE_DETACH_FLOATING_ON_SHUTDOWNtrue是否在关机时分离浮动许可证
激活密钥N8N_LICENSE_ACTIVATION_KEY``许可证激活密钥
租户 IDN8N_LICENSE_TENANT_ID1许可证的租户 ID
证书N8N_LICENSE_CERT``临时许可证的许可证证书

许可证系统支持多种企业功能，例如多主设置、高级权限等。在分布式设置中运行时，许可证由主实例管理并共享给从属实例。

来源： packages/cli/src/license.ts33-436 packages/@n8n/config/src/configs/license.config.ts8-22

部署模式和配置示例

n8n 可在不同模式下运行，每种模式都有其自身的配置要求。

主进程（常规模式）

队列模式，带工作进程

多主设置（企业版）

来源： packages/cli/src/commands/start.ts203-214 packages/cli/src/commands/worker.ts17-28 packages/cli/src/commands/webhook.ts13-16

社区节点配置

n8n 支持通过 npm 安装的社区贡献节点。这些设置控制着社区节点的处理方式。

选项环境变量默认描述
已启用N8N_COMMUNITY_PACKAGES_ENABLEDtrue是否启用社区软件包
注册表N8N_COMMUNITY_PACKAGES_NPM_REGISTRYhttps://registry.npmjs.org用于社区软件包的 npm 注册表
重新安装缺失的N8N_REINSTALL_MISSING_PACKAGESfalse启动时是否自动重新安装缺失的软件包
未经验证启用N8N_COMMUNITY_PACKAGES_UNVERIFIED_ENABLEDtrue是否允许安装未经验证的社区软件包
已验证启用N8N_COMMUNITY_PACKAGES_VERIFIED_ENABLEDtrue是否允许安装已验证的社区软件包
阻止加载N8N_COMMUNITY_PACKAGES_PREVENT_LOADINGfalse是否阻止加载社区软件包

社区节点系统允许 n8n 扩展，添加核心包中未包含的节点类型。启用后，用户可以通过 UI 或 API 安装、更新和删除社区节点包。

来源： packages/cli/src/services/community-packages.service.ts68-302 packages/cli/src/commands/start.ts183-198

配置最佳实践

  1. 安全：始终为安全相关设置设置自定义值，例如 N8N_USER_MANAGEMENT_JWT_SECRET
  2. 数据库：对于生产环境，请使用 PostgreSQL 而不是 SQLite
  3. 执行模式：为了扩展，请使用队列模式并配合多个工作进程
  4. 特定环境：为开发、预演和生产环境使用不同的配置
  5. 敏感数据：对敏感值使用 _FILE 后缀（例如 DB_POSTGRESDB_PASSWORD_FILE）
  6. 超时：设置适当的超时时间以防止运行失控的执行
  7. 日志记录：根据您的环境调整日志级别（例如，开发环境使用 debug，生产环境使用 info）
  8. 工作进程并发：根据您的硬件能力调整工作进程并发
  9. 队列恢复：配置队列恢复设置以处理崩溃的执行

来源： packages/@n8n/config/src/decorators.ts22-27 packages/cli/src/commands/worker.ts135-147 packages/cli/src/config/schema.ts89-101

有关 Docker 部署的信息，请参阅 Docker 部署。有关工作流特定配置选项的信息，请参阅 工作流执行引擎。