wangcong/story

Fork 0

Files

T

Codex Local 56b8e0c6da feat: verify production runtime integrity

2026-08-26 23:30:59 +08:00

13 KiB

Raw Permalink Blame History

发布候选证据包开发与使用说明

1. 目标与边界

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

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

2. 输入设计

2.1 必需参数

参数	说明
`-candidate-version`	与验收快照一致的候选版本，最长128字符
`-build-digest`	与验收快照一致的`sha256:`不可变构建摘要
`-source-commit`	源代码提交；`STAGING/PRODUCTION`必须是40或64位十六进制提交摘要，`LAB`可使用明确的本地标签
`-acceptance-snapshot`	`POST /api/v1/ops/diagnostics/acceptance-snapshots`返回或下载的JSON
`-evidence-index`	`release-evidence-index-v2`外部证据索引
`-pilot-daily-snapshot`	`PILOT`包重复传入恰好7次，分别对应周一至周日的`ops-pilot-daily-minimal-v1`日报
`-pilot-weekly-snapshot`	`PILOT`包必需的`ops-pilot-weekly-minimal-v1`完整周报
`-out`	新ZIP文件路径；已有文件不会被覆盖

技术验收快照必须满足：候选版本和构建摘要完全匹配、overall_gate_satisfied=true、脱敏策略为ops-acceptance-minimal-v1，并包含有效环境、验收类型、编号和生成时间。

2.2 PILOT周期证据

验收类型为PILOT时，打包器执行以下强制校验：

验收快照、7份日报和周报的tenant_id、candidate_version和build_digest完全一致；
所有日/周报使用同一个有效IANA时区，周报起始日是周一；
周报is_complete=true，生成时间不早于自然周结束时间，UTC窗口与业务自然周一致；
7份日报日期无重复、无缺失且完整覆盖周一至周日，每份UTC窗口与其业务自然日一致；
日报和周报分别使用ops-pilot-daily-minimal-v1、ops-pilot-weekly-minimal-v1；
周报继续包含complaints/REQUIRED，防止打包时把未接入的客服/CRM投诉证据误报为已完成。

任一项不满足即拒绝生成ZIP。非PILOT包不要求周期证据；若主动提供，则同样必须满足完整的一周规则，不能只附零散文件。

2.3 外部证据索引

索引必须逐项包含以下十个代码，不能缺少、重复或自行改名：

代码	证据范围
`REMOTE_CI_SUPPLY_CHAIN`	固定提交的远程CI、14项构建/质量/安全检查、后端与Web镜像摘要及三份CycloneDX SBOM；首个文件须为`REMOTE_CI_SUPPLY_CHAIN`一致性报告
`REAL_DEVICE_RTC`	量产候选终端、真实RTC、三模式通话和异常恢复
`REAL_DEVICE_FIRMWARE`	至少3台量产候选终端的四场景`HARDWARE_CAPTURE`固件一致性报告
`REAL_AGENT_MODELS`	真实语音、内容、Embedding、内容安全与效果评测
`PRODUCTION_INFRASTRUCTURE`	生产域名、证书、OIDC、数据库、Redis、对象存储、网络和监控
`PRODUCTION_RECOVERY`	生产等价备份恢复、滚动重启、供应商停机和回滚演练
`KMS_ROTATION`	云KMS/HSM身份、挂载、轮换及旧凭据失效
`REAL_ALERT_RECEIVER`	真实通知网关、值班组映射、唯一送达及正式告警演练
`SAFARI_COMPATIBILITY`	macOS最近两个Safari版本关键流程
`BUSINESS_APPROVAL`	产品、硬件、Agent、SRE、安全、法务和试点联合结论

每项状态只能为：

VERIFIED：至少关联一个实际证据文件；
PENDING：明确保留待外部验证，不会阻止生成包，但包状态不能进入发布评审就绪；
WAIVED：必须填写豁免说明，最终状态为RELEASE_REVIEW_WITH_WAIVERS，仍需有权人员复核。

