Skip to content

加密密钥轮换(Encryption key rotation)#

功能可用性

  • 仅在自托管的 n8n 实例上可用。
  • 你需要是实例所有者才能启用此功能并轮换密钥。

加密密钥轮换允许你定期替换用来加密 n8n 数据的密钥，例如凭证、OAuth 令牌以及其他敏感内容，而无需更改实例的主加密密钥。

🌐 Encryption key rotation lets you periodically replace the key that encrypts your n8n data, like credentials, OAuth tokens, and other sensitive content, without changing your instance's master encryption key.

加密密钥轮换的工作原理(How encryption key rotation works)#

n8n 使用双层密钥模型：

🌐 n8n uses a two-layer key model:

  • 实例加密密钥 (N8N_ENCRYPTION_KEY)：你的主密钥，在部署时设置。此密钥永远不会改变。n8n 仅使用它来保护数据加密密钥。
  • 数据加密密钥：直接加密你的凭证数据的密钥。这是你需要轮换的密钥。n8n 将其以加密形式存储在数据库中，并由实例密钥保护。

当你旋转时，n8n 会生成一个新的数据加密密钥，并将其用于所有未来的写入操作。使用以前的密钥加密的现有数据仍然可以读取。n8n 会在你下次更新每条记录时悄悄将其重新加密为新密钥。

🌐 When you rotate, n8n generates a new data encryption key and uses it for all future writes. Existing data encrypted with the previous key remains readable. n8n silently re-encrypts each record to the new key the next time you update it.

在你开始之前(Before you begin)#

在启用此功能之前，先进行完整的数据库备份

启用加密密钥轮换是单向更改。无法回滚。有关详细信息，请参见向后兼容性和回滚。

你还需要确保：

🌐 You also need to make sure that:

  • 所有 n8n 实例，主服务器和所有工作节点，共享相同的 N8N_ENCRYPTION_KEY 值。
  • 你可以直接控制你的环境变量和 n8n 数据库。这只有在自托管部署上才可能实现。

启用加密密钥轮换(Enable encryption key rotation)#

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

    1
    N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true

  2. 重启所有实例。在启动时，n8n 会自动生成初始数据加密密钥，并将其加密后存储在你的数据库中。

  3. 要确认该功能是否已启用，请前往 设置 > 数据加密密钥。你应该能看到列出的活动密钥。

旋转活动密钥(Rotate the active key)#

一旦启用此功能，你可以随时更换新的数据加密密钥。

🌐 Once the feature is enabled, you can rotate to a new data encryption key at any time.

使用用户界面(Using the UI)#

转到 设置 > 数据加密密钥 并选择 轮换密钥。

🌐 Go to Settings > Data Encryption Keys and select Rotate key.

使用 API(Using the API)#

对 /encryption/keys 端点进行 POST 调用。该请求需要 encryptionKey:manage 全局作用域。n8n 从不在 API 响应中返回密钥材料，只返回 ID、算法、状态和时间戳等元数据。

🌐 Make a POST call to the /encryption/keys endpoint. The request requires the encryptionKey:manage global scope. n8n never returns key material in API responses, only metadata such as the ID, algorithm, status, and timestamps.

轮换后，n8n 会将新的活动密钥用于所有新的写入。使用以前密钥加密的记录仍然可以读取。n8n 会在你下次更新每条记录时，将其重新加密为新的密钥。

🌐 After rotation, n8n uses the new active key for all new writes. Records encrypted with previous keys remain readable. n8n re-encrypts them to the new key the next time you update each record.

向后兼容性和回滚(Backwards compatibility and rollback)#

这是一次单向迁移

在启用加密密钥轮换之前，请仔细阅读本部分内容。

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

🌐 Once you enable encryption key rotation, n8n begins writing credentials and other sensitive data in a new format that includes a key identifier. Older versions of n8n, and instances running without the feature flag, can't read this format.

  • 在以新格式写入任何数据后不要禁用功能标志。删除 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION 或将其设置为 false 会导致在启用该功能后加密的所有数据永久无法访问。
  • 在启用后不要降级你的 n8n 版本。旧版本无法解密新格式。

没有自动化工具可以将采用新格式加密的数据转换回旧格式。唯一的恢复方法是从启用该功能之前进行的数据库备份中恢复。

🌐 There's no automated tool to convert data encrypted in the new format back to the legacy format. The only recovery path is restoring from a database backup taken before you enabled the feature.

  1. 备份你的数据库。在进行任何更改之前，先进行完整快照。
  2. 先在预发布环境启用。在非生产环境中设置 N8N_ENV_FEAT_ENCRYPTION_KEY_ROTATION=true，重启，然后验证凭据是否仍能正确解密。
  3. 在生产环境中启用。请仅在验证了预发布环境的行为之后再进行此操作。
  4. 不要禁用或降级。一旦生产数据已以新格式写入，请保持该标志启用，并保持在相同或更新的 n8n 版本上。