feat: verify production runtime integrity

2026-08-26 23:30:59 +08:00
parent feb99de192
commit 56b8e0c6da
15 changed files with 103 additions and 22 deletions
@@ -1,7 +1,7 @@
 # 开发状态与门禁记录

 > 更新日期：2026-08-26
-> 当前接口契约版本：0.67.0
+> 当前接口契约版本：0.68.0
 > 当前主里程碑：M8目标环境联调、试点与上线验收（外部条件待提供）

 ## 阶段状态
@@ -181,7 +181,7 @@
 | 隐私删除并发 | 100个并发受理全部成功、HTTP失败率0%、提交p95 385.15ms；11.58秒内600个子任务、100个墓碑和100个主体冻结全部对账 |
 | PostgreSQL隔离恢复 | 实际`pg_dump`/`pg_restore`到随机隔离库，迁移`22|false`、66张表、190个外键和关键计数一致；本地约5.14秒，临时库/备份已清理 |
 | 阿里云单机加密备份与恢复 | 目标服务器已安装每日systemd备份任务，覆盖PostgreSQL、认证Redis RDB、MinIO全部桶和暂停后的Keycloak数据目录；归档使用AES-256-CBC/PBKDF2加密、逐文件SHA-256并保留14天。首次实际归档成功，数据库从V38备份恢复到随机隔离库后`38|false|2|3|73|215`六项证据一致，归档内Redis RDB格式有效、Keycloak 3个文件一致、临时恢复库为0；同机备份尚不作为跨故障域生产恢复证据 |
-| 阿里云单机健康监测 | 目标服务器已安装五分钟systemd健康检查，结构化状态覆盖部署模式、外部告警配置、HTTPS、宿主机公网监听端口、OIDC签发地址、核心容器、模拟服务、本机/异地备份状态与摘要、备份执行结果、三个运行timer、短期IP证书剩余时间和磁盘阈值。监听策略只允许非回环TCP 22/80/443，回环数据库端口不误报，额外端口会进入critical。演示正常路径26项全部healthy；生产模式要求模拟服务退出。可选Webhook仅在状态变化时发送带时间戳和HMAC-SHA256的脱敏状态；真实接收器尚未配置，因此不作为值班通知送达证据 |
+| 阿里云单机健康监测 | 目标服务器已安装五分钟systemd健康检查，结构化状态覆盖部署模式、实际应用运行环境、身份服务模式、外部告警配置、HTTPS、宿主机公网监听端口、OIDC签发地址、核心容器、模拟服务、本机/异地备份状态与摘要、备份执行结果、三个运行timer、短期IP证书剩余时间和磁盘阈值。监听策略只允许非回环TCP 22/80/443，回环数据库端口不误报，额外端口会进入critical。演示正常路径28项全部healthy；生产模式要求三个业务进程实际运行在`prod`、Keycloak不使用`start-dev`并退出模拟服务。可选Webhook仅在状态变化时发送带时间戳和HMAC-SHA256的脱敏状态；真实接收器尚未配置，因此不作为值班通知送达证据 |
 | 阿里云OSS异地备份适配 | 目标服务器已按官方SHA-256安装ossutil 2.3.0，新增每日OSS同步任务、加密归档及摘要上传、远端回读复算、原子状态和健康强制门禁。ECS正式路径现使用IMDSv2和`EcsRamRole`自动短期凭据，不保存长期AK；隔离配置模式验证上传/回读2个文件并得到`verified`，目标实例缺角色时退出4并记录`failed/ecs_ram_role_missing`。2026-08-26实测地域`cn-hangzhou`且角色元数据404；当前仍无RAM角色和Bucket，正式任务保持`disabled/not_enabled`且健康状态为`not_required`，不能作为真实异地备份证据 |
 | 进程与Redis恢复 | API/Callbacks/Worker重启恢复；停机期间Outbox仅执行一次；Redis 14个热状态键清空后由签名设备请求重建，PostgreSQL权威计数不变 |
 | 供应商故障恢复 | V23持久化按租户/供应商的可用状态；连续临时失败暂停新启动但停止任务继续尝试；演练确认暂停后新外呼0、停止尝试2次、历史接口200、CRITICAL告警出现，恢复后全部收敛；V23单版本回退/重升通过 |
