加密密钥轮换
提示
Feature availability 功能可用性
加密密钥轮换适用于:
- Self-hosted: 所有版本
n8n Cloud 不支持此功能。
从 n8n 3.0 起,加密密钥轮换默认启用。在更早的版本中,需要通过环境变量启用。
您需要成为实例所有者才能开启或关闭该功能,以及轮换密钥。
加密密钥轮换允许你在不更改实例主加密密钥的前提下,定期替换用于加密 n8n 数据的密钥,例如凭据、OAuth token 以及其他敏感内容。
加密密钥轮换的工作原理
n8n 使用双层密钥模型:
- 实例加密密钥(
N8N_ENCRYPTION_KEY):这是部署时设置的主密钥。它不会变化。n8n 仅使用它来保护数据加密密钥。 - 数据加密密钥:这是直接用于加密凭据数据的密钥,也是你要轮换的密钥。n8n 会将其以加密形式存储在数据库中,由实例密钥保护。
轮换时,n8n 会生成一个新的数据加密密钥,并将其用于之后的所有写入。使用旧密钥加密的现有数据仍然可以读取。n8n 会在你下一次更新对应记录时,静默地将其重新加密到新密钥下。
开始之前
警告
请先进行完整数据库备份
一旦 n8n 使用数据加密密钥写入数据,旧版本 n8n 就无法读取这些数据。请在启用此功能之前备份数据库;升级到会自动启用此功能的 n8n 3.0 之前也应备份。有关详细信息,请参阅向后兼容性和回滚。
你还需要确保:
- 所有 n8n 实例,包括主实例和所有 worker,都共享同一个
N8N_ENCRYPTION_KEY值。 - 你可以直接控制环境变量和 n8n 数据库。这只适用于自托管部署。
启用加密密钥轮换
从 n8n 3.0 起,加密密钥轮换默认启用,无需设置。升级后的首次启动会生成初始数据加密密钥,并将其以加密形式存储在数据库中。
在 n8n 2.x 中,请自行启用此功能:
-
在所有 n8n 实例上设置以下环境变量,包括主实例和 worker:
sh N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true -
重启所有实例。启动时,n8n 会自动生成初始数据加密密钥,并以加密形式存入数据库。
要确认功能已启用,请进入 Settings 设置 > Data Encryption Keys 数据加密密钥。你应该能看到当前生效的密钥。
旋转活动密钥
启用该功能后,你可以随时轮换到新的数据加密密钥。
使用用户界面
进入 Settings > Data Encryption Keys,然后选择 Rotate key。
使用 API
向 /encryption/keys 端点发送一个 POST 请求。该请求需要 encryptionKey:manage 全局作用域。n8n 不会在 API 响应中返回密钥材料本身,只会返回 ID、算法、状态和时间戳等元数据。
轮换后,n8n 会对所有新的写入使用新的活动密钥。使用旧密钥加密的记录仍可读取,并会在你下一次更新每条记录时重新加密到新密钥下。
关闭加密密钥轮换
从 n8n 2.40.3 起,可以再次关闭加密密钥轮换。在所有 n8n 实例(包括主实例和 worker)上设置以下环境变量,然后重启:
N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=false
在 n8n 2.40.3 之前的版本中,如果 n8n 已经以新格式写入数据,关闭此功能会使这些数据永久无法访问。请先升级到 n8n 2.40.3。
向后兼容和回滚
危险
加密密钥轮换写入数据后,请勿降级 n8n
在启用此功能之前,以及升级到会自动启用此功能的 n8n 3.0 之前,请阅读本节。
一旦启用加密密钥轮换,n8n 就会以包含密钥标识符的新格式写入凭据和其他敏感数据。旧版本 n8n 无法读取这种格式。
- n8n 以新格式写入数据后,不要降级 n8n 版本。旧版本无法解密这种新格式。
- 从 n8n 2.40.3 起,可以安全关闭此功能。 在更早的版本中,将
N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION设为false会使启用此功能以来加密的所有数据永久无法访问。
目前没有自动化工具可将新格式加密的数据转换回旧格式。如果使用的 n8n 版本无法读取这些数据,唯一的恢复方式是还原数据库备份。
推荐步骤
- 备份数据库。在做任何改动前先创建完整快照,包括升级到 n8n 3.0 之前。
- 先在预发布环境试用。在非生产环境中启用此功能或升级到 n8n 3.0,重启后验证凭据仍能正确解密。
- 再应用到生产环境。仅在确认预发布环境行为正常后再执行。
- 不要降级。一旦生产数据已开始以新格式写入,请使用当前版本或更高版本的 n8n。
相关资源
- 安全性:审计、加固和限制自托管实例。
- 设置自定义加密密钥:设置实例级
N8N_ENCRYPTION_KEY值。 - 部署环境变量:查看
N8N_ENCRYPTION_KEY和N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION的参考信息。 - 配置队列模式:确保所有 worker 共享同一个实例加密密钥。
- n8n 3.0 不兼容变更:升级时的变化,包括加密密钥轮换。