密文盘点与受控迁移
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) |
推荐流程
- 先盘点:
POST .../inventory,确认totals(如遗留密文LEGACY、未知密钥UNKNOWN_KEY)。 - 核对活跃密钥:与密钥管理中的当前
activeKeyId一致后再执行。 - 演练执行:
POST .../execute,带上expectedActiveKeyId,保持dryRun: true(或不传)。 - 真实迁移:确认无误后同一请求体设
dryRun: false。低代码范围必须带configKeys。 - 再盘点:确认遗留计数下降。
调用示例(结构示意)
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
}范围说明
| 范围开关 | 实际迁移服务 |
|---|---|
includeDataConnections | DataConnectionCryptoMigrationService(数据连接) |
includeLowcode | LowcodeCryptoMigrationService(低代码配置键) |
企业协同凭据等其它范围若另有接口,不在本编排器内(例如协同侧独立迁移入口)。
注意事项
- 默认 dry-run,避免误操作直接改库。
- 低代码迁移强制
configKeys,防止全表盲扫。 - 这是平台运维能力,不是业务菜单功能;二开不要把密钥或明文打进日志。