@@ -252,6 +252,7 @@
 | 云端主机健康状态接入 | OpenAPI 0.65.0新增独立HMAC签名的主机健康回调、30天脱敏快照表和运营只读状态页面。五分钟周期上报覆盖公网入口、容器、备份、证书、磁盘和定时器；无签名、过期、重复检查及综合状态不一致报告被拒绝，页面超过15分钟未更新明确标记过期。该能力不替代整机、Callbacks或数据库失联时必须使用的外部探针。 |
 | 云端主机健康发布门禁 | OpenAPI 0.66.0把最新主机健康快照纳入发布候选技术验收：无上报、超过15分钟、综合预警或严重异常均阻断，只有当前有效且23项检查全部正常才通过，其中包括宿主机公网监听端口策略。快照仅归档状态、时间和检查数量，不复制磁盘、证书、监听地址或备份明细值。 |
 | 生产基础设施强制门禁 | OpenAPI 0.67.0把生产基础设施状态作为第八项技术门禁。`PRODUCTION`快照必须从当前主机健康报告同时证明`production`部署模式、OSS异地备份上传回读校验不过期、外部告警接收器已配置及两个Mock服务均已退出；演示机继续明确上报`demo`，因此生产快照会被如实阻断。`LAB/STAGING`标记为不适用，不影响开发联调。前端同步展示部署模式、告警和Mock状态；该门禁只证明配置与当前进程状态，不替代真实告警送达演练和生产基础设施一致性报告。 |
+| 生产运行时完整性门禁 | OpenAPI 0.68.0继续收紧第八项门禁：主机健康脚本直接读取API、Callbacks和Worker容器的`APP_ENV`及Keycloak实际启动命令。生产快照新增`application_runtime_ready`和`identity_service_ready`，只有三个进程均为`prod`且身份服务不使用`start-dev`才可通过；只修改`HOST_DEPLOYMENT_PROFILE`会同时触发运行环境和身份模式严重检查。演示路径保持`local/development`且功能可用，前端用业务化中文展示两项状态。 |
 | 阶段8外部执行轻量预检 | 新增`scripts/stage8-preflight.ps1`，以单一只读入口核对候选Git提交、远程仓库、Compose本地基线、外部配置变量名称和十类证据索引结构/状态；报告明确不读取密钥值，也不把环境变量或本地服务可用性当作验收证据。默认仅报告缺口，`-Strict`可供自动化阻断未就绪交接；当前已建立本地`main`候选提交，本地运行基线就绪且索引结构有效，仍缺远程仓库，样例构建摘要为占位值，十类外部证据均为`PENDING`。 |
 | 候选构建身份贯通 | Compose新增统一候选构建参数，后端二进制和后端/Web镜像OCI标签共享版本、完整Git提交及UTC构建时间；远程CI从OpenAPI版本和运行编号形成候选版本，构建后重新读取两个镜像标签并与`GITHUB_SHA`和构建时间逐项比对，再把候选版本、提交、时间和双镜像摘要写入构建元数据。修复了此前Dockerfile虽支持注入但Compose/CI未传参、运行版本仍为`dev/unknown`的问题。 |

@@ -1,7 +1,7 @@
 # 设备 API 兼容性约定

 > 当前设备接口主版本：`/device/v2`  
-> 当前接口契约：OpenAPI 0.67.0
+> 当前接口契约：OpenAPI 0.68.0
 > 适用对象：云端 API、终端固件、模拟终端和设备联调工具

 ## 1. 兼容目标
@@ -42,6 +42,7 @@ CI在拉取请求中以目标分支OpenAPI为基线执行破坏性变更检查

 | OpenAPI版本 | 设备兼容变更 | 兼容结论 |
 |---|---|---|
+| 0.68.0 | 生产基础设施状态增加实际应用运行环境与身份服务模式证明；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
 | 0.67.0 | 发布候选快照增加生产基础设施强制门禁及主机部署模式、异地备份、外部告警、模拟服务状态；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
 | 0.66.0 | 发布候选技术验收快照增加主机健康当前性门禁；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
 | 0.65.0 | 新增主机健康签名回调和运营只读查询；未修改设备端点、字段、状态机或终端行为 | v2完全兼容 |
