845 lines
24 KiB
Markdown
845 lines
24 KiB
Markdown
# 资源备份恢复前端对接文档
|
||
|
||
## 1. 对接目标
|
||
|
||
本文说明当前 `tms-framework` 资源备份和资源恢复接口的前端调用方式、接口顺序、页面判断规则和错误处理建议。
|
||
|
||
当前前端只需要支持两个主流程：
|
||
|
||
- 创建资源备份包并下载 `.tmsbak`
|
||
- 上传 `.tmsbak`，预检通过后执行停机恢复，并在 TMS 重启后展示最近恢复结果
|
||
|
||
恢复侧已经收敛为轻量流程，不再提供恢复任务详情、恢复步骤和恢复步骤日志接口。恢复完成后的页面展示只依赖 `GET /api/v1/resource-restores/latest`。
|
||
|
||
## 2. 通用约定
|
||
|
||
### 2.1 基础路径
|
||
|
||
| 模块 | 基础路径 |
|
||
| --- | --- |
|
||
| 文件上传 | `/api/v1/files` |
|
||
| 资源备份 | `/api/v1/resource-backups` |
|
||
| 资源恢复 | `/api/v1/resource-restores` |
|
||
|
||
### 2.2 统一响应
|
||
|
||
除备份包下载接口外，其它接口返回 `ApiResponse<T>`：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"msg": "成功",
|
||
"data": {},
|
||
"timestamp": 1777459200000,
|
||
"traceId": "optional-trace-id"
|
||
}
|
||
```
|
||
|
||
前端统一处理规则：
|
||
|
||
- HTTP 非 2xx：请求失败，展示 HTTP 错误或后端 `msg`
|
||
- `success=false`：业务失败，展示 `msg`
|
||
- `success=true`：请求成功，继续按 `data` 中的业务字段判断流程
|
||
|
||
### 2.3 权限和防重放
|
||
|
||
资源备份/恢复接口要求内部登录态，角色为 `OPS_ADMIN`，认证等级为 `FULL`。
|
||
|
||
需要防重放头的接口：
|
||
|
||
- `POST /api/v1/resource-backups`
|
||
- `POST /api/v1/resource-restores`
|
||
- `POST /api/v1/resource-restores/{taskId}/apply`
|
||
|
||
请求头示例：
|
||
|
||
```http
|
||
Authorization: Bearer <token>
|
||
X-Request-Timestamp: <unix秒时间戳>
|
||
X-Request-Nonce: <唯一随机串>
|
||
```
|
||
|
||
`GET` 查询类接口和 `POST /api/v1/resource-restores/precheck` 当前不需要防重放头，但仍需要登录态。
|
||
|
||
### 2.4 时间字段
|
||
|
||
时间字段前端按字符串展示即可：
|
||
|
||
- Java 任务时间：`2026-04-29T16:00:00`
|
||
- shell 状态时间：`2026-04-29T16:00:00+0800`
|
||
|
||
## 3. 页面流程总览
|
||
|
||
### 3.1 备份流程
|
||
|
||
1. 用户点击“创建资源备份”。
|
||
2. 前端调用 `POST /api/v1/resource-backups`。
|
||
3. 根据返回的 `data.status` 判断：
|
||
- `SUCCESS`：展示“下载备份包”
|
||
- `FAILED`：展示 `errorMessage`，可查看备份步骤/日志
|
||
- 其它状态：调用 `GET /api/v1/resource-backups/{taskId}` 轮询
|
||
4. 用户点击“下载”，调用 `GET /api/v1/resource-backups/{taskId}/download`。
|
||
5. 浏览器保存 `.tmsbak` 文件。
|
||
|
||
当前后端创建备份通常同步完成，`POST /api/v1/resource-backups` 可能直接返回 `SUCCESS` 或 `FAILED`。前端保留轮询逻辑即可。
|
||
|
||
### 3.2 恢复流程
|
||
|
||
1. 用户选择 `.tmsbak` 文件。
|
||
2. 前端调用 `POST /api/v1/files/upload` 上传文件，拿到 `fileId`。
|
||
3. 前端调用 `POST /api/v1/resource-restores/precheck`，传入 `fileId`。
|
||
4. 前端展示预检信息，并按 `data.precheckPassed` 判断是否允许下一步。
|
||
5. `precheckPassed=true` 时，前端展示一次“确认恢复”弹窗，弹窗中明确提示会进入停机恢复。
|
||
6. 用户确认后，前端调用 `POST /api/v1/resource-restores` 创建恢复准备任务。
|
||
7. 创建成功且 `data.status=READY_TO_APPLY` 时，前端不要再次弹确认框，直接调用 `POST /api/v1/resource-restores/{taskId}/apply`。
|
||
8. `apply` 接口返回后，TMS 可能很快停机、恢复、重启。前端应提示页面/API 短暂不可用。
|
||
9. TMS 重启后，恢复页面调用 `GET /api/v1/resource-restores/latest` 展示最近恢复结果。
|
||
|
||
### 3.3 恢复流程判断点
|
||
|
||
| 阶段 | 判断字段 | 前端动作 |
|
||
| --- | --- | --- |
|
||
| 上传备份包 | `data.fileId` 非空 | 保存 `fileId`，进入预检 |
|
||
| 预检 | `data.precheckPassed === true` | 允许点击“确认恢复” |
|
||
| 预检 | `data.precheckPassed !== true` | 禁止下一步，展示 `blockingIssues` / `warnings` |
|
||
| 创建恢复任务 | `data.status === "READY_TO_APPLY"` | 立即调用 apply，不再弹确认框 |
|
||
| 执行恢复任务 | `data.status === "APPLYING"` | 展示“恢复中，服务可能重启” |
|
||
| 重启后查询 latest | `data.status === "SUCCESS"` | 展示恢复成功 |
|
||
| 重启后查询 latest | `data.status === "FAILED"` | 展示恢复失败、`phase`、`message` |
|
||
| 重启后查询 latest | `data.status === "NONE"` | 展示暂无恢复记录 |
|
||
|
||
## 4. 接口明细
|
||
|
||
### 4.1 上传备份包
|
||
|
||
`POST /api/v1/files/upload`
|
||
|
||
请求类型：`multipart/form-data`
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `file` | `File` | 是 | 用户选择的 `.tmsbak` 文件 |
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"msg": "成功",
|
||
"data": {
|
||
"fileId": "FILE-20260429-000001",
|
||
"filename": "RBKP-20260429-160000-ABCDEF.tmsbak",
|
||
"size": 1048576
|
||
}
|
||
}
|
||
```
|
||
|
||
前端只需要保存 `fileId`，不要依赖服务端文件路径。
|
||
|
||
### 4.2 创建资源备份
|
||
|
||
`POST /api/v1/resource-backups`
|
||
|
||
需要防重放头。
|
||
|
||
请求体可为空，也可以传备注：
|
||
|
||
```json
|
||
{
|
||
"remark": "硬件更换前备份"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `remark` | `string` | 否 | 备份备注 |
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"msg": "成功",
|
||
"data": {
|
||
"taskId": "RBKP-TASK-20260429-000001",
|
||
"backupId": "RBKP-20260429-160000-ABCDEF",
|
||
"status": "SUCCESS",
|
||
"createdAt": "2026-04-29T16:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
前端判断：
|
||
|
||
- `status=SUCCESS`：允许下载
|
||
- `status=FAILED`：展示失败原因，可查询任务详情或步骤日志
|
||
- 其它状态：使用 `taskId` 查询任务详情
|
||
|
||
### 4.3 查询备份任务详情
|
||
|
||
`GET /api/v1/resource-backups/{taskId}`
|
||
|
||
常用响应字段：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `taskId` | `string` | 备份任务号 |
|
||
| `backupId` | `string` | 备份包身份号，恢复预检后会显示给用户确认 |
|
||
| `status` | `ResourceTaskStatus` | 任务状态 |
|
||
| `productType` | `ProductType` | 产品类型 |
|
||
| `mqType` | `MqType` | MQ 类型 |
|
||
| `orgCode` | `string` | 机构号 |
|
||
| `packageName` | `string` | 备份包文件名 |
|
||
| `packageSize` | `number` | 包大小，字节 |
|
||
| `packageHash` | `string` | 包摘要 |
|
||
| `remark` | `string` | 创建备份时传入的备注 |
|
||
| `errorMessage` | `string` | 失败原因 |
|
||
| `createdAt` | `string` | 创建时间 |
|
||
| `finishedAt` | `string` | 完成时间 |
|
||
|
||
### 4.4 下载备份包
|
||
|
||
`GET /api/v1/resource-backups/{taskId}/download`
|
||
|
||
该接口返回文件流，不是 `ApiResponse`。
|
||
|
||
响应头示例：
|
||
|
||
```http
|
||
Content-Type: application/octet-stream
|
||
Content-Disposition: attachment; filename="RBKP-20260429-160000-ABCDEF.tmsbak"
|
||
```
|
||
|
||
前端建议：
|
||
|
||
- 仅当备份任务 `status=SUCCESS` 时展示下载按钮
|
||
- 使用浏览器下载能力或 `blob` 保存文件
|
||
|
||
### 4.5 查询备份步骤
|
||
|
||
`GET /api/v1/resource-backups/{taskId}/steps`
|
||
|
||
用途：备份失败时展示执行上下文。
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"msg": "成功",
|
||
"data": [
|
||
{
|
||
"stepNo": 1,
|
||
"stepCode": "PACKAGE_CREATE",
|
||
"status": "SUCCESS",
|
||
"message": "generated backup package RBKP-20260429-160000-ABCDEF.tmsbak",
|
||
"startedAt": "2026-04-29T16:00:00",
|
||
"finishedAt": "2026-04-29T16:00:03",
|
||
"logAvailable": false
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4.6 查询备份步骤日志
|
||
|
||
`GET /api/v1/resource-backups/{taskId}/steps/{stepNo}/log`
|
||
|
||
用途：备份失败或排障时展示详细日志。
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"msg": "成功",
|
||
"data": {
|
||
"taskId": "RBKP-TASK-20260429-000001",
|
||
"stepNo": 1,
|
||
"stepCode": "PACKAGE_CREATE",
|
||
"content": "{\"packageName\":\"RBKP-20260429-160000-ABCDEF.tmsbak\"}",
|
||
"truncated": false
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.7 恢复预检
|
||
|
||
`POST /api/v1/resource-restores/precheck`
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"fileId": "FILE-20260429-000001"
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `fileId` | `string` | 是 | 上传接口返回的文件 ID |
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"msg": "成功",
|
||
"data": {
|
||
"precheckId": "RPRE-20260429-000001",
|
||
"backupId": "RBKP-20260429-160000-ABCDEF",
|
||
"sourceProductType": "ENTERPRISE",
|
||
"sourceMqType": "RABBITMQ",
|
||
"sourceOrgCode": "AAAABBBBXXX",
|
||
"sourceBackupTime": "2026-04-29T16:00:00",
|
||
"targetProductType": "ENTERPRISE",
|
||
"keysetMatched": true,
|
||
"signatureValid": true,
|
||
"compatible": true,
|
||
"precheckPassed": true,
|
||
"payloadDecrypted": false,
|
||
"warnings": [],
|
||
"blockingIssues": [],
|
||
"restorePlan": ["JAVA_EXTRACT", "SHELL_APPLY"],
|
||
"restoreScopeSummary": {
|
||
"resourceCount": 6,
|
||
"productType": "ENTERPRISE",
|
||
"mqType": "RABBITMQ",
|
||
"orgCode": "AAAABBBBXXX"
|
||
},
|
||
"expiresAt": "2026-04-29T16:30:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
前端判断：
|
||
|
||
- 下一步只看 `precheckPassed`
|
||
- `precheckPassed=true`：允许创建恢复任务
|
||
- `precheckPassed=false`：禁止下一步，展示 `blockingIssues`；如只有 `warnings`，按页面需要提示用户
|
||
|
||
说明：
|
||
|
||
- `precheckPassed` 是后端聚合结果，当前等价于 `keysetMatched=true`、`signatureValid=true`、`compatible=true` 且 `blockingIssues` 为空
|
||
- `payloadDecrypted=false` 是正常值，预检阶段不解密完整 payload
|
||
- 真正解密、展开 payload、路径白名单校验发生在创建恢复任务阶段
|
||
- `payload.enc` 的实际加解密由后端通过 PCIe 密码卡 SDF 会话密钥流程完成，前端不需要传递 `keyIndex/keyBits/algId`
|
||
|
||
### 4.8 创建恢复任务
|
||
|
||
`POST /api/v1/resource-restores`
|
||
|
||
需要防重放头。
|
||
|
||
请求体：
|
||
|
||
```json
|
||
{
|
||
"precheckId": "RPRE-20260429-000001",
|
||
"confirmBackupId": "RBKP-20260429-160000-ABCDEF",
|
||
"deployMode": "DUAL",
|
||
"nodes": {
|
||
"node01Ip": "192.168.1.11",
|
||
"node02Ip": "192.168.1.12"
|
||
}
|
||
}
|
||
```
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `precheckId` | `string` | 是 | 预检接口返回的预检号 |
|
||
| `confirmBackupId` | `string` | 是 | 用户确认的备份号，必须等于预检响应 `backupId` |
|
||
| `deployMode` | `DeployMode` | 是 | `SINGLE`、`DUAL`、`QUAD` |
|
||
| `nodes.node01Ip` | `string` | 是 | 节点 1 IPv4 |
|
||
| `nodes.node02Ip` | `string` | `DUAL` / `QUAD` 必填 | 节点 2 IPv4 |
|
||
| `nodes.node03Ip` | `string` | `QUAD` 必填 | 节点 3 IPv4 |
|
||
| `nodes.node04Ip` | `string` | `QUAD` 必填 | 节点 4 IPv4 |
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"msg": "成功",
|
||
"data": {
|
||
"taskId": "RRST-TASK-20260429-000001",
|
||
"status": "READY_TO_APPLY",
|
||
"createdAt": "2026-04-29T16:05:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
前端判断：
|
||
|
||
- `status=READY_TO_APPLY`：立即调用 apply，不再弹确认框
|
||
- 其它状态：展示异常提示，不调用 apply
|
||
|
||
后端在该阶段会完成验签、PCIe/SDF 解密、payload 展开、用户密钥恢复、路径白名单校验和恢复计划文件生成，但不会停止 TMS。
|
||
|
||
### 4.9 执行恢复任务
|
||
|
||
`POST /api/v1/resource-restores/{taskId}/apply`
|
||
|
||
需要防重放头。
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"msg": "成功",
|
||
"data": {
|
||
"taskId": "RRST-TASK-20260429-000001",
|
||
"status": "APPLYING",
|
||
"createdAt": "2026-04-29T16:05:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
前端判断：
|
||
|
||
- `status=APPLYING`：提示用户恢复执行中，页面和接口可能短暂不可用
|
||
- 之后不要继续轮询恢复步骤，等待 TMS 重启后查 latest
|
||
|
||
后端在该阶段会启动后台脚本，执行停服务、文件覆盖、数据库导入、MQ replay、启动服务和健康检查。
|
||
|
||
### 4.10 查询最近恢复结果
|
||
|
||
`GET /api/v1/resource-restores/latest`
|
||
|
||
用途：TMS 重启后，恢复页面展示最近一次恢复结果。
|
||
|
||
响应示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"msg": "成功",
|
||
"data": {
|
||
"taskId": "RRST-TASK-20260429-000001",
|
||
"backupId": "RBKP-20260429-160000-ABCDEF",
|
||
"status": "FAILED",
|
||
"phase": "DATABASE",
|
||
"message": "数据库恢复失败",
|
||
"createdAt": "2026-04-29T16:05:00",
|
||
"finishedAt": "2026-04-29T16:12:00+0800"
|
||
}
|
||
}
|
||
```
|
||
|
||
前端判断：
|
||
|
||
- `status=SUCCESS`：展示最近恢复成功和 `finishedAt`
|
||
- `status=FAILED`：展示恢复失败、`phase`、`message`
|
||
- `status=APPLYING` 或 `RUNNING`：展示恢复仍在执行或等待刷新
|
||
- `status=NONE`：展示暂无恢复记录
|
||
|
||
## 5. 状态和枚举
|
||
|
||
### 5.1 ProductType
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `ENTERPRISE` | 企参模式 |
|
||
| `INDIRECT` | 间参模式 |
|
||
| `DIRECT` | 直参模式 |
|
||
| `UNKNOWN` | 后端无法识别或未配置 |
|
||
|
||
### 5.2 MqType
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `RABBITMQ` | 标准 RabbitMQ |
|
||
| `TLQ` | TLQ |
|
||
| `RABBITMQ_TLQ` | RabbitMQ + TLQ |
|
||
| `RABBITMQ_CFMQ` | RabbitMQ + CFMQ |
|
||
|
||
### 5.3 DeployMode
|
||
|
||
| 值 | 说明 | 节点要求 |
|
||
| --- | --- | --- |
|
||
| `SINGLE` | 单节点部署 | `node01Ip` |
|
||
| `DUAL` | 双节点部署 | `node01Ip`、`node02Ip` |
|
||
| `QUAD` | 四节点部署 | `node01Ip`、`node02Ip`、`node03Ip`、`node04Ip` |
|
||
|
||
第一版中，节点参数只写入恢复上下文用于审计和排障，不自动改写恢复后的配置文件。
|
||
|
||
### 5.4 ResourceTaskStatus
|
||
|
||
| 值 | 前端文案建议 | 说明 |
|
||
| --- | --- | --- |
|
||
| `RUNNING` | 执行中 | 备份或 shell 恢复执行中 |
|
||
| `SUCCESS` | 成功 | 任务成功 |
|
||
| `FAILED` | 失败 | 任务失败 |
|
||
| `READY_TO_APPLY` | 待停机恢复 | 恢复任务已准备好，前端可继续调用 apply |
|
||
| `APPLYING` | 恢复执行中 | 恢复脚本已启动或即将启动 |
|
||
| `NONE` | 暂无记录 | 仅 latest 接口可能返回 |
|
||
|
||
其它预留状态前端可以兜底展示原值。
|
||
|
||
### 5.5 RestorePhase
|
||
|
||
| 值 | 说明 |
|
||
| --- | --- |
|
||
| `APPLY_DELAY` | 后台脚本启动后短暂等待 |
|
||
| `SERVICE_STOP` | 停止服务 |
|
||
| `FILE` | 恢复文件 |
|
||
| `DATABASE` | 导入数据库 |
|
||
| `MQ_REPLAY` | 重放 MQ 配置 |
|
||
| `SERVICE_START` | 启动服务 |
|
||
| `HEALTH_CHECK` | 健康检查 |
|
||
| `DONE` | 完成 |
|
||
|
||
### 5.6 资源范围说明
|
||
|
||
当前备份/恢复资源包括：
|
||
|
||
- `TMS_CONFIG`
|
||
- `TMS_DB`
|
||
- `CMEP_DB`
|
||
- `ORG_DB`
|
||
- `CP_CONFIG`
|
||
- `RECEIVER_LICENSE`
|
||
- `STANDARD_CMSP_APP_CONFIG`
|
||
- `STANDARD_CMTP_APP_CONFIG`
|
||
- `USER_KEY`
|
||
- `MQ_REPLAY`
|
||
|
||
`TMS_DB` 默认排除 `tms.backup.tms-db-excluded-tables` 中声明的表。默认排除角色、授权、会话和资源任务表，避免恢复时覆盖新机器安全登录状态或带回旧的资源任务状态；`tms_operation_audit_log` 默认随 TMS 库一起备份。
|
||
|
||
## 6. TypeScript 类型建议
|
||
|
||
```ts
|
||
export interface ApiResponse<T> {
|
||
success: boolean;
|
||
code: number;
|
||
msg: string;
|
||
data: T;
|
||
timestamp?: number;
|
||
traceId?: string;
|
||
}
|
||
|
||
export type ProductType = 'ENTERPRISE' | 'INDIRECT' | 'DIRECT' | 'UNKNOWN';
|
||
export type MqType = 'RABBITMQ' | 'TLQ' | 'RABBITMQ_TLQ' | 'RABBITMQ_CFMQ';
|
||
export type DeployMode = 'SINGLE' | 'DUAL' | 'QUAD';
|
||
|
||
export type ResourceTaskStatus =
|
||
| 'RUNNING'
|
||
| 'SUCCESS'
|
||
| 'FAILED'
|
||
| 'READY_TO_APPLY'
|
||
| 'APPLYING'
|
||
| 'NONE'
|
||
| string;
|
||
|
||
export interface CreateResourceBackupRequest {
|
||
remark?: string;
|
||
}
|
||
|
||
export interface CreateResourceBackupResponse {
|
||
taskId: string;
|
||
backupId?: string;
|
||
status: ResourceTaskStatus;
|
||
createdAt?: string;
|
||
}
|
||
|
||
export interface ResourceBackupTaskDetailResponse {
|
||
taskId: string;
|
||
backupId?: string;
|
||
status: ResourceTaskStatus;
|
||
productType?: ProductType;
|
||
mqType?: MqType;
|
||
orgCode?: string;
|
||
packageName?: string;
|
||
packageSize?: number;
|
||
packageHash?: string;
|
||
remark?: string;
|
||
errorMessage?: string;
|
||
createdAt?: string;
|
||
finishedAt?: string;
|
||
}
|
||
|
||
export interface ResourceRestorePrecheckRequest {
|
||
fileId: string;
|
||
}
|
||
|
||
export interface ResourceRestorePrecheckResponse {
|
||
precheckId: string;
|
||
backupId: string;
|
||
sourceProductType?: ProductType;
|
||
sourceMqType?: MqType;
|
||
sourceOrgCode?: string;
|
||
sourceBackupTime?: string;
|
||
targetProductType?: ProductType;
|
||
keysetMatched: boolean;
|
||
signatureValid: boolean;
|
||
compatible: boolean;
|
||
precheckPassed: boolean;
|
||
payloadDecrypted: boolean;
|
||
warnings: string[];
|
||
blockingIssues: string[];
|
||
restorePlan: string[];
|
||
restoreScopeSummary?: unknown;
|
||
expiresAt: string;
|
||
}
|
||
|
||
export interface CreateResourceRestoreRequest {
|
||
precheckId: string;
|
||
confirmBackupId: string;
|
||
deployMode: DeployMode;
|
||
nodes: {
|
||
node01Ip: string;
|
||
node02Ip?: string;
|
||
node03Ip?: string;
|
||
node04Ip?: string;
|
||
};
|
||
}
|
||
|
||
export interface CreateResourceRestoreResponse {
|
||
taskId: string;
|
||
status: ResourceTaskStatus;
|
||
createdAt?: string;
|
||
}
|
||
|
||
export interface ResourceRestoreLatestResponse {
|
||
taskId?: string;
|
||
backupId?: string;
|
||
status: ResourceTaskStatus;
|
||
phase?: string;
|
||
message?: string;
|
||
createdAt?: string;
|
||
finishedAt?: string;
|
||
}
|
||
```
|
||
|
||
## 7. Vue 3 对接示例
|
||
|
||
以下示例按 Vue 3 Composition API 编写。`request`、`message`、`confirmRestore`、`downloadByUrl` 可替换为项目内已有的 axios 封装、弹窗组件和下载工具。
|
||
|
||
### 7.1 防重放头
|
||
|
||
```ts
|
||
function replayHeaders() {
|
||
return {
|
||
'X-Request-Timestamp': String(Math.floor(Date.now() / 1000)),
|
||
'X-Request-Nonce': crypto.randomUUID()
|
||
};
|
||
}
|
||
```
|
||
|
||
### 7.2 备份 composable
|
||
|
||
```ts
|
||
import { computed, ref } from 'vue';
|
||
|
||
export function useResourceBackup() {
|
||
const backupTask = ref<ResourceBackupTaskDetailResponse | CreateResourceBackupResponse>();
|
||
const backupLoading = ref(false);
|
||
|
||
const canDownload = computed(() => backupTask.value?.status === 'SUCCESS');
|
||
const backupFailed = computed(() => backupTask.value?.status === 'FAILED');
|
||
|
||
async function createBackup(remark?: string) {
|
||
backupLoading.value = true;
|
||
try {
|
||
const res = await request.post<ApiResponse<CreateResourceBackupResponse>>(
|
||
'/api/v1/resource-backups',
|
||
remark ? { remark } : {},
|
||
{ headers: replayHeaders() }
|
||
);
|
||
if (!res.data.success) throw new Error(res.data.msg);
|
||
|
||
backupTask.value = res.data.data;
|
||
if (!['SUCCESS', 'FAILED'].includes(res.data.data.status)) {
|
||
await refreshBackup(res.data.data.taskId);
|
||
}
|
||
} finally {
|
||
backupLoading.value = false;
|
||
}
|
||
}
|
||
|
||
async function refreshBackup(taskId: string) {
|
||
const res = await request.get<ApiResponse<ResourceBackupTaskDetailResponse>>(
|
||
`/api/v1/resource-backups/${taskId}`
|
||
);
|
||
if (!res.data.success) throw new Error(res.data.msg);
|
||
backupTask.value = res.data.data;
|
||
}
|
||
|
||
function downloadBackup() {
|
||
if (!backupTask.value || backupTask.value.status !== 'SUCCESS') return;
|
||
downloadByUrl(`/api/v1/resource-backups/${backupTask.value.taskId}/download`);
|
||
}
|
||
|
||
return {
|
||
backupTask,
|
||
backupLoading,
|
||
canDownload,
|
||
backupFailed,
|
||
createBackup,
|
||
refreshBackup,
|
||
downloadBackup
|
||
};
|
||
}
|
||
```
|
||
|
||
页面判断：
|
||
|
||
- `canDownload=true` 时展示“下载备份包”。
|
||
- `backupFailed=true` 时展示 `backupTask.errorMessage`，并允许进入备份步骤/日志排查。
|
||
- 备份侧可以继续保留任务详情、步骤、日志查询。
|
||
|
||
### 7.3 恢复 composable
|
||
|
||
```ts
|
||
import { computed, ref } from 'vue';
|
||
|
||
export function useResourceRestore() {
|
||
const selectedFile = ref<File>();
|
||
const precheckResult = ref<ResourceRestorePrecheckResponse>();
|
||
const latestRestore = ref<ResourceRestoreLatestResponse>();
|
||
const restoreLoading = ref(false);
|
||
|
||
const canCreateRestore = computed(() => precheckResult.value?.precheckPassed === true);
|
||
const precheckBlocked = computed(() => precheckResult.value?.precheckPassed === false);
|
||
|
||
async function uploadAndPrecheck(file: File) {
|
||
selectedFile.value = file;
|
||
restoreLoading.value = true;
|
||
try {
|
||
const form = new FormData();
|
||
form.append('file', file);
|
||
|
||
const upload = await request.post<ApiResponse<{ fileId: string }>>(
|
||
'/api/v1/files/upload',
|
||
form
|
||
);
|
||
if (!upload.data.success) throw new Error(upload.data.msg);
|
||
|
||
const precheck = await request.post<ApiResponse<ResourceRestorePrecheckResponse>>(
|
||
'/api/v1/resource-restores/precheck',
|
||
{ fileId: upload.data.data.fileId }
|
||
);
|
||
if (!precheck.data.success) throw new Error(precheck.data.msg);
|
||
|
||
precheckResult.value = precheck.data.data;
|
||
} finally {
|
||
restoreLoading.value = false;
|
||
}
|
||
}
|
||
|
||
async function confirmAndRestore(deployMode: DeployMode, nodes: CreateResourceRestoreRequest['nodes']) {
|
||
if (!precheckResult.value || !canCreateRestore.value) return;
|
||
|
||
await confirmRestore({
|
||
title: '确认恢复资源',
|
||
message: `确认使用备份包 ${precheckResult.value.backupId} 进行恢复？恢复过程中服务会停启，页面可能短暂不可访问。`
|
||
});
|
||
|
||
restoreLoading.value = true;
|
||
try {
|
||
const created = await request.post<ApiResponse<CreateResourceRestoreResponse>>(
|
||
'/api/v1/resource-restores',
|
||
{
|
||
precheckId: precheckResult.value.precheckId,
|
||
confirmBackupId: precheckResult.value.backupId,
|
||
deployMode,
|
||
nodes
|
||
},
|
||
{ headers: replayHeaders() }
|
||
);
|
||
if (!created.data.success) throw new Error(created.data.msg);
|
||
if (created.data.data.status !== 'READY_TO_APPLY') {
|
||
throw new Error('恢复任务状态异常');
|
||
}
|
||
|
||
const applied = await request.post<ApiResponse<CreateResourceRestoreResponse>>(
|
||
`/api/v1/resource-restores/${created.data.data.taskId}/apply`,
|
||
{},
|
||
{ headers: replayHeaders() }
|
||
);
|
||
if (!applied.data.success) throw new Error(applied.data.msg);
|
||
|
||
message.info('恢复已开始，TMS 将停机并重启。重启后请返回恢复页面查看最近恢复结果。');
|
||
} finally {
|
||
restoreLoading.value = false;
|
||
}
|
||
}
|
||
|
||
async function loadLatestRestore() {
|
||
const res = await request.get<ApiResponse<ResourceRestoreLatestResponse>>(
|
||
'/api/v1/resource-restores/latest'
|
||
);
|
||
if (!res.data.success) throw new Error(res.data.msg);
|
||
latestRestore.value = res.data.data;
|
||
}
|
||
|
||
return {
|
||
selectedFile,
|
||
precheckResult,
|
||
latestRestore,
|
||
restoreLoading,
|
||
canCreateRestore,
|
||
precheckBlocked,
|
||
uploadAndPrecheck,
|
||
confirmAndRestore,
|
||
loadLatestRestore
|
||
};
|
||
}
|
||
```
|
||
|
||
页面判断：
|
||
|
||
- 文件选择后调用 `uploadAndPrecheck(file)`。
|
||
- “确认恢复”按钮只在 `canCreateRestore=true` 时启用。
|
||
- `precheckBlocked=true` 时展示 `blockingIssues`，不要允许用户继续。
|
||
- `confirmAndRestore` 内部只弹一次确认；用户确认后按顺序调用创建恢复任务和 apply。
|
||
- apply 返回后不要轮询恢复任务详情、恢复步骤或恢复日志。
|
||
|
||
### 7.4 重启后最近恢复结果展示
|
||
|
||
```vue
|
||
<script setup lang="ts">
|
||
import { computed, onMounted } from 'vue';
|
||
|
||
const { latestRestore, loadLatestRestore } = useResourceRestore();
|
||
|
||
onMounted(loadLatestRestore);
|
||
|
||
const latestText = computed(() => {
|
||
const latest = latestRestore.value;
|
||
if (!latest || latest.status === 'NONE') return '暂无资源恢复记录';
|
||
if (latest.status === 'SUCCESS') return `最近恢复成功：${latest.finishedAt ?? ''}`;
|
||
if (latest.status === 'FAILED') {
|
||
return `最近恢复失败：${latest.phase ?? ''} ${latest.message ?? ''}`;
|
||
}
|
||
return `最近恢复状态：${latest.status}`;
|
||
});
|
||
</script>
|
||
|
||
<template>
|
||
<div>{{ latestText }}</div>
|
||
</template>
|
||
```
|
||
|
||
## 8. 交互和展示建议
|
||
|
||
- 备份创建按钮点击后立即禁用，避免重复提交。
|
||
- 恢复预检通过后，必须展示备份号 `backupId`，让用户确认正在恢复哪个包。
|
||
- `precheckPassed=false` 时不要允许创建恢复任务。
|
||
- 恢复流程只做一次用户确认；确认后前端按顺序调用创建恢复任务和 apply。
|
||
- apply 返回后不要继续请求恢复步骤接口；恢复侧没有步骤接口。
|
||
- TMS 重启后只调用 latest 展示最近恢复结果。
|
||
- `payloadDecrypted=false` 不表示失败，它表示预检阶段没有解密完整 payload。
|
||
- `TMS_DB` 默认不包含角色、授权、会话和资源任务表，因此恢复不会覆盖新机器已有登录授权状态；操作审计日志默认随 TMS 库备份。
|
||
- 服务端路径类字段不展示给普通用户，只用于运维排查。
|