n8n API Key 配置教程：凭据、环境变量与安全（2026）

n8n 里叫“Key”的东西至少有三类：管理 n8n 实例的公共 API Key、调用模型服务的 OpenAI 兼容 Key，以及保护数据库里凭据的 N8N_ENCRYPTION_KEY。三者用途不同，放错位置就会带来安全问题。很多“配置不生效”的求助，其实是把其中一种当成了另一种。

本文按“是什么、放哪里、怎么轮换、出了问题怎么查”的顺序讲，适合自托管团队和需要多人协作的实例。

说明：n8n 是 n8n GmbH 的商标，OpenAI 是 OpenAI, Inc. 的商标。本文仅作技术说明，与相关公司无隶属或合作关系。价格与可用模型以站内模型价格页为准。

一、三种 Key 先分清

类型	用途	存放位置	典型请求头
n8n 公共 API Key	调用 n8n 自身的 REST API，管理流程和执行	n8n 界面创建，调用方保存	`X-N8N-API-KEY`
模型服务 Key	调用 OpenAI 兼容接口	n8n 凭证，加密后入库	`Authorization: Bearer ...`
`N8N_ENCRYPTION_KEY`	加密数据库中的凭据	环境变量或 `.n8n` 配置文件	不作为请求头发送

公共 API Key 不能拿去调模型，模型 Key 也不能拿来管理 n8n 工作流。混用最直接的后果是 401，或者把本应只读的权限放大。

二、n8n 公共 API Key 怎么创建

入口在 Settings > n8n API，点 Create an API key，填写 Label 和过期时间。官方文档注明，云端免费试用期不可用公共 API；企业版还可以选择 Scopes，把 Key 限制到 workflow:read、credential:list 这类具体资源与动作。非企业版 Key 默认拥有账号资源的完整访问权限，所以更要控制持有者。

调用时把 Key 放在 X-N8N-API-KEY 请求头，路径通常是 /api/v1：

curl -sS "https://你的-n8n-域名/api/v1/workflows?active=true" \
  -H "accept: application/json" \
  -H "X-N8N-API-KEY: $N8N_API_KEY"

几条规矩：

一把 Key 只服务一个用途，例如 CI、监控或内部工具。
设置过期时间，到期前主动轮换。
不把 Key 写进前端代码、URL 参数或日志。
不用公共 API Key 代替模型 Key。
不需要时用 N8N_PUBLIC_API_DISABLED=true 关闭公共 API。

三、模型凭据：Key 应该放在凭证里

连接 OpenAI 兼容服务，用 OpenAI 类型凭证，填 API Key 和 Base URL。网关地址一般填到 /v1，例如 https://ai.zhongshangqihang.com/v1。Organization ID 只在官方 OpenAI 多组织账号时需要，走兼容网关通常留空。凭证还支持附加自定义请求头，适合网关要求额外标识的场景。

不要让 Key 出现在这些地方：

Code 节点、Set 节点或提示词里；
工作流 JSON 的普通字段里；
Webhook 返回体、执行日志和错误通知里；
截图、录屏和共享文档里。

工作流导出通常不包含凭证本身，但写在节点参数里的 Key 会跟着 JSON 一起流出。团队共享工作流前，先搜索一遍 sk- 和常见 Key 前缀。

四、环境变量：配置可以，密钥仓库不行

自托管 n8n 用环境变量配置端口、数据库、Webhook 地址等。N8N_ENCRYPTION_KEY、数据库密码这类敏感值也应通过环境变量或密钥管理服务注入，而不是写在 Compose 文件里提交到 Git。部分变量支持 _FILE 后缀，把值放在单独文件中读取。

但环境变量不是安全的密钥仓库。n8n 文档明确提示，环境变量在 n8n 中不受保护，可能泄露给用户；因此用 CREDENTIALS_OVERWRITE_DATA 批量下发凭据并不被推荐，更稳妥的是带鉴权的 overwrite endpoint。

如果允许业务人员编辑工作流，建议开启 N8N_BLOCK_ENV_ACCESS_IN_NODE=true，阻止表达式和 Code 节点读取环境变量。该变量默认是 false，修改后要重启实例。还要注意，执行历史会保存节点输入输出，敏感字段应在进入 n8n 前脱敏，或用 EXECUTIONS_DATA_MAX_AGE 缩短保留时间。

五、加密密钥：丢了一切凭据都读不出来

首次启动时，n8n 会自动生成加密密钥，保存在 ~/.n8n 目录，并用它加密要写入数据库的凭据。也可以通过 N8N_ENCRYPTION_KEY 指定自定义值。官方文档明确说明：丢失这把密钥，所有已保存的凭据都无法读取。

因此备份要成对做：数据库备份和加密密钥分开保存、分别控制访问。只备份数据库，恢复后没有原密钥，凭证仍然解不开；只备份密钥，数据库丢了也没有意义。

队列模式下，主实例和所有 worker 必须使用同一个 N8N_ENCRYPTION_KEY，否则 worker 无法解密主实例写入的凭据。扩容前先把这一点写进部署清单。