REAL_DEVICE_FIRMWARE是不可豁免门禁。它只能保持PENDING或标记为VERIFIED，其中每个文件都必须是官方校验器生成、候选版本和构建摘要一致、全部检查通过且范围为HARDWARE_CAPTURE的firmware-conformance-report-v1。打包器要求至少3台不同真机中的每一台均完成AB_SUCCESS、AB_ROLLBACK、POWER_LOSS_AFTER_STAGE和POWER_LOSS_DURING_BOOT四个场景，共至少12份不重复报告。缺少设备或任一场景时，索引必须保持PENDING；模拟器的PROTOCOL_SIMULATION报告即使全部通过也会被拒绝作为真机证据。

REAL_ALERT_RECEIVER同样不可豁免。第一个证据文件必须是PASS/REAL_RECEIVER的alert-receiver-conformance-report-v1，并与候选版本和构建摘要一致。报告必须覆盖全部活动路由、每条路由的唯一验签联通回执、主/升级接收组映射以及一条已确认并解决的受控正式告警演练。只完成本地或测试网关时报告范围为MOCK_RECEIVER，不能进入真实接收器证据项；缺报告或缺正式演练时必须保持PENDING。

KMS_ROTATION也不可豁免。第一个文件必须是PASS/REAL_KMS_HSM的kms-rotation-conformance-report-v1，环境必须为预生产或生产，并同时覆盖逐请求动态读取和受控滚动重启两类凭据。新版本接受、旧版本拒绝、业务连续性、工作负载身份和云提供器审计缺一不可。本地LOCAL_SECRET报告只能证明演练工具可用，不能进入真实轮换证据项。

PRODUCTION_RECOVERY不可豁免。第一个文件必须是PASS/PRODUCTION_EQUIVALENT的production-recovery-conformance-report-v1，同一预生产或生产候选必须完成PostgreSQL隔离恢复、Redis权威状态重建、API/Callbacks/Worker滚动重启和供应商停机恢复。每项都必须证明权威数据一致、业务连续、没有重复效果并完成清理。本地LOCAL_RECOVERY报告不能放行。

PRODUCTION_INFRASTRUCTURE不可豁免。第一个文件必须是PASS/PRODUCTION_INFRASTRUCTURE的production-infrastructure-conformance-report-v1，并完整覆盖域名TLS、OIDC、PostgreSQL、Redis、对象存储、网络隔离和监控。每类组件必须具备规定控制项和探针、配置、审计引用。本地LOCAL_INFRASTRUCTURE报告只能验证采集工具链，不能放行。

SAFARI_COMPATIBILITY不可豁免。第一个文件必须是PASS/REAL_SAFARI的safari-compatibility-conformance-report-v1，覆盖发布依据中的CURRENT/PREVIOUS两个不同真实Safari版本、两种视口和六条关键流程，共24项结果。本地浏览器或Playwright WebKit只能形成NON_SAFARI_TOOLCHAIN报告，不能放行。

REAL_DEVICE_RTC不可豁免。第一个文件必须是PASS/REAL_DEVICE_RTC_PROVIDER的real-device-rtc-conformance-report-v1，至少3台量产候选终端以6通精简矩阵覆盖三种语音方式正常闭环，以及凭证续签、网络切换恢复和受控停止。每通都必须证明双向媒体、供应商启停、最终字幕、用量、质量结论、任务去重和资源回收。本地PROTOCOL_SIMULATION报告不能放行。

REAL_AGENT_MODELS不可豁免。第一个文件必须是PASS/REAL_AGENT_MODELS的real-agent-models-conformance-report-v1，内容生成必须使用real观测重新计算已有10类固定评测，Embedding和内容安全各覆盖6类精简数据集，并附数据条款和额度证据。本地生成器、哈希向量或本地规则只能形成LOCAL_AGENT_TOOLCHAIN报告，不能放行。

