wangcong/story
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: expose signed platform health status

Browse Source
This commit is contained in:
Codex Local
2026-08-26 21:15:03 +08:00
parent 1e12d329dc
commit 47ef596d3b
30 changed files with 811 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/development-status.md
+2 -1
View File
@@ -1,7 +1,7 @@
# 开发状态与门禁记录
> 更新日期：2026-08-26
> 当前接口契约版本：0.64.0
> 当前接口契约版本：0.65.0
> 当前主里程碑：M8目标环境联调、试点与上线验收（外部条件待提供）
## 阶段状态
@@ -249,6 +249,7 @@
| 真实终端RTC/语音供应商精简矩阵与发布门禁 | 新增`real-device-rtc-capture-v1`、`real-device-rtc-conformance-report-v1`和`cmd/rtc-conformance`。真实报告以至少3台候选终端执行6通：`s2s_pure/s2s_hybrid/cascade`各正常完成1通，再覆盖凭证续签、网络切换恢复和受控停止；每通必须证明房间/用户/任务绑定、双向媒体、固定状态序列、供应商启停、最终字幕、用量、质量通过、任务去重和资源回收。协议模拟固定为`PROTOCOL_SIMULATION/external_validation_required=true`。v3证据包新增`real_device_rtc_validation`，该门禁不可豁免且首个文件必须为合格真实报告。按低强度策略执行采集器/证据包定向测试和一条协议结构工具链冒烟：1台模拟终端1通结构结果生成`PASS/PROTOCOL_SIMULATION`并继续外部待验；证据包保留真实报告、设备/通话数量、三方式和四场景共10项缺口，临时文件已清理。 |
| 真实Agent生成、Embedding和内容安全质量门禁 | 新增`real-agent-models-capture-v1`、`real-agent-models-conformance-report-v1`和`cmd/agent-models-conformance`。内容生成复用现有固定10类Agent评测，并使用评测集、脱敏观测和报告重新计算防篡改；Embedding按版本化阈值覆盖精确/改写召回、跨长者隔离、撤销/敏感排除和无匹配降级六类；内容安全覆盖验证码、金融账户、提示注入、敏感医疗、正常内容和模型输出六类。真实证据还必须绑定受控提供器、账号/区域、数据条款、额度和审计引用；本地生成器、哈希向量和规则固定为`LOCAL_AGENT_TOOLCHAIN/external_validation_required=true`。v3证据包新增`real_agent_models_validation`，该门禁不可豁免。按低强度策略执行聚合器/证据包定向测试和一条重算现有模拟报告的本地工具链冒烟：既有10类模拟报告重新计算一致，两组六类结构完整，输出`PASS/LOCAL_AGENT_TOOLCHAIN`并继续外部待验；证据包保留真实报告、三提供器和12类别共16项缺口，临时文件已清理。 |
| 托管内容安全外部预检与告警 | OpenAPI 0.64.0把`content_safety_tls`纳入外部依赖查询和候选验收快照。生产Worker仅执行DNS、TCP和受信TLS握手，不发送待分类正文；结果复用依赖可用性指标、数据库脱敏状态和运营诊断页面，连续5分钟不可用进入统一CRITICAL告警，记录缺失/失败/过期均可阻断候选技术快照但不驱逐Pod。按低强度策略执行App/探针/诊断定向测试、前端类型生成/类型检查/生产构建和Prometheus规则校验。 |
| 云端主机健康状态接入 | OpenAPI 0.65.0新增独立HMAC签名的主机健康回调、30天脱敏快照表和运营只读状态页面。五分钟周期上报覆盖公网入口、容器、备份、证书、磁盘和定时器；无签名、过期、重复检查及综合状态不一致报告被拒绝，页面超过15分钟未更新明确标记过期。该能力不替代整机、Callbacks或数据库失联时必须使用的外部探针。 |
| 阶段8外部执行轻量预检 | 新增`scripts/stage8-preflight.ps1`，以单一只读入口核对候选Git提交、远程仓库、Compose本地基线、外部配置变量名称和十类证据索引结构/状态；报告明确不读取密钥值，也不把环境变量或本地服务可用性当作验收证据。默认仅报告缺口，`-Strict`可供自动化阻断未就绪交接；当前已建立本地`main`候选提交，本地运行基线就绪且索引结构有效，仍缺远程仓库，样例构建摘要为占位值，十类外部证据均为`PENDING`。 |
| 候选构建身份贯通 | Compose新增统一候选构建参数，后端二进制和后端/Web镜像OCI标签共享版本、完整Git提交及UTC构建时间；远程CI从OpenAPI版本和运行编号形成候选版本，构建后重新读取两个镜像标签并与`GITHUB_SHA`和构建时间逐项比对，再把候选版本、提交、时间和双镜像摘要写入构建元数据。修复了此前Dockerfile虽支持注入但Compose/CI未传参、运行版本仍为`dev/unknown`的问题。 |
docs/device-api-compatibility.md
+2 -1
View File
@@ -1,7 +1,7 @@
# 设备 API 兼容性约定
> 当前设备接口主版本：`/device/v2`
> 当前接口契约：OpenAPI 0.64.0
> 当前接口契约：OpenAPI 0.65.0
> 适用对象：云端 API、终端固件、模拟终端和设备联调工具
## 1. 兼容目标
@@ -43,6 +43,7 @@ CI在拉取请求中以目标分支OpenAPI为基线执行破坏性变更检查
| OpenAPI版本 | 设备兼容变更 | 兼容结论 |
|---|---|---|
| 0.64.0 | 运营外部预检增加`content_safety_tls`枚举和候选快照第四类可选必需依赖；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
| 0.65.0 | 新增主机健康签名回调和运营只读查询；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
| 0.63.0 | 增加设备固件阶段事件查询及云端证据字段；设备已有命令回执仅记录同一结果的不可变事件，未增加旧终端必填字段 | v2兼容，旧终端行为不变 |
| 0.62.0 | 命令结果增加A/B写入、待重启、启动健康和回退可选字段，省略时保持原有单分区结果语义 | v2兼容，旧终端可继续省略 |
| 0.61.0 | 新增家庭侧固件版本影响只读接口，未修改设备协议 | v2完全兼容 |
docs/kubernetes-deployment.md
+2 -2
View File
@@ -84,7 +84,7 @@ docker push "$Registry/migrate:$Version"
|---|---|---|
| `voice-platform-common-secrets` | `database-url`、`redis-password` | API、Callbacks、Worker、迁移Job |
| `voice-platform-api-secrets` | `rtc-app-key`、`cursor-signing-secret`、`share-token-signing-secret` | API |
| `voice-platform-callbacks-secrets` | `provider-callback-secret` | Callbacks |
| `voice-platform-callbacks-secrets` | `provider-callback-secret`、`platform-health-callback-secret` | Callbacks |
| `voice-platform-worker-secrets` | `volc-access-key-id`、`volc-secret-access-key`、`voice-chat-template.json` | Worker |
| `voice-platform-model-storage-secrets` | `object-store-access-key`、`object-store-secret-key`、`ark-api-key`、`content-safety-api-key` | API、Worker；内容安全Key仅由Worker引用 |
| `voice-platform-device-secrets` | 每台设备一个key，例如`terminal-001` | API |
@@ -119,7 +119,7 @@ kubectl -n voice-platform get secret
|---|---|
| `voice-platform-common` | `database-url`、`redis-password` |
| `voice-platform-api` | `rtc-app-key`、`cursor-signing-secret`、`share-token-signing-secret` |
| `voice-platform-callbacks` | `provider-callback-secret` |
| `voice-platform-callbacks` | `provider-callback-secret`、`platform-health-callback-secret` |
| `voice-platform-worker` | `volc-access-key-id`、`volc-secret-access-key`、`voice-chat-template.json` |
| `voice-platform-model-storage` | `object-store-access-key`、`object-store-secret-key`、`ark-api-key`、`content-safety-api-key` |
| `voice-platform-devices` | 每台设备一个文件，例如`terminal-001` |
docs/platform-health-reporting.md
+56
View File
@@ -0,0 +1,56 @@
# 云端主机健康状态接入开发说明
## 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`；运营查询返回最新观测时间；无签名、旧时间戳、聚合状态不一致均被拒绝；下一周期再次上报后快照时间前进。
docs/server-health-monitoring.md
+8 -1
View File
@@ -20,7 +20,7 @@
| 证书 | 本地活动证书剩余时间不少于36小时 | `missing`或`remaining_seconds=...` |
| 磁盘 | 低于80%为健康，80%—89%为warning，90%及以上为critical | `used_percent=...` |
状态文件写入`/var/lib/data-terminal-cloud-monitor/status.json`，格式为`platform-server-health-v1`。每个检查只有稳定名称、状态和脱敏值，不包含数据库密码、Webhook地址、证书正文、业务数据或令牌。
状态文件写入`/var/lib/data-terminal-cloud-monitor/status.json`，格式为`platform-server-health-v1`。每个检查只有稳定名称、状态和脱敏值，不包含数据库密码、Webhook地址、证书正文、业务数据或令牌。配置平台健康上报后，同一状态会每五分钟通过独立HMAC密钥发送到Callbacks并在运营联调诊断页面展示，详细协议见[云端主机健康状态接入开发说明](platform-health-reporting.md)。
## 3. 状态模型
@@ -65,6 +65,13 @@ ALERT_WEBHOOK_URL=https://receiver.example.com/platform-health
ALERT_WEBHOOK_SECRET_FILE=/etc/data-terminal-cloud/monitor-webhook-secret
```
平台内部状态上报与外部告警分开配置；内部上报每个周期发送，外部告警仍只在综合状态变化时发送：
```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
```
只有总体状态发生变化时才发送JSON状态文件。请求包含：
- `Content-Type: application/json`；