n8n 3.0 起默认支持数据加密密钥轮换，2.x 需要手动开启 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true，并在所有节点上保持一致。轮换前先做完整数据库备份；官方文档还提醒，启用新格式后不要降级到旧版本。轮换入口在 Settings > Data Encryption Keys。

六、轮换与最小权限

密钥管理不是“设一次就不管”，而是持续收敛权限：

分环境：开发、测试、生产各用不同 Key，生产 Key 不放在开发机。
分项目：一个项目一把 Key，按用量和额度分别观察。
分人员：每人自己的 Key，离职时单独吊销，不搞全员共用。
短过期：公共 API Key 设置过期时间；模型 Key 也定期轮换。
先建后删：轮换时先创建新 Key、更新调用方、验证通过，再吊销旧 Key。
最小权限：企业版公共 API Key 只勾选必要 scopes；项目角色只给需要的权限。
限制用途：部分基于 Web API 的凭证可配置允许的 HTTP 请求域名，降低 Key 被拿去请求其他地址的风险。
审计：保留 Key 创建、使用和删除记录，异常用量及时告警。

七、团队角色与凭据共享

n8n 的实例角色包括 Owner、Admin 和 Member，项目和凭证可以按项目隔离。社区版的凭证放在个人空间；支持项目的版本可以把凭证放进项目，供项目成员使用。自定义角色和企业级细粒度权限属于企业版能力，具体范围以官方文档为准。

实践建议：

Owner 只留少数人，日常操作使用 Admin 或 Member。
业务工作流放项目，凭证也放项目，不放在个人空间。
凭证命名统一为“服务-环境-用途”，例如“网关-生产-客服摘要”。
不共享登录账号，不把个人 Key 发给同事。
开启 MFA，生产实例强制 HTTPS，并设置 N8N_SECURE_COOKIE=true。
生产环境使用外部 task runner；官方文档已把 internal 模式标记为不推荐，并从 3.0 起弃用。

企业版还可以使用外部密钥存储，把 1Password Connect、AWS Secrets Manager、Azure Key Vault、GCP Secrets Manager、HashiCorp Vault 或 Infisical 中的值引用到凭证字段。引用只在该字段内解析，不会出现在工作流其他表达式里。

八、常见故障排查

现象	可能原因	处理
凭据无法解密	换了 `N8N_ENCRYPTION_KEY`，或恢复了旧数据库	换回原密钥；用配套备份恢复
公共 API 返回 401	缺少或过期 `X-N8N-API-KEY`	重新创建 Key，检查请求头
公共 API 返回 403	企业版 scopes 不足	补足 `workflow:read` 等必要 scope
模型请求 401	模型 Key 错误、过期或未选中凭证	重填 Key，确认凭证绑定到节点
环境变量读不到	变量未传入容器，或节点访问被禁用	检查 Compose 环境，确认 `N8N_BLOCK_ENV_ACCESS_IN_NODE`
worker 报解密失败	worker 与主实例密钥不一致	统一 `N8N_ENCRYPTION_KEY` 后重启

排查顺序建议从“最近改了什么”开始：换 Key、改 Base URL、升级版本、迁移数据库，这四类变更最容易引发密钥问题。一次只改一个变量，改完立即用最小请求验证。

常见问题

n8n API Key 和 OpenAI API Key 是一回事吗？

不是。n8n API Key 用来调用 n8n 自身的 REST API，请求头是 X-N8N-API-KEY；OpenAI 兼容 Key 用来调用模型接口，放在凭证里，由节点以 Bearer 方式发送。

n8n 公共 API Key 支持权限范围吗？

企业版支持 Scopes，可以限制到具体资源和动作，官方建议只授予必要范围。非企业版 Key 默认拥有账号资源的完整访问权限，因此要按人和用途拆分，并设置过期时间。

修改 `N8N_ENCRYPTION_KEY` 会怎样？

已经加密保存的凭据通常无法再解密。首次部署时就应固定该值并做好备份；需要更换时，先评估是否可以通过官方的密钥轮换功能完成，不要直接改环境变量。

可以把 Key 放在环境变量里给工作流用吗？

可以但不推荐。n8n 文档提示环境变量不受保护，可能泄露给用户。更稳妥的做法是使用凭证或外部密钥存储；如果必须用环境变量，至少开启 N8N_BLOCK_ENV_ACCESS_IN_NODE，并限制实例访问权限。

团队共用一把模型 Key 行不行？

不建议。共用 Key 无法区分用量，一人泄露全员受影响，也无法单独吊销。按项目、环境或人员拆 Key，配合网关的额度与用量报表，成本和安全都更可控。

下一步

n8n 的密钥体系可以记成一句话：公共 API Key 管实例，模型 Key 管调用，加密密钥管数据库。三者分开存放、分别轮换，再配合项目角色、过期时间和审计，才算把配置做完整。需要统一模型入口和用量管理，可以注册中商起航 AI 网关，模型与价格以模型价格页为准。