# 云端主机健康状态接入开发说明

## 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.67.0。最新快照同时进入发布候选技术验收门禁：缺失、超过15分钟、warning或critical都会阻断，只有当前healthy快照通过。`PRODUCTION`快照还执行独立的生产基础设施门禁：主机必须明确上报`production`部署模式，异地备份必须已完成远端回读校验且不过期，外部告警接收器必须配置，两个模拟服务必须停止。`LAB`和`STAGING`保留该门禁字段但标记为不适用，不影响现有开发与联调。

## 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
HOST_DEPLOYMENT_PROFILE=demo
```

不得仅把`HOST_DEPLOYMENT_PROFILE`改为`production`来制造放行结果。切换前应先停用模拟服务，启用并验证OSS异地备份，配置真实外部告警接收器及HMAC密钥，再执行一次主机健康检查并重新生成生产快照。

启用后执行：

```bash
systemctl start platform-health-monitor.service
systemctl show platform-health-monitor.service -p Result -p ExecMainStatus
```

验收至少确认：回调返回201/200；数据库迁移版本为39且`dirty=false`；运营查询返回最新观测时间；无签名、旧时间戳、聚合状态不一致均被拒绝；下一周期再次上报后快照时间前进。