@@ -97,7 +97,7 @@ powershell -ExecutionPolicy Bypass -File scripts/stage8-preflight.ps1 `
 - 最近两个Chrome/Edge和macOS最近两个Safari版本通过关键流程；
 - 使用`cmd/safari-conformance`归档同一候选在真实Safari `CURRENT/PREVIOUS`、两视口和六流程的24项结果；报告必须为`PASS/REAL_SAFARI`，证据包内`safari_compatibility_validation.coverage_complete=true`。
 - 核心模块覆盖率和关键分支覆盖率达到需求规定门槛，当前本地未达标项必须在发布前关闭或由风险负责人书面接受。
- 已使用生产候选镜像摘要生成`PRODUCTION_RELEASE`验收快照；运行版本必须等于候选版本且包含提交号和构建时间，八项技术门禁全部通过，其中生产基础设施门禁必须证明生产部署模式、已验证异地备份、真实外部告警配置和Mock服务退出。
+- 已使用生产候选镜像摘要生成`PRODUCTION_RELEASE`验收快照；运行版本必须等于候选版本且包含提交号和构建时间，八项技术门禁全部通过，其中生产基础设施门禁必须证明生产部署模式、三个业务进程实际运行在`prod`、身份服务不是开发模式、异地备份已验证、真实外部告警已配置和Mock服务已退出。
 - 使用`cmd/release-evidence`为同一候选版本、镜像摘要和源提交生成最终证据包；十类证据索引不得存在`PENDING`。出现`WAIVED`时必须附有权责任人的书面风险接受，包状态只能进入带豁免的发布评审，不能自动视为批准；八类不可豁免门禁不得使用`WAIVED`。

 ### 4.2 业务与合规门禁
@@ -35,7 +35,7 @@
 | `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`保留该门禁字段但标记为不适用，不影响现有开发与联调。
+接口契约见`openapi/openapi.yaml` 0.68.0。最新快照同时进入发布候选技术验收门禁：缺失、超过15分钟、warning或critical都会阻断，只有当前healthy快照通过。`PRODUCTION`快照还执行独立的生产基础设施门禁：主机必须明确上报`production`部署模式，API、Callbacks和Worker实际容器环境必须均为`prod`，身份服务不得使用Keycloak开发启动模式，异地备份必须已完成远端回读校验且不过期，外部告警接收器必须配置，两个模拟服务必须停止。`LAB`和`STAGING`保留该门禁字段但标记为不适用，不影响现有开发与联调。

 ## 5. 单机配置

@@ -47,7 +47,7 @@ PLATFORM_HEALTH_REPORT_SECRET_FILE=/etc/data-terminal-cloud/platform-health-call
 HOST_DEPLOYMENT_PROFILE=demo
 ```

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

 启用后执行：

@@ -4,7 +4,7 @@

 `cmd/release-evidence`用于阶段8联调、试点和生产发布前，把同一候选版本的技术验收快照、外部验收状态、真机固件一致性报告、接口契约、数据库迁移、部署清单、关键交付文档和可用SBOM封装为一个带SHA-256清单的ZIP。`PILOT`包还必须携带同一客户组织、同一业务时区、上一完整自然周的7份日报和1份周报。它解决证据散落、候选身份不一致、真机场景缺口被模拟结果掩盖、试点周期证据缺失以及归档后无法判断文件是否被替换的问题。

-证据包不是发布批准。生成器只在技术验收快照八项门禁全部通过时工作；其中生产快照必须额外证明生产部署模式、已验证异地备份、外部告警配置和模拟服务退出。外部证据可以保持`PENDING`，此时包内状态固定为`EXTERNAL_VALIDATION_PENDING`。真实设备、供应商、KMS、告警接收器、Safari或业务签署不能用本地模拟结果替代。
+证据包不是发布批准。生成器只在技术验收快照八项门禁全部通过时工作；其中生产快照必须额外证明生产部署模式、业务进程实际`prod`环境、身份服务非开发模式、已验证异地备份、外部告警配置和模拟服务退出。外部证据可以保持`PENDING`，此时包内状态固定为`EXTERNAL_VALIDATION_PENDING`。真实设备、供应商、KMS、告警接收器、Safari或业务签署不能用本地模拟结果替代。

 ## 2. 输入设计

