Skip to content

加密密钥轮换#

功能可用性

  • 仅适用于自托管 n8n 实例。
  • 你需要是实例所有者，才能启用该功能并轮换密钥。

加密密钥轮换允许你在不更改实例主加密密钥的前提下，定期替换用于加密 n8n 数据的密钥，例如凭据、OAuth token 以及其他敏感内容。

加密密钥轮换的工作方式#

n8n 使用双层密钥模型：

  • 实例加密密钥（N8N_ENCRYPTION_KEY）：这是部署时设置的主密钥。它不会变化。n8n 仅使用它来保护数据加密密钥。
  • 数据加密密钥：这是直接用于加密凭据数据的密钥，也是你要轮换的密钥。n8n 会将其以加密形式存储在数据库中，由实例密钥保护。

轮换时，n8n 会生成一个新的数据加密密钥，并将其用于之后的所有写入。使用旧密钥加密的现有数据仍然可以读取。n8n 会在你下一次更新对应记录时，静默地将其重新加密到新密钥下。

开始之前#

启用此功能前请先完整备份数据库

启用加密密钥轮换是单向变更，没有回滚路径。详情请参阅向后兼容性与回滚。

你还需要确保：

  • 所有 n8n 实例，包括主实例和所有 worker，都共享同一个 N8N_ENCRYPTION_KEY 值。
  • 你可以直接控制环境变量和 n8n 数据库。这只适用于自托管部署。

启用加密密钥轮换#

  1. 在所有 n8n 实例上设置以下环境变量，包括主实例和 worker：

    1
    N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true

  2. 重启所有实例。启动时，n8n 会自动生成初始数据加密密钥，并以加密形式存入数据库。

  3. 要确认功能已启用，请进入 Settings > Data Encryption Keys。你应该能看到当前生效的密钥。

轮换当前生效的密钥#

启用该功能后，你可以随时轮换到新的数据加密密钥。

使用 UI#

进入 Settings > Data Encryption Keys，然后选择 Rotate key。

使用 API#

向 /encryption/keys 端点发送一个 POST 请求。该请求需要 encryptionKey:manage 全局作用域。n8n 不会在 API 响应中返回密钥材料本身，只会返回 ID、算法、状态和时间戳等元数据。

轮换后，n8n 会对所有新的写入使用新的活动密钥。使用旧密钥加密的记录仍可读取，并会在你下一次更新每条记录时重新加密到新密钥下。

向后兼容性与回滚#

这是一次单向迁移

启用加密密钥轮换前，请仔细阅读本节。

一旦启用加密密钥轮换，n8n 就会开始以包含密钥标识符的新格式写入凭据和其他敏感数据。旧版本 n8n，以及未启用该功能标志的实例，都无法读取这种格式。

  • 不要在新格式数据已经写入后关闭该功能标志。移除 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION 或将其设为 false，会导致你启用该功能后加密的所有数据永久无法访问。
  • 启用后不要降级 n8n 版本。旧版本无法解密这种新格式。

目前没有自动化工具可将新格式加密的数据转换回旧格式。唯一的恢复方式，是还原启用该功能之前制作的数据库备份。

建议步骤#

  1. 备份数据库。在做任何改动前先创建完整快照。
  2. 先在预发布环境启用。在非生产环境中设置 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true，重启后验证凭据仍能正确解密。
  3. 再在生产环境启用。仅在确认预发布环境行为正常后再执行。
  4. 不要关闭或降级。一旦生产数据已开始以新格式写入，请始终保持该标志开启，并使用当前版本或更高版本的 n8n。

相关资源#