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

1. 目标与边界

单机健康监测原先只把结果保存在主机/var/lib/data-terminal-cloud-monitor/status.json。本功能把同一份脱敏状态每五分钟签名上报到Callbacks进程，并在运营“联调诊断”工作台展示最新结果，覆盖部署模式、公网HTTPS、OIDC签发地址、核心容器、模拟服务、本地及异地备份、外部告警配置、证书、磁盘和systemd定时器。

该链路用于当前状态查看和排障，不替代外部告警网关：Callbacks、数据库或整机同时不可用时，平台无法把自身故障写入自身数据库，仍需阿里云云监控、独立探针或真实值班网关从系统外发现。

2. 业务流程

platform-health-monitor.timer每五分钟运行deploy/server/health-monitor.sh。
脚本执行全部轻量检查，先原子更新主机状态文件。
配置PLATFORM_HEALTH_REPORT_URL后，脚本使用独立密钥对Unix时间戳 + "." + 原始JSON正文计算HMAC-SHA256，发送至POST /callbacks/v1/platform-health。
Callbacks校验64KiB正文上限、五分钟签名时间窗、JSON严格字段、15分钟观测时间窗、检查名唯一性及综合状态一致性。
PostgreSQL按正文SHA-256幂等保存快照；完全相同的重放返回原公开编号。数据保留30天。
具备ops_viewer、ops_operator、ops_approver或ops_admin角色的账号通过GET /api/v1/ops/diagnostics/platform-health读取最新快照。
前端超过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.68.0。最新快照同时进入发布候选技术验收门禁：缺失、超过15分钟、warning或critical都会阻断，只有当前healthy快照通过。PRODUCTION快照还执行独立的生产基础设施门禁：主机必须明确上报production部署模式，API、Callbacks和Worker实际容器环境必须均为prod，身份服务不得使用Keycloak开发启动模式，异地备份必须已完成远端回读校验且不过期，外部告警接收器必须配置，两个模拟服务必须停止。LAB和STAGING保留该门禁字段但标记为不适用，不影响现有开发与联调。

5. 单机配置

首次部署由bootstrap-secrets.sh生成独立密钥，install-monitoring.sh把同一值写入root只读文件并自动设置当前公网回调地址。已有环境升级时需把deploy/server/.env中的PLATFORM_HEALTH_CALLBACK_SECRET与主机密钥文件保持一致，并在/etc/data-terminal-cloud/monitor.env增加：

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来制造放行结果。监控脚本会读取三个业务进程的实际APP_ENV和Keycloak启动命令。切换前应先使用能通过服务端生产配置校验的APP_ENV=prod部署，停用身份服务开发模式和模拟服务，启用并验证OSS异地备份，配置真实外部告警接收器及HMAC密钥，再执行一次主机健康检查并重新生成生产快照。

启用后执行：

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

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

4.8 KiB Raw Blame History Unescape Escape