Skip to content

密文盘点与受控迁移 ​

Admin 应用层提供持久化密文盘点 / 受控迁移入口,用于在密钥轮换后,把仍落在库里的旧密文迁到当前活跃密钥。编排在 forge-admin-server 的 CryptoMigrationCoordinator,避免 forge-starter-crypto 反向依赖业务插件。

当前没有独立后台菜单页;由超级管理员调用管理 API。字段加解密与脱敏能力见 加解密(forge-starter-crypto);密钥轮换操作见 Docs PRO 加密密钥轮换。

谁能用 ​

  • 仅 超级管理员(SessionHelper.assertAdmin,失败文案:只有超级管理员可以执行密文盘点和迁移)。
  • 接口带 @ApiEncrypt / @ApiDecrypt,调用侧需按平台传输加密约定发请求。

接口 ​

前缀:/api/config/manage/crypto/migration

方法路径说明
POST/inventory盘点(默认可 dry-run 语义的只读汇总)
POST/execute执行迁移(默认 dryRun=true,需显式关闭才真正写库)

请求体 CryptoMigrationRequest ​

字段必填说明
expectedActiveKeyId执行时是期望的活跃密钥 ID;与当前密钥不一致会失败
dryRun否默认 true(未传或非 false 都按演练)。只有显式 false 才落库
batchSize否批次大小
includeDataConnections否是否包含数据连接密文(forge-plugin-data)
includeLowcode否是否包含低代码配置密文(forge-plugin-generator)
configKeys低代码执行时是低代码迁移必须显式给出;只迁数据连接时设 includeLowcode=false

请求不接受明文、密文或密钥材料字段。

响应 CryptoMigrationReport(摘要) ​

演示环境盘点示例(字段名以响应为准):

字段说明
tenantId当前租户
scope编排范围,当前为 ALL
activeKeyId当前活跃密钥 ID
expectedActiveKeyId执行时传入的期望密钥
dryRun是否演练
totals分类计数,如 LEGACY、UNKNOWN_KEY
items明细项列表(盘点可为空数组,仅 totals)

推荐流程 ​

  1. 先盘点:POST .../inventory,确认 totals(如遗留密文 LEGACY、未知密钥 UNKNOWN_KEY)。
  2. 核对活跃密钥:与密钥管理中的当前 activeKeyId 一致后再执行。
  3. 演练执行:POST .../execute,带上 expectedActiveKeyId,保持 dryRun: true(或不传)。
  4. 真实迁移:确认无误后同一请求体设 dryRun: false。低代码范围必须带 configKeys。
  5. 再盘点:确认遗留计数下降。

调用示例(结构示意) ​

http
POST /api/config/manage/crypto/migration/inventory
Authorization: Bearer <超级管理员 token>
Content-Type: application/json

{
  "includeDataConnections": true,
  "includeLowcode": false
}
http
POST /api/config/manage/crypto/migration/execute
Authorization: Bearer <超级管理员 token>
Content-Type: application/json

{
  "expectedActiveKeyId": "<当前活跃密钥ID>",
  "dryRun": true,
  "includeDataConnections": true,
  "includeLowcode": false
}

范围说明 ​

范围开关实际迁移服务
includeDataConnectionsDataConnectionCryptoMigrationService(数据连接)
includeLowcodeLowcodeCryptoMigrationService(低代码配置键)

企业协同凭据等其它范围若另有接口,不在本编排器内(例如协同侧独立迁移入口)。

注意事项 ​

  • 默认 dry-run,避免误操作直接改库。
  • 低代码迁移强制 configKeys,防止全表盲扫。
  • 这是平台运维能力,不是业务菜单功能;二开不要把密钥或明文打进日志。

相关文档 ​