Web_FreeCAD_Bitbybit/docs/release-runbook.zh-CN.md

BitBybit CAD Studio 发布 Runbook

基线：FreeCAD 1.1.1（提交 0108fd4b4850cc46e625b60e53cea7a7bbe69f8d），Chrome 150，COOP/COEP 隔离上下文，sqlite-opfs 持久化。

发布前

1. 使用锁定 Node/npm 环境运行 ./npmw run verify。
2. 确认 ./npmw run check:release-closure 输出 G0-G9 全部通过。
3. 受控本地发布使用 .secrets/release-signing-private.pem（权限 600，已被 Git 忽略）和默认 key id bitbybit-local-release-2026；先执行 ./npmw run check:release-signing-key，再执行 ./npmw run build && ./npmw run generate:release-artifacts。CI/发布机也可注入 RELEASE_SIGNING_PRIVATE_KEY、RELEASE_SIGNING_KEY_ID，入口会校验其 Ed25519 类型及与仓库公钥的一致性。
4. 只发布 dist/、config/sbom.cdx.json、config/release-artifacts.json 和对应公钥；私钥不得进入仓库或静态资源。密钥轮换必须同时更新受控私钥和 config/release-signing-public.pem，然后重新生成清单。

部署

保持 Cross-Origin-Opener-Policy: same-origin、Cross-Origin-Embedder-Policy: require-corp、Cross-Origin-Resource-Policy: same-origin、Permissions-Policy 和 CSP。Service Worker cache 名称由构建产物固定为 bitbybit-cad-shell-v1；哈希资源和 OCCT/SQLite WASM 必须存在于 precache。

升级、回滚与诊断

先保留旧 cache 和旧发布清单，再切换新版本。首装/升级/离线/缓存清理使用 ./npmw run test:chrome-offline 复核；项目 schema 迁移与整事务回滚使用 ./npmw run check:project-migration 和 ./npmw run check:chrome-opfs-migration。若签名或 SBOM 校验失败，停止切换并回滚至上一份已签名清单；不得以 unsigned-development 产物替代。

出现 Worker/WASM 崩溃或 stale 结果时运行 ./npmw run check:chrome-fault-injection，确认恢复状态和资源计数；出现格式/权限问题时运行 ./npmw run check:chrome-security。浏览器不满足隔离或 OPFS 能力时显示明确降级/导出路径，不伪装为完整兼容。