相对证据路径以索引文件所在目录为基准。每个文件必须是普通文件且不超过100 MiB。打包时本机绝对路径会被替换为包内路径，避免泄露工作站目录；不得把密钥、令牌、录音、字幕正文或未脱敏个人信息作为证据文件。

样例见testdata/release-evidence-index.example.v2.json。使用前必须替换候选版本、构建摘要、责任人、状态和证据文件。

3. 包结构与完整性

candidate-evidence.zip
├── release-manifest.json
├── evidence-index.json
├── acceptance/technical-acceptance-snapshot.json
├── pilot/daily/YYYY-MM-DD.json       # PILOT包恰好7份
├── pilot/weekly/YYYY-MM-DD.json      # PILOT包1份完整周报
├── baseline/openapi/openapi.yaml
├── baseline/migrations/*.sql
├── baseline/deploy/kubernetes/**
├── baseline/docs/**
├── baseline/artifacts/*.cdx.json       # 当前工作区存在时加入
└── evidence/<CODE>/<序号>-<文件名>

release-manifest.json使用release-candidate-evidence-bundle-v3，保存候选版本、构建摘要、源提交、OpenAPI版本、环境、验收类型、技术快照编号、外部证据状态计数、SBOM数量和每个归档文件的大小与SHA-256。remote_ci_supply_chain_validation给出远程运行、14项检查、双镜像摘要和三份SBOM覆盖，firmware_validation同步给出真机与四场景覆盖，real_device_rtc_validation给出真机、三种方式和四类RTC场景覆盖，real_agent_models_validation给出真实生成、Embedding和内容安全质量覆盖，alert_receiver_validation给出活动路由、映射、唯一回执和正式演练，kms_rotation_validation给出真实提供器和两种轮换模式，production_recovery_validation给出基础设施、四类演练和实际恢复用时，production_infrastructure_validation给出目标环境和七类组件控制项覆盖，safari_compatibility_validation给出两个Safari版本和24项关键流程矩阵。没有报告时这些门禁都会明确列出PENDING原因。PILOT包额外保存pilot_evidence_included=true、pilot_week_start、pilot_timezone和pilot_daily_count=7。清单不把自身摘要写入自身；命令完成后另行输出整个ZIP的sha256:摘要，用于制品库登记。

如果当前工作区没有CI生成的CycloneDX文件，包仍可用于外部验收准备，但清单写入SBOM_NOT_PRESENT_IN_WORKTREE警告，且REMOTE_CI_SUPPLY_CHAIN不应标记为已验证。

4. 使用流程

固定候选提交、构建镜像并取得不可变摘要。
使用相同候选标识生成技术验收快照；任一技术门禁失败先处理问题，不允许打包。
复制外部证据索引样例，逐项登记责任人、状态和文件；真机固件报告未达到3台×4场景时保持PENDING。
执行：

go run ./cmd/release-evidence `
  -root . `
  -candidate-version 0.55.0-rc.1 `
  -build-digest sha256:<64位摘要> `
  -source-commit <固定提交摘要> `
  -acceptance-snapshot E:\evidence\acceptance.json `
  -evidence-index E:\evidence\evidence-index.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-17.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-18.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-19.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-20.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-21.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-22.json `
  -pilot-daily-snapshot E:\evidence\daily\2026-08-23.json `
  -pilot-weekly-snapshot E:\evidence\weekly\2026-08-17.json `
  -out E:\evidence\data-terminal-cloud-0.55.0-rc.1.zip

保存命令输出的ZIP摘要，解包抽查清单，再上传只读制品库。
任何候选版本、构建摘要或源提交变化都重新生成快照和证据包；不修改旧包伪装成同一候选。

5. 验证

受影响模块测试：

go test ./internal/releaseevidence ./cmd/release-evidence

真实本地纵向烟测：

.\scripts\smoke-release-evidence.ps1

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

13 KiB Raw Permalink Blame History Unescape Escape