@@ -143,4 +143,4 @@ go test ./internal/releaseevidence ./cmd/release-evidence
 .\scripts\smoke-release-evidence.ps1
 ```

-烟测使用真实OIDC生成绑定同一候选版本和API镜像摘要的`PILOT`技术验收快照、上一完整自然周的7份日报和1份周报，构造十项全部`PENDING`的外部索引，生成并解包临时ZIP，核对OpenAPI 0.67.0、v3清单、候选一致性、周期证据、摘要、待验计数和真机固件四场景缺口，随后清理临时文件、审计和幂等记录。技术验收快照还要求主机健康上报在15分钟内且没有warning/critical；生产类型另要求生产基础设施门禁通过。该结果只证明打包链路可用，不证明十项外部验收、真机固件或投诉证据已经完成。
+烟测使用真实OIDC生成绑定同一候选版本和API镜像摘要的`PILOT`技术验收快照、上一完整自然周的7份日报和1份周报，构造十项全部`PENDING`的外部索引，生成并解包临时ZIP，核对OpenAPI 0.68.0、v3清单、候选一致性、周期证据、摘要、待验计数和真机固件四场景缺口，随后清理临时文件、审计和幂等记录。技术验收快照还要求主机健康上报在15分钟内且没有warning/critical；生产类型另要求生产部署标记、实际应用环境、身份服务模式、异地备份、外部告警和Mock退出全部通过。该结果只证明打包链路可用，不证明十项外部验收、真机固件或投诉证据已经完成。
@@ -87,7 +87,7 @@

 | 来源 | 要求 | 当前处理 |
 |---|---|---|
-| P0414 | 首期需求、验收用例、缺陷和风险形成对应关系 | 本文完成首期功能到代码、接口、数据和验证的基线；V30问题清单由V36补充严重级别、根因、修复版本、回归证据及未关闭HIGH/CRITICAL发布阻断汇总；OpenAPI 0.50.0—0.67.0可按候选构建导出八项技术门禁及脱敏阻断告警定位快照，绑定候选版本/构建摘要后按业务时区归档日/周运行证据。第七项门禁要求主机健康快照在15分钟内且全部检查正常；第八项在`PRODUCTION`强制要求生产部署模式、已验证异地备份、外部告警配置及Mock服务退出，在`LAB/STAGING`明确标记不适用。`cmd/release-evidence`现使用v3清单，把同一候选的快照、接口、迁移、部署、SBOM和十类外部状态形成逐文件摘要；远程CI供应链、真机固件、真实终端RTC、真实Agent模型、真实告警网关、云KMS/HSM轮换、生产等价恢复、生产基础设施和Safari兼容分别要求结构化报告，并把14项CI检查/镜像/SBOM、设备固件场景、语音方式与恢复场景、生成/Embedding/内容安全质量、路由演练、轮换模式、恢复类型、基础设施控制项及Safari矩阵覆盖与缺口写入清单。V38及九个离线校验器把云端状态与远程构建、外部设备、RTC/语音供应商、模型提供器、网关、密钥提供器、目标环境和浏览器证据绑定；`content_safety_tls`把策略服务网络/证书状态纳入指标、告警、运营页面和候选快照。缺检查、缺制品、缺场景、缺演练、缺质量类别、缺控制项、`PENDING`和本地模拟证据均不会被误报为外部验收完成，整体发布仍必须基于真实联调、灰度和审批记录确认。 |
+| P0414 | 首期需求、验收用例、缺陷和风险形成对应关系 | 本文完成首期功能到代码、接口、数据和验证的基线；V30问题清单由V36补充严重级别、根因、修复版本、回归证据及未关闭HIGH/CRITICAL发布阻断汇总；OpenAPI 0.50.0—0.68.0可按候选构建导出八项技术门禁及脱敏阻断告警定位快照，绑定候选版本/构建摘要后按业务时区归档日/周运行证据。第七项门禁要求主机健康快照在15分钟内且全部检查正常；第八项在`PRODUCTION`强制要求生产部署模式、三个业务进程实际`APP_ENV=prod`、身份服务非开发模式、已验证异地备份、外部告警配置及Mock服务退出，在`LAB/STAGING`明确标记不适用。`cmd/release-evidence`现使用v3清单，把同一候选的快照、接口、迁移、部署、SBOM和十类外部状态形成逐文件摘要；远程CI供应链、真机固件、真实终端RTC、真实Agent模型、真实告警网关、云KMS/HSM轮换、生产等价恢复、生产基础设施和Safari兼容分别要求结构化报告，并把14项CI检查/镜像/SBOM、设备固件场景、语音方式与恢复场景、生成/Embedding/内容安全质量、路由演练、轮换模式、恢复类型、基础设施控制项及Safari矩阵覆盖与缺口写入清单。V38及九个离线校验器把云端状态与远程构建、外部设备、RTC/语音供应商、模型提供器、网关、密钥提供器、目标环境和浏览器证据绑定；`content_safety_tls`把策略服务网络/证书状态纳入指标、告警、运营页面和候选快照。缺检查、缺制品、缺场景、缺演练、缺质量类别、缺控制项、`PENDING`和本地模拟证据均不会被误报为外部验收完成，整体发布仍必须基于真实联调、灰度和审批记录确认。 |
 | P0445 | 需求编号关联代码、测试、接口或配置变更 | 本文逐项建立关联；后续功能变更必须同步更新本矩阵和`development-status.md`。 |

 当前仍不能宣告完成的部分集中为：真实火山RTC与豆包三模式联调、真实方舟内容与Embedding质量、真实听筒的长者交流体验、量产设备/KMS注入、跨故障域生产对象存储与备份、真机异常恢复、真实账单和生产级内容安全。阿里云单机环境已经形成加密全组件归档、数据库隔离恢复和Redis RDB校验，但同机归档不能替代托管PITR、异地副本和生产恢复演练。这些剩余项属于阶段8外部验收，不应通过增加本地低价值测试伪造完成证据。
@@ -11,6 +11,8 @@
 | 检查 | 正常条件 | 失败状态 |
 |---|---|---|
 | 部署模式 | `HOST_DEPLOYMENT_PROFILE`只能为`demo`或`production` | 非法值直接拒绝执行 |
+| 应用运行环境 | API、Callbacks和Worker实际容器`APP_ENV`必须一致；`demo`要求`local`，`production`要求`prod` | `missing`、`mixed`或与部署模式不符的实际值 |
+| 身份服务模式 | `demo`可使用开发模式；`production`不得使用Keycloak `start-dev` | `missing`或`development` |
 | 外部告警接收器 | `demo`未配置时明确记录`not_configured`；`production`必须配置且HMAC密钥不少于32字节 | `not_configured`、`secret_missing`或`secret_invalid` |
 | 公网地址 | `PUBLIC_ORIGIN`为HTTPS | `invalid_https_origin` |
 | HTTPS入口 | `/api/v1/version`在10秒内返回成功 | `request_failed` |
@@ -134,7 +136,7 @@ systemctl list-timers platform-health-monitor.timer platform-backup.timer certbo
 docker compose -f compose.yaml -f deploy/server/compose.override.yaml --env-file deploy/server/.env ps -a
 ```

-生产分支可在不改变线上容器的情况下验证。临时配置`HOST_DEPLOYMENT_PROFILE=production`运行检查时，只要模拟服务仍在运行，结果必须为critical且`mock_services=unexpected_running`；测试状态目录应与正式目录隔离。
+生产分支可在不改变线上容器的情况下验证。临时配置`HOST_DEPLOYMENT_PROFILE=production`运行检查时，当前演示栈必须因`application_environment=local`、`identity_service_mode=development`、外部告警、异地备份及模拟服务同时进入critical；测试状态目录应与正式目录隔离。该检查读取容器实际环境和Keycloak启动命令，不能只改主机配置文件伪造生产结果。

 ## 8. 下一步生产化