57 lines
3.7 KiB
Markdown
57 lines
3.7 KiB
Markdown
# 云端主机健康状态接入开发说明
|
||
|
||
## 1. 目标与边界
|
||
|
||
单机健康监测原先只把结果保存在主机`/var/lib/data-terminal-cloud-monitor/status.json`。本功能把同一份脱敏状态每五分钟签名上报到Callbacks进程，并在运营“联调诊断”工作台展示最新结果，覆盖公网HTTPS、OIDC签发地址、核心容器、本地及异地备份、证书、磁盘和systemd定时器。
|
||
|
||
该链路用于当前状态查看和排障，不替代外部告警网关：Callbacks、数据库或整机同时不可用时，平台无法把自身故障写入自身数据库，仍需阿里云云监控、独立探针或真实值班网关从系统外发现。
|
||
|
||
## 2. 业务流程
|
||
|
||
1. `platform-health-monitor.timer`每五分钟运行`deploy/server/health-monitor.sh`。
|
||
2. 脚本执行全部轻量检查，先原子更新主机状态文件。
|
||
3. 配置`PLATFORM_HEALTH_REPORT_URL`后，脚本使用独立密钥对`Unix时间戳 + "." + 原始JSON正文`计算HMAC-SHA256，发送至`POST /callbacks/v1/platform-health`。
|
||
4. Callbacks校验64KiB正文上限、五分钟签名时间窗、JSON严格字段、15分钟观测时间窗、检查名唯一性及综合状态一致性。
|
||
5. PostgreSQL按正文SHA-256幂等保存快照；完全相同的重放返回原公开编号。数据保留30天。
|
||
6. 具备`ops_viewer`、`ops_operator`、`ops_approver`或`ops_admin`角色的账号通过`GET /api/v1/ops/diagnostics/platform-health`读取最新快照。
|
||
7. 前端超过15分钟未收到新快照时明确显示“上报过期”，不继续把旧的`healthy`当作当前状态。
|
||
|
||
## 3. 数据与安全设计
|
||
|
||
`platform_health_snapshot`保存公开编号、模式版本、综合状态、观测/接收时间、检查数组及正文摘要。检查值限制为256字符，拒绝换行、NUL、重复名称和未知状态。报告不包含数据库连接串、Redis密码、Webhook地址、证书正文、访问令牌、业务记录或个人数据。
|
||
|
||
主机上报密钥与供应商回调密钥、告警投递密钥相互独立：
|
||
|
||
- 容器环境：`PLATFORM_HEALTH_CALLBACK_SECRET`或`PLATFORM_HEALTH_CALLBACK_SECRET_FILE`；
|
||
- 主机文件：`/etc/data-terminal-cloud/platform-health-callback-secret`，权限`0600 root:root`；
|
||
- 主机配置：`PLATFORM_HEALTH_REPORT_SECRET_FILE`指向该文件。
|
||
|
||
密钥至少32字符。生产Kubernetes通过`voice-platform-callbacks-secrets/platform-health-callback-secret`挂载，不把正文写进ConfigMap或镜像。
|
||
|
||
## 4. 接口摘要
|
||
|
||
| 接口 | 身份 | 结果 |
|
||
|---|---|---|
|
||
| `POST /callbacks/v1/platform-health` | 独立HMAC签名 | 新快照返回201；完全重复返回200 |
|
||
| `GET /api/v1/ops/diagnostics/platform-health` | OIDC + 运营角色 + 客户组织选择 | 返回全平台最新脱敏快照 |
|
||
|
||
接口契约见`openapi/openapi.yaml` 0.65.0。
|
||
|
||
## 5. 单机配置
|
||
|
||
首次部署由`bootstrap-secrets.sh`生成独立密钥，`install-monitoring.sh`把同一值写入root只读文件并自动设置当前公网回调地址。已有环境升级时需把`deploy/server/.env`中的`PLATFORM_HEALTH_CALLBACK_SECRET`与主机密钥文件保持一致，并在`/etc/data-terminal-cloud/monitor.env`增加：
|
||
|
||
```dotenv
|
||
PLATFORM_HEALTH_REPORT_URL=https://121.41.46.238/callbacks/v1/platform-health
|
||
PLATFORM_HEALTH_REPORT_SECRET_FILE=/etc/data-terminal-cloud/platform-health-callback-secret
|
||
```
|
||
|
||
启用后执行：
|
||
|
||
```bash
|
||
systemctl start platform-health-monitor.service
|
||
systemctl show platform-health-monitor.service -p Result -p ExecMainStatus
|
||
```
|
||
|
||
验收至少确认：回调返回201/200；数据库迁移版本为39且`dirty=false`；运营查询返回最新观测时间；无签名、旧时间戳、聚合状态不一致均被拒绝；下一周期再次上报后快照时间前进。
|