n8n 2.43.7 配置参数详解（环境变量实测）
n8n 2.43.7 核心环境变量分类详解：端口路径/时区/安全 Cookie/数据库/执行保留/日志/指标/任务运行器，实测生效回显与官方默认参考分明，附配置验证三法。
n8n 2.43.7 配置参数详解（环境变量实测）
> 目标：系统梳理 n8n 2.43.7 的核心环境变量，按"实测生效"与"官方默认【参考】"两类标注，给出验证配置是否生效的三种方法。实测环境：Ubuntu 22.04 服务器，n8n 2.43.7，默认数据目录 ~/.n8n，默认 SQLite 数据库。
一、配置体系总览
n8n 的配置有三个来源：
| 来源 | 位置 | 管什么 |
|---|---|---|
| 环境变量 | systemd 的 EnvironmentFile（如 /etc/n8n/n8n.env）或 shell export | 几乎全部行为，本文主角 |
| settings 文件 | ~/.n8n/config | 只存加密密钥 encryptionKey（实测文件内容仅此一项） |
| 编辑器 UI | Settings 页面 | 用户偏好、个性化设置（存数据库） |
config 文件实测内容：
{"encryptionKey": "aJMWh6+Hmeqw0n4EIFhA8J/0ONBoGagG"}
首启日志原文：No encryption key found - Auto-generating and saving to: /home/node/.n8n/config。不要手工编辑它，加密密钥用 N8N_ENCRYPTION_KEY 环境变量控制（见第四节）。
二、服务地址与端口
| 变量 | 默认 | 说明 | 实测 |
|---|---|---|---|
N8N_PORT | 5678 | HTTP 监听端口 | ✅ 设 5682 后 curl :5682/healthz 返回 {"status":"ok"} |
N8N_HOST | 空 | 对外主机名（用于生成 webhook 链接等） | 【参考】 |
N8N_PATH | / | 编辑器 UI 的路径前缀 | ✅ 见下方重要实测 |
WEBHOOK_URL | 由 N8N_HOST/PORT 推导 | 反向代理场景下外部可达的 webhook 基地址 | 【参考】 |
N8N_EDITOR_BASE_URL | 空 | 反代下编辑器外部地址 | 【参考】 |
N8N_PROXY_HOPS | 0 | 反代链路层数（>0 时信任 X-Forwarded-* 头） | 【参考】 |
N8N_PATH 实测细节（容易踩坑）
设 N8N_PATH=/n8n/ 后实测：
- 编辑器页面与静态资源在
/n8n/...下正常； - REST 接口仍在根路径：
/rest/owner/setup、/rest/login照常工作（/n8n/rest/...反而 404）； - 健康检查也在根路径：
/n8n/healthz返回的是编辑器 HTML，真正的{"status":"ok"}在/healthz。
结论：N8N_PATH 只挪 UI，监控与接口路径不变，反代规则要按这个实际行为写。
三、时区与本地化
| 变量 | 默认 | 说明 | 实测 |
|---|---|---|---|
GENERIC_TIMEZONE | America/New_York | 定时触发器、计划任务的业务时区 | ✅ |
TZ | 系统 | 进程系统时区（影响日志时间戳） | ✅ 与业务时区分开 |
N8N_DEFAULT_LOCALE | en | 界面语言 | 【参考】 |
GENERIC_TIMEZONE 生效验证：设为 America/New_York 后，登录态请求 GET /rest/settings 实测回显：
"timezone": "America/New_York"
💡 排查"定时任务半夜没跑"先看这两个变量：日志时间戳由
TZ决定，定时触发时刻由GENERIC_TIMEZONE决定，两者不一致是最常见原因。
四、安全
| 变量 | 默认 | 说明 | 实测 |
|---|---|---|---|
N8N_ENCRYPTION_KEY | 首启自动生成写入 config | 凭证加密密钥 | ✅ 自动生成日志可见；【参考】显式设置后优先用环境变量 |
N8N_SECURE_COOKIE | true | 登录 Cookie 是否带 Secure 标志 | ✅ |
N8N_BLOCK_ENV_ACCESS_IN_NODE | false | 禁止工作流内 $env 读环境变量 | 【参考】 |
N8N_BASIC_AUTH_* | 已移除 | 旧版基础认证不再存在于 2.x | — |
N8N_SECURE_COOKIE 实测对比
登录接口 POST /rest/login 的 Set-Cookie 对比：
默认(true): n8n-auth=...; HttpOnly; Secure; SameSite=Lax
=false: n8n-auth=...; HttpOnly; SameSite=Lax # 无 Secure
即：纯 HTTP 访问编辑器时登录态无法保持（浏览器不回传 Secure Cookie）。生产建议反代 + TLS 保持默认；仅内网临时 HTTP 调试时设 false。
五、数据库
| 变量 | 默认 | 说明 | 实测 |
|---|---|---|---|
DB_TYPE | sqlitedb | 数据库类型 | ✅ |
DB_SQLITE_POOL_SIZE | 0（单连接） | SQLite 连接池 | 【参考】 |
DB_POSTGRESDB_HOST/PORT/DATABASE/USER/PASSWORD | — | PostgreSQL 连接五件套 | ✅ |
DB_POSTGRESDB_SCHEMA | public | schema | 【参考】 |
DB_POSTGRESDB_SSL_ENABLED | false | TLS 连接 | 【参考】 |
切 PostgreSQL 实测：空库启动自动完成全部迁移（启动日志逐条 Starting migration ... / Finished migration ...），完成后统计 157 张表，/healthz 正常。SQLite 库共 157 张表（副本统计），与 PG 建表数一致。
六、执行数据保留
全部【参考官方默认】，生产前按磁盘容量评估。
| 变量 | 默认 | 说明 |
|---|---|---|
EXECUTIONS_DATA_SAVE_ON_SUCCESS | all | 成功执行是否入库（可 none） |
EXECUTIONS_DATA_SAVE_ON_ERROR | all | 失败执行是否入库 |
EXECUTIONS_DATA_SAVE_MANUAL_EXECUTIONS | true | 手动执行是否入库 |
EXECUTIONS_DATA_PRUNE | true | 自动清理 |
EXECUTIONS_DATA_MAX_AGE | 336（小时，14 天） | 清理阈值 |
EXECUTIONS_DATA_PRUNE_MAX_COUNT | 10000 | 最大保留条数 |
EXECUTIONS_DATA_HARD_DELETE_BUFFER | 1（小时） | 硬删除缓冲 |
执行数据是 SQLite/PG 体积膨胀的主因；清理参数调低后记得配合《n8n 2.43.7 运维手册：备份、升级、日志与监控》的 VACUUM。
七、日志
| 变量 | 默认 | 说明 | 实测 |
|---|---|---|---|
N8N_LOG_LEVEL | info | debug/info/warn/error | ✅ |
N8N_LOG_OUTPUT | console | 可 file 或 console,file | ✅ |
N8N_LOG_FILE_LOCATION | ~/.n8n/n8n.log | 日志文件完整路径 | ✅ 踩坑见下 |
N8N_LOG_FILE_SIZE_MAX | 16（MB） | 单文件上限 | ✅ 参数传入生效（轮转行为未长测） |
N8N_LOG_FILE_COUNT_MAX | 100 | 保留轮转份数 | ✅ 同上 |
debug 级别实测格式（console）：
2026-10-17T12:59:42.296Z | debug | Received CLI command {"execPath":"/usr/bin/node",...}
2026-10-17T12:59:42.365Z | debug | Lazy-loading nodes and credentials from n8n-nodes-base {"nodes":500,"credentials":410,...}
file 模式实测格式（JSON 行，逐条可解析）：
{"level":"info","message":"Initializing n8n process","metadata":{"file":"start.js","function":"init","timestamp":"2026-10-17T13:01:10.369Z"}}
⚠️ 踩坑：
N8N_LOG_FILE_LOCATION要给完整文件路径（如~/.n8n/logs/n8n.log）。实测传成目录/home/node/.n8n/logs/时，n8n 会把它当文件名创建出一个叫logs的文件，访问时报Not a directory。
八、监控与遥测
| 变量 | 默认 | 说明 | 实测 |
|---|---|---|---|
N8N_METRICS | false | 暴露 Prometheus 指标 | ✅ |
N8N_METRICS_NAMESPACE | n8n_* | 指标命名空间 | 【参考】 |
N8N_DIAGNOSTICS_ENABLED | true | 匿名产品遥测（上报官方） | 【参考】（n8n audit 报告中回显 diagnosticsEnabled: true） |
开启 metrics 后实测 GET /metrics 输出样例：
# HELP n8n_expression_evaluation_duration_seconds Duration of VM-based expression evaluation in seconds.
# TYPE n8n_expression_evaluation_duration_seconds histogram
# HELP n8n_expression_code_cache_hit_total Expression code cache hits.
默认关闭时 /metrics 实测 404。健康检查始终可用：GET /healthz → {"status":"ok"}。
九、任务运行器（Task Runners）
| 变量 | 默认 | 说明 | 实测 |
|---|---|---|---|
N8N_RUNNERS_ENABLED | 版本相关 | Code 节点独立进程执行 | ✅ 开启时启动日志出现 n8n Task Broker ready on 127.0.0.1, port 5679 |
N8N_RUNNERS_BROKER_PORT | 5679 | Broker 端口 | 【参考】（同机跑第二个 n8n 进程时必须错开，实测 5679 冲突会拒绝启动子命令） |
Python runner 需要系统有 Python 3，缺失时日志原文：Failed to start Python task runner in internal mode. because Python 3 is missing from this system.（JS runner 不受影响）。
十、文件路径与扩展
| 变量 | 默认 | 说明 | 实测 |
|---|---|---|---|
N8N_USER_FOLDER | ~/.n8n | 数据根目录 | ✅ 以服务账户运行时务必显式设置 |
N8N_CUSTOM_EXTENSIONS | 空 | 额外加载的自定义节点目录 | 【参考】 |
N8N_COMMUNITY_PACKAGES_ENABLED | true | 社区节点开关 | 【参考】（对应数据目录 nodes/） |
十一、验证配置生效的三种方法（推荐顺序）
- 启动日志：
journalctl -u n8n -n 50——迁移、加密密钥来源、Task Broker 端口、ready 行都在这里； - 健康/指标端点：
curl :$N8N_PORT/healthz；开 metrics 后抓/metrics； - 内部设置接口：登录后
GET /rest/settings，可直接看到timezone等生效值。
更多运维操作见《n8n 2.43.7 运维手册：备份、升级、日志与监控》；命令行验证工具见《n8n 2.43.7 CLI 命令详解与实测》。