hyb-oa/.trellis/tasks/08-08-production-deployment-execution/implement.md

生产部署执行与验收：实施清单

0. 规划与启动门禁

• 已向用户呈现本 task 的最终规划摘要，并取得对该摘要的最新明确批准。
• 已解决候选发布是否可进入上游的外部授权；未获授权不得使用 unpublished override。
• 任务从 planning 切换到 in_progress 前，确认本清单、PRD、design 与 Open Questions 已收敛。
• **规划修订复核：**确认唯一公网环境拓扑、精确身份匹配和数据库名只读引导的修订摘要，并重新批准后再改 tooling/连接生产。

1. 候选与本地证据

• 提交本 task 的规划 artifacts，确认工作区 clean。
• 记录候选完整 commit、短 SHA、分支和上游包含关系；不把连接串、SSH target 或环境值写入文档。
• 运行 node deploy/trialrun/check-source-provenance.mjs，要求 published=true、remoteVerified=true。
• 运行既有本地合同门禁：
  • node deploy/trialrun/validate-env-contract.js
  • 相关部署 shell bash -n
  • node --check deploy/trialrun/production-preflight.mjs
• 聚焦 deployment-safety-contract.test.js（既有提交证据为 13/13，本轮未重复触发生产动作）

1.1 拓扑校准与 tooling 修订（生产前）

• **刻意次序调整：**本轮 target gate 不再是第一条生产命令；历史身份恢复、refresh exact probe、systemd contract/公网 origin 核对、远端 POSTGRES_DB 只读引导四步探测排在其之前。四步全程只读、逐步 fail-closed，任一失败均不得进入 target gate 或 Prisma status。
• 从 34181e3 只读恢复历史 DEPLOY_SERVER，从 5e2d03893826 恢复首次显式冻结的 COMPOSE_PROJECT_NAME；确认历史 REMOTE_DIR 只是未验证 fallback，不作为身份基线。值仅保存在当前进程，不写入 task、日志或对话。
• 无回显探测 DEPLOY_REFRESH_SERVER，要求 exact forced-command probe 唯一 PASS；多个候选或零候选均 PAUSED。
• 修改 production preflight：取消对合法 trialrun 命名的单独拒绝，增加部署目标、远端目录、Compose project、systemd contract、公网 origin 的精确身份对账；保留回环/零地址/local regression/staging/shadow/placeholder 防线。
• 明确 DEPLOY_SERVER 验证责任：真实来源在上游历史身份解析；引导器向 preflight 同时传 actual/expected 只用于防进程内漂移，不构成第二个独立身份来源。若重构上游，必须保留独立 target 来源校验，不能把下游恒等比较当作替代。
• 增加只读数据库身份 bootstrap：身份组匹配后读取远端 .env 的 POSTGRES_DB，在远端转换为 SHA-256 比较基线后仅在内存中传给 target gate；数据库名明文禁止离开远端、回显或落盘，读取失败或身份组不一致时不得进入 Prisma status。
• 增加 synthetic fixture：合法 hyb-oa-trialrun 身份通过；错误目录/project/host/db、回环、staging、占位符和多 refresh 候选 fail-closed；断言 bootstrap 不泄露值且顺序早于 status。
• 增加 PRODUCTION_READ_ONLY_PREFLIGHT=1 停止点：完成 target/pre-status 与回滚窗口后、进入 deploy.sh 前退出；只读证据复核通过前不得运行写入路径。
• 增加 PRODUCTION_IDENTITY_ONLY=1 停止点：以 contract 定位远端 .env/容器并完成 origin 双取样后，冻结 contract REMOTE_DIR 为进程内精确基线并立即退出；不得读取数据库名、运行 13 项体检或 Prisma。
• 重新运行部署安全测试、shell/Node syntax、task/governance/sensitive/diff 门禁，提交并推送新的候选后重新通过 provenance。

2. 生产 preflight（全部只读）

• 在同一进程内加载现行 OPS7 origin、历史身份恢复结果、exact refresh identity、只读 DB bootstrap 结果和 EXPECTED_PENDING_MIGRATIONS；不把任何值写入仓库或对话。
• 先运行 check-existing-deployment.sh，记录 13 项真实 PASS/FAIL 数字；任何 FAIL 停止。
• 运行 deploy-existing.sh 内置的 source/target/preflight，或按同一 wrapper 的只读阶段执行；人工阅读 target gate 原始输出和 Prisma status marker 原文。
• 核对 candidate migration manifest、_prisma_migrations applied/异常/pending 集合和批准 allowlist；未知 pending、failed、rolled-back、unfinished、diverged 或目标身份不确定均 PAUSED。
• 同一只读窗口查询 terminated 行数，记录 rollbackWindow=OPEN|CLOSED、实际 count 和读取时间；确认这是部署前快照。
• 确认 preflight 到 deploy 之间有配置/数据库变更冻结；无法保证则停止。

3. 获批发布（唯一写入阶段）

• 再次确认 preflight 所有门禁仍为 PASS，且没有新的远端配置/候选变化。
• 仅调用 deploy/trialrun/deploy-existing.sh，固定 SYNC_ENV=0、DEPLOY_DATA_MODE=existing、DEPLOY_STATUS_OUTPUT_MODE=quiet。
• 允许的 schema 写入仅为候选 migration；不得执行 migrate dev、reset、db push、resolve、手工 DDL、seed 或业务 API 写入。
• 若 deploy/migrate/init 中途失败，保留远端现场并停止；不自行重试、回滚或清理。

4. 发布后只读验收

• 保存 post-status 原始输出（仅受控现场）及脱敏副本；确认全部候选 migration applied / schema up to date。
• 核对 /ready、完整 build SHA、公开短 SHA 与候选 commit。
• 运行基础 smoke、external deps smoke、runtime smoke 和公开 bundle 扫描，记录真实数字和输出摘要。
• 在任何真实终止写入前完成未登录、无权限、详情不存在/无权等权限负向路径及合同详情只读检查；缺凭据项标 PAUSED/SKIP。
• 检查备份合同 refresh；失败记 DEPLOYED_BUT_CONTRACT_REFRESH_FAILED，不重复发布应用。

5. 失败分流、review 与收口

• 将每个失败归入 target/migration、应用健康、refresh、public/live/permission 之一；不得把迁移失败与产品回归混为一类。
• 记录真实业务写入计数为 0（本 task 不主动写入 terminated 或其他业务数据）。
• 对照部署前窗口快照决定兼容回退或 roll-forward；CLOSED 时不得回退到不识别 terminated 的旧应用，不 drop 三列。
• 启动只读 reviewer，确认门禁顺序、原始证据可追溯、脱敏副本无敏感信息、失败后没有继续推进。
• 运行最终 Trellis/process/docs/governance/sensitive/diff 门禁；通过后提交中文 commit 并引用 08-08-production-deployment-execution。
• 只有生产、公网和必要真机全部获批并通过时才可告知用户可以测试；否则保留 PAUSED。
• 归档 task 并记录会话日志，报告中保留 pre/post status、target gate、窗口判定和所有 PAUSED/SKIP 原因。

Rollback Points

1. 来源或 preflight 失败：尚未写入，停止并修正授权/输入后重新检查。
2. migrate deploy/init 失败：保留现场，禁止 reset/resolve/drop，等待明确处置。
3. /ready/smoke 失败：窗口 OPEN 可按既有合同回退兼容应用；窗口 CLOSED 只 roll-forward。
4. refresh 失败：应用已部署但合同刷新失败，不重复发布应用，只走合同修复流程。

Evidence Notes

• 原始 target gate 和 Prisma status stdout/stderr 不进 Git；只在受控执行现场留存。
• 任务 artifacts 只保存脱敏副本、commit、状态码、migration ID、计数、窗口状态和证据引用。
• 不保存生产 origin、数据库名、SSH target、用户名、绝对远端路径、连接串、凭据、业务正文或原始 payload。

Execution Evidence (2026-08-08)

• 规划提交：4596ed0；暂停证据提交：73f1467；当前候选已推送到配置的 origin/main，check-source-provenance.mjs 返回 published=true、remoteVerified=true。
• 本地门禁：env contract、shell/Node syntax、task validate、process contract、docs audit（0 errors，保留仓库既有 warning）、Trellis governance（0 errors/0 warnings）、sensitive scan（0 findings）均通过。
• 生产输入存在性检查：EXPECTED_PRODUCTION_ORIGIN、EXPECTED_PRODUCTION_DB_NAME、EXPECTED_PENDING_MIGRATIONS、DEPLOY_SERVER、DEPLOY_REFRESH_SERVER 五个进程输入均未注入；受控 contract 路径按设计应在连接目标后由 systemd unit 读取，未把它们误当作本地输入缺失。
• 生产动作：未执行 SSH、target gate、prisma migrate status、migrate deploy、数据库写入、refresh、公网 smoke 或真机验证；AC1 的生产体检及 AC2–AC7 保持未验收并标记 PAUSED。
• 失败分流：停止在生产输入门禁，未出现“门禁失败但继续推进”。后续必须在同一受控执行环境注入输入后，从 target gate 重新开始。

Input Traceback Evidence (2026-08-08)

• 当前 OPS7 运维交接 Runbook 仍提供公网 origin 作为只读检查基准；它没有提供生产数据库名或 SSH 身份。
• 仓库外的三份验收 env 文件仍存在且为受控用户、0600 权限；它们只包含 live smoke、SMTP 或一次性账号键，不包含生产部署身份/数据库输入，未被本 task 读取或 source。
• Git 历史没有 deploy/trialrun/.env、deploy.env 或上述验收 env 文件的删除记录；.gitignore 从始终将 .env 排除在版本库之外。
• shell 历史没有五个部署变量的字面赋值记录。结论：部署输入不是被本 task 删除，而是按运维合同设计为每次执行时临时注入。

Planning Revision Evidence (2026-08-08)

• 历史提交 34181e3 的旧 deploy.sh 确有默认部署 target/目录，但当时尚未显式设置 Compose project；5e2d03893826 首次冻结 project 且沿用同一远端目录。两份证据共同证明该遗留命名与公网 origin 属于同一唯一运行环境，不能因 trialrun 字样单独拒绝。
• 现行 gate 尚未对 DEPLOY_SERVER、REMOTE_DIR、COMPOSE_PROJECT_NAME 与独立预期身份做精确对账；本节修订只允许先改部署/QA tooling，不改业务代码或生产数据。
• 修订后的第一条远端动作仍是只读身份 bootstrap；数据库名读取排在 exact identity 匹配之后，任何 bootstrap 或 target gate FAIL 都不得继续。

Read-only Identity Bootstrap Evidence (2026-08-08)

• tooling 提交 f11e2f2 已进入 origin/main；执行前 provenance 为 published=true、remoteVerified=true，工作区 clean。
• 使用 PRODUCTION_READ_ONLY_PREFLIGHT=1 启动只读身份引导。历史 target/目录与首次显式 project 记录解析成功；refresh forced-command probe 恰好一个候选精确 PASS，候选身份未回显。
• systemd deployment contract 读取成功且六项结构校验通过，但当前 REMOTE_DIR 与已批准历史精确基线不一致；稳定停止码为 SYSTEMD_REMOTE_DIR_MISMATCH。
• 门禁在数据库身份引导前停止：未读取或生成 POSTGRES_DB 比较基线，未运行 13 项聚合体检、target gate、prisma migrate status、_prisma_migrations 对账或 terminated 行数查询，因此 rollback window 仍为 UNKNOWN，不得推断 OPEN/CLOSED。
• 未调用 deploy-existing.sh 的 preflight/deploy 阶段，未进入 deploy.sh、rsync、migrate deploy、应用切换、refresh 或公网 smoke；生产 schema 写入与业务写入均为 0。
• 失败后未改用当前 contract 自述覆盖历史预期、未跳过目录精确比较、未继续推进。后续必须先独立确认当前 contract 目录变更的来源与公网环境归属，再修订批准基线或恢复正确 contract。

Origin-first Identity Recalibration Evidence (2026-08-08)

• 修订提交 bf2631c 已进入 origin/main；执行前 provenance 为 published=true、remoteVerified=true，工作区 clean。
• Git 全历史复核确认 REMOTE_DIR="${REMOTE_DIR:-...}" 始终是可被运维显式输入覆盖的 fallback，未形成其曾在生产生效的证据；本轮不再把该默认值作为目录权威，也未修改线上 contract。
• 使用 PRODUCTION_IDENTITY_ONLY=1 重新执行：历史 SSH target 与首次显式 Compose project 基线解析成功，refresh forced-command probe 仍恰好一个候选精确 PASS，systemd contract 六项结构和 contract-relative env/Compose 约束通过。
• 远端 .env 的 APP_ORIGIN 与运行中 server 容器的 APP_ORIGIN 分别独立取样，二者均与 OPS7 当前 HTTPS 公网基准精确匹配；稳定结果为 origin_verified_remote_dir_baseline=systemd_contract。
• 只有上述 origin 双取样通过后，当前 systemd contract 的 REMOTE_DIR 才被冻结为本进程 EXPECTED_REMOTE_DIR；目录字面值未回显、未写入 task、日志或证据文件。
• identity-only 在目录基线冻结后立即退出：未读取 POSTGRES_DB、未生成 DB hash、未运行 13 项聚合体检、target gate、prisma migrate status、迁移表对账或 terminated 行数查询，rollback window 仍为 UNKNOWN。
• 未调用 deploy-existing.sh、deploy.sh、rsync、migrate deploy、应用切换、refresh 或公网 smoke；生产 schema 写入与业务写入均为 0。进入数据库身份和 pre-status 前仍需用户复核本节证据。

Read-only Pre-status Attempt Evidence (2026-08-08)

• 责任边界记录提交 bf23664 已进入 origin/main；执行前 provenance 为 published=true、remoteVerified=true，工作区 clean。
• 使用 PRODUCTION_READ_ONLY_PREFLIGHT=1 执行。历史 target/project、refresh exact probe、origin 双取样、contract 目录冻结和远端 DB hash 引导通过，稳定输出 exact_identity_group；数据库名、目标、路径均未回显。
• check-existing-deployment.sh 的 13 项全部真实 PASS：PASS=13 FAIL=0，包括部署身份、六项 contract、仓库/环境/数据目录、唯一 runtime、build、storage/PGDATA mount、backup build 和 refresh program。
• production preflight 在 Prisma status marker 产生前停止，外层稳定码为 PRISMA_STATUS_OUTPUT_MISSING；脱敏 preflight-output.txt 为空，未生成 prisma-migrate-status.txt。因此没有可审查的 status 原文，不能判定 pending、applied、failed、diverged 或 schema up to date。
• 代码复核确认 production-preflight.mjs 先在 rawStatus == null 时抛 PRISMA_STATUS_OUTPUT_MISSING，之后才在 result.status !== 0 分支解析远端 stderr 安全码；本次真实远端停止码被该顺序遮蔽，不能从现存 evidence 恢复，也不得猜测。
• DB hash 引导成功只证明远端 .env 数据库名已形成比较基线，不证明后续 .env / current_database() / runtime DATABASE_URL 三方一致性；远端 preflight 未输出 target_identity_and_database_identity PASS，故该验收项保持未通过。
• 未获得 migration reconciliation、pending allowlist 对账或 terminated count；rollback window 仍为 UNKNOWN，不得写作 OPEN/CLOSED。
• PRODUCTION_READ_ONLY_PREFLIGHT=1 未进入 deploy.sh；未执行 rsync、migrate deploy、应用切换、contract refresh 或业务 API，生产 schema 写入与业务写入均为 0。失败后未重跑、未跳过门禁。

Pre-status Diagnostic Wrapper Repair Evidence (2026-08-08)

• 已确认外层 production-preflight.mjs 在远端非零退出且 Prisma marker 缺失时，先抛出 PRISMA_STATUS_OUTPUT_MISSING，遮蔽了远端 helper 已输出的稳定安全码；该结论来自源码顺序与既有脱敏 evidence，不反推或猜测真实远端原因。
• 最小修复保持稳定摘要与 reportRef 在失败判断前输出，并把远端非零退出判断提前：可解析 code=... 时传播原码，不可解析时固定失败为 PRODUCTION_PREFLIGHT_REMOTE_FAILED；只有远端退出 0 且 marker 缺失时才返回 PRISMA_STATUS_OUTPUT_MISSING。
• 聚焦回归覆盖四种组合：非零/有安全码/marker 缺失，非零/有安全码/marker 存在，非零/无可解析码/marker 缺失，以及退出 0/marker 缺失；deployment-safety-contract.test.js 为 19/19 PASS。
• 本地 Node/shell syntax、env contract、task validate、process contract、docs audit、Trellis governance、sensitive scan 与 git diff --check 均通过；docs audit 仅保留仓库既有的未注册文档 warning。
• 本节修复阶段未连接生产、未运行 target/status、未执行 rsync、migration、应用切换或业务 API；生产 schema 写入与业务写入仍为 0。候选提交进入上游且 provenance 重新通过后，才允许重跑只读 pre-status；取得真实远端错误码后必须立即停止并复核原因。

Read-only Candidate Compose Attempt Evidence (2026-08-08)

• 错误优先级修复提交 83af754 已进入 origin/main；执行前 provenance 为 published=true、remoteVerified=true，工作区 clean。
• 使用 PRODUCTION_READ_ONLY_PREFLIGHT=1 重跑：精确身份组通过，既有部署聚合体检仍为 PASS=13 FAIL=0；production preflight 在 Compose 配置校验处以真实稳定码 PROD_TARGET_COMPOSE_CONFIG_INVALID 停止，外层 DEPLOY_EXISTING_FAILED 只表示受控 wrapper 已停止。
• 源码核对确认 Compose 文件以 ${BUILD_SHA:?...} / ${VITE_BUILD_SHA:?...} 强制要求构建标识；正式 deploy.sh 从已验证 provenance 注入完整 commit 与 12 位短 commit，而只读 preflight 未注入两值，因此失败属于 preflight 候选配置输入缺口，不是生产配置漂移。
• 本次未生成 Prisma status marker 或脱敏 status 文件，未完成 .env / current_database() / runtime DATABASE_URL 三方一致性、pending 对账或 terminated count；rollback window 仍为 UNKNOWN。
• 失败后立即停止，未进入 deploy.sh、rsync、migrate deploy、应用切换、refresh 或业务 API；生产 schema 写入与业务写入均为 0。

Candidate Compose Contract Repair Evidence (2026-08-08)

• deploy-existing.sh 仍是候选来源唯一入口：它先运行 check-source-provenance.mjs，只在 published=true / remoteVerified=true 后把 source_commit 传为 CANDIDATE_COMMIT。production-preflight.mjs 已移除 git rev-parse HEAD fallback，候选缺失直接 fail-closed。
• preflight 仅从该候选派生 BUILD_SHA=<完整 commit> 与 VITE_BUILD_SHA=<前 12 位>，并传给远端 Compose；不使用 7 位 Git 默认短 hash。远端 helper 在 docker compose config 前校验完整/短 SHA 格式以及 VITE_BUILD_SHA === BUILD_SHA.slice(0, 12)。
• 此处 docker compose config 验证的是候选发布后将生效的配置，不代表当前运行容器已经使用该 build SHA；运行态仍须由后续只读 runtime/SHA 检查独立证明。禁止用 --no-interpolate 绕过 Compose 的必填变量合同。
• 聚焦测试保持 19/19 PASS，并新增候选完整/12 位注入、7 位短 SHA 拒绝、合法但不匹配 SHA 拒绝、禁止 HEAD fallback 的覆盖；Node/shell syntax 与 env contract PASS。

Empty-Allowlist Migration Discovery Evidence (2026-08-08)

• 候选配置修复提交 8b2ed5b 已进入 origin/main；执行前 provenance 为 published=true、remoteVerified=true，工作区 clean。
• 使用空 EXPECTED_PENDING_MIGRATIONS 重跑只读 pre-status：精确身份组、13 项聚合体检和 .env / current_database() / runtime DATABASE_URL 三方数据库身份均 PASS；脱敏 Prisma status 显示运行镜像包含 64 条 migration 且对自身为 Database schema is up to date!。
• 候选 manifest 包含 65 条 migration；独立候选清单与生产 _prisma_migrations 差集发现唯一 pending 为 20260807193000_contract_registry_termination_workspace，因此稳定停止码为 PROD_MIGRATION_PENDING_ALLOWLIST_MISMATCH。这证明运行镜像 status 不能替代候选差集门禁。
• 该 migration SQL 已复核为三个可空列、一个索引和一个 ON DELETE RESTRICT 外键，无 drop/truncate/delete 或数据改写；用户已明确批准把它加入下一次只读 pre-status 的 allowlist。
• 空 allowlist 停止发生在窗口查询前，故 terminated count 未读取、rollback window 仍为 UNKNOWN；未进入 deploy.sh、rsync、migration、应用切换、refresh 或业务 API，生产 schema 写入与业务写入均为 0。

Explicit Rollback-window Basis Repair Evidence (2026-08-08)

• termination migration 尚未应用时，终止能力不可能由本轮应用生效；helper 现以 _prisma_migrations applied set 走显式分支，不发送 contract_registry 状态查询，固定输出 rollbackWindow=OPEN terminatedRows=0 basis=migration_not_applied。
• migration 已应用时继续执行真实 status = 'terminated' 计数，输出 basis=terminated_status_count；查询失败或结果不可解析分别返回固定错误，不使用 catch/default 把未知状态误报为 OPEN。
• 聚焦 fixture 覆盖：未应用且状态查询被设置为必失败仍应 OPEN（证明未查询）、已应用 0 行 OPEN、已应用 2 行 CLOSED，以及已应用查询失败必须 PROD_TERMINATED_COUNT_UNAVAILABLE。聚焦测试 19/19 PASS。

First Production Deployment Attempt Evidence (2026-08-08)

• 窗口依据修复提交 b94afcf 已进入 origin/main；发布前 preflight 再次通过：精确身份组、13 项聚合体检、数据库三方身份、唯一 pending allowlist 和 rollbackWindow=OPEN ... basis=migration_not_applied 全部 PASS。
• 唯一生产入口随后完成已验证源码同步并进入远端 build init；编排进程在该长阶段退出，未到 run init。代码顺序固定为先 build init、后 prisma:migrate:deploy，只读复核同时证明 termination migration 仍 pending、公开 /ready 仍为旧 build、新 init 镜像仍为旧 build，故 schema 写入和应用切换均为 0。
• 同一候选在本地 client typecheck/build PASS；远端当时仍有可用磁盘和内存，未取得明确 OOM 证据，不能把环境猜测写成根因。原裸调用只把输出写入 SSH 流，通道证据不完整，未能恢复真实末尾错误。
• 失败后未重试部署、未运行 reset/resolve/drop、未改生产配置。额外只读检查确认现有 13 项合同仍健康、回滚窗口仍 OPEN；用户随后只批准一次在远端持久化日志机制落地后的受控重试。

Persistent Remote Stage Log Repair Evidence (2026-08-08)

• deploy.sh 为 build-init、run-init 和 build-switch-server 三个长阶段统一增加远端日志包装器；完整 stdout/stderr 直接写入仓库相对 artifacts/deployment-runtime/，目录 0700、文件 0600，文件名只含固定阶段名和已验证候选 12 位 SHA。
• 普通输出仅记录 stage、真实 child exit code 和相对 logRef。失败状态在 Bash else 分支中立即捕获并返回，随后由 set -e 停止，不会因 fi 后读取 $? 而丢失原码。
• 原始 build/init 日志不写入 Git、task 或普通对话；若受控重试失败，先只读取对应远端日志尾部并脱敏定性，再决定后续动作。任何下一次 rsync 可能清除旧 runtime artifacts，因此读取必须发生在重试之前。
• 聚焦静态回归证明三个裸调用均已替换、重定向和权限合同存在、失败分支立即捕获退出码；shell syntax、env contract 与部署安全测试 PASS。