diff --git a/deploy/nginx/README.md b/deploy/nginx/README.md
index 4a1bd5700..98cddbc0d 100644
--- a/deploy/nginx/README.md
+++ b/deploy/nginx/README.md
@@ -46,18 +46,20 @@
 - Pingora 网关默认仍只监听本机 shadow 端口，不绑定公网 `80/443`。
 - 需要评估直连入口时，显式配置 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` 和 `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE`；网关只读取现有证书文件，不负责 Certbot / ACME 自动续期。
 - 需要 HTTP 到 HTTPS 跳转时，再显式配置 `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`；该入口除 `/.well-known/acme-challenge/*` 外统一 301 到 HTTPS，ACME challenge 仍从 `GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT` 精确读取。
-- API release 必须把 `api-server.sha256`、可选 `pingora-gateway.sha256`、`scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-live.mjs`、`scripts/check-pingora-canary-access-log-parity.mjs`、`scripts/ops/pingora-current-release-audit.mjs`、`scripts/ops/pingora-direct-rehearsal-status.mjs`、`scripts/ops/pingora-cutover-status-snapshot.mjs`、`scripts/ops/pingora-cutover-evidence-bundle.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/check-production-health-patrol-env.mjs`、`scripts/deploy/pingora-health-patrol-env-switch.mjs`、`scripts/deploy/pingora-tls-cert-sync.mjs`、`deploy/systemd/`、`deploy/env/` 和 `deploy/pingora/` 一起复制到 `/opt/genarrative/current`；current release 自审、直连彩排状态、直连启用、health patrol env 切换、TLS 证书同步、canary live、access log 对账、cutover 状态快照和证据包脚本都从 current release 推导依赖路径，切换窗口不得依赖 Jenkins 工作区或目标机源码 checkout。
+- 同一公网 IP 上还承载 `git.genarrative.world` 时，直连前必须配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world` 与 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000`，让命中 Gitea Host 的请求整站转发到 Gitea；该路由不走应用维护页、API body limit 或网关接流保护，避免影响 git clone / push。当前 Pingora TLS listener 只加载一组 cert/key；如果直连 443 同时服务 `dev.genarrative.world` 和 `git.genarrative.world`，证书必须同时覆盖两个域名，不能使用只有单域名 SAN 的证书。
+- API release 必须把 `api-server.sha256`、可选 `pingora-gateway.sha256`、`scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-live.mjs`、`scripts/check-pingora-canary-access-log-parity.mjs`、`scripts/ops/pingora-current-release-audit.mjs`、`scripts/ops/pingora-direct-rehearsal-status.mjs`、`scripts/ops/pingora-cutover-status-snapshot.mjs`、`scripts/ops/pingora-cutover-evidence-bundle.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/check-production-health-patrol-env.mjs`、`scripts/deploy/pingora-health-patrol-env-switch.mjs`、`scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`scripts/deploy/pingora-tls-cert-sync.mjs`、`deploy/systemd/`、`deploy/env/` 和 `deploy/pingora/` 一起复制到 `/opt/genarrative/current`；current release 自审、直连彩排状态、直连启用、health patrol env 切换、Pingora gateway env shadow 切换、TLS 证书同步、canary live、access log 对账、cutover 状态快照和证据包脚本都从 current release 推导依赖路径，切换窗口不得依赖 Jenkins 工作区或目标机源码 checkout。
 - 目标机如果使用 Certbot / Let’s Encrypt 证书，不要直接放宽 `/etc/letsencrypt/live` 或 `archive` 的目录 / 私钥权限。先用随包脚本把 root 可读的 live symlink 解析并复制到 Pingora 私有目录，例如 `sudo -n node -- /opt/genarrative/current/scripts/deploy/pingora-tls-cert-sync.mjs --apply --source-cert-file /etc/letsencrypt/live/<域名>/fullchain.pem --source-key-file /etc/letsencrypt/live/<域名>/privkey.pem --target-dir /etc/genarrative/pingora-tls/<域名>`；脚本默认 dry-run，`--apply` 才原子写入 `fullchain.pem` / `privkey.pem`，目标目录默认 `root:genarrative 0750`，文件默认 `root:genarrative 0640`，并复核 `genarrative` 服务用户可读。随后把 `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE` 指向 `/etc/genarrative/pingora-tls/<域名>/` 下的副本。
 - 默认 systemd service 以 `genarrative` 非 root 用户运行，不具备绑定 `80/443` 的能力。Server-Provision 只安装 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 作为人工启用模板；切直连低端口时必须先确认 `genarrative` 可读证书文件、Nginx 已释放 `80/443`，再执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；脚本会先执行随包 current release 自审，确认 `pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release，失败时不会安装 drop-in。自审通过后才安装 drop-in、`systemctl daemon-reload` 并重启 Pingora；脚本会用 `systemctl cat` 确认 `CAP_NET_BIND_SERVICE` drop-in 已进入 systemd 最终配置，用 `systemctl show ... ExecStart` 确认最终 service 指向随包主 service 模板中的 current release `pingora-gateway`，用 `systemctl is-active` 确认 Pingora active，并执行 direct live smoke，强制覆盖 HTTPS / HTTP redirect / ACME / WSS 101 和 Pingora access log request_id 落盘。
 - `npm run check:pingora-gateway-smoke` 会用临时自签证书覆盖 TLS 直连、HTTP redirect 和 WSS subscribe 行为；正式公网切换前仍必须先走 Nginx canary 和 release readiness 门禁。
-- 目标机直连入口启用后先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再运行 `npm run check:pingora-direct-live`，检查 HTTPS 根路径、HTTP/2 ALPN、代表性 API、SpacetimeDB identity、WSS subscribe 握手、generated 拒绝、公开 `/healthz` 拒绝、可选 shadow probe，以及 HTTP 301 / ACME challenge；真实 SpacetimeDB 对 `GET /v1/identity` 返回 `405 Method Not Allowed` 属于可接受语义，direct live 只把它作为路径转发代表，不要求该 GET 创建 identity；release readiness 可用 `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free` 强制纳入同一条门禁，漏掉 direct HTTP base URL、正式域名 Host/SNI、redirect Location host、目标 SpacetimeDB 库、Pingora access log request_id 落盘、health patrol env direct 模式复核、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户 / systemd 服务用户证书可读检查、service 二进制可执行检查或 80/443 端口释放检查都会直接失败。高端口 rehearsal 如果通过 `https://127.0.0.1:18443` 打入、但 Pingora 应返回正式域名默认 HTTPS Location，可额外传 `--direct-redirect-base-url https://<域名>`；`--direct-redirect-host` 仍必须保留，用于直连切换 Host 一致性约束。
+- 目标机直连入口启用前先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，证明 TLS 文件、service env、current release 二进制和低端口释放都满足切流条件；启用后再运行 `npm run check:pingora-direct-live`，检查 HTTPS 根路径、HTTP/2 ALPN、代表性 API、SpacetimeDB identity、WSS subscribe 握手、generated 拒绝、公开 `/healthz` 拒绝、可选 shadow probe，以及 HTTP 301 / ACME challenge；真实 SpacetimeDB 对 `GET /v1/identity` 返回 `405 Method Not Allowed` 属于可接受语义，direct live 只把它作为路径转发代表，不要求该 GET 创建 identity；release readiness 可用 `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable` 强制纳入同一条启用后门禁，漏掉 direct HTTP base URL、正式域名 Host/SNI、redirect Location host、目标 SpacetimeDB 库、Pingora access log request_id 落盘、health patrol env direct 模式复核、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户 / systemd 服务用户证书可读检查或 service 二进制可执行检查都会直接失败；启用后 `--require-direct` 复核不再要求端口空闲，因为此时 `80/443` 应由 Pingora 占用。高端口 rehearsal 如果通过 `https://127.0.0.1:18443` 打入、但 Pingora 应返回正式域名默认 HTTPS Location，可额外传 `--direct-redirect-base-url https://<域名>`；`--direct-redirect-host` 仍必须保留，用于直连切换 Host 一致性约束。
 - direct live 在 HTTPS 根路径返回 `200` 且 HTML 中发现 `/assets/` 或 `/admin/assets/` 引用时，会自动请求该静态资源，确认 `Cache-Control`、`ETag`、`Last-Modified`、`Accept-Ranges: bytes`、`HEAD` 头响应、`If-None-Match` / `If-Modified-Since` 的 `304` 响应和 `Range: bytes=0-0` 的 `206 + Content-Range` 响应，并纳入 Pingora access log method/path/status 对账；若首页引用 Vite 指纹资源，还会额外确认 `Cache-Control: public, max-age=31536000, immutable` 以及指纹资源 GET / HEAD / 304 / Range access log 证据。维护模式、非 HTML 或发布包首页没有资产引用时该项标记为 skipped，不阻断维护窗口。
-- 直连启用前先 dry-run `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status`；验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名> --nginx-smoke-expect-body '"ok":true'`，脚本会先运行 `nginx -t`，通过后移除 direct-entry drop-in、重启 Pingora，用 `systemctl cat` 确认 `CAP_NET_BIND_SERVICE` 已从 systemd 最终配置中移除，用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，并 reload Nginx、确认 Nginx service 仍为 `active`，最后用 smoke URL 证明 Nginx 入口真实可访问；传入 `--nginx-smoke-expect-body` 时还会要求响应体包含该片段。仓库工作区可用 `npm run deploy:pingora-direct-enable -- --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log` 和 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名> --nginx-smoke-expect-body '"ok":true'`。两个脚本默认 dry-run；启用脚本 `--apply` 必须先通过 current release 自审，并带 env、证书可读、service EnvironmentFile 一致性、服务用户证书可读、service 二进制可执行、端口释放预检、direct live 参数和 Pingora access log 参数，回退脚本 `--apply` 必须带 `--reload-nginx` 和 `--nginx-smoke-url`；如果 health patrol env 已预先切回 Nginx，也可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 让回退脚本在 Nginx smoke 后复核 `gateway mode=nginx` 且 public base URL / Host 已恢复，若切换前 Nginx 巡检本来需要 Host 覆盖，则把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`；如果还要同时证明 shadow 高端口仍健康，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应包含 `gateway=pingora-shadow`。本机 `npm run check:pingora-direct-enable` / `npm run check:pingora-direct-rollback` 会验证 dry-run 不会安装或删除临时 drop-in、current release 自审失败时启用脚本不会安装 drop-in，并展示启用 / 回退后的 systemd 最终配置核验、ExecStart 指向核验、Pingora active 核验、direct live smoke、Nginx 语法检查、reload 状态核验、Nginx smoke 及响应体片段核验、可选 health patrol env 复核和可选 shadow probe 复核。
+- 直连启用前先 dry-run `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status`；验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`，脚本会先运行 `nginx -t`，通过后移除 direct-entry drop-in、重启 Pingora，用 `systemctl cat` 确认 `CAP_NET_BIND_SERVICE` 已从 systemd 最终配置中移除，用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，并 reload Nginx、确认 Nginx service 仍为 `active`，最后用 smoke URL 证明 Nginx 入口真实可访问；传入 `--nginx-smoke-expect-body` 时还会要求响应体包含该片段。回退 smoke 的 URL 与 body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`；若 smoke URL 打本机地址，再显式追加 `--nginx-smoke-host <域名>` 避免命中默认 vhost。仓库工作区可用 `npm run deploy:pingora-direct-enable -- --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log` 和 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`。两个脚本默认 dry-run；启用脚本 `--apply` 必须先通过 current release 自审，并带 env、证书可读、service EnvironmentFile 一致性、服务用户证书可读、service 二进制可执行、端口释放预检、direct live 参数和 Pingora access log 参数，回退脚本 `--apply` 必须带 `--reload-nginx` 和 `--nginx-smoke-url`；如果 health patrol env 已预先切回 Nginx，也可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 让回退脚本在 Nginx smoke 后复核 `gateway mode=nginx` 且 public base URL / Host 已恢复，若切换前 Nginx 巡检本来需要 Host 覆盖，则把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`；如果还要同时证明 shadow 高端口仍健康，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应包含 `gateway=pingora-shadow`。本机 `npm run check:pingora-direct-enable` / `npm run check:pingora-direct-rollback` 会验证 dry-run 不会安装或删除临时 drop-in、current release 自审失败时启用脚本不会安装 drop-in，并展示启用 / 回退后的 systemd 最终配置核验、ExecStart 指向核验、Pingora active 核验、direct live smoke、Nginx 语法检查、reload 状态核验、Nginx smoke 及响应体片段核验、可选 health patrol env 复核和可选 shadow probe 复核。
+- rollback apply 前必须先执行 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env`，把 active Pingora env 恢复为 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081`，并清空 `TLS_LISTEN`、`HTTP_REDIRECT_LISTEN`、`TLS_CERT_FILE` 和 `TLS_KEY_FILE`；只移除 systemd direct-entry drop-in 而不恢复 env，会让回退后的 Pingora shadow 继续按 direct 低端口或半 TLS 配置启动。
 - `npm run check:pingora-current-release-audit` 会烟测 current release 自审脚本；正式直连 runbook 会先执行 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show`，只读确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 匹配、`release-manifest.api-server.json` 已登记 `pingora-gateway`、`pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release。
-- `npm run check:pingora-cutover-status-snapshot` 会烟测状态快照脚本，`npm run check:pingora-cutover-evidence-bundle` 会烟测证据包脚本；正式切换窗口与 release readiness 使用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 归档切换前 / 启用后 / 回退后三个阶段的 `manifest.json`、`snapshot.json`、stdout / stderr 和命令记录。直连 runbook 的三个证据包阶段都会向状态快照透传 `--require-pingora-gateway`，在 `checks.current-release-audit` 中保存 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果；启用后证据包还会通过 `--run-direct-live` 保存 `direct-live.json`、direct live stdout / stderr、命令记录、Pingora access log `request_id` 反查结果，以及静态响应头白名单证据。`manifest.summary.directLiveAccessLog` 会提升 checked / matched / missing / mismatch 对账摘要，`manifest.summary.directLiveStaticHeaders` 会提升普通静态和 Vite 指纹静态的缓存头、校验头、Range `Content-Range` 和 304 状态摘要，便于值班人员不打开 `direct-live.json` 也能先判断证据是否完整；如果 direct live 已输出静态资产结果但摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 或 Last-Modified 304 证据，证据包会记为 `CRITICAL`。最终总审计还会带 `--require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable`，防止缺少 access log 对账摘要或静态头摘要的旧启用后证据包混入正式归档。快照脚本只读采集状态，证据包脚本只写指定证据目录，不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora。
+- `npm run check:pingora-cutover-status-snapshot` 会烟测状态快照脚本，`npm run check:pingora-cutover-evidence-bundle` 会烟测证据包脚本；正式切换窗口与 release readiness 使用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 归档切换前 / 启用后 / 回退后三个阶段的 `manifest.json`、`snapshot.json`、stdout / stderr 和命令记录。直连 runbook 的三个证据包阶段都会向状态快照透传 `--require-pingora-gateway`，在 `checks.current-release-audit` 中保存 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果；启用后证据包还会通过 `--run-direct-live` 保存 `direct-live.json`、direct live stdout / stderr、命令记录、Pingora access log `request_id` 反查结果，以及静态响应头白名单证据。`post-enable` 证据包必须传 `--expected-pingora-env-mode direct`，`post-rollback` 证据包必须传 `--expected-pingora-env-mode shadow`。`manifest.summary.directLiveAccessLog` 会提升 checked / matched / missing / mismatch 对账摘要，`manifest.summary.directLiveStaticHeaders` 会提升普通静态和 Vite 指纹静态的缓存头、校验头、Range `Content-Range` 和 304 状态摘要，`manifest.summary.pingoraEnvShadow` 会提升 `listen`、`tlsListen`、`httpRedirectListen`、`tlsCertFile`、`tlsKeyFile`、`mode` 和 `shadowReady`，便于值班人员不打开 `direct-live.json` 或 `snapshot.json` 也能先判断证据是否完整；如果 direct live 已输出静态资产结果但摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 或 Last-Modified 304 证据，证据包会记为 `CRITICAL`。最终总审计还会带 `--require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-phase-pingora-env-shadow post-rollback`，防止缺少 access log 对账摘要、静态头摘要或回退后 shadow env 摘要的旧证据包混入正式归档。快照脚本只读采集状态，证据包脚本只写指定证据目录，不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora。
 - 最终证据根目录总审计 JSON 先看 `summary.status`、`summary.failedItems[]` 和 `summary.directLiveEvidence[]`：失败时这里会直接指出阶段 / 命令 / 根目录问题，以及 `post-enable` access log 或静态头摘要的短 reason；`phases[]`、`commands[]` 和 `timeline` 继续作为完整机器归档。
-- 最终证据根目录总审计必须同时带 `--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 和 `--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，避免只证明有命令证据，却没有证明真实执行的是 current release 随包 enable / rollback 脚本。
-- `npm run check:production-api-release` 会动态生成 API release，并检查发布包 README 与随包 `scripts/check-pingora-release-readiness.mjs --dry-run-cutover` 输出的最终总审计步骤都保留上述两条 `--require-command-executable` 要求，避免源码文档正确但发布包操作口径漂移。
+- 最终证据根目录总审计必须同时带五条 `--require-command-executable`：`enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs` 和 `rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，避免只证明有命令证据，却没有证明真实执行的是 current release 随包切换脚本。
+- `npm run check:production-api-release` 会动态生成 API release，并检查发布包 README 与随包 `scripts/check-pingora-release-readiness.mjs --dry-run-cutover` 输出的最终总审计步骤都保留上述五条 `--require-command-executable` 要求，避免源码文档正确但发布包操作口径漂移。
 - 直连接管后用 `node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply --env-file /etc/genarrative/health-patrol.env --gateway-mode pingora-direct --public-base-url <直连HTTPS入口> --public-host <域名>` 切换 health patrol env；该脚本只改 gateway mode、public base URL 和 public Host，并先用临时目标 env 调用随包 `check-production-health-patrol-env.mjs` 复核，复核通过后才原子替换真实 env，复核失败不会落盘。回退到 Nginx 前用同一脚本改回 `--gateway-mode nginx --public-base-url <切换前Nginx巡检入口>`，若切换前 Nginx 巡检不需要 Host 覆盖则传 `--clear-public-host`，需要 Host 覆盖则传 `--public-host <切换前Host>`；随后 rollback 脚本和独立 env 复核会再次阻断 public base URL / Host 漂移。`plan:pingora-direct-cutover` 会在 JSON runbook 中列出 direct / nginx 两个方向的 env 切换脚本和 env 复核步骤，并先输出 Host 与回退巡检入口确认；正式切换 runbook 会拒绝 `--direct-redirect-host` 或 `--rollback-nginx-smoke-host` 与 `--direct-host` 使用不同 hostname，且必须提供 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退计划把现场巡检入口覆盖成仓库默认值。若切换计划希望回退后同时证明 Pingora shadow 高端口仍健康，可给 runbook 追加 `--rollback-pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --rollback-pingora-shadow-probe-token <token>`；JSON 输出会隐藏 token 原文，并把对应参数传给 rollback dry-run / apply 步骤。
 
 ## Pingora canary
@@ -71,8 +73,8 @@
 - 真实路径 canary 不再手工编辑 `/etc/nginx/conf.d/`。目标机从 current release 执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083`；脚本会渲染到 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`，保持晚于主站 `log_format genarrative_upstream` 加载，执行 `nginx -t`、reload Nginx，并默认运行 realpath live smoke。`nginx -t`、reload 或 live smoke 任一失败都会恢复写入前配置。关闭时执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply`，脚本会删除该 `zz-...` 文件，执行 `nginx -t` 和 reload，失败时恢复删除前配置。
 - `npm run check:pingora-release-readiness` 默认包含 `npm run check:pingora-realpath-canary-toggle`，用临时 Nginx 目录和 fake `nginx` / `systemctl` / live smoke 验证 realpath canary 启停脚本默认 dry-run、apply 写入、失败回滚和 disable 恢复逻辑；不再把这条脚本护栏留成单独可选项。
 - 真实路径 canary reload 后可再次运行 `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host <域名>`，再运行 `node -- /opt/genarrative/current/scripts/check-pingora-canary-access-log-parity.mjs --realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_realpath_canary/healthz --path /api/creation-entry/config --path /v1/identity --path /assets/app.js`。真实路径模式除 healthz 探针外要求 Nginx path 与 Pingora path 完全一致。
-- 正式切换前在源码 checkout / CI / 构建环境跑 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；启用真实路径 canary 时追加 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。
-- 目标机 `/opt/genarrative/current` 只能跑随包 runtime-only 门禁：`/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；验证真实路径 canary 或 Pingora 直连入口时分别追加 `--require-realpath-live ...` 或 `--require-direct ...` 参数。未带 `--require-direct` 的 runtime-only 基础门禁会自动执行直连彩排状态复核，确认公网 `80/443` 仍由 Nginx 接流、Pingora shadow `127.0.0.1:18081`、realpath canary `127.0.0.1:18083` 和 current release 自审均通过；启用后 `--require-direct` 复核不再要求 Nginx 接公网彩排状态。生成正式直连切换 runbook 时，`--direct-redirect-host` 和回退 smoke Host 必须与 `--direct-host` 同 hostname，只允许端口不同。
+- 正式切换前在源码 checkout / CI / 构建环境跑聚合门禁，并按目标机已启用的 canary 入口选择参数：前缀 canary 已启用时使用 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；真实路径 canary 已启用时追加或单独使用 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。如果现场只启用了真实路径 canary，不要同时传 `--require-live`。
+- 目标机 `/opt/genarrative/current` 只能跑随包 runtime-only 门禁，并同样按现场已启用入口选择：前缀 canary 用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；真实路径 canary 用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；验证 Pingora 直连入口时再追加 `--require-direct ...` 参数。未带 `--require-direct` 的 runtime-only 基础门禁会自动执行直连彩排状态复核，确认公网 `80/443` 仍由 Nginx 接流、Pingora shadow `127.0.0.1:18081`、realpath canary `127.0.0.1:18083` 和 current release 自审均通过；启用后 `--require-direct` 复核不再要求 Nginx 接公网彩排状态。生成正式直连切换 runbook 时，`--direct-redirect-host` 和回退 smoke Host 必须与 `--direct-host` 同 hostname，只允许端口不同。
 
 ## 验证
 
diff --git a/deploy/pingora/pingora-gateway.env.example b/deploy/pingora/pingora-gateway.env.example
index 1c69ad8cf..67b1bc3ff 100644
--- a/deploy/pingora/pingora-gateway.env.example
+++ b/deploy/pingora/pingora-gateway.env.example
@@ -16,6 +16,11 @@ GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081
 # GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_TARGET_SCHEME=https
 GENARRATIVE_PINGORA_GATEWAY_API_UPSTREAM=127.0.0.1:8082
 GENARRATIVE_PINGORA_GATEWAY_SPACETIME_UPSTREAM=127.0.0.1:3101
+# 可选：同一公网 IP 上还承载 Gitea 时，按 Host 整站转发到 Gitea。
+# 命中这些 Host 的请求不走应用维护页、API body limit 或网关接流保护，避免影响 git clone / push。
+# 直连 443 如果要同时服务这些域名，当前单 listener TLS 配置必须使用覆盖全部 Host 的同一张证书。
+# GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world
+# GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000
 
 GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT=/srv/genarrative/web
 GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT=/var/www/html
diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 4591282bc..1fa9243e6 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -19,10 +19,11 @@
 ## 2026-06-13 Pingora 低端口直连只通过显式 systemd drop-in 启用
 
 - 背景：`genarrative-pingora-gateway.service` 默认以 `genarrative` 非 root 用户运行，shadow 阶段只监听本机高端口；如果正式评估让 Pingora 直接绑定公网 `80/443`，需要低端口绑定能力，但不能让 Server-Provision 或默认 service 自动改变接流边界。
-- 决策：主 systemd service 保持 shadow 口径，不携带 `CAP_NET_BIND_SERVICE`。仓库提供 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf` 作为人工启用 drop-in 模板，Server-Provision 只安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 备查和手动覆盖；正式切换窗口从 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 执行时默认读取 current release 随包的 `/opt/genarrative/current/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，不依赖 `/etc` 参考模板、Jenkins 工作区或源码 checkout。直连切换前先用 `npm run plan:pingora-direct-cutover -- --require-direct ...` 生成 JSON runbook，逐条审阅 Host 与回退巡检入口确认、current release preflight、启用前基础门禁、direct enable dry-run、direct enable apply（通过命令证据脚本归档 stdout / stderr / 退出码）、切换后 health patrol 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后 `--require-direct` 复核、rollback dry-run、rollback apply（通过命令证据脚本归档 stdout / stderr / 退出码）、回退后 health patrol 切回 `nginx` 并恢复切换前 public base URL / Host、回退后 health patrol env Nginx 模式复核；启用前基础门禁不带 `--require-direct`，因为 systemd drop-in 尚未生效，启用后复核必须带 `--require-direct`。正式切换 runbook 中 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同，避免 redirect 和回退 smoke 分别验证到不同入口；还必须显式传 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，切换前 Nginx 巡检需要 Host 覆盖时再传 `--rollback-health-patrol-public-host <切换前Host>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退 runbook 覆盖现场原有巡检入口。若需把回退后 Pingora shadow 探针复核纳入 runbook，追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，JSON 输出会隐藏 token 原文并把参数传给 rollback dry-run / apply。只有切换窗口通过 `pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名>` 先跑 current release 自审，确认发布包自包含、`pingora-gateway` 可执行且 systemd `ExecStart` 指向随包网关，失败时不安装 drop-in；随后跑 direct preflight，确认当前执行用户和 `genarrative-pingora-gateway.service` 的 `User=` 服务用户都可读取证书链 / 私钥，确认 service 模板与 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含本次 `/etc/genarrative/pingora-gateway.env`，并确认 service `ExecStart=` 指向的 current release `pingora-gateway` 存在且可执行，再安装到 `/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf`、执行 `systemctl daemon-reload`、重启 Pingora，并用 `systemctl cat` 核验 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已生效、用 `systemctl is-active` 确认服务 active、用 direct live smoke 验证 HTTPS / HTTP redirect / ACME / WSS 101 后，才视为授予低端口能力成功。启用前还必须显式配置 TLS / redirect env 和真实证书，并确认 current release 已落盘可执行 `pingora-gateway`、Nginx 或其它进程已释放 `80/443`；启用后仍必须跑 release readiness 门禁；验证失败时统一执行 `pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名>` 回到 shadow / Nginx 入口，回退脚本会先运行 `nginx -t`，通过后移除 direct-entry drop-in、重启 Pingora，再用 `systemctl cat` 确认两条低端口 capability 均已从最终 unit 配置中移除，用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，并 reload Nginx、确认 Nginx service 仍为 `active`，最后用 curl smoke URL 证明 Nginx 入口真实可访问。回退脚本 `--apply` 必须同时带 `--reload-nginx` 和 `--nginx-smoke-url`，避免只撤掉 Pingora 低端口能力却没有证明 Nginx 已重新接流；本机打 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 必须带 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免命中默认 vhost。回退后必须复核 health patrol env 已切回 `nginx` 且 public base URL / Host 恢复为切换前记录值；如果 env 已预先修正，rollback 脚本可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 自动执行这项复核，切换前 Nginx 巡检需要 Host 覆盖时把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`。若需证明 Pingora 仍以 shadow 高端口存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应包含 `gateway=pingora-shadow`。
+- 决策：主 systemd service 保持 shadow 口径，不携带 `CAP_NET_BIND_SERVICE`。仓库提供 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf` 作为人工启用 drop-in 模板，Server-Provision 只安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 备查和手动覆盖；正式切换窗口从 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 执行时默认读取 current release 随包的 `/opt/genarrative/current/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，不依赖 `/etc` 参考模板、Jenkins 工作区或源码 checkout。直连切换前先用 `npm run plan:pingora-direct-cutover -- --require-direct ...` 生成 JSON runbook，逐条审阅 Host 与回退巡检入口确认、current release preflight、启用前基础门禁、direct enable dry-run、direct enable apply（通过命令证据脚本归档 stdout / stderr / 退出码）、切换后 health patrol 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后 `--require-direct` 复核、rollback dry-run、rollback apply（通过命令证据脚本归档 stdout / stderr / 退出码）、回退后 health patrol 切回 `nginx` 并恢复切换前 public base URL / Host、回退后 health patrol env Nginx 模式复核；启用前基础门禁不带 `--require-direct`，因为 systemd drop-in 尚未生效，启用后复核必须带 `--require-direct`。正式切换 runbook 中 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同，避免 redirect 和回退 smoke 分别验证到不同入口；还必须显式传 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，切换前 Nginx 巡检需要 Host 覆盖时再传 `--rollback-health-patrol-public-host <切换前Host>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退 runbook 覆盖现场原有巡检入口。若需把回退后 Pingora shadow 探针复核纳入 runbook，追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，JSON 输出会隐藏 token 原文并把参数传给 rollback dry-run / apply。只有切换窗口通过 `pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名>` 先跑 current release 自审，确认发布包自包含、`pingora-gateway` 可执行且 systemd `ExecStart` 指向随包网关，失败时不安装 drop-in；随后跑 direct preflight，确认当前执行用户和 `genarrative-pingora-gateway.service` 的 `User=` 服务用户都可读取证书链 / 私钥，确认 service 模板与 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含本次 `/etc/genarrative/pingora-gateway.env`，并确认 service `ExecStart=` 指向的 current release `pingora-gateway` 存在且可执行，再安装到 `/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf`、执行 `systemctl daemon-reload`、重启 Pingora，并用 `systemctl cat` 核验 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已生效、用 `systemctl is-active` 确认服务 active、用 direct live smoke 验证 HTTPS / HTTP redirect / ACME / WSS 101 后，才视为授予低端口能力成功。启用前还必须显式配置 TLS / redirect env 和真实证书，并确认 current release 已落盘可执行 `pingora-gateway`、Nginx 或其它进程已释放 `80/443`；启用后仍必须跑 release readiness 门禁；验证失败时统一执行 `pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'` 回到 shadow / Nginx 入口，回退脚本会先运行 `nginx -t`，通过后移除 direct-entry drop-in、重启 Pingora，再用 `systemctl cat` 确认两条低端口 capability 均已从最终 unit 配置中移除，用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，并 reload Nginx、确认 Nginx service 仍为 `active`，最后用 curl smoke URL 证明 Nginx 入口真实可访问；回退 smoke URL/body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`。回退脚本 `--apply` 必须同时带 `--reload-nginx` 和 `--nginx-smoke-url`，避免只撤掉 Pingora 低端口能力却没有证明 Nginx 已重新接流；本机打 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 必须带 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免命中默认 vhost。回退后必须复核 health patrol env 已切回 `nginx` 且 public base URL / Host 恢复为切换前记录值；如果 env 已预先修正，rollback 脚本可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 自动执行这项复核，切换前 Nginx 巡检需要 Host 覆盖时把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`。若需证明 Pingora 仍以 shadow 高端口存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应包含 `gateway=pingora-shadow`。
 - 决策补充：health patrol env 的直连/回退切换不再靠人工编辑三行变量；正式 runbook 使用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply`，只更新 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST` 并立即调用随包 `check-production-health-patrol-env.mjs` 复核。Pingora direct 使用本机 public base URL 时脚本必须带 `--public-host <域名>`；回退到 Nginx 时根据切换前记录传 `--clear-public-host` 或 `--public-host <切换前Host>`。生产巡检、health patrol env 复核和 env 切换脚本读取的布尔 env 必须严格解析，非法值直接失败，不得静默按 false 继续；env 复核脚本的 `--env-file` 与 env 切换脚本的 `--env-file` / `--check-script` 必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本写入的 public base URL / Host 同样不能包含换行或 NUL。Node 22 已内置 `--env-file` 启动参数，凡是用 Node 启动项目脚本且要把业务 `--env-file` 传给脚本时，必须写成 `node -- <script> --env-file ...`；systemd / shell / release readiness runbook 中的这类 Node 调用都必须保留 `--` 分隔符。
 - 写入语义补充：`pingora-health-patrol-env-switch.mjs --apply` 必须先对权限固定为 `0600` 的临时目标 env 运行随包 env 复核脚本，复核通过后才按真实 `/etc/genarrative/health-patrol.env` 原权限和 owner/group 原子替换；复核失败时不得写入真实 env，避免切换窗口留下半坏巡检配置。`--apply` 时 `--env-file` 必须直接指向真实普通文件，不能是符号链接；若现场 env 是链接，先确认真实目标路径后再传给脚本，避免替换链接本身或写入非预期目标。
 - 顺序补充：正式 runbook 中 health patrol 的 Nginx 回退 env 必须在 `rollback apply` 前预置，随后 `pingora-direct-rollback.sh --apply` 会用 `--health-patrol-expected-public-base-url` 和 `--health-patrol-expected-public-host` / `--health-patrol-require-empty-public-host` 在 Nginx smoke 后复核该 env；最后仍保留独立的回退后 health patrol env 复核步骤。
+- 顺序补充：正式 runbook 中 Pingora 自身 env 的 shadow 回退也必须在 `rollback apply` 前预置。真实直连会把 `/etc/genarrative/pingora-gateway.env` 提升为 `0.0.0.0:80/443` direct 配置；回退脚本移除 `CAP_NET_BIND_SERVICE` 后会重启 Pingora，如果 env 仍保留低端口监听，服务可能按预期失败而不是回到 shadow。因此 rollback apply 前必须用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 先确认 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081`，并清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` 和 `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE`，避免保留证书路径但无 TLS listener 的半直连 env。
 - 安全补充：直连公网地址时 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR` 必须保持 `false`；只有 Pingora 前方仍有会清洗 `X-Forwarded-For` 的受控代理且监听为 loopback / 受控入口时，才允许配合 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true` 使用转发 IP 作为接流保护 client key。目标机 direct preflight 必须在公网监听加 `TRUST_X_FORWARDED_FOR=true` 时失败，且这两个 gateway env 布尔值也必须严格解析，非法值直接失败，避免公网用户伪造限流 key 或拼写错误被当成 false。
 - 发布补充：`npm run check:production-api-release` 继续验证 API release 自包含和显式 include 的假二进制布局；`npm run check:pingora-production-release-build` 必须额外走真实 `cargo build -p pingora-gateway --release --target x86_64-unknown-linux-gnu`，并用假 `api-server` 验证 `--include-pingora-gateway` 发布包包含可执行 `pingora-gateway`、`pingora-gateway.sha256` 和 manifest 登记。`check:pingora-release-readiness` 默认纳入该真实构建 smoke，避免正式切换前只验证发布包布局而没有验证 Pingora release 二进制可构建。
 - 发布安全补充：API release 和 deploy 动态烟测必须复核 `deploy/pingora/pingora-gateway.env.example` 随包后的生产安全默认值，至少包括 `COMPRESSION_ALGORITHMS=gzip`、`TRUST_X_FORWARDED_FOR=false`、`TRUSTED_FRONT_PROXY_CONFIRMED=false`、`PROTECTION_ENABLED=true` 和空 `PROBE_TOKEN`；这些值漂移时应在构建 / 部署门禁中失败，而不是等切换窗口人工审查。
@@ -36,15 +37,17 @@
 - 静态方法补充：Pingora 静态路由只允许 `GET` / `HEAD` 读取；非读取方法命中静态候选时返回 `405` 并写入 `Allow: GET, HEAD`，缺失文件仍返回 `404`。`npm run check:pingora-gateway-smoke` 必须覆盖该行为，避免直连后错误客户端把静态入口当作可写接口。
 - direct live 静态资产补充：`check-pingora-direct-live.mjs` 在 HTTPS 根路径返回 `200` 且 HTML 中发现 `/assets/` 或 `/admin/assets/` 引用时，必须额外请求该静态资源，校验 `Cache-Control`、`ETag`、`Last-Modified`、`Accept-Ranges: bytes`，再用 `HEAD` 验证头响应，用 `If-None-Match` / `If-Modified-Since` 验证 `304` 协商缓存，用 `Range: bytes=0-0` 验证 `206 + Content-Range` 且不压缩，并把这些 request_id 都纳入 `direct-access-log` method/path/status 对账；如果首页引用 Vite 指纹资源，还必须额外验证 `Cache-Control: public, max-age=31536000, immutable`，并把指纹资源 GET / HEAD / 304 / Range request_id 纳入同一 access log method/path/status 对账。静态 GET / HEAD / 304 / Range 的 `direct-live.json` 结果必须写入白名单 `headers`，只保留 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`，让证据包复盘时能直接确认缓存分档、校验器和 Range 语义；API / WSS 检查不落原始响应头。证据包 `manifest.summary.directLiveStaticHeaders` 必须把普通静态和 Vite 指纹静态的缓存头、校验头、Range `Content-Range` 与 304 状态提升出来；如果 direct live 已输出静态资产结果但摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 或 Last-Modified 304 证据，整包记为 `CRITICAL`。维护模式、非 HTML 或首页没有构建资产引用时该项允许标记为 skipped。这样直连切换证据不只覆盖 API / WSS / redirect，也覆盖当前发布包前端静态资源可读、协商缓存和旧 tab chunk 长缓存口径。
 - 快照补充：状态快照必须把 `--pingora-env-file` 与 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 精确匹配，支持 `EnvironmentFile=-/path` 和一行多个文件，但不能用路径前缀误判；未包含本次 pingora env 时 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile=false` 并标记 `CRITICAL`，避免证据包读取一份 env 而真实 Pingora 服务读取另一份 env。
+- 快照补充：状态快照支持 `--expected-pingora-env-mode shadow|direct`。正式 cutover runbook 的 `post-enable` 证据包必须传 `--expected-pingora-env-mode direct`，`post-rollback` 证据包必须传 `--expected-pingora-env-mode shadow`；若 active env 姿态与期望不一致，证据包应标记 `CRITICAL`，不能只依赖 health patrol gateway mode 或 systemd drop-in 判断切流状态。
 - 证据验真补充：`scripts/ops/pingora-cutover-evidence-verify.mjs` 只接受 `schemaVersion=1` 的 manifest，并把 `manifest.files` 视为闭集，证据目录中除 `manifest.json` 和 manifest 已登记文件外，任何未登记普通文件、目录或符号链接都默认失败；`--allow-extra-files` 只用于人工排障显式放行，正式切换归档不使用。正式 runbook 的五个即时验真步骤都必须追加 `--require-summary-ok`，让 `pre-cutover`、`enable-apply`、`post-enable`、`rollback-apply`、`post-rollback` 证据在生成后立即要求 `manifest.summary.status=OK`；缺少 summary 或状态非 OK 时先修现场状态或重采证据，不等最终总审计才发现。
 - 正式 runbook 安全补充：`--warn-only`、`--allow-extra-files` 和 `--allow-extra-root-entries` 只允许在 runbook 外作为人工排障命令使用；`plan:pingora-direct-cutover` 生成的正式切换计划不得携带这些放行参数。需要使用放行参数时，先修现场状态、证据目录或重新归档，不能把人工排障口径带入正式切换计划。
 - 证据根目录补充：`scripts/ops/pingora-cutover-evidence-audit.mjs` 默认把证据根目录也视为闭集，只允许带 `manifest.json` 的证据目录；根目录普通文件、无 manifest 子目录和符号链接都会失败。`--allow-extra-root-entries` 只用于人工排障显式放行，正式切换归档不使用。
-- 证据总审计补充：三阶段 `pre-cutover` / `post-enable` / `post-rollback` 证据包分别验真，且 `enable-apply` / `rollback-apply` 命令证据生成后，正式 runbook 还必须执行 current release 随包 `scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-command enable-apply:pingora-direct-enable-apply --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000`。runbook 会自动生成或接受显式 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、enable / rollback apply 命令证据和最终总审计；该脚本只读扫描证据根目录，按 `manifest.phase` 选择每个阶段最新证据目录、按 `manifest.phase + manifest.commandName` 选择真实切换命令证据，并复用随包 verifier 验真；所有候选 manifest 必须是 `schemaVersion=1`，最新证据选择和时间线证明只接受合法且规范的 UTC 毫秒 `manifest.generatedAt`，命令记录 `startedAt` / `finishedAt` 也必须使用 `new Date().toISOString()` 形式；缺失、非法或省略毫秒 / 本地时区格式时直接失败，不能用目录 mtime 兜底；`post-enable` 阶段还必须带可判定的 `manifest.summary.directLiveAccessLog` 与 `manifest.summary.directLiveStaticHeaders`，否则总审计失败，避免旧启用后证据包缺少 request_id 对账、静态缓存、校验器、Range 或 304 复盘入口；缺阶段、缺命令证据、最新证据损坏、阶段 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`、命令证据缺少或漂移 `manifest.expectedExecutable` / `manifest.command.executable` / 独立 `command-record.json` executable、命令证据缺少必需 `--apply` 参数、`manifest.command` 与 `command-record.json` 关键字段不一致、命令 stdout / stderr 引用与 `manifest.files` 不一致、命令 args / command 漂移、命令记录时间线不合法、标准五段证据任一条目审计状态非 `OK`、标准五段证据 `manifest.generatedAt` 顺序不满足 `pre-cutover -> enable-apply -> post-enable -> rollback-apply -> post-rollback`、标准五段证据跨度超过默认 24 小时、要求 `--require-cutover-run-id` 时任一阶段或命令缺少同一 `manifest.cutoverRunId`、证据根目录或 verifier 路径不安全、证据 verifier / 总审计入口路径或 manifest 登记文件名含换行 / NUL、证据根目录内出现坏 manifest / 符号链接时都应失败。确需更长维护窗口时，通过 release readiness runbook 参数 `--cutover-evidence-timeline-max-span-ms <ms>` 显式放宽，并让最终总审计 JSON 留下 `requiredCutoverRunId`、`requiredCommandExecutables`、`requiredCommandArgs`、`timeline.maxSpanMs` / `timeline.spanMs`。
+- 证据总审计补充：三阶段 `pre-cutover` / `post-enable` / `post-rollback` 证据包分别验真，且 `enable-apply` / `rollback-apply` 命令证据生成后，正式 runbook 还必须执行 current release 随包 `scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:pingora-direct --require-command-arg rollback-prep:pingora-gateway-shadow-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:nginx --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000`。runbook 会自动生成或接受显式 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、五条真实切换命令证据和最终总审计；该脚本只读扫描证据根目录，按 `manifest.phase` 选择每个阶段最新证据目录、按 `manifest.phase + manifest.commandName` 选择真实切换命令证据，并复用随包 verifier 验真；所有候选 manifest 必须是 `schemaVersion=1`，最新证据选择和时间线证明只接受合法且规范的 UTC 毫秒 `manifest.generatedAt`，命令记录 `startedAt` / `finishedAt` 也必须使用 `new Date().toISOString()` 形式；缺失、非法或省略毫秒 / 本地时区格式时直接失败，不能用目录 mtime 兜底；`post-enable` 阶段还必须带可判定的 `manifest.summary.directLiveAccessLog` 与 `manifest.summary.directLiveStaticHeaders`，否则总审计失败，避免旧启用后证据包缺少 request_id 对账、静态缓存、校验器、Range 或 304 复盘入口；缺阶段、缺命令证据、最新证据损坏、阶段 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`、命令证据缺少或漂移 `manifest.expectedExecutable` / `manifest.command.executable` / 独立 `command-record.json` executable、命令证据缺少必需 `--apply` 参数、`manifest.command` 与 `command-record.json` 关键字段不一致、命令 stdout / stderr 引用与 `manifest.files` 不一致、命令 args / command 漂移、命令记录时间线不合法、标准八段证据任一条目审计状态非 `OK`、标准八段证据 `manifest.generatedAt` 顺序不满足 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`、标准八段证据跨度超过默认 24 小时、要求 `--require-cutover-run-id` 时任一阶段或命令缺少同一 `manifest.cutoverRunId`、证据根目录或 verifier 路径不安全、证据 verifier / 总审计入口路径或 manifest 登记文件名含换行 / NUL、证据根目录内出现坏 manifest / 符号链接时都应失败。确需更长维护窗口时，通过 release readiness runbook 参数 `--cutover-evidence-timeline-max-span-ms <ms>` 显式放宽，并让最终总审计 JSON 留下 `requiredCutoverRunId`、`requiredCommandExecutables`、`requiredCommandArgs`、`timeline.maxSpanMs` / `timeline.spanMs`。
 - 证据总审计补充：最终审计 JSON 的 `summary` 是值班人员优先入口；`summary.status` 给出 `OK` / `CRITICAL`，`summary.failedItems[]` 聚合根目录、阶段、命令和时间线失败，`summary.directLiveEvidence[]` 聚合 `post-enable` 的 access log 与静态头要求、ok 状态、短 reason 和摘要。现场先看 summary 定位，再展开 `phases[]`、`commands[]`、`timeline` 深挖。
-- 文档门禁补充：Pingora 技术文档里的最终证据根目录总审计命令示例也必须包含 enable / rollback 两条 `--require-command-executable`，`npm run check:pingora-release-readiness-plan` 会读取文档并阻断示例落后于真实 runbook 的情况；`npm run check:production-api-release` 还必须动态生成 API release，检查发布包 README 和随包 `scripts/check-pingora-release-readiness.mjs --dry-run-cutover` 输出的最终总审计步骤也保留这两条 current release 脚本身份要求。
+- 证据总审计补充：证据包会把状态快照里的 Pingora env 监听摘要提升到 `manifest.summary.pingoraEnvShadow`，包含 `listen`、`tlsListen`、`httpRedirectListen`、`tlsCertFile`、`tlsKeyFile`、`mode`、`shadowReady` 和 `ok`。正式 runbook 的最终总审计必须追加 `--require-phase-pingora-env-shadow post-rollback`，要求 `post-rollback` 证明 `listen=127.0.0.1:18081`、`mode=shadow`、`shadowReady=true`，且 TLS / HTTP redirect 低端口监听和证书路径均为空；最终审计 JSON 的 `summary.pingoraEnvShadowEvidence[]` 会聚合该要求、ok 状态、短 reason 和摘要，避免回退后 active env 仍残留 direct 低端口配置或 cert/key 半直连配置。
+- 文档门禁补充：Pingora 技术文档里的最终证据根目录总审计命令示例也必须包含 enable apply、health patrol direct env switch、Pingora gateway shadow env switch、health patrol nginx env switch 和 rollback apply 五条 `--require-command-executable`，`npm run check:pingora-release-readiness-plan` 会读取文档并阻断示例落后于真实 runbook 的情况；`npm run check:production-api-release` 还必须动态生成 API release，检查发布包 README 和随包 `scripts/check-pingora-release-readiness.mjs --dry-run-cutover` 输出的最终总审计步骤也保留这五条 current release 脚本身份要求。
 - 证据总审计补充：同一阶段或同一命令的最新 `manifest.generatedAt` 必须唯一。若多个候选共享最新时间戳，`pingora-cutover-evidence-audit.mjs` 必须输出 `AMBIGUOUS_LATEST` 并列出重复目录，不能按目录名排序打平；处理方式是重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。
-- 证据总审计补充：标准五段时间线只要任一阶段或命令证据声明了 `manifest.cutoverRunId`，五段就必须全部声明同一个值；缺字段或混入其它批次时，即使没有显式传 `--require-cutover-run-id`，总审计也必须失败，避免人工临时审计把不同切换批次拼成一条时间线。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。
-- 证据总审计输出补充：标准五段时间线失败时，`timeline.failedCount` 按具体失败项累计，`timeline.failureBreakdown` 分别记录 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded`，用于把多个失败证据或多个时间线问题拆成可操作排障项。
+- 证据总审计补充：标准八段时间线只要任一阶段或命令证据声明了 `manifest.cutoverRunId`，八段就必须全部声明同一个值；顺序固定为 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`。缺字段或混入其它批次时，即使没有显式传 `--require-cutover-run-id`，总审计也必须失败，避免人工临时审计把不同切换批次拼成一条时间线。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。
+- 证据总审计输出补充：标准八段时间线失败时，`timeline.failedCount` 按具体失败项累计，`timeline.failureBreakdown` 分别记录 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded`，用于把多个失败证据或多个时间线问题拆成可操作排障项。
 - 命令证据身份补充：正式 runbook 的 `enable-apply` / `rollback-apply` 命令证据必须传 `--expected-executable <current release 随包脚本绝对路径>` 和 `--require-arg --apply`，分别绑定 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 和 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，并在执行前要求真实命令参数包含 `--apply`。命令证据脚本会在创建正式命令证据前拒绝真实命令与预期脚本不一致、缺少必需 apply 参数，或任一真实命令参数包含换行 / NUL 字符，并把 `expectedExecutable` 写入 manifest / command-record；最终证据根目录总审计再用 `--require-command-executable` 复核 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` executable，并用 `--require-command-arg ...:--apply` 复核 `manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，同时拒绝 args 数组中任何带换行或 NUL 字符的结构化参数。总审计传入的 `--require-command-executable` executable 段也必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符，且会写入 `requiredCommandExecutables` 供复盘。总审计还会要求顶层 `manifest.commandName` 与内嵌 `manifest.command.name` 只要存在就各自是安全非空命令名，且两者同时存在时必须一致，并比较 `manifest.command` 与 `command-record.json` 的 schemaVersion / phase / name / cutoverRunId / exitCode / signal / startedAt / finishedAt / durationMs / stdoutPath / stderrPath / args / command / cwd / error 等关键字段；两份命令记录的 `schemaVersion` 都必须是 `1`，stdoutPath / stderrPath 还必须分别与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 指向同一份归档文件，args 与 command 用于证明真实 apply 参数未被替换成 dry-run 或其它动作；命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`；这些参数会隐式要求对应命令证据存在；`commandName` 只用于审计分类，不能替代真实脚本身份和真实 apply 参数校验。
 - 命令证据字段补充：`manifest.expectedExecutable` 和 `manifest.command.expectedExecutable` 只要出现，就必须是安全绝对路径；空字符串、相对路径、文件系统根目录或包含换行 / NUL 的值必须按坏 manifest 失败，不能用 `||` 等兜底逻辑把坏字段吞掉。命令证据生成端的 `--expected-executable` 同样必须在执行真实命令前拒绝相对路径、文件系统根目录和带换行 / NUL 的路径。
 - 命令证据身份补充：只要命令证据声明了 `expectedExecutable`，`manifest.command.executable` 和独立 `command-record.json.executable` 就必须同时是同一个安全绝对路径；即使人工总审计漏传 `--require-command-executable`，真实 executable 与 expectedExecutable 漂移也必须失败。
@@ -53,13 +56,13 @@
 - 路径安全补充：切换窗口覆盖 `pingora-direct-enable.sh` 的 `--preflight-script`、`--direct-live-script`、`--current-release-audit-script`、`--template-path`、`--service-unit-path`、`--dropin-path` 或 env 文件路径时必须使用绝对路径，且不能指向文件系统根目录，避免 current release、Jenkins 工作区和现场 cwd 混用；`--apply` 必须在安装 direct-entry drop-in 前确认 current release 自审、direct preflight 和 direct live smoke 脚本都真实存在，任一脚本缺失时直接失败且不改 systemd。启用脚本还必须在 current release 自审、preflight、drop-in 写入和 systemctl 前拒绝 service、路径、URL、Host、probe token、access log、数据库名、tail 行数和 timeout 参数中的换行或 NUL 字符，并在安装前拒绝符号链接形式的 drop-in 目录或 drop-in 目标文件、拒绝已存在但不是普通文件的目标，避免把低端口 capability 写入非预期 systemd 位置。`pingora-direct-rollback.sh --apply` 也必须在 `nginx -t`、删除 drop-in、reload Nginx 或 health patrol / shadow probe 复核前拒绝 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override 中的换行或 NUL 字符，并拒绝 service unit、drop-in、health patrol env、复核脚本和路径形式二进制 override 指向文件系统根目录，再拒绝符号链接形式的 drop-in 目录或目标文件、拒绝已存在但不是普通文件的目标，避免回退窗口误删或误判非预期 systemd 位置。`pingora-direct-rollback.sh` 覆盖 `--nginx-binary` 或 `--curl-binary` 时允许裸命令名走 `PATH`，但只要值包含路径分隔符就必须是绝对路径，避免回退窗口从 cwd 运行相对二进制；`--nginx-smoke-url` 必须是 `http(s)` URL，非法值在移除 drop-in 前失败。
 - 直连日志证据补充：Pingora 直连接管不能只看 HTTPS / HTTP redirect / ACME / WSS 响应成功；`pingora-direct-enable.sh --apply` 和 release readiness `--require-direct` 必须显式提供 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。direct live smoke 会给每个请求生成 `X-Request-Id`，再反查 Pingora access log 尾部记录，缺少对应 `request_id`、方法、路径或状态漂移都应阻断启用后复核。启用脚本 apply 后必须以 `--json` 运行 direct live 并解析 stdout 中的 `direct-access-log` 结构化结果；缺少该结果、`matchedCount != checked`、`missingCount != 0` 或 `mismatchCount != 0` 都让启用失败，避免 direct live 子进程退出 0 但 access log 证据缺失时误判切换成功。正式 runbook 的启用后证据包必须额外传 `--run-direct-live`，把 `direct-live.json`、stdout / stderr、命令记录、direct-access-log 检查结果和静态响应头白名单证据写入同一证据目录，不能只依赖启用脚本或 release readiness 的终端输出；`direct-live.json` 中的 `direct-access-log` 必须保留 `scannedLineCount`、`matchedCount`、`missing[]`、`mismatches[]` 以及每个 `request_id` 的预期 / 实际 method、path 与 status，静态资源检查还必须保留 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding` 白名单头，避免复盘时只看到 count 或终端 stderr。证据包还必须把 `directLiveAccessLog` 和 `directLiveStaticHeaders` 摘要提升到 `manifest.summary`，让值班人员先从 manifest 快速看到普通静态 / 指纹静态的 `Cache-Control`、`ETag`、`Last-Modified`、`Content-Length`、Range `Content-Range` 与 304 状态证据；缺少 `direct-access-log` 结构化结果、缺少可判定的静态头摘要，或静态头摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 / Last-Modified 304 证据时整包记为 `CRITICAL`。若 snapshot 或 direct live stdout 无法解析，证据包必须保留 `snapshot-parse-error.txt` 或 `direct-live-parse-error.txt`，并在 manifest / 最终 stdout 中索引错误文件。`deploy/env/pingora-direct-live.env.example` 必须保留 `GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG` 和 `GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES`，让目标机和 CI 使用同一口径。
 - 影响范围：`deploy/systemd/genarrative-pingora-gateway.service`、`deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`deploy/env/`、`scripts/deploy/pingora-direct-enable.sh`、`scripts/deploy/pingora-direct-rollback.sh`、`scripts/deploy/pingora-health-patrol-env-switch.mjs`、`scripts/jenkins-server-provision.sh`、API release / Jenkins 归档链路、生产运维护栏、Pingora 试点文档、Nginx README 和生产护栏。
-- 验证方式：`npm run check:production-ops` 确认主 service 仍是 shadow、drop-in 具备最小 capability、Provision 只安装人工启用模板且 release 携带启用 / 回退脚本，并确认 enable 脚本默认模板路径指向 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`plan:pingora-direct-cutover` 入口存在；`npm run check:pingora-direct-enable` 和 `npm run check:pingora-direct-rollback` 确认脚本默认 dry-run 不修改 drop-in、会打印命令、release layout 默认读取随包 direct-entry 模板、拒绝相对路径、非法 Nginx smoke URL、路径形式的二进制 override、enable / rollback 控制字符参数、符号链接 drop-in 目录 / 目标以及非普通 drop-in 目标，enable current release 自审失败、direct preflight 脚本缺失或 direct live smoke 脚本缺失时不会安装 drop-in，direct live 退出 0 但缺少 `direct-access-log` JSON 证据时启用失败，rollback drop-in 路径异常或控制字符参数时不会继续执行 `nginx -t` 或删除真实目标，enable `--apply` 缺少 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 或 `--direct-spacetime-database` 会失败，rollback `--apply` 缺少 `--reload-nginx` 或 `--nginx-smoke-url` 会失败，且启用 / 回退后都会核验 systemd 最终配置和 `ExecStart` 指向 current release；`npm run check:pingora-cutover-status-snapshot` 必须覆盖 `systemctl cat` 读取另一份 Pingora env 时快照标记 `CRITICAL`；`npm run check:pingora-release-readiness-plan` 必须覆盖 `--dry-run-cutover` runbook、Host 一致性确认、redirect Host / rollback smoke Host 漂移负例、缺少 `--require-direct` 的负例、缺少 `--rollback-health-patrol-public-base-url` 的负例、enable / rollback apply 步骤和回退后 health patrol env Nginx 模式复核；enable 必须确认 Pingora active 并执行 direct live smoke，direct live 失败或 access log 结构化证据缺失时整次启用失败；rollback 必须先跑 `nginx -t`，失败时不能先删除 drop-in，重启后必须确认 `ExecStart` 没有漂到旧 release，reload 后必须确认 Nginx active 并执行 smoke URL，curl 失败时整次回退失败；可选 health patrol env 复核必须拒绝 `pingora-direct` 残留或 public base URL / Host 漂移；可选 shadow probe 复核必须拒绝 URL / token 缺任一项、非法 URL 或非 `pingora-shadow` 响应；`npm run check:pingora-release-readiness` 默认会串起 direct-entry 静态预检、启用 / 回退 dry-run 与生产护栏；切换窗口先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再运行 release readiness `--require-direct`；验证失败时先 dry-run 回退脚本，再用 `--apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名>` 执行，并确认回退脚本未报告 capability 残留、ExecStart 漂移、Nginx 非 active 或 smoke 失败，最后用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs ...` 运行 health patrol env nginx 模式复核。
+- 验证方式：`npm run check:production-ops` 确认主 service 仍是 shadow、drop-in 具备最小 capability、Provision 只安装人工启用模板且 release 携带启用 / 回退脚本，并确认 enable 脚本默认模板路径指向 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`plan:pingora-direct-cutover` 入口存在；`npm run check:pingora-direct-enable` 和 `npm run check:pingora-direct-rollback` 确认脚本默认 dry-run 不修改 drop-in、会打印命令、release layout 默认读取随包 direct-entry 模板、拒绝相对路径、非法 Nginx smoke URL、路径形式的二进制 override、enable / rollback 控制字符参数、符号链接 drop-in 目录 / 目标以及非普通 drop-in 目标，enable current release 自审失败、direct preflight 脚本缺失或 direct live smoke 脚本缺失时不会安装 drop-in，direct live 退出 0 但缺少 `direct-access-log` JSON 证据时启用失败，rollback drop-in 路径异常或控制字符参数时不会继续执行 `nginx -t` 或删除真实目标，enable `--apply` 缺少 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 或 `--direct-spacetime-database` 会失败，rollback `--apply` 缺少 `--reload-nginx` 或 `--nginx-smoke-url` 会失败，且启用 / 回退后都会核验 systemd 最终配置和 `ExecStart` 指向 current release；`npm run check:pingora-cutover-status-snapshot` 必须覆盖 `systemctl cat` 读取另一份 Pingora env 时快照标记 `CRITICAL`；`npm run check:pingora-release-readiness-plan` 必须覆盖 `--dry-run-cutover` runbook、Host 一致性确认、redirect Host / rollback smoke Host 漂移负例、缺少 `--require-direct` 的负例、缺少 `--rollback-health-patrol-public-base-url` 的负例、enable / rollback apply 步骤和回退后 health patrol env Nginx 模式复核；enable 必须确认 Pingora active 并执行 direct live smoke，direct live 失败或 access log 结构化证据缺失时整次启用失败；rollback 必须先跑 `nginx -t`，失败时不能先删除 drop-in，重启后必须确认 `ExecStart` 没有漂到旧 release，reload 后必须确认 Nginx active 并执行 smoke URL，curl 失败时整次回退失败；可选 health patrol env 复核必须拒绝 `pingora-direct` 残留或 public base URL / Host 漂移；可选 shadow probe 复核必须拒绝 URL / token 缺任一项、非法 URL 或非 `pingora-shadow` 响应；`npm run check:pingora-release-readiness` 默认会串起 direct-entry 静态预检、启用 / 回退 dry-run 与生产护栏；切换窗口先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再运行 release readiness `--require-direct`；验证失败时先 dry-run 回退脚本，再用 `--apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'` 执行，并确认回退脚本未报告 capability 残留、ExecStart 漂移、Nginx 非 active 或 smoke 失败，最后用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs ...` 运行 health patrol env nginx 模式复核。
 - 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。
 
 ## 2026-06-13 Pingora direct live 必须覆盖 WSS subscribe
 
 - 背景：Pingora 已具备显式 TLS / HTTP redirect 直连入口，但 SpacetimeDB 前端订阅依赖 `/v1/database/<db>/subscribe` 的 WebSocket 长连接；只检查 HTTPS 普通请求无法证明直连入口能替代 Nginx 的 WebSocket 透传。
-- 决策：`check-pingora-direct-live.mjs` 默认先通过 TLS ALPN 确认 HTTPS 可协商 `h2`，再对 `wss://<direct>/v1/database/<database>/subscribe` 发起握手，并使用 SpacetimeDB SDK 2.4.1 默认子协议 `v2.bsatn.spacetimedb`；成功 101 时必须保留该子协议和 `X-Genarrative-Gateway: pingora-shadow`。release readiness `--require-direct` 会自动要求 WSS subscribe 返回 101，并强制要求 `--direct-http-base-url` / `GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL`、`--direct-host` / `GENARRATIVE_PINGORA_DIRECT_HOST`、`--direct-redirect-host` / `GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST`、`--direct-pingora-access-log` / `GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG`、`--direct-preflight-systemd` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT=true`、`--direct-preflight-check-cert-readable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE=true`、`--direct-preflight-check-service-env-file` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE=true`、`--direct-preflight-check-service-user-cert-readable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE=true`、`--direct-preflight-check-service-binary-executable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE=true`、`--direct-preflight-check-ports-free` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE=true` 和 `--direct-spacetime-database` / `GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE` 和 `--direct-health-patrol-env-file` / `GENARRATIVE_PINGORA_DIRECT_HEALTH_PATROL_ENV_FILE`，确保 HTTP/2 ALPN、HTTP 301、ACME challenge、正式域名 Host/SNI、redirect Location host、Pingora access log 的 request_id 落盘、systemd drop-in 生效、service EnvironmentFile 一致性、当前用户证书可读性、服务用户证书可读性、current release 二进制可执行性、80/443 端口释放、health patrol direct 模式和目标库 WSS subscribe 都进入直连硬门禁；单独运行 direct live smoke 时可用 `--require-wss-upgrade` 强制同一口径。本机 `--host <域名>` 验证正式证书时，该 host 同时用于 HTTP Host 和 TLS SNI，`--redirect-host <域名或host:port>` 则用于校验 HTTP redirect `Location`。`--skip-wss` 只允许单独 direct live 临时排障；release readiness `--require-direct` 会直接拒绝。
+- 决策：`check-pingora-direct-live.mjs` 默认先通过 TLS ALPN 确认 HTTPS 可协商 `h2`，再对 `wss://<direct>/v1/database/<database>/subscribe` 发起握手，并使用 SpacetimeDB SDK 2.4.1 默认子协议 `v2.bsatn.spacetimedb`；成功 101 时必须保留该子协议和 `X-Genarrative-Gateway: pingora-shadow`。release readiness `--require-direct` 会自动要求 WSS subscribe 返回 101，并强制要求 `--direct-http-base-url` / `GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL`、`--direct-host` / `GENARRATIVE_PINGORA_DIRECT_HOST`、`--direct-redirect-host` / `GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST`、`--direct-pingora-access-log` / `GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG`、`--direct-preflight-systemd` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT=true`、`--direct-preflight-check-cert-readable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE=true`、`--direct-preflight-check-service-env-file` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE=true`、`--direct-preflight-check-service-user-cert-readable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE=true`、`--direct-preflight-check-service-binary-executable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE=true` 和 `--direct-spacetime-database` / `GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE` 和 `--direct-health-patrol-env-file` / `GENARRATIVE_PINGORA_DIRECT_HEALTH_PATROL_ENV_FILE`，确保 HTTP/2 ALPN、HTTP 301、ACME challenge、正式域名 Host/SNI、redirect Location host、Pingora access log 的 request_id 落盘、systemd drop-in 生效、service EnvironmentFile 一致性、当前用户证书可读性、服务用户证书可读性、current release 二进制可执行性、health patrol direct 模式和目标库 WSS subscribe 都进入直连硬门禁；单独运行 direct live smoke 时可用 `--require-wss-upgrade` 强制同一口径。本机 `--host <域名>` 验证正式证书时，该 host 同时用于 HTTP Host 和 TLS SNI，`--redirect-host <域名或host:port>` 则用于校验 HTTP redirect `Location`。`--skip-wss` 只允许单独 direct live 临时排障；release readiness `--require-direct` 会直接拒绝。
 - 影响范围：`scripts/check-pingora-direct-live.mjs`、`scripts/check-pingora-gateway-smoke.mjs`、`scripts/check-pingora-release-readiness.mjs`、`deploy/env/pingora-direct-live.env.example`、生产运维护栏、Pingora 试点文档和 Nginx README。
 - 验证方式：`node --check scripts/check-pingora-direct-live.mjs scripts/check-pingora-release-readiness.mjs scripts/check-pingora-release-readiness-plan.mjs`、`npm run check:pingora-gateway-smoke`、`npm run check:pingora-release-readiness-plan`、`npm run check:production-ops`、`npm run check:pingora-release-readiness`。
 - 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。
@@ -2339,7 +2342,8 @@
 - 决策补充：Pingora 切换命令证据生成端必须在执行前约束真实命令身份：`-- <command>` 本身必须是绝对路径，不能是文件系统根目录；真实命令和每个真实命令参数都不能包含换行或 NUL 字符。正式 runbook 因此直接执行 current release 随包 enable / rollback 脚本绝对路径，禁止用 `node`、`bash`、脚本名或其它 PATH 裸命令名包装。
 - 决策补充：Pingora release readiness、canary access log 对账、direct live、direct preflight 和 cutover evidence bundle 的显式日志 / env 文件路径必须是绝对路径且不能是文件系统根目录。`--live-nginx-access-log`、`--live-pingora-access-log`、`--direct-pingora-access-log`、`--direct-health-patrol-env-file`、`--direct-preflight-env-file`、canary 对账脚本的 `--nginx-log-file` / `--pingora-log-file`、direct live 的 `--pingora-access-log`、direct preflight 的 `--env-file` 与 evidence bundle `--run-direct-live` 的 `--direct-pingora-access-log` 都不能指向 `/`，避免切换窗口把日志扫描或 env 复核误绑到根目录。证据包 `--run-direct-live` 的 direct URL、Host、probe token、SpacetimeDB 数据库名、Pingora access log 路径和 access log tail 行数还必须在配置层拒绝换行或 NUL，避免污染参数进入状态快照或 direct live 子命令后才失败。
 - 决策补充：证据根目录总审计按 `--require-phase` 查找阶段证据时，只接受不带 `manifest.commandName` 的状态快照证据包；enable / rollback apply 的命令证据只能通过 `--require-command`、`--require-command-executable` 和 `--require-command-arg` 审计，不能冒充同名 phase 的阶段证据。
-- 决策补充：直连回退的 Nginx smoke 不能只看 `curl --fail` / HTTP 200。`pingora-direct-rollback.sh` 支持 `--nginx-smoke-expect-body <片段>`，正式 cutover runbook 默认向 rollback dry-run / apply 传 `--nginx-smoke-expect-body '"ok":true'`，要求回退后的 `/healthz` 响应体包含预期片段；若现场 smoke URL 改成其它端点，必须显式调整 `--rollback-nginx-smoke-expect-body`。
+- 决策补充：直连回退的 Nginx smoke 不能只看 `curl --fail` / HTTP 200。`pingora-direct-rollback.sh` 支持 `--nginx-smoke-expect-body <片段>`；正式 cutover runbook 必须显式传入切换前真实 Nginx 入口和响应片段，不再默认假定 `/healthz` 会返回 `"ok":true`。dev 真实直连验证确认公网 Nginx 首页 `https://dev.genarrative.world/` 与 `<!doctype html>` 是可用 smoke，而固定 `http://127.0.0.1/healthz` / `"ok":true` 可能误卡回退或验证到错误入口。
+- 决策补充：`check-pingora-release-readiness.mjs --require-direct` 是启用后直连复核，不再强制要求 `--direct-preflight-check-ports-free`；`--dry-run-cutover` 和启用前 preflight 仍必须要求端口空闲，用于证明 Nginx、Gitea 等占用 `80/443` 的进程已释放。dev 真实 direct 接管 `80/443` 后，启用后复核应看到端口由 Pingora 占用而不是空闲。
 - 决策补充：Pingora 网关行为变更必须运行 `npm run check:pingora-gateway-smoke`；该脚本用临时 mock 上游验证静态路由、API 代理头、请求体限制、429 接流保护、上游断连 JSON 错误、维护模式和 SpacetimeDB WebSocket Upgrade，避免只靠单元测试遗漏接流路径。代理路径的上游失败必须返回稳定 JSON code，例如 `GATEWAY_UPSTREAM_ERROR` / `GATEWAY_UPSTREAM_TIMEOUT`。静态协商缓存、非读取方法和 Range 边界请求必须用固定 `X-Request-Id` 反查 Pingora access log，确认 `304`、`405`、`206`、`416` 这些本地响应状态也可进入切换证据链。
 - 决策补充：Nginx 到 Pingora 的 canary 先采用 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 的前缀手动入口，Server-Provision 只安装 snippet，不默认 include；启用时必须替换 probe token、限制来源，并用 `X-Genarrative-Nginx-Handoff: pingora-canary` 与 Pingora shadow 日志证明请求确实经过 handoff。
 - 决策补充：Pingora shadow / canary 必须配置可落盘 access log，默认示例为 `/var/log/genarrative/pingora-gateway.access.log`；Server-Provision 创建 `/var/log/genarrative`、安装 `deploy/logrotate/genarrative-pingora-gateway`，并让 systemd 沙箱允许写该目录。canary 对照时同时看 Nginx access log、Pingora access log 与 tracing 日志。
@@ -2350,6 +2354,7 @@
 - 决策补充：Pingora 前缀 canary 在目标 Nginx 中人工 include 并 reload 后，必须运行 `npm run check:pingora-canary-live`；该脚本只读访问 `__genarrative_pingora_canary` 前缀下的 healthz、代表性 API、SpacetimeDB identity、静态资源和拒绝入口，并强制校验 `X-Genarrative-Nginx-Handoff: pingora-canary`，避免只通过 snippet 静态检查却没有证明真实 handoff 链路可用。
 - 决策补充：Pingora release readiness 分为源码全量门禁和 current release runtime-only 门禁。源码 checkout / CI / 构建环境继续运行默认 `check-pingora-release-readiness.mjs`，覆盖 Cargo、npm、Docker、Nginx 静态 / 真机校验和发布包构建烟测；目标机 `/opt/genarrative/current` 的启用前基础门禁和启用后 `--require-direct` 复核必须调用随包 `scripts/check-pingora-release-readiness.mjs --release-runtime-only`，只执行 current release 自审、启用前直连彩排状态、live canary、access log 对账、direct preflight、health patrol env 复核和 direct live smoke。未带 `--require-direct` 时 runtime-only 必须自动运行随包 `scripts/ops/pingora-direct-rehearsal-status.mjs --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical`，确认公网 `80/443` 仍由 Nginx 接流、Pingora shadow `127.0.0.1:18081`、realpath canary `127.0.0.1:18083` 和 current release 自审均通过；启用后 `--require-direct` 复核不再要求 Nginx 接公网彩排状态，改为检查 direct preflight、health patrol 直连模式和 direct live smoke。API release / current release 必须随包携带 `scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-live.mjs`、canary access log 对账脚本、直连彩排状态脚本和 direct preflight / live 子脚本；runtime-only 模式不得依赖源码 checkout、npm project root、Docker 或目标机 Nginx 静态校验。
 - 决策补充：Pingora 直连静态响应必须显式写入缓存头。HTML、目录 index 和 SPA fallback 默认 `Cache-Control: no-cache`；`/assets/*` 与 `/admin/assets/*` 中带 Vite 指纹文件名的资源默认 `Cache-Control: public, max-age=31536000, immutable`；非指纹静态和 ACME challenge 默认 `no-cache`。三档由 `GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL`、`GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL` 和 `GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL` 覆盖，配置值不能包含换行或 NUL；`npm run check:pingora-gateway-smoke` 必须覆盖这些缓存头，避免直连后入口 HTML 被长期缓存或指纹资源失去长期缓存收益。
+- 决策补充：Pingora 直连同一公网 IP 上的多域名时，必须先保住非主站域名的 Host 语义。dev 上 `dev.genarrative.world` 与 `git.genarrative.world` 共用 `80/443`，因此 direct env 必须配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world` 和 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000`，命中 Gitea Host 的请求整站代理到 Gitea，且不走应用维护页、API body limit 或网关接流保护。当前 Pingora TLS listener 只加载一组 cert/key；同时接管 `dev.genarrative.world` 和 `git.genarrative.world` 前，证书必须覆盖两个域名，不能使用单域名 SAN 证书。
 ## 2026-06-11 资产计费边界改为 fail-closed 并补偿退款
 
 - 背景：图片 / 资产生成入口曾在钱包或 SpacetimeDB 预扣费连通性异常时允许继续生成，且失败后同步退款如果遇到 SpacetimeDB 短暂不可用缺少本地补偿；拼图首图后台任务还使用 api-server 进程内 HashSet 互斥，多实例下不能防重复。
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index fa45cfe79..42aff25b8 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -19,12 +19,13 @@
 
 - 现象：`/etc/genarrative/pingora-gateway.env` 已把 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `HTTP_REDIRECT_LISTEN` 改到 `0.0.0.0:443` / `0.0.0.0:80`，但 `genarrative-pingora-gateway.service` 启动失败，日志出现低端口绑定权限错误。
 - 原因：默认 service 用非 root `genarrative` 用户运行，并且主模板为了保持 shadow 安全边界不带 `CAP_NET_BIND_SERVICE`。低端口直连必须通过显式 systemd drop-in 单独授予 capability；同时 Certbot 私钥默认未必允许 `genarrative` 读取，Nginx 也可能仍占用 `80/443`。另一个常见误区是 API release 只带 `pingora-direct-enable.sh` / rollback 壳脚本，却漏带 `pingora-current-release-audit.mjs`、`pingora-direct-rehearsal-status.mjs`、`check-pingora-direct-preflight.mjs`、`check-pingora-direct-live.mjs`、`deploy/systemd/`、`deploy/env/` 或 `deploy/pingora/`，导致从 `/opt/genarrative/current` 启用时依赖 Jenkins 工作区、源码 checkout 或 `/etc` 里某份参考模板；或者 release 已经包含新版 `pingora-gateway`，但已运行的 shadow / canary / direct service 没有随 `current` 链接切换重启，仍在跑旧二进制。Server-Provision 安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 的 drop-in 只用于人工审阅和显式覆盖；直连启用脚本默认必须读取 current release 随包 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，否则旧 `/etc` 模板会掩盖发布包缺失。API deploy 脚本本身也不能继续用部署工作区根部的 `scripts/deploy/production-api-deploy.sh`，否则 Jenkins workspace 里的脚本会掩盖 `build/<version>` 发布包缺少 deploy / maintenance 同目录脚本的问题；备份脚本、健康巡检脚本和 env 示例目录同样不能从部署工作区兜底，切换命令证据脚本也不能从部署工作区兜底，否则 current release 会和上游构建归档漂移。Pingora 直连依赖、备份脚本、巡检脚本、env 示例目录和 API deploy 执行入口都必须来自上游发布产物；随包 `api-server.sha256` 和可选 `pingora-gateway.sha256` 也必须复制进 current release，供随包 current release 自审校验二进制；随包 `deploy/pingora/pingora-gateway.env.example` 也不能只检查存在，还要保持 gzip-only、不信任 XFF、前置代理确认关闭、接流保护开启和空 probe token 这些生产安全默认值；`production-api-deploy.sh` 发现缺失时应 fail-fast 并保持维护模式，不应从部署工作区兜底补齐；所有 API 发布包都必须携带 `release-manifest.json` 且登记 `api-server` artifact，发布包包含 Pingora 时还必须登记 `pingora-gateway` artifact，否则 deploy 应在切换 current 前失败；deploy 必须要求 release root、current link 和 api env file 都是绝对路径，release version 以数字或字母开头并拒绝点目录，再先写 staging release，全部复制完成后用非合并语义提升为正式 release，失败时清理 staging 且不留下正式 release，同版本 release 已存在、提升前竞态出现或 current 路径不是符号链接时拒绝覆盖 / 合并，避免旧文件混入 current；发布包包含 Pingora 时，deploy 必须先确认 systemd 最终配置没有 direct-entry `CAP_NET_BIND_SERVICE`、env 仍是 `127.0.0.1:18081` shadow 且未配置 `TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，再提升 release、切换 current 并 `restart` Pingora shadow；配置不安全时必须在切换 current 前失败并保持维护模式。
-- 处理：确认真实 TLS 证书和 redirect env 已写入 `/etc/genarrative/pingora-gateway.env`、service 模板和 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含这份 env、当前执行用户和 `genarrative-pingora-gateway.service` 的 `User=` 服务用户都能读取证书链 / 私钥、current release 的 `pingora-gateway` 已存在且可执行、Nginx 或其它进程已释放 `80/443` 后，先用 `npm run plan:pingora-direct-cutover -- --require-direct ...` 生成只读 JSON runbook，并逐条审阅 Host 与回退巡检入口确认、current release 自包含自审、current release preflight、启用前基础 readiness、direct enable dry-run、direct enable apply、启用后 `--require-direct` 复核、rollback dry-run、rollback apply、回退后 health patrol 切回 Nginx 并恢复切换前 public base URL / Host、回退后 health patrol env 复核；runbook 只用于审阅，不修改系统。正式 runbook 中 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同，避免 redirect 或回退 smoke 各自验证到不同入口；同时必须提供 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，若切换前 Nginx 巡检需要 Host 覆盖，再追加 `--rollback-health-patrol-public-host <切换前Host>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退 runbook 把现场巡检入口覆盖成仓库默认值；如需把回退后 Pingora shadow 探针复核纳入 runbook，追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，JSON 输出会隐藏 token 原文。随后先执行 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show`，再 dry-run `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status`，最后执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，由脚本先跑 direct preflight，再安装 drop-in、reload systemd、重启 Pingora，并用 `systemctl cat` 核验 capability 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已生效、用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板里的 current release `pingora-gateway`、用 `systemctl is-active` 确认服务 active，再以 JSON 模式执行 direct live smoke，验证 HTTPS / HTTP redirect / ACME / WSS 101 和 Pingora access log request_id 落盘，并要求 `direct-access-log` 结构化结果 `matchedCount == checked`、`missingCount=0`、`mismatchCount=0`；如果 direct live 退出 0 但缺少该结构化证据，也必须视为启用失败。直连启用后同步调整 `/etc/genarrative/health-patrol.env`：设置 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct`，本机打 `127.0.0.1` 时设置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`，否则巡检会继续按 Nginx 模式误报。验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名>` 或 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名>`；回退脚本先跑 `nginx -t`，通过后才移除 drop-in、reload systemd、重启 Pingora，并用 `systemctl cat` 核验 capability 已移除、用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板里的 current release `pingora-gateway`，随后 reload Nginx、确认 Nginx service 仍为 active，并用 curl smoke URL 证明公网入口已回到 Nginx；回退脚本 `--apply` 不允许省略 `--reload-nginx` 或 `--nginx-smoke-url`，当 smoke URL 指向本机地址时必须同时提供 `--nginx-smoke-host <域名>`，且 host 值不能包含 URL、路径或查询；回退后把 health patrol gateway mode 改回 `nginx`，恢复切换前 public base URL / Host，并用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs --env-file /etc/genarrative/health-patrol.env --expected-gateway-mode nginx --expected-public-base-url <切换前Nginx巡检入口> --require-empty-public-host` 复核；若切换前 Nginx 巡检需要 Host 覆盖，则把 `--require-empty-public-host` 换成 `--expected-public-host <切换前Host>`。若 env 已在回退命令前切回 Nginx，也可给 rollback 脚本追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 让它在 Nginx smoke 后自动复核；切换前 Nginx 巡检需要 Host 覆盖时把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`。若要同时证明 Pingora shadow 高端口仍活着，追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应为 `gateway=pingora-shadow`。
+- 处理：确认真实 TLS 证书和 redirect env 已写入 `/etc/genarrative/pingora-gateway.env`、service 模板和 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含这份 env、当前执行用户和 `genarrative-pingora-gateway.service` 的 `User=` 服务用户都能读取证书链 / 私钥、current release 的 `pingora-gateway` 已存在且可执行、Nginx 或其它进程已释放 `80/443` 后，先用 `npm run plan:pingora-direct-cutover -- --require-direct ...` 生成只读 JSON runbook，并逐条审阅 Host 与回退巡检入口确认、current release 自包含自审、current release preflight、启用前基础 readiness、direct enable dry-run、direct enable apply、启用后 `--require-direct` 复核、rollback dry-run、rollback apply、回退后 health patrol 切回 Nginx 并恢复切换前 public base URL / Host、回退后 health patrol env 复核；runbook 只用于审阅，不修改系统。正式 runbook 中 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同，避免 redirect 或回退 smoke 各自验证到不同入口；同时必须提供 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，若切换前 Nginx 巡检需要 Host 覆盖，再追加 `--rollback-health-patrol-public-host <切换前Host>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退 runbook 把现场巡检入口覆盖成仓库默认值；如需把回退后 Pingora shadow 探针复核纳入 runbook，追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，JSON 输出会隐藏 token 原文。随后先执行 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show`，再 dry-run `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status`，最后执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，由脚本先跑 direct preflight，再安装 drop-in、reload systemd、重启 Pingora，并用 `systemctl cat` 核验 capability 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已生效、用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板里的 current release `pingora-gateway`、用 `systemctl is-active` 确认服务 active，再以 JSON 模式执行 direct live smoke，验证 HTTPS / HTTP redirect / ACME / WSS 101 和 Pingora access log request_id 落盘，并要求 `direct-access-log` 结构化结果 `matchedCount == checked`、`missingCount=0`、`mismatchCount=0`；如果 direct live 退出 0 但缺少该结构化证据，也必须视为启用失败。直连启用后同步调整 `/etc/genarrative/health-patrol.env`：设置 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct`，本机打 `127.0.0.1` 时设置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`，否则巡检会继续按 Nginx 模式误报。验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'` 或 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`；回退脚本先跑 `nginx -t`，通过后才移除 drop-in、reload systemd、重启 Pingora，并用 `systemctl cat` 核验 capability 已移除、用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板里的 current release `pingora-gateway`，随后 reload Nginx、确认 Nginx service 仍为 active，并用 curl smoke URL 证明公网入口已回到 Nginx；回退 smoke URL/body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`；回退脚本 `--apply` 不允许省略 `--reload-nginx` 或 `--nginx-smoke-url`，当 smoke URL 指向本机地址时必须同时提供 `--nginx-smoke-host <域名>`，且 host 值不能包含 URL、路径或查询；回退后把 health patrol gateway mode 改回 `nginx`，恢复切换前 public base URL / Host，并用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs --env-file /etc/genarrative/health-patrol.env --expected-gateway-mode nginx --expected-public-base-url <切换前Nginx巡检入口> --require-empty-public-host` 复核；若切换前 Nginx 巡检需要 Host 覆盖，则把 `--require-empty-public-host` 换成 `--expected-public-host <切换前Host>`。若 env 已在回退命令前切回 Nginx，也可给 rollback 脚本追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 让它在 Nginx smoke 后自动复核；切换前 Nginx 巡检需要 Host 覆盖时把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`。若要同时证明 Pingora shadow 高端口仍活着，追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应为 `gateway=pingora-shadow`。
 - 处理补充：不要直接 chmod `/etc/letsencrypt/live` 或 `archive` 来让 Pingora 读取证书；Certbot live 路径通常是 symlink，即使 `stat -L` 看起来是普通文件，父目录权限也会让非 root `genarrative` 用户不可达。先用随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-tls-cert-sync.mjs --apply --source-cert-file /etc/letsencrypt/live/<域名>/fullchain.pem --source-key-file /etc/letsencrypt/live/<域名>/privkey.pem --target-dir /etc/genarrative/pingora-tls/<域名>` 把证书同步到 Pingora 私有目录，再让 `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE` 指向 `/etc/genarrative/pingora-tls/<域名>/fullchain.pem` 和 `privkey.pem`。脚本默认 dry-run，`--apply` 才写入，目标目录默认 `root:genarrative 0750`，文件默认 `root:genarrative 0640`，并拒绝符号链接目标目录或目标文件。
 - 处理补充：不要在切换窗口手工编辑 `/etc/genarrative/health-patrol.env` 的三项网关变量；使用 `node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply --env-file /etc/genarrative/health-patrol.env --gateway-mode pingora-direct --public-base-url <直连HTTPS入口> --public-host <域名>` 切到直连，回退前用同一脚本传 `--gateway-mode nginx --public-base-url <切换前Nginx巡检入口>` 并按切换前记录选择 `--clear-public-host` 或 `--public-host <切换前Host>`。脚本只改 gateway mode / public base URL / public Host，并立即复用随包 env 复核脚本，减少空 Host 和旧值残留；生产巡检、env 复核和 env 切换脚本读取的布尔 env 都必须是明确布尔值，非法值直接失败，不能把拼写错误当成 false；env 复核脚本的 `--env-file` 与 env 切换脚本的 `--env-file` / `--check-script` 必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本写入的 public base URL / Host 同样不能包含换行或 NUL。Node 22 已内置 `--env-file` 启动参数，直接用 `node script.mjs --env-file ...` 或 shebang 执行 `.mjs --env-file ...` 都可能让 Node 抢走业务参数；所有这类命令都必须写成 `node -- script.mjs --env-file ...`，或通过已内置 `node --` 的 npm script 执行。
 - 踩坑补充：health patrol env 切换脚本必须先复核权限固定为 `0600` 的临时目标 env 再写真实文件，真实 env 原子替换时保持原文件权限和 owner/group；如果随包 env 复核脚本失败，`--apply` 应失败且真实 env 保持原样，避免“切换脚本失败但巡检配置已半改”的状态。`--apply` 的 `--env-file` 必须直接指向真实普通文件，不能传符号链接；如果 `/etc/genarrative/health-patrol.env` 是链接，先确认真实目标路径后再传给脚本，避免替换链接本身或写入非预期目标。
 - 踩坑补充：直连启用脚本的 `--preflight-script`、`--direct-live-script`、`--current-release-audit-script`、`--template-path`、`--service-unit-path`、`--dropin-path` 和 env 文件参数都必须使用绝对路径；不要在切换窗口传相对脚本路径，否则会把 current release、Jenkins 工作区或现场 cwd 混在一起。`--apply` 会在安装 direct-entry drop-in 前确认 current release 自审、direct preflight 和 direct live smoke 脚本存在，缺脚本时应先修发布包或复制链路，不要手工改成工作区相对路径绕过。启用脚本还会在任何自审、preflight、drop-in 写入或 systemctl 前拒绝 service、路径、URL、Host、probe token、access log、数据库名、tail 行数和 timeout 参数中的换行或 NUL 字符；遇到这类失败先修 runbook 参数来源或现场 env，不要手工绕过脚本。启用脚本还会拒绝符号链接形式的 drop-in 目录或 drop-in 目标文件，以及已存在但不是普通文件的目标；如果现场 systemd 目录被软链改写，应先修正真实路径，不要让脚本把低端口 capability 写入非预期位置。回退脚本 `--apply` 同样会在 `nginx -t` 和删除 drop-in 前拒绝 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override 中的换行或 NUL 字符，并拒绝符号链接 drop-in 目录 / 目标以及非普通 drop-in 目标；如果现场路径或参数异常，应先修正 systemd 路径、runbook 参数或现场 env，不要手工删 drop-in、绕过 `nginx -t` 或把删除 symlink 当成已回退真实低端口能力。回退脚本覆盖 `--nginx-binary` 或 `--curl-binary` 时也不要传 `./nginx`、`tools/curl` 这类相对路径；裸命令名可以走 `PATH`，路径形式必须使用绝对路径。`--nginx-smoke-url` 必须带 `http://` 或 `https://`，不要只写 host/path，否则脚本会在移除 drop-in 前失败。
-- 踩坑补充：回退到 Nginx 后不要只把 `curl --fail` / HTTP 200 当作 Nginx 已接回的证据；正式 runbook 默认给 rollback dry-run / apply 传 `--nginx-smoke-expect-body '"ok":true'`，要求 `/healthz` 响应体包含预期片段。若现场把 `--rollback-nginx-smoke-url` 改成其它端点，必须同步调整 `--rollback-nginx-smoke-expect-body`，否则要么误卡回退，要么只验证到了错误入口。
+- 踩坑补充：回退到 Nginx 后不要只把 `curl --fail` / HTTP 200 当作 Nginx 已接回的证据；正式 runbook 必须给 rollback dry-run / apply 显式传切换前真实 Nginx smoke URL 和响应体片段，例如 `--nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`。不要继续用固定 `/healthz` 与 `"ok":true`，否则要么误卡回退，要么只验证到了错误入口。
+- 踩坑修正：上述 `/healthz` 与 `"ok":true` 只能算旧示例，不再是正式 runbook 默认。dev 真实直连 `80/443` 测试确认回退 smoke 必须从切换前真实 Nginx 入口取样，例如 `https://dev.genarrative.world/` 与 `<!doctype html>`；固定 `http://127.0.0.1/healthz` 可能返回 301/404 或命中错误 vhost。回退前还必须把 `/etc/genarrative/pingora-gateway.env` 从 direct 低端口配置恢复为 shadow 高端口配置，否则回退脚本移除 capability 后重启 Pingora 可能继续按 `80/443` 配置失败；恢复 shadow 时不能只清 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，也必须清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE`，避免留下证书路径但无 TLS listener 的半直连 env。
 - 踩坑补充：直连彩排状态脚本不是修复动作。`node -- /opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs --release-root /opt/genarrative/current --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical` 只读检查公网端口归属、health patrol 模式、Pingora shadow、realpath canary、systemd 和 current release 自审；如果它报 `CRITICAL`，应先修发布包、端口归属、canary 配置、health patrol env 或 systemd 指向，不要把它当成会自动启用 canary、停止 Nginx 或修复 current release 的脚本。
 - 踩坑补充：Pingora current release 自审和切换证据链都不是修复动作，`npm run check:pingora-current-release-audit` / `scripts/ops/pingora-current-release-audit.mjs` 只负责只读确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 匹配、release manifest 登记了当前要接流的 Pingora 产物、`pingora-gateway` 可执行和 systemd `ExecStart` 指向；`npm run check:pingora-cutover-status-snapshot` / `scripts/ops/pingora-cutover-status-snapshot.mjs` 只负责输出 `pre-cutover`、`post-enable`、`post-rollback` 三阶段只读 JSON evidence，并在直连 runbook 中通过 `--require-pingora-gateway` 把上述自审结果收录到 `checks.current-release-audit.details`；快照还必须确认 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 精确包含本次 `--pingora-env-file`，否则 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile=false` 且标记 `CRITICAL`，避免证据包读到一份 env、真实服务读另一份 env。正式切换窗口用 `scripts/ops/pingora-cutover-evidence-bundle.mjs` 把快照 JSON、stdout、stderr、命令记录和 manifest 写入 `--output-root` 下的新证据目录，证据包 manifest 必须记录已生成 snapshot、direct live、stdout / stderr、命令记录和 parse-error 文件的 `path`、`sizeBytes` 与 `sha256`，便于归档后复核；证据目录生成、复制或归档后必须用随包 `scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <bundleDir>` 做只读验真，确认 `manifest.files` 登记的文件未缺失、大小未漂移、sha256 未漂移，且证据目录不是符号链接或非目录；三阶段证据分别验真后，还必须用随包 `scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback` 做只读总审计，自动选择每个阶段最新 bundle 并复用 verifier，缺阶段、最新证据损坏、坏 manifest 或符号链接条目都应失败。direct enable apply / rollback apply 必须通过 `scripts/ops/pingora-cutover-command-evidence.mjs` 包装真实脚本，单独保存命令 stdout、stderr、退出码、脱敏命令记录和 manifest，runbook 必须显式传绝对路径 `--output-root`，且该路径不能是文件系统根目录、符号链接或包含换行 / NUL 字符；命令记录必须同时保留脱敏后的可读命令和结构化 `executable` / `args[]`，命令证据 manifest 也必须记录 `command.stdout.txt`、`command.stderr.txt` 和 `command-record.json` 的 `sizeBytes` 与 `sha256`；命令证据生成后也要立即把 stdout 中的 `bundleDir` 填入随包 verifier 的 `<enable-apply-bundle-dir>` 或 `<rollback-apply-bundle-dir>` 占位符做只读验真，不能只等最终根目录总审计才发现 command-record 或 stdout/stderr 归档漂移。启用后证据包必须额外运行随包 direct live smoke，并写入 `direct-live.json`、`direct-live.stdout.txt`、`direct-live.stderr.txt`、`direct-live-command.json` 和 manifest summary 的 `directLiveStatus`，让 Pingora access log `request_id` 反查结果可复盘；`direct-live.json` 的 `direct-access-log` 结果必须保留扫描行数、匹配数量、缺失明细以及 method/path/status 漂移明细，不要只保留 count 或依赖 stderr。证据包 manifest summary 还必须包含 `directLiveAccessLog` 摘要；如果 direct live JSON 缺少 `direct-access-log` 结构化结果，整包应记为 `CRITICAL`。若 snapshot 或 direct live stdout 解析失败，必须保留 `snapshot-parse-error.txt` 或 `direct-live-parse-error.txt` 并在 manifest / 最终 stdout 中给出路径；不要只截图或复制 `pingora-direct-enable.sh` / release readiness 的终端输出当作直连证据。证据阶段名只能使用 ASCII 字母、数字、点、下划线和短横线，非法 `--phase` 会直接失败，不会被清洗后继续落盘；自审、状态快照和证据包的 `--release-root` 都不能是文件系统根目录，状态快照的 `--health-patrol-env-file` / `--pingora-env-file` 以及证据包所有显式路径参数也不能是文件系统根目录，状态快照自身还必须拒绝带换行或 NUL 的 release/env 路径，并在执行 systemctl、current release 自审、health patrol env 复核或生产巡检子命令前复核子命令参数，证据包执行状态快照或 direct live 子命令前也必须拒绝任何带换行或 NUL 字符的子命令参数，避免污染后的结构化 `args[]` 先进入正式证据再等总审计兜底，`--output-root` 及其已存在上级路径不能是符号链接，已存在的 `--output-root` 必须是真实目录，路径异常时会在执行状态快照前失败，避免把证据写入非预期软链目标；current release 自审、状态快照和证据包的显式 `--timeout-ms` 及对应 env 必须是正整数，生产健康巡检的 `--timeout-ms`、`--slow-ms`、`GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS` 和 `GENARRATIVE_HEALTH_PATROL_SLOW_MS`，canary / direct live smoke 的 `--timeout-ms` 及对应 env，canary access log 对账的 `--since-lines` 及对应 env 也必须是正整数，直连 live / release readiness 的布尔 env 也必须是明确布尔值，非法值都会失败，不再静默回退默认值或 false。自审、快照、证据包、证据验真和证据总审计脚本都不修改 `/etc`、systemd、Nginx 或 Pingora；命令证据脚本只执行 `--` 后面的真实命令并归档输出，不自行理解 systemd / Nginx；证据包和命令证据目录必须是 `0750`，证据文件必须是 `0640`，且不能覆盖既有文件；probe token 和其他 env 敏感值只能记录是否存在或显示 `<redacted>`，不能把 env 原文写入终端执行日志、gateway smoke / direct live / direct rollback shadow probe 命令日志、stdout、snapshot、manifest、命令记录或子检查 stdout / stderr；如果自审、快照、direct live 或总审计证据里出现 `CRITICAL`，应先修发布包、Jenkins 归档过滤、deploy 复制、env、systemd capability、直连入口、巡检状态或证据归档，再继续下一阶段，不要把自审、快照或证据包当成可自动修复的烟测。
 - 踩坑补充：直连 Pingora 后不要让静态缓存头继续依赖框架默认值。HTML、目录 index 和 SPA fallback 必须保持 `Cache-Control: no-cache`，否则旧入口页可能长期引用已经切换的 chunk；带 Vite 指纹的 `/assets/*` 和 `/admin/assets/*` 才能使用 `public, max-age=31536000, immutable`；普通非指纹静态和 ACME challenge 继续保守 `no-cache`。如果需要临时覆盖 `GENARRATIVE_PINGORA_GATEWAY_*_CACHE_CONTROL`，值不能包含换行或 NUL，修改后必须跑 `npm run check:pingora-gateway-smoke` 确认 HTML、普通静态和指纹资源三类响应头没有漂移。
@@ -34,9 +35,9 @@
 - 踩坑补充：直连 live smoke 不能只证明根 HTML 返回 `200`。正式发布包的首页通常会引用 `/assets/` 或 `/admin/assets/` 构建产物，direct live 应自动发现静态资源，验证静态缓存 / 校验头、`HEAD` 头响应、`If-None-Match` / `If-Modified-Since` 304 和 `Range: bytes=0-0`，并纳入 access log method/path/status 对账；如果首页存在 Vite 指纹资源，还必须额外证明 `Cache-Control: public, max-age=31536000, immutable` 以及指纹资源 GET / HEAD / 304 / Range 的 access log method/path/status 证据，避免只验证普通 `/assets/app.js` 却漏掉旧 tab chunk 长缓存口径。如果该项显示 skipped，要确认是维护模式、非 HTML，还是发布包首页确实没有资产引用，不要把 skipped 当作已经验证前端静态资源可读。
 - 踩坑补充：不要把 `direct-live.json` 当成只有状态码的摘要。静态 GET / HEAD / 304 / Range 检查必须保留白名单 `headers`，至少能复盘 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`；证据包自测要确认普通静态和 Vite 指纹资源的 `Cache-Control`、`Content-Range` 都被归档。API / WSS 检查不要落原始响应头，避免把认证、Cookie 或上游细节带进切换证据。
 - 踩坑补充：切流证据包不能只把静态头部藏在 `direct-live.json`。`manifest.summary.directLiveStaticHeaders` 必须提升普通静态和 Vite 指纹静态的缓存头、校验头、Range `Content-Range` 和 304 状态摘要，方便切换窗口先扫 manifest 判断证据是否完整；如果 direct live 已输出静态资产结果但摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 或 Last-Modified 304 证据，证据包会直接记为 `CRITICAL`。遇到摘要缺失或 diagnostics 非空时，应重新生成启用后证据包或修复 direct live / 静态响应头，不要手工改 manifest。
-- 踩坑补充：最终证据根目录总审计必须带 `--require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable`，正式 runbook 已默认生成这两个参数。若旧 `post-enable` bundle 虽然 `manifest.summary.status=OK` 但没有 `directLiveAccessLog` 或 `directLiveStaticHeaders`，总审计也应失败；处理方式是用新版 current release 重新生成启用后证据包，不要把旧包混进正式归档。
+- 踩坑补充：最终证据根目录总审计必须带 `--require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-phase-pingora-env-shadow post-rollback`，正式 runbook 已默认生成这些参数。`post-enable` 证据包还必须传 `--expected-pingora-env-mode direct`，`post-rollback` 证据包必须传 `--expected-pingora-env-mode shadow`，否则 health patrol 模式正确也不能证明 active Pingora env 姿态正确。若旧 `post-enable` bundle 虽然 `manifest.summary.status=OK` 但没有 `directLiveAccessLog` 或 `directLiveStaticHeaders`，或旧 `post-rollback` bundle 没有 `manifest.summary.pingoraEnvShadow`、没有 `mode=shadow` / `shadowReady=true`、仍残留 `tlsCertFile` / `tlsKeyFile`，总审计也应失败；处理方式是用新版 current release 重新生成对应阶段证据包，不要把旧包混进正式归档。
 - 踩坑补充：最终证据根目录总审计失败时先看 JSON 顶层 `summary`，不要直接在长 `phases[]` / `commands[]` 里翻。`summary.failedItems[]` 会聚合失败阶段、命令、根目录或时间线诊断，`summary.directLiveEvidence[]` 会直接给出 `post-enable` 的 `accessLog.ok/reason` 与 `staticHeaders.ok/reason`；reason 指向缺摘要或字段不完整时，应重新生成启用后证据包，而不是手工补 manifest。
-- 踩坑补充：最终证据根目录总审计命令示例也必须包含两条 `--require-command-executable`，分别绑定 current release 随包 `pingora-direct-enable.sh` 和 `pingora-direct-rollback.sh`。不要只写 `--require-command` 和 `--require-command-arg --apply`，否则只能证明有命令证据和参数，不能证明真实执行的是本次 current release 脚本。发布包级 `npm run check:production-api-release` 会同时检查生成 README 和随包 readiness dry-run cutover 输出，若这里失败，先修发布包构建脚本或随包 readiness 脚本，不要只改源码文档。
+- 踩坑补充：最终证据根目录总审计命令示例也必须包含五条 `--require-command-executable`，分别绑定 current release 随包 `pingora-direct-enable.sh`、`pingora-health-patrol-env-switch.mjs`、`pingora-gateway-env-shadow-switch.mjs`、`pingora-health-patrol-env-switch.mjs` 和 `pingora-direct-rollback.sh`。不要只写 `--require-command` 和 `--require-command-arg --apply`，否则只能证明有命令证据和参数，不能证明真实执行的是本次 current release 脚本。发布包级 `npm run check:production-api-release` 会同时检查生成 README 和随包 readiness dry-run cutover 输出，若这里失败，先修发布包构建脚本或随包 readiness 脚本，不要只改源码文档。
 - 踩坑补充：直连 Pingora 后也不要只看前端页面和 access log 成功。API 上游必须继续收到 Nginx 口径代理头：`Host`、`X-Forwarded-Host`、配置化 `X-Forwarded-Proto`、TCP 对端 IP 的 `X-Real-IP`，以及追加 TCP 对端 IP 的 `X-Forwarded-For`。`TRUST_X_FORWARDED_FOR` 只用于接流保护 client key；如果误以为它会改变上游 `X-Real-IP` 或覆盖上游 `X-Forwarded-For`，容易造成回调 URL、鉴权来源或日志归因排查漂移。修改代理头逻辑后先跑 `npm run check:pingora-gateway-smoke`，让 mock 上游回显这些头。
 - 踩坑补充：current release 自审开启 `--systemd-show` 时，带换行或 NUL 的 `--release-root` / `--systemd-service` 必须在执行 `systemctl show` 前失败，不能把污染参数写进子命令或后续证据链。遇到这类失败先修 runbook 参数来源，不要用 `--warn-only` 继续采集。
 - 踩坑补充：canary live 的 `--base-url`、`--prefix`、`--host`、`--path`、`--timeout-ms` 和对应 env 如果包含换行或 NUL，必须在发起 canary 请求前失败，不能让污染参数进入 URL、Host header 或 JSON 输出。遇到这类失败先修目标机 env、runbook 参数来源或手工命令，不要用只看 `X-Genarrative-Nginx-Handoff` 的 curl 替代完整 `npm run check:pingora-canary-live`。
@@ -48,18 +49,19 @@
 - 踩坑补充：不要把即时证据验真理解成只验 hash。正式 runbook 中 `pre-cutover`、`enable-apply`、`post-enable`、`rollback-apply`、`post-rollback` 五个即时 verifier 步骤都必须带 `--require-summary-ok`，同时要求 `manifest.schemaVersion=1`、`manifest.files` 未漂移且 `manifest.summary.status=OK`；如果证据包已经记录 `CRITICAL`、缺少 schemaVersion 或缺少 summary，应先修复现场状态、发布包、env、systemd、health patrol 或 direct live 证据并重新归档，不能继续推进到最终总审计。
 - 踩坑补充：最终证据根目录总审计复用 verifier 时也必须启用 `--require-summary-ok`。如果总审计输出里 `verify.requireSummaryOk` 不是 `true`，说明脚本或随包 verifier 已经退化成宽松模式，应先修发布包脚本而不是继续切换。
 - 踩坑补充：不要用带 `manifest.commandName` 的命令证据目录满足 `--require-phase`。阶段证据必须来自状态快照证据包，命令证据必须通过 `--require-command` 单独要求；否则总审计可能把“真实执行过命令”和“某阶段状态已归档”混成一件事。
-- 踩坑补充：证据根目录总审计不能只要求三阶段状态快照，也不能只做 sha256 验真。正式 runbook 必须在 `--require-phase pre-cutover --require-phase post-enable --require-phase post-rollback` 之外，再传 `--require-command enable-apply:pingora-direct-enable-apply --require-command rollback-apply:pingora-direct-rollback-apply`，用 `manifest.phase + manifest.commandName` 锁定真实 enable / rollback apply 命令证据；缺命令证据、最新命令证据损坏、阶段或命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`、命令名不安全，或顶层 `manifest.commandName` / 内嵌 `manifest.command.name` 任一为空、非法、互不一致时都必须失败。
-- 踩坑补充：`commandName` 只能说明证据分类，不能证明真的跑了 enable / rollback 脚本。正式 runbook 的命令证据必须传 `--expected-executable` 绑定 current release 随包脚本绝对路径，并传 `--require-arg --apply` 在执行前确认真实命令参数包含 `--apply`；如果真实命令与预期脚本不一致或缺少 `--apply`，命令证据脚本应在创建正式命令证据前失败，避免把错误命令归档成正式切换证据。最终证据根目录总审计还必须传 `--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`、`--require-command-arg enable-apply:pingora-direct-enable-apply:--apply` 和 `--require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply`，复核 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` 的 executable，并要求 `manifest.commandName` 与 `manifest.command.name` 只要存在就各自是安全非空命令名、两者同时存在时一致、`manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，且每个 args 字符串都不含换行或 NUL 字符。`--require-command-executable` 的 executable 段必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符；总审计 JSON 会记录 `requiredCommandExecutables`，便于复盘本次绑定的真实 current release 随包脚本。总审计还会要求 `manifest.command` 与 `command-record.json` 关键字段一致；其中两份命令记录的 `schemaVersion` 都必须是 `1`，`stdoutPath` / `stderrPath` 必须同时与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 对齐，不能把重新计算过 hash 的 command-record 指向另一份输出文件；`args` / `command` 也必须一致，不能只保证脚本路径正确却把 `--apply` 证据改成 `--dry-run` 或其它参数；命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`；旧证据缺少 schemaVersion、缺少 expectedExecutable、缺少必需 `--apply` 参数、人工同名证据 executable 漂移、manifest 与 command-record 语义漂移、命令 stdout / stderr 引用漂移、命令参数漂移、命令参数控制字符污染、命令时间线漂移或同一命令重复绑定不同脚本路径都必须失败。
+- 踩坑补充：证据根目录总审计不能只要求三阶段状态快照，也不能只做 sha256 验真。正式 runbook 必须在 `--require-phase pre-cutover --require-phase post-enable --require-phase post-rollback` 之外，再传 `--require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply`，用 `manifest.phase + manifest.commandName` 锁定五条真实切换命令证据；缺命令证据、最新命令证据损坏、阶段或命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`、命令名不安全，或顶层 `manifest.commandName` / 内嵌 `manifest.command.name` 任一为空、非法、互不一致时都必须失败。
+- 踩坑补充：`commandName` 只能说明证据分类，不能证明真的跑了 enable / rollback 脚本。正式 runbook 的命令证据必须传 `--expected-executable` 绑定 current release 随包脚本绝对路径，并传 `--require-arg --apply` 在执行前确认真实命令参数包含 `--apply`；如果真实命令与预期脚本不一致或缺少 `--apply`，命令证据脚本应在创建正式命令证据前失败，避免把错误命令归档成正式切换证据。最终证据根目录总审计还必须传五条 `--require-command-executable` 和七条 `--require-command-arg`，覆盖 enable apply、health patrol direct env switch、Pingora gateway shadow env switch、health patrol nginx env switch 和 rollback apply，其中包含 `enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh` 以及对应 `--apply`、`pingora-direct`、`nginx` 参数要求，复核 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` 的 executable，并要求 `manifest.commandName` 与 `manifest.command.name` 只要存在就各自是安全非空命令名、两者同时存在时一致、`manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，且每个 args 字符串都不含换行或 NUL 字符。`--require-command-executable` 的 executable 段必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符；总审计 JSON 会记录 `requiredCommandExecutables`，便于复盘本次绑定的真实 current release 随包脚本。总审计还会要求 `manifest.command` 与 `command-record.json` 关键字段一致；其中两份命令记录的 `schemaVersion` 都必须是 `1`，`stdoutPath` / `stderrPath` 必须同时与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 对齐，不能把重新计算过 hash 的 command-record 指向另一份输出文件；`args` / `command` 也必须一致，不能只保证脚本路径正确却把 `--apply` 证据改成 `--dry-run` 或其它参数；命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`；旧证据缺少 schemaVersion、缺少 expectedExecutable、缺少必需 `--apply` 参数、人工同名证据 executable 漂移、manifest 与 command-record 语义漂移、命令 stdout / stderr 引用漂移、命令参数漂移、命令参数控制字符污染、命令时间线漂移或同一命令重复绑定不同脚本路径都必须失败。
 - 踩坑补充：命令证据里 `expectedExecutable` 字段不能用空字符串或相对路径表示“未知”。`manifest.expectedExecutable` 和 `manifest.command.expectedExecutable` 只要存在就必须是安全绝对路径；否则总审计应把 manifest 判坏，避免坏顶层字段被内嵌字段兜底，或坏内嵌字段被 command-record 里的路径掩盖。生成端 `--expected-executable` 也不能填 `/` 或带换行 / NUL 的路径，脚本会在执行真实命令前失败，不能用坏 expected path 先生成证据再交给总审计兜底。
 - 踩坑补充：不能只检查 `manifest.command.executable` 与 `command-record.json.executable` 两边一致；如果命令证据已经声明 `expectedExecutable`，真实 `executable` 必须同时等于该预期路径，并且必须是绝对路径。否则人工修改两份命令记录为同一个错误脚本或相对路径，也可能伪造成一致证据。
 - 踩坑补充：命令证据的 `command` 字符串是给人读的，不是结构化身份事实。`manifest.command.executable` 和 `command-record.json.executable` 都必须存在且是绝对路径；缺少结构化 executable 时，即使 `command` 字符串看起来包含正确脚本，也不能作为正式切换证据。
 - 踩坑补充：生成命令证据时不要写 `-- node script.mjs ...`、`-- bash script.sh ...` 或 `-- pingora-direct-enable.sh ...`。`pingora-cutover-command-evidence.mjs` 现在要求 `-- <command>` 本身就是绝对路径，且不能是文件系统根目录；真实命令和每个真实命令参数都不能包含换行或 NUL 字符。正式 runbook 应直接执行 current release 随包脚本的绝对路径，让 manifest 与 command-record 的 `executable` / `args[]` 字段从源头就是可审计事实。
 - 踩坑补充：不要把 Pingora 日志、env、drop-in、脚本或 release root 路径填成 `/` 来“先跑通参数”。release readiness 的 `--live-nginx-access-log` / `--live-pingora-access-log` / `--direct-pingora-access-log` / `--direct-health-patrol-env-file` / `--direct-preflight-env-file`，canary 对账脚本的 `--nginx-log-file` / `--pingora-log-file`，direct live 的 `--pingora-access-log`，direct preflight 的 `--env-file`，以及 `pingora-direct-enable.sh` / `pingora-direct-rollback.sh` 的显式路径参数都必须是绝对文件路径且不能是文件系统根目录；如果现场不确定真实日志、env、drop-in 或脚本文件，先查 `systemctl cat`、logrotate、发布包 manifest 或服务 env，而不是用 `/` 占位。
-- 踩坑补充：证据根目录总审计选择“每类最新证据”后，还必须证明这些证据来自同一次切换时间线。最新证据选择和标准五段时间线证明只接受 `schemaVersion=1` 且带合法、规范 UTC 毫秒格式 `manifest.generatedAt` 的 manifest，命令记录 `startedAt` / `finishedAt` 也必须是 `new Date().toISOString()` 形式；缺失、非法、省略毫秒、本地时区或其它宽松可解析格式都会直接失败，不能用目录 mtime 兜底；证据目录被复制、归档或恢复后，也必须以 manifest 时间为准。同一阶段或同一命令如果出现多个候选共享最新 `manifest.generatedAt`，总审计会以 `AMBIGUOUS_LATEST` 失败并列出重复目录，不能按目录名排序打平；应重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。标准五段证据都被要求时，每段审计状态都必须是 `OK`，`manifest.generatedAt` 必须满足 `pre-cutover -> enable-apply -> post-enable -> rollback-apply -> post-rollback`，且默认五段跨度不能超过 24 小时；非 OK、倒序或跨度过大都代表可能混入不同切换窗口遗留证据或现场状态未达标，必须失败后重新归档或清理证据根目录。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。确需跨更长维护窗口时，只能在生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让最终总审计 JSON 记录本次放宽后的 `timeline.maxSpanMs` 与实际 `timeline.spanMs`。
-- 踩坑补充：标准五段时间线失败时不要只看顶层 `ok=false` 或 `diagnostics` 文本。`timeline.failedCount` 会按具体失败项累计，`timeline.failureBreakdown` 会把非 OK 证据、缺少时间、cutoverRunId 混入、时间倒序和跨度超限拆开计数；同一次审计可能同时暴露多个证据问题，应逐项修复后重新归档。
-- 踩坑补充：同一天多次演练或切换时，只靠“最新证据”和 24 小时窗口仍可能把两轮证据拼在一起。正式 runbook 会生成或接受 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、enable / rollback apply 命令证据和最终总审计；最终审计必须带 `--require-cutover-run-id <本次cutoverRunId>`，缺少该字段或 ID 不一致时必须失败。即使人工临时总审计忘记带 `--require-cutover-run-id`，标准五段时间线里只要任一证据声明了 `manifest.cutoverRunId`，五段也必须全部声明同一个值，否则总审计失败。
-- 验证：先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，确认 env、drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限、service 二进制可执行性和 80/443 已释放；`systemctl cat genarrative-pingora-gateway.service` 必须显示 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env`；启用脚本 apply 必须先通过 current release 自审，失败时不安装 direct-entry drop-in；还必须带 direct HTTPS / HTTP / Host / redirect host / SpacetimeDB database / Pingora access log 参数，并在重启后直接完成 direct live smoke 和 direct-access-log JSON 证据校验；也可用 release readiness `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free` 把 HTTPS、HTTP redirect / ACME、正式域名 Host/SNI、redirect Location host、Pingora access log request_id 落盘、env 预检、systemd drop-in、service EnvironmentFile 一致性、当前用户和服务用户证书可读、service 二进制可执行、端口释放、显式目标库和 WSS 101 一起纳入硬门禁，并拒绝 `--direct-skip-wss`，避免 TLS 证书只按 `127.0.0.1` 误测、HTTP redirect Location 指错域名、Nginx 仍占用 80/443、service 实际读取另一份 env、root / deploy 用户可读但 systemd 服务用户不可读、current release 缺少可执行 `pingora-gateway`，或 WSS subscribe 隐式打到默认 SpacetimeDB 库。`check-pingora-release-readiness.mjs --help` 的正式直连和只生成 runbook 示例也必须带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，不要让值班人员复制示例后才被 `--require-direct` 拦截。current release 自审、状态快照和证据包的布尔 env 必须是明确布尔值，非法值会失败，不得把拼错的 run / require / fail 开关当成 false。`npm run plan:pingora-direct-cutover -- --require-direct ...` 输出必须包含 Host 与回退巡检入口确认、current release preflight、启用前不带 `--require-direct` 的基础 readiness、direct enable dry-run/apply、启用后带 `--require-direct` 的复核、rollback dry-run/apply、回退后 health patrol 切回 Nginx 并恢复切换前 public base URL / Host、回退后 health patrol env 复核；缺少 `--require-direct`、缺少 `--rollback-health-patrol-public-base-url`、缺少 `--direct-pingora-access-log`、redirect Host 漂移或 rollback smoke Host 漂移时必须失败，避免生成缺少正式直连硬门禁或验证不同入口的切换计划。Host 与回退巡检入口确认步骤必须展示回退后要恢复的 health patrol public base URL / Host。直连后 `genarrative-health-patrol.service` 应使用 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct`，状态 JSON 中 `gatewayMode` 应为 `pingora-direct`，并检查 `genarrative-pingora-gateway.service` 而不是 `nginx.service`；public probe 走 `127.0.0.1` 时应带 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`。回退后 `nginx -t` 必须先通过，`systemctl cat genarrative-pingora-gateway.service` 不应再显示这两条 capability，`systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager` 必须仍指向 current release 的 `pingora-gateway`，`systemctl is-active nginx.service` 应为 `active`，`curl --fail --max-time 5` 访问 `--nginx-smoke-url` 应成功；若 smoke URL 为本机地址必须带 `--nginx-smoke-host <域名>`，证明正式 vhost 已回到 Nginx；随后用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs ...` 复核 health patrol env，必须显示 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 public base URL / Host 与切换前记录一致，shadow probe 可选复核必须返回 `gateway=pingora-shadow`。本机提交前还要运行 `npm run check:pingora-direct-enable`、`npm run check:pingora-direct-rollback`、`npm run check:production-health-patrol`、`npm run check:production-api-release`、`npm run check:pingora-production-release-build` 和 `npm run check:production-api-deploy`，确保脚本默认 dry-run 不会安装或删除 drop-in、current release 自审失败时启用脚本不会安装 drop-in、direct live 退出 0 但缺少 `direct-access-log` 结构化证据时启用失败，API release 布局自包含，真实 Pingora release 二进制能构建并进入发布包，API deploy 从发布产物内执行后 current release 自包含；缺少数据库备份脚本、健康巡检脚本、健康巡检 env 复核脚本、切换命令证据脚本、env 示例目录或 direct live smoke 脚本的发布包都必须部署失败并保持维护模式。正式直连 readiness 必须带 `--direct-health-patrol-env-file /etc/genarrative/health-patrol.env`，并用 `scripts/check-production-health-patrol-env.mjs` 阻断 health patrol 仍停在 Nginx 模式或本机 direct probe 缺少正式 Host；发布包包含 `pingora-gateway` 时，`npm run check:production-api-deploy` 必须覆盖服务 active / inactive 都会在 shadow 配置安全时执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，同时覆盖 direct-entry capability 或公网监听 env 下不会提升 release、不会切 current、不会自动 restart。
+- 踩坑补充：证据根目录总审计选择“每类最新证据”后，还必须证明这些证据来自同一次切换时间线。最新证据选择和标准八段时间线证明只接受 `schemaVersion=1` 且带合法、规范 UTC 毫秒格式 `manifest.generatedAt` 的 manifest，命令记录 `startedAt` / `finishedAt` 也必须是 `new Date().toISOString()` 形式；缺失、非法、省略毫秒、本地时区或其它宽松可解析格式都会直接失败，不能用目录 mtime 兜底；证据目录被复制、归档或恢复后，也必须以 manifest 时间为准。同一阶段或同一命令如果出现多个候选共享最新 `manifest.generatedAt`，总审计会以 `AMBIGUOUS_LATEST` 失败并列出重复目录，不能按目录名排序打平；应重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。标准八段证据都被要求时，每段审计状态都必须是 `OK`，`manifest.generatedAt` 必须满足 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`，且默认八段跨度不能超过 24 小时；非 OK、倒序或跨度过大都代表可能混入不同切换窗口遗留证据或现场状态未达标，必须失败后重新归档或清理证据根目录。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。确需跨更长维护窗口时，只能在生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让最终总审计 JSON 记录本次放宽后的 `timeline.maxSpanMs` 与实际 `timeline.spanMs`。
+- 踩坑补充：标准八段时间线失败时不要只看顶层 `ok=false` 或 `diagnostics` 文本。`timeline.failedCount` 会按具体失败项累计，`timeline.failureBreakdown` 会把非 OK 证据、缺少时间、cutoverRunId 混入、时间倒序和跨度超限拆开计数；同一次审计可能同时暴露多个证据问题，应逐项修复后重新归档。
+- 踩坑补充：同一天多次演练或切换时，只靠“最新证据”和 24 小时窗口仍可能把两轮证据拼在一起。正式 runbook 会生成或接受 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、五条真实切换命令证据和最终总审计；最终审计必须带 `--require-cutover-run-id <本次cutoverRunId>`，缺少该字段或 ID 不一致时必须失败。即使人工临时总审计忘记带 `--require-cutover-run-id`，标准八段时间线里只要任一证据声明了 `manifest.cutoverRunId`，八段也必须全部声明同一个值，否则总审计失败。
+- 验证：先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，确认 env、drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限、service 二进制可执行性和 80/443 已释放；`systemctl cat genarrative-pingora-gateway.service` 必须显示 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env`；启用脚本 apply 必须先通过 current release 自审，失败时不安装 direct-entry drop-in；还必须带 direct HTTPS / HTTP / Host / redirect host / SpacetimeDB database / Pingora access log 参数，并在重启后直接完成 direct live smoke 和 direct-access-log JSON 证据校验；也可用 release readiness `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable` 把 HTTPS、HTTP redirect / ACME、正式域名 Host/SNI、redirect Location host、Pingora access log request_id 落盘、env 预检、systemd drop-in、service EnvironmentFile 一致性、当前用户和服务用户证书可读、service 二进制可执行、显式目标库和 WSS 101 一起纳入硬门禁，并拒绝 `--direct-skip-wss`，避免 TLS 证书只按 `127.0.0.1` 误测、HTTP redirect Location 指错域名、service 实际读取另一份 env、root / deploy 用户可读但 systemd 服务用户不可读、current release 缺少可执行 `pingora-gateway`，或 WSS subscribe 隐式打到默认 SpacetimeDB 库。`check-pingora-release-readiness.mjs --help` 的正式直连和只生成 runbook 示例也必须带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，不要让值班人员复制示例后才被 `--require-direct` 拦截。current release 自审、状态快照和证据包的布尔 env 必须是明确布尔值，非法值会失败，不得把拼错的 run / require / fail 开关当成 false。`npm run plan:pingora-direct-cutover -- --require-direct ...` 输出必须包含 Host 与回退巡检入口确认、current release preflight、启用前不带 `--require-direct` 的基础 readiness、direct enable dry-run/apply、启用后带 `--require-direct` 的复核、rollback dry-run/apply、回退后 health patrol 切回 Nginx 并恢复切换前 public base URL / Host、回退后 health patrol env 复核；缺少 `--require-direct`、缺少 `--rollback-health-patrol-public-base-url`、缺少 `--direct-pingora-access-log`、redirect Host 漂移或 rollback smoke Host 漂移时必须失败，避免生成缺少正式直连硬门禁或验证不同入口的切换计划。Host 与回退巡检入口确认步骤必须展示回退后要恢复的 health patrol public base URL / Host。直连后 `genarrative-health-patrol.service` 应使用 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=pingora-direct`，状态 JSON 中 `gatewayMode` 应为 `pingora-direct`，并检查 `genarrative-pingora-gateway.service` 而不是 `nginx.service`；public probe 走 `127.0.0.1` 时应带 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>`。回退后 `nginx -t` 必须先通过，`systemctl cat genarrative-pingora-gateway.service` 不应再显示这两条 capability，`systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager` 必须仍指向 current release 的 `pingora-gateway`，`systemctl is-active nginx.service` 应为 `active`，`curl --fail --max-time 5` 访问 `--nginx-smoke-url` 应成功；若 smoke URL 为本机地址必须带 `--nginx-smoke-host <域名>`，证明正式 vhost 已回到 Nginx；随后用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs ...` 复核 health patrol env，必须显示 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 public base URL / Host 与切换前记录一致，shadow probe 可选复核必须返回 `gateway=pingora-shadow`。本机提交前还要运行 `npm run check:pingora-direct-enable`、`npm run check:pingora-direct-rollback`、`npm run check:production-health-patrol`、`npm run check:production-api-release`、`npm run check:pingora-production-release-build` 和 `npm run check:production-api-deploy`，确保脚本默认 dry-run 不会安装或删除 drop-in、current release 自审失败时启用脚本不会安装 drop-in、direct live 退出 0 但缺少 `direct-access-log` 结构化证据时启用失败，API release 布局自包含，真实 Pingora release 二进制能构建并进入发布包，API deploy 从发布产物内执行后 current release 自包含；缺少数据库备份脚本、健康巡检脚本、健康巡检 env 复核脚本、切换命令证据脚本、env 示例目录或 direct live smoke 脚本的发布包都必须部署失败并保持维护模式。正式直连 readiness 必须带 `--direct-health-patrol-env-file /etc/genarrative/health-patrol.env`，并用 `scripts/check-production-health-patrol-env.mjs` 阻断 health patrol 仍停在 Nginx 模式或本机 direct probe 缺少正式 Host；发布包包含 `pingora-gateway` 时，`npm run check:production-api-deploy` 必须覆盖服务 active / inactive 都会在 shadow 配置安全时执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，同时覆盖 direct-entry capability 或公网监听 env 下不会提升 release、不会切 current、不会自动 restart。
 - 顺序补充：正式 runbook 必须先通过 health patrol env 切换脚本预置回 Nginx 和切换前 public base URL / Host，再执行 `rollback apply`；回退脚本内置 env 复核和独立 env 复核都会阻断 public base URL / Host 漂移。
+- 顺序补充：正式 runbook 还必须在 `rollback apply` 前预置 Pingora shadow env。启用前和 `--dry-run-cutover` 要求 `80/443` 空闲；启用后 `--require-direct` 复核不再要求端口空闲，因为端口应由 Pingora 占用。回退时要先用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 恢复 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081` 并清空 TLS / HTTP redirect 低端口监听，再移除 direct-entry drop-in 和重启 Pingora。
 - 关联：`deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`deploy/env/health-patrol.env.example`、`deploy/env/pingora-direct-live.env.example`、`deploy/env/pingora-canary-live.env.example`、`scripts/deploy/pingora-direct-enable.sh`、`scripts/deploy/pingora-direct-rollback.sh`、`scripts/deploy/pingora-tls-cert-sync.mjs`、`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`scripts/ops/pingora-cutover-command-evidence.mjs`、`scripts/ops/pingora-cutover-evidence-verify.mjs`、`scripts/ops/pingora-cutover-evidence-audit.mjs`、`scripts/jenkins-server-provision.sh`、`scripts/build-production-release.sh`、`scripts/deploy/production-api-deploy.sh`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
 
 ## 外部生成 worker 业务失败重试会撞上钱包扣退费幂等
@@ -2358,6 +2360,14 @@
 - 验证：`npm run check:pingora-gateway-smoke` 必须覆盖静态 `HEAD`、`If-None-Match` 304、`If-Modified-Since` 304，并用 access log method/path/status 对账证明本地静态边界进入日志证据链；`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml` 必须覆盖 ETag 构造和匹配 helper。
 - 关联：`server-rs/crates/pingora-gateway/src/main.rs`、`scripts/check-pingora-gateway-smoke.mjs`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
 
+## Pingora 静态路径必须按 URL segment 解码
+
+- 现象：dev 页面里部分像素图标加载失败，浏览器直接打开 `/Icons/Admurin%27s%20Pixel%20Items/.../499_Iron_Gear.png` 返回 `200 text/html`，响应体是主站 `index.html`，但服务器磁盘上真实 PNG 文件存在。
+- 原因：浏览器请求中的空格和英文撇号会变成 `%20` / `%27`；Pingora 静态文件解析如果直接把编码后的 path 当磁盘路径查找，就会错过真实文件，并继续落到 SPA fallback，最终让图片解码看到 HTML。
+- 处理：静态路径按 `/` 拆分 URL segment 后逐段 percent-decode；解码后拒绝 `/`、`\`、NUL、`..` 和非法 `%` 编码，既能读取带空格 / 撇号的真实文件，又不重新打开目录穿越边界。
+- 验证：`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml` 必须覆盖编码空格 / 撇号、`%2e%2e`、`%2f` 和非法 `%GG`；`npm run check:pingora-gateway-smoke` 必须覆盖编码图标路径返回 `image/png`，并确认危险编码路径仍返回 `404`。dev 切换后用浏览器或 curl 直接验证对应图标 URL 的 `Content-Type` 和 PNG magic bytes。
+- 关联：`server-rs/crates/pingora-gateway/src/main.rs`、`scripts/check-pingora-gateway-smoke.mjs`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
 ## dev health patrol 不能缺少公网 HTTPS 入口配置
 
 - 现象：dev 上 `genarrative-health-patrol.timer` 正常 active，但 `genarrative-health-patrol.service` 最近一次运行失败；Pingora 直连彩排状态脚本只因 `/etc/genarrative/health-patrol.env` 缺失或 public probe 命中 `http://127.0.0.1` 后被 Nginx 301 而报 `CRITICAL`。
@@ -2375,6 +2385,14 @@
 - 验证：先跑 `check-pingora-direct-preflight.mjs --env-file <临时env> --require-live-env --check-cert-readable --check-service-user-cert-readable --check-ports-free --allow-loopback-only`；启动临时 unit 后跑 `check-pingora-direct-live.mjs --https-base-url https://127.0.0.1:18443 --http-base-url http://127.0.0.1:18080 --host <域名> --redirect-host <域名> --redirect-base-url https://<域名> --require-wss-upgrade --pingora-access-log <临时log> --insecure-tls --json`，要求 `OK` 且 `direct-access-log matchedCount == checked`。收尾后复核 `80/443` 仍由 Nginx 监听，正式 Pingora shadow 仍为 `127.0.0.1:18081`。
 - 关联：`scripts/check-pingora-direct-preflight.mjs`、`scripts/check-pingora-direct-live.mjs`、`deploy/pingora/pingora-gateway.env.example`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
 
+## Pingora 直连接管同 IP 多域名前先确认 Host 和证书覆盖
+
+- 现象：dev 上准备让 Pingora 直接绑定 `0.0.0.0:80/443` 时，只按 `dev.genarrative.world` 配置证书和路由会让同 IP 的 `git.genarrative.world` 也进入主站 Pingora 路由，Gitea 可能不可访问；即使补了 Gitea Host 路由，如果仍使用只覆盖 `dev.genarrative.world` 的单域名证书，浏览器和 Git 客户端访问 `git.genarrative.world` 也会遇到证书域名不匹配。
+- 原因：Nginx 原来通过多个 `server_name` vhost 承载主站和 Gitea；当前 Pingora direct listener 默认只有一组 TLS cert/key，且路径路由本身无法区分同一 IP 上的多个域名。
+- 处理：direct env 必须配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world` 与 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000`；TLS 证书必须同时覆盖 `dev.genarrative.world` 和 `git.genarrative.world`，并通过 `pingora-tls-cert-sync.mjs` 同步到 Pingora 私有目录后再指向 env。不要通过“临时释放 Gitea vhost”把 Gitea 从切换窗口里牺牲掉。
+- 验证：本地 `npm run check:pingora-gateway-smoke` 必须覆盖 Gitea Host 整站转发、维护模式不拦截 Gitea Host 和 access log `proxy_target=Gitea`；dev 切换后除 `https://dev.genarrative.world/` 外，还必须验证 `https://git.genarrative.world/` 返回 Gitea，HTTP 到 HTTPS redirect 保留正确 Host，Pingora access log 中有 `host=git.genarrative.world` / `proxy_target=Gitea`。
+- 关联：`server-rs/crates/pingora-gateway/src/main.rs`、`deploy/pingora/pingora-gateway.env.example`、`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
+
 ## SpacetimeDB 连接池租约必须有 Drop 兜底，acquire 不允许无界自旋
 
 - 现象：release 上 api-server 周期性出现全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 业务超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），`/healthz` 仍 200，只有重启能恢复，过若干小时复发。
diff --git a/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md b/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md
index 934f6b28c..4e22e53b8 100644
--- a/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md
+++ b/docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md
@@ -21,6 +21,7 @@
 - 默认开启单进程内接流保护，按客户端 IP 与路由组执行并发上限、RPS 和 burst 限制。保护组默认对齐当前 Nginx：`admin_api=64/30rps/16burst`、`gallery_list=320/5000rps/4096burst`、`gallery_detail=32/300rps/32burst`、`api=64/300rps/64burst`、`spacetime=256/1000rps/256burst`。超限返回 JSON `429` 并带 `Retry-After: 1`。
 - 当前接流保护的默认正式口径是单 Pingora 实例。`GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT` 默认 `1`；若 `GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true` 且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1`，必须先落地共享限流 / 共享并发保护层，并显式设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则网关启动和目标机 direct preflight 都会失败。若关闭网关保护后横向多实例运行，则全局接流保护必须由前置 Nginx / LB 承担。
 - 默认以 TCP 对端 IP 作为限流 client key；只有在 Pingora 前置代理已经清洗 `X-Forwarded-For` 时，才允许开启 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true` 使用首个转发 IP。开启时必须同时设置 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true`，否则网关会拒绝启动。若 Pingora 直接监听公网地址，`TRUST_X_FORWARDED_FOR` 必须保持 `false`，目标机 direct preflight 会在看到公网监听加该开关时失败。
+- 可选配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS` 和 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM` 后，网关会先按 `Host` 归一化匹配 Gitea 域名，命中时整站代理到 Gitea 上游。Gitea 路由不走应用维护页、API 请求体上限或网关接流保护，避免影响 git clone / push。用于同一公网 IP 同时承载 `dev.genarrative.world` 与 `git.genarrative.world` 的直连切换时，TLS 证书必须同时覆盖两个域名；当前单 listener 配置只加载一组 cert/key。
 - 网关启动会做配置校验：监听地址不能和上游地址相同，TLS 入口必须同时给出可读取的证书和私钥文件，HTTP redirect 入口必须依附已配置的 TLS 入口且不能复用同一监听地址，redirect scheme 当前只允许 `https`，`MAX_API_BODY_BYTES` 必须大于 `0`，上游 timeout 必须大于 `0`，`GZIP_LEVEL` 必须在 `0..=9`，`GZIP_MIN_LENGTH_BYTES` 必须大于 `0`，`COMPRESSION_ALGORITHMS` 当前只允许 `gzip`，shadow probe token 不能是占位值或短 token，access log 不能指向目录，`BURST>0` 时对应 `RATE_PER_SECOND` 不能为 `0`，开启网关保护时 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 必须已确认共享保护层。
 - 结构化日志会写入 `request_id`、`method`、`path`、`uri`、`host`、`client_ip`、`status`、`route`、`proxy_target`、`upstream`、`content_length`、`body_bytes_seen` 和 `elapsed_ms`，用于和 Nginx access log 对照 shadow 行为。
 - 配置 `GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE` 后，网关会额外写入 tab-separated access log。影子 systemd 模板默认允许写 `/var/log/genarrative`，Server-Provision 会安装 `deploy/logrotate/genarrative-pingora-gateway` 到 `/etc/logrotate.d/`，避免 canary 日志无限增长。
@@ -58,7 +59,7 @@ npm run check:pingora-cutover-evidence-audit
 npm run check:pingora-release-readiness
 ```
 
-`check:pingora-gateway-smoke` 会临时启动 mock `api-server`、mock SpacetimeDB 和 `pingora-gateway`，覆盖 SPA fallback、后台静态路由、HTML / 普通静态资源 `no-cache`、Vite 指纹静态资源 immutable 缓存、静态 `ETag` / `Last-Modified` 与 `304` 协商缓存、静态 `HEAD` 响应、静态 Range、静态 access log method/path/status 对账、gzip 最小长度、小响应不压缩、图片资源不压缩、大响应压缩、ACME、TLS 直连、HTTP/2 ALPN、HTTP 到 HTTPS 重定向、内部路由拒绝、shadow probe、API 代理头（`Host` / `X-Forwarded-Host` / `X-Forwarded-Proto` / `X-Real-IP` / `X-Forwarded-For`）、请求体上限、429 接流保护、上游断连 / 超时 JSON 错误、维护模式和 SpacetimeDB WebSocket Upgrade，并复用 `check-pingora-direct-live.mjs` 对临时 HTTPS / HTTP redirect / WSS subscribe 入口做 live smoke。该本地 fixture 会让首页同时引用普通静态资源和 Vite 指纹静态资源，direct live JSON 必须确认指纹资源 GET / HEAD / `Range: bytes=0-0` 以及 access log method/path/status 证据，避免正式直连前只证明普通静态读取。排查失败时可追加 `-- --verbose` 输出网关 stderr / stdout；已确认二进制无需重编时可追加 `-- --skip-build`。
+`check:pingora-gateway-smoke` 会临时启动 mock `api-server`、mock SpacetimeDB、mock Gitea 和 `pingora-gateway`，覆盖 SPA fallback、后台静态路由、HTML / 普通静态资源 `no-cache`、Vite 指纹静态资源 immutable 缓存、静态 `ETag` / `Last-Modified` 与 `304` 协商缓存、静态 `HEAD` 响应、静态 Range、静态 access log method/path/status 对账、gzip 最小长度、小响应不压缩、图片资源不压缩、大响应压缩、ACME、TLS 直连、HTTP/2 ALPN、HTTP 到 HTTPS 重定向、内部路由拒绝、shadow probe、API 代理头（`Host` / `X-Forwarded-Host` / `X-Forwarded-Proto` / `X-Real-IP` / `X-Forwarded-For`）、Gitea Host 整站转发、请求体上限、429 接流保护、上游断连 / 超时 JSON 错误、维护模式、维护模式不拦截 Gitea Host 和 SpacetimeDB WebSocket Upgrade，并复用 `check-pingora-direct-live.mjs` 对临时 HTTPS / HTTP redirect / WSS subscribe 入口做 live smoke。该本地 fixture 会让首页同时引用普通静态资源和 Vite 指纹静态资源，direct live JSON 必须确认指纹资源 GET / HEAD / `Range: bytes=0-0` 以及 access log method/path/status 证据，避免正式直连前只证明普通静态读取。排查失败时可追加 `-- --verbose` 输出网关 stderr / stdout；已确认二进制无需重编时可追加 `-- --skip-build`。
 
 `check:pingora-route-parity` 读取 `deploy/pingora/nginx-route-parity.matrix.json`，静态确认生产 / 开发 Nginx 模板、Pingora Rust 路由单测和本文档都覆盖同一组核心路由。`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix` 会读取同一份矩阵，逐条断言 `classify_path` 的路由结果、body limit 和接流保护分组。
 
@@ -103,15 +104,15 @@ node -- /opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs
 该脚本只读读取 health patrol env、Pingora env、`systemctl`、`ss -H -ltnp`、realpath canary 配置和 current release 自审结果，输出 JSON 总览；不会写 `/etc`、不会 reload systemd，也不会修改 Nginx 或 Pingora。`--expect-public-gateway nginx` 会要求公网 `80/443` 仍由 Nginx 监听，`--require-pingora-shadow` 会要求 `127.0.0.1:18081` 由 Pingora shadow 监听，`--require-realpath-canary` 会要求 `127.0.0.1:18083` 有 Nginx realpath canary，`--require-current-release-gateway` 会复用 current release 自审确认 `pingora-gateway`、checksum、manifest 和 systemd `ExecStart`。该脚本用于直连前确认现场状态已经进入“可彩排但未切公网”的安全边界，不替代后续证据包，也不做任何启用或回退动作。
 
 `check:pingora-cutover-status-snapshot` 会烟测 `scripts/ops/pingora-cutover-status-snapshot.mjs` 的只读边界、release artifact 采集、health patrol env 复核、systemd capability / EnvironmentFile 判断和 `--fail-on-critical` 行为。正式切换窗口由 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 调用随包状态快照脚本，按 `--phase pre-cutover`、`--phase post-enable`、`--phase post-rollback` 生成时间戳证据目录，保存 `manifest.json`、`snapshot.json`、`snapshot.stdout.txt`、`snapshot.stderr.txt` 和 `snapshot-command.json`；状态快照 stdout 解析失败时保存 `snapshot-parse-error.txt` 并在 manifest / 最终 stdout 中给出路径，启用后 direct live stdout 解析失败时保存 `direct-live-parse-error.txt` 并同样索引。状态快照会把 `--pingora-env-file` 与 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 做精确匹配，支持 `EnvironmentFile=-/path` 和一行多个文件，但不接受路径前缀误判；未包含本次 pingora env 时 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile=false` 并标记 `CRITICAL`。启用后 direct live 结果中的 `direct-access-log` 必须保留 `scannedLineCount`、`matchedCount`、`missing[]`、`mismatches[]` 以及每个 `request_id` 的预期 / 实际 method、path 与 status，避免证据包只留下计数或终端 stderr；静态 GET / HEAD / 304 / Range 结果还必须在 `direct-live.json` 中保留白名单响应头，字段限于 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`，便于复盘缓存分档、校验器和 Range 语义，同时避免把 API / WSS 原始响应头落进正式证据。证据包还会把 `directLiveAccessLog` 和 `directLiveStaticHeaders` 摘要提升到 `manifest.summary`，前者用于快速确认 request_id 对账，后者用于快速确认普通静态 / Vite 指纹静态的 `Cache-Control`、`ETag`、`Last-Modified`、`Content-Length`、Range `Content-Range` 与 304 状态证据；缺少 `direct-access-log` 结构化结果、缺少可判定的静态头摘要，或静态摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 / Last-Modified 304 证据时，证据包都会直接记为 `CRITICAL`。维护模式、非 HTML 或首页确实没有构建资产引用时，direct live 会把静态检查标记为 skipped，此时允许证据包继续记录跳过原因。`snapshot-command.json` 与 manifest 的 `commands[]` 同时保留脱敏后的可读命令和结构化 `executable` / `args[]`，便于路径或参数包含空格时复盘；证据包在执行状态快照或 direct live 子命令前也会拒绝任何带换行或 NUL 字符的子命令参数，避免污染后的 `args[]` 先落盘再等总审计兜底。`--run-direct-live` 使用的 HTTPS / HTTP base URL、Host、redirect Host、probe token、SpacetimeDB 数据库名、Pingora access log 路径和 access log tail 行数也会在证据包配置层先拒绝换行或 NUL，且 `--direct-pingora-access-log` 必须是绝对路径并且不能是文件系统根目录，避免进入 snapshot 或 direct live 子命令后才暴露参数污染。`--phase` 只允许 ASCII 字母、数字、点、下划线和短横线，非法阶段名直接失败，不做隐式清洗，避免目录名和 manifest 阶段漂移；状态快照和证据包的显式 `--timeout-ms` 以及 `GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS` 必须是正整数，非法值直接失败，不再静默回退默认 `5000`。`GENARRATIVE_HEALTH_PATROL_REQUIRE_EMPTY_PUBLIC_HOST`、`GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_RUN_HEALTH_PATROL`、`GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_REQUIRE_PINGORA_GATEWAY`、`GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_FAIL_ON_CRITICAL` 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败，避免 run / require / fail 开关拼写错误后静默按 false 采集证据。状态快照脚本只读采集 `summary`、`healthPatrolEnv`、`pingoraEnv`、`releaseArtifacts`、`systemd` 和 `checks`；probe token 和其他 env 敏感值只记录是否存在，不输出原文，健康巡检、current release 自审等子检查的 stdout / stderr 在进入快照 JSON 前也必须按 env 敏感值脱敏，证据包里的 manifest、snapshot、stdout 和命令记录都必须通过自测确认不落盘 token 原文；状态快照脚本的 `--release-root`、`--health-patrol-env-file` 和 `--pingora-env-file` 都必须是绝对路径、不能是文件系统根目录，也不能包含换行或 NUL 字符，且执行 systemctl、current release 自审、health patrol env 复核或生产巡检子命令前还会复核子命令参数不含换行或 NUL；证据包脚本只写 `--output-root` 下的新目录，且证据包所有显式路径参数也不能是文件系统根目录，`--output-root` 及其已存在上级路径不能是符号链接，已存在的 `--output-root` 必须是真实目录；路径异常时会在执行状态快照前失败，不写入软链目标、不覆盖既有文件，证据目录权限固定为 `0750`，证据文件权限固定为 `0640`，不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora。
-直连 runbook 的三个证据包阶段都会透传 `--require-pingora-gateway`，让 `checks.current-release-audit.details` 同步归档 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果，避免证据包只有巡检状态而缺少发布物可信度证明。每个证据包生成后都要用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <本阶段bundleDir>` 做只读验真；该脚本只接受 `schemaVersion=1` 的 manifest，并把 `manifest.files` 视为闭集，只读取 `manifest.files` 中的 `{ path, sizeBytes, sha256 }`，拒绝路径逃逸、符号链接证据目录、非目录证据目录、非元数据对象文件条目，以及任何未登记的额外普通文件、目录或符号链接，发现缺文件、大小漂移或 sha256 漂移时退出失败；`--allow-extra-files` 只用于人工排障时显式放行额外条目，正式切换归档不应使用。验真脚本不修改证据目录、不 reload systemd，也不访问 Nginx 或 Pingora。enable apply / rollback apply 的命令证据生成后也要立即用同一个随包 verifier 验真，将上一步 stdout 的 `bundleDir` 分别填入 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>`，确认 `command.stdout.txt`、`command.stderr.txt`、`command-record.json` 与 manifest 元数据一致，再继续后续 health patrol 或回退复核。三阶段证据包都生成并分别验真、enable / rollback apply 命令证据也即时验真后，还要执行 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-command enable-apply:pingora-direct-enable-apply --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000`，由脚本按 `manifest.phase` 找到每个阶段最新证据目录、按 `manifest.phase + manifest.commandName` 找到 enable / rollback apply 最新命令证据，并复核两条真实切换命令都来自 current release 随包脚本；所有候选证据都必须带合法 `manifest.generatedAt`，格式必须是 `new Date().toISOString()` 产出的 UTC 毫秒格式 `YYYY-MM-DDTHH:mm:ss.sssZ`，最新选择和后续时间线证明只使用该字段，不依赖目录 mtime；随后复用随包 verifier 的 `--require-summary-ok` 严格模式再次只读验真，输出可归档的阶段与命令总表；阶段证据必须是不带 `manifest.commandName` 的状态快照证据包，命令证据不能冒充同名 phase 的阶段证据。总审计输出会把阶段 manifest 中的 `directLiveAccessLog` 与 `directLiveStaticHeaders` 一并带到对应 `phases[]` 项，启用后阶段可直接看到 request_id 对账数量、普通静态和指纹静态的缓存头、校验头、Range `Content-Range` 与 304 状态摘要，不必再逐个打开 bundle manifest；正式 runbook 还会通过 `--require-phase-direct-live-access-log post-enable` 和 `--require-phase-direct-live-static-headers post-enable` 把缺少 request_id 对账摘要、缺少静态头摘要、摘要被跳过或摘要缺少缓存头 / 校验头 / Range / 304 证据的启用后证据判为失败，避免旧 post-enable 证据包混入最终归档。总审计的证据根目录默认只能包含带 `manifest.json` 的证据目录，夹带普通文件、无 manifest 子目录或符号链接都会失败，`--allow-extra-root-entries` 只用于人工排障显式放行，正式切换归档不应使用。总审计不只验文件 hash，还要求所有候选证据 `manifest.schemaVersion=1`，阶段证据 `manifest.summary.status=OK`，命令证据 `manifest.summary.status=OK`、`manifest.summary.exitCode=0` 且无 signal；命令证据的顶层 `manifest.commandName` 和内嵌 `manifest.command.name` 只要存在就必须各自是安全非空命令名，且两者同时存在时必须一致，否则按坏 manifest 处理；并在标准五段证据都被要求时校验每段审计状态都是 `OK`，以及 `pre-cutover -> enable-apply -> post-enable -> rollback-apply -> post-rollback` 的 `manifest.generatedAt` 顺序和默认 24 小时最大跨度，防止从不同切换窗口拼出一组看似完整的最新证据；缺失、非法或非规范格式的 `manifest.generatedAt` 会直接失败，不能靠目录 mtime 兜底；最终总审计还会在 `--require-command-arg` 下要求 enable / rollback 命令证据的 `manifest.command.args` 和独立 `command-record.json.args` 都包含 `--apply`，并在 `--require-cutover-run-id` 下要求所有阶段和命令证据的 `manifest.cutoverRunId` 与本次 runbook 一致；确需跨更长维护窗口时，只能在生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让最终总审计 JSON 可见本次放宽值；证据根目录、verifier 路径、阶段名、命令名或 cutover run id 不安全时直接失败。
+直连 runbook 的三个证据包阶段都会透传 `--require-pingora-gateway`，让 `checks.current-release-audit.details` 同步归档 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果，避免证据包只有巡检状态而缺少发布物可信度证明。每个证据包生成后都要用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <本阶段bundleDir>` 做只读验真；该脚本只接受 `schemaVersion=1` 的 manifest，并把 `manifest.files` 视为闭集，只读取 `manifest.files` 中的 `{ path, sizeBytes, sha256 }`，拒绝路径逃逸、符号链接证据目录、非目录证据目录、非元数据对象文件条目，以及任何未登记的额外普通文件、目录或符号链接，发现缺文件、大小漂移或 sha256 漂移时退出失败；`--allow-extra-files` 只用于人工排障时显式放行额外条目，正式切换归档不应使用。验真脚本不修改证据目录、不 reload systemd，也不访问 Nginx 或 Pingora。enable apply / rollback apply 的命令证据生成后也要立即用同一个随包 verifier 验真，将上一步 stdout 的 `bundleDir` 分别填入 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>`，确认 `command.stdout.txt`、`command.stderr.txt`、`command-record.json` 与 manifest 元数据一致，再继续后续 health patrol 或回退复核。三阶段证据包都生成并分别验真、enable / rollback apply 命令证据和三条 env 变更命令证据也即时验真后，还要执行 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:pingora-direct --require-command-arg rollback-prep:pingora-gateway-shadow-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:nginx --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000`，由脚本按 `manifest.phase` 找到每个阶段最新证据目录、按 `manifest.phase + manifest.commandName` 找到五条真实切换命令证据，并复核五条真实切换命令都来自 current release 随包脚本；所有候选证据都必须带合法 `manifest.generatedAt`，格式必须是 `new Date().toISOString()` 产出的 UTC 毫秒格式 `YYYY-MM-DDTHH:mm:ss.sssZ`，最新选择和后续时间线证明只使用该字段，不依赖目录 mtime；随后复用随包 verifier 的 `--require-summary-ok` 严格模式再次只读验真，输出可归档的阶段与命令总表；阶段证据必须是不带 `manifest.commandName` 的状态快照证据包，命令证据不能冒充同名 phase 的阶段证据。总审计输出会把阶段 manifest 中的 `directLiveAccessLog` 与 `directLiveStaticHeaders` 一并带到对应 `phases[]` 项，启用后阶段可直接看到 request_id 对账数量、普通静态和指纹静态的缓存头、校验头、Range `Content-Range` 与 304 状态摘要，不必再逐个打开 bundle manifest；正式 runbook 还会通过 `--require-phase-direct-live-access-log post-enable` 和 `--require-phase-direct-live-static-headers post-enable` 把缺少 request_id 对账摘要、缺少静态头摘要、摘要被跳过或摘要缺少缓存头 / 校验头 / Range / 304 证据的启用后证据判为失败，避免旧 post-enable 证据包混入最终归档。总审计的证据根目录默认只能包含带 `manifest.json` 的证据目录，夹带普通文件、无 manifest 子目录或符号链接都会失败，`--allow-extra-root-entries` 只用于人工排障显式放行，正式切换归档不应使用。总审计不只验文件 hash，还要求所有候选证据 `manifest.schemaVersion=1`，阶段证据 `manifest.summary.status=OK`，命令证据 `manifest.summary.status=OK`、`manifest.summary.exitCode=0` 且无 signal；命令证据的顶层 `manifest.commandName` 和内嵌 `manifest.command.name` 只要存在就必须各自是安全非空命令名，且两者同时存在时必须一致，否则按坏 manifest 处理；并在标准八段证据都被要求时校验每段审计状态都是 `OK`，以及 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback` 的 `manifest.generatedAt` 顺序和默认 24 小时最大跨度，防止从不同切换窗口拼出一组看似完整的最新证据；缺失、非法或非规范格式的 `manifest.generatedAt` 会直接失败，不能靠目录 mtime 兜底；最终总审计还会在 `--require-command-arg` 下要求 enable / rollback 命令证据的 `manifest.command.args` 和独立 `command-record.json.args` 都包含 `--apply`，并在 `--require-cutover-run-id` 下要求所有阶段和命令证据的 `manifest.cutoverRunId` 与本次 runbook 一致；确需跨更长维护窗口时，只能在生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让最终总审计 JSON 可见本次放宽值；证据根目录、verifier 路径、阶段名、命令名或 cutover run id 不安全时直接失败。
 
 正式 runbook 的五个即时验真步骤（`pre-cutover`、`enable-apply`、`post-enable`、`rollback-apply`、`post-rollback`）都必须在随包 verifier 后追加 `--require-summary-ok`，让刚生成的证据包除文件完整性外也立即要求 `manifest.summary.status=OK`；缺少 `summary` 或状态为 `CRITICAL` 时要先修现场状态或重新生成证据，不能等最终根目录总审计才发现。最终 `pingora-cutover-evidence-audit.mjs` 仍是证据根目录、命令身份、`--apply` 参数、时间线和 `cutoverRunId` 的二次总审计，不替代即时验真；它内部复用 verifier 时也必须启用 `--require-summary-ok`。
 
 证据根目录总审计选择每个阶段或命令的“最新证据”时，最新 `manifest.generatedAt` 必须唯一；如果同一阶段或同一命令存在两个或多个候选拥有相同的最新 `generatedAt`，总审计会输出 `AMBIGUOUS_LATEST` 并列出重复目录，不能按目录名排序打平。出现这种情况时应重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后重新总审计。
 
-标准五段时间线只要任一阶段或命令证据带 `manifest.cutoverRunId`，五段就必须全部带同一个值；缺字段或混入其它 `cutoverRunId` 都会让总审计失败。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。正式 runbook 仍必须显式传 `--require-cutover-run-id <本次cutoverRunId>`，这条一致性检查只是防止人工临时总审计忘带该参数时把不同切换批次拼在一起。
+标准八段时间线只要任一阶段或命令证据带 `manifest.cutoverRunId`，八段就必须全部带同一个值；缺字段或混入其它 `cutoverRunId` 都会让总审计失败。八段顺序固定为 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。正式 runbook 仍必须显式传 `--require-cutover-run-id <本次cutoverRunId>`，这条一致性检查只是防止人工临时总审计忘带该参数时把不同切换批次拼在一起。
 
-标准五段时间线失败时，总审计 JSON 的 `timeline.failedCount` 不只是一个笼统红灯，而是按可操作失败项累计；`timeline.failureBreakdown` 会分别输出 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded` 数量，值班人员应按 breakdown 先修对应证据或现场状态，再重新生成总审计。
+标准八段时间线失败时，总审计 JSON 的 `timeline.failedCount` 不只是一个笼统红灯，而是按可操作失败项累计；`timeline.failureBreakdown` 会分别输出 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded` 数量，值班人员应按 breakdown 先修对应证据或现场状态，再重新生成总审计。
 
 最终总审计 JSON 的 `summary` 是切换窗口的人工入口：先看 `summary.status` 和 `summary.failedItems[]` 定位失败阶段、命令或根目录诊断，再看 `summary.directLiveEvidence[]` 里的 `accessLog.ok/reason` 与 `staticHeaders.ok/reason` 判断 `post-enable` 是否缺 request_id 对账或静态头证据；完整字段仍保留在 `phases[]`、`commands[]` 与 `timeline` 中供机器归档和深挖复盘。
 
@@ -123,7 +124,7 @@ node -- /opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs
 
 正式 runbook 的 direct enable apply / rollback apply 命令证据必须额外传 `--expected-executable <current release 随包脚本绝对路径>` 和 `--require-arg --apply`；命令证据脚本会在执行前拒绝与预期脚本不一致、缺少必需 `--apply` 参数，或任一真实命令参数包含换行 / NUL 字符的真实命令，并把 `expectedExecutable` 写入 manifest / command-record。命令名只用于审计分类，不能替代真实脚本身份和真实 apply 参数校验。
 
-最终证据根目录总审计还必须传 `--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`、`--require-command-arg enable-apply:pingora-direct-enable-apply:--apply` 和 `--require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply`，复核命令证据里的 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` 的 executable 都指向 current release 随包脚本，并要求 `manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，且每个 args 字符串都不含换行或 NUL 字符。`--require-command-executable` 的路径参数本身也必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符。总审计还要求 `manifest.command` 与 `command-record.json` 的 schemaVersion / phase / commandName / cutoverRunId / exitCode / signal / startedAt / finishedAt / durationMs / stdoutPath / stderrPath / args / command / cwd / error 等关键字段一致；其中两份命令记录的 `schemaVersion` 都必须是 `1`，stdoutPath / stderrPath 还必须分别与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 指向同一份归档文件，args 与 command 用于证明真实 apply 参数未被替换成 dry-run 或其它动作。命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`。这些参数会隐式要求对应命令证据存在；缺命令证据、旧证据缺少 `schemaVersion` 或 `expectedExecutable`、缺少必需 `--apply` 参数、人工同名证据的 executable 漂移、命令 stdout / stderr 引用漂移、命令参数漂移、命令参数控制字符污染或命令时间线漂移都会失败。
+最终证据根目录总审计还必须传五条真实切换命令的脚本身份和关键参数要求：`--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`--require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`--require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`--require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，并要求 `enable-apply:pingora-direct-enable-apply:--apply`、`post-enable:pingora-health-patrol-direct-env-switch:--apply`、`post-enable:pingora-health-patrol-direct-env-switch:pingora-direct`、`rollback-prep:pingora-gateway-shadow-env-switch:--apply`、`rollback-prep:pingora-health-patrol-nginx-env-switch:--apply`、`rollback-prep:pingora-health-patrol-nginx-env-switch:nginx`、`rollback-apply:pingora-direct-rollback-apply:--apply` 这些 `--require-command-arg` 均存在。总审计会复核命令证据里的 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` 的 executable 都指向 current release 随包脚本，并要求 `manifest.command.args` 与独立 `command-record.json.args` 都包含必需参数，且每个 args 字符串都不含换行或 NUL 字符。`--require-command-executable` 的路径参数本身也必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符。总审计还要求 `manifest.command` 与 `command-record.json` 的 schemaVersion / phase / commandName / cutoverRunId / exitCode / signal / startedAt / finishedAt / durationMs / stdoutPath / stderrPath / args / command / cwd / error 等关键字段一致；其中两份命令记录的 `schemaVersion` 都必须是 `1`，stdoutPath / stderrPath 还必须分别与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 指向同一份归档文件，args 与 command 用于证明真实 apply 参数未被替换成 dry-run 或其它动作。命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`。这些参数会隐式要求对应命令证据存在；缺命令证据、旧证据缺少 `schemaVersion` 或 `expectedExecutable`、缺少必需参数、人工同名证据的 executable 漂移、命令 stdout / stderr 引用漂移、命令参数漂移、命令参数控制字符污染或命令时间线漂移都会失败。
 
 命令证据 manifest 只要出现 `manifest.expectedExecutable` 或 `manifest.command.expectedExecutable` 字段，就必须是安全绝对路径；空字符串、相对路径、文件系统根目录或包含换行 / NUL 的值都会按坏 manifest 处理，不能退化成“未声明 expectedExecutable”。生成端 `pingora-cutover-command-evidence.mjs --expected-executable` 也会在执行真实命令前拒绝相对路径、文件系统根目录和带换行 / NUL 的路径，避免先生成坏命令证据再等最终总审计失败。
 
@@ -166,10 +167,11 @@ node scripts/check-pingora-release-readiness.mjs \
   --direct-preflight-check-cert-readable \
   --direct-preflight-check-service-env-file \
   --direct-preflight-check-service-user-cert-readable \
-  --direct-preflight-check-service-binary-executable \
-  --direct-preflight-check-ports-free
+  --direct-preflight-check-service-binary-executable
 ```
 
+`--require-direct` 用于 Pingora 已接管后的直连复核，不再要求 `--direct-preflight-check-ports-free`；切换前释放 `80/443` 的证明只放在 `--dry-run-cutover`、启用前 preflight 和 `pingora-direct-enable.sh --apply` 中。
+
 正式执行直连切换前先生成只读 runbook，供当班人员逐条审阅。该命令只打印 JSON，不启动检查、不修改 systemd：
 
 ```bash
@@ -190,11 +192,12 @@ npm run plan:pingora-direct-cutover -- \
   --direct-preflight-check-service-binary-executable \
   --direct-preflight-check-ports-free \
   --cutover-evidence-output-root /var/log/genarrative/pingora-cutover-evidence \
-  --rollback-nginx-smoke-url http://127.0.0.1/healthz \
+  --rollback-nginx-smoke-url https://<域名>/ \
+  --rollback-nginx-smoke-expect-body '<!doctype html>' \
   --rollback-health-patrol-public-base-url <切换前Nginx巡检入口>
 ```
 
-runbook 会列出 Host 与回退巡检入口确认、切换前 current release 自包含自审、切换前状态快照证据包、切换前证据 manifest 只读验真、current release 随包 preflight、启用前基础门禁、direct enable dry-run、direct enable apply、启用命令证据 manifest 只读验真、用 current release 随包 `scripts/deploy/pingora-health-patrol-env-switch.mjs --apply` 把 health patrol 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后状态快照证据包、启用后证据 manifest 只读验真、启用后 `--require-direct` 复核、rollback dry-run、用同一脚本在 rollback apply 前把 health patrol 预置回 `nginx`、rollback apply、回退命令证据 manifest 只读验真、回退后 health patrol env Nginx 模式复核、回退后状态快照证据包、回退后证据 manifest 只读验真和切换证据根目录三阶段总审计。rollback dry-run / apply 默认会传 `--nginx-smoke-expect-body '"ok":true'`，因此回退 smoke 不只接受 HTTP 200，还要求 `/healthz` 响应体包含预期片段；若现场回退 smoke URL 换成其它端点，必须显式调整 `--rollback-nginx-smoke-expect-body`。启用前 current release 自审使用 `--require-pingora-gateway --systemd-show`，先确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 匹配、`release-manifest.api-server.json` 已登记 `pingora-gateway`、`pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release；启用前基础门禁不带 `--require-direct`，因为此时 systemd direct-entry drop-in 尚未生效；启用后复核必须带 `--require-direct`，若切换参数提供 `--direct-probe-token`，启用后复核也会继续透传该 token 检查内部探针，JSON runbook 只显示 `<redacted>`。三个状态快照证据包都使用 current release 随包脚本，显式传 `--output-root <证据根目录>` 和同一个 `--cutover-run-id`，并带 `--require-pingora-gateway --run-health-patrol --fail-on-critical`，用于把切换前基线、启用后 direct 状态、回退后 Nginx 状态和当前发布物自审结果留成可归档证据；其中启用后证据包还会额外传 `--run-direct-live`，把 direct live smoke 的 `direct-live.json`、stdout / stderr、命令记录和 Pingora access log `request_id` 反查结果一起写入同一证据目录，且 `direct-access-log` JSON 要保留匹配数量、缺失明细和 method/path/status 漂移明细，避免只在终端输出里保留直连证据；证据包 manifest 会给已生成的 snapshot、direct live、stdout / stderr、命令记录和 parse-error 文件记录 `path`、`sizeBytes` 与 `sha256`，direct enable apply / rollback apply 通过命令证据脚本归档时，命令证据 manifest 也会给 `command.stdout.txt`、`command.stderr.txt` 和 `command-record.json` 同步记录 `sizeBytes` 与 `sha256`。每次复制或归档证据目录后，都要把对应阶段 stdout 中的 `bundleDir` 填入 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <bundleDir>` 做只读验真，确认文件未在归档过程中损坏或被替换；enable / rollback apply 命令证据生成后也要分别把 stdout 中的 `bundleDir` 填入 verifier 的 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>` 占位符，先验真命令证据，再继续 health patrol 切换或回退后复核；三阶段证据和 enable / rollback apply 命令证据都完成并即时验真后，再运行 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-command enable-apply:pingora-direct-enable-apply --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000` 生成总审计 JSON，并在 JSON 中记录 `requiredCutoverRunId`、`requiredCommandExecutables`、`requiredCommandArgs`、`timeline.maxSpanMs` 与 `timeline.spanMs`。若 snapshot 或 direct live stdout 解析失败，证据包会保留对应 `*-parse-error.txt` 并写入 manifest 索引。`--cutover-release-root` 与 `--cutover-evidence-output-root` 必须是绝对路径，且不能是文件系统根目录，证据根目录默认 `/var/log/genarrative/pingora-cutover-evidence`；`--cutover-evidence-timeline-max-span-ms` 默认 `86400000`，仅用于明确批准超过 24 小时的维护窗口。
+runbook 会列出 Host 与回退巡检入口确认、切换前 current release 自包含自审、切换前状态快照证据包、切换前证据 manifest 只读验真、current release 随包 preflight、启用前基础门禁、direct enable dry-run、direct enable apply、启用命令证据 manifest 只读验真、用 current release 随包 `scripts/deploy/pingora-health-patrol-env-switch.mjs --apply` 把 health patrol 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后状态快照证据包、启用后证据 manifest 只读验真、启用后 `--require-direct` 复核、rollback dry-run、用 current release 随包 `scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply` 在 rollback apply 前把 Pingora env 预置回 shadow、用 health patrol env 切换脚本在 rollback apply 前把 health patrol 预置回 `nginx`、rollback apply、回退命令证据 manifest 只读验真、回退后 health patrol env Nginx 模式复核、回退后状态快照证据包、回退后证据 manifest 只读验真和切换证据根目录三阶段总审计。rollback dry-run / apply 必须显式传 `--nginx-smoke-expect-body`，该片段必须来自切换前真实 Nginx 入口响应；dev 实测证明默认 `/healthz` 并不总是公网 Nginx 可用端点，因此不要把 `http://127.0.0.1/healthz` 或固定 `"ok":true` 当作通用回退 smoke。启用前 current release 自审使用 `--require-pingora-gateway --systemd-show`，先确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 匹配、`release-manifest.api-server.json` 已登记 `pingora-gateway`、`pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release；启用前基础门禁不带 `--require-direct`，因为此时 systemd direct-entry drop-in 尚未生效；启用后复核必须带 `--require-direct`，但不再检查 `--direct-preflight-check-ports-free`，因为此时 `80/443` 应由 Pingora 直连入口占用。若切换参数提供 `--direct-probe-token`，启用后复核也会继续透传该 token 检查内部探针，JSON runbook 只显示 `<redacted>`。三个状态快照证据包都使用 current release 随包脚本，显式传 `--output-root <证据根目录>` 和同一个 `--cutover-run-id`，并带 `--require-pingora-gateway --run-health-patrol --fail-on-critical`，用于把切换前基线、启用后 direct 状态、回退后 Nginx 状态和当前发布物自审结果留成可归档证据；其中启用后证据包还会额外传 `--run-direct-live`，把 direct live smoke 的 `direct-live.json`、stdout / stderr、命令记录和 Pingora access log `request_id` 反查结果一起写入同一证据目录，且 `direct-access-log` JSON 要保留匹配数量、缺失明细和 method/path/status 漂移明细，避免只在终端输出里保留直连证据；`post-enable` 证据包会传 `--expected-pingora-env-mode direct`，`post-rollback` 证据包会传 `--expected-pingora-env-mode shadow`。证据包 manifest 会给已生成的 snapshot、direct live、stdout / stderr、命令记录和 parse-error 文件记录 `path`、`sizeBytes` 与 `sha256`，并把 Pingora env 的 `listen`、`tlsListen`、`httpRedirectListen`、`tlsCertFile`、`tlsKeyFile`、`mode` 和 `shadowReady` 提升到 `manifest.summary.pingoraEnvShadow`，用于证明回退后 active env 已恢复到 `127.0.0.1:18081` shadow，且低端口 TLS / HTTP redirect / 证书路径均已清空；direct enable apply / rollback apply 通过命令证据脚本归档时，命令证据 manifest 也会给 `command.stdout.txt`、`command.stderr.txt` 和 `command-record.json` 同步记录 `sizeBytes` 与 `sha256`。每次复制或归档证据目录后，都要把对应阶段 stdout 中的 `bundleDir` 填入 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <bundleDir>` 做只读验真，确认文件未在归档过程中损坏或被替换；enable / rollback apply 命令证据生成后也要分别把 stdout 中的 `bundleDir` 填入 verifier 的 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>` 占位符，先验真命令证据，再继续 health patrol 切换或回退后复核；三阶段证据、enable / rollback apply 命令证据和三条 env 变更命令证据都完成并即时验真后，再运行 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-phase-pingora-env-shadow post-rollback --require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:pingora-direct --require-command-arg rollback-prep:pingora-gateway-shadow-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:nginx --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000` 生成总审计 JSON，并在 JSON 中记录 `requiredCutoverRunId`、`requiredCommandExecutables`、`requiredCommandArgs`、`timeline.maxSpanMs` 与 `timeline.spanMs`。若 snapshot 或 direct live stdout 解析失败，证据包会保留对应 `*-parse-error.txt` 并写入 manifest 索引。`--cutover-release-root` 与 `--cutover-evidence-output-root` 必须是绝对路径，且不能是文件系统根目录，证据根目录默认 `/var/log/genarrative/pingora-cutover-evidence`；`--cutover-evidence-timeline-max-span-ms` 默认 `86400000`，仅用于明确批准超过 24 小时的维护窗口。
 
 runbook 中“启用前基础门禁”和“启用后 `--require-direct` 复核”都调用 current release 随包 `scripts/check-pingora-release-readiness.mjs --release-runtime-only`。前者不带 `--require-direct`，因为 direct-entry drop-in 尚未生效，并会额外跑直连彩排状态复核，确认 Nginx 仍接公网、Pingora shadow / realpath canary 高端口和 current release 自审均可用；后者必须带 `--require-direct`，不再要求 Nginx 接公网彩排状态，并复核 direct preflight、health patrol env 直连模式和 direct live smoke。
 
@@ -205,7 +208,7 @@ runbook 中“启用前基础门禁”和“启用后 `--require-direct` 复核
 最终证据根目录总审计命令必须同时带两条真实脚本身份要求：`--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 和 `--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`。这两个参数的 executable 段必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符；否则总审计会在读取证据前失败，避免把被控制字符污染的审计要求带入正式证据链。总审计 JSON 会记录 `requiredCommandExecutables`，用于复盘本次 enable / rollback apply 证据到底绑定了哪两个 current release 随包脚本。
 
 `--live-host`、`--direct-host`、`--direct-redirect-host` 和 `--rollback-nginx-smoke-host` 都只接受域名或 `host:port`，不要填 `https://` URL、路径或查询。`--direct-redirect-host` 用于校验 HTTP redirect `Location` 的目标 host，本机单独 smoke 使用非标准端口验证 redirect 时可填 `127.0.0.1:18443`；但 `--dry-run-cutover` 代表正式切换 runbook，会要求 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 使用同一 hostname，只允许端口不同，避免 redirect 和回退 smoke 打到不同入口。Host 与回退巡检入口确认步骤会同时展示 `rollback-health-patrol-public-base-url` 和 `rollback-health-patrol-public-host`，当班人员必须确认回退巡检入口就是切换前记录值。`--rollback-health-patrol-public-base-url` 必须填写切换前 `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL` 的原值；如果切换前 Nginx 巡检需要 Host 覆盖，再追加 `--rollback-health-patrol-public-host <切换前Host>`，否则 runbook 会要求回退后清空 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST`。若希望回退步骤同时证明 Pingora shadow 高端口仍存活，可给 runbook 追加 `--rollback-pingora-shadow-probe-url` 和 `--rollback-pingora-shadow-probe-token`；两者必须成对出现，URL 必须是 `http(s)`，JSON runbook 会隐藏 token 原文。生产不应使用 `--direct-insecure-tls`，`--require-direct` 会直接拒绝 insecure TLS。
-`--require-direct` 会强制要求同时提供 `--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log`、`--direct-health-patrol-env-file`、`--direct-preflight-env-file`、`--direct-preflight-systemd`、`--direct-preflight-check-cert-readable`、`--direct-preflight-check-service-env-file`、`--direct-preflight-check-service-user-cert-readable`、`--direct-preflight-check-service-binary-executable`、`--direct-preflight-check-ports-free` 和 `--direct-spacetime-database`，避免只验证 HTTPS / WSS 而漏掉 HTTP 301、ACME challenge、正式域名 Host/SNI、redirect Location host、Pingora access log 的 request_id 落盘证据、health patrol 仍按 Nginx 模式巡检、systemd drop-in 生效、service 实际读取 env 与 preflight env 一致性、当前用户证书可读性、服务用户证书私钥可读性、current release 二进制可执行性、80/443 端口释放或误用默认 SpacetimeDB 库。`--direct-pingora-access-log`、`--direct-health-patrol-env-file` 和 `--direct-preflight-env-file` 必须是绝对路径且不能是文件系统根目录；单独运行 `scripts/check-pingora-direct-live.mjs --pingora-access-log` 或 `scripts/check-pingora-direct-preflight.mjs --env-file` 时同样不能把路径指向 `/`。
+`--require-direct` 会强制要求同时提供 `--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log`、`--direct-health-patrol-env-file`、`--direct-preflight-env-file`、`--direct-preflight-systemd`、`--direct-preflight-check-cert-readable`、`--direct-preflight-check-service-env-file`、`--direct-preflight-check-service-user-cert-readable`、`--direct-preflight-check-service-binary-executable` 和 `--direct-spacetime-database`，避免只验证 HTTPS / WSS 而漏掉 HTTP 301、ACME challenge、正式域名 Host/SNI、redirect Location host、Pingora access log 的 request_id 落盘证据、health patrol 仍按 Nginx 模式巡检、systemd drop-in 生效、service 实际读取 env 与 preflight env 一致性、当前用户证书可读性、服务用户证书私钥可读性、current release 二进制可执行性或误用默认 SpacetimeDB 库。`--direct-preflight-check-ports-free` 只属于切换前端口释放门禁，`--dry-run-cutover`、启用前 preflight 和 enable apply 必须带它，启用后 `--require-direct` 复核不能再带它。`--direct-pingora-access-log`、`--direct-health-patrol-env-file` 和 `--direct-preflight-env-file` 必须是绝对路径且不能是文件系统根目录；单独运行 `scripts/check-pingora-direct-live.mjs --pingora-access-log` 或 `scripts/check-pingora-direct-preflight.mjs --env-file` 时同样不能把路径指向 `/`。
 `check-pingora-release-readiness.mjs --help` 的正式直连和只生成 runbook 示例也必须显式带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，确保值班人员复制示例命令时不会因为缺少 direct access log 参数而被 `--require-direct` 拦住。
 
 前缀 canary 已在目标 Nginx 中人工 include 且 reload 后，执行 live smoke：
@@ -257,7 +260,7 @@ sudo -n node -- /opt/genarrative/current/scripts/deploy/pingora-tls-cert-sync.mj
 该脚本默认 dry-run，`--apply` 才原子写入 `fullchain.pem` / `privkey.pem`，目标目录默认 `root:genarrative 0750`，文件默认 `root:genarrative 0640`，并复核 `genarrative` 服务用户可读；目标目录和目标文件不能是符号链接。随后先 dry-run 直连启用脚本：
 
 ```bash
-npm run plan:pingora-direct-cutover -- --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free --rollback-nginx-smoke-url http://127.0.0.1/healthz --rollback-health-patrol-public-base-url <切换前Nginx巡检入口>
+npm run plan:pingora-direct-cutover -- --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --rollback-nginx-smoke-url https://<域名>/ --rollback-nginx-smoke-expect-body '<!doctype html>' --rollback-health-patrol-public-base-url <切换前Nginx巡检入口>
 /opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --no-status
 ```
 
@@ -285,17 +288,20 @@ grep -E 'GENARRATIVE_PINGORA_GATEWAY_(TLS_LISTEN|HTTP_REDIRECT_LISTEN|TLS_CERT_F
   /etc/genarrative/pingora-gateway.env
 ```
 
-仓库工作区也可以执行 `npm run deploy:pingora-direct-enable -- --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。`--apply` 会先执行随包 `scripts/ops/pingora-current-release-audit.mjs --require-pingora-gateway --systemd-show`；自审失败、direct preflight 脚本缺失、direct live smoke 脚本缺失、drop-in 目录是符号链接、drop-in 目标是符号链接或已存在目标不是普通文件时不会安装 direct-entry drop-in。`--apply` 缺少 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 或 `--direct-spacetime-database` 会直接失败，避免跳过 env / 当前用户证书可读 / service EnvironmentFile 一致性 / 服务用户证书可读 / service 二进制可执行 / 端口释放预检、正式域名 Host/SNI、HTTP redirect Location host、Pingora access log request_id 落盘或 WSS 目标库验证；`--apply` 安装并重启后还会用 `systemctl cat` 核验 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已进入 systemd 最终配置，用 `systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager` 确认最终 ExecStart 指向随包主 service 模板中的 current release `pingora-gateway`，用 `systemctl is-active` 确认 Pingora service 为 `active`，再执行 direct live smoke，覆盖 HTTPS 根路径、首页引用静态资产自动发现探测、静态资产 `HEAD` 与 `Range: bytes=0-0`、HTTP/2 ALPN、API、SpacetimeDB identity、HTTP redirect / ACME、generated / healthz 拒绝、WSS 101 和 Pingora access log request_id 落盘。首页返回 `200` 且 HTML 中包含 `/assets/` 或 `/admin/assets/` 引用时，direct live 会额外请求该静态资源，确认 `Cache-Control`、`ETag`、`Last-Modified`、`Accept-Ranges: bytes` 和 `HEAD` 头响应，再用 `Range: bytes=0-0` 验证 `206 + Content-Range` 且不压缩，并纳入 `direct-access-log` method/path/status 对账；维护模式、非 HTML 或发布包首页没有资产引用时该项标记为 skipped，不阻断维护窗口。启用脚本会解析 direct live JSON 中的 `direct-access-log` 结果，要求 `matchedCount == checked` 且 `missingCount=0`、`mismatchCount=0`，因此 direct live 退出 0 但缺少结构化 access log 证据也会被视为启用失败。这一步只授予 `CAP_NET_BIND_SERVICE`，不写入证书、不启用 TLS env、不停止或替代 Nginx 配置。启用后仍可单独执行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free` 与 `npm run check:pingora-direct-live` 做复核；正式切换门禁追加 `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free`。验证失败时优先执行随 release 携带的直连回退脚本，移除 drop-in、`systemctl daemon-reload` 并重启 Pingora，让公网入口回到 Nginx：
+仓库工作区也可以执行 `npm run deploy:pingora-direct-enable -- --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。`--apply` 会先执行随包 `scripts/ops/pingora-current-release-audit.mjs --require-pingora-gateway --systemd-show`；自审失败、direct preflight 脚本缺失、direct live smoke 脚本缺失、drop-in 目录是符号链接、drop-in 目标是符号链接或已存在目标不是普通文件时不会安装 direct-entry drop-in。`--apply` 缺少 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 或 `--direct-spacetime-database` 会直接失败，避免跳过 env / 当前用户证书可读 / service EnvironmentFile 一致性 / 服务用户证书可读 / service 二进制可执行 / 端口释放预检、正式域名 Host/SNI、HTTP redirect Location host、Pingora access log request_id 落盘或 WSS 目标库验证；`--apply` 安装并重启后还会用 `systemctl cat` 核验 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已进入 systemd 最终配置，用 `systemctl show genarrative-pingora-gateway.service --property=ExecStart --value --no-pager` 确认最终 ExecStart 指向随包主 service 模板中的 current release `pingora-gateway`，用 `systemctl is-active` 确认 Pingora service 为 `active`，再执行 direct live smoke，覆盖 HTTPS 根路径、首页引用静态资产自动发现探测、静态资产 `HEAD` 与 `Range: bytes=0-0`、HTTP/2 ALPN、API、SpacetimeDB identity、HTTP redirect / ACME、generated / healthz 拒绝、WSS 101 和 Pingora access log request_id 落盘。首页返回 `200` 且 HTML 中包含 `/assets/` 或 `/admin/assets/` 引用时，direct live 会额外请求该静态资源，确认 `Cache-Control`、`ETag`、`Last-Modified`、`Accept-Ranges: bytes` 和 `HEAD` 头响应，再用 `Range: bytes=0-0` 验证 `206 + Content-Range` 且不压缩，并纳入 `direct-access-log` method/path/status 对账；维护模式、非 HTML 或发布包首页没有资产引用时该项标记为 skipped，不阻断维护窗口。启用脚本会解析 direct live JSON 中的 `direct-access-log` 结果，要求 `matchedCount == checked` 且 `missingCount=0`、`mismatchCount=0`，因此 direct live 退出 0 但缺少结构化 access log 证据也会被视为启用失败。直连启用前必须已把 active `/etc/genarrative/pingora-gateway.env` 提升为直连 env；回退前则必须用 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 把同一文件恢复为 shadow 高端口 env（`GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081` 且清空 TLS / HTTP redirect 低端口监听），否则移除 capability 后重启 Pingora 可能仍按 `80/443` 配置失败。启用后单独复核可执行 `npm run check:pingora-direct-live`；启用后 `--require-direct` 聚合复核不再带 `--direct-preflight-check-ports-free`。验证失败时优先执行随 release 携带的直连回退脚本，移除 drop-in、`systemctl daemon-reload` 并重启 Pingora，让公网入口回到 Nginx：
+
+正式 runbook 的状态快照证据包必须显式传 `--expected-pingora-env-mode`：`post-enable` 使用 `direct`，证明 active `/etc/genarrative/pingora-gateway.env` 已是直连姿态；`post-rollback` 使用 `shadow`，证明回退后的 active env 已恢复 shadow 姿态。`pingora-gateway-env-shadow-switch.mjs --apply` 不只清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，还必须同时清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE`；否则 Pingora 会看到“有证书路径但无 TLS listen”的半直连 env，回退证据也会被判为 `CRITICAL`。
 
 ```bash
 /opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh \
   --apply \
   --reload-nginx \
-  --nginx-smoke-url http://127.0.0.1/healthz \
-  --nginx-smoke-host <域名>
+  --nginx-smoke-url https://<域名>/ \
+  --nginx-smoke-host <域名> \
+  --nginx-smoke-expect-body '<!doctype html>'
 ```
 
-在仓库工作区也可以执行 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名> --nginx-smoke-expect-body '"ok":true'`；不带 `--apply` 时只打印将执行的命令，适合切换前复核。回退脚本 `--apply` 必须同时带 `--reload-nginx` 和 `--nginx-smoke-url`，且 smoke URL 必须是 `http(s)` URL；执行时会先拒绝带换行或 NUL 的 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override，并拒绝路径参数指向文件系统根目录，再拒绝符号链接形式的 drop-in 目录或目标文件，并拒绝已存在但不是普通文件的 drop-in 目标，通过后才运行 `nginx -t`、移除 direct-entry drop-in、`systemctl daemon-reload`、重启 Pingora；随后用 `systemctl cat` 确认 `AmbientCapabilities=CAP_NET_BIND_SERVICE` 与 `CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 已从最终 unit 配置中消失，避免只删除文件但 systemd 仍保留旧能力，并用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，避免回退后 shadow 服务继续跑旧发布包；最后 reload Nginx、确认 Nginx service 仍为 `active`，并用 smoke URL 证明 Nginx 入口真实可访问；传入 `--nginx-smoke-expect-body` 时会额外要求响应体包含预期片段，避免 HTTP 200 命中错误入口。`--nginx-smoke-url` 指向本机 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 必须同时传 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免回退 smoke 命中默认 vhost。覆盖 `--nginx-binary` 或 `--curl-binary` 时可以传裸命令名；如果值包含路径分隔符，则必须使用绝对路径，避免回退窗口受 cwd 影响。若 health patrol env 已先切回 Nginx，可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host`，脚本会在 Nginx smoke 之后调用 current release 的 `scripts/check-production-health-patrol-env.mjs`，确认 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 public base URL / Host 已恢复为切换前记录值；若切换前 Nginx 巡检需要 Host 覆盖，则把 `--health-patrol-require-empty-public-host` 换成 `--health-patrol-expected-public-host <切换前Host>`。若需要同时证明回退后 Pingora 仍作为 shadow 高端口服务存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`；脚本会隐藏 token，并要求探针响应包含 `gateway=pingora-shadow`。同一能力也可由 `plan:pingora-direct-cutover` 的 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token` 写进 rollback dry-run 和 apply 步骤。
+在仓库工作区也可以执行 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-host <域名> --nginx-smoke-expect-body '<!doctype html>'`；不带 `--apply` 时只打印将执行的命令，适合切换前复核。回退脚本 `--apply` 必须同时带 `--reload-nginx` 和 `--nginx-smoke-url`，且 smoke URL 必须是 `http(s)` URL；执行时会先拒绝带换行或 NUL 的 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override，并拒绝路径参数指向文件系统根目录，再拒绝符号链接形式的 drop-in 目录或目标文件，并拒绝已存在但不是普通文件的 drop-in 目标，通过后才运行 `nginx -t`、移除 direct-entry drop-in、`systemctl daemon-reload`、重启 Pingora；随后用 `systemctl cat` 确认 `AmbientCapabilities=CAP_NET_BIND_SERVICE` 与 `CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 已从最终 unit 配置中消失，避免只删除文件但 systemd 仍保留旧能力，并用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，避免回退后 shadow 服务继续跑旧发布包；最后 reload Nginx、确认 Nginx service 仍为 `active`，并用 smoke URL 证明 Nginx 入口真实可访问；传入 `--nginx-smoke-expect-body` 时会额外要求响应体包含预期片段，避免 HTTP 200 命中错误入口。回退 smoke URL 和响应片段必须来自切换前真实 Nginx 响应；dev 当前首页可用 `https://dev.genarrative.world/` 与 `<!doctype html>`，不要沿用固定 `/healthz + "ok":true`。`--nginx-smoke-url` 指向本机 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 必须同时传 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免回退 smoke 命中默认 vhost。覆盖 `--nginx-binary` 或 `--curl-binary` 时可以传裸命令名；如果值包含路径分隔符，则必须使用绝对路径，避免回退窗口受 cwd 影响。若 health patrol env 已先切回 Nginx，可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host`，脚本会在 Nginx smoke 之后调用 current release 的 `scripts/check-production-health-patrol-env.mjs`，确认 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 public base URL / Host 已恢复为切换前记录值；若切换前 Nginx 巡检需要 Host 覆盖，则把 `--health-patrol-require-empty-public-host` 换成 `--health-patrol-expected-public-host <切换前Host>`。若需要同时证明回退后 Pingora 仍作为 shadow 高端口服务存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`；脚本会隐藏 token，并要求探针响应包含 `gateway=pingora-shadow`。同一能力也可由 `plan:pingora-direct-cutover` 的 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token` 写进 rollback dry-run 和 apply 步骤。
 
 生产健康巡检脚本支持可选 shadow probe。将 `deploy/env/health-patrol.env.example` 复制到 `/etc/genarrative/health-patrol.env` 后，同时配置：
 
@@ -442,9 +448,25 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
 - `node -- /opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs --release-root /opt/genarrative/current --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical` 返回 `summary.status=OK`：公网 `80/443` 为 Nginx，Pingora shadow 为 `127.0.0.1:18081`，realpath canary 为 Nginx `127.0.0.1:18083`，health patrol env 为 `nginx` 模式且 public base URL 为 `https://dev.genarrative.world`。
 - `node -- /opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show` 返回 `summary.status=OK`，确认 current release 自包含、`api-server.sha256` / `pingora-gateway.sha256` 匹配、manifest 登记 `pingora-gateway`，且 `genarrative-pingora-gateway.service` 的 `ExecStart` 指向 `/opt/genarrative/current/pingora-gateway`。
 - 生成正式 direct env 候选 `/tmp/pingora-direct-dev-20260618T1548-final-prep.pingora-gateway.env`，与正式 `/etc/genarrative/pingora-gateway.env` 的差异仅为 `FORWARDED_PROTO=https`，追加 `TLS_LISTEN=0.0.0.0:443`、`HTTP_REDIRECT_LISTEN=0.0.0.0:80`、`TLS_CERT_FILE=/etc/genarrative/pingora-tls/dev.genarrative.world/fullchain.pem`、`TLS_KEY_FILE=/etc/genarrative/pingora-tls/dev.genarrative.world/privkey.pem`、`HTTP_REDIRECT_TARGET_SCHEME=https`。该候选 env 的 `check-pingora-direct-preflight.mjs --require-live-env --check-cert-readable --check-service-user-cert-readable` 通过，证明 direct env 内容和证书权限就绪。
-- 生成正式 dry-run cutover runbook `/tmp/pingora-direct-dev-20260618T1548-final-prep.runbook.json`，共 22 步，cutover run id 为 `pingora-direct-dev-20260618T1548-final-prep`，覆盖 pre-cutover 证据、enable/rollback 命令证据、post-enable/post-rollback 证据和最终根目录总审计。
+- 生成正式 dry-run cutover runbook `/tmp/pingora-direct-dev-20260618T1548-final-prep.runbook.json`，共 22 步，cutover run id 为 `pingora-direct-dev-20260618T1548-final-prep`，覆盖 pre-cutover 证据、enable/rollback 命令证据、post-enable/post-rollback 证据和最终根目录总审计。后续 runbook 已追加回退前 Pingora env shadow 预置确认，因此步数会大于该早期 final-prep 版本。
 - 注意：该 runbook 仍按正式切换窗口读取 active `/etc/genarrative/pingora-gateway.env`。因此正式执行前必须在维护窗口内先把已审阅的 direct env 提升为 `/etc/genarrative/pingora-gateway.env`，确认 Nginx 释放 `80/443`，再进入 runbook 第 5 步 preflight；否则第 5 步会继续按当前 shadow env 失败。当前阶段未替换 active env、未安装 direct-entry drop-in、未释放 Nginx 端口、未执行 `pingora-direct-enable.sh --apply`。
 
+同日真实 dev 直连 `80/443` 切换已完成一次启用和回退验证：
+
+- 切换前必须释放所有占用公网低端口的进程，不只是主站 Nginx；dev 上还需要临时释放 Gitea vhost，回退时再恢复。
+- Pingora direct 接管 `0.0.0.0:80/443` 后，HTTPS 根路径、API、静态资源 `HEAD` / `Range` / `304`、HTTP/2 ALPN、WSS subscribe 和 Pingora access log 对账均通过，direct access log `19/19 matched`。
+- 启用后 release readiness 不能再要求 `80/443` 空闲；此时端口应由 Pingora 占用。
+- 回退 smoke 不能使用固定 `http://127.0.0.1/healthz` 和 `"ok":true`。dev 实测应使用切换前真实 Nginx 首页，例如 `https://dev.genarrative.world/` 与 `<!doctype html>`。
+- 回退前必须把 `/etc/genarrative/pingora-gateway.env` 从 direct 低端口配置恢复为 shadow 配置；回退后 dev 恢复为 Nginx 监听 `0.0.0.0:80/443`、Pingora shadow `127.0.0.1:18081`、realpath canary `127.0.0.1:18083`，`genarrative-api.service`、`spacetimedb.service`、`nginx.service` 和 `genarrative-pingora-gateway.service` 均 active。
+
+同日继续推进正式 dev 切换时发现 `dev.genarrative.world` 和 `git.genarrative.world` 解析到同一公网 IP；旧 Pingora 只按 path 分流，若直接绑定 `0.0.0.0:80/443` 会把 `git.genarrative.world` 也落到主站静态 / API 路由。新版补齐 Host 分流后，dev 直连切换不应再“临时释放 Gitea vhost 后让 Gitea 不可用”，而应在 direct env 中配置：
+
+- `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world`
+- `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000`
+- `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` / `TLS_KEY_FILE` 指向同时覆盖 `dev.genarrative.world` 和 `git.genarrative.world` 的证书副本。
+
+当前 dev 的单域名证书 `/etc/letsencrypt/live/dev.genarrative.world/fullchain.pem` 只覆盖 `dev.genarrative.world`，`/etc/letsencrypt/live/git.genarrative.world/fullchain.pem` 只覆盖 `git.genarrative.world`。由于当前 Pingora TLS listener 只加载一组 cert/key，正式直连接管两个 Host 前必须先准备一张覆盖两个域名的证书并同步到 `/etc/genarrative/pingora-tls/<combined-name>/`，或另行实现 SNI 多证书支持。
+
 ## 环境变量
 
 | 变量                                                                | 默认值                                     | 说明                                                                                               |
@@ -457,6 +479,8 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
 | `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_TARGET_SCHEME`           | `https`                                    | HTTP 重定向目标 scheme，当前只允许 `https`。                                                       |
 | `GENARRATIVE_PINGORA_GATEWAY_API_UPSTREAM`                          | `127.0.0.1:8082`                           | `api-server` 上游地址。                                                                            |
 | `GENARRATIVE_PINGORA_GATEWAY_SPACETIME_UPSTREAM`                    | `127.0.0.1:3101`                           | SpacetimeDB 上游地址。                                                                             |
+| `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS`                           | 空                                         | 可选 Gitea Host 白名单，逗号分隔；匹配时整站代理到 Gitea。                                        |
+| `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM`                        | 空                                         | 可选 Gitea 上游；配置 Gitea Host 时必须同时设置。                                                  |
 | `GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT`                              | `/srv/genarrative/web`                     | 前端静态文件根目录。                                                                               |
 | `GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT`                             | `/var/www/html`                            | ACME challenge 静态目录。                                                                          |
 | `GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE`                      | `/var/lib/genarrative/maintenance/enabled` | 存在即进入维护模式。                                                                               |
@@ -529,9 +553,10 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
 3. 容器内使用同一份 Web 产物、同一组真实上游地址跑 Pingora smoke，并继续对照 `deploy/nginx/genarrative.conf` 扩展真实上游路由 parity 自动测试。
 4. 使用 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 做 Nginx 前缀 canary；启用前先跑 `npm run check:nginx-pingora-canary` 和 `npm run check:pingora-canary-docker`，有 Nginx 或 Docker 的目标环境分别强制跑 `node scripts/check-nginx-pingora-canary.mjs --require-nginx` 与 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull`，其中 Docker handoff 会自动对账临时 Nginx 与 Pingora access log。启用后跑 `npm run check:pingora-canary-live`，再用 current release 随包 access log parity 脚本对账目标机 Nginx 与 Pingora access log。canary live 的 base URL、prefix、Host、额外 path 和 timeout 不能包含换行或 NUL；canary live timeout 和 access log `since-lines` 必须是正整数，非法值直接失败。
 5. 前缀 canary 通过后，再使用 current release 随包 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083` 启用真实路径 canary；它会把 `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 渲染成独立本机 `server`，写入 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`，不能 include 到生产 `443` server 内。该片段使用 `access_log ... genarrative_upstream`，文件名必须保证晚于定义 `log_format genarrative_upstream` 的主站配置加载；否则 `nginx -t` 会报 `unknown log format "genarrative_upstream"`。启用脚本会先执行 `nginx -t`、reload Nginx，再默认运行 realpath live smoke，任一阶段失败都会恢复写入前配置。关闭时执行 `/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply`，脚本会在 `nginx -t` 或 reload 失败时恢复删除前配置。启用后跑 `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host <域名>`，再用 current release 随包 access log parity 脚本传 `--realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log` 对账 `/api/creation-entry/config`、`/v1/identity` 和 `/assets/app.js` 等真实路径。
-6. 目标机 canary include 后必须跑正式切换聚合门禁：源码 checkout / CI / 构建环境执行默认全量命令 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；目标机 current release 执行 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。启用真实路径 canary 时，两种命令都追加 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。缺少 Host 会直接失败，避免 live canary 误测默认 vhost；live smoke 后还会按 `request_id` 对账 Nginx 与 Pingora access log，缺少同一请求的 Pingora 日志、状态码、方法或 path 漂移都会失败。
-7. 如需评估 Pingora 直连公网入口，必须显式配置 `TLS_LISTEN`、证书、私钥和 `HTTP_REDIRECT_LISTEN`；Certbot 证书先用随包 `scripts/deploy/pingora-tls-cert-sync.mjs` 同步到 `/etc/genarrative/pingora-tls/<域名>/`，不要直接 chmod Let’s Encrypt live/archive 原路径；绑定 `80/443` 时还必须人工启用 `genarrative-pingora-gateway-direct-entry.conf` drop-in 授予 `CAP_NET_BIND_SERVICE`。随后用 `npm run check:pingora-gateway-smoke` 覆盖 TLS / HTTP/2 ALPN / redirect / WSS subscribe；目标机必须先跑 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再跑 `npm run check:pingora-direct-live` 或 release readiness 的 `--require-direct`，且 `--require-direct` 必须带 direct HTTPS base URL、direct HTTP base URL、正式域名 Host/SNI、redirect Location host、Pingora access log 文件、health patrol env 文件、direct preflight env 文件、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户和 systemd 服务用户证书可读检查、service 二进制可执行检查、端口释放检查和显式 SpacetimeDB 数据库名，并会拒绝 `--skip-wss`。高端口 rehearsal 使用 `https://127.0.0.1:<高端口>` 打入但期望 HTTP redirect Location 指向正式域名默认 HTTPS 入口时，额外传 `--direct-redirect-base-url https://<域名>`；`--direct-redirect-host` 仍必须保留，用于 runbook Host 一致性约束。direct live 会用生成的 `request_id` 反查 Pingora access log；缺少对应日志、method 漂移、path 漂移或 status 漂移都算直连门禁失败。direct preflight 会拒绝开启网关保护但未确认共享保护层的 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 配置；`--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值都不能包含换行或 NUL，执行 `systemctl cat` 或 `sudo -u <serviceUser> test -r <file>` 前还会复核子命令参数，避免污染参数进入目标机预检命令；direct live 的 URL、Host、redirect base URL、probe token、额外 path、数据库名、access log 路径、timeout 和布尔 env 也不能包含换行或 NUL，且会在发起请求前失败；direct live timeout 必须是正整数，直连相关布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败。证书申请与续期仍由 Certbot / 外部自动化承担，网关只读取现有文件。
+6. 目标机 canary include 后必须跑正式切换聚合门禁，并按现场已启用的 canary 入口选择参数：前缀 canary 已启用时，源码 checkout / CI / 构建环境执行 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，目标机 current release 执行 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`；真实路径 canary 已启用时，追加或单独使用 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。如果现场只启用了真实路径 canary，不要同时传 `--require-live`；缺少 Host 会直接失败，避免 live canary 误测默认 vhost。live smoke 后还会按 `request_id` 对账 Nginx 与 Pingora access log，缺少同一请求的 Pingora 日志、状态码、方法或 path 漂移都会失败。
+7. 如需评估 Pingora 直连公网入口，必须显式配置 `TLS_LISTEN`、证书、私钥和 `HTTP_REDIRECT_LISTEN`；Certbot 证书先用随包 `scripts/deploy/pingora-tls-cert-sync.mjs` 同步到 `/etc/genarrative/pingora-tls/<域名>/`，不要直接 chmod Let’s Encrypt live/archive 原路径；同一 IP 上还有 Gitea 域名时，还必须配置 `GITEA_HOSTS` / `GITEA_UPSTREAM` 并确认 TLS 证书覆盖所有由 Pingora 直连接管的 Host。绑定 `80/443` 时还必须人工启用 `genarrative-pingora-gateway-direct-entry.conf` drop-in 授予 `CAP_NET_BIND_SERVICE`。随后用 `npm run check:pingora-gateway-smoke` 覆盖 TLS / HTTP/2 ALPN / redirect / WSS subscribe / Gitea Host 分流；目标机必须先跑 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再跑 `npm run check:pingora-direct-live` 或 release readiness 的 `--require-direct`，且 `--require-direct` 必须带 direct HTTPS base URL、direct HTTP base URL、正式域名 Host/SNI、redirect Location host、Pingora access log 文件、health patrol env 文件、direct preflight env 文件、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户和 systemd 服务用户证书可读检查、service 二进制可执行检查、显式 SpacetimeDB 数据库名，并会拒绝 `--skip-wss`。高端口 rehearsal 使用 `https://127.0.0.1:<高端口>` 打入但期望 HTTP redirect Location 指向正式域名默认 HTTPS 入口时，额外传 `--direct-redirect-base-url https://<域名>`；`--direct-redirect-host` 仍必须保留，用于 runbook Host 一致性约束。direct live 会用生成的 `request_id` 反查 Pingora access log；缺少对应日志、method 漂移、path 漂移或 status 漂移都算直连门禁失败。direct preflight 会拒绝开启网关保护但未确认共享保护层的 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 配置；`--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值都不能包含换行或 NUL，执行 `systemctl cat` 或 `sudo -u <serviceUser> test -r <file>` 前还会复核子命令参数，避免污染参数进入目标机预检命令；direct live 的 URL、Host、redirect base URL、probe token、额外 path、数据库名、access log 路径、timeout 和布尔 env 也不能包含换行或 NUL，且会在发起请求前失败；direct live timeout 必须是正整数，直连相关布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败。证书申请与续期仍由 Certbot / 外部自动化承担，网关只读取现有文件。
 8. 正式直连 runbook 的启用前基础门禁和启用后 `--require-direct` 复核必须调用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs --release-runtime-only`。该脚本、`scripts/check-pingora-canary-live.mjs`、`scripts/ops/pingora-direct-rehearsal-status.mjs`、realpath canary 启停脚本和 `deploy/nginx/` 必须进入生产 API release、Jenkins API Build 归档、Jenkins API Deploy 复制清单和目标机 current release；缺失时部署应 fail-fast，切换窗口不能依赖源码 checkout 或 Jenkins workspace。
 9. direct preflight / direct live timeout 必须是正整数；直连相关布尔 env 和 Pingora gateway env 里的 `TRUST_X_FORWARDED_FOR` / `TRUSTED_FRONT_PROXY_CONFIRMED` 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败。
-10. Pingora 正式化口径固定为 gzip-only；Brotli 继续由 Nginx / 前置代理承担，直连 Pingora 不以 Brotli parity 作为切换门禁。如需多实例，开启网关接流保护时必须先引入共享限流 / 共享并发保护层并设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则保持 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT=1`；关闭网关保护的多实例方案必须明确由前置 Nginx / LB 承担全局限流。
-10. 前缀 canary 稳定后，再评估是否做真实路径 canary；真实路径 canary 稳定后，再评估是否让 Pingora 直接承接公网入口。
+10. 最终证据根目录总审计必须带 `--require-phase-pingora-env-shadow post-rollback`；`post-enable` 证据包必须通过 `--expected-pingora-env-mode direct` 证明 active Pingora env 是直连姿态，`post-rollback` 证据包必须通过 `--expected-pingora-env-mode shadow` 证明 active Pingora env 已恢复 shadow 姿态。`manifest.summary.pingoraEnvShadow` 必须证明 `listen=127.0.0.1:18081`，`mode=shadow`，`shadowReady=true`，且 `tlsListen` / `httpRedirectListen` / `tlsCertFile` / `tlsKeyFile` 均为空，避免回退后仍残留 direct 低端口或证书路径 env。
+11. Pingora 正式化口径固定为 gzip-only；Brotli 继续由 Nginx / 前置代理承担，直连 Pingora 不以 Brotli parity 作为切换门禁。如需多实例，开启网关接流保护时必须先引入共享限流 / 共享并发保护层并设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则保持 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT=1`；关闭网关保护的多实例方案必须明确由前置 Nginx / LB 承担全局限流。
+12. 前缀 canary 稳定后，再评估是否做真实路径 canary；真实路径 canary 稳定后，再评估是否让 Pingora 直接承接公网入口。
diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
index 3e2750dcc..9df1db3aa 100644
--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -284,27 +284,31 @@ Pingora 网关行为变更后应先在本机运行 `npm run check:pingora-gatewa
 
 直连 HTTPS 入口只在显式设置 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、证书链和私钥文件后启用，证书链和私钥必须允许 `genarrative` 用户读取；HTTP 重定向入口只在已配置 TLS 入口后启用，且 ACME challenge 仍从 `ACME_ROOT` 静态读取。默认 systemd service 仍以非 root `genarrative` 用户运行且不具备低端口绑定能力；Server-Provision 只把直连 drop-in 模板安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 作为参考和手动覆盖来源，正式切换默认使用 current release 内的 `/opt/genarrative/current/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`。需要绑定 `80/443` 时必须先释放 Nginx 或其它进程占用，再通过 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log` 安装到 `/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf`、`systemctl daemon-reload` 并重启 Pingora；脚本会先拒绝带换行或 NUL 的 service、路径、URL、Host、probe token、access log、数据库名、tail 行数和 timeout 参数，并拒绝脚本、env、drop-in、release root、access log 等路径参数指向文件系统根目录，再执行 current release 自审，确认发布包自包含、`pingora-gateway` 可执行且 systemd `ExecStart` 指向随包网关，失败时不会安装 drop-in；随后确认当前执行用户可读 TLS 文件，确认 service 模板和 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含本次 preflight env，再按 `genarrative-pingora-gateway.service` 的 `User=` 验证真实服务用户可读证书链和私钥，并从 service `ExecStart=` 确认 current release 的 `pingora-gateway` 存在且可执行，重启后用 `systemctl cat` 核验低端口 capability drop-in 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已进入 systemd 最终配置，用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，用 `systemctl is-active` 确认 Pingora active，并以 JSON 模式执行 direct live smoke，强制覆盖 HTTPS / HTTP redirect / ACME / WSS 101 和 Pingora access log request_id 落盘；启用脚本会解析 `direct-access-log` 结构化结果，要求 `matchedCount == checked` 且 `missingCount=0`、`mismatchCount=0`，缺少该结构化结果时即使 direct live 子进程退出 0 也会让启用失败。只有需要临时改用 `/etc/genarrative/pingora/` 参考模板时，才显式传 `--template-path` 或设置 `GENARRATIVE_PINGORA_DIRECT_TEMPLATE_PATH`；切换窗口覆盖 `--preflight-script`、`--direct-live-script`、`--current-release-audit-script`、`--template-path`、`--service-unit-path`、`--dropin-path` 或 env 文件路径时必须使用绝对路径，且不能用 `/` 占位，`--apply` 会在安装 drop-in 前确认 current release 自审、direct preflight 和 direct live smoke 脚本都存在。
 
-目标机验证直连入口时先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再运行 `npm run check:pingora-direct-live`；正式切换聚合门禁追加 `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free`；`--require-direct` 会强制要求 direct HTTPS base URL、direct HTTP base URL、正式域名 Host/SNI、redirect Location host、Pingora access log 文件、health patrol env 文件、direct preflight env 文件、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户证书可读检查、服务用户证书可读检查、service 二进制可执行检查、端口释放检查和显式 SpacetimeDB 数据库名同时存在，并默认要求 WSS subscribe 返回 101，避免漏掉 HTTP 301 / ACME challenge、正式证书域名、HTTP redirect Location host、Pingora access log request_id 落盘、SpacetimeDB 长连接、低端口 capability、TLS 文件权限验证、systemd 实际 env 漂移、systemd 服务用户权限、current release 二进制可执行性、80/443 端口释放或误用默认数据库名。`--direct-pingora-access-log`、`--direct-health-patrol-env-file`、`--direct-preflight-env-file`、direct live 单脚本的 `--pingora-access-log` 和 direct preflight 单脚本的 `--env-file` 都必须是绝对路径，且不能是文件系统根目录；direct preflight 的 `--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值还不能包含换行或 NUL，执行 `systemctl cat` 或 `sudo -u <serviceUser> test -r <file>` 前会复核子命令参数，避免污染参数进入目标机预检命令；direct live 的 URL、Host、probe token、额外 path、数据库名、access log 路径、timeout 和布尔 env 同样不能包含换行或 NUL，脚本会在发起 HTTPS / HTTP / WSS 请求前失败，避免污染请求头、URL、日志对账或 JSON 证据。若 env 中 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true`，preflight 会要求同时设置 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true`；当 TLS / HTTP redirect 监听公网地址时还会直接失败，因为公网直连 Pingora 不能信任客户端可伪造的 `X-Forwarded-For`。若 env 中 `GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true` 且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1`，preflight 会要求同时设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，避免把进程内保护误当成跨实例全局保护。生产证书必须可被系统信任，`--direct-insecure-tls` 只允许本机自签证书 smoke 使用；`--direct-skip-wss` 只允许单独 direct live 临时排障，release readiness `--require-direct` 会直接拒绝。生成 `--dry-run-cutover` 正式切换 runbook 时，`--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同；同时必须提供 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，若切换前 Nginx 巡检需要 Host 覆盖，再追加 `--rollback-health-patrol-public-host <切换前Host>`，避免回退计划把现场巡检入口覆盖成仓库默认值。runbook 的 Host 与回退巡检入口确认步骤会直接展示回退后要恢复的 public base URL / Host，并默认展示 `rollback-nginx-smoke-expect-body="ok":true`，当班人员需要在启用前确认它们就是切换前记录值。多域名或 canonical redirect 切换需要单独设计，不混入第一版 runbook。runbook 可选追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，把回退后 Pingora shadow 高端口探针复核写入 rollback dry-run / apply，JSON 输出会隐藏 token 原文。
+目标机验证直连入口时先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再运行 `npm run check:pingora-direct-live`；正式切换聚合门禁追加 `--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable`；`--require-direct` 会强制要求 direct HTTPS base URL、direct HTTP base URL、正式域名 Host/SNI、redirect Location host、Pingora access log 文件、health patrol env 文件、direct preflight env 文件、systemd drop-in 生效检查、service EnvironmentFile 一致性检查、当前用户证书可读检查、服务用户证书可读检查、service 二进制可执行检查和显式 SpacetimeDB 数据库名同时存在，并默认要求 WSS subscribe 返回 101，避免漏掉 HTTP 301 / ACME challenge、正式证书域名、HTTP redirect Location host、Pingora access log request_id 落盘、SpacetimeDB 长连接、低端口 capability、TLS 文件权限验证、systemd 实际 env 漂移、systemd 服务用户权限、current release 二进制可执行性或误用默认数据库名。`--direct-pingora-access-log`、`--direct-health-patrol-env-file`、`--direct-preflight-env-file`、direct live 单脚本的 `--pingora-access-log` 和 direct preflight 单脚本的 `--env-file` 都必须是绝对路径，且不能是文件系统根目录；direct preflight 的 `--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值还不能包含换行或 NUL，执行 `systemctl cat` 或 `sudo -u <serviceUser> test -r <file>` 前会复核子命令参数，避免污染参数进入目标机预检命令；direct live 的 URL、Host、probe token、额外 path、数据库名、access log 路径、timeout 和布尔 env 同样不能包含换行或 NUL，脚本会在发起 HTTPS / HTTP / WSS 请求前失败，避免污染请求头、URL、日志对账或 JSON 证据。若 env 中 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true`，preflight 会要求同时设置 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true`；当 TLS / HTTP redirect 监听公网地址时还会直接失败，因为公网直连 Pingora 不能信任客户端可伪造的 `X-Forwarded-For`。若 env 中 `GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true` 且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1`，preflight 会要求同时设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，避免把进程内保护误当成跨实例全局保护。生产证书必须可被系统信任，`--direct-insecure-tls` 只允许本机自签证书 smoke 使用；`--direct-skip-wss` 只允许单独 direct live 临时排障，release readiness `--require-direct` 会直接拒绝。生成 `--dry-run-cutover` 正式切换 runbook 时，`--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同；同时必须提供 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，若切换前 Nginx 巡检需要 Host 覆盖，再追加 `--rollback-health-patrol-public-host <切换前Host>`，避免回退计划把现场巡检入口覆盖成仓库默认值。runbook 的 Host 与回退巡检入口确认步骤会直接展示回退后要恢复的 public base URL / Host，并默认展示来自切换前真实 Nginx 入口的 `rollback-nginx-smoke-expect-body`，当班人员需要在启用前确认它们就是切换前记录值。多域名或 canonical redirect 切换需要单独设计，不混入第一版 runbook。runbook 可选追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，把回退后 Pingora shadow 高端口探针复核写入 rollback dry-run / apply，JSON 输出会隐藏 token 原文。
 
-直连验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名> --nginx-smoke-expect-body '"ok":true'`，或在仓库工作区执行 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名> --nginx-smoke-expect-body '"ok":true'`；回退脚本会先拒绝带换行或 NUL 的 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override，并拒绝 service unit、drop-in、health patrol env、复核脚本、路径形式二进制 override 指向文件系统根目录，再拒绝符号链接形式的 drop-in 目录或目标文件，以及已存在但不是普通文件的 drop-in 目标，通过后才运行 `nginx -t`、移除 drop-in、重启 Pingora，并用 `systemctl cat` 核验低端口 capability 已从 systemd 最终配置中移除，用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，最后 reload Nginx、确认 Nginx service 仍为 `active`，并用 smoke URL 证明 Nginx 入口真实可访问；传入 `--nginx-smoke-expect-body` 时还会要求响应体包含该片段，避免 HTTP 200 命中错误入口。`--nginx-smoke-url` 必须是 `http(s)` URL；本机打 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 还必须显式传 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免命中默认 vhost。覆盖 `--nginx-binary` 或 `--curl-binary` 时可以传裸命令名；如果值包含路径分隔符，则必须使用绝对路径，避免回退窗口受 cwd 影响。若 health patrol env 已在回退命令前切回 Nginx，可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env`，让回退脚本在 Nginx smoke 后复核 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST` 为空；若要证明回退后 Pingora 仍作为 shadow 高端口服务存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`。否则回退后必须单独运行 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs --env-file /etc/genarrative/health-patrol.env --expected-gateway-mode nginx --require-empty-public-host`。启用 / 回退脚本默认 dry-run，必须显式传 `--apply` 才修改 systemd；启用脚本 `--apply` 必须先通过 current release 自审，并同时传 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 和 `--direct-spacetime-database`，回退脚本 `--apply` 必须同时传 `--reload-nginx` 和 `--nginx-smoke-url`；当 smoke URL 是本机地址时还必须传 `--nginx-smoke-host`。本机 `npm run check:pingora-direct-enable` 和 `npm run check:pingora-direct-rollback` 会用临时文件验证 dry-run 不修改 drop-in、current release 自审失败时启用脚本不会安装 drop-in、direct preflight / direct live smoke 脚本缺失时安装前失败、direct live 退出 0 但缺少 `direct-access-log` JSON 证据时启用失败、回退脚本在 drop-in 路径安全异常时不会继续执行 `nginx -t` 或删除真实目标、会打印对应命令、展示 release layout 默认读取随包 `deploy/systemd` direct-entry 模板、systemd 最终配置核验、ExecStart 指向核验、Pingora active 核验、direct live smoke、Nginx 配置语法检查、Nginx reload 后状态核验、Nginx smoke 及响应体片段核验、可选 health patrol env 复核、可选 Pingora shadow probe 复核，并拒绝相对路径、文件系统根目录路径、非法 smoke URL、路径形式的二进制 override 和控制字符参数。
+正式 runbook 的状态快照证据包必须显式传 `--expected-pingora-env-mode`：`post-enable` 使用 `direct`，证明 active `/etc/genarrative/pingora-gateway.env` 已是直连姿态；`post-rollback` 使用 `shadow`，证明回退后的 active env 已恢复 shadow 姿态。回退前的 `pingora-gateway-env-shadow-switch.mjs --apply` 必须同时清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` 和 `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE`，避免留下“有证书路径但无 TLS listen”的半直连 env。
 
-`npm run check:pingora-current-release-audit` 会烟测 current release 自审脚本，`npm run check:pingora-cutover-status-snapshot` 会烟测随包状态快照脚本，`npm run check:pingora-cutover-evidence-bundle` 会烟测证据包归档脚本，`npm run check:pingora-cutover-command-evidence` 会烟测 apply 命令 stdout / stderr / 退出码归档脚本，`npm run check:pingora-cutover-evidence-verify` 会烟测证据 manifest 只读验真脚本，`npm run check:pingora-cutover-evidence-audit` 会烟测证据根目录三阶段总审计脚本；正式切换窗口先用 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show` 只读确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 与当前文件匹配、`release-manifest.api-server.json` 已登记 `pingora-gateway`、`pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release，再使用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 在 `pre-cutover`、`post-enable`、`post-rollback` 三个阶段生成时间戳证据目录，保存 `manifest.json`、`snapshot.json`、`snapshot.stdout.txt`、`snapshot.stderr.txt` 和 `snapshot-command.json`；证据包 `manifest.files` 会给已生成的 snapshot / stdout / stderr / command / parse-error / direct-live 文件统一记录 `path`、`sizeBytes` 和 `sha256`，便于窗口后复核归档文件未漂移。每个阶段证据目录生成、复制或归档后，都要用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <本阶段bundleDir>` 做只读验真；该 verifier 把 `manifest.files` 视为闭集，除已登记文件和 `manifest.json` 外，目录中混入任何未登记普通文件、目录或符号链接都会默认失败，`--allow-extra-files` 只允许人工排障时显式放行，正式切换归档不使用。enable / rollback apply 命令证据生成后也要立即用同一个 verifier 做只读验真，把上一步 stdout 中的 `bundleDir` 分别填入 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>`，确认 `command.stdout.txt`、`command.stderr.txt`、`command-record.json` 与 manifest 元数据一致后，再继续 health patrol 切换或回退后复核。三阶段证据和 enable / rollback apply 命令证据都完成并即时验真后，再用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-command enable-apply:pingora-direct-enable-apply --require-command rollback-apply:pingora-direct-rollback-apply --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000` 自动定位每个阶段最新证据目录和真实 apply 命令证据目录，并复用 verifier 的 `--require-summary-ok` 严格模式输出总审计 JSON。证据根目录总审计默认只接受带 `manifest.json` 的证据目录，根目录夹带普通文件、无 manifest 子目录或符号链接都会失败；`--allow-extra-root-entries` 只允许人工排障显式放行，正式切换归档不使用。阶段证据必须是不带 `manifest.commandName` 的状态快照证据包，命令证据不能冒充同名 phase 的阶段证据。验真与总审计脚本只读取 manifest 和证据文件，拒绝路径逃逸、未登记额外条目、根目录额外条目、缺文件、大小漂移、sha256 漂移、符号链接证据目录、非目录证据路径、缺阶段证据、缺命令证据、阶段 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`，以及标准五段证据的 `manifest.generatedAt` 顺序不满足 `pre-cutover -> enable-apply -> post-enable -> rollback-apply -> post-rollback` 或五段跨度超过默认 24 小时、要求 `--require-cutover-run-id` 时任一证据缺少同一 `manifest.cutoverRunId`，不修改 `/etc`、systemd、Nginx、Pingora 或证据文件；runbook 会生成或接受 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、enable / rollback apply 命令证据和最终总审计；确需跨更长维护窗口时，生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让总审计 JSON 记录本次 `timeline.maxSpanMs` 和 `timeline.spanMs`。runbook 的 direct enable apply / rollback apply 还会通过 `/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs` 包装真实脚本执行，额外保存 `command.stdout.txt`、`command.stderr.txt`、`command-record.json` 和 `manifest.json`，失败时同样保留证据并返回真实退出码，命令证据 `manifest.files` 也会记录这三份命令证据文件的 `path`、`sizeBytes` 和 `sha256` 供归档后复核。若状态快照 stdout 无法解析为 JSON，证据包会改写 `snapshot-parse-error.txt` 并在 `manifest.files.snapshotParseError` 与最终 stdout 中给出路径；启用后 direct live stdout 无法解析时，同理写入 `direct-live-parse-error.txt` 并在 `manifest.files.directLiveParseError` 与最终 stdout 中给出路径，避免解析失败原因只散落在终端输出里。底层状态快照收录 `summary`、`healthPatrolEnv`、`pingoraEnv`、`releaseArtifacts`、`systemd` 和 `checks`；其中 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile` 必须为 `true`，证明 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 精确包含本次 `--pingora-env-file`，避免证据包读取一份 env 而真实服务读取另一份 env。直连 runbook 的三个证据包阶段都会向状态快照透传 `--require-pingora-gateway`，因此 `checks.current-release-audit.details` 会同步保存 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果。自审脚本和快照脚本只读采集状态，证据包脚本只写 `--output-root` 下的新目录；命令证据脚本只负责执行 `--` 后面的真实命令并归档输出，不自行修改 `/etc`、systemd、Nginx 或 Pingora；自审、快照和证据包传入的 `--release-root` 都必须是绝对路径且不能是文件系统根目录，状态快照的 `--health-patrol-env-file` / `--pingora-env-file` 以及证据包所有显式路径参数也不能是文件系统根目录，`--output-root` 及其已存在上级路径不能是符号链接，且已存在的 `--output-root` 必须是目录；路径异常时会在执行状态快照前失败，不写入软链真实目标、不覆盖已有文件、不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora；正式 runbook 传 `--run-health-patrol --fail-on-critical`，任何 `CRITICAL` 都应阻断继续切换或回退确认。
+直连验证失败时执行 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`，或在仓库工作区执行 `npm run deploy:pingora-direct-rollback -- --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'`；回退脚本会先拒绝带换行或 NUL 的 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override，并拒绝 service unit、drop-in、health patrol env、复核脚本、路径形式二进制 override 指向文件系统根目录，再拒绝符号链接形式的 drop-in 目录或目标文件，以及已存在但不是普通文件的 drop-in 目标，通过后才运行 `nginx -t`、移除 drop-in、重启 Pingora，并用 `systemctl cat` 核验低端口 capability 已从 systemd 最终配置中移除，用 `systemctl show ... ExecStart` 核验最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，最后 reload Nginx、确认 Nginx service 仍为 `active`，并用 smoke URL 证明 Nginx 入口真实可访问；传入 `--nginx-smoke-expect-body` 时还会要求响应体包含该片段，避免 HTTP 200 命中错误入口；该 URL 与 body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`。`--nginx-smoke-url` 必须是 `http(s)` URL；本机打 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 还必须显式传 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免命中默认 vhost。覆盖 `--nginx-binary` 或 `--curl-binary` 时可以传裸命令名；如果值包含路径分隔符，则必须使用绝对路径，避免回退窗口受 cwd 影响。若 health patrol env 已在回退命令前切回 Nginx，可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env`，让回退脚本在 Nginx smoke 后复核 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 且 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST` 为空；若要证明回退后 Pingora 仍作为 shadow 高端口服务存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`。否则回退后必须单独运行 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs --env-file /etc/genarrative/health-patrol.env --expected-gateway-mode nginx --require-empty-public-host`。启用 / 回退脚本默认 dry-run，必须显式传 `--apply` 才修改 systemd；启用脚本 `--apply` 必须先通过 current release 自审，并同时传 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 和 `--direct-spacetime-database`，回退脚本 `--apply` 必须同时传 `--reload-nginx` 和 `--nginx-smoke-url`；当 smoke URL 是本机地址时还必须传 `--nginx-smoke-host`。本机 `npm run check:pingora-direct-enable` 和 `npm run check:pingora-direct-rollback` 会用临时文件验证 dry-run 不修改 drop-in、current release 自审失败时启用脚本不会安装 drop-in、direct preflight / direct live smoke 脚本缺失时安装前失败、direct live 退出 0 但缺少 `direct-access-log` JSON 证据时启用失败、回退脚本在 drop-in 路径安全异常时不会继续执行 `nginx -t` 或删除真实目标、会打印对应命令、展示 release layout 默认读取随包 `deploy/systemd` direct-entry 模板、systemd 最终配置核验、ExecStart 指向核验、Pingora active 核验、direct live smoke、Nginx 配置语法检查、Nginx reload 后状态核验、Nginx smoke 及响应体片段核验、可选 health patrol env 复核、可选 Pingora shadow probe 复核，并拒绝相对路径、文件系统根目录路径、非法 smoke URL、路径形式的二进制 override 和控制字符参数。
+
+`npm run check:pingora-current-release-audit` 会烟测 current release 自审脚本，`npm run check:pingora-cutover-status-snapshot` 会烟测随包状态快照脚本，`npm run check:pingora-cutover-evidence-bundle` 会烟测证据包归档脚本，`npm run check:pingora-cutover-command-evidence` 会烟测 apply 命令 stdout / stderr / 退出码归档脚本，`npm run check:pingora-cutover-evidence-verify` 会烟测证据 manifest 只读验真脚本，`npm run check:pingora-cutover-evidence-audit` 会烟测证据根目录三阶段总审计脚本；正式切换窗口先用 `/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show` 只读确认发布包自包含、`api-server.sha256` / `pingora-gateway.sha256` 与当前文件匹配、`release-manifest.api-server.json` 已登记 `pingora-gateway`、`pingora-gateway` 可执行且 systemd `ExecStart` 指向 current release，再使用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 在 `pre-cutover`、`post-enable`、`post-rollback` 三个阶段生成时间戳证据目录，保存 `manifest.json`、`snapshot.json`、`snapshot.stdout.txt`、`snapshot.stderr.txt` 和 `snapshot-command.json`；证据包 `manifest.files` 会给已生成的 snapshot / stdout / stderr / command / parse-error / direct-live 文件统一记录 `path`、`sizeBytes` 和 `sha256`，便于窗口后复核归档文件未漂移。每个阶段证据目录生成、复制或归档后，都要用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs --bundle-dir <本阶段bundleDir>` 做只读验真；该 verifier 把 `manifest.files` 视为闭集，除已登记文件和 `manifest.json` 外，目录中混入任何未登记普通文件、目录或符号链接都会默认失败，`--allow-extra-files` 只允许人工排障时显式放行，正式切换归档不使用。enable / rollback apply 命令证据生成后也要立即用同一个 verifier 做只读验真，把上一步 stdout 中的 `bundleDir` 分别填入 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>`，确认 `command.stdout.txt`、`command.stderr.txt`、`command-record.json` 与 manifest 元数据一致后，再继续 health patrol 切换或回退后复核。三阶段证据、enable / rollback apply 命令证据和三条 env 变更命令证据都完成并即时验真后，再用 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:pingora-direct --require-command-arg rollback-prep:pingora-gateway-shadow-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:nginx --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000` 自动定位每个阶段最新证据目录和五条真实切换命令证据目录，并复用 verifier 的 `--require-summary-ok` 严格模式输出总审计 JSON。证据根目录总审计默认只接受带 `manifest.json` 的证据目录，根目录夹带普通文件、无 manifest 子目录或符号链接都会失败；`--allow-extra-root-entries` 只允许人工排障显式放行，正式切换归档不使用。阶段证据必须是不带 `manifest.commandName` 的状态快照证据包，命令证据不能冒充同名 phase 的阶段证据。验真与总审计脚本只读取 manifest 和证据文件，拒绝路径逃逸、未登记额外条目、根目录额外条目、缺文件、大小漂移、sha256 漂移、符号链接证据目录、非目录证据路径、缺阶段证据、缺命令证据、阶段 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`，以及标准八段证据的 `manifest.generatedAt` 顺序不满足 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback` 或八段跨度超过默认 24 小时、要求 `--require-cutover-run-id` 时任一证据缺少同一 `manifest.cutoverRunId`，不修改 `/etc`、systemd、Nginx、Pingora 或证据文件；runbook 会生成或接受 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、五条真实切换命令证据和最终总审计；确需跨更长维护窗口时，生成 runbook 时显式传 `--cutover-evidence-timeline-max-span-ms <ms>`，让总审计 JSON 记录本次 `timeline.maxSpanMs` 和 `timeline.spanMs`。runbook 的 direct enable apply / rollback apply 还会通过 `/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs` 包装真实脚本执行，额外保存 `command.stdout.txt`、`command.stderr.txt`、`command-record.json` 和 `manifest.json`，失败时同样保留证据并返回真实退出码，命令证据 `manifest.files` 也会记录这三份命令证据文件的 `path`、`sizeBytes` 和 `sha256` 供归档后复核。若状态快照 stdout 无法解析为 JSON，证据包会改写 `snapshot-parse-error.txt` 并在 `manifest.files.snapshotParseError` 与最终 stdout 中给出路径；启用后 direct live stdout 无法解析时，同理写入 `direct-live-parse-error.txt` 并在 `manifest.files.directLiveParseError` 与最终 stdout 中给出路径，避免解析失败原因只散落在终端输出里。底层状态快照收录 `summary`、`healthPatrolEnv`、`pingoraEnv`、`releaseArtifacts`、`systemd` 和 `checks`；其中 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile` 必须为 `true`，证明 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 精确包含本次 `--pingora-env-file`，避免证据包读取一份 env 而真实服务读取另一份 env。直连 runbook 的三个证据包阶段都会向状态快照透传 `--require-pingora-gateway`，因此 `checks.current-release-audit.details` 会同步保存 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果。自审脚本和快照脚本只读采集状态，证据包脚本只写 `--output-root` 下的新目录；命令证据脚本只负责执行 `--` 后面的真实命令并归档输出，不自行修改 `/etc`、systemd、Nginx 或 Pingora；自审、快照和证据包传入的 `--release-root` 都必须是绝对路径且不能是文件系统根目录，状态快照的 `--health-patrol-env-file` / `--pingora-env-file` 以及证据包所有显式路径参数也不能是文件系统根目录，`--output-root` 及其已存在上级路径不能是符号链接，且已存在的 `--output-root` 必须是目录；路径异常时会在执行状态快照前失败，不写入软链真实目标、不覆盖已有文件、不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora；正式 runbook 传 `--run-health-patrol --fail-on-critical`，任何 `CRITICAL` 都应阻断继续切换或回退确认。
+
+证据包还会把 Pingora env 的 `listen`、`tlsListen`、`httpRedirectListen`、`tlsCertFile`、`tlsKeyFile`、`mode` 和 `shadowReady` 提升到 `manifest.summary.pingoraEnvShadow`；正式总审计必须追加 `--require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-phase-pingora-env-shadow post-rollback`，其中 `post-rollback` 必须证明 `listen=127.0.0.1:18081`、`mode=shadow`、`shadowReady=true`，且低端口 TLS / HTTP redirect 监听和证书路径均为空。
 
 证据 verifier / 总审计的 `--manifest`、`--bundle-dir`、`--evidence-root`、`--verify-script` 和 manifest 登记文件名都不能包含换行或 NUL 字符；遇到此类失败应修正 runbook 参数或重新生成证据，不要把被污染的路径留给下游 JSON 归档兜底。
 
 current release 自审的 `--release-root` 和 `--systemd-service` 不能包含换行或 NUL 字符；启用 `--systemd-show` 时，脚本还会在执行 `systemctl show` 前复核子命令可执行文件和所有参数不含换行或 NUL，避免只读自审命令被污染参数带偏。
 
-证据根目录总审计的“最新证据”只以 `manifest.generatedAt` 为准；任何阶段或命令候选缺少合法 `manifest.generatedAt` 都会作为根目录 `CRITICAL` 失败，不能用目录 mtime 兜底。同一阶段或同一命令如果出现多个候选共享最新 `manifest.generatedAt`，总审计会以 `AMBIGUOUS_LATEST` 失败并列出重复目录，不能按目录名排序打平；应重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。所有证据 manifest 必须是 `schemaVersion=1`，命令证据中的 `manifest.command` 与独立 `command-record.json` 也必须是 `schemaVersion=1` 且字段一致；`manifest.generatedAt`、命令 `startedAt` 和 `finishedAt` 必须使用 `new Date().toISOString()` 产出的 UTC 毫秒格式 `YYYY-MM-DDTHH:mm:ss.sssZ`，不接受省略毫秒、本地时区或其它可被 `Date.parse` 宽松解析的字符串；命令证据的顶层 `manifest.commandName` 和内嵌 `manifest.command.name` 只要存在就必须各自是安全非空命令名，且两者同时存在时必须一致，否则按坏 manifest 处理；旧格式或手工 JSON 即使 hash 正确，也不能进入正式证据链。标准五段时间线在阶段和命令都被要求时，还会显式检查五段条目的审计状态都是 `OK`，任一阶段或命令为 `MANIFEST_FAILED` / `VERIFY_FAILED` 等非 OK 状态都会写入 timeline 诊断。这样证据目录被复制、归档或恢复后，选择最新证据和标准五段时间线证明仍只依赖 manifest 中可验真的事实。
+证据根目录总审计的“最新证据”只以 `manifest.generatedAt` 为准；任何阶段或命令候选缺少合法 `manifest.generatedAt` 都会作为根目录 `CRITICAL` 失败，不能用目录 mtime 兜底。同一阶段或同一命令如果出现多个候选共享最新 `manifest.generatedAt`，总审计会以 `AMBIGUOUS_LATEST` 失败并列出重复目录，不能按目录名排序打平；应重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。所有证据 manifest 必须是 `schemaVersion=1`，命令证据中的 `manifest.command` 与独立 `command-record.json` 也必须是 `schemaVersion=1` 且字段一致；`manifest.generatedAt`、命令 `startedAt` 和 `finishedAt` 必须使用 `new Date().toISOString()` 产出的 UTC 毫秒格式 `YYYY-MM-DDTHH:mm:ss.sssZ`，不接受省略毫秒、本地时区或其它可被 `Date.parse` 宽松解析的字符串；命令证据的顶层 `manifest.commandName` 和内嵌 `manifest.command.name` 只要存在就必须各自是安全非空命令名，且两者同时存在时必须一致，否则按坏 manifest 处理；旧格式或手工 JSON 即使 hash 正确，也不能进入正式证据链。标准八段时间线在阶段和命令都被要求时，还会显式检查八段条目的审计状态都是 `OK`，任一阶段或命令为 `MANIFEST_FAILED` / `VERIFY_FAILED` 等非 OK 状态都会写入 timeline 诊断。这样证据目录被复制、归档或恢复后，选择最新证据和标准八段时间线证明仍只依赖 manifest 中可验真的事实。
 
-标准五段时间线只要任一阶段或命令证据声明了 `manifest.cutoverRunId`，五段就必须全部声明同一个值；缺字段或混入其它批次都会让总审计失败。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。正式 runbook 仍必须显式传 `--require-cutover-run-id <本次cutoverRunId>`，避免人工临时审计遗漏参数。
+标准八段时间线只要任一阶段或命令证据声明了 `manifest.cutoverRunId`，八段就必须全部声明同一个值；缺字段或混入其它批次都会让总审计失败。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。正式 runbook 仍必须显式传 `--require-cutover-run-id <本次cutoverRunId>`，避免人工临时审计遗漏参数。
 
-总审计 JSON 的 `timeline.failedCount` 会按标准五段时间线的具体失败项累计，`timeline.failureBreakdown` 会区分 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded`。切换窗口排障时不要只看顶层 `ok=false`，应先按 breakdown 定位是证据状态未达标、时间字段缺失、批次混入、顺序倒挂还是维护窗口跨度超限。
+总审计 JSON 的 `timeline.failedCount` 会按标准八段时间线的具体失败项累计，`timeline.failureBreakdown` 会区分 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded`。切换窗口排障时不要只看顶层 `ok=false`，应先按 breakdown 定位是证据状态未达标、时间字段缺失、批次混入、顺序倒挂还是维护窗口跨度超限。
 
-正式 runbook 的每个即时 verifier 步骤都必须追加 `--require-summary-ok`：三阶段状态证据和 enable / rollback apply 命令证据在刚生成后就要同时通过 `manifest.files` 完整性校验和 `manifest.summary.status=OK` 校验；缺少 `summary`、状态为 `CRITICAL` 或文件 hash 漂移都必须立即停住。最终证据根目录总审计仍负责跨目录聚合、命令身份、`--apply` 参数、时间线和 `cutoverRunId` 的二次确认，不能用来替代即时验真；总审计内部再次复用 verifier 时也必须启用 `--require-summary-ok`。
+正式 runbook 的每个即时 verifier 步骤，以及三条 env 变更命令证据即时验真步骤，都必须追加 `--require-summary-ok`：三阶段状态证据、enable / rollback apply 命令证据和三条 env 变更命令证据在刚生成后就要同时通过 `manifest.files` 完整性校验和 `manifest.summary.status=OK` 校验；缺少 `summary`、状态为 `CRITICAL` 或文件 hash 漂移都必须立即停住。最终证据根目录总审计仍负责跨目录聚合、命令身份、`--apply` 参数、时间线和 `cutoverRunId` 的二次确认，不能用来替代即时验真；总审计内部再次复用 verifier 时也必须启用 `--require-summary-ok`。
 
 正式 cutover runbook 不允许携带 `--warn-only`、`--allow-extra-files` 或 `--allow-extra-root-entries`。这些参数只用于 runbook 之外的人工排障命令；一旦需要它们，说明正式证据链还不干净，应先修现场状态、归档方式或重新生成证据，再回到无放行参数的 runbook。
 
-最终证据根目录总审计必须在 `--require-command` 之外追加 `--require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`--require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`、`--require-command-arg enable-apply:pingora-direct-enable-apply:--apply` 和 `--require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply`，复核命令证据里的 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` 的 executable 都是 current release 随包脚本，并要求 `manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，且每个 args 字符串都不含换行或 NUL 字符。`--require-command-executable` 的 executable 段必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符；总审计 JSON 会记录 `requiredCommandExecutables`，便于复盘本次绑定的真实 current release 随包脚本。总审计还会要求 `manifest.commandName` 与 `manifest.command.name` 一致，并要求 `manifest.command` 与 `command-record.json` 的 schemaVersion / phase / commandName / cutoverRunId / exitCode / signal / startedAt / finishedAt / durationMs / stdoutPath / stderrPath / args / command / cwd / error 等关键字段一致；stdoutPath / stderrPath 还必须分别与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 指向同一份归档文件，args 与 command 用于证明真实 apply 参数未被替换成 dry-run 或其它动作。命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`。这些参数会隐式要求对应命令证据存在；旧证据缺少 `schemaVersion` 或 `expectedExecutable`、缺少必需 `--apply` 参数、人工同名证据的 executable 漂移、manifest 与 command-record 语义漂移、命令 stdout / stderr 引用漂移、命令参数漂移、命令参数控制字符污染、命令时间线漂移或同一命令绑定多个不同脚本路径都会失败。
+最终证据根目录总审计必须在 `--require-command` 之外追加五条 `--require-command-executable` 和七条 `--require-command-arg` 要求，覆盖 enable apply、health patrol direct env switch、Pingora gateway shadow env switch、health patrol nginx env switch 和 rollback apply；其中 include `enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs`、`rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs`、`rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，并要求 `--apply`、`pingora-direct` 与 `nginx` 等关键参数，复核命令证据里的 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` 的 executable 都是 current release 随包脚本，并要求 `manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，且每个 args 字符串都不含换行或 NUL 字符。`--require-command-executable` 的 executable 段必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符；总审计 JSON 会记录 `requiredCommandExecutables`，便于复盘本次绑定的真实 current release 随包脚本。总审计还会要求 `manifest.commandName` 与 `manifest.command.name` 一致，并要求 `manifest.command` 与 `command-record.json` 的 schemaVersion / phase / commandName / cutoverRunId / exitCode / signal / startedAt / finishedAt / durationMs / stdoutPath / stderrPath / args / command / cwd / error 等关键字段一致；stdoutPath / stderrPath 还必须分别与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 指向同一份归档文件，args 与 command 用于证明真实 apply 参数未被替换成 dry-run 或其它动作。命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`。这些参数会隐式要求对应命令证据存在；旧证据缺少 `schemaVersion` 或 `expectedExecutable`、缺少必需 `--apply` 参数、人工同名证据的 executable 漂移、manifest 与 command-record 语义漂移、命令 stdout / stderr 引用漂移、命令参数漂移、命令参数控制字符污染、命令时间线漂移或同一命令绑定多个不同脚本路径都会失败。
 
 命令证据的 `manifest.expectedExecutable` 和 `manifest.command.expectedExecutable` 只要出现，就必须是安全绝对路径；空字符串、相对路径、文件系统根目录或包含换行 / NUL 的值都会让总审计失败，避免坏字段被当作缺省值跳过。生成命令证据时，`pingora-cutover-command-evidence.mjs --expected-executable` 也会在执行真实命令前拒绝相对路径、文件系统根目录和带换行 / NUL 的路径。
 
@@ -320,15 +324,19 @@ current release 自审、状态快照、证据包、direct preflight、生产巡
 
 current release 随包执行的 release readiness 必须追加 `--release-runtime-only`，只运行包内可自包含的 current release 自审、live canary、真实 access log 对账、direct preflight、health patrol env 复核和 direct live smoke；不要在 `/opt/genarrative/current` 上运行默认源码全量门禁。默认不带 `--release-runtime-only` 的聚合门禁仍属于本机 / CI / 构建环境使用，负责覆盖 Cargo、npm、Docker、Nginx 静态 / 真机校验和发布包构建烟测。
 
+Pingora direct 切换门禁按阶段拆分：启用前 preflight、`--dry-run-cutover` 和 `pingora-direct-enable.sh --apply` 必须带 `--direct-preflight-check-ports-free` / `--preflight-check-ports-free`，证明 Nginx、Gitea 等所有占用 `80/443` 的进程已释放；启用后 `--require-direct --release-runtime-only` 复核不再要求端口空闲，因为此时 `80/443` 应由 Pingora 占用。回退 runbook 必须显式提供来自切换前真实 Nginx 响应的 `--rollback-nginx-smoke-url` 与 `--rollback-nginx-smoke-expect-body`，例如 dev 首页 `https://dev.genarrative.world/` 和 `<!doctype html>`；不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`。如果切换窗口把 `/etc/genarrative/pingora-gateway.env` 提升为 direct 低端口配置，rollback apply 前必须用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 预置 Pingora shadow env，确认 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081`，并清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN` / `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`，再重启 Pingora。
+
 涉及 Nginx 模板、Pingora 路由、限流分组或路由文档时，必须同步更新 `deploy/pingora/nginx-route-parity.matrix.json`，并运行 `npm run check:pingora-route-parity`；Rust 侧 `cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix` 会读取同一份矩阵验证 `classify_path` 的路由结果、body limit 和接流保护分组。
 
 Pingora canary 入口默认由 Server-Provision 安装但不接入主站配置。`deploy/nginx/snippets/genarrative-pingora-canary.conf` 是前缀 canary，人工 include 后用 `/__genarrative_pingora_canary/` rewrite 到 Pingora shadow；`deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 是前缀 canary 之后、direct 直连之前的真实路径 canary，只能在 Nginx `http` 上下文 include，默认监听 `127.0.0.1:18083` 并写独立 `/var/log/nginx/genarrative-pingora-realpath-canary.access.log`，不要 include 到生产 `443` server 内覆盖正式 location。启用前必须运行 `npm run check:nginx-pingora-canary`；目标 agent 有 Nginx 时运行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`，强制把前缀 location 片段和真实路径 server 片段一起执行 `nginx -t`。本机或 CI 可用 `npm run check:pingora-canary-docker` 启动 Docker Nginx、真实 Pingora 和 mock 上游复现两条 Nginx -> Pingora handoff，并复用 `scripts/check-pingora-canary-access-log-parity.mjs` 按 `request_id` 对账。需要证明 Docker Nginx -> Pingora -> 真实本地服务时，先启动真实 api-server 与 SpacetimeDB，再运行 `node scripts/check-pingora-canary-docker.mjs --require-docker --real-upstreams --api-upstream 127.0.0.1:<api-port> --spacetime-upstream 127.0.0.1:<spacetime-port> --web-root dist`；该模式不会启动内置 mock 上游，会先检查真实 `/healthz` 和 `/v1/ping`，随后复用同一组 live smoke 与 access log 对账。真实 SpacetimeDB 对 `GET /v1/identity` 返回 `405 Method Not Allowed` 属于可接受语义，canary live 只把它作为路径路由代表，不要求该 GET 创建 identity。前缀 canary reload 后运行 `GENARRATIVE_PINGORA_CANARY_BASE_URL=http://127.0.0.1 GENARRATIVE_PINGORA_CANARY_HOST=<域名> npm run check:pingora-canary-live`；真实路径 canary 启停统一使用 current release 随包脚本：`/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-enable.sh --apply --probe-token <token> --host <域名> --base-url http://127.0.0.1:18083` 写入 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf` 并执行 `nginx -t`、reload 和 realpath live smoke，`/opt/genarrative/current/scripts/deploy/pingora-realpath-canary-disable.sh --apply` 删除该配置并复核 Nginx；两者失败都会恢复操作前状态。真实路径 canary reload 后运行 `node -- /opt/genarrative/current/scripts/check-pingora-canary-live.mjs --realpath --base-url http://127.0.0.1:18083 --host <域名>`，随后用 `node -- /opt/genarrative/current/scripts/check-pingora-canary-access-log-parity.mjs --realpath --nginx-log-file /var/log/nginx/genarrative-pingora-realpath-canary.access.log --pingora-log-file /var/log/genarrative/pingora-gateway.access.log --path /__genarrative_pingora_realpath_canary/healthz --path /api/creation-entry/config --path /v1/identity --path /assets/app.js` 对账；真实路径模式除 healthz 探针外要求 Nginx path 与 Pingora path 完全一致。canary live 的 base URL、prefix、Host、额外 path、`--timeout-ms` / `GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS` 不能包含换行或 NUL，脚本会在发起请求前失败；canary access log 对账脚本的日志路径、prefix、必需路径和 `--since-lines` / `GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES` 也不能包含换行或 NUL，日志行里解析出的 URI / path 含控制字符时必须失败；timeout 和 access log 对账的 `--since-lines` / 对应 env 必须是正整数，非法值直接失败，不静默回默认值。
 
-Pingora 正式切换前必须额外运行聚合门禁：`node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。该门禁串起 Rust 单测、mock smoke、路由 parity、Nginx snippet 校验、Docker Nginx handoff、canary access log 对账烟测、直连入口静态预检、直连启用 / 回退 dry-run 行为检查、health patrol env 切换脚本烟测、current release 自审烟测、release readiness 计划自检、生产运维护栏、API release build 烟测、Pingora production release 真实构建烟测、API deploy release 烟测、目标机 live canary 和目标机真实 access log 对账；其中 `--require-live` 只能在目标 Nginx 已人工 include canary snippet 并 reload 后执行，并会强制要求 `--live-host`，避免只访问 `127.0.0.1` 命中 Nginx 默认 vhost。live smoke 成功后会立即读取 Nginx 与 Pingora access log 尾部记录，按 `request_id` 验证 `/__genarrative_pingora_canary/healthz` 和 `/__genarrative_pingora_canary/api/creation-entry/config` 已在两边落盘且 method/status/path 没有漂移。启用真实路径 canary 时追加 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，它会用独立 Nginx access log 对账真实 `/api`、`/v1` 与 `/assets` 路径。live canary、direct live 和 access log 对账的显式毫秒超时或尾部行数参数都必须是正整数，非法值应先修参数再重跑，不能把默认值兜底后的结果当成切换证据；direct live 与 release readiness 读取的直连布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，拼写错误会直接失败，避免 `REQUIRE_WSS_UPGRADE`、preflight 开关或 `SKIP_WSS` 被悄悄当成 false。若验证 Pingora 直连公网入口，还必须追加 direct preflight 参数检查目标机 env、systemd drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限、service 二进制可执行性和端口释放：`--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free`；该模式缺少 `--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log`、`--direct-preflight-systemd`、`--direct-preflight-check-cert-readable`、`--direct-preflight-check-service-env-file`、`--direct-preflight-check-service-user-cert-readable`、`--direct-preflight-check-service-binary-executable`、`--direct-preflight-check-ports-free` 、缺少 `--direct-health-patrol-env-file` 或缺少 `--direct-spacetime-database` 会直接失败，且会拒绝 `--direct-skip-wss`，并默认要求 WSS subscribe 返回 101，证明 HTTP redirect / ACME、正式域名 Host/SNI、redirect Location host、Pingora access log request_id + path/status 对账、health patrol direct 模式、systemd drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限、service 二进制可执行性、80/443 端口释放与目标 SpacetimeDB 长连接都能从直连入口透传。`check-pingora-release-readiness.mjs --help` 中的正式直连和只生成 runbook 示例也必须显式带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，避免值班人员复制示例后被 `--require-direct` 自身拦住。普通本机提交前可先跑 `npm run check:pingora-release-readiness`，但该默认模式不能替代目标机切换窗口的强制门禁。直连切换前还应先运行 `npm run plan:pingora-direct-cutover -- --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free --rollback-nginx-smoke-url http://127.0.0.1/healthz --rollback-health-patrol-public-base-url <切换前Nginx巡检入口>` 生成只读 JSON runbook；若切换参数提供 `--direct-probe-token`，启用后复核会继续透传 direct probe token 检查内部探针，runbook JSON 只显示 `<redacted>`。runbook 会列出 Host 与回退巡检入口确认、current release 自包含自审、current release preflight、启用前基础门禁、direct enable dry-run、direct enable apply、用 `/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply` 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后 `--require-direct` 复核、rollback dry-run、回退前用同一脚本预置回 `nginx` 并恢复切换前 public base URL / Host、rollback apply、回退后 health patrol env Nginx 模式复核，供当班人员逐条审阅。direct enable / rollback `--apply` 都会拒绝符号链接形式的 systemd drop-in 目录或目标文件，并拒绝已存在但不是普通文件的目标，避免把低端口 capability 写入非预期位置，或在回退窗口误删 / 误判非预期 systemd 位置；health patrol env 切换脚本 `--apply` 会保留原文件权限和 owner/group，此时 `--env-file` 必须直接指向真实普通文件，不能是符号链接。如果现场 env 是链接，先确认真实目标路径后再传给脚本，避免替换链接本身或写入非预期目标。
+下方聚合门禁示例以前缀 canary 已启用为前提；如果现场只启用了真实路径 canary，源码 checkout / CI 与目标机 `--release-runtime-only` 都不要传 `--require-live`，改用 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。只有前缀 canary 和真实路径 canary 都启用时，才同时传两组 live 参数。
+
+Pingora 正式切换前必须额外运行聚合门禁：`node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名> --live-nginx-access-log /var/log/nginx/genarrative.access.log --live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。该门禁串起 Rust 单测、mock smoke、路由 parity、Nginx snippet 校验、Docker Nginx handoff、canary access log 对账烟测、直连入口静态预检、直连启用 / 回退 dry-run 行为检查、health patrol env 切换脚本烟测、current release 自审烟测、release readiness 计划自检、生产运维护栏、API release build 烟测、Pingora production release 真实构建烟测、API deploy release 烟测、目标机 live canary 和目标机真实 access log 对账；其中 `--require-live` 只能在目标 Nginx 已人工 include canary snippet 并 reload 后执行，并会强制要求 `--live-host`，避免只访问 `127.0.0.1` 命中 Nginx 默认 vhost。live smoke 成功后会立即读取 Nginx 与 Pingora access log 尾部记录，按 `request_id` 验证 `/__genarrative_pingora_canary/healthz` 和 `/__genarrative_pingora_canary/api/creation-entry/config` 已在两边落盘且 method/status/path 没有漂移。启用真实路径 canary 时追加 `--require-realpath-live --realpath-live-base-url http://127.0.0.1:18083 --realpath-live-host <域名> --realpath-live-nginx-access-log /var/log/nginx/genarrative-pingora-realpath-canary.access.log --realpath-live-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，它会用独立 Nginx access log 对账真实 `/api`、`/v1` 与 `/assets` 路径。live canary、direct live 和 access log 对账的显式毫秒超时或尾部行数参数都必须是正整数，非法值应先修参数再重跑，不能把默认值兜底后的结果当成切换证据；direct live 与 release readiness 读取的直连布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，拼写错误会直接失败，避免 `REQUIRE_WSS_UPGRADE`、preflight 开关或 `SKIP_WSS` 被悄悄当成 false。若验证 Pingora 直连公网入口，还必须追加 direct preflight 参数检查目标机 env、systemd drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限和 service 二进制可执行性：`--require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable`；该模式缺少 `--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log`、`--direct-preflight-systemd`、`--direct-preflight-check-cert-readable`、`--direct-preflight-check-service-env-file`、`--direct-preflight-check-service-user-cert-readable`、`--direct-preflight-check-service-binary-executable`、缺少 `--direct-health-patrol-env-file` 或缺少 `--direct-spacetime-database` 会直接失败，且会拒绝 `--direct-skip-wss`，并默认要求 WSS subscribe 返回 101，证明 HTTP redirect / ACME、正式域名 Host/SNI、redirect Location host、Pingora access log request_id + path/status 对账、health patrol direct 模式、systemd drop-in、service EnvironmentFile 一致性、当前用户证书权限、服务用户证书权限、service 二进制可执行性与目标 SpacetimeDB 长连接都能从直连入口透传。`check-pingora-release-readiness.mjs --help` 中的正式直连和只生成 runbook 示例也必须显式带 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`，避免值班人员复制示例后被 `--require-direct` 自身拦住。普通本机提交前可先跑 `npm run check:pingora-release-readiness`，但该默认模式不能替代目标机切换窗口的强制门禁。直连切换前还应先运行 `npm run plan:pingora-direct-cutover -- --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --rollback-nginx-smoke-url https://<域名>/ --rollback-nginx-smoke-expect-body '<!doctype html>' --rollback-health-patrol-public-base-url <切换前Nginx巡检入口>` 生成只读 JSON runbook；若切换参数提供 `--direct-probe-token`，启用后复核会继续透传 direct probe token 检查内部探针，runbook JSON 只显示 `<redacted>`。runbook 会列出 Host 与回退巡检入口确认、current release 自包含自审、current release preflight、启用前基础门禁、direct enable dry-run、direct enable apply、用 `/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply` 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后 `--require-direct` 复核、rollback dry-run、回退前用同一脚本预置回 `nginx` 并恢复切换前 public base URL / Host、rollback apply、回退后 health patrol env Nginx 模式复核，供当班人员逐条审阅。direct enable / rollback `--apply` 都会拒绝符号链接形式的 systemd drop-in 目录或目标文件，并拒绝已存在但不是普通文件的目标，避免把低端口 capability 写入非预期位置，或在回退窗口误删 / 误判非预期 systemd 位置；health patrol env 切换脚本 `--apply` 会保留原文件权限和 owner/group，此时 `--env-file` 必须直接指向真实普通文件，不能是符号链接。如果现场 env 是链接，先确认真实目标路径后再传给脚本，避免替换链接本身或写入非预期目标。
 
 目标机在 `/opt/genarrative/current` 上执行上述启用前基础门禁或启用后 `--require-direct` 复核时，命令必须显式使用 `--release-runtime-only`。该模式会拒绝 `--require-docker`、`--pull-docker` 和 `--require-nginx`，这些源码 / 构建环境门禁应在 CI 或构建机的默认聚合门禁中完成。
 
-上述聚合门禁默认还会执行 `npm run check:pingora-cutover-status-snapshot`、`npm run check:pingora-cutover-evidence-bundle`、`npm run check:pingora-cutover-command-evidence`、`npm run check:pingora-cutover-evidence-verify` 和 `npm run check:pingora-cutover-evidence-audit`。正式直连 runbook 会额外列出 `切换前状态快照证据包`、`启用后状态快照证据包` 和 `回退后状态快照证据包`，每个证据包阶段后都会列出对应的 `证据 manifest 只读验真` 步骤；`Pingora direct enable apply` 与 `Pingora direct rollback apply` 后也会分别列出 `启用命令证据 manifest 只读验真` 和 `回退命令证据 manifest 只读验真`，先用随包 verifier 复核命令证据 manifest，再进入 health patrol 切换或回退后 env 复核；最后在三阶段与 enable / rollback apply 命令证据都完成并即时验真后列出 `切换证据根目录三阶段总审计`。这些步骤都从 `/opt/genarrative/current` 读取随包脚本和支撑文件，分别校验 Nginx 基线、Pingora direct 接流状态、回退后的 Nginx 状态、真实切换命令 stdout / stderr / 退出码证据和证据根目录阶段完整性，并通过 `--require-pingora-gateway --fail-on-critical` 防止把发布物 checksum / manifest 漂移、env 漂移、release 缺文件、systemd capability 残留、systemd 实际读取的 Pingora env 与快照 env 不一致或生产巡检失败当作可忽略信息。启用后证据包还会通过 `--run-direct-live` 归档 `direct-live.json`、stdout / stderr、命令记录和 Pingora access log `request_id` 反查结果，确保 direct live 不是只停留在终端输出；`direct-live.json` 中的 `direct-access-log` 检查必须保留扫描行数、匹配数量、缺失明细以及 path/status 漂移明细，便于事后不用翻 stderr 就能定位具体请求。证据包还会把 `directLiveAccessLog` 摘要写入 `manifest.summary`，缺少 `direct-access-log` 结构化结果会直接标记 `CRITICAL`。若 snapshot 或 direct live stdout 解析失败，证据包必须同时归档对应 `*-parse-error.txt` 并在 manifest 中索引。证据链脚本的 timeout 必须是正整数，布尔 env 必须是明确布尔值，非法值应先修配置再重跑，不能把静默 false 当成切换证据；状态快照脚本单独执行时会拒绝带换行或 NUL 字符的 release/env 路径，并在执行 systemctl、current release 自审、health patrol env 复核或生产巡检子命令前复核子命令参数；证据包脚本在执行状态快照或 direct live 子命令前必须先拒绝任一带换行或 NUL 字符的子命令参数，且 `--run-direct-live` 的 direct URL、Host、probe token、数据库名、Pingora access log 路径和 tail 行数会在配置层先拒绝换行或 NUL，`--direct-pingora-access-log` 还必须是绝对路径且不能是文件系统根目录，避免污染后的结构化 `args[]` 进入证据链；命令证据脚本的 `--phase` / `--command-name` 只允许 ASCII 安全字符，`--output-root` 必须是绝对路径且不能是符号链接或文件系统根目录，`--` 后的真实命令也必须是绝对路径、不能是文件系统根目录、不能包含换行或 NUL 字符；证据根目录总审计的 `--require-command <phase>:<commandName>` 同样只接受 ASCII 安全阶段名和命令名，缺失 `enable-apply:pingora-direct-enable-apply` 或 `rollback-apply:pingora-direct-rollback-apply` 任一命令证据都必须失败。
+上述聚合门禁默认还会执行 `npm run check:pingora-cutover-status-snapshot`、`npm run check:pingora-cutover-evidence-bundle`、`npm run check:pingora-cutover-command-evidence`、`npm run check:pingora-cutover-evidence-verify` 和 `npm run check:pingora-cutover-evidence-audit`。正式直连 runbook 会额外列出 `切换前状态快照证据包`、`启用后状态快照证据包` 和 `回退后状态快照证据包`，每个证据包阶段后都会列出对应的 `证据 manifest 只读验真` 步骤；`Pingora direct enable apply` 与 `Pingora direct rollback apply` 后也会分别列出 `启用命令证据 manifest 只读验真` 和 `回退命令证据 manifest 只读验真`，先用随包 verifier 复核命令证据 manifest，再进入 health patrol 切换或回退后 env 复核；最后在三阶段与 enable / rollback apply 命令证据和三条 env 变更命令证据都完成并即时验真后列出 `切换证据根目录三阶段总审计`。这些步骤都从 `/opt/genarrative/current` 读取随包脚本和支撑文件，分别校验 Nginx 基线、Pingora direct 接流状态、回退后的 Nginx 状态、真实切换命令 stdout / stderr / 退出码证据和证据根目录阶段完整性，并通过 `--require-pingora-gateway --fail-on-critical` 防止把发布物 checksum / manifest 漂移、env 漂移、release 缺文件、systemd capability 残留、systemd 实际读取的 Pingora env 与快照 env 不一致或生产巡检失败当作可忽略信息。启用后证据包还会通过 `--run-direct-live` 归档 `direct-live.json`、stdout / stderr、命令记录和 Pingora access log `request_id` 反查结果，确保 direct live 不是只停留在终端输出；`direct-live.json` 中的 `direct-access-log` 检查必须保留扫描行数、匹配数量、缺失明细以及 path/status 漂移明细，便于事后不用翻 stderr 就能定位具体请求。证据包还会把 `directLiveAccessLog` 摘要写入 `manifest.summary`，缺少 `direct-access-log` 结构化结果会直接标记 `CRITICAL`。若 snapshot 或 direct live stdout 解析失败，证据包必须同时归档对应 `*-parse-error.txt` 并在 manifest 中索引。证据链脚本的 timeout 必须是正整数，布尔 env 必须是明确布尔值，非法值应先修配置再重跑，不能把静默 false 当成切换证据；状态快照脚本单独执行时会拒绝带换行或 NUL 字符的 release/env 路径，并在执行 systemctl、current release 自审、health patrol env 复核或生产巡检子命令前复核子命令参数；证据包脚本在执行状态快照或 direct live 子命令前必须先拒绝任一带换行或 NUL 字符的子命令参数，且 `--run-direct-live` 的 direct URL、Host、probe token、数据库名、Pingora access log 路径和 tail 行数会在配置层先拒绝换行或 NUL，`--direct-pingora-access-log` 还必须是绝对路径且不能是文件系统根目录，避免污染后的结构化 `args[]` 进入证据链；命令证据脚本的 `--phase` / `--command-name` 只允许 ASCII 安全字符，`--output-root` 必须是绝对路径且不能是符号链接或文件系统根目录，`--` 后的真实命令也必须是绝对路径、不能是文件系统根目录、不能包含换行或 NUL 字符；证据根目录总审计的 `--require-command <phase>:<commandName>` 同样只接受 ASCII 安全阶段名和命令名，缺失 `enable-apply:pingora-direct-enable-apply` 或 `rollback-apply:pingora-direct-rollback-apply` 任一命令证据都必须失败。
 
 命令证据脚本还支持 `--expected-executable <绝对路径>` 和 `--require-arg <参数>`，正式 runbook 的 enable / rollback apply 会分别绑定到 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh`、`/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，并在执行前要求真实命令参数包含 `--apply`。如果 `--` 后真实命令与预期脚本不一致、缺少必需 `--apply` 参数，或任一真实命令参数包含换行 / NUL 字符，脚本会在创建正式命令证据前失败，避免只靠 `commandName` 把错误命令伪装成正式切换证据。
 
diff --git a/jenkins/Jenkinsfile.production-api-build b/jenkins/Jenkinsfile.production-api-build
index ace9ca71a..d3daebccb 100644
--- a/jenkins/Jenkinsfile.production-api-build
+++ b/jenkins/Jenkinsfile.production-api-build
@@ -123,7 +123,7 @@ pipeline {
 
     stage('Archive') {
       steps {
-        archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-current-release-audit.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-direct-rehearsal-status.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-status-snapshot.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-bundle.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-command-evidence.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-verify.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-audit.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-production-health-patrol-env.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-release-readiness.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-direct-preflight.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-direct-live.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-canary-live.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-canary-access-log-parity.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/production-api-deploy.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/maintenance-on.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/maintenance-off.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/systemd/**,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/nginx/**,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/env/**,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/pingora/**", fingerprint: true
+        archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-current-release-audit.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-direct-rehearsal-status.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-status-snapshot.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-bundle.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-command-evidence.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-verify.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-audit.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-production-health-patrol-env.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-release-readiness.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-direct-preflight.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-direct-live.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-canary-live.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/check-pingora-canary-access-log-parity.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/production-api-deploy.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/maintenance-on.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/maintenance-off.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/systemd/**,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/nginx/**,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/env/**,build/${env.EFFECTIVE_BUILD_VERSION}/deploy/pingora/**", fingerprint: true
         script {
           if (params.INCLUDE_PINGORA_GATEWAY) {
             archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/pingora-gateway,build/${env.EFFECTIVE_BUILD_VERSION}/pingora-gateway.sha256", fingerprint: true
diff --git a/jenkins/Jenkinsfile.production-api-deploy b/jenkins/Jenkinsfile.production-api-deploy
index 7f60e03a9..39fc7e70b 100644
--- a/jenkins/Jenkinsfile.production-api-deploy
+++ b/jenkins/Jenkinsfile.production-api-deploy
@@ -66,7 +66,7 @@ pipeline {
         copyArtifacts(
           projectName: params.BUILD_JOB_NAME,
           selector: specific(params.BUILD_NUMBER_TO_DEPLOY),
-          filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json,build/${params.BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${params.BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-current-release-audit.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-direct-rehearsal-status.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-status-snapshot.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-bundle.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-command-evidence.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-verify.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-audit.mjs,build/${params.BUILD_VERSION}/scripts/check-production-health-patrol-env.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-release-readiness.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-direct-preflight.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-direct-live.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-canary-live.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-canary-access-log-parity.mjs,build/${params.BUILD_VERSION}/scripts/deploy/production-api-deploy.sh,build/${params.BUILD_VERSION}/scripts/deploy/maintenance-on.sh,build/${params.BUILD_VERSION}/scripts/deploy/maintenance-off.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs,build/${params.BUILD_VERSION}/deploy/systemd/**,build/${params.BUILD_VERSION}/deploy/nginx/**,build/${params.BUILD_VERSION}/deploy/env/**,build/${params.BUILD_VERSION}/deploy/pingora/**",
+          filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json,build/${params.BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${params.BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-current-release-audit.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-direct-rehearsal-status.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-status-snapshot.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-bundle.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-command-evidence.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-verify.mjs,build/${params.BUILD_VERSION}/scripts/ops/pingora-cutover-evidence-audit.mjs,build/${params.BUILD_VERSION}/scripts/check-production-health-patrol-env.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-release-readiness.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-direct-preflight.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-direct-live.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-canary-live.mjs,build/${params.BUILD_VERSION}/scripts/check-pingora-canary-access-log-parity.mjs,build/${params.BUILD_VERSION}/scripts/deploy/production-api-deploy.sh,build/${params.BUILD_VERSION}/scripts/deploy/maintenance-on.sh,build/${params.BUILD_VERSION}/scripts/deploy/maintenance-off.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh,build/${params.BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs,build/${params.BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs,build/${params.BUILD_VERSION}/deploy/systemd/**,build/${params.BUILD_VERSION}/deploy/nginx/**,build/${params.BUILD_VERSION}/deploy/env/**,build/${params.BUILD_VERSION}/deploy/pingora/**",
           target: '.',
           fingerprintArtifacts: true
         )
@@ -92,7 +92,7 @@ pipeline {
         sh '''
           bash -lc '
             set -euo pipefail
-            chmod +x "build/${BUILD_VERSION}/scripts/deploy/production-api-deploy.sh" "build/${BUILD_VERSION}/scripts/deploy/maintenance-on.sh" "build/${BUILD_VERSION}/scripts/deploy/maintenance-off.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs"
+            chmod +x "build/${BUILD_VERSION}/scripts/deploy/production-api-deploy.sh" "build/${BUILD_VERSION}/scripts/deploy/maintenance-on.sh" "build/${BUILD_VERSION}/scripts/deploy/maintenance-off.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-direct-enable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-direct-rollback.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-enable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-realpath-canary-disable.sh" "build/${BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs" "build/${BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
             "build/${BUILD_VERSION}/scripts/deploy/production-api-deploy.sh" \
               --source-dir "build/${BUILD_VERSION}" \
               --version "${BUILD_VERSION}" \
diff --git a/package.json b/package.json
index f8e01769f..537fa0846 100644
--- a/package.json
+++ b/package.json
@@ -45,6 +45,7 @@
     "check:pingora-direct-enable": "node scripts/check-pingora-direct-enable.mjs",
     "check:pingora-direct-rollback": "node scripts/check-pingora-direct-rollback.mjs",
     "check:pingora-health-patrol-env-switch": "node scripts/check-pingora-health-patrol-env-switch.mjs",
+    "check:pingora-gateway-env-shadow-switch": "node scripts/check-pingora-gateway-env-shadow-switch.mjs",
     "check:pingora-tls-cert-sync": "node scripts/check-pingora-tls-cert-sync.mjs",
     "check:pingora-current-release-audit": "node scripts/check-pingora-current-release-audit.mjs",
     "check:pingora-direct-rehearsal-status": "node scripts/check-pingora-direct-rehearsal-status.mjs",
diff --git a/scripts/build-production-release.sh b/scripts/build-production-release.sh
index 017af9a8b..5b08f1f71 100644
--- a/scripts/build-production-release.sh
+++ b/scripts/build-production-release.sh
@@ -523,6 +523,7 @@ cp "${SCRIPT_DIR}/deploy/pingora-direct-rollback.sh" "${TARGET_DIR}/scripts/depl
 cp "${SCRIPT_DIR}/deploy/pingora-realpath-canary-enable.sh" "${TARGET_DIR}/scripts/deploy/pingora-realpath-canary-enable.sh"
 cp "${SCRIPT_DIR}/deploy/pingora-realpath-canary-disable.sh" "${TARGET_DIR}/scripts/deploy/pingora-realpath-canary-disable.sh"
 cp "${SCRIPT_DIR}/deploy/pingora-health-patrol-env-switch.mjs" "${TARGET_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs"
+cp "${SCRIPT_DIR}/deploy/pingora-gateway-env-shadow-switch.mjs" "${TARGET_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
 cp "${SCRIPT_DIR}/deploy/pingora-tls-cert-sync.mjs" "${TARGET_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs"
 cp "${SCRIPT_DIR}/deploy/jenkins-inbound-agent-start.sh" "${TARGET_DIR}/scripts/jenkins-inbound-agent-start.sh"
 cp "${SCRIPT_DIR}/deploy/install-jenkins-inbound-agent.sh" "${TARGET_DIR}/scripts/install-jenkins-inbound-agent.sh"
@@ -540,6 +541,7 @@ chmod +x \
   "${TARGET_DIR}/scripts/deploy/pingora-realpath-canary-enable.sh" \
   "${TARGET_DIR}/scripts/deploy/pingora-realpath-canary-disable.sh" \
   "${TARGET_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs" \
+  "${TARGET_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs" \
   "${TARGET_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs" \
   "${TARGET_DIR}/scripts/jenkins-inbound-agent-start.sh" \
   "${TARGET_DIR}/scripts/install-jenkins-inbound-agent.sh"
diff --git a/scripts/check-nginx-pingora-canary.mjs b/scripts/check-nginx-pingora-canary.mjs
index f21ed7c77..a6e6d5f35 100644
--- a/scripts/check-nginx-pingora-canary.mjs
+++ b/scripts/check-nginx-pingora-canary.mjs
@@ -444,10 +444,16 @@ function runNginxSyntaxCheck(prefixContent, realpathContent) {
       PROBE_TOKEN_PLACEHOLDER,
       'local-nginx-canary-check-token',
     );
-    const renderedRealpathSnippet = realpathContent.replaceAll(
-      PROBE_TOKEN_PLACEHOLDER,
-      'local-nginx-canary-check-token',
-    );
+    const renderedRealpathSnippet = realpathContent
+      .replaceAll(PROBE_TOKEN_PLACEHOLDER, 'local-nginx-canary-check-token')
+      .replace(
+        '/var/log/nginx/genarrative-pingora-realpath-canary.access.log',
+        path.join(tempRoot, 'genarrative-pingora-realpath-canary.access.log'),
+      )
+      .replace(
+        '/var/log/nginx/genarrative-pingora-realpath-canary.error.log',
+        path.join(tempRoot, 'genarrative-pingora-realpath-canary.error.log'),
+      );
     const nginxConfig = `
 pid ${tempRoot}/nginx.pid;
 error_log stderr notice;
@@ -463,6 +469,7 @@ http {
         'request_time=$request_time upstream_connect_time=$upstream_connect_time '
         'upstream_header_time=$upstream_header_time upstream_response_time=$upstream_response_time '
         'upstream_status=$upstream_status request_id=$request_id';
+    access_log ${tempRoot}/access.log genarrative_upstream;
 
     server {
         listen 127.0.0.1:18082;
diff --git a/scripts/check-pingora-current-release-audit.mjs b/scripts/check-pingora-current-release-audit.mjs
index cd27b1e92..dd87e6220 100644
--- a/scripts/check-pingora-current-release-audit.mjs
+++ b/scripts/check-pingora-current-release-audit.mjs
@@ -5,6 +5,7 @@ import {
   chmodSync,
   copyFileSync,
   existsSync,
+  symlinkSync,
   mkdirSync,
   mkdtempSync,
   readFileSync,
@@ -47,6 +48,7 @@ function main() {
   assertRequirePingoraGatewayFailsWhenMissing();
   assertIncludedPingoraGatewayMustBeExecutable();
   assertSystemdShowRequiresCurrentReleaseExecStart();
+  assertSystemdShowAcceptsCurrentSymlinkExecStart();
   assertRejectsRelativeReleaseRoot();
   assertRejectsFilesystemRootReleaseRoot();
   assertRejectsPathArgsWithControlCharacters();
@@ -300,6 +302,43 @@ function assertSystemdShowRequiresCurrentReleaseExecStart() {
   );
 }
 
+function assertSystemdShowAcceptsCurrentSymlinkExecStart() {
+  const fixture = prepareFixture('systemd-current-symlink', {
+    releaseDirectoryName: 'releases/current-build',
+  });
+  const currentRoot = path.join(fixture.root, 'current');
+  symlinkSync(fixture.releaseRoot, currentRoot, 'dir');
+  const currentBinary = path.join(currentRoot, 'pingora-gateway');
+  const result = runAudit(fixture, ['--systemd-show'], {
+    systemdExecStart: currentBinary,
+  });
+
+  assertStatus(
+    result,
+    0,
+    'systemd ExecStart 指向 current symlink 且解析到本次 release 时必须通过。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const payload = parseJson(result.stdout, 'current symlink ExecStart 自审输出');
+  assertEqual(
+    payload.systemd.status,
+    'OK',
+    'current symlink ExecStart 必须让 systemd 自审通过。',
+  );
+  assertEqual(
+    payload.systemd.execStartBinary,
+    currentBinary,
+    'systemd 自审必须记录 ExecStart 中的原始 current symlink 路径。',
+  );
+  assertEqual(
+    payload.systemd.expectedRealpath,
+    payload.systemd.execStartRealpath,
+    'systemd 自审必须用真实路径确认 current symlink 指向本次 release 二进制。',
+  );
+}
+
 function assertRejectsRelativeReleaseRoot() {
   const result = spawnSync(
     'node',
@@ -416,7 +455,7 @@ function assertRejectsInvalidBoolEnv() {
 
 function prepareFixture(name, options = {}) {
   const root = path.join(tmpRoot, name);
-  const releaseRoot = path.join(root, 'current');
+  const releaseRoot = path.join(root, options.releaseDirectoryName || 'current');
   const fakeBin = path.join(root, 'bin');
   const commandsLog = path.join(root, 'commands.log');
   const includePingoraGateway = options.includePingoraGateway !== false;
@@ -472,6 +511,7 @@ function prepareReleaseRoot(releaseRoot, options) {
     'scripts/deploy/pingora-realpath-canary-enable.sh',
     'scripts/deploy/pingora-realpath-canary-disable.sh',
     'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
     'scripts/deploy/pingora-tls-cert-sync.mjs',
     'deploy/systemd/genarrative-pingora-gateway.service',
     'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
@@ -498,6 +538,7 @@ function prepareReleaseRoot(releaseRoot, options) {
     'scripts/deploy/pingora-realpath-canary-enable.sh',
     'scripts/deploy/pingora-realpath-canary-disable.sh',
     'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
     'scripts/deploy/pingora-tls-cert-sync.mjs',
   ]) {
     chmodExecutable(path.join(releaseRoot, file));
diff --git a/scripts/check-pingora-cutover-evidence-audit.mjs b/scripts/check-pingora-cutover-evidence-audit.mjs
index c1d59783f..99979b377 100644
--- a/scripts/check-pingora-cutover-evidence-audit.mjs
+++ b/scripts/check-pingora-cutover-evidence-audit.mjs
@@ -43,6 +43,9 @@ function main() {
   assertRequirePhaseDirectLiveAccessLogFailsWhenPhaseMissing();
   assertRequirePhaseDirectLiveStaticHeadersSucceeds();
   assertRequirePhaseDirectLiveStaticHeadersFailsWhenMissing();
+  assertRequirePhasePingoraEnvShadowSucceeds();
+  assertRequirePhasePingoraEnvShadowFailsWhenMissing();
+  assertRequirePhasePingoraEnvShadowFailsWhenDirectLowPortsRemain();
   assertRequiredCommandsSucceed();
   assertRequiredCommandExecutableImplicitlyRequiresCommand();
   assertRequiredCommandArgImplicitlyRequiresCommand();
@@ -152,6 +155,16 @@ function assertScriptShape() {
     '--require-phase-direct-live-static-headers',
     '证据根审计脚本 usage 必须公开 direct live 静态响应头摘要强制审计参数。',
   );
+  assertIncludes(
+    content,
+    '--require-phase-pingora-env-shadow',
+    '证据根审计脚本 usage 必须公开 Pingora env shadow 摘要强制审计参数。',
+  );
+  assertIncludes(
+    content,
+    'manifest.summary.pingoraEnvShadow',
+    '证据根审计脚本必须能校验 Pingora env shadow 摘要。',
+  );
   assertIncludes(
     content,
     '--require-command-executable <phase>:<commandName>:<absolutePath>',
@@ -497,6 +510,134 @@ function assertRequirePhaseDirectLiveStaticHeadersFailsWhenMissing() {
   );
 }
 
+function assertRequirePhasePingoraEnvShadowSucceeds() {
+  const root = path.join(tmpRoot, 'required-pingora-env-shadow-ok');
+  prepareBundle(root, '20260617T030000Z-post-rollback', 'post-rollback', {
+    pingoraEnvShadow: true,
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-rollback',
+    '--require-phase-pingora-env-shadow',
+    'post-rollback',
+  ]);
+  assertStatus(
+    result,
+    0,
+    '要求 post-rollback Pingora env shadow 摘要且 manifest 已包含完整摘要时应成功。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'Pingora env shadow 强制审计 stdout');
+  assertEqual(
+    output.phases?.[0]?.requiredPingoraEnvShadow,
+    true,
+    'Pingora env shadow 强制审计输出必须标记该 phase 已要求 shadow 摘要。',
+  );
+  assertEqual(
+    output.phases?.[0]?.manifestCheck?.pingoraEnvShadowCheck?.ok,
+    true,
+    'Pingora env shadow 强制审计必须输出 pingoraEnvShadowCheck.ok=true。',
+  );
+  assertEqual(
+    output.summary?.pingoraEnvShadowEvidence?.[0]?.shadow?.ok,
+    true,
+    'operator summary 必须标记 Pingora env shadow 摘要通过。',
+  );
+}
+
+function assertRequirePhasePingoraEnvShadowFailsWhenMissing() {
+  const root = path.join(tmpRoot, 'required-pingora-env-shadow-missing');
+  prepareBundle(root, '20260617T030000Z-post-rollback', 'post-rollback', {
+    pingoraEnvShadow: false,
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-rollback',
+    '--require-phase-pingora-env-shadow',
+    'post-rollback',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '要求 post-rollback Pingora env shadow 摘要但 manifest 缺少 pingoraEnvShadow 时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'manifest.summary.pingoraEnvShadow',
+    '缺少 Pingora env shadow 摘要时必须给出 pingoraEnvShadow 诊断。',
+  );
+  const output = parseJson(result.stdout, '缺 Pingora env shadow 摘要审计 stdout');
+  assertEqual(
+    output.summary?.pingoraEnvShadowEvidence?.[0]?.shadow?.ok,
+    false,
+    '缺 Pingora env shadow 摘要时 operator summary 必须标记 shadow.ok=false。',
+  );
+}
+
+function assertRequirePhasePingoraEnvShadowFailsWhenDirectLowPortsRemain() {
+  const root = path.join(tmpRoot, 'required-pingora-env-shadow-low-ports');
+  prepareBundle(root, '20260617T030000Z-post-rollback', 'post-rollback', {
+    pingoraEnvShadow: {
+      present: true,
+      listen: '127.0.0.1:18081',
+      tlsListen: '0.0.0.0:443',
+      httpRedirectListen: '0.0.0.0:80',
+      tlsCertFile: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+      tlsKeyFile: '/etc/genarrative/pingora-tls/example/privkey.pem',
+      mode: 'direct',
+      shadowReady: false,
+      ok: false,
+      diagnostics: [
+        'tlsListen 应为空，实际 0.0.0.0:443',
+        'httpRedirectListen 应为空，实际 0.0.0.0:80',
+        'tlsCertFile 应为空，实际 /etc/genarrative/pingora-tls/example/fullchain.pem',
+      ],
+    },
+  });
+
+  const result = runAudit([
+    '--evidence-root',
+    root,
+    '--require-phase',
+    'post-rollback',
+    '--require-phase-pingora-env-shadow',
+    'post-rollback',
+  ]);
+  assertStatus(
+    result,
+    1,
+    '要求 post-rollback Pingora env shadow 摘要但低端口监听仍残留时必须失败。',
+  );
+  assertIncludes(
+    result.stdout,
+    'tlsListen 必须为空',
+    '低端口 TLS 残留时必须给出 tlsListen 诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'httpRedirectListen 必须为空',
+    '低端口 HTTP redirect 残留时必须给出 httpRedirectListen 诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'tlsCertFile 必须为空',
+    'TLS 证书路径残留时必须给出 tlsCertFile 诊断。',
+  );
+  assertIncludes(
+    result.stdout,
+    'shadowReady 必须为 true',
+    'snapshot 姿态不是 shadow 时必须给出 shadowReady 诊断。',
+  );
+}
+
 function assertRequiredCommandsSucceed() {
   const root = path.join(tmpRoot, 'required-command-ok');
   prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover');
@@ -1240,7 +1381,10 @@ function assertFullCutoverTimelineSucceed() {
   prepareFullCutoverTimeline(root, {
     preCutover: '2026-06-17T01:00:00.000Z',
     enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
     postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
     rollbackApply: '2026-06-17T04:00:00.000Z',
     postRollback: '2026-06-17T05:00:00.000Z',
   });
@@ -1263,7 +1407,7 @@ function assertFullCutoverTimelineSucceed() {
     14400000,
     '完整切换时间线必须输出实际跨度。',
   );
-  assertEqual(output.checkedCount, 5, '完整切换时间线总审计必须检查三阶段和两条命令。');
+  assertEqual(output.checkedCount, 8, '完整切换时间线总审计必须检查三阶段和五条命令。');
   assertEqual(
     output.summary?.status,
     'OK',
@@ -1297,6 +1441,19 @@ function assertFullCutoverTimelineSucceed() {
     true,
     '完整切换时间线总审计必须默认要求 post-enable direct live access log 摘要。',
   );
+  const postRollbackPhase = output.phases?.find(
+    (phase) => phase.phase === 'post-rollback',
+  );
+  assertEqual(
+    postRollbackPhase?.requiredPingoraEnvShadow,
+    true,
+    '完整切换时间线总审计必须默认要求 post-rollback Pingora env shadow 摘要。',
+  );
+  assertEqual(
+    output.summary?.pingoraEnvShadowEvidence?.[0]?.shadow?.ok,
+    true,
+    '完整切换时间线 operator summary 必须标记 post-rollback Pingora env shadow 摘要通过。',
+  );
 }
 
 function assertFullCutoverTimelineFailsWhenPostEnableAccessLogMissing() {
@@ -1306,7 +1463,10 @@ function assertFullCutoverTimelineFailsWhenPostEnableAccessLogMissing() {
     {
       preCutover: '2026-06-17T01:00:00.000Z',
       enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
       postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
       rollbackApply: '2026-06-17T04:00:00.000Z',
       postRollback: '2026-06-17T05:00:00.000Z',
     },
@@ -1354,7 +1514,10 @@ function assertFullCutoverTimelineFailsWhenPostEnableStaticHeadersMissing() {
     {
       preCutover: '2026-06-17T01:00:00.000Z',
       enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
       postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
       rollbackApply: '2026-06-17T04:00:00.000Z',
       postRollback: '2026-06-17T05:00:00.000Z',
     },
@@ -1402,7 +1565,10 @@ function assertFullCutoverTimelineWithRunIdSucceed() {
     {
       preCutover: '2026-06-17T01:00:00.000Z',
       enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
       postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
       rollbackApply: '2026-06-17T04:00:00.000Z',
       postRollback: '2026-06-17T05:00:00.000Z',
     },
@@ -1451,7 +1617,10 @@ function assertLongCutoverTimelineFails() {
   prepareFullCutoverTimeline(root, {
     preCutover: '2026-06-17T01:00:00.000Z',
     enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
     postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
     rollbackApply: '2026-06-18T04:00:00.000Z',
     postRollback: '2026-06-18T05:00:00.000Z',
   });
@@ -1480,7 +1649,10 @@ function assertTimelineMaxSpanOverrideSucceed() {
   prepareFullCutoverTimeline(root, {
     preCutover: '2026-06-17T01:00:00.000Z',
     enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
     postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
     rollbackApply: '2026-06-18T04:00:00.000Z',
     postRollback: '2026-06-18T05:00:00.000Z',
   });
@@ -1509,7 +1681,10 @@ function assertTimelineNonOkItemFails() {
   prepareFullCutoverTimeline(root, {
     preCutover: '2026-06-17T01:00:00.000Z',
     enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
     postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
     rollbackApply: '2026-06-17T04:00:00.000Z',
     postRollback: '2026-06-17T05:00:00.000Z',
   });
@@ -1537,7 +1712,7 @@ function assertTimelineNonOkItemFails() {
   writeJson(postEnableManifestPath, postEnableManifest);
 
   const result = runFullCutoverAudit(root);
-  assertStatus(result, 1, '标准五段时间线包含非 OK 条目时 timeline 必须失败。');
+  assertStatus(result, 1, '标准八段时间线包含非 OK 条目时 timeline 必须失败。');
   assertIncludes(
     result.stdout,
     '标准切换时间线包含非 OK 证据',
@@ -1573,7 +1748,10 @@ function assertMixedTimelineCutoverRunIdFails() {
     {
       preCutover: '2026-06-17T01:00:00.000Z',
       enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
       postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
       rollbackApply: '2026-06-17T04:00:00.000Z',
       postRollback: '2026-06-17T05:00:00.000Z',
     },
@@ -1617,7 +1795,10 @@ function assertPartialTimelineCutoverRunIdFails() {
     {
       preCutover: '2026-06-17T01:00:00.000Z',
       enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
       postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
       rollbackApply: '2026-06-17T04:00:00.000Z',
       postRollback: '2026-06-17T05:00:00.000Z',
     },
@@ -1680,7 +1861,10 @@ function assertCutoverRunIdMismatchFails() {
     {
       preCutover: '2026-06-17T01:00:00.000Z',
       enableApply: '2026-06-17T02:00:00.000Z',
+      healthPatrolDirect: '2026-06-17T02:10:00.000Z',
       postEnable: '2026-06-17T03:00:00.000Z',
+      gatewayShadow: '2026-06-17T03:30:00.000Z',
+      healthPatrolNginx: '2026-06-17T03:40:00.000Z',
       rollbackApply: '2026-06-17T04:00:00.000Z',
       postRollback: '2026-06-17T05:00:00.000Z',
     },
@@ -1709,7 +1893,10 @@ function assertMissingCutoverRunIdFailsWhenRequired() {
   prepareFullCutoverTimeline(root, {
     preCutover: '2026-06-17T01:00:00.000Z',
     enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
     postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
     rollbackApply: '2026-06-17T04:00:00.000Z',
     postRollback: '2026-06-17T05:00:00.000Z',
   });
@@ -2098,32 +2285,15 @@ function assertMissingCommandFails() {
 
 function assertOutOfOrderCutoverTimelineFails() {
   const root = path.join(tmpRoot, 'out-of-order-timeline');
-  prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover', {
-    generatedAt: '2026-06-17T01:00:00.000Z',
-  });
-  prepareCommandBundle(
-    root,
-    '20260617T030000Z-enable-apply-pingora-direct-enable-apply',
-    'enable-apply',
-    'pingora-direct-enable-apply',
-    {
-      generatedAt: '2026-06-17T03:00:00.000Z',
-    },
-  );
-  prepareBundle(root, '20260617T020000Z-post-enable', 'post-enable', {
-    generatedAt: '2026-06-17T02:00:00.000Z',
-  });
-  prepareCommandBundle(
-    root,
-    '20260617T040000Z-rollback-apply-pingora-direct-rollback-apply',
-    'rollback-apply',
-    'pingora-direct-rollback-apply',
-    {
-      generatedAt: '2026-06-17T04:00:00.000Z',
-    },
-  );
-  prepareBundle(root, '20260617T050000Z-post-rollback', 'post-rollback', {
-    generatedAt: '2026-06-17T05:00:00.000Z',
+  prepareFullCutoverTimeline(root, {
+    preCutover: '2026-06-17T01:00:00.000Z',
+    enableApply: '2026-06-17T03:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T03:10:00.000Z',
+    postEnable: '2026-06-17T02:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+    rollbackApply: '2026-06-17T04:00:00.000Z',
+    postRollback: '2026-06-17T05:00:00.000Z',
   });
 
   const result = runFullCutoverAudit(root);
@@ -2615,8 +2785,19 @@ function assertRejectsInvalidTimelineMaxSpan() {
 }
 
 function prepareFullCutoverTimeline(root, times, options = {}) {
+  const timelineTimes = {
+    preCutover: '2026-06-17T01:00:00.000Z',
+    enableApply: '2026-06-17T02:00:00.000Z',
+    healthPatrolDirect: '2026-06-17T02:10:00.000Z',
+    postEnable: '2026-06-17T03:00:00.000Z',
+    gatewayShadow: '2026-06-17T03:30:00.000Z',
+    healthPatrolNginx: '2026-06-17T03:40:00.000Z',
+    rollbackApply: '2026-06-17T04:00:00.000Z',
+    postRollback: '2026-06-17T05:00:00.000Z',
+    ...times,
+  };
   prepareBundle(root, '20260617T010000Z-pre-cutover', 'pre-cutover', {
-    generatedAt: times.preCutover,
+    generatedAt: timelineTimes.preCutover,
     cutoverRunId: options.cutoverRunId,
   });
   prepareCommandBundle(
@@ -2625,12 +2806,22 @@ function prepareFullCutoverTimeline(root, times, options = {}) {
     'enable-apply',
     'pingora-direct-enable-apply',
     {
-      generatedAt: times.enableApply,
+      generatedAt: timelineTimes.enableApply,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+  prepareCommandBundle(
+    root,
+    `${directoryTimestamp(timelineTimes.healthPatrolDirect)}-post-enable-pingora-health-patrol-direct-env-switch`,
+    'post-enable',
+    'pingora-health-patrol-direct-env-switch',
+    {
+      generatedAt: timelineTimes.healthPatrolDirect,
       cutoverRunId: options.cutoverRunId,
     },
   );
   prepareBundle(root, '20260617T030000Z-post-enable', 'post-enable', {
-    generatedAt: times.postEnable,
+    generatedAt: timelineTimes.postEnable,
     cutoverRunId: options.cutoverRunId,
     directLiveSummary: true,
     directLiveAccessLog: options.postEnableDirectLiveAccessLog !== false,
@@ -2638,18 +2829,43 @@ function prepareFullCutoverTimeline(root, times, options = {}) {
   });
   prepareCommandBundle(
     root,
-    `${directoryTimestamp(times.rollbackApply)}-rollback-apply-pingora-direct-rollback-apply`,
-    'rollback-apply',
-    'pingora-direct-rollback-apply',
+    `${directoryTimestamp(timelineTimes.gatewayShadow)}-rollback-prep-pingora-gateway-shadow-env-switch`,
+    'rollback-prep',
+    'pingora-gateway-shadow-env-switch',
     {
-      generatedAt: times.rollbackApply,
+      generatedAt: timelineTimes.gatewayShadow,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+  prepareCommandBundle(
+    root,
+    `${directoryTimestamp(timelineTimes.healthPatrolNginx)}-rollback-prep-pingora-health-patrol-nginx-env-switch`,
+    'rollback-prep',
+    'pingora-health-patrol-nginx-env-switch',
+    {
+      generatedAt: timelineTimes.healthPatrolNginx,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+  prepareCommandBundle(
+    root,
+    `${directoryTimestamp(timelineTimes.rollbackApply)}-rollback-apply-pingora-direct-rollback-apply`,
+    'rollback-apply',
+    'pingora-direct-rollback-apply',
+    {
+      generatedAt: timelineTimes.rollbackApply,
+      cutoverRunId: options.cutoverRunId,
+    },
+  );
+  prepareBundle(
+    root,
+    `${directoryTimestamp(timelineTimes.postRollback)}-post-rollback`,
+    'post-rollback',
+    {
+      generatedAt: timelineTimes.postRollback,
       cutoverRunId: options.cutoverRunId,
     },
   );
-  prepareBundle(root, `${directoryTimestamp(times.postRollback)}-post-rollback`, 'post-rollback', {
-    generatedAt: times.postRollback,
-    cutoverRunId: options.cutoverRunId,
-  });
 }
 
 function directoryTimestamp(isoTime) {
@@ -2669,6 +2885,12 @@ function prepareBundle(root, dirName, phase, options = {}) {
     options.directLiveSummary && options.directLiveStaticHeaders !== false
       ? createDirectLiveStaticHeadersSummary()
       : null;
+  const pingoraEnvShadow =
+    options.pingoraEnvShadow === false
+      ? null
+      : options.pingoraEnvShadow && typeof options.pingoraEnvShadow === 'object'
+      ? options.pingoraEnvShadow
+      : createPingoraEnvShadowSummary();
   mkdirSync(dir, { recursive: true });
   writeFileSync(path.join(dir, 'snapshot.json'), '{"ok":true}\n', 'utf8');
   writeFileSync(path.join(dir, 'snapshot.stdout.txt'), '{"ok":true}\n', 'utf8');
@@ -2691,6 +2913,7 @@ function prepareBundle(root, dirName, phase, options = {}) {
       ...(directLiveStaticHeaders
         ? { directLiveStaticHeaders }
         : {}),
+      ...(pingoraEnvShadow ? { pingoraEnvShadow } : {}),
     },
     files: {
       manifest: 'manifest.json',
@@ -2752,13 +2975,26 @@ function createDirectLiveStaticHeadersSummary() {
   };
 }
 
+function createPingoraEnvShadowSummary() {
+  return {
+    present: true,
+    listen: '127.0.0.1:18081',
+    tlsListen: '',
+    httpRedirectListen: '',
+    tlsCertFile: '',
+    tlsKeyFile: '',
+    mode: 'shadow',
+    shadowReady: true,
+    directReady: false,
+    ok: true,
+    diagnostics: [],
+  };
+}
+
 function prepareCommandBundle(root, dirName, phase, commandName, options = {}) {
   const dir = path.join(root, dirName);
-  const executable =
-    options.executable ||
-    (commandName === 'pingora-direct-rollback-apply'
-      ? '/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh'
-      : '/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh');
+  const executable = options.executable || defaultCommandExecutable(commandName);
+  const args = options.args || defaultCommandArgs(commandName);
   const generatedAt = options.generatedAt || '2026-06-17T00:00:00.000Z';
   const startedAt = options.startedAt || generatedAt;
   const finishedAt = options.finishedAt || generatedAt;
@@ -2773,8 +3009,8 @@ function prepareCommandBundle(root, dirName, phase, commandName, options = {}) {
     ...(options.cutoverRunId ? { cutoverRunId: options.cutoverRunId } : {}),
     expectedExecutable: executable,
     executable,
-    args: ['--apply'],
-    command: `${executable} --apply`,
+    args,
+    command: [executable, ...args].join(' '),
     cwd: process.cwd(),
     exitCode: options.exitCode ?? 0,
     signal: options.signal ?? null,
@@ -2809,6 +3045,35 @@ function prepareCommandBundle(root, dirName, phase, commandName, options = {}) {
   return dir;
 }
 
+function defaultCommandExecutable(commandName) {
+  switch (commandName) {
+    case 'pingora-direct-rollback-apply':
+      return '/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh';
+    case 'pingora-health-patrol-direct-env-switch':
+    case 'pingora-health-patrol-nginx-env-switch':
+      return '/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs';
+    case 'pingora-gateway-shadow-env-switch':
+      return '/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs';
+    case 'pingora-direct-enable-apply':
+    default:
+      return '/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh';
+  }
+}
+
+function defaultCommandArgs(commandName) {
+  switch (commandName) {
+    case 'pingora-health-patrol-direct-env-switch':
+      return ['--apply', 'pingora-direct'];
+    case 'pingora-health-patrol-nginx-env-switch':
+      return ['--apply', 'nginx'];
+    case 'pingora-direct-enable-apply':
+    case 'pingora-gateway-shadow-env-switch':
+    case 'pingora-direct-rollback-apply':
+    default:
+      return ['--apply'];
+  }
+}
+
 function metadataFor(filePath) {
   const content = readFileSync(filePath);
   return {
@@ -2846,13 +3111,41 @@ function runFullCutoverAudit(root, extraArgs = []) {
     'post-enable',
     '--require-phase-direct-live-static-headers',
     'post-enable',
+    '--require-phase-pingora-env-shadow',
+    'post-rollback',
     '--require-command',
     'enable-apply:pingora-direct-enable-apply',
     '--require-command',
+    'post-enable:pingora-health-patrol-direct-env-switch',
+    '--require-command',
+    'rollback-prep:pingora-gateway-shadow-env-switch',
+    '--require-command',
+    'rollback-prep:pingora-health-patrol-nginx-env-switch',
+    '--require-command',
     'rollback-apply:pingora-direct-rollback-apply',
+    '--require-command-executable',
+    'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+    '--require-command-executable',
+    'post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    '--require-command-executable',
+    'rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    '--require-command-executable',
+    'rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    '--require-command-executable',
+    'rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
     '--require-command-arg',
     'enable-apply:pingora-direct-enable-apply:--apply',
     '--require-command-arg',
+    'post-enable:pingora-health-patrol-direct-env-switch:--apply',
+    '--require-command-arg',
+    'post-enable:pingora-health-patrol-direct-env-switch:pingora-direct',
+    '--require-command-arg',
+    'rollback-prep:pingora-gateway-shadow-env-switch:--apply',
+    '--require-command-arg',
+    'rollback-prep:pingora-health-patrol-nginx-env-switch:--apply',
+    '--require-command-arg',
+    'rollback-prep:pingora-health-patrol-nginx-env-switch:nginx',
+    '--require-command-arg',
     'rollback-apply:pingora-direct-rollback-apply:--apply',
     ...extraArgs,
   ]);
diff --git a/scripts/check-pingora-cutover-evidence-bundle.mjs b/scripts/check-pingora-cutover-evidence-bundle.mjs
index f8b99aa9f..8db9760a8 100644
--- a/scripts/check-pingora-cutover-evidence-bundle.mjs
+++ b/scripts/check-pingora-cutover-evidence-bundle.mjs
@@ -42,6 +42,8 @@ console.log('[check:pingora-cutover-evidence-bundle] OK');
 function main() {
   assertScriptShape();
   assertBundleSucceedsAndWritesManifest();
+  assertBundleSummarizesPingoraEnvShadow();
+  assertBundleSummarizesDirectPingoraEnvAsNotShadow();
   assertBundleWritesCutoverRunId();
   assertBundleCanArchiveDirectLiveEvidence();
   assertDirectLiveFailureStillWritesEvidenceAndFails();
@@ -132,6 +134,11 @@ function assertScriptShape() {
     'parseDirectLiveJson',
     '证据包必须能从 direct live stdout 中提取 JSON 结果。',
   );
+  assertIncludes(
+    content,
+    'pingoraEnvShadow',
+    '证据包 manifest 必须提升 Pingora env shadow 摘要。',
+  );
   assertIncludes(
     content,
     '--run-direct-live',
@@ -197,6 +204,11 @@ function assertBundleSucceedsAndWritesManifest() {
   const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
   assertEqual(manifest.phase, 'post-enable', 'manifest 必须记录阶段。');
   assertEqual(manifest.summary.status, 'OK', 'manifest 必须记录快照状态。');
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.ok,
+    true,
+    'manifest 必须记录 Pingora env 已处于 shadow 高端口。',
+  );
   assertEqual(
     manifest.commands?.[0]?.exitCode,
     0,
@@ -301,6 +313,118 @@ function assertBundleSucceedsAndWritesManifest() {
   );
 }
 
+function assertBundleSummarizesPingoraEnvShadow() {
+  const fixture = prepareFixture('pingora-env-shadow-summary');
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: ['--phase', 'post-rollback', '--fail-on-critical'],
+  });
+
+  assertStatus(result, 0, 'shadow env 快照应生成 OK 摘要。');
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'shadow env 证据包 stdout');
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.present,
+    true,
+    'manifest.summary.pingoraEnvShadow 必须标记 env 摘要存在。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.listen,
+    '127.0.0.1:18081',
+    'manifest.summary.pingoraEnvShadow 必须记录 shadow listen。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.tlsListen,
+    '',
+    'manifest.summary.pingoraEnvShadow 必须记录 TLS 低端口为空。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.httpRedirectListen,
+    '',
+    'manifest.summary.pingoraEnvShadow 必须记录 HTTP redirect 低端口为空。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.tlsCertFile,
+    '',
+    'manifest.summary.pingoraEnvShadow 必须记录 TLS cert 路径为空。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.tlsKeyFile,
+    '',
+    'manifest.summary.pingoraEnvShadow 必须记录 TLS key 路径为空。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.mode,
+    'shadow',
+    'manifest.summary.pingoraEnvShadow 必须记录 snapshot 判定的 shadow 姿态。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.shadowReady,
+    true,
+    'manifest.summary.pingoraEnvShadow 必须记录 shadowReady=true。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.ok,
+    true,
+    'manifest.summary.pingoraEnvShadow.ok 必须为 true。',
+  );
+}
+
+function assertBundleSummarizesDirectPingoraEnvAsNotShadow() {
+  const fixture = prepareFixture('pingora-env-direct-summary', {
+    snapshotPingoraEnvValues: {
+      listen: '127.0.0.1:18081',
+      tlsListen: '0.0.0.0:443',
+      httpRedirectListen: '0.0.0.0:80',
+      tlsCertFile: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+      tlsKeyFile: '/etc/genarrative/pingora-tls/example/privkey.pem',
+    },
+  });
+  const result = runBundle(fixture, {
+    status: 'OK',
+    extraArgs: ['--phase', 'post-enable', '--fail-on-critical'],
+  });
+
+  assertStatus(
+    result,
+    0,
+    'direct env 快照默认只生成摘要，不应让证据包本身失败。',
+  );
+  if (result.status !== 0) {
+    return;
+  }
+  const output = parseJson(result.stdout, 'direct env 证据包 stdout');
+  const manifest = readJson(path.join(output.bundleDir, 'manifest.json'));
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.ok,
+    false,
+    'direct 低端口 env 摘要必须标记 ok=false。',
+  );
+  assertIncludes(
+    manifest.summary.pingoraEnvShadow?.diagnostics || [],
+    'tlsListen 应为空，实际 0.0.0.0:443',
+    'direct 低端口 env 摘要必须记录 TLS 低端口诊断。',
+  );
+  assertIncludes(
+    manifest.summary.pingoraEnvShadow?.diagnostics || [],
+    'httpRedirectListen 应为空，实际 0.0.0.0:80',
+    'direct 低端口 env 摘要必须记录 HTTP redirect 低端口诊断。',
+  );
+  assertIncludes(
+    manifest.summary.pingoraEnvShadow?.diagnostics || [],
+    'tlsCertFile 应为空，实际 /etc/genarrative/pingora-tls/example/fullchain.pem',
+    'direct 低端口 env 摘要必须记录 TLS cert 残留诊断。',
+  );
+  assertEqual(
+    manifest.summary.pingoraEnvShadow?.mode,
+    'direct',
+    'direct 低端口 env 摘要必须记录 snapshot 判定的 direct 姿态。',
+  );
+}
+
 function assertBundleWritesCutoverRunId() {
   const fixture = prepareFixture('cutover-run-id');
   const result = runBundle(fixture, {
@@ -1562,6 +1686,18 @@ function prepareFixture(name, options = {}) {
       'const args = process.argv.slice(2);',
       'const status = process.env.FAKE_SNAPSHOT_STATUS || "OK";',
       `const outputMode = ${JSON.stringify(options.snapshotOutputMode || 'json')};`,
+      `const pingoraEnvValues = ${JSON.stringify(
+        options.snapshotPingoraEnvValues || {
+          listen: '127.0.0.1:18081',
+          tlsListen: '',
+          httpRedirectListen: '',
+          tlsCertFile: '',
+          tlsKeyFile: '',
+        },
+      )};`,
+      'const shadowReady = pingoraEnvValues.listen === "127.0.0.1:18081" && !pingoraEnvValues.tlsListen && !pingoraEnvValues.httpRedirectListen && !pingoraEnvValues.tlsCertFile && !pingoraEnvValues.tlsKeyFile;',
+      'const directReady = Boolean(pingoraEnvValues.tlsListen && pingoraEnvValues.httpRedirectListen && pingoraEnvValues.tlsCertFile && pingoraEnvValues.tlsKeyFile);',
+      'const pingoraEnvPosture = { mode: directReady ? "direct" : shadowReady ? "shadow" : "mixed", shadowReady, directReady };',
       'const phaseIndex = args.indexOf("--phase");',
       'console.error(`[fake-snapshot] ${status}`);',
       'if (outputMode === "log-only") {',
@@ -1589,10 +1725,10 @@ function prepareFixture(name, options = {}) {
       ...(options.snapshotIncludesProbeFlags
         ? [
             '  healthPatrolEnv: { values: { hasPingoraProbeToken: Boolean(healthEnv.GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN || healthEnv.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN) } },',
-            '  pingoraEnv: { values: { hasProbeToken: Boolean(pingoraEnv.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN) } },',
+            '  pingoraEnv: { values: { ...pingoraEnvValues, hasProbeToken: Boolean(pingoraEnv.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN) }, posture: pingoraEnvPosture },',
             '  checks: [{ name: "production-health-patrol", stdout: "probe stdout <redacted>:<redacted>", stderr: "probe stderr <redacted>:<redacted>" }],',
           ]
-        : []),
+        : ['  pingoraEnv: { values: pingoraEnvValues, posture: pingoraEnvPosture },']),
       '  args,',
       '}, null, 2));',
       'if (status === "CRITICAL" && args.includes("--fail-on-critical")) process.exit(1);',
diff --git a/scripts/check-pingora-cutover-status-snapshot.mjs b/scripts/check-pingora-cutover-status-snapshot.mjs
index bf301fb2e..646ff49a0 100644
--- a/scripts/check-pingora-cutover-status-snapshot.mjs
+++ b/scripts/check-pingora-cutover-status-snapshot.mjs
@@ -40,6 +40,9 @@ console.log('[check:pingora-cutover-status-snapshot] OK');
 function main() {
   assertScriptShape();
   assertSnapshotSucceedsWithFakeSystemctlAndReleaseRoot();
+  assertSnapshotAcceptsExpectedDirectPingoraEnvMode();
+  assertSnapshotRejectsDirectPingoraEnvModeDrift();
+  assertSnapshotRejectsShadowPingoraEnvModeDrift();
   assertSnapshotRedactsEnvProbeTokens();
   assertFailOnCriticalRejectsEnvDriftWithoutWritingEnv();
   assertFailOnCriticalRejectsMissingDirectCapability();
@@ -120,6 +123,16 @@ function assertScriptShape() {
     'AmbientCapabilities=CAP_NET_BIND_SERVICE',
     '状态快照必须记录 Pingora 低端口 capability 是否生效。',
   );
+  assertIncludes(
+    content,
+    '--expected-pingora-env-mode',
+    '状态快照必须支持按阶段强制校验 active Pingora env 姿态。',
+  );
+  assertIncludes(
+    content,
+    'summarizePingoraEnvPosture',
+    '状态快照必须输出 Pingora env shadow/direct 姿态摘要。',
+  );
   if (content.includes('writeFile') || content.includes('rmSync(')) {
     failures.push('状态快照脚本不应写文件或删除文件。');
   }
@@ -173,6 +186,16 @@ function assertSnapshotSucceedsWithFakeSystemctlAndReleaseRoot() {
     'OK',
     'direct 快照所有 fake 检查通过时 summary 应为 OK。',
   );
+  assertEqual(
+    payload.pingoraEnv?.posture?.mode,
+    'direct',
+    '状态快照必须能把完整低端口 TLS env 识别为 direct 姿态。',
+  );
+  assertEqual(
+    payload.pingoraEnv?.posture?.directReady,
+    true,
+    '完整低端口 TLS env 必须标记 directReady=true。',
+  );
   const healthPatrolCheck = payload.checks.find(
     (check) => check.name === 'production-health-patrol',
   );
@@ -246,6 +269,122 @@ function assertSnapshotSucceedsWithFakeSystemctlAndReleaseRoot() {
   );
 }
 
+function assertSnapshotAcceptsExpectedDirectPingoraEnvMode() {
+  const fixture = prepareFixture('direct-env-mode-ok', {
+    gatewayMode: 'pingora-direct',
+    publicBaseUrl: 'https://127.0.0.1',
+    publicHost: 'example.com',
+    directCapability: true,
+    pingoraActive: true,
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-pingora-env-mode',
+    'direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(result, 0, 'direct env 姿态符合预期时快照应成功。');
+  const payload = parseJson(result.stdout, 'direct env 姿态快照输出');
+  assertEqual(
+    payload.pingoraEnv?.posture?.expectedMode,
+    'direct',
+    '快照必须记录 expected Pingora env mode。',
+  );
+  assertEqual(
+    payload.pingoraEnv?.posture?.directReady,
+    true,
+    'direct env 姿态正例必须 directReady=true。',
+  );
+}
+
+function assertSnapshotRejectsDirectPingoraEnvModeDrift() {
+  const fixture = prepareFixture('direct-env-mode-drift', {
+    gatewayMode: 'pingora-direct',
+    publicBaseUrl: 'https://127.0.0.1',
+    publicHost: 'example.com',
+    directCapability: true,
+    pingoraActive: true,
+    pingoraEnvMode: 'shadow',
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-enable',
+    '--expected-gateway-mode',
+    'pingora-direct',
+    '--expected-pingora-env-mode',
+    'direct',
+    '--expected-public-base-url',
+    'https://127.0.0.1',
+    '--expected-public-host',
+    'example.com',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(
+    result,
+    1,
+    '启用后要求 direct env 但 active env 仍是 shadow 时必须失败。',
+  );
+  const payload = parseJson(result.stdout, 'direct env 漂移快照输出');
+  assertEqual(
+    payload.pingoraEnv?.status,
+    'CRITICAL',
+    'direct env 漂移必须标记 pingoraEnv 为 CRITICAL。',
+  );
+  assertIncludes(
+    payload.pingoraEnv?.diagnostics || [],
+    'Pingora direct env 要求 tlsListen 已配置',
+    'direct env 漂移必须给出缺少 tlsListen 的诊断。',
+  );
+}
+
+function assertSnapshotRejectsShadowPingoraEnvModeDrift() {
+  const fixture = prepareFixture('shadow-env-mode-drift', {
+    gatewayMode: 'nginx',
+    publicBaseUrl: 'https://example.com',
+    publicHost: '',
+    directCapability: false,
+    pingoraActive: true,
+  });
+  const result = runSnapshot(fixture, [
+    '--phase',
+    'post-rollback',
+    '--expected-gateway-mode',
+    'nginx',
+    '--expected-pingora-env-mode',
+    'shadow',
+    '--expected-public-base-url',
+    'https://example.com',
+    '--require-empty-public-host',
+    '--fail-on-critical',
+  ]);
+
+  assertStatus(
+    result,
+    1,
+    '回退后要求 shadow env 但 active env 仍有 direct 配置时必须失败。',
+  );
+  const payload = parseJson(result.stdout, 'shadow env 漂移快照输出');
+  assertEqual(
+    payload.pingoraEnv?.posture?.shadowReady,
+    false,
+    'shadow env 漂移必须标记 shadowReady=false。',
+  );
+  assertIncludes(
+    payload.pingoraEnv?.diagnostics || [],
+    'tlsCertFile 为空',
+    'shadow env 漂移必须给出 TLS cert 残留诊断。',
+  );
+}
+
 function assertFailOnCriticalRejectsEnvDriftWithoutWritingEnv() {
   const fixture = prepareFixture('env-drift', {
     gatewayMode: 'nginx',
@@ -657,15 +796,7 @@ function prepareFixture(name, options) {
   writeFileSync(healthEnvFile, healthEnvText, 'utf8');
   writeFileSync(
     pingoraEnvFile,
-    [
-      'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
-      'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=0.0.0.0:443',
-      'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=0.0.0.0:80',
-      'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/etc/letsencrypt/live/example/fullchain.pem',
-      'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/etc/letsencrypt/live/example/privkey.pem',
-      `GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN=${options.pingoraProbeToken || 'fake-token'}`,
-      '',
-    ].join('\n'),
+    pingoraEnvText(options),
     'utf8',
   );
   writeFileSync(
@@ -686,6 +817,32 @@ function prepareFixture(name, options) {
   };
 }
 
+function pingoraEnvText(options) {
+  const lines =
+    options.pingoraEnvMode === 'shadow'
+      ? [
+          'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=',
+          'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=',
+          'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=http',
+        ]
+      : [
+          'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=0.0.0.0:443',
+          'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=0.0.0.0:80',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/etc/letsencrypt/live/example/fullchain.pem',
+          'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/etc/letsencrypt/live/example/privkey.pem',
+          'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
+        ];
+  return [
+    ...lines,
+    `GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN=${options.pingoraProbeToken || 'fake-token'}`,
+    '',
+  ].join('\n');
+}
+
 function prepareReleaseRoot(releaseRoot) {
   for (const dir of [
     'scripts',
@@ -753,6 +910,7 @@ function prepareReleaseRoot(releaseRoot) {
     'scripts/deploy/pingora-realpath-canary-enable.sh',
     'scripts/deploy/pingora-realpath-canary-disable.sh',
     'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
     'scripts/deploy/pingora-tls-cert-sync.mjs',
     'deploy/systemd/genarrative-pingora-gateway.service',
     'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
@@ -778,6 +936,7 @@ function prepareReleaseRoot(releaseRoot) {
     'scripts/deploy/pingora-realpath-canary-enable.sh',
     'scripts/deploy/pingora-realpath-canary-disable.sh',
     'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
     'scripts/deploy/pingora-tls-cert-sync.mjs',
   ]) {
     chmodExecutable(path.join(releaseRoot, file));
diff --git a/scripts/check-pingora-direct-enable.mjs b/scripts/check-pingora-direct-enable.mjs
index bc3f50d08..dcfe02110 100644
--- a/scripts/check-pingora-direct-enable.mjs
+++ b/scripts/check-pingora-direct-enable.mjs
@@ -16,6 +16,9 @@ import path from 'node:path';
 const ENABLE_SCRIPT = 'scripts/deploy/pingora-direct-enable.sh';
 const PREFLIGHT_SCRIPT = 'scripts/check-pingora-direct-preflight.mjs';
 const failures = [];
+const [DIRECT_TLS_PORT, DIRECT_HTTP_REDIRECT_PORT] = allocateLoopbackPorts(2);
+const DIRECT_TLS_LISTEN = `127.0.0.1:${DIRECT_TLS_PORT}`;
+const DIRECT_HTTP_REDIRECT_LISTEN = `127.0.0.1:${DIRECT_HTTP_REDIRECT_PORT}`;
 
 const tmpRoot = mkdtempSync(path.join(tmpdir(), 'genarrative-pingora-enable-'));
 
@@ -271,8 +274,8 @@ function assertDirectPreflightRejectsPublicForwardedForTrust() {
   writeFileSync(
     envPath,
     [
-      'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=127.0.0.1:18443',
-      'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=127.0.0.1:18080',
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
       'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/tmp/cert.pem',
       'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/tmp/key.pem',
       'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
@@ -292,8 +295,8 @@ function assertDirectPreflightRejectsPublicForwardedForTrust() {
   writeFileSync(
     envPath,
     [
-      'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=127.0.0.1:18443',
-      'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=127.0.0.1:18080',
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
       'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=/tmp/cert.pem',
       'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=/tmp/key.pem',
       'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
@@ -390,8 +393,8 @@ function assertReleaseLayoutDryRunUsesBundledDirectChecks() {
   writeFileSync(
     envPath,
     [
-      'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=127.0.0.1:18443',
-      'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=127.0.0.1:18080',
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
       'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
       `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=${certPath}`,
       `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=${keyPath}`,
@@ -833,8 +836,8 @@ function assertDryRunRunsPreflightWhenRequested() {
   writeFileSync(
     envPath,
     [
-      'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=127.0.0.1:18443',
-      'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=127.0.0.1:18080',
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
       'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
       `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=${certPath}`,
       `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=${keyPath}`,
@@ -1845,8 +1848,8 @@ function assertApplyFailsWhenDirectLiveSmokeFails() {
   writeFileSync(
     envPath,
     [
-      'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=127.0.0.1:18443',
-      'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=127.0.0.1:18080',
+      `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=${DIRECT_TLS_LISTEN}`,
+      `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=${DIRECT_HTTP_REDIRECT_LISTEN}`,
       'GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO=https',
       `GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=${certPath}`,
       `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=${keyPath}`,
@@ -2347,3 +2350,33 @@ function assertIncludes(content, needle, reason) {
     failures.push(`${reason} 缺少: ${needle}`);
   }
 }
+
+function allocateLoopbackPorts(count) {
+  const ports = [];
+  for (let offset = 0; ports.length < count && offset < 1000; offset += 1) {
+    const candidate = 28080 + offset;
+    const result = spawnSync(
+      process.execPath,
+      [
+        '-e',
+        [
+          "const net = require('node:net');",
+          `const server = net.createServer();`,
+          `server.once('error', () => process.exit(1));`,
+          `server.listen(${candidate}, '127.0.0.1', () => server.close(() => process.exit(0)));`,
+        ].join(''),
+      ],
+      {
+        cwd: process.cwd(),
+        encoding: 'utf8',
+      },
+    );
+    if ((result.status ?? 1) === 0) {
+      ports.push(candidate);
+    }
+  }
+  if (ports.length !== count) {
+    throw new Error('无法为 Pingora direct enable 自测分配空闲 loopback 端口。');
+  }
+  return ports;
+}
diff --git a/scripts/check-pingora-direct-rehearsal-status.mjs b/scripts/check-pingora-direct-rehearsal-status.mjs
index 0cbf8bbda..0df53ed12 100644
--- a/scripts/check-pingora-direct-rehearsal-status.mjs
+++ b/scripts/check-pingora-direct-rehearsal-status.mjs
@@ -452,6 +452,7 @@ function prepareReleaseRoot(releaseRoot) {
     'scripts/deploy/pingora-realpath-canary-enable.sh',
     'scripts/deploy/pingora-realpath-canary-disable.sh',
     'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
     'scripts/deploy/pingora-tls-cert-sync.mjs',
   ];
   for (const relativePath of copyScripts) {
@@ -463,6 +464,7 @@ function prepareReleaseRoot(releaseRoot) {
     'scripts/deploy/pingora-realpath-canary-enable.sh',
     'scripts/deploy/pingora-realpath-canary-disable.sh',
     'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
     'scripts/deploy/pingora-tls-cert-sync.mjs',
   ]) {
     chmodSync(path.join(releaseRoot, relativePath), 0o755);
diff --git a/scripts/check-pingora-gateway-env-shadow-switch.mjs b/scripts/check-pingora-gateway-env-shadow-switch.mjs
new file mode 100644
index 000000000..57a28ee43
--- /dev/null
+++ b/scripts/check-pingora-gateway-env-shadow-switch.mjs
@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const SWITCH_SCRIPT = 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs';
+const failures = [];
+const tmpRoot = mkdtempSync(
+  path.join(tmpdir(), 'genarrative-pingora-gateway-env-shadow-switch-'),
+);
+
+try {
+  main();
+} finally {
+  rmSync(tmpRoot, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+  console.error('[check:pingora-gateway-env-shadow-switch] FAILED');
+  for (const failure of failures) {
+    console.error(`- ${failure}`);
+  }
+  process.exit(1);
+}
+
+console.log('[check:pingora-gateway-env-shadow-switch] OK');
+
+function main() {
+  assertScriptShape();
+  assertDryRunDoesNotModifyEnv();
+  assertApplyRestoresShadowAndPreservesOtherKeys();
+  assertApplyPreservesEnvFileMode();
+  assertMissingManagedKeysAreAppended();
+  assertDuplicateManagedKeysFail();
+  assertRejectsRelativeAndRootEnvFile();
+  assertRejectsSymlinkEnvFileBeforeWrite();
+  assertRejectsControlCharacterEnvFile();
+}
+
+function assertScriptShape() {
+  const content = readFileSync(SWITCH_SCRIPT, 'utf8');
+  assertIncludes(content, '--apply', '切换脚本必须显式要求 --apply 才写 env。');
+  assertIncludes(
+    content,
+    '当前是 dry-run',
+    '切换脚本必须在 dry-run 中明确不会写 env。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_LISTEN: \'127.0.0.1:18081\'',
+    '切换脚本必须固定恢复 Pingora shadow 高端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: \'\'',
+    '切换脚本必须清空 TLS 低端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: \'\'',
+    '切换脚本必须清空 HTTP redirect 低端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: \'\'',
+    '切换脚本必须清空 TLS 证书链路径，避免无 TLS_LISTEN 但残留 cert。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: \'\'',
+    '切换脚本必须清空 TLS 私钥路径，避免无 TLS_LISTEN 但残留 key。',
+  );
+  assertIncludes(
+    content,
+    'assertShadowEnv(checkFile);',
+    '切换脚本必须先用临时目标 env 复核 shadow 口径。',
+  );
+  assertIncludes(
+    content,
+    'writeEnvFileAtomically(config.envFile, nextText);',
+    '切换脚本通过复核后才可原子写入真实 env。',
+  );
+  assertIncludes(
+    content,
+    '--env-file 不能是符号链接',
+    'apply 写入真实 env 前必须拒绝符号链接目标。',
+  );
+  assertIncludes(
+    content,
+    'DRY_RUN_ENV_FILE_MODE = 0o600',
+    '临时复核 env 文件权限必须固定为 0600。',
+  );
+  assertIncludes(
+    content,
+    'chownSync(tempFile, currentStat.uid, currentStat.gid);',
+    '真实 env 原子替换必须保留原文件 owner/group。',
+  );
+}
+
+function assertDryRunDoesNotModifyEnv() {
+  const envFile = writeEnv('dry-run.env', {
+    GENARRATIVE_PINGORA_GATEWAY_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: '0.0.0.0:80',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: '/etc/genarrative/pingora-tls/example/privkey.pem',
+  });
+  const before = readFileSync(envFile, 'utf8');
+  const result = runSwitch(['--env-file', envFile]);
+
+  assertStatus(result, 0, 'dry-run 应成功。');
+  assertEqual(
+    readFileSync(envFile, 'utf8'),
+    before,
+    'dry-run 不应修改真实 Pingora gateway env。',
+  );
+  assertIncludes(
+    result.stdout,
+    '当前是 dry-run',
+    'dry-run 输出必须明确不会写入 env。',
+  );
+}
+
+function assertApplyRestoresShadowAndPreservesOtherKeys() {
+  const envFile = writeEnv('apply.env', {
+    GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API: 'http://127.0.0.1:8082',
+    GENARRATIVE_PINGORA_GATEWAY_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: '0.0.0.0:80',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: '/etc/genarrative/pingora-tls/example/privkey.pem',
+    GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED: 'true',
+  });
+  const result = runSwitch(['--env-file', envFile, '--apply']);
+  const content = readFileSync(envFile, 'utf8');
+
+  assertStatus(result, 0, 'apply 应成功。');
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+    'apply 必须恢复 shadow 高端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=',
+    'apply 必须清空 TLS 低端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=',
+    'apply 必须清空 HTTP redirect 低端口监听。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=',
+    'apply 必须清空 TLS 证书链路径。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=',
+    'apply 必须清空 TLS 私钥路径。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API=http://127.0.0.1:8082',
+    'apply 不应修改其它 Pingora gateway env。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true',
+    'apply 不应修改接流保护配置。',
+  );
+}
+
+function assertApplyPreservesEnvFileMode() {
+  const envFile = writeEnv('mode.env', {
+    GENARRATIVE_PINGORA_GATEWAY_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: '0.0.0.0:443',
+    GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: '0.0.0.0:80',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: '/etc/genarrative/pingora-tls/example/fullchain.pem',
+    GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: '/etc/genarrative/pingora-tls/example/privkey.pem',
+  });
+  chmodSync(envFile, 0o640);
+  const before = statSync(envFile);
+  const result = runSwitch(['--env-file', envFile, '--apply']);
+  const after = statSync(envFile);
+
+  assertStatus(result, 0, 'apply 保留权限 smoke 应成功。');
+  assertEqual(
+    after.mode & 0o777,
+    before.mode & 0o777,
+    'apply 原子替换必须保留 env 文件权限。',
+  );
+}
+
+function assertMissingManagedKeysAreAppended() {
+  const envFile = writeEnv('append.env', {
+    GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_API: 'http://127.0.0.1:8082',
+  });
+  const result = runSwitch(['--env-file', envFile, '--apply']);
+  const content = readFileSync(envFile, 'utf8');
+
+  assertStatus(result, 0, '缺失目标键时 apply 应成功。');
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+    '缺失 LISTEN 时必须追加 shadow 默认值。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN=',
+    '缺失 TLS_LISTEN 时必须追加空值。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN=',
+    '缺失 HTTP_REDIRECT_LISTEN 时必须追加空值。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE=',
+    '缺失 TLS_CERT_FILE 时必须追加空值。',
+  );
+  assertIncludes(
+    content,
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE=',
+    '缺失 TLS_KEY_FILE 时必须追加空值。',
+  );
+}
+
+function assertDuplicateManagedKeysFail() {
+  const envFile = path.join(tmpRoot, 'duplicate.env');
+  writeFileSync(
+    envFile,
+    [
+      'GENARRATIVE_PINGORA_GATEWAY_LISTEN=0.0.0.0:443',
+      'GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081',
+      '',
+    ].join('\n'),
+    'utf8',
+  );
+  const result = runSwitch(['--env-file', envFile]);
+
+  assertStatus(result, 1, '重复目标键必须失败。');
+  assertIncludes(
+    result.stderr,
+    'pingora gateway env 中存在重复配置',
+    '重复目标键失败时必须说明具体原因。',
+  );
+}
+
+function assertRejectsRelativeAndRootEnvFile() {
+  const relative = runSwitch(['--env-file', 'relative.env']);
+  assertStatus(relative, 1, '相对 env 路径必须失败。');
+  assertIncludes(
+    relative.stderr,
+    '--env-file 必须是绝对路径',
+    '相对 env 路径失败时必须说明原因。',
+  );
+
+  const root = runSwitch(['--env-file', '/']);
+  assertStatus(root, 1, '文件系统根目录 env 路径必须失败。');
+  assertIncludes(
+    root.stderr,
+    '--env-file 不能是文件系统根目录',
+    '根目录 env 路径失败时必须说明原因。',
+  );
+}
+
+function assertRejectsSymlinkEnvFileBeforeWrite() {
+  const target = writeEnv('symlink-target.env', {
+    GENARRATIVE_PINGORA_GATEWAY_LISTEN: '0.0.0.0:443',
+  });
+  const link = path.join(tmpRoot, 'symlink.env');
+  symlinkSync(target, link);
+  const before = readFileSync(target, 'utf8');
+  const result = runSwitch(['--env-file', link, '--apply']);
+
+  assertStatus(result, 1, '符号链接 env 必须失败。');
+  assertIncludes(
+    result.stderr,
+    '--env-file 不能是符号链接',
+    '符号链接 env 失败时必须说明原因。',
+  );
+  assertEqual(
+    readFileSync(target, 'utf8'),
+    before,
+    '符号链接 env 被拒绝后不应写真实目标文件。',
+  );
+}
+
+function assertRejectsControlCharacterEnvFile() {
+  const result = spawnSync(
+    process.execPath,
+    ['--', SWITCH_SCRIPT, '--env-file', `${tmpRoot}/bad\n.env`],
+    {
+      cwd: process.cwd(),
+      encoding: 'utf8',
+    },
+  );
+  assertStatus(result, 1, '控制字符 env 路径必须失败。');
+  assertIncludes(
+    result.stderr,
+    '--env-file 不能包含换行或 NUL 字符',
+    '控制字符 env 路径失败时必须说明原因。',
+  );
+}
+
+function runSwitch(args) {
+  return spawnSync(process.execPath, ['--', SWITCH_SCRIPT, ...args], {
+    cwd: process.cwd(),
+    encoding: 'utf8',
+  });
+}
+
+function writeEnv(fileName, values) {
+  const filePath = path.join(tmpRoot, fileName);
+  const lines = Object.entries(values).map(([key, value]) => `${key}=${value}`);
+  writeFileSync(filePath, `${lines.join('\n')}\n`, 'utf8');
+  return filePath;
+}
+
+function assertStatus(result, expected, message) {
+  if ((result.status ?? 0) !== expected) {
+    failures.push(
+      `${message} 实际退出码 ${result.status}。stdout=${result.stdout || '<empty>'} stderr=${result.stderr || '<empty>'}`,
+    );
+  }
+}
+
+function assertIncludes(value, expected, message) {
+  if (!String(value || '').includes(expected)) {
+    failures.push(`${message} 缺少 ${expected}。`);
+  }
+}
+
+function assertEqual(actual, expected, message) {
+  if (actual !== expected) {
+    failures.push(`${message} 实际 ${actual}，预期 ${expected}。`);
+  }
+}
diff --git a/scripts/check-pingora-gateway-smoke.mjs b/scripts/check-pingora-gateway-smoke.mjs
index 363573e98..ef2aac8c1 100644
--- a/scripts/check-pingora-gateway-smoke.mjs
+++ b/scripts/check-pingora-gateway-smoke.mjs
@@ -19,6 +19,9 @@ const sockets = new Set();
 const tempDirs = [];
 const SPACETIME_WEBSOCKET_PROTOCOL = 'v2.bsatn.spacetimedb';
 const SECRET_VALUE_FLAGS = new Set(['--probe-token']);
+const PNG_MAGIC_BYTES = Buffer.from([
+  0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a,
+]);
 
 const config = parseArgs(process.argv.slice(2));
 
@@ -54,6 +57,7 @@ async function main() {
 
   const api = await startApiMock();
   const spacetime = await startSpacetimeMock();
+  const gitea = await startGiteaMock();
   const listenPort = await getFreePort();
   const tlsListenPort = await getFreePort();
   const redirectListenPort = await getFreePort();
@@ -120,6 +124,22 @@ async function main() {
     'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
     'HTTP 重定向未配置 TLS 入口',
   );
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS: 'git.genarrative.world',
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM',
+    'Gitea Host 缺少上游',
+  );
+  expectInvalidConfigRejected(
+    gatewayBinary,
+    {
+      GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM: '127.0.0.1:3000',
+    },
+    'GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS',
+    'Gitea 上游缺少 Host',
+  );
   const gateway = spawn(gatewayBinary, [], {
     cwd: repoRoot,
     env: {
@@ -132,6 +152,9 @@ async function main() {
       GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_TARGET_SCHEME: 'https',
       GENARRATIVE_PINGORA_GATEWAY_API_UPSTREAM: `127.0.0.1:${api.port}`,
       GENARRATIVE_PINGORA_GATEWAY_SPACETIME_UPSTREAM: `127.0.0.1:${spacetime.port}`,
+      GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS:
+        'git.genarrative.world, Git-Alias.Genarrative.World:443',
+      GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM: `127.0.0.1:${gitea.port}`,
       GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT: webRoot,
       GENARRATIVE_PINGORA_GATEWAY_ACME_ROOT: acmeRoot,
       GENARRATIVE_PINGORA_GATEWAY_MAINTENANCE_FILE: maintenanceFile,
@@ -188,6 +211,7 @@ async function main() {
     accessLogFile,
     api,
     spacetime,
+    gitea,
   );
 }
 
@@ -207,9 +231,12 @@ function expectInvalidConfigRejected(
     },
     shell: false,
     encoding: 'utf8',
+    timeout: 3000,
   });
 
-  if (result.status === 0) {
+  if (result.error?.code === 'ETIMEDOUT') {
+    failures.push(`配置错误启动失败: ${label} 未被拒绝，进程超时后已终止`);
+  } else if (result.status === 0) {
     failures.push(`配置错误启动失败: ${label} 未被拒绝`);
   }
   const output = `${result.stdout || ''}\n${result.stderr || ''}`;
@@ -253,6 +280,17 @@ function parseArgs(argv) {
 async function prepareStaticRoots(webRoot, acmeRoot) {
   await mkdir(path.join(webRoot, 'admin', 'assets'), { recursive: true });
   await mkdir(path.join(webRoot, 'assets'), { recursive: true });
+  await mkdir(
+    path.join(
+      webRoot,
+      'Icons',
+      "Admurin's Pixel Items",
+      "Admurin's Pixel Items",
+      'General',
+      'Singles',
+    ),
+    { recursive: true },
+  );
   await mkdir(path.join(acmeRoot, '.well-known', 'acme-challenge'), {
     recursive: true,
   });
@@ -285,6 +323,21 @@ async function prepareStaticRoots(webRoot, acmeRoot) {
     path.join(webRoot, 'assets', 'large-image.webp'),
     Buffer.alloc(4096, 0x52),
   );
+  await writeFile(
+    path.join(
+      webRoot,
+      'Icons',
+      "Admurin's Pixel Items",
+      "Admurin's Pixel Items",
+      'General',
+      'Singles',
+      '499_Iron_Gear.png',
+    ),
+    Buffer.concat([
+      PNG_MAGIC_BYTES,
+      Buffer.from([0x00, 0x00, 0x00, 0x0d, 0x49, 0x48, 0x44, 0x52]),
+    ]),
+  );
   await writeFile(
     path.join(webRoot, 'admin', 'assets', 'admin.js'),
     'console.log("admin asset");',
@@ -454,6 +507,43 @@ async function startSpacetimeMock() {
   };
 }
 
+async function startGiteaMock() {
+  const state = {
+    requests: [],
+  };
+  const server = http.createServer(async (request, response) => {
+    const body = await readRequestBody(request);
+    state.requests.push({
+      method: request.method || '',
+      url: request.url || '',
+      headers: request.headers,
+      body,
+    });
+
+    response.writeHead(200, {
+      'Content-Type': 'application/json; charset=utf-8',
+      'X-Upstream': 'gitea',
+    });
+    response.end(
+      JSON.stringify({
+        ok: true,
+        upstream: 'gitea',
+        method: request.method,
+        url: request.url,
+        forwardedProto: request.headers['x-forwarded-proto'] || '',
+        forwardedHost: request.headers['x-forwarded-host'] || '',
+        host: request.headers.host || '',
+      }),
+    );
+  });
+
+  const port = await listen(server);
+  return {
+    port,
+    state,
+  };
+}
+
 async function runSmokeCases(
   baseUrl,
   tlsBaseUrl,
@@ -463,6 +553,7 @@ async function runSmokeCases(
   accessLogFile,
   api,
   spacetime,
+  gitea,
 ) {
   await expectHttp(
     baseUrl,
@@ -677,6 +768,32 @@ async function runSmokeCases(
     undefined,
     'gzip types 不压缩图片资源',
   );
+  await expectStaticPng(
+    baseUrl,
+    "/Icons/Admurin%27s%20Pixel%20Items/Admurin%27s%20Pixel%20Items/General/Singles/499_Iron_Gear.png",
+    '百分号编码图标路径返回 PNG',
+  );
+  await expectHttp(
+    baseUrl,
+    '/assets%2ffavicon.svg',
+    404,
+    '',
+    '静态路径拒绝编码斜杠',
+  );
+  await expectRawPathHttp(
+    baseUrl,
+    '/assets/%2e%2e/favicon.svg',
+    404,
+    '',
+    '静态路径拒绝编码上级目录',
+  );
+  await expectHttp(
+    baseUrl,
+    '/assets/%GG',
+    404,
+    '',
+    '静态路径拒绝非法百分号编码',
+  );
   await expectHttp(
     baseUrl,
     '/admin/assets/admin.js',
@@ -894,6 +1011,50 @@ async function runSmokeCases(
     spacetime,
   );
 
+  const giteaBeforeRequests = gitea.state.requests.length;
+  const giteaResponse = await expectHttp(
+    baseUrl,
+    '/api/v1/repos/GenarrativeAI/Genarrative',
+    200,
+    '"upstream":"gitea"',
+    'Gitea Host 路由转发',
+    {
+      headers: {
+        Host: 'git.genarrative.world:443',
+        'X-Request-Id': 'gitea-host-request-id',
+      },
+    },
+  );
+  const giteaPayload = JSON.parse(giteaResponse.body || '{}');
+  ensure(
+    giteaPayload.host === 'git.genarrative.world:443',
+    `Gitea 上游 Host 未透传：${giteaPayload.host || '-'}`,
+  );
+  ensure(
+    giteaPayload.forwardedHost === 'git.genarrative.world:443',
+    `Gitea 上游 X-Forwarded-Host 未透传：${giteaPayload.forwardedHost || '-'}`,
+  );
+  ensure(
+    giteaPayload.forwardedProto === 'https',
+    `Gitea 上游 X-Forwarded-Proto 未对齐：${giteaPayload.forwardedProto || '-'}`,
+  );
+  await expectHttp(
+    baseUrl,
+    '/api/v1/repos/GenarrativeAI/Genarrative',
+    200,
+    '"upstream":"gitea"',
+    'Gitea Host 别名路由转发',
+    {
+      headers: {
+        Host: 'git-alias.genarrative.world',
+      },
+    },
+  );
+  ensure(
+    gitea.state.requests.length === giteaBeforeRequests + 2,
+    `Gitea Host 路由没有稳定打到 Gitea mock：${gitea.state.requests.length - giteaBeforeRequests}`,
+  );
+
   await expectAccessLog(accessLogFile);
   await expectAccessLogEntries(accessLogFile, [
     {
@@ -932,10 +1093,34 @@ async function runSmokeCases(
       path: '/assets/app.js',
       status: 206,
     },
+    {
+      requestId: 'gitea-host-request-id',
+      method: 'GET',
+      path: '/api/v1/repos/GenarrativeAI/Genarrative',
+      status: 200,
+      proxyTarget: 'Gitea',
+    },
   ]);
 
   await mkdir(path.dirname(maintenanceFile), { recursive: true });
   await writeFile(maintenanceFile, 'enabled');
+  const giteaRequestsBeforeMaintenance = gitea.state.requests.length;
+  await expectHttp(
+    baseUrl,
+    '/user/login',
+    200,
+    '"upstream":"gitea"',
+    '维护模式不拦截 Gitea Host',
+    {
+      headers: {
+        Host: 'git.genarrative.world',
+      },
+    },
+  );
+  ensure(
+    gitea.state.requests.length === giteaRequestsBeforeMaintenance + 1,
+    '维护模式 Gitea Host 请求没有打到 Gitea mock',
+  );
   await expectHttp(
     baseUrl,
     '/api/creation-entry/config',
@@ -1116,6 +1301,49 @@ async function expectNotCompressedResponse(baseUrl, route, bodyNeedle, label) {
   }
 }
 
+async function expectStaticPng(baseUrl, route, label) {
+  console.log(`[pingora-gateway-smoke] ${label}`);
+  const response = await requestHttp(`${baseUrl}${route}`, {
+    rawBody: true,
+  });
+
+  if (response.status !== 200) {
+    failures.push(`${label}: 期望 HTTP 200，实际 ${response.status}`);
+    return;
+  }
+  if (!String(response.headers['content-type'] || '').startsWith('image/png')) {
+    failures.push(
+      `${label}: 期望 Content-Type=image/png，实际 ${response.headers['content-type'] || '-'}`,
+    );
+  }
+  if (!response.bodyBuffer.subarray(0, 8).equals(PNG_MAGIC_BYTES)) {
+    failures.push(`${label}: 响应体不是 PNG magic bytes`);
+  }
+  if (response.body.includes('<!doctype html>')) {
+    failures.push(`${label}: 命中了 SPA fallback HTML`);
+  }
+}
+
+async function expectRawPathHttp(baseUrl, route, status, bodyNeedle, label) {
+  console.log(`[pingora-gateway-smoke] ${label}`);
+  let response;
+  try {
+    response = await rawHttpPathRequest(baseUrl, route);
+  } catch (error) {
+    failures.push(
+      `${label}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return;
+  }
+
+  if (response.status !== status) {
+    failures.push(`${label}: 期望 HTTP ${status}，实际 ${response.status}`);
+  }
+  if (bodyNeedle && !response.body.includes(bodyNeedle)) {
+    failures.push(`${label}: 响应体缺少 ${bodyNeedle}`);
+  }
+}
+
 async function expectCompressedResponse(baseUrl, route, bodyNeedle, options) {
   const label = options.label;
   console.log(`[pingora-gateway-smoke] ${label}`);
@@ -1183,7 +1411,7 @@ async function expectAccessLogEntries(accessLogFile, expectedEntries) {
           entry.method === expected.method &&
           entry.path === expected.path &&
           Number.parseInt(entry.status || '', 10) === expected.status &&
-          entry.proxy_target === 'Local'
+          entry.proxy_target === (expected.proxyTarget || 'Local')
         );
       });
     } catch {
@@ -1469,6 +1697,22 @@ async function rawHttpRequest(url, headers = {}) {
   });
 }
 
+function rawHttpPathRequest(baseUrl, route, headers = {}) {
+  return new Promise((resolve, reject) => {
+    const target = new URL(baseUrl);
+    const socket = net.connect(
+      { host: target.hostname, port: Number(target.port) },
+      () => {
+        socket.write(buildRawHttpPathRequest(target, route, headers));
+        collectRawHttpResponse(socket, `${baseUrl}${route}`, 35000)
+          .then(resolve, reject)
+          .finally(() => socket.destroy());
+      },
+    );
+    socket.on('error', reject);
+  });
+}
+
 function buildRawHttpRequest(target, headers) {
   const mergedHeaders = {
     Host: target.host,
@@ -1486,6 +1730,18 @@ function buildRawHttpRequest(target, headers) {
   ].join('\r\n');
 }
 
+function buildRawHttpPathRequest(target, route, headers) {
+  const mergedHeaders = {
+    Host: target.host,
+    Connection: 'close',
+    ...headers,
+  };
+  const headerLines = Object.entries(mergedHeaders).map(
+    ([name, value]) => `${name}: ${value}`,
+  );
+  return [`GET ${route} HTTP/1.1`, ...headerLines, '', ''].join('\r\n');
+}
+
 function collectRawHttpResponse(socket, url, timeoutMs) {
   return new Promise((resolve, reject) => {
     let raw = Buffer.alloc(0);
diff --git a/scripts/check-pingora-release-readiness-plan.mjs b/scripts/check-pingora-release-readiness-plan.mjs
index adc5241f0..f2673d276 100644
--- a/scripts/check-pingora-release-readiness-plan.mjs
+++ b/scripts/check-pingora-release-readiness-plan.mjs
@@ -31,7 +31,6 @@ const requireDirectBaseArgs = [
   '--direct-preflight-check-service-env-file',
   '--direct-preflight-check-service-user-cert-readable',
   '--direct-preflight-check-service-binary-executable',
-  '--direct-preflight-check-ports-free',
   '--direct-spacetime-database',
   'genarrative-prod',
   '--direct-pingora-access-log',
@@ -40,6 +39,25 @@ const requireDirectBaseArgs = [
   '/etc/genarrative/health-patrol.env',
 ];
 
+const cutoverRequiredArgs = [
+  '--direct-preflight-check-ports-free',
+  '--rollback-nginx-smoke-url',
+  'https://example.com/',
+  '--rollback-nginx-smoke-expect-body',
+  '<!doctype html>',
+  '--rollback-health-patrol-public-base-url',
+  'http://127.0.0.1',
+];
+
+function cutoverPlanArgs(...extraArgs) {
+  return [
+    ...requireDirectBaseArgs,
+    '--dry-run-cutover',
+    ...cutoverRequiredArgs,
+    ...extraArgs,
+  ];
+}
+
 const requireLiveBaseArgs = [
   '--require-live',
   '--live-base-url',
@@ -86,6 +104,7 @@ function main() {
   assertDefaultPlanIncludesProductionApiDeploySmoke();
   assertDefaultPlanIncludesHealthPatrolEnvSmoke();
   assertDefaultPlanIncludesPingoraHealthPatrolEnvSwitchSmoke();
+  assertDefaultPlanIncludesPingoraGatewayEnvShadowSwitchSmoke();
   assertDefaultPlanIncludesPingoraCurrentReleaseAuditSmoke();
   assertDefaultPlanIncludesPingoraDirectRehearsalStatusSmoke();
   assertDefaultPlanIncludesPingoraCutoverStatusSnapshotSmoke();
@@ -98,10 +117,11 @@ function main() {
   assertDefaultPlanIncludesPingoraProductionReleaseBuildSmoke();
   assertReleaseRuntimeOnlyPlanUsesCurrentReleaseScripts();
   assertReleaseRuntimeOnlyPlanIncludesDirectRehearsalStatus();
+  assertReleaseRuntimeOnlyAllowsRealpathOnlyCanary();
   assertReleaseRuntimeOnlyKeepsInvokedCurrentSymlinkPath();
   assertReleaseRuntimeOnlyRejectsSourceOnlyFlags();
   assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook();
-  assertDryRunCutoverDefaultRollbackBodyIgnoresProcessEnv();
+  assertDryRunCutoverExplicitRollbackBodyIgnoresProcessEnv();
   assertDryRunCutoverPostEnableReadinessRedactsDirectProbeToken();
   assertDryRunCutoverPlanIncludesHostConsistencyConfirmation();
   assertDryRunCutoverAllowsSameHostnameWithDifferentPorts();
@@ -131,7 +151,8 @@ function main() {
   assertRequireDirectForcesHostSni();
   assertRequireDirectForcesRedirectHost();
   assertRequireDirectForcesPingoraAccessLog();
-  assertRequireDirectForcesPreflightSystemdCertReadableAndPortsFree();
+  assertRequireDirectForcesPreflightSystemdCertReadable();
+  assertDryRunCutoverForcesPortsFreePreflight();
   assertRequireDirectForcesExplicitSpacetimeDatabase();
   assertRequireDirectForcesHealthPatrolEnvCheck();
   assertDryRunPlanRedactsDirectProbeToken();
@@ -150,7 +171,8 @@ function main() {
   assertRequireDirectRejectsMissingServiceEnvFilePreflight();
   assertRequireDirectRejectsMissingServiceUserCertReadablePreflight();
   assertRequireDirectRejectsMissingServiceBinaryExecutablePreflight();
-  assertRequireDirectRejectsMissingPortsFreePreflight();
+  assertRequireDirectAllowsPostEnablePortsOwnedByPingora();
+  assertDryRunCutoverRejectsMissingPortsFreePreflight();
   assertRequireDirectRejectsMissingSpacetimeDatabase();
   assertRequireDirectRejectsFilesystemRootPreflightEnvFile();
   assertRequireDirectRejectsMissingHealthPatrolEnvFile();
@@ -164,6 +186,7 @@ function main() {
   assertDryRunCutoverRejectsFilesystemRootEvidenceOutputRoot();
   assertUsageCutoverExampleIncludesExplicitEvidenceOutputRoot();
   assertUsageExamplesIncludeDirectPingoraAccessLog();
+  assertDryRunCutoverRejectsMissingRollbackSmokeBody();
   assertDryRunCutoverRejectsMissingRollbackHealthPatrolPublicBaseUrl();
   assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicBaseUrl();
   assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicHost();
@@ -239,6 +262,22 @@ function assertDefaultPlanIncludesPingoraHealthPatrolEnvSwitchSmoke() {
   );
 }
 
+function assertDefaultPlanIncludesPingoraGatewayEnvShadowSwitchSmoke() {
+  const plan = readPlan(['--dry-run-plan']);
+  const step = findStep(plan, 'Pingora gateway env shadow 切换烟测');
+  if (!step) {
+    failures.push(
+      '默认 release readiness 计划必须包含 Pingora gateway env shadow 切换烟测。',
+    );
+    return;
+  }
+  assertIncludes(
+    step.args,
+    'check:pingora-gateway-env-shadow-switch',
+    'Pingora gateway env shadow 切换烟测必须调用 check:pingora-gateway-env-shadow-switch。',
+  );
+}
+
 function assertDefaultPlanIncludesPingoraCutoverStatusSnapshotSmoke() {
   const plan = readPlan(['--dry-run-plan']);
   const step = findStep(plan, 'Pingora cutover 状态快照烟测');
@@ -416,16 +455,10 @@ function assertDefaultPlanIncludesPingoraProductionReleaseBuildSmoke() {
 }
 
 function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
+  const plan = readPlan(cutoverPlanArgs(
     '--cutover-release-root',
     '/opt/genarrative/current',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
-  ]);
+  ));
   const preflight = findStep(
     plan,
     '切换前 current release 直连 env / 证书 / 端口预检',
@@ -758,6 +791,16 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
       'pingora-direct',
       '启用后状态快照证据包必须确认 pingora-direct 巡检口径。',
     );
+    assertIncludes(
+      postEnableSnapshot.args,
+      '--expected-pingora-env-mode',
+      '启用后状态快照证据包必须显式校验 active Pingora env 姿态。',
+    );
+    assertIncludes(
+      postEnableSnapshot.args,
+      'direct',
+      '启用后状态快照证据包必须要求 active Pingora env 是 direct 姿态。',
+    );
     assertIncludes(
       postEnableSnapshot.args,
       '--expected-public-host',
@@ -863,6 +906,11 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
       '--direct-preflight-systemd',
       'dry-run cutover 启用后复核必须检查 systemd drop-in 生效。',
     );
+    if (postReadiness.args.includes('--direct-preflight-check-ports-free')) {
+      failures.push(
+        'dry-run cutover 启用后 release readiness 复核不能继续要求 80/443 空闲；此时端口应由 Pingora 直连入口占用。',
+      );
+    }
   }
 
   const healthPatrolEnvCheck = findStep(
@@ -908,11 +956,35 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
     plan,
     '切换后 health patrol 切到 Pingora direct',
   );
+  const healthPatrolDirectVerify = findStep(
+    plan,
+    '切换后 health patrol direct 命令证据 manifest 只读验真',
+  );
   if (!healthPatrolDirect) {
     failures.push(
       'dry-run cutover 必须包含切换后 health patrol direct 模式脚本。',
     );
   } else {
+    assertIncludes(
+      healthPatrolDirect.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs',
+      'dry-run cutover 切换后 health patrol env 切换必须通过命令证据脚本归档。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '--command-name',
+      'dry-run cutover 切换后 health patrol env 切换必须显式记录命令证据名称。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      'pingora-health-patrol-direct-env-switch',
+      'dry-run cutover 切换后 health patrol env 切换必须记录固定命令证据名称。',
+    );
+    assertIncludes(
+      healthPatrolDirect.args,
+      '--expected-executable',
+      'dry-run cutover 切换后 health patrol env 切换必须绑定真实脚本身份。',
+    );
     assertIncludes(
       healthPatrolDirect.args,
       '/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
@@ -964,6 +1036,27 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
       'dry-run cutover 切换后 health patrol env 切换必须使用正式 Host。',
     );
   }
+  if (!healthPatrolDirectVerify) {
+    failures.push(
+      'dry-run cutover 必须包含切换后 health patrol direct 命令证据 manifest 只读验真。',
+    );
+  } else {
+    assertIncludes(
+      healthPatrolDirectVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '切换后 health patrol direct 命令证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      healthPatrolDirectVerify.args,
+      '<health-patrol-direct-env-switch-bundle-dir>',
+      '切换后 health patrol direct 命令证据验真必须提示替换刚生成的 bundleDir。',
+    );
+    assertIncludes(
+      healthPatrolDirectVerify.args,
+      '--require-summary-ok',
+      '切换后 health patrol direct 命令证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
   assertStepBefore(
     plan,
     'Pingora direct enable apply',
@@ -976,6 +1069,18 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
     '切换后 health patrol 切到 Pingora direct',
     'dry-run cutover 必须先验真 enable apply 命令证据，再切换 health patrol 到 pingora-direct。',
   );
+  assertStepBefore(
+    plan,
+    '切换后 health patrol 切到 Pingora direct',
+    '切换后 health patrol direct 命令证据 manifest 只读验真',
+    'dry-run cutover 必须先生成 health patrol direct env 命令证据，再验真该命令证据。',
+  );
+  assertStepBefore(
+    plan,
+    '切换后 health patrol direct 命令证据 manifest 只读验真',
+    '启用后 health patrol env 直连复核',
+    'dry-run cutover 必须先验真 health patrol direct env 命令证据，再执行直连 env 复核。',
+  );
 
   const rollbackDryRun = findStep(plan, 'Pingora direct rollback dry-run');
   if (!rollbackDryRun) {
@@ -1006,8 +1111,8 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
     );
     assertIncludes(
       rollbackDryRun.args,
-      '"ok":true',
-      'dry-run cutover rollback dry-run 必须默认校验 healthz ok body。',
+      '<!doctype html>',
+      'dry-run cutover rollback dry-run 必须使用显式传入的 Nginx smoke body 片段。',
     );
     assertIncludes(
       rollbackDryRun.args,
@@ -1078,7 +1183,7 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
     );
     assertIncludes(
       rollbackApply.args,
-      'http://127.0.0.1/healthz',
+      'https://example.com/',
       'dry-run cutover rollback apply 必须包含 Nginx smoke URL。',
     );
     assertIncludes(
@@ -1098,8 +1203,8 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
     );
     assertIncludes(
       rollbackApply.args,
-      '"ok":true',
-      'dry-run cutover rollback apply 必须默认校验 healthz ok body。',
+      '<!doctype html>',
+      'dry-run cutover rollback apply 必须使用显式传入的 Nginx smoke body 片段。',
     );
     assertIncludes(
       rollbackApply.args,
@@ -1143,11 +1248,112 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
   }
 
   const healthPatrolNginx = findStep(plan, '回退前 health patrol 预置回 Nginx');
+  const pingoraEnvShadow = findStep(plan, '回退前 Pingora env 预置回 shadow');
+  const pingoraEnvShadowVerify = findStep(
+    plan,
+    '回退前 Pingora env shadow 命令证据 manifest 只读验真',
+  );
+  const healthPatrolNginxVerify = findStep(
+    plan,
+    '回退前 health patrol nginx 命令证据 manifest 只读验真',
+  );
+  if (!pingoraEnvShadow) {
+    failures.push(
+      'dry-run cutover 必须包含回退前 Pingora env shadow 配置预置确认。',
+    );
+  } else {
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs',
+      'dry-run cutover 回退前 Pingora env shadow 预置必须通过命令证据脚本归档。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '--command-name',
+      'dry-run cutover 回退前 Pingora env shadow 预置必须显式记录命令证据名称。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      'pingora-gateway-shadow-env-switch',
+      'dry-run cutover 回退前 Pingora env shadow 预置必须记录固定命令证据名称。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '--expected-executable',
+      'dry-run cutover 回退前 Pingora env shadow 预置必须绑定真实脚本身份。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+      'dry-run cutover 回退前必须使用 current release 随包 Pingora gateway env shadow 切换脚本。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '--apply',
+      'dry-run cutover 回退前 Pingora gateway env shadow 切换必须显式带 --apply。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '--env-file',
+      'dry-run cutover 回退前 Pingora gateway env shadow 切换必须显式传 env 文件。',
+    );
+    assertIncludes(
+      pingoraEnvShadow.args,
+      '/tmp/pingora-gateway.env',
+      'dry-run cutover 回退前 Pingora gateway env shadow 切换必须使用显式 env 文件。',
+    );
+    if (!pingoraEnvShadow.when.includes('80/443 direct')) {
+      failures.push(
+        'dry-run cutover 回退前 Pingora env shadow 预置说明必须解释从 80/443 direct 配置恢复。',
+      );
+    }
+  }
+  if (!pingoraEnvShadowVerify) {
+    failures.push(
+      'dry-run cutover 必须包含回退前 Pingora env shadow 命令证据 manifest 只读验真。',
+    );
+  } else {
+    assertIncludes(
+      pingoraEnvShadowVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '回退前 Pingora env shadow 命令证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      pingoraEnvShadowVerify.args,
+      '<pingora-gateway-shadow-env-switch-bundle-dir>',
+      '回退前 Pingora env shadow 命令证据验真必须提示替换刚生成的 bundleDir。',
+    );
+    assertIncludes(
+      pingoraEnvShadowVerify.args,
+      '--require-summary-ok',
+      '回退前 Pingora env shadow 命令证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
   if (!healthPatrolNginx) {
     failures.push(
       'dry-run cutover 必须包含回退前 health patrol Nginx 模式预置脚本。',
     );
   } else {
+    assertIncludes(
+      healthPatrolNginx.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-command-evidence.mjs',
+      'dry-run cutover 回退前 health patrol env 切回 nginx 必须通过命令证据脚本归档。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      '--command-name',
+      'dry-run cutover 回退前 health patrol env 切回 nginx 必须显式记录命令证据名称。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      'pingora-health-patrol-nginx-env-switch',
+      'dry-run cutover 回退前 health patrol env 切回 nginx 必须记录固定命令证据名称。',
+    );
+    assertIncludes(
+      healthPatrolNginx.args,
+      '--expected-executable',
+      'dry-run cutover 回退前 health patrol env 切回 nginx 必须绑定真实脚本身份。',
+    );
     assertIncludes(
       healthPatrolNginx.args,
       '/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
@@ -1184,6 +1390,27 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
       'dry-run cutover 回退前 health patrol env 切换必须清理 public Host 覆盖。',
     );
   }
+  if (!healthPatrolNginxVerify) {
+    failures.push(
+      'dry-run cutover 必须包含回退前 health patrol nginx 命令证据 manifest 只读验真。',
+    );
+  } else {
+    assertIncludes(
+      healthPatrolNginxVerify.args,
+      '/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs',
+      '回退前 health patrol nginx 命令证据验真必须使用 current release 随包 verifier。',
+    );
+    assertIncludes(
+      healthPatrolNginxVerify.args,
+      '<health-patrol-nginx-env-switch-bundle-dir>',
+      '回退前 health patrol nginx 命令证据验真必须提示替换刚生成的 bundleDir。',
+    );
+    assertIncludes(
+      healthPatrolNginxVerify.args,
+      '--require-summary-ok',
+      '回退前 health patrol nginx 命令证据验真必须要求 manifest.summary.status=OK。',
+    );
+  }
 
   const healthPatrolIndex = plan.findIndex(
     (step) => step.name === '回退前 health patrol 预置回 Nginx',
@@ -1191,6 +1418,18 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
   const rollbackApplyIndex = plan.findIndex(
     (step) => step.name === 'Pingora direct rollback apply',
   );
+  const pingoraEnvShadowIndex = plan.findIndex(
+    (step) => step.name === '回退前 Pingora env 预置回 shadow',
+  );
+  if (
+    pingoraEnvShadowIndex >= 0 &&
+    rollbackApplyIndex >= 0 &&
+    pingoraEnvShadowIndex > rollbackApplyIndex
+  ) {
+    failures.push(
+      'dry-run cutover 必须先预置 Pingora shadow env，再执行 rollback apply。',
+    );
+  }
   if (
     healthPatrolIndex >= 0 &&
     rollbackApplyIndex >= 0 &&
@@ -1200,6 +1439,30 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
       'dry-run cutover 必须先预置 health patrol env，再执行 rollback apply。',
     );
   }
+  assertStepBefore(
+    plan,
+    '回退前 Pingora env 预置回 shadow',
+    '回退前 Pingora env shadow 命令证据 manifest 只读验真',
+    'dry-run cutover 必须先生成 Pingora shadow env 命令证据，再验真该命令证据。',
+  );
+  assertStepBefore(
+    plan,
+    '回退前 Pingora env shadow 命令证据 manifest 只读验真',
+    '回退前 health patrol 预置回 Nginx',
+    'dry-run cutover 必须先验真 Pingora shadow env 命令证据，再预置 health patrol nginx env。',
+  );
+  assertStepBefore(
+    plan,
+    '回退前 health patrol 预置回 Nginx',
+    '回退前 health patrol nginx 命令证据 manifest 只读验真',
+    'dry-run cutover 必须先生成 health patrol nginx env 命令证据，再验真该命令证据。',
+  );
+  assertStepBefore(
+    plan,
+    '回退前 health patrol nginx 命令证据 manifest 只读验真',
+    'Pingora direct rollback apply',
+    'dry-run cutover 必须先验真 health patrol nginx env 命令证据，再执行 rollback apply。',
+  );
   assertStepBefore(
     plan,
     'Pingora direct rollback apply',
@@ -1285,6 +1548,16 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
       'nginx',
       '回退后状态快照证据包必须确认 nginx 巡检口径。',
     );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      '--expected-pingora-env-mode',
+      '回退后状态快照证据包必须显式校验 active Pingora env 姿态。',
+    );
+    assertIncludes(
+      postRollbackSnapshot.args,
+      'shadow',
+      '回退后状态快照证据包必须要求 active Pingora env 已恢复 shadow 姿态。',
+    );
     assertIncludes(
       postRollbackSnapshot.args,
       '--require-empty-public-host',
@@ -1375,6 +1648,16 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
       'post-enable',
       '三阶段总审计必须把 direct live 静态响应头摘要要求绑定到 post-enable 阶段。',
     );
+    assertIncludes(
+      evidenceRootAudit.args,
+      '--require-phase-pingora-env-shadow',
+      '三阶段总审计必须要求 post-rollback 阶段带 Pingora env shadow 摘要。',
+    );
+    assertIncludes(
+      evidenceRootAudit.args,
+      'post-rollback',
+      '三阶段总审计必须把 Pingora env shadow 摘要要求绑定到 post-rollback 阶段。',
+    );
     assertIncludes(
       evidenceRootAudit.args,
       '--require-command',
@@ -1382,6 +1665,9 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
     );
     for (const command of [
       'enable-apply:pingora-direct-enable-apply',
+      'post-enable:pingora-health-patrol-direct-env-switch',
+      'rollback-prep:pingora-gateway-shadow-env-switch',
+      'rollback-prep:pingora-health-patrol-nginx-env-switch',
       'rollback-apply:pingora-direct-rollback-apply',
     ]) {
       assertIncludes(
@@ -1397,6 +1683,9 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
     );
     for (const commandExecutable of [
       'enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh',
+      'post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+      'rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+      'rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
       'rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh',
     ]) {
       assertIncludes(
@@ -1412,6 +1701,11 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
     );
     for (const commandArg of [
       'enable-apply:pingora-direct-enable-apply:--apply',
+      'post-enable:pingora-health-patrol-direct-env-switch:--apply',
+      'post-enable:pingora-health-patrol-direct-env-switch:pingora-direct',
+      'rollback-prep:pingora-gateway-shadow-env-switch:--apply',
+      'rollback-prep:pingora-health-patrol-nginx-env-switch:--apply',
+      'rollback-prep:pingora-health-patrol-nginx-env-switch:nginx',
       'rollback-apply:pingora-direct-rollback-apply:--apply',
     ]) {
       assertIncludes(
@@ -1440,16 +1734,10 @@ function assertDryRunCutoverPlanIncludesDirectEnableAndRollbackRunbook() {
 }
 
 function assertDryRunCutoverPlanCanOverrideEvidenceTimelineMaxSpan() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+  const plan = readPlan(cutoverPlanArgs(
     '--cutover-evidence-timeline-max-span-ms',
     '172800000',
-  ]);
+  ));
   const evidenceRootAudit = findStep(plan, '切换证据根目录三阶段总审计');
   if (!evidenceRootAudit) {
     failures.push('dry-run cutover 必须包含切换证据根目录三阶段总审计。');
@@ -1468,14 +1756,7 @@ function assertDryRunCutoverPlanCanOverrideEvidenceTimelineMaxSpan() {
 }
 
 function assertDryRunCutoverPlanAvoidsManualEvidenceEscapeHatches() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
-  ]);
+  const plan = readPlan(cutoverPlanArgs());
   const forbiddenArgs = [
     '--warn-only',
     '--allow-extra-files',
@@ -1533,16 +1814,10 @@ function assertTechnicalDocCutoverAuditExamplesRequireCommandExecutables() {
 }
 
 function assertDryRunCutoverPlanIncludesHostConsistencyConfirmation() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
+  const plan = readPlan(cutoverPlanArgs(
     '--cutover-release-root',
     '/opt/genarrative/current',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
-  ]);
+  ));
   const step = findStep(plan, '切换 Host 一致性确认');
   if (!step) {
     failures.push('dry-run cutover 必须包含 Host 一致性确认步骤。');
@@ -1575,7 +1850,7 @@ function assertDryRunCutoverPlanIncludesHostConsistencyConfirmation() {
   );
   assertIncludes(
     step.args,
-    'rollback-nginx-smoke-expect-body="ok":true',
+    'rollback-nginx-smoke-expect-body=<!doctype html>',
     'dry-run cutover Host 一致性确认必须展示 rollback smoke body 证据片段。',
   );
   assertIncludes(
@@ -1591,16 +1866,10 @@ function assertDryRunCutoverPlanIncludesHostConsistencyConfirmation() {
 }
 
 function assertDryRunCutoverPlanCarriesCutoverRunId() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
+  const plan = readPlan(cutoverPlanArgs(
     '--cutover-run-id',
     'cutover-20260617T010000Z',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
-  ]);
+  ));
   const hostConsistency = findStep(plan, '切换 Host 一致性确认');
   if (!hostConsistency) {
     failures.push('dry-run cutover 必须包含 Host 一致性确认步骤。');
@@ -1654,14 +1923,7 @@ function assertDryRunCutoverPlanCarriesCutoverRunId() {
 }
 
 function assertDryRunCutoverPlanGeneratesDefaultCutoverRunId() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
-  ]);
+  const plan = readPlan(cutoverPlanArgs());
   const hostConsistency = findStep(plan, '切换 Host 一致性确认');
   if (!hostConsistency) {
     failures.push('dry-run cutover 必须包含 Host 一致性确认步骤。');
@@ -1691,22 +1953,16 @@ function assertDryRunCutoverPlanGeneratesDefaultCutoverRunId() {
   );
 }
 
-function assertDryRunCutoverDefaultRollbackBodyIgnoresProcessEnv() {
+function assertDryRunCutoverExplicitRollbackBodyIgnoresProcessEnv() {
   const previous =
     process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY;
   process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY =
     'polluted-body';
   try {
-    const plan = readPlan([
-      ...requireDirectBaseArgs,
-      '--dry-run-cutover',
+    const plan = readPlan(cutoverPlanArgs(
       '--cutover-release-root',
       '/opt/genarrative/current',
-      '--rollback-nginx-smoke-url',
-      'http://127.0.0.1/healthz',
-      '--rollback-health-patrol-public-base-url',
-      'http://127.0.0.1',
-    ]);
+    ));
     const rollbackApply = findStep(plan, 'Pingora direct rollback apply');
     if (!rollbackApply) {
       failures.push('dry-run cutover 必须包含 rollback apply。');
@@ -1714,8 +1970,8 @@ function assertDryRunCutoverDefaultRollbackBodyIgnoresProcessEnv() {
     }
     assertIncludes(
       rollbackApply.args,
-      '"ok":true',
-      'dry-run cutover 默认 rollback body 断言不能被本机 env 污染。',
+      '<!doctype html>',
+      'dry-run cutover 必须使用显式 rollback body 断言，且不能被本机 env 污染。',
     );
     if (rollbackApply.args.includes('polluted-body')) {
       failures.push(
@@ -1733,18 +1989,12 @@ function assertDryRunCutoverDefaultRollbackBodyIgnoresProcessEnv() {
 }
 
 function assertDryRunCutoverPostEnableReadinessRedactsDirectProbeToken() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
+  const plan = readPlan(cutoverPlanArgs(
     '--direct-probe-token',
     'direct-secret-token',
-    '--dry-run-cutover',
     '--cutover-release-root',
     '/opt/genarrative/current',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
-  ]);
+  ));
   const step = findStep(plan, '启用后 release readiness 直连复核');
   if (!step) {
     failures.push('带 direct probe token 的 cutover runbook 必须包含启用后 readiness 复核。');
@@ -1766,20 +2016,14 @@ function assertDryRunCutoverPostEnableReadinessRedactsDirectProbeToken() {
 }
 
 function assertDryRunCutoverAllowsSameHostnameWithDifferentPorts() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
+  const plan = readPlan(cutoverPlanArgs(
     '--direct-redirect-host',
     'example.com:443',
-    '--dry-run-cutover',
     '--cutover-release-root',
     '/opt/genarrative/current',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
     '--rollback-nginx-smoke-host',
     'example.com:80',
-  ]);
+  ));
   const step = findStep(plan, '切换 Host 一致性确认');
   if (!step) {
     failures.push('dry-run cutover 同 hostname 不同端口时仍必须能生成计划。');
@@ -1803,18 +2047,12 @@ function assertDryRunCutoverAllowsSameHostnameWithDifferentPorts() {
 }
 
 function assertDryRunCutoverCanRestoreRollbackHealthPatrolPublicHost() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
+  const plan = readPlan(cutoverPlanArgs(
     '--cutover-release-root',
     '/opt/genarrative/current',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
     '--rollback-health-patrol-public-host',
     'nginx.example.com',
-  ]);
+  ));
   const healthPatrolNginx = findStep(plan, '回退前 health patrol 预置回 Nginx');
   const hostConsistency = findStep(plan, '切换 Host 一致性确认');
   if (!hostConsistency) {
@@ -1903,20 +2141,14 @@ function assertDryRunCutoverCanRestoreRollbackHealthPatrolPublicHost() {
 }
 
 function assertDryRunCutoverPlanCanIncludeRollbackShadowProbe() {
-  const plan = readPlan([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
+  const plan = readPlan(cutoverPlanArgs(
     '--cutover-release-root',
     '/opt/genarrative/current',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
     '--rollback-pingora-shadow-probe-url',
     'http://127.0.0.1:18081/__genarrative_pingora/healthz',
     '--rollback-pingora-shadow-probe-token',
     'probe-secret-token',
-  ]);
+  ));
   const rollbackDryRun = findStep(plan, 'Pingora direct rollback dry-run');
   const rollbackApply = findStep(plan, 'Pingora direct rollback apply');
   for (const step of [rollbackDryRun, rollbackApply]) {
@@ -2285,6 +2517,65 @@ function assertReleaseRuntimeOnlyPlanIncludesDirectRehearsalStatus() {
   }
 }
 
+function assertReleaseRuntimeOnlyAllowsRealpathOnlyCanary() {
+  const plan = readPlan([
+    ...requireRealpathLiveBaseArgs,
+    '--release-runtime-only',
+    '--dry-run-plan',
+  ]);
+  const prefixLive = findStep(plan, '目标 Nginx live canary smoke');
+  if (prefixLive) {
+    failures.push(
+      'release runtime-only 只要求 realpath canary 时不能强制执行前缀 canary smoke。',
+    );
+  }
+  const prefixParity = findStep(plan, '目标 Nginx live canary access log 对账');
+  if (prefixParity) {
+    failures.push(
+      'release runtime-only 只要求 realpath canary 时不能强制执行前缀 canary access log 对账。',
+    );
+  }
+
+  const realpathLive = findStep(plan, '目标 Nginx realpath canary smoke');
+  if (!realpathLive) {
+    failures.push(
+      'release runtime-only 只要求 realpath canary 时必须包含 realpath smoke。',
+    );
+  } else {
+    assertAbsoluteScriptArg(
+      realpathLive.args,
+      'scripts/check-pingora-canary-live.mjs',
+      'release runtime-only realpath-only smoke 必须使用 current release 随包脚本。',
+    );
+    assertIncludes(
+      realpathLive.args,
+      '--realpath',
+      'release runtime-only realpath-only smoke 必须传 --realpath。',
+    );
+  }
+
+  const realpathParity = findStep(
+    plan,
+    '目标 Nginx realpath canary access log 对账',
+  );
+  if (!realpathParity) {
+    failures.push(
+      'release runtime-only 只要求 realpath canary 时必须包含 realpath access log 对账。',
+    );
+  } else {
+    assertAbsoluteScriptArg(
+      realpathParity.args,
+      'scripts/check-pingora-canary-access-log-parity.mjs',
+      'release runtime-only realpath-only 对账必须使用 current release 随包脚本。',
+    );
+    assertIncludes(
+      realpathParity.args,
+      '--realpath',
+      'release runtime-only realpath-only 对账必须传 --realpath。',
+    );
+  }
+}
+
 function assertReleaseRuntimeOnlyKeepsInvokedCurrentSymlinkPath() {
   const tmpRoot = mkdtempSync(
     path.join(tmpdir(), 'genarrative-release-readiness-current-'),
@@ -2455,7 +2746,7 @@ function assertRequireDirectForcesPingoraAccessLog() {
   );
 }
 
-function assertRequireDirectForcesPreflightSystemdCertReadableAndPortsFree() {
+function assertRequireDirectForcesPreflightSystemdCertReadable() {
   const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
   const step = findStep(plan, '目标 Pingora direct entry preflight');
   if (!step) {
@@ -2487,10 +2778,24 @@ function assertRequireDirectForcesPreflightSystemdCertReadableAndPortsFree() {
     '--check-service-binary-executable',
     '--require-direct 必须检查 Pingora service ExecStart 二进制可执行。',
   );
+  assertNotIncludes(
+    step.args,
+    '--check-ports-free',
+    '--require-direct 启用后复核不能继续要求 TLS/HTTP redirect 端口空闲；此时端口应由 Pingora 占用。',
+  );
+}
+
+function assertDryRunCutoverForcesPortsFreePreflight() {
+  const plan = readPlan(cutoverPlanArgs());
+  const step = findStep(plan, '切换前 current release 直连 env / 证书 / 端口预检');
+  if (!step) {
+    failures.push('dry-run cutover 计划必须包含切换前 direct entry preflight。');
+    return;
+  }
   assertIncludes(
     step.args,
     '--check-ports-free',
-    '--require-direct 必须检查 TLS/HTTP redirect 端口已释放。',
+    'dry-run cutover 启用前 preflight 必须检查 TLS/HTTP redirect 端口已释放。',
   );
 }
 
@@ -3086,34 +3391,35 @@ function assertRequireDirectRejectsMissingServiceBinaryExecutablePreflight() {
   );
 }
 
-function assertRequireDirectRejectsMissingPortsFreePreflight() {
+function assertRequireDirectAllowsPostEnablePortsOwnedByPingora() {
+  const plan = readPlan([...requireDirectBaseArgs, '--dry-run-plan']);
+  const step = findStep(plan, '目标 Pingora direct entry preflight');
+  if (!step) {
+    failures.push('--require-direct 计划必须包含 direct entry preflight。');
+    return;
+  }
+  assertNotIncludes(
+    step.args,
+    '--check-ports-free',
+    '--require-direct post-enable 复核不能要求 80/443 空闲。',
+  );
+}
+
+function assertDryRunCutoverRejectsMissingPortsFreePreflight() {
   const result = runReadinessExpectFailure([
-    '--require-direct',
-    '--direct-https-base-url',
-    'https://127.0.0.1',
-    '--direct-http-base-url',
+    ...requireDirectBaseArgs,
+    '--dry-run-cutover',
+    '--rollback-nginx-smoke-url',
+    'https://example.com/',
+    '--rollback-nginx-smoke-expect-body',
+    '<!doctype html>',
+    '--rollback-health-patrol-public-base-url',
     'http://127.0.0.1',
-    '--direct-host',
-    'example.com',
-    '--direct-redirect-host',
-    'example.com',
-    '--direct-pingora-access-log',
-    '/var/log/genarrative/pingora-gateway.access.log',
-    '--direct-preflight-env-file',
-    '/tmp/pingora-gateway.env',
-    '--direct-preflight-systemd',
-    '--direct-preflight-check-cert-readable',
-    '--direct-preflight-check-service-env-file',
-    '--direct-preflight-check-service-user-cert-readable',
-    '--direct-preflight-check-service-binary-executable',
-    '--direct-spacetime-database',
-    'genarrative-prod',
-    '--dry-run-plan',
   ]);
   assertFailureIncludes(
     result,
-    '启用 --require-direct 时必须提供 --direct-preflight-check-ports-free 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE=true',
-    '--require-direct 缺少端口释放 preflight 时必须失败。',
+    '启用 --dry-run-cutover 时必须提供 --direct-preflight-check-ports-free',
+    'dry-run cutover 缺少端口释放 preflight 时必须失败。',
   );
 }
 
@@ -3340,12 +3646,7 @@ function assertDryRunCutoverRejectsMissingRequireDirect() {
 
 function assertDryRunCutoverRejectsRelativeEvidenceOutputRoot() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ...cutoverPlanArgs(),
     '--cutover-evidence-output-root',
     'relative-evidence',
   ]);
@@ -3358,12 +3659,7 @@ function assertDryRunCutoverRejectsRelativeEvidenceOutputRoot() {
 
 function assertDryRunCutoverRejectsFilesystemRootReleaseRoot() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ...cutoverPlanArgs(),
     '--cutover-release-root',
     '/',
   ]);
@@ -3376,12 +3672,7 @@ function assertDryRunCutoverRejectsFilesystemRootReleaseRoot() {
 
 function assertDryRunCutoverRejectsFilesystemRootEvidenceOutputRoot() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ...cutoverPlanArgs(),
     '--cutover-evidence-output-root',
     '/',
   ]);
@@ -3436,8 +3727,11 @@ function assertDryRunCutoverRejectsMissingRollbackHealthPatrolPublicBaseUrl() {
   const result = runReadinessExpectFailure([
     ...requireDirectBaseArgs,
     '--dry-run-cutover',
+    '--direct-preflight-check-ports-free',
     '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
+    'https://example.com/',
+    '--rollback-nginx-smoke-expect-body',
+    '<!doctype html>',
   ]);
   assertFailureIncludes(
     result,
@@ -3446,12 +3740,32 @@ function assertDryRunCutoverRejectsMissingRollbackHealthPatrolPublicBaseUrl() {
   );
 }
 
+function assertDryRunCutoverRejectsMissingRollbackSmokeBody() {
+  const result = runReadinessExpectFailure([
+    ...requireDirectBaseArgs,
+    '--dry-run-cutover',
+    '--direct-preflight-check-ports-free',
+    '--rollback-nginx-smoke-url',
+    'https://example.com/',
+    '--rollback-health-patrol-public-base-url',
+    'http://127.0.0.1',
+  ]);
+  assertFailureIncludes(
+    result,
+    '启用 --dry-run-cutover 时必须提供 --rollback-nginx-smoke-expect-body',
+    'dry-run cutover 缺少回退 Nginx smoke body 证据片段时必须失败。',
+  );
+}
+
 function assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicBaseUrl() {
   const result = runReadinessExpectFailure([
     ...requireDirectBaseArgs,
     '--dry-run-cutover',
+    '--direct-preflight-check-ports-free',
     '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
+    'https://example.com/',
+    '--rollback-nginx-smoke-expect-body',
+    '<!doctype html>',
     '--rollback-health-patrol-public-base-url',
     'ftp://127.0.0.1',
   ]);
@@ -3464,12 +3778,7 @@ function assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicBaseUrl() {
 
 function assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicHost() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ...cutoverPlanArgs(),
     '--rollback-health-patrol-public-host',
     'https://example.com',
   ]);
@@ -3482,14 +3791,10 @@ function assertDryRunCutoverRejectsInvalidRollbackHealthPatrolPublicHost() {
 
 function assertDryRunCutoverRejectsRedirectHostMismatch() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
+    ...cutoverPlanArgs(
     '--direct-redirect-host',
     'redirect.example.com',
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ),
   ]);
   assertFailureIncludes(
     result,
@@ -3500,12 +3805,7 @@ function assertDryRunCutoverRejectsRedirectHostMismatch() {
 
 function assertDryRunCutoverRejectsRollbackHostMismatch() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ...cutoverPlanArgs(),
     '--rollback-nginx-smoke-host',
     'nginx.example.com',
   ]);
@@ -3518,12 +3818,7 @@ function assertDryRunCutoverRejectsRollbackHostMismatch() {
 
 function assertDryRunCutoverRejectsIncompleteRollbackShadowProbe() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ...cutoverPlanArgs(),
     '--rollback-pingora-shadow-probe-url',
     'http://127.0.0.1:18081/__genarrative_pingora/healthz',
   ]);
@@ -3536,12 +3831,7 @@ function assertDryRunCutoverRejectsIncompleteRollbackShadowProbe() {
 
 function assertDryRunCutoverRejectsInvalidRollbackShadowProbeUrl() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ...cutoverPlanArgs(),
     '--rollback-pingora-shadow-probe-url',
     'ftp://127.0.0.1/probe',
     '--rollback-pingora-shadow-probe-token',
@@ -3556,12 +3846,7 @@ function assertDryRunCutoverRejectsInvalidRollbackShadowProbeUrl() {
 
 function assertDryRunCutoverRejectsInvalidEvidenceTimelineMaxSpan() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ...cutoverPlanArgs(),
     '--cutover-evidence-timeline-max-span-ms',
     '0',
   ]);
@@ -3574,14 +3859,10 @@ function assertDryRunCutoverRejectsInvalidEvidenceTimelineMaxSpan() {
 
 function assertDryRunCutoverRejectsInvalidCutoverRunId() {
   const result = runReadinessExpectFailure([
-    ...requireDirectBaseArgs,
-    '--dry-run-cutover',
+    ...cutoverPlanArgs(
     '--cutover-run-id',
     'cutover 1',
-    '--rollback-nginx-smoke-url',
-    'http://127.0.0.1/healthz',
-    '--rollback-health-patrol-public-base-url',
-    'http://127.0.0.1',
+    ),
   ]);
   assertFailureIncludes(
     result,
@@ -3983,6 +4264,11 @@ function readinessPlanEnv() {
     ...process.env,
     GENARRATIVE_PINGORA_CANARY_HOST: '',
     GENARRATIVE_PINGORA_CANARY_BASE_URL: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_HOST: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_BASE_URL: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_NGINX_ACCESS_LOG: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_PINGORA_ACCESS_LOG: '',
+    GENARRATIVE_PINGORA_REALPATH_CANARY_ACCESS_LOG_SINCE_LINES: '',
     GENARRATIVE_PINGORA_DIRECT_HTTPS_BASE_URL: '',
     GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL: '',
     GENARRATIVE_PINGORA_DIRECT_HOST: '',
diff --git a/scripts/check-pingora-release-readiness.mjs b/scripts/check-pingora-release-readiness.mjs
index 28c7abc95..dd6dd1ff1 100644
--- a/scripts/check-pingora-release-readiness.mjs
+++ b/scripts/check-pingora-release-readiness.mjs
@@ -146,13 +146,11 @@ function parseArgs(argv) {
     ),
     cutoverRunId: process.env.GENARRATIVE_PINGORA_CUTOVER_RUN_ID || '',
     rollbackNginxSmokeUrl:
-      process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_URL ||
-      'http://127.0.0.1/healthz',
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_URL || '',
     rollbackNginxSmokeHost:
       process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_HOST || '',
     rollbackNginxSmokeExpectBody:
-      process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY ||
-      '"ok":true',
+      process.env.GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY || '',
     rollbackHealthPatrolPublicBaseUrl:
       process.env.GENARRATIVE_PINGORA_ROLLBACK_HEALTH_PATROL_PUBLIC_BASE_URL ||
       '',
@@ -502,9 +500,9 @@ function parseArgs(argv) {
       '启用 --require-direct 时必须提供 --direct-preflight-check-service-binary-executable 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE=true',
     );
   }
-  if (result.requireDirect && !result.directPreflightCheckPortsFree) {
+  if (result.dryRunCutover && !result.directPreflightCheckPortsFree) {
     throw new Error(
-      '启用 --require-direct 时必须提供 --direct-preflight-check-ports-free 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE=true',
+      '启用 --dry-run-cutover 时必须提供 --direct-preflight-check-ports-free 或 GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_PORTS_FREE=true，用于切换前证明 Nginx 和其它进程已释放 80/443。',
     );
   }
   if (result.requireDirect && result.directSkipWss) {
@@ -567,6 +565,11 @@ function parseArgs(argv) {
       '启用 --dry-run-cutover 时必须提供 --rollback-nginx-smoke-url 或 GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_URL。',
     );
   }
+  if (result.dryRunCutover && !result.rollbackNginxSmokeExpectBody) {
+    throw new Error(
+      '启用 --dry-run-cutover 时必须提供 --rollback-nginx-smoke-expect-body 或 GENARRATIVE_PINGORA_ROLLBACK_NGINX_SMOKE_EXPECT_BODY，且该片段必须来自切换前真实 Nginx 入口。',
+    );
+  }
   if (result.dryRunCutover && !result.rollbackNginxSmokeHost) {
     result.rollbackNginxSmokeHost = result.directHost || result.liveHost;
   }
@@ -711,7 +714,7 @@ Options:
   --direct-preflight-check-service-binary-executable
                               direct entry 预检要求 service ExecStart 指向的 pingora-gateway 已存在且可执行；--require-direct 时必须显式提供。
   --direct-preflight-check-ports-free
-                              direct entry 预检要求 TLS/HTTP redirect 端口当前可绑定；--require-direct 时必须显式提供。
+                              direct entry 预检要求 TLS/HTTP redirect 端口当前可绑定；--dry-run-cutover / direct enable apply 前必须显式提供，启用后 --require-direct 复核不要求端口空闲。
   --direct-spacetime-database <name>
                               direct live WSS subscribe 使用的数据库名；也可用 GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE。--require-direct 时必须显式提供。
   --direct-health-patrol-env-file <path>
@@ -728,11 +731,11 @@ Options:
                               生成切换 runbook 时传给证据根目录总审计的标准五段时间线最大跨度，默认 ${DEFAULT_CUTOVER_EVIDENCE_TIMELINE_MAX_SPAN_MS}ms。
   --cutover-run-id <id>       生成切换 runbook 时写入所有证据 manifest 的本次切换批次 ID；不传则自动生成 ${DEFAULT_CUTOVER_RUN_ID_PREFIX}<UTC时间>。
   --rollback-nginx-smoke-url <url>
-                              生成切换 runbook 时传给回退脚本的 Nginx smoke URL，默认 http://127.0.0.1/healthz。
+                              生成切换 runbook 时传给回退脚本的 Nginx smoke URL；必须显式填写切换前真实 Nginx 入口。
   --rollback-nginx-smoke-host <host>
                               生成切换 runbook 时传给回退脚本的 Host header；默认复用 --direct-host，显式传入时必须和 --direct-host 使用同一 hostname。
   --rollback-nginx-smoke-expect-body <text>
-                              生成切换 runbook 时传给回退脚本的 Nginx smoke 响应体预期片段，默认 "ok":true。
+                              生成切换 runbook 时传给回退脚本的 Nginx smoke 响应体预期片段；必须显式来自切换前真实响应，例如首页 <!doctype html>。
   --rollback-health-patrol-public-base-url <url>
                               生成切换 runbook 时回退后恢复的 Nginx public base URL；应填切换前 health-patrol env 的原值。
   --rollback-health-patrol-public-host <host>
@@ -751,10 +754,10 @@ Options:
   node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名>
 
 Pingora 直连入口切换窗口追加：
-  node scripts/check-pingora-release-readiness.mjs --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free
+  node scripts/check-pingora-release-readiness.mjs --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable
 
 只生成直连切换 runbook：
-  node scripts/check-pingora-release-readiness.mjs --dry-run-cutover --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free --cutover-evidence-output-root /var/log/genarrative/pingora-cutover-evidence --rollback-nginx-smoke-url http://127.0.0.1/healthz --rollback-health-patrol-public-base-url http://127.0.0.1
+  node scripts/check-pingora-release-readiness.mjs --dry-run-cutover --require-direct --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名> --direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log --direct-health-patrol-env-file /etc/genarrative/health-patrol.env --direct-preflight-env-file /etc/genarrative/pingora-gateway.env --direct-preflight-systemd --direct-preflight-check-cert-readable --direct-preflight-check-service-env-file --direct-preflight-check-service-user-cert-readable --direct-preflight-check-service-binary-executable --direct-preflight-check-ports-free --cutover-evidence-output-root /var/log/genarrative/pingora-cutover-evidence --rollback-nginx-smoke-url https://<域名>/ --rollback-nginx-smoke-expect-body '<!doctype html>' --rollback-health-patrol-public-base-url http://127.0.0.1
 `);
 }
 
@@ -928,6 +931,10 @@ function buildCutoverPlan(config) {
     releaseRoot,
     'scripts/deploy/pingora-direct-rollback.sh',
   );
+  const gatewayEnvShadowSwitchScript = path.join(
+    releaseRoot,
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+  );
   const healthPatrolEnvSwitchScript = path.join(
     releaseRoot,
     'scripts/deploy/pingora-health-patrol-env-switch.mjs',
@@ -1048,6 +1055,34 @@ function buildCutoverPlan(config) {
       config.rollbackPingoraShadowProbeToken,
     );
   }
+  const healthPatrolDirectSwitchArgs = [
+    '--apply',
+    '--env-file',
+    config.directHealthPatrolEnvFile,
+    '--gateway-mode',
+    'pingora-direct',
+    '--public-base-url',
+    config.directHttpsBaseUrl,
+    '--public-host',
+    config.directHost,
+  ];
+  const pingoraGatewayShadowSwitchArgs = [
+    '--apply',
+    '--env-file',
+    config.directPreflightEnvFile,
+  ];
+  const healthPatrolNginxSwitchArgs = [
+    '--apply',
+    '--env-file',
+    config.directHealthPatrolEnvFile,
+    '--gateway-mode',
+    'nginx',
+    '--public-base-url',
+    config.rollbackHealthPatrolPublicBaseUrl,
+    ...(config.rollbackHealthPatrolPublicHost
+      ? ['--public-host', config.rollbackHealthPatrolPublicHost]
+      : ['--clear-public-host']),
+  ];
 
   return [
     {
@@ -1196,18 +1231,39 @@ function buildCutoverPlan(config) {
       command: 'node',
       args: [
         '--',
+        commandEvidenceScript,
+        '--phase',
+        'post-enable',
+        '--command-name',
+        'pingora-health-patrol-direct-env-switch',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--expected-executable',
         healthPatrolEnvSwitchScript,
+        '--require-arg',
         '--apply',
-        '--env-file',
-        config.directHealthPatrolEnvFile,
-        '--gateway-mode',
+        '--require-arg',
         'pingora-direct',
-        '--public-base-url',
-        config.directHttpsBaseUrl,
-        '--public-host',
-        config.directHost,
+        '--',
+        healthPatrolEnvSwitchScript,
+        ...healthPatrolDirectSwitchArgs,
       ],
-      when: 'direct enable apply 成功后执行，避免巡检继续要求 nginx.service active。',
+      when: 'direct enable apply 成功后执行，并用命令证据归档 health patrol env 从 nginx 切到 pingora-direct 的真实 stdout / stderr / 退出码，避免巡检继续要求 nginx.service active。',
+    },
+    {
+      phase: 'post-enable',
+      name: '切换后 health patrol direct 命令证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<health-patrol-direct-env-switch-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: 'health patrol direct env switch 命令证据生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认 env 切换命令 stdout / stderr / command-record 与 manifest 元数据一致，且 manifest.summary.status 为 OK。',
     },
     {
       phase: 'post-enable',
@@ -1251,6 +1307,8 @@ function buildCutoverPlan(config) {
         config.directPreflightEnvFile,
         '--expected-gateway-mode',
         'pingora-direct',
+        '--expected-pingora-env-mode',
+        'direct',
         '--expected-public-base-url',
         config.directHttpsBaseUrl,
         '--expected-public-host',
@@ -1302,8 +1360,12 @@ function buildCutoverPlan(config) {
       args: [
         '--',
         releaseReadinessScript,
-        ...readinessArgs(config, { includeDirect: true }),
+        ...readinessArgs(config, {
+          includeDirect: true,
+          includeDirectPortsFree: false,
+        }),
       ],
+      when: 'Pingora 已接管 80/443 后执行；此阶段不再检查端口空闲，因为端口应由 Pingora 直连入口占用。',
     },
     {
       phase: 'rollback-dry-run',
@@ -1312,25 +1374,83 @@ function buildCutoverPlan(config) {
       args: rollbackBaseArgs,
       when: '启用失败、direct live smoke 失败或业务验证失败时先执行。',
     },
+    {
+      phase: 'rollback-prep',
+      name: '回退前 Pingora env 预置回 shadow',
+      command: 'node',
+      args: [
+        '--',
+        commandEvidenceScript,
+        '--phase',
+        'rollback-prep',
+        '--command-name',
+        'pingora-gateway-shadow-env-switch',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--expected-executable',
+        gatewayEnvShadowSwitchScript,
+        '--require-arg',
+        '--apply',
+        '--',
+        gatewayEnvShadowSwitchScript,
+        ...pingoraGatewayShadowSwitchArgs,
+      ],
+      when: 'rollback apply 前执行，并用命令证据归档 Pingora gateway env 从 80/443 direct 配置恢复为 shadow 高端口配置；否则回退脚本移除低端口 capability 后重启 Pingora 可能仍按 80/443 配置启动失败。',
+    },
+    {
+      phase: 'rollback-prep',
+      name: '回退前 Pingora env shadow 命令证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<pingora-gateway-shadow-env-switch-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: 'Pingora gateway shadow env switch 命令证据生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认 env 切换命令 stdout / stderr / command-record 与 manifest 元数据一致，且 manifest.summary.status 为 OK。',
+    },
     {
       phase: 'rollback-prep',
       name: '回退前 health patrol 预置回 Nginx',
       command: 'node',
       args: [
         '--',
+        commandEvidenceScript,
+        '--phase',
+        'rollback-prep',
+        '--command-name',
+        'pingora-health-patrol-nginx-env-switch',
+        '--cutover-run-id',
+        config.cutoverRunId,
+        '--output-root',
+        config.cutoverEvidenceOutputRoot,
+        '--expected-executable',
         healthPatrolEnvSwitchScript,
+        '--require-arg',
         '--apply',
-        '--env-file',
-        config.directHealthPatrolEnvFile,
-        '--gateway-mode',
+        '--require-arg',
         'nginx',
-        '--public-base-url',
-        config.rollbackHealthPatrolPublicBaseUrl,
-        ...(config.rollbackHealthPatrolPublicHost
-          ? ['--public-host', config.rollbackHealthPatrolPublicHost]
-          : ['--clear-public-host']),
+        '--',
+        healthPatrolEnvSwitchScript,
+        ...healthPatrolNginxSwitchArgs,
       ],
-      when: 'rollback apply 前执行，确保回退脚本内置 health patrol env 复核能校验切换前 public base URL / Host。',
+      when: 'rollback apply 前执行，并用命令证据归档 health patrol env 从 pingora-direct 预置回 nginx，确保回退脚本内置 health patrol env 复核能校验切换前 public base URL / Host。',
+    },
+    {
+      phase: 'rollback-prep',
+      name: '回退前 health patrol nginx 命令证据 manifest 只读验真',
+      command: 'node',
+      args: [
+        '--',
+        evidenceVerifyScript,
+        '--bundle-dir',
+        '<health-patrol-nginx-env-switch-bundle-dir>',
+        '--require-summary-ok',
+      ],
+      when: 'health patrol nginx env switch 命令证据生成后，将上一步 stdout 中的 bundleDir 替换占位符执行，确认 env 切换命令 stdout / stderr / command-record 与 manifest 元数据一致，且 manifest.summary.status 为 OK。',
     },
     {
       phase: 'rollback-apply',
@@ -1420,6 +1540,8 @@ function buildCutoverPlan(config) {
         config.directPreflightEnvFile,
         '--expected-gateway-mode',
         'nginx',
+        '--expected-pingora-env-mode',
+        'shadow',
         '--expected-public-base-url',
         config.rollbackHealthPatrolPublicBaseUrl,
         ...(config.rollbackHealthPatrolPublicHost
@@ -1465,29 +1587,53 @@ function buildCutoverPlan(config) {
         'post-enable',
         '--require-phase-direct-live-static-headers',
         'post-enable',
+        '--require-phase-pingora-env-shadow',
+        'post-rollback',
         '--require-command',
         'enable-apply:pingora-direct-enable-apply',
         '--require-command',
+        'post-enable:pingora-health-patrol-direct-env-switch',
+        '--require-command',
+        'rollback-prep:pingora-gateway-shadow-env-switch',
+        '--require-command',
+        'rollback-prep:pingora-health-patrol-nginx-env-switch',
+        '--require-command',
         'rollback-apply:pingora-direct-rollback-apply',
         '--require-command-executable',
         `enable-apply:pingora-direct-enable-apply:${enableScript}`,
         '--require-command-executable',
+        `post-enable:pingora-health-patrol-direct-env-switch:${healthPatrolEnvSwitchScript}`,
+        '--require-command-executable',
+        `rollback-prep:pingora-gateway-shadow-env-switch:${gatewayEnvShadowSwitchScript}`,
+        '--require-command-executable',
+        `rollback-prep:pingora-health-patrol-nginx-env-switch:${healthPatrolEnvSwitchScript}`,
+        '--require-command-executable',
         `rollback-apply:pingora-direct-rollback-apply:${rollbackScript}`,
         '--require-command-arg',
         'enable-apply:pingora-direct-enable-apply:--apply',
         '--require-command-arg',
+        'post-enable:pingora-health-patrol-direct-env-switch:--apply',
+        '--require-command-arg',
+        'post-enable:pingora-health-patrol-direct-env-switch:pingora-direct',
+        '--require-command-arg',
+        'rollback-prep:pingora-gateway-shadow-env-switch:--apply',
+        '--require-command-arg',
+        'rollback-prep:pingora-health-patrol-nginx-env-switch:--apply',
+        '--require-command-arg',
+        'rollback-prep:pingora-health-patrol-nginx-env-switch:nginx',
+        '--require-command-arg',
         'rollback-apply:pingora-direct-rollback-apply:--apply',
         '--require-cutover-run-id',
         config.cutoverRunId,
         '--timeline-max-span-ms',
         String(config.cutoverEvidenceTimelineMaxSpanMs),
       ],
-      when: '三阶段证据包和 enable / rollback apply 命令证据都生成并分别验真后执行，自动找每个 phase 与命令的最新 bundleDir 并再次做只读 manifest 验真，且要求 post-enable manifest.summary.directLiveAccessLog 和 directLiveStaticHeaders 可直接复盘 request_id 对账、静态缓存、校验器、Range 和 304 证据。',
+      when: '三阶段证据包、enable / rollback apply 命令证据和三条 env 变更命令证据都生成并分别验真后执行，自动找每个 phase 与命令的最新 bundleDir 并再次做只读 manifest 验真，且要求 post-enable manifest.summary.directLiveAccessLog 和 directLiveStaticHeaders 可直接复盘 request_id 对账、静态缓存、校验器、Range 和 304 证据，同时要求 post-rollback manifest.summary.pingoraEnvShadow 证明 Pingora env 已恢复 shadow 高端口。',
     },
   ];
 }
 
-function readinessArgs(config, { includeDirect }) {
+function readinessArgs(config, { includeDirect, includeDirectPortsFree = true }) {
   return [
     '--release-runtime-only',
     ...(config.requireLive
@@ -1546,7 +1692,9 @@ function readinessArgs(config, { includeDirect }) {
           '--direct-preflight-check-service-env-file',
           '--direct-preflight-check-service-user-cert-readable',
           '--direct-preflight-check-service-binary-executable',
-          '--direct-preflight-check-ports-free',
+          ...(includeDirectPortsFree
+            ? ['--direct-preflight-check-ports-free']
+            : []),
         ]
       : []),
   ];
@@ -1656,6 +1804,11 @@ function buildSteps(config) {
       command: 'npm',
       args: ['run', 'check:pingora-health-patrol-env-switch'],
     },
+    {
+      name: 'Pingora gateway env shadow 切换烟测',
+      command: 'npm',
+      args: ['run', 'check:pingora-gateway-env-shadow-switch'],
+    },
     {
       name: 'Pingora current release 自审烟测',
       command: 'npm',
diff --git a/scripts/check-production-api-deploy.mjs b/scripts/check-production-api-deploy.mjs
index 378a442a2..3d6d5cc7a 100644
--- a/scripts/check-production-api-deploy.mjs
+++ b/scripts/check-production-api-deploy.mjs
@@ -67,6 +67,7 @@ function main() {
   assertMissingPingoraRealpathCanaryEnableFails();
   assertMissingPingoraRealpathCanaryDisableFails();
   assertMissingPingoraHealthPatrolEnvSwitchFails();
+  assertMissingPingoraGatewayEnvShadowSwitchFails();
   assertMissingPingoraTlsCertSyncFails();
   assertMissingEnvExamplesFails();
   assertMissingPingoraDirectCheckFails();
@@ -119,6 +120,13 @@ function assertDeployCopiesPingoraDirectReleaseDependencies() {
     ),
     'current release 必须包含 Pingora health patrol env 切换脚本。',
   );
+  assertFileExists(
+    path.join(
+      releaseDir,
+      'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    ),
+    'current release 必须包含 Pingora gateway env shadow 切换脚本。',
+  );
   assertFileExists(
     path.join(releaseDir, 'scripts/deploy/pingora-tls-cert-sync.mjs'),
     'current release 必须包含 Pingora TLS 证书同步脚本。',
@@ -996,6 +1004,31 @@ function assertMissingPingoraHealthPatrolEnvSwitchFails() {
   }
 }
 
+function assertMissingPingoraGatewayEnvShadowSwitchFails() {
+  const fixture = prepareFixture('missing-pingora-gateway-env-shadow-switch');
+  rmSync(
+    path.join(
+      fixture.sourceDir,
+      'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    ),
+  );
+  const result = runDeploy(fixture);
+
+  if (result.status === 0) {
+    failures.push(
+      '发布产物缺少 Pingora gateway env shadow 切换脚本时部署必须失败。',
+    );
+  }
+  assertIncludes(
+    result.stderr,
+    '发布产物缺少 Pingora gateway env shadow 切换脚本',
+    '缺少 Pingora gateway env shadow 切换脚本时必须给出明确错误。',
+  );
+  if (!existsSync(fixture.maintenanceFile)) {
+    failures.push('部署失败时必须保持维护模式。');
+  }
+}
+
 function assertMissingPingoraRealpathCanaryEnableFails() {
   const fixture = prepareFixture('missing-pingora-realpath-canary-enable');
   rmSync(
@@ -1215,6 +1248,10 @@ function prepareFixture(name) {
     'scripts/deploy/pingora-health-patrol-env-switch.mjs',
     path.join(sourceDir, 'scripts/deploy/pingora-health-patrol-env-switch.mjs'),
   );
+  copyFile(
+    'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    path.join(sourceDir, 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs'),
+  );
   copyFile(
     'scripts/deploy/pingora-tls-cert-sync.mjs',
     path.join(sourceDir, 'scripts/deploy/pingora-tls-cert-sync.mjs'),
diff --git a/scripts/check-production-api-release.mjs b/scripts/check-production-api-release.mjs
index b2ce7f8b3..652f09a32 100644
--- a/scripts/check-production-api-release.mjs
+++ b/scripts/check-production-api-release.mjs
@@ -132,6 +132,20 @@ function assertApiReleaseContainsPingoraDirectDependencies() {
       ),
       'Pingora health patrol env 切换脚本必须可执行。',
     );
+    assertFileExists(
+      path.join(
+        releaseDir,
+        'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+      ),
+      'API release 必须包含 Pingora gateway env shadow 切换脚本。',
+    );
+    assertExecutable(
+      path.join(
+        releaseDir,
+        'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+      ),
+      'Pingora gateway env shadow 切换脚本必须可执行。',
+    );
     assertFileExists(
       path.join(releaseDir, 'scripts/deploy/pingora-tls-cert-sync.mjs'),
       'API release 必须包含 Pingora TLS 证书同步脚本。',
@@ -479,7 +493,9 @@ function assertReleaseReadinessCutoverPlanBindsCurrentExecutables(releaseDir) {
       '--cutover-run-id',
       'check-production-api-release',
       '--rollback-nginx-smoke-url',
-      'http://127.0.0.1/healthz',
+      'https://example.com/',
+      '--rollback-nginx-smoke-expect-body',
+      '<!doctype html>',
       '--rollback-health-patrol-public-base-url',
       'http://127.0.0.1',
     ],
diff --git a/scripts/check-production-ops-guardrails.mjs b/scripts/check-production-ops-guardrails.mjs
index f011adf78..4ab1e3ff1 100644
--- a/scripts/check-production-ops-guardrails.mjs
+++ b/scripts/check-production-ops-guardrails.mjs
@@ -274,6 +274,18 @@ const checks = [
     reason:
       'Pingora 切换状态快照必须确认 systemd EnvironmentFile 指向本次 pingora env。',
   },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: '--expected-pingora-env-mode',
+    reason:
+      'Pingora 切换状态快照必须支持按阶段强制校验 active Pingora env 是 direct 或 shadow。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
+    includes: 'summarizePingoraEnvPosture',
+    reason:
+      'Pingora 切换状态快照必须输出 active Pingora env 的 shadow/direct 姿态摘要。',
+  },
   {
     file: 'scripts/ops/pingora-cutover-status-snapshot.mjs',
     includes: 'EnvironmentFile 未包含本次 --pingora-env-file',
@@ -290,6 +302,18 @@ const checks = [
     includes: 'assertFailOnCriticalRejectsSystemdPingoraEnvDrift',
     reason: 'Pingora 状态快照自测必须覆盖 systemd 读取了另一份 Pingora env 的负例。',
   },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertSnapshotRejectsDirectPingoraEnvModeDrift',
+    reason:
+      'Pingora 状态快照自测必须覆盖启用后 active env 仍是 shadow 的负例。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
+    includes: 'assertSnapshotRejectsShadowPingoraEnvModeDrift',
+    reason:
+      'Pingora 状态快照自测必须覆盖回退后 active env 仍残留 direct TLS 配置的负例。',
+  },
   {
     file: 'scripts/check-pingora-cutover-status-snapshot.mjs',
     includes: 'assertSnapshotRedactsEnvProbeTokens',
@@ -338,6 +362,24 @@ const checks = [
     reason:
       'Pingora 切换证据包必须能从 direct live stdout 中提取 JSON 结果。',
   },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'pingoraEnvShadow',
+    reason:
+      'Pingora 切换证据包必须把状态快照中的 Pingora env shadow 摘要提升到 manifest。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: '--expected-pingora-env-mode',
+    reason:
+      'Pingora 切换证据包必须把 active Pingora env 姿态要求透传给状态快照。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
+    includes: 'tlsCertFile 应为空',
+    reason:
+      'Pingora env shadow 摘要必须把 TLS 证书路径残留纳入回退证据诊断。',
+  },
   {
     file: 'scripts/ops/pingora-cutover-evidence-bundle.mjs',
     includes: 'snapshotParseError',
@@ -433,6 +475,12 @@ const checks = [
     reason:
       'Pingora 切换证据包自测必须覆盖 direct live 证据归档成功路径。',
   },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
+    includes: 'assertBundleSummarizesPingoraEnvShadow',
+    reason:
+      'Pingora 切换证据包自测必须覆盖 Pingora env shadow 摘要成功路径。',
+  },
   {
     file: 'scripts/check-pingora-cutover-evidence-bundle.mjs',
     includes: 'assertDirectLiveFailureStillWritesEvidenceAndFails',
@@ -1391,6 +1439,11 @@ const checks = [
     includes: 'check:pingora-health-patrol-env-switch',
     reason: 'Pingora health patrol env 切换脚本必须保留可重复 npm 自测入口。',
   },
+  {
+    file: 'package.json',
+    includes: 'check:pingora-gateway-env-shadow-switch',
+    reason: 'Pingora gateway env shadow 切换脚本必须保留可重复 npm 自测入口。',
+  },
   {
     file: 'package.json',
     includes: 'check:pingora-current-release-audit',
@@ -1487,6 +1540,11 @@ const checks = [
     includes: 'check:pingora-health-patrol-env-switch',
     reason: 'Pingora 聚合门禁必须执行 health patrol env 切换脚本烟测。',
   },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'check:pingora-gateway-env-shadow-switch',
+    reason: 'Pingora 聚合门禁必须执行 gateway env shadow 切换脚本烟测。',
+  },
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
     includes: 'check:pingora-current-release-audit',
@@ -1691,6 +1749,53 @@ const checks = [
     reason:
       'Pingora health patrol env 切换脚本自测必须覆盖控制字符参数在 apply 写入前失败。',
   },
+  {
+    file: 'scripts/check-pingora-gateway-env-shadow-switch.mjs',
+    includes: 'assertApplyRestoresShadowAndPreservesOtherKeys',
+    reason: 'Pingora gateway env shadow 切换脚本自测必须覆盖恢复 shadow 并保留其它键。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_LISTEN: \'127.0.0.1:18081\'',
+    reason: 'Pingora gateway env shadow 切换脚本必须固定恢复 shadow 高端口监听。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: \'\'',
+    reason: 'Pingora gateway env shadow 切换脚本必须清空 TLS 低端口监听。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: \'\'',
+    reason: 'Pingora gateway env shadow 切换脚本必须清空 HTTP redirect 低端口监听。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: \'\'',
+    reason:
+      'Pingora gateway env shadow 切换脚本必须清空 TLS cert，避免回退后形成不完整 TLS 配置。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: \'\'',
+    reason:
+      'Pingora gateway env shadow 切换脚本必须清空 TLS key，避免回退后形成不完整 TLS 配置。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'assertShadowEnv(checkFile);',
+    reason: 'Pingora gateway env shadow 切换脚本必须先复核临时目标 env。',
+  },
+  {
+    file: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    includes: 'writeEnvFileAtomically(config.envFile, nextText);',
+    reason: 'Pingora gateway env shadow 切换脚本只能在复核通过后原子写入真实 env。',
+  },
+  {
+    file: 'scripts/check-pingora-gateway-env-shadow-switch.mjs',
+    includes: 'assertRejectsSymlinkEnvFileBeforeWrite',
+    reason: 'Pingora gateway env shadow 切换脚本自测必须覆盖符号链接 env 被拒绝。',
+  },
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
     includes: '--release-runtime-only',
@@ -1828,6 +1933,23 @@ const checks = [
     reason:
       'Pingora cutover runbook 必须在 rollback apply 前提醒把健康巡检预置回 nginx。',
   },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '回退前 Pingora env 预置回 shadow',
+    reason:
+      'Pingora cutover runbook 必须在 rollback apply 前提醒把 Pingora env 预置回 shadow。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'Pingora cutover runbook 必须用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'dry-run cutover 回退前 Pingora gateway env shadow 切换必须显式带 --apply。',
+    reason:
+      'Pingora runbook 自检必须锁住 rollback apply 前 Pingora shadow env 脚本化预置步骤。',
+  },
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
     includes: 'pingora-health-patrol-env-switch.mjs',
@@ -2011,6 +2133,66 @@ const checks = [
     includes: 'manifest.files` 视为闭集',
     reason: '团队共享踩坑必须记录 Pingora 证据目录不能夹带未登记条目。',
   },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'pingora-gateway-env-shadow-switch.mjs --apply',
+    reason: 'Pingora 试点文档必须记录 rollback apply 前用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: 'pingora-gateway-env-shadow-switch.mjs --apply',
+    reason: '生产运维文档必须记录 rollback apply 前用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: 'pingora-gateway-env-shadow-switch.mjs --apply',
+    reason: '团队共享决策必须记录 rollback apply 前用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: 'pingora-gateway-env-shadow-switch.mjs --apply',
+    reason: '团队共享踩坑必须记录 rollback apply 前用随包脚本恢复 Pingora shadow env。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'Nginx README 的 API release 清单必须包含 Pingora gateway env shadow 切换脚本。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'rollback apply 前必须先执行',
+    reason: 'Nginx README 必须说明 rollback apply 前先恢复 Pingora gateway shadow env。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'TLS_CERT_FILE',
+    reason: 'Nginx README 必须说明 Pingora gateway shadow 回退会清空 TLS cert/key 路径。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '--expected-pingora-env-mode direct',
+    reason: 'Nginx README 必须说明 post-enable 证据包会强制校验 Pingora env direct 姿态。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '--expected-pingora-env-mode shadow',
+    reason: 'Nginx README 必须说明 post-rollback 证据包会强制校验 Pingora env shadow 姿态。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'manifest.summary.pingoraEnvShadow',
+    reason: 'Nginx README 必须说明证据 manifest 会提升 Pingora env shadow 摘要。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: 'tlsCertFile',
+    reason: 'Nginx README 必须说明 Pingora env shadow 摘要包含 TLS cert/key 残留字段。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: 'tlsCertFile',
+    reason: 'Pingora 试点文档必须说明证据摘要包含 TLS cert/key 残留字段。',
+  },
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
     includes: '切换证据根目录三阶段总审计',
@@ -2028,35 +2210,107 @@ const checks = [
     reason:
       'Pingora cutover runbook 总审计必须要求 direct rollback apply 命令证据。',
   },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'post-enable:pingora-health-patrol-direct-env-switch',
+    reason:
+      'Pingora cutover runbook 总审计必须要求 health patrol 切到 direct 的命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'rollback-prep:pingora-gateway-shadow-env-switch',
+    reason:
+      'Pingora cutover runbook 总审计必须要求回退前 Pingora gateway env shadow 切换命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: 'rollback-prep:pingora-health-patrol-nginx-env-switch',
+    reason:
+      'Pingora cutover runbook 总审计必须要求回退前 health patrol 切回 Nginx 的命令证据。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness.mjs',
+    includes: '--require-phase-pingora-env-shadow',
+    reason:
+      'Pingora cutover runbook 总审计必须要求 post-rollback Pingora env shadow 证据。',
+  },
   {
     file: 'scripts/check-pingora-release-readiness-plan.mjs',
     includes: '三阶段总审计必须使用 current release 随包 evidence audit 脚本',
     reason: 'Pingora runbook 自检必须锁住 current release 随包证据根目录审计脚本。',
   },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: '三阶段总审计必须要求 post-rollback 阶段带 Pingora env shadow 摘要。',
+    reason:
+      'Pingora runbook 自检必须锁住总审计里的 post-rollback shadow env 证据要求。',
+  },
   {
     file: 'scripts/check-pingora-release-readiness-plan.mjs',
     includes: '三阶段总审计必须显式要求真实切换命令证据',
-    reason: 'Pingora runbook 自检必须锁住总审计里的 enable / rollback 命令证据要求。',
+    reason: 'Pingora runbook 自检必须锁住总审计里的 enable / rollback 和 env 切换命令证据要求。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason:
+      'Pingora runbook 自检必须锁住 health patrol direct env 切换命令的真实脚本身份。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason:
+      'Pingora runbook 自检必须锁住 Pingora gateway shadow env 切换命令的真实脚本身份。',
+  },
+  {
+    file: 'scripts/check-pingora-release-readiness-plan.mjs',
+    includes: 'rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs',
+    reason:
+      'Pingora runbook 自检必须锁住 health patrol nginx env 切换命令的真实脚本身份。',
   },
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
     includes: '--require-command-executable',
-    reason: 'Pingora cutover runbook 总审计必须要求 enable / rollback 命令证据的真实脚本身份。',
+    reason: 'Pingora cutover runbook 总审计必须要求真实切换命令证据的真实脚本身份。',
   },
   {
     file: 'scripts/check-pingora-release-readiness-plan.mjs',
     includes: '三阶段总审计必须显式要求真实切换脚本身份',
-    reason: 'Pingora runbook 自检必须锁住总审计里的 enable / rollback 命令脚本身份要求。',
+    reason: 'Pingora runbook 自检必须锁住总审计里的真实切换命令脚本身份要求。',
   },
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
     includes: '--require-command-arg',
-    reason: 'Pingora cutover runbook 总审计必须要求 enable / rollback 命令证据包含 --apply 参数。',
+    reason: 'Pingora cutover runbook 总审计必须要求真实切换命令证据包含关键参数。',
   },
   {
     file: 'scripts/check-pingora-release-readiness-plan.mjs',
     includes: '三阶段总审计必须显式要求真实切换命令必需参数',
-    reason: 'Pingora runbook 自检必须锁住总审计里的 enable / rollback 命令参数要求。',
+    reason: 'Pingora runbook 自检必须锁住总审计里的真实切换命令参数要求。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: "commandName: 'pingora-health-patrol-direct-env-switch'",
+    reason:
+      'Pingora 证据根目录审计标准时间线必须包含 health patrol direct env 切换命令。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: "commandName: 'pingora-gateway-shadow-env-switch'",
+    reason:
+      'Pingora 证据根目录审计标准时间线必须包含 Pingora gateway shadow env 切换命令。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: "commandName: 'pingora-health-patrol-nginx-env-switch'",
+    reason:
+      'Pingora 证据根目录审计标准时间线必须包含 health patrol nginx env 切换命令。',
+  },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: '完整切换时间线总审计必须检查三阶段和五条命令',
+    reason:
+      'Pingora 证据根目录审计自测必须把完整时间线固定为三阶段和五条命令。',
   },
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
@@ -2526,8 +2780,9 @@ const checks = [
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
     includes:
-      '启用 --require-direct 时必须提供 --direct-preflight-check-ports-free',
-    reason: 'Pingora 强制直连门禁不能跳过 80/443 端口释放核验。',
+      '启用 --dry-run-cutover 时必须提供 --direct-preflight-check-ports-free',
+    reason:
+      'Pingora 切换前 runbook 门禁不能跳过 80/443 端口释放核验；启用后直连复核不再要求端口空闲。',
   },
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
@@ -2814,9 +3069,9 @@ const checks = [
   },
   {
     file: 'scripts/check-pingora-release-readiness-plan.mjs',
-    includes: '--require-direct 必须检查 TLS/HTTP redirect 端口已释放',
+    includes: 'dry-run cutover 启用前预检必须检查 80/443 端口释放',
     reason:
-      'Pingora 聚合门禁计划自检必须覆盖 --require-direct 的端口释放硬要求。',
+      'Pingora 聚合门禁计划自检必须覆盖切换前端口释放硬要求。',
   },
   {
     file: 'scripts/check-pingora-release-readiness-plan.mjs',
@@ -2900,8 +3155,9 @@ const checks = [
   },
   {
     file: 'scripts/check-pingora-release-readiness-plan.mjs',
-    includes: '--require-direct 缺少端口释放 preflight 时必须失败',
-    reason: 'Pingora 聚合门禁计划自检必须覆盖缺少端口释放 preflight 的负例。',
+    includes: '--require-direct post-enable 复核不能要求 80/443 空闲',
+    reason:
+      'Pingora 聚合门禁计划自检必须覆盖启用后直连复核不再要求端口空闲。',
   },
   {
     file: 'scripts/check-pingora-release-readiness-plan.mjs',
@@ -4103,8 +4359,9 @@ const checks = [
   },
   {
     file: 'scripts/check-pingora-release-readiness-plan.mjs',
-    includes: 'dry-run cutover rollback apply 必须默认校验 healthz ok body',
-    reason: 'Pingora cutover runbook 自检必须覆盖 rollback Nginx smoke body 默认门禁。',
+    includes: 'dry-run cutover rollback apply 必须使用显式传入的 Nginx smoke body 片段',
+    reason:
+      'Pingora cutover runbook 自检必须覆盖 rollback Nginx smoke body 显式配置门禁。',
   },
   {
     file: 'scripts/check-pingora-release-readiness.mjs',
@@ -4323,6 +4580,11 @@ const checks = [
     includes: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
     reason: 'API release build 动态烟测必须覆盖 health patrol env 切换脚本进入发布包。',
   },
+  {
+    file: 'scripts/check-production-api-release.mjs',
+    includes: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'API release build 动态烟测必须覆盖 gateway env shadow 切换脚本进入发布包。',
+  },
   {
     file: 'scripts/check-production-api-release.mjs',
     includes: 'scripts/check-pingora-direct-preflight.mjs',
@@ -4582,6 +4844,11 @@ const checks = [
     includes: 'scripts/deploy/pingora-health-patrol-env-switch.mjs',
     reason: 'API deploy 动态烟测必须覆盖 health patrol env 切换脚本进入 current release。',
   },
+  {
+    file: 'scripts/check-production-api-deploy.mjs',
+    includes: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'API deploy 动态烟测必须覆盖 gateway env shadow 切换脚本进入 current release。',
+  },
   {
     file: 'scripts/check-production-api-deploy.mjs',
     includes: 'scripts/check-pingora-direct-live.mjs',
@@ -5121,12 +5388,42 @@ const checks = [
     reason:
       'Pingora 证据根目录审计必须读取阶段 manifest 的 direct live 静态响应头摘要。',
   },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: '--require-phase-pingora-env-shadow',
+    reason:
+      'Pingora 证据根目录审计必须支持强制校验 post-rollback Pingora env shadow 摘要。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'summaryPingoraEnvShadow',
+    reason:
+      'Pingora 证据根目录审计必须读取阶段 manifest 的 Pingora env shadow 摘要。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'tlsCertFile 必须为空',
+    reason:
+      'Pingora 证据根目录审计必须拒绝 post-rollback TLS 证书路径残留。',
+  },
+  {
+    file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
+    includes: 'shadowReady 必须为 true',
+    reason:
+      'Pingora 证据根目录审计必须拒绝 post-rollback 快照姿态不是 shadow 的证据。',
+  },
   {
     file: 'scripts/ops/pingora-cutover-evidence-audit.mjs',
     includes: 'directLiveStaticHeaders: latest.summaryDirectLiveStaticHeaders',
     reason:
       'Pingora 证据根目录审计输出必须提升阶段 direct live 静态响应头摘要。',
   },
+  {
+    file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
+    includes: 'assertRequirePhasePingoraEnvShadowFailsWhenDirectLowPortsRemain',
+    reason:
+      'Pingora 证据根目录审计自测必须覆盖 post-rollback 低端口 env 残留失败路径。',
+  },
   {
     file: 'scripts/check-pingora-cutover-evidence-audit.mjs',
     includes: '证据根审计输出必须提升 post-enable direct live 指纹静态 Cache-Control 摘要。',
@@ -5557,6 +5854,98 @@ const checks = [
     includes: '--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log',
     reason: '团队共享踩坑必须记录 Pingora 直连 access log 参数。',
   },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: '启用后 `--require-direct --release-runtime-only` 复核不再要求端口空闲',
+    reason:
+      '生产运维文档必须明确 Pingora 启用后直连复核不再要求 80/443 空闲。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: '不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`',
+    reason:
+      '生产运维文档必须阻止回退 smoke 继续沿用旧的固定 healthz 响应片段。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    includes: "--rollback-nginx-smoke-expect-body '<!doctype html>'",
+    reason: '生产运维文档必须展示来自真实 Nginx 首页的回退响应体片段示例。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: '`--require-direct` 用于 Pingora 已接管后的直连复核，不再要求 `--direct-preflight-check-ports-free`',
+    reason:
+      'Pingora 试点文档必须明确端口释放检查只属于切流前和启用 apply 阶段。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    includes: "--rollback-nginx-smoke-expect-body '<!doctype html>'",
+    reason: 'Pingora 试点文档必须展示真实 Nginx 回退 smoke 响应体片段。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '启用后 `--require-direct` 复核不再要求端口空闲',
+    reason: 'Nginx README 必须记录 Pingora 启用后 direct 复核的端口语义。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: "--nginx-smoke-expect-body '<!doctype html>'",
+    reason: 'Nginx README 必须展示真实 Nginx 回退 smoke 响应体片段。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    includes: '不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`',
+    reason: 'Nginx README 必须防止回退 smoke 示例回到旧 healthz 口径。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: '不再默认假定 `/healthz` 会返回 `"ok":true`',
+    reason: '团队共享决策必须记录回退 smoke 的真实 Nginx 入口要求。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/decision-log.md',
+    includes: '启用后复核应看到端口由 Pingora 占用而不是空闲',
+    reason:
+      '团队共享决策必须记录启用后 --require-direct 不再检查端口空闲。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: '不要继续用固定 `/healthz` 与 `"ok":true`',
+    reason: '团队共享踩坑必须提醒回退 smoke 不能沿用旧 healthz 片段。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    includes: '启用后 `--require-direct` 复核不再要求端口空闲',
+    reason: '团队共享踩坑必须提醒端口空闲只属于切流前门禁。',
+  },
+  {
+    file: 'deploy/nginx/README.md',
+    excludes:
+      '--nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名> --nginx-smoke-expect-body \'"ok":true\'',
+    reason: 'Nginx README 不应再给出固定 healthz + ok:true 的回退命令。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    excludes:
+      '--nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名> --nginx-smoke-expect-body \'"ok":true\'',
+    reason: '生产运维文档不应再给出固定 healthz + ok:true 的回退命令。',
+  },
+  {
+    file: 'docs/【开发运维】本地开发验证与生产运维-2026-05-15.md',
+    excludes: 'rollback-nginx-smoke-expect-body="ok":true',
+    reason: '生产运维 runbook 不应再默认展示 ok:true 作为回退响应体片段。',
+  },
+  {
+    file: 'docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md',
+    excludes: 'rollback-nginx-smoke-expect-body="ok":true',
+    reason: 'Pingora 试点 runbook 不应再默认展示 ok:true 作为回退响应体片段。',
+  },
+  {
+    file: 'docs/project-memory/shared-memory/pitfalls.md',
+    excludes:
+      '--nginx-smoke-url http://127.0.0.1/healthz --nginx-smoke-host <域名>',
+    reason: '团队共享踩坑不应再把固定本机 healthz 当成可执行回退示例。',
+  },
   {
     file: 'deploy/pingora/pingora-gateway.env.example',
     includes: 'GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED',
@@ -5703,6 +6092,12 @@ const checks = [
       'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs',
     reason: 'API Build 归档必须包含 Pingora health patrol env 切换脚本。',
   },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-build',
+    includes:
+      'build/${env.EFFECTIVE_BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'API Build 归档必须包含 Pingora gateway env shadow 切换脚本。',
+  },
   {
     file: 'jenkins/Jenkinsfile.production-api-build',
     includes:
@@ -5845,6 +6240,12 @@ const checks = [
       'build/${params.BUILD_VERSION}/scripts/deploy/pingora-health-patrol-env-switch.mjs',
     reason: 'API Deploy 必须复制 build 产物内的 Pingora health patrol env 切换脚本。',
   },
+  {
+    file: 'jenkins/Jenkinsfile.production-api-deploy',
+    includes:
+      'build/${params.BUILD_VERSION}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
+    reason: 'API Deploy 必须复制 build 产物内的 Pingora gateway env shadow 切换脚本。',
+  },
   {
     file: 'jenkins/Jenkinsfile.production-api-deploy',
     includes: 'build/${params.BUILD_VERSION}/scripts/deploy/maintenance-off.sh',
diff --git a/scripts/deploy/pingora-gateway-env-shadow-switch.mjs b/scripts/deploy/pingora-gateway-env-shadow-switch.mjs
new file mode 100644
index 000000000..ab7ba188e
--- /dev/null
+++ b/scripts/deploy/pingora-gateway-env-shadow-switch.mjs
@@ -0,0 +1,254 @@
+#!/usr/bin/env node
+
+import {
+  chownSync,
+  chmodSync,
+  lstatSync,
+  mkdtempSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const TARGET_KEYS = [
+  'GENARRATIVE_PINGORA_GATEWAY_LISTEN',
+  'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN',
+  'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
+  'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE',
+  'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE',
+];
+const SHADOW_VALUES = {
+  GENARRATIVE_PINGORA_GATEWAY_LISTEN: '127.0.0.1:18081',
+  GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN: '',
+  GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN: '',
+  GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE: '',
+  GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE: '',
+};
+const DRY_RUN_ENV_FILE_MODE = 0o600;
+
+const config = parseArgs(process.argv.slice(2));
+if (config.apply) {
+  assertEnvFileIsWritableRegularFile(config.envFile);
+}
+
+const originalText = readFileSync(config.envFile, 'utf8');
+const nextText = rewriteEnvFile(originalText, SHADOW_VALUES);
+const checkFile = writeDryRunEnv(nextText);
+
+try {
+  console.log(
+    `[pingora-gateway-env-shadow-switch] apply=${config.apply} env=${config.envFile}`,
+  );
+  for (const key of TARGET_KEYS) {
+    console.log(`~ ${key}=${SHADOW_VALUES[key]}`);
+  }
+  assertShadowEnv(checkFile);
+
+  if (!config.apply) {
+    console.log(
+      '[pingora-gateway-env-shadow-switch] 当前是 dry-run；追加 --apply 后才会写入 env 文件。',
+    );
+  } else {
+    writeEnvFileAtomically(config.envFile, nextText);
+  }
+
+  console.log('[pingora-gateway-env-shadow-switch] 完成');
+} finally {
+  rmSync(path.dirname(checkFile), { recursive: true, force: true });
+}
+
+function parseArgs(argv) {
+  const result = {
+    envFile:
+      process.env.GENARRATIVE_PINGORA_GATEWAY_ENV_FILE ||
+      '/etc/genarrative/pingora-gateway.env',
+    apply: false,
+  };
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case '-h':
+      case '--help':
+        printUsage();
+        process.exit(0);
+        break;
+      case '--env-file':
+        result.envFile = requireValue(argv, ++index, arg);
+        break;
+      case '--apply':
+        result.apply = true;
+        break;
+      default:
+        throw new Error(`未知参数: ${arg}`);
+    }
+  }
+
+  if (!path.isAbsolute(result.envFile)) {
+    throw new Error(`--env-file 必须是绝对路径: ${result.envFile}`);
+  }
+  validateNoControlCharacters(result.envFile, '--env-file');
+  if (isFilesystemRootPath(result.envFile)) {
+    throw new Error('--env-file 不能是文件系统根目录。');
+  }
+
+  return result;
+}
+
+function printUsage() {
+  console.log(`Usage:
+  node scripts/deploy/pingora-gateway-env-shadow-switch.mjs [options]
+
+Options:
+  --env-file <path>  Pingora gateway env 文件，默认 /etc/genarrative/pingora-gateway.env。
+  --apply            写入 env 文件；默认只 dry-run 并用临时 env 复核。
+`);
+}
+
+function requireValue(argv, index, flag) {
+  const value = argv[index];
+  if (value === undefined || value.startsWith('--')) {
+    throw new Error(`${flag} 缺少参数值`);
+  }
+  return value;
+}
+
+function rewriteEnvFile(text, nextValuesByKey) {
+  const lines = text.replace(/\r\n/gu, '\n').split('\n');
+  if (lines.at(-1) === '') {
+    lines.pop();
+  }
+
+  const seen = new Set();
+  const output = [];
+  for (const line of lines) {
+    const assignment = parseAssignmentLine(line);
+    if (!assignment || !TARGET_KEYS.includes(assignment.key)) {
+      output.push(line);
+      continue;
+    }
+    if (seen.has(assignment.key)) {
+      throw new Error(`pingora gateway env 中存在重复配置: ${assignment.key}`);
+    }
+    seen.add(assignment.key);
+    output.push(
+      `${assignment.leading}${assignment.exportPrefix}${assignment.key}=${nextValuesByKey[assignment.key]}`,
+    );
+  }
+
+  for (const key of TARGET_KEYS) {
+    if (!seen.has(key)) {
+      output.push(`${key}=${nextValuesByKey[key]}`);
+    }
+  }
+
+  return `${output.join('\n')}\n`;
+}
+
+function parseAssignmentLine(line) {
+  const match = line.match(/^(\s*)(export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/u);
+  if (!match) {
+    return null;
+  }
+  return {
+    leading: match[1] || '',
+    exportPrefix: match[2] || '',
+    key: match[3],
+  };
+}
+
+function writeDryRunEnv(content) {
+  const dir = mkdtempSync(
+    path.join(tmpdir(), 'genarrative-pingora-gateway-env-shadow-switch-'),
+  );
+  const filePath = path.join(dir, 'pingora-gateway.env');
+  writeFileSync(filePath, content, {
+    encoding: 'utf8',
+    mode: DRY_RUN_ENV_FILE_MODE,
+  });
+  chmodSync(filePath, DRY_RUN_ENV_FILE_MODE);
+  return filePath;
+}
+
+function assertShadowEnv(filePath) {
+  const values = parseEnvFile(readFileSync(filePath, 'utf8'));
+  if (
+    values.GENARRATIVE_PINGORA_GATEWAY_LISTEN !==
+    SHADOW_VALUES.GENARRATIVE_PINGORA_GATEWAY_LISTEN
+  ) {
+    throw new Error(
+      'shadow env 复核失败：GENARRATIVE_PINGORA_GATEWAY_LISTEN 必须是 127.0.0.1:18081。',
+    );
+  }
+  for (const key of [
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN',
+    'GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN',
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE',
+    'GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE',
+  ]) {
+    if ((values[key] || '') !== '') {
+      throw new Error(`shadow env 复核失败：${key} 必须为空。`);
+    }
+  }
+}
+
+function parseEnvFile(text) {
+  const values = {};
+  for (const line of text.split(/\r?\n/u)) {
+    const assignment = parseAssignmentLine(line);
+    if (!assignment) {
+      continue;
+    }
+    values[assignment.key] = line
+      .slice(line.indexOf('=') + 1)
+      .trim()
+      .replace(/^['"]|['"]$/gu, '');
+  }
+  return values;
+}
+
+function writeEnvFileAtomically(filePath, content) {
+  const currentStat = assertEnvFileIsWritableRegularFile(filePath);
+  const currentMode = currentStat.mode & 0o777;
+  const tempFile = path.join(
+    path.dirname(filePath),
+    `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  try {
+    writeFileSync(tempFile, content, { encoding: 'utf8', mode: currentMode });
+    chownSync(tempFile, currentStat.uid, currentStat.gid);
+    chmodSync(tempFile, currentMode);
+    assertEnvFileIsWritableRegularFile(filePath);
+    renameSync(tempFile, filePath);
+  } catch (error) {
+    rmSync(tempFile, { force: true });
+    throw error;
+  }
+}
+
+function assertEnvFileIsWritableRegularFile(filePath) {
+  const currentStat = lstatSync(filePath);
+  if (currentStat.isSymbolicLink()) {
+    throw new Error(
+      `--env-file 不能是符号链接；请直接传真实 Pingora gateway env 文件路径: ${filePath}`,
+    );
+  }
+  if (!currentStat.isFile()) {
+    throw new Error(`--env-file 必须指向普通文件: ${filePath}`);
+  }
+  return currentStat;
+}
+
+function validateNoControlCharacters(value, label) {
+  if (/[\0\r\n]/u.test(String(value ?? ''))) {
+    throw new Error(`${label} 不能包含换行或 NUL 字符。`);
+  }
+}
+
+function isFilesystemRootPath(value) {
+  const resolved = path.resolve(String(value));
+  return resolved === path.parse(resolved).root;
+}
diff --git a/scripts/deploy/production-api-deploy.sh b/scripts/deploy/production-api-deploy.sh
index 14742cdcd..851d897a2 100644
--- a/scripts/deploy/production-api-deploy.sh
+++ b/scripts/deploy/production-api-deploy.sh
@@ -706,6 +706,7 @@ PINGORA_ROLLBACK_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-direct-roll
 PINGORA_REALPATH_CANARY_ENABLE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-realpath-canary-enable.sh"
 PINGORA_REALPATH_CANARY_DISABLE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-realpath-canary-disable.sh"
 PINGORA_HEALTH_PATROL_ENV_SWITCH_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs"
+PINGORA_GATEWAY_ENV_SHADOW_SWITCH_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
 PINGORA_TLS_CERT_SYNC_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs"
 PINGORA_PREFLIGHT_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/check-pingora-direct-preflight.mjs"
 PINGORA_LIVE_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/check-pingora-direct-live.mjs"
@@ -812,6 +813,12 @@ if [[ ! -f "${PINGORA_HEALTH_PATROL_ENV_SWITCH_SCRIPT_SOURCE}" ]]; then
 fi
 cp "${PINGORA_HEALTH_PATROL_ENV_SWITCH_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs"
 chmod 0755 "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-health-patrol-env-switch.mjs"
+if [[ ! -f "${PINGORA_GATEWAY_ENV_SHADOW_SWITCH_SCRIPT_SOURCE}" ]]; then
+  echo "[production-api-deploy] 发布产物缺少 Pingora gateway env shadow 切换脚本: ${SOURCE_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs" >&2
+  exit 1
+fi
+cp "${PINGORA_GATEWAY_ENV_SHADOW_SWITCH_SCRIPT_SOURCE}" "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
+chmod 0755 "${RELEASE_CONTENT_DIR}/scripts/deploy/pingora-gateway-env-shadow-switch.mjs"
 if [[ ! -f "${PINGORA_TLS_CERT_SYNC_SCRIPT_SOURCE}" ]]; then
   echo "[production-api-deploy] 发布产物缺少 Pingora TLS 证书同步脚本: ${SOURCE_DIR}/scripts/deploy/pingora-tls-cert-sync.mjs" >&2
   exit 1
diff --git a/scripts/ops/pingora-current-release-audit.mjs b/scripts/ops/pingora-current-release-audit.mjs
index 88f9a1e55..cc49901f2 100644
--- a/scripts/ops/pingora-current-release-audit.mjs
+++ b/scripts/ops/pingora-current-release-audit.mjs
@@ -3,7 +3,7 @@
 import { execFile } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { constants as fsConstants } from 'node:fs';
-import { access, readFile, stat } from 'node:fs/promises';
+import { access, readFile, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
 
 const REQUIRED_ARTIFACTS = [
@@ -25,6 +25,7 @@ const REQUIRED_ARTIFACTS = [
   { path: 'scripts/deploy/pingora-realpath-canary-enable.sh', executable: true },
   { path: 'scripts/deploy/pingora-realpath-canary-disable.sh', executable: true },
   { path: 'scripts/deploy/pingora-health-patrol-env-switch.mjs', executable: true },
+  { path: 'scripts/deploy/pingora-gateway-env-shadow-switch.mjs', executable: true },
   { path: 'scripts/deploy/pingora-tls-cert-sync.mjs', executable: true },
   { path: 'deploy/systemd/genarrative-pingora-gateway.service' },
   { path: 'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf' },
@@ -555,6 +556,7 @@ async function inspectReleaseManifest(input, pingoraGateway) {
 
 async function inspectSystemd(input) {
   const expectedBinary = path.join(input.releaseRoot, 'pingora-gateway');
+  const expectedRealpath = await resolveOptionalRealpath(expectedBinary);
   const result = await runCommand(
     'systemctl',
     [
@@ -578,7 +580,17 @@ async function inspectSystemd(input) {
   }
 
   const execStart = show.ExecStart || '';
-  if (result.code === 0 && !execStart.includes(expectedBinary)) {
+  const execStartBinary = parseExecStartBinary(execStart);
+  const execStartRealpath = execStartBinary
+    ? await resolveOptionalRealpath(execStartBinary)
+    : null;
+  const execStartMatches =
+    execStartBinary === expectedBinary ||
+    (expectedRealpath &&
+      execStartRealpath &&
+      expectedRealpath === execStartRealpath);
+
+  if (result.code === 0 && !execStartMatches) {
     diagnostics.push(
       `ExecStart 未指向 current release 网关二进制: expected ${expectedBinary}, actual ${execStart || '(空)'}`,
     );
@@ -590,6 +602,9 @@ async function inspectSystemd(input) {
     service: input.systemdService,
     status,
     expectedBinary,
+    expectedRealpath,
+    execStartBinary,
+    execStartRealpath,
     fragmentPath: show.FragmentPath || '',
     dropInPaths: show.DropInPaths || '',
     user: show.User || '',
@@ -599,6 +614,26 @@ async function inspectSystemd(input) {
   };
 }
 
+async function resolveOptionalRealpath(filePath) {
+  try {
+    return await realpath(filePath);
+  } catch {
+    return null;
+  }
+}
+
+function parseExecStartBinary(execStart) {
+  const pathMatch = execStart.match(/\bpath=([^ ;]+)(?:\s|;|$)/u);
+  if (pathMatch) {
+    return pathMatch[1];
+  }
+  const argvMatch = execStart.match(/\bargv\[\]=([^ ;]+)(?:\s|;|$)/u);
+  if (argvMatch) {
+    return argvMatch[1];
+  }
+  return '';
+}
+
 function parseSystemctlShow(text) {
   const result = {};
   for (const line of text.split(/\r?\n/u)) {
diff --git a/scripts/ops/pingora-cutover-evidence-audit.mjs b/scripts/ops/pingora-cutover-evidence-audit.mjs
index 6b9f5787c..43b73eba2 100644
--- a/scripts/ops/pingora-cutover-evidence-audit.mjs
+++ b/scripts/ops/pingora-cutover-evidence-audit.mjs
@@ -16,7 +16,22 @@ const CUTOVER_TIMELINE_ORDER = [
     phase: 'enable-apply',
     commandName: 'pingora-direct-enable-apply',
   },
+  {
+    type: 'command',
+    phase: 'post-enable',
+    commandName: 'pingora-health-patrol-direct-env-switch',
+  },
   { type: 'phase', phase: 'post-enable' },
+  {
+    type: 'command',
+    phase: 'rollback-prep',
+    commandName: 'pingora-gateway-shadow-env-switch',
+  },
+  {
+    type: 'command',
+    phase: 'rollback-prep',
+    commandName: 'pingora-health-patrol-nginx-env-switch',
+  },
   {
     type: 'command',
     phase: 'rollback-apply',
@@ -59,6 +74,7 @@ function parseArgs(argv) {
     requiredPhases: [],
     requiredPhaseDirectLiveAccessLog: [],
     requiredPhaseDirectLiveStaticHeaders: [],
+    requiredPhasePingoraEnvShadow: [],
     requiredCommands: [],
     requiredCommandExecutables: [],
     requiredCommandArgs: [],
@@ -95,6 +111,11 @@ function parseArgs(argv) {
           requireValue(argv, ++index, arg),
         );
         break;
+      case '--require-phase-pingora-env-shadow':
+        result.requiredPhasePingoraEnvShadow.push(
+          requireValue(argv, ++index, arg),
+        );
+        break;
       case '--require-command-executable':
         result.requiredCommandExecutables.push(requireValue(argv, ++index, arg));
         break;
@@ -137,6 +158,9 @@ function parseArgs(argv) {
   result.requiredPhaseDirectLiveStaticHeaders = normalizeRequiredPhases(
     result.requiredPhaseDirectLiveStaticHeaders,
   );
+  result.requiredPhasePingoraEnvShadow = normalizeRequiredPhases(
+    result.requiredPhasePingoraEnvShadow,
+  );
   const requiredCommands = normalizeRequiredCommands(result.requiredCommands);
   result.requiredCommandExecutables = normalizeRequiredCommandExecutables(
     result.requiredCommandExecutables,
@@ -172,6 +196,8 @@ Options:
                          要求某个阶段 manifest.summary.directLiveAccessLog 已存在且 direct live request_id access log 对账成功；正式切换默认用于 post-enable。
   --require-phase-direct-live-static-headers <phase>
                          要求某个阶段 manifest.summary.directLiveStaticHeaders 已存在且包含可判定的 direct live 静态响应头摘要；正式切换默认用于 post-enable。
+  --require-phase-pingora-env-shadow <phase>
+                         要求某个阶段 manifest.summary.pingoraEnvShadow 已存在且证明 Pingora env 已恢复 shadow 高端口；正式切换默认用于 post-rollback。
   --require-command-executable <phase>:<commandName>:<absolutePath>
                          要求某个命令证据的 manifest.expectedExecutable、manifest.command.executable 和 command-record.json executable 与该绝对路径一致；可重复。
   --require-command-arg <phase>:<commandName>:<arg>
@@ -183,7 +209,7 @@ Options:
   --allow-extra-root-entries
                          允许证据根目录中存在非证据目录条目；默认拒绝，正式切换归档不应使用。
 
-该脚本只读扫描 Pingora 直连切换证据根目录，按 manifest.phase 找到每个阶段的最新证据目录，也可按 manifest.phase + manifest.commandName 找到真实切换命令证据，并调用随包证据验真脚本的 --require-summary-ok 严格模式校验 schemaVersion=1 manifest.files 的 sizeBytes / sha256 与 manifest.summary.status=OK；所有候选证据都必须带合法 manifest.generatedAt，最新证据选择和标准时间线证明只使用该字段，不用目录 mtime 兜底；若同一阶段或同一命令的最新 manifest.generatedAt 重复，则拒绝按目录名打平并要求重新归档或清理证据根目录；命令证据的 manifest.command 与 command-record.json 也必须是 schemaVersion=1；可用 --require-phase-direct-live-access-log 要求指定阶段必须带 direct live access log 对账摘要，防止旧 post-enable 证据包缺少 request_id 反查复盘入口；可用 --require-phase-direct-live-static-headers 要求指定阶段必须带 direct live 静态响应头摘要，防止旧 post-enable 证据包缺少 Cache-Control、ETag、Last-Modified、Range 和 304 复盘入口；证据根目录默认只能包含带 manifest.json 的证据目录，不允许夹带普通文件、无 manifest 目录或符号链接；不会修改证据目录、不会 reload systemd、不会访问 Nginx 或 Pingora。
+该脚本只读扫描 Pingora 直连切换证据根目录，按 manifest.phase 找到每个阶段的最新证据目录，也可按 manifest.phase + manifest.commandName 找到真实切换命令证据，并调用随包证据验真脚本的 --require-summary-ok 严格模式校验 schemaVersion=1 manifest.files 的 sizeBytes / sha256 与 manifest.summary.status=OK；所有候选证据都必须带合法 manifest.generatedAt，最新证据选择和标准时间线证明只使用该字段，不用目录 mtime 兜底；若同一阶段或同一命令的最新 manifest.generatedAt 重复，则拒绝按目录名打平并要求重新归档或清理证据根目录；命令证据的 manifest.command 与 command-record.json 也必须是 schemaVersion=1；可用 --require-phase-direct-live-access-log 要求指定阶段必须带 direct live access log 对账摘要，防止旧 post-enable 证据包缺少 request_id 反查复盘入口；可用 --require-phase-direct-live-static-headers 要求指定阶段必须带 direct live 静态响应头摘要，防止旧 post-enable 证据包缺少 Cache-Control、ETag、Last-Modified、Range 和 304 复盘入口；可用 --require-phase-pingora-env-shadow 要求指定阶段必须带 Pingora env shadow 摘要，防止旧 post-rollback 证据包无法证明 active env 已从低端口 direct 恢复到 127.0.0.1:18081；证据根目录默认只能包含带 manifest.json 的证据目录，不允许夹带普通文件、无 manifest 目录或符号链接；不会修改证据目录、不会 reload systemd、不会访问 Nginx 或 Pingora。
 `);
 }
 
@@ -634,6 +660,7 @@ async function discoverEvidence(evidenceRoot, options = {}) {
       summaryDirectLiveAccessLog: manifest.summary?.directLiveAccessLog ?? null,
       summaryDirectLiveStaticHeaders:
         manifest.summary?.directLiveStaticHeaders ?? null,
+      summaryPingoraEnvShadow: manifest.summary?.pingoraEnvShadow ?? null,
       commandName,
       manifestCommand: manifest.command || null,
       commandRecordFileName: manifest.files?.commandRecord?.path || null,
@@ -730,6 +757,9 @@ async function buildAudit(config, discovery) {
     const requiredStaticHeaders = config.requiredPhaseDirectLiveStaticHeaders.includes(
       phase,
     );
+    const requiredPingoraEnvShadow = config.requiredPhasePingoraEnvShadow.includes(
+      phase,
+    );
     const allPhaseCandidates = discovery.candidates.filter(
       (candidate) => candidate.phase === phase && candidate.commandName === null,
     );
@@ -747,8 +777,10 @@ async function buildAudit(config, discovery) {
         requiredCutoverRunId: config.requiredCutoverRunId || null,
         requiredDirectLiveAccessLog: requiredAccessLog,
         requiredDirectLiveStaticHeaders: requiredStaticHeaders,
+        requiredPingoraEnvShadow,
         directLiveAccessLog: null,
         directLiveStaticHeaders: null,
+        pingoraEnvShadow: null,
         diagnostics: [
           missingEvidenceDiagnostic(
             '该阶段',
@@ -771,8 +803,10 @@ async function buildAudit(config, discovery) {
         generatedAt: latestSelection.generatedAt,
         requiredDirectLiveAccessLog: requiredAccessLog,
         requiredDirectLiveStaticHeaders: requiredStaticHeaders,
+        requiredPingoraEnvShadow,
         directLiveAccessLog: null,
         directLiveStaticHeaders: null,
+        pingoraEnvShadow: null,
         ambiguousBundleDirs: latestSelection.ambiguousBundleDirs,
         diagnostics: latestSelection.diagnostics,
       });
@@ -784,6 +818,7 @@ async function buildAudit(config, discovery) {
     const manifestCheck = checkPhaseManifest(latest, {
       requiredAccessLog,
       requiredStaticHeaders,
+      requiredPingoraEnvShadow,
     });
     phases.push({
       phase,
@@ -797,8 +832,10 @@ async function buildAudit(config, discovery) {
       summaryStatus: latest.summaryStatus,
       requiredDirectLiveAccessLog: requiredAccessLog,
       requiredDirectLiveStaticHeaders: requiredStaticHeaders,
+      requiredPingoraEnvShadow,
       directLiveAccessLog: latest.summaryDirectLiveAccessLog,
       directLiveStaticHeaders: latest.summaryDirectLiveStaticHeaders,
+      pingoraEnvShadow: latest.summaryPingoraEnvShadow,
       commandName: latest.commandName,
       verify,
       manifestCheck,
@@ -960,6 +997,28 @@ async function buildAudit(config, discovery) {
 }
 
 function buildOperatorSummary(input) {
+  const pingoraEnvShadowEvidence = input.phases
+    .filter((phase) => phase.requiredPingoraEnvShadow)
+    .map((phase) => {
+      const summary = phase.pingoraEnvShadow ?? null;
+      const firstDiagnostic = phase.diagnostics?.[0] ?? null;
+      return {
+        phase: phase.phase,
+        status: phase.status,
+        latestBundleDir: phase.latestBundleDir ?? null,
+        manifestPath: phase.manifestPath ?? null,
+        cutoverRunId: phase.cutoverRunId ?? null,
+        generatedAt: phase.generatedAt ?? null,
+        shadow: {
+          required: true,
+          ok: phase.manifestCheck?.pingoraEnvShadowCheck?.ok === true,
+          reason:
+            phase.manifestCheck?.pingoraEnvShadowCheck?.reason ??
+            firstDiagnostic,
+          summary,
+        },
+      };
+    });
   const directLiveEvidence = input.phases
     .filter(
       (phase) =>
@@ -1058,6 +1117,7 @@ function buildOperatorSummary(input) {
             },
           ]),
     ],
+    pingoraEnvShadowEvidence,
     directLiveEvidence,
     timeline: {
       checked: input.timeline.checked,
@@ -1124,6 +1184,7 @@ function checkPhaseManifest(candidate, options = {}) {
   const {
     requiredAccessLog = false,
     requiredStaticHeaders = false,
+    requiredPingoraEnvShadow = false,
   } = options;
   const diagnostics = [];
   if (candidate.commandName !== null) {
@@ -1152,18 +1213,73 @@ function checkPhaseManifest(candidate, options = {}) {
       `最新阶段证据 manifest.summary.directLiveStaticHeaders 必须包含 direct live 静态响应头摘要：${staticHeadersCheck.reason}`,
     );
   }
+  const pingoraEnvShadowCheck = checkPingoraEnvShadowSummary(
+    candidate.summaryPingoraEnvShadow,
+  );
+  if (requiredPingoraEnvShadow && !pingoraEnvShadowCheck.ok) {
+    diagnostics.push(
+      `最新阶段证据 manifest.summary.pingoraEnvShadow 必须证明 Pingora env 已恢复 shadow：${pingoraEnvShadowCheck.reason}`,
+    );
+  }
   return {
     ok: diagnostics.length === 0,
     expectedSummaryStatus: 'OK',
     actualSummaryStatus: candidate.summaryStatus,
     requiredDirectLiveAccessLog: requiredAccessLog,
     requiredDirectLiveStaticHeaders: requiredStaticHeaders,
+    requiredPingoraEnvShadow,
     directLiveAccessLogCheck: accessLogCheck,
     directLiveStaticHeadersCheck: staticHeadersCheck,
+    pingoraEnvShadowCheck,
     diagnostics,
   };
 }
 
+function checkPingoraEnvShadowSummary(summary) {
+  if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
+    return { ok: false, reason: '字段缺失或不是对象。' };
+  }
+  const failures = [];
+  if (summary.present !== true) {
+    failures.push('present 必须为 true');
+  }
+  if (summary.ok !== true) {
+    failures.push('ok 必须为 true');
+  }
+  if (summary.listen !== '127.0.0.1:18081') {
+    failures.push(
+      `listen 必须是 127.0.0.1:18081，实际为 ${formatNullable(summary.listen)}`,
+    );
+  }
+  if (summary.tlsListen !== '') {
+    failures.push(`tlsListen 必须为空，实际为 ${formatNullable(summary.tlsListen)}`);
+  }
+  if (summary.httpRedirectListen !== '') {
+    failures.push(
+      `httpRedirectListen 必须为空，实际为 ${formatNullable(summary.httpRedirectListen)}`,
+    );
+  }
+  if (summary.tlsCertFile !== '') {
+    failures.push(
+      `tlsCertFile 必须为空，实际为 ${formatNullable(summary.tlsCertFile)}`,
+    );
+  }
+  if (summary.tlsKeyFile !== '') {
+    failures.push(
+      `tlsKeyFile 必须为空，实际为 ${formatNullable(summary.tlsKeyFile)}`,
+    );
+  }
+  if (summary.mode && summary.mode !== 'shadow') {
+    failures.push(`mode 必须是 shadow，实际为 ${formatNullable(summary.mode)}`);
+  }
+  if (summary.shadowReady === false) {
+    failures.push('shadowReady 必须为 true');
+  }
+  return failures.length === 0
+    ? { ok: true, reason: null }
+    : { ok: false, reason: failures.join('；') };
+}
+
 function checkDirectLiveAccessLogSummary(summary) {
   if (!summary || typeof summary !== 'object' || Array.isArray(summary)) {
     return { ok: false, reason: '字段缺失或不是对象。' };
diff --git a/scripts/ops/pingora-cutover-evidence-bundle.mjs b/scripts/ops/pingora-cutover-evidence-bundle.mjs
index c9cb176a8..bdc4c6f4e 100644
--- a/scripts/ops/pingora-cutover-evidence-bundle.mjs
+++ b/scripts/ops/pingora-cutover-evidence-bundle.mjs
@@ -15,6 +15,7 @@ import {
 import path from 'node:path';
 
 const GATEWAY_MODES = new Set(['nginx', 'pingora-direct']);
+const PINGORA_ENV_MODES = new Set(['shadow', 'direct']);
 const BUNDLE_DIR_MODE = 0o750;
 const EVIDENCE_FILE_MODE = 0o640;
 const SECRET_VALUE_FLAGS = new Set([
@@ -73,6 +74,7 @@ if (
 
 const directLiveAccessLog = summarizeDirectLiveAccessLog(directLiveRun);
 const directLiveStaticHeaders = summarizeDirectLiveStaticHeaders(directLiveRun);
+const pingoraEnvShadow = summarizePingoraEnvShadow(snapshotRun);
 const directLiveStatus = directLiveRun
   ? isDirectLiveEvidenceOk(
       directLiveRun,
@@ -106,6 +108,7 @@ const manifest = {
     directLiveExitCode: directLiveRun?.result.code ?? null,
     directLiveAccessLog: directLiveAccessLog?.summary ?? null,
     directLiveStaticHeaders: directLiveStaticHeaders?.summary ?? null,
+    pingoraEnvShadow: pingoraEnvShadow?.summary ?? null,
     criticalCount: snapshotCriticalCount + directLiveCriticalCount,
     warningCount: snapshot.ok
       ? Number(snapshot.value?.summary?.warningCount || 0)
@@ -166,6 +169,85 @@ if (!result.ok) {
   process.exit(1);
 }
 
+function summarizePingoraEnvShadow(snapshotRun) {
+  if (!snapshotRun.parsed.ok) {
+    return {
+      ok: false,
+      summary: {
+        present: false,
+        listen: '',
+        tlsListen: '',
+        httpRedirectListen: '',
+        ok: false,
+        diagnostics: ['snapshot JSON parse failed'],
+      },
+    };
+  }
+
+  const pingoraEnv = snapshotRun.parsed.value?.pingoraEnv;
+  const values = pingoraEnv?.values;
+  if (!values || typeof values !== 'object' || Array.isArray(values)) {
+    return {
+      ok: false,
+      summary: {
+        present: false,
+        listen: '',
+        tlsListen: '',
+        httpRedirectListen: '',
+        ok: false,
+        diagnostics: ['snapshot JSON missing pingoraEnv.values'],
+      },
+    };
+  }
+
+  const summary = {
+    present: true,
+    mode: String(pingoraEnv?.posture?.mode || ''),
+    shadowReady: pingoraEnv?.posture?.shadowReady === true,
+    directReady: pingoraEnv?.posture?.directReady === true,
+    listen: String(values.listen || ''),
+    tlsListen: String(values.tlsListen || ''),
+    httpRedirectListen: String(values.httpRedirectListen || ''),
+    tlsCertFile: String(values.tlsCertFile || ''),
+    tlsKeyFile: String(values.tlsKeyFile || ''),
+    ok: false,
+    diagnostics: [],
+  };
+  if (summary.listen !== '127.0.0.1:18081') {
+    summary.diagnostics.push(
+      `listen 应为 127.0.0.1:18081，实际 ${summary.listen || '-'}`,
+    );
+  }
+  if (summary.tlsListen !== '') {
+    summary.diagnostics.push(
+      `tlsListen 应为空，实际 ${summary.tlsListen}`,
+    );
+  }
+  if (summary.httpRedirectListen !== '') {
+    summary.diagnostics.push(
+      `httpRedirectListen 应为空，实际 ${summary.httpRedirectListen}`,
+    );
+  }
+  if (summary.tlsCertFile !== '') {
+    summary.diagnostics.push(
+      `tlsCertFile 应为空，实际 ${summary.tlsCertFile}`,
+    );
+  }
+  if (summary.tlsKeyFile !== '') {
+    summary.diagnostics.push(
+      `tlsKeyFile 应为空，实际 ${summary.tlsKeyFile}`,
+    );
+  }
+  if (summary.mode && summary.mode !== 'shadow') {
+    summary.diagnostics.push(`mode 应为 shadow，实际 ${summary.mode}`);
+  }
+  if (summary.shadowReady === false) {
+    summary.diagnostics.push('shadowReady 应为 true');
+  }
+  summary.ok = summary.diagnostics.length === 0;
+  return { ok: summary.ok, summary };
+}
+
 function summarizeDirectLiveAccessLog(directLiveRun) {
   if (!directLiveRun) {
     return null;
@@ -453,6 +535,8 @@ function parseArgs(argv) {
       process.env.GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES || '2000',
     expectedGatewayMode:
       process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_GATEWAY_MODE || '',
+    expectedPingoraEnvMode:
+      process.env.GENARRATIVE_PINGORA_EXPECTED_ENV_MODE || '',
     expectedPublicBaseUrl:
       process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_PUBLIC_BASE_URL || '',
     expectedPublicHost:
@@ -541,6 +625,9 @@ function parseArgs(argv) {
       case '--expected-gateway-mode':
         result.expectedGatewayMode = requireValue(argv, ++index, arg);
         break;
+      case '--expected-pingora-env-mode':
+        result.expectedPingoraEnvMode = requireValue(argv, ++index, arg);
+        break;
       case '--expected-public-base-url':
         result.expectedPublicBaseUrl = requireValue(argv, ++index, arg);
         break;
@@ -610,6 +697,8 @@ Options:
   --direct-access-log-since-lines <n>
                                     透传给 direct live smoke 的 access log tail 行数，默认 2000。
   --expected-gateway-mode <mode>    可选，nginx 或 pingora-direct；会透传给状态快照。
+  --expected-pingora-env-mode <mode>
+                                    可选，shadow 或 direct；会透传给状态快照。
   --expected-public-base-url <url>  可选，要求 health-patrol public base URL 与该值一致。
   --expected-public-host <host>     可选，要求 health-patrol public Host 与该值一致。
   --require-empty-public-host       可选，要求 health-patrol public Host 为空。
@@ -650,6 +739,14 @@ function validateConfig(config) {
       `--expected-gateway-mode 只支持 nginx 或 pingora-direct: ${config.expectedGatewayMode}`,
     );
   }
+  if (
+    config.expectedPingoraEnvMode &&
+    !PINGORA_ENV_MODES.has(config.expectedPingoraEnvMode)
+  ) {
+    throw new Error(
+      `--expected-pingora-env-mode 只支持 shadow 或 direct: ${config.expectedPingoraEnvMode}`,
+    );
+  }
   if (config.expectedPublicHost !== null) {
     validateHostOption(config.expectedPublicHost, '--expected-public-host');
   }
@@ -961,6 +1058,9 @@ function buildSnapshotArgs(config) {
     ...(config.expectedGatewayMode
       ? ['--expected-gateway-mode', config.expectedGatewayMode]
       : []),
+    ...(config.expectedPingoraEnvMode
+      ? ['--expected-pingora-env-mode', config.expectedPingoraEnvMode]
+      : []),
     ...(config.expectedPublicBaseUrl
       ? ['--expected-public-base-url', config.expectedPublicBaseUrl]
       : []),
diff --git a/scripts/ops/pingora-cutover-status-snapshot.mjs b/scripts/ops/pingora-cutover-status-snapshot.mjs
index 2ae7bb3d9..5b35b5f5b 100644
--- a/scripts/ops/pingora-cutover-status-snapshot.mjs
+++ b/scripts/ops/pingora-cutover-status-snapshot.mjs
@@ -12,6 +12,7 @@ const STATUS_RANK = {
 };
 
 const GATEWAY_MODES = new Set(['nginx', 'pingora-direct']);
+const PINGORA_ENV_MODES = new Set(['shadow', 'direct']);
 const SERVICES = [
   'genarrative-api.service',
   'spacetimedb.service',
@@ -38,6 +39,7 @@ const RELEASE_ARTIFACTS = [
   'scripts/deploy/pingora-realpath-canary-enable.sh',
   'scripts/deploy/pingora-realpath-canary-disable.sh',
   'scripts/deploy/pingora-health-patrol-env-switch.mjs',
+  'scripts/deploy/pingora-gateway-env-shadow-switch.mjs',
   'deploy/systemd/genarrative-pingora-gateway.service',
   'deploy/systemd/genarrative-pingora-gateway-direct-entry.conf',
   'deploy/nginx/snippets/genarrative-pingora-canary.conf',
@@ -68,6 +70,8 @@ function parseArgs(argv) {
     pingoraEnvFile:
       process.env.GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_ENV_FILE ||
       '/etc/genarrative/pingora-gateway.env',
+    expectedPingoraEnvMode:
+      process.env.GENARRATIVE_PINGORA_EXPECTED_ENV_MODE || '',
     expectedGatewayMode:
       process.env.GENARRATIVE_HEALTH_PATROL_EXPECTED_GATEWAY_MODE || '',
     expectedPublicBaseUrl:
@@ -113,6 +117,9 @@ function parseArgs(argv) {
       case '--pingora-env-file':
         result.pingoraEnvFile = requireValue(argv, ++index, arg);
         break;
+      case '--expected-pingora-env-mode':
+        result.expectedPingoraEnvMode = requireValue(argv, ++index, arg);
+        break;
       case '--expected-gateway-mode':
         result.expectedGatewayMode = requireValue(argv, ++index, arg);
         break;
@@ -177,6 +184,14 @@ function parseArgs(argv) {
       `--expected-gateway-mode 只支持 nginx 或 pingora-direct: ${result.expectedGatewayMode}`,
     );
   }
+  if (
+    result.expectedPingoraEnvMode &&
+    !PINGORA_ENV_MODES.has(result.expectedPingoraEnvMode)
+  ) {
+    throw new Error(
+      `--expected-pingora-env-mode 只支持 shadow 或 direct: ${result.expectedPingoraEnvMode}`,
+    );
+  }
   if (result.expectedPublicHost !== null) {
     validateHostOption(result.expectedPublicHost, '--expected-public-host');
   }
@@ -202,6 +217,8 @@ Options:
   --health-patrol-env-file <path>   health-patrol env 文件，默认 /etc/genarrative/health-patrol.env。
   --pingora-env-file <path>         pingora-gateway env 文件，默认 /etc/genarrative/pingora-gateway.env。
   --expected-gateway-mode <mode>    可选，nginx 或 pingora-direct；提供后会检查 env 和 systemd capability 方向。
+  --expected-pingora-env-mode <mode>
+                                    可选，shadow 或 direct；提供后会检查 active Pingora env 姿态。
   --expected-public-base-url <url>  可选，要求 health-patrol public base URL 与该值一致。
   --expected-public-host <host>     可选，要求 health-patrol public Host 与该值一致。
   --require-empty-public-host       可选，要求 health-patrol public Host 为空。
@@ -402,25 +419,118 @@ async function inspectPingoraEnv(input) {
     return {
       ...parsed,
       values: {},
+      posture: {
+        expectedMode: input.expectedPingoraEnvMode || '',
+        mode: 'unknown',
+        shadowReady: false,
+        directReady: false,
+        diagnostics: parsed.diagnostics || [],
+      },
     };
   }
   const values = parsed.values;
+  const envValues = {
+    listen: values.GENARRATIVE_PINGORA_GATEWAY_LISTEN || '',
+    tlsListen: values.GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN || '',
+    httpRedirectListen:
+      values.GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN || '',
+    tlsCertFile: values.GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE || '',
+    tlsKeyFile: values.GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE || '',
+    forwardedProto:
+      values.GENARRATIVE_PINGORA_GATEWAY_FORWARDED_PROTO || '',
+    trustXForwardedFor:
+      values.GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR || '',
+    trustedFrontProxyConfirmed:
+      values.GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED || '',
+    protectionEnabled:
+      values.GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED || '',
+    instanceCount:
+      values.GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT || '',
+    sharedProtectionConfirmed:
+      values.GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED || '',
+    hasProbeToken: Boolean(values.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN),
+    accessLogFile:
+      values.GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE || '',
+  };
+  const posture = summarizePingoraEnvPosture(
+    envValues,
+    input.expectedPingoraEnvMode,
+  );
+  const diagnostics = [...parsed.diagnostics, ...posture.diagnostics];
+  const status =
+    input.expectedPingoraEnvMode && posture.diagnostics.length > 0
+      ? 'CRITICAL'
+      : parsed.status;
   return {
     path: input.pingoraEnvFile,
-    status: 'OK',
+    status,
     secretValues: collectSecretValuesFromEnv(values),
-    values: {
-      listen: values.GENARRATIVE_PINGORA_GATEWAY_LISTEN || '',
-      tlsListen: values.GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN || '',
-      httpRedirectListen:
-        values.GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN || '',
-      tlsCertFile: values.GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE || '',
-      tlsKeyFile: values.GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE || '',
-      hasProbeToken: Boolean(values.GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN),
-      accessLogFile:
-        values.GENARRATIVE_PINGORA_GATEWAY_ACCESS_LOG_FILE || '',
-    },
-    diagnostics: [],
+    values: envValues,
+    posture,
+    diagnostics,
+  };
+}
+
+function summarizePingoraEnvPosture(values, expectedMode) {
+  const shadowReady =
+    values.listen === '127.0.0.1:18081' &&
+    values.tlsListen === '' &&
+    values.httpRedirectListen === '' &&
+    values.tlsCertFile === '' &&
+    values.tlsKeyFile === '';
+  const directReady =
+    values.tlsListen !== '' &&
+    values.httpRedirectListen !== '' &&
+    values.tlsCertFile !== '' &&
+    values.tlsKeyFile !== '' &&
+    values.forwardedProto === 'https';
+  const mode = directReady ? 'direct' : shadowReady ? 'shadow' : 'mixed';
+  const diagnostics = [];
+
+  if (expectedMode === 'shadow') {
+    if (values.listen !== '127.0.0.1:18081') {
+      diagnostics.push(
+        `Pingora shadow env 要求 listen=127.0.0.1:18081，实际 ${values.listen || '-'}`,
+      );
+    }
+    for (const [label, value] of [
+      ['tlsListen', values.tlsListen],
+      ['httpRedirectListen', values.httpRedirectListen],
+      ['tlsCertFile', values.tlsCertFile],
+      ['tlsKeyFile', values.tlsKeyFile],
+    ]) {
+      if (value !== '') {
+        diagnostics.push(
+          `Pingora shadow env 要求 ${label} 为空，实际 ${value}`,
+        );
+      }
+    }
+  }
+
+  if (expectedMode === 'direct') {
+    for (const [label, value] of [
+      ['tlsListen', values.tlsListen],
+      ['httpRedirectListen', values.httpRedirectListen],
+      ['tlsCertFile', values.tlsCertFile],
+      ['tlsKeyFile', values.tlsKeyFile],
+    ]) {
+      if (value === '') {
+        diagnostics.push(`Pingora direct env 要求 ${label} 已配置。`);
+      }
+    }
+    if (values.forwardedProto !== 'https') {
+      diagnostics.push(
+        `Pingora direct env 要求 forwardedProto=https，实际 ${values.forwardedProto || '-'}`,
+      );
+    }
+  }
+
+  return {
+    expectedMode: expectedMode || '',
+    mode,
+    shadowReady,
+    directReady,
+    diagnostics,
   };
 }
 
diff --git a/server-rs/crates/pingora-gateway/src/main.rs b/server-rs/crates/pingora-gateway/src/main.rs
index b9567f0ff..4978a84c4 100644
--- a/server-rs/crates/pingora-gateway/src/main.rs
+++ b/server-rs/crates/pingora-gateway/src/main.rs
@@ -6,7 +6,7 @@ use std::{
     io::SeekFrom,
     io::Write,
     net::SocketAddr,
-    path::{Component, Path, PathBuf},
+    path::{Path, PathBuf},
     sync::{Arc, Mutex},
     time::{Duration, Instant, SystemTime, UNIX_EPOCH},
 };
@@ -65,6 +65,8 @@ struct GatewayConfig {
     http_redirect_target_scheme: String,
     api_upstream: SocketAddr,
     spacetime_upstream: SocketAddr,
+    gitea_hosts: Vec<String>,
+    gitea_upstream: Option<SocketAddr>,
     web_root: PathBuf,
     acme_root: PathBuf,
     maintenance_file: PathBuf,
@@ -113,6 +115,10 @@ impl GatewayConfig {
                 "GENARRATIVE_PINGORA_GATEWAY_SPACETIME_UPSTREAM",
                 DEFAULT_SPACETIME_UPSTREAM,
             )?,
+            gitea_hosts: read_host_list_env("GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS")?,
+            gitea_upstream: read_optional_socket_addr_env(
+                "GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM",
+            )?,
             web_root: PathBuf::from(read_env_or_default(
                 "GENARRATIVE_PINGORA_GATEWAY_WEB_ROOT",
                 DEFAULT_WEB_ROOT,
@@ -175,6 +181,7 @@ impl GatewayConfig {
                 "GENARRATIVE_PINGORA_GATEWAY_LISTEN 不能与上游地址相同",
             ));
         }
+        self.validate_gitea_config(listen_addr, None, None)?;
 
         let tls_listen_addr = if let Some(tls_listen_addr) = &self.tls_listen_addr {
             let tls_listen_addr = parse_socket_addr_config(
@@ -187,7 +194,9 @@ impl GatewayConfig {
                 listen_addr,
                 self.api_upstream,
                 self.spacetime_upstream,
+                self.gitea_upstream,
             )?;
+            self.validate_gitea_config(listen_addr, Some(tls_listen_addr), None)?;
             validate_tls_file_config(&self.tls_cert_file, &self.tls_key_file)?;
             Some(tls_listen_addr)
         } else if self.tls_cert_file.is_some() || self.tls_key_file.is_some() {
@@ -216,6 +225,7 @@ impl GatewayConfig {
                 listen_addr,
                 self.api_upstream,
                 self.spacetime_upstream,
+                self.gitea_upstream,
             )?;
             if http_redirect_listen_addr == tls_listen_addr {
                 return Err(io::Error::new(
@@ -223,6 +233,11 @@ impl GatewayConfig {
                     "GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN 不能与 TLS_LISTEN 相同",
                 ));
             }
+            self.validate_gitea_config(
+                listen_addr,
+                Some(tls_listen_addr),
+                Some(http_redirect_listen_addr),
+            )?;
             validate_redirect_target_scheme(&self.http_redirect_target_scheme)?;
         }
 
@@ -277,6 +292,60 @@ impl GatewayConfig {
         )?;
         Ok(())
     }
+
+    fn validate_gitea_config(
+        &self,
+        listen_addr: SocketAddr,
+        tls_listen_addr: Option<SocketAddr>,
+        http_redirect_listen_addr: Option<SocketAddr>,
+    ) -> io::Result<()> {
+        for host in &self.gitea_hosts {
+            validate_configured_gateway_host("GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS", host)?;
+        }
+
+        match (self.gitea_hosts.is_empty(), self.gitea_upstream) {
+            (true, Some(_)) => {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "配置 GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM 时必须同时设置 GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS",
+                ));
+            }
+            (false, None) => {
+                return Err(io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    "配置 GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS 时必须同时设置 GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM",
+                ));
+            }
+            _ => {}
+        }
+
+        let Some(gitea_upstream) = self.gitea_upstream else {
+            return Ok(());
+        };
+        if gitea_upstream == self.api_upstream || gitea_upstream == self.spacetime_upstream {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM 不能与 API 或 SpacetimeDB 上游地址相同",
+            ));
+        }
+        if gitea_upstream == listen_addr
+            || Some(gitea_upstream) == tls_listen_addr
+            || Some(gitea_upstream) == http_redirect_listen_addr
+        {
+            return Err(io::Error::new(
+                io::ErrorKind::InvalidInput,
+                "GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM 不能与 Pingora 监听地址相同",
+            ));
+        }
+        Ok(())
+    }
+
+    fn matches_gitea_host(&self, host: Option<&str>) -> bool {
+        let Some(host) = host.and_then(normalize_gateway_host) else {
+            return false;
+        };
+        self.gitea_hosts.iter().any(|candidate| candidate == &host)
+    }
 }
 
 #[derive(Clone, Debug)]
@@ -595,6 +664,7 @@ impl HttpModule for GatewayResponseCompression {
 enum ProxyTarget {
     Api,
     Spacetime,
+    Gitea,
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
@@ -782,11 +852,13 @@ impl RouteDecision {
     fn applies_maintenance_gate(&self) -> bool {
         matches!(
             self,
-            RouteDecision::Proxy { .. }
-                | RouteDecision::Local(LocalResponse::Static {
-                    root: StaticRoot::Web,
-                    ..
-                })
+            RouteDecision::Proxy {
+                target: ProxyTarget::Api | ProxyTarget::Spacetime,
+                ..
+            } | RouteDecision::Local(LocalResponse::Static {
+                root: StaticRoot::Web,
+                ..
+            })
         )
     }
 
@@ -958,6 +1030,8 @@ fn main() -> std::result::Result<(), Box<dyn std::error::Error>> {
         http_redirect_listen = ?config.http_redirect_listen_addr,
         api_upstream = %config.api_upstream,
         spacetime_upstream = %config.spacetime_upstream,
+        gitea_hosts = ?config.gitea_hosts,
+        gitea_upstream = ?config.gitea_upstream,
         web_root = %config.web_root.display(),
         "Pingora shadow gateway 启动"
     );
@@ -1049,7 +1123,8 @@ impl ProxyHttp for GenarrativeGateway {
         Self::CTX: Send + Sync,
     {
         let path = session.req_header().uri.path();
-        ctx.route = self.classify_request_path(path);
+        let host = host_or_authority(session);
+        ctx.route = self.classify_request(host.as_deref(), path);
         apply_configured_body_limit(&mut ctx.route, self.config.max_api_body_bytes);
         ctx.request_id = resolve_request_id(session);
 
@@ -1162,6 +1237,10 @@ impl ProxyHttp for GenarrativeGateway {
         let upstream = match ctx.route.proxy_target().unwrap_or(ProxyTarget::Api) {
             ProxyTarget::Api => self.config.api_upstream,
             ProxyTarget::Spacetime => self.config.spacetime_upstream,
+            ProxyTarget::Gitea => self
+                .config
+                .gitea_upstream
+                .expect("Gitea route requires configured upstream"),
         };
 
         let mut peer = HttpPeer::new(upstream, false, String::new());
@@ -1254,6 +1333,11 @@ impl ProxyHttp for GenarrativeGateway {
         let upstream = match ctx.route.proxy_target() {
             Some(ProxyTarget::Api) => self.config.api_upstream.to_string(),
             Some(ProxyTarget::Spacetime) => self.config.spacetime_upstream.to_string(),
+            Some(ProxyTarget::Gitea) => self
+                .config
+                .gitea_upstream
+                .map(|upstream| upstream.to_string())
+                .unwrap_or_default(),
             None => String::new(),
         };
         let route = format!("{:?}", ctx.route);
@@ -1508,7 +1592,10 @@ fn escape_access_log_value(value: &str) -> String {
 }
 
 fn should_disable_accel_buffering(route: &RouteDecision) -> bool {
-    route.proxy_target() == Some(ProxyTarget::Api)
+    matches!(
+        route.proxy_target(),
+        Some(ProxyTarget::Api | ProxyTarget::Gitea)
+    )
 }
 
 fn is_long_upstream_route(path: &str) -> bool {
@@ -1541,6 +1628,10 @@ fn protection_class_for_route(route: &RouteDecision, path: &str) -> Option<Prote
             target: ProxyTarget::Spacetime,
             ..
         } => Some(ProtectionClass::Spacetime),
+        RouteDecision::Proxy {
+            target: ProxyTarget::Gitea,
+            ..
+        } => None,
         RouteDecision::Local(_) => None,
     }
 }
@@ -1613,6 +1704,7 @@ fn validate_distinct_listen_addr(
     primary_listen_addr: SocketAddr,
     api_upstream: SocketAddr,
     spacetime_upstream: SocketAddr,
+    gitea_upstream: Option<SocketAddr>,
 ) -> io::Result<()> {
     if listen_addr == primary_listen_addr {
         return Err(io::Error::new(
@@ -1621,7 +1713,10 @@ fn validate_distinct_listen_addr(
         ));
     }
 
-    if listen_addr == api_upstream || listen_addr == spacetime_upstream {
+    if listen_addr == api_upstream
+        || listen_addr == spacetime_upstream
+        || Some(listen_addr) == gitea_upstream
+    {
         return Err(io::Error::new(
             io::ErrorKind::InvalidInput,
             format!("{key} 不能与上游地址相同"),
@@ -1704,8 +1799,12 @@ impl GenarrativeGateway {
             .is_some_and(|actual| actual == expected)
     }
 
-    fn classify_request_path(&self, path: &str) -> RouteDecision {
+    fn classify_request(&self, host: Option<&str>, path: &str) -> RouteDecision {
         match self.mode {
+            GatewayMode::Proxy if self.config.matches_gitea_host(host) => RouteDecision::Proxy {
+                target: ProxyTarget::Gitea,
+                body_limit: None,
+            },
             GatewayMode::Proxy => classify_path(path),
             GatewayMode::HttpRedirect => classify_http_redirect_path(path),
         }
@@ -2280,16 +2379,57 @@ fn is_asset_fingerprint(value: &str) -> bool {
 
 fn sanitize_static_path(root: &Path, path: &str) -> Option<PathBuf> {
     let mut result = root.to_path_buf();
-    for component in Path::new(path.trim_start_matches('/')).components() {
-        match component {
-            Component::Normal(value) => result.push(value),
-            Component::CurDir => {}
-            Component::Prefix(_) | Component::RootDir | Component::ParentDir => return None,
+    for raw_segment in path.trim_start_matches('/').split('/') {
+        if raw_segment.is_empty() {
+            continue;
+        }
+
+        let segment = decode_static_path_segment(raw_segment)?;
+        match segment.as_str() {
+            "." => continue,
+            ".." => return None,
+            _ => result.push(segment),
         }
     }
     Some(result)
 }
 
+fn decode_static_path_segment(segment: &str) -> Option<String> {
+    let bytes = segment.as_bytes();
+    let mut decoded = Vec::with_capacity(bytes.len());
+    let mut index = 0;
+
+    while index < bytes.len() {
+        if bytes[index] == b'%' {
+            let high = *bytes.get(index + 1)?;
+            let low = *bytes.get(index + 2)?;
+            let value = decode_percent_hex(high)? << 4 | decode_percent_hex(low)?;
+            if value == b'/' || value == b'\\' || value == b'\0' {
+                return None;
+            }
+            decoded.push(value);
+            index += 3;
+        } else {
+            if bytes[index] == b'\\' || bytes[index] == b'\0' {
+                return None;
+            }
+            decoded.push(bytes[index]);
+            index += 1;
+        }
+    }
+
+    String::from_utf8(decoded).ok()
+}
+
+fn decode_percent_hex(byte: u8) -> Option<u8> {
+    match byte {
+        b'0'..=b'9' => Some(byte - b'0'),
+        b'a'..=b'f' => Some(byte - b'a' + 10),
+        b'A'..=b'F' => Some(byte - b'A' + 10),
+        _ => None,
+    }
+}
+
 async fn is_regular_file(path: &Path) -> bool {
     tokio::fs::metadata(path)
         .await
@@ -2745,6 +2885,80 @@ fn read_socket_addr_env(key: &str, default_value: &str) -> io::Result<SocketAddr
     })
 }
 
+fn read_optional_socket_addr_env(key: &str) -> io::Result<Option<SocketAddr>> {
+    read_optional_env(key)
+        .map(|value| {
+            value.parse().map_err(|error| {
+                io::Error::new(
+                    io::ErrorKind::InvalidInput,
+                    format!("{key} 不是有效 socket 地址 {value:?}：{error}"),
+                )
+            })
+        })
+        .transpose()
+}
+
+fn read_host_list_env(key: &str) -> io::Result<Vec<String>> {
+    let Some(raw) = read_optional_env(key) else {
+        return Ok(Vec::new());
+    };
+    let mut result = Vec::new();
+    for value in raw
+        .split(',')
+        .map(str::trim)
+        .filter(|value| !value.is_empty())
+    {
+        let host = normalize_gateway_host(value).ok_or_else(|| {
+            io::Error::new(
+                io::ErrorKind::InvalidInput,
+                format!("{key} 包含无效 Host：{value:?}"),
+            )
+        })?;
+        if !result.contains(&host) {
+            result.push(host);
+        }
+    }
+    Ok(result)
+}
+
+fn normalize_gateway_host(value: &str) -> Option<String> {
+    let value = value.trim();
+    if value.is_empty() || value.contains(['/', '\\', '\n', '\r', '\0']) {
+        return None;
+    }
+    if value.starts_with('[') {
+        return None;
+    }
+    let host = value
+        .rsplit_once(':')
+        .and_then(|(host, port)| {
+            (!port.is_empty() && port.bytes().all(|byte| byte.is_ascii_digit())).then_some(host)
+        })
+        .unwrap_or(value)
+        .trim_end_matches('.');
+    if host.is_empty() || host.len() > 253 {
+        return None;
+    }
+    if !host
+        .bytes()
+        .all(|byte| byte.is_ascii_alphanumeric() || matches!(byte, b'.' | b'-'))
+    {
+        return None;
+    }
+    Some(host.to_ascii_lowercase())
+}
+
+fn validate_configured_gateway_host(key: &str, host: &str) -> io::Result<()> {
+    if normalize_gateway_host(host).as_deref() == Some(host) {
+        return Ok(());
+    }
+
+    Err(io::Error::new(
+        io::ErrorKind::InvalidInput,
+        format!("{key} 包含无效 Host：{host:?}"),
+    ))
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -2845,6 +3059,7 @@ mod tests {
         match target {
             ProxyTarget::Api => "api",
             ProxyTarget::Spacetime => "spacetime",
+            ProxyTarget::Gitea => "gitea",
         }
     }
 
@@ -2885,6 +3100,8 @@ mod tests {
             http_redirect_target_scheme: "https".to_string(),
             api_upstream: "127.0.0.1:8082".parse().unwrap(),
             spacetime_upstream: "127.0.0.1:3101".parse().unwrap(),
+            gitea_hosts: Vec::new(),
+            gitea_upstream: None,
             web_root: PathBuf::from("/srv/genarrative/web"),
             acme_root: PathBuf::from("/var/www/html"),
             maintenance_file: PathBuf::from("/var/lib/genarrative/maintenance/enabled"),
@@ -2977,6 +3194,106 @@ mod tests {
         let mut gallery = classify_path("/api/runtime/puzzle/gallery");
         apply_configured_body_limit(&mut gallery, 1024);
         assert_eq!(gallery.body_limit(), None);
+
+        let mut gitea = RouteDecision::Proxy {
+            target: ProxyTarget::Gitea,
+            body_limit: None,
+        };
+        apply_configured_body_limit(&mut gitea, 1024);
+        assert_eq!(gitea.body_limit(), None);
+    }
+
+    #[test]
+    fn routes_configured_gitea_hosts_to_gitea_upstream() {
+        let config = GatewayConfig {
+            gitea_hosts: vec!["git.genarrative.world".to_string()],
+            gitea_upstream: Some("127.0.0.1:3000".parse().unwrap()),
+            ..test_gateway_config()
+        };
+        let gateway = GenarrativeGateway {
+            config: Arc::new(config),
+            protection: Arc::new(GatewayProtection::new(test_gateway_config().protection)),
+            mode: GatewayMode::Proxy,
+        };
+
+        let route = RouteDecision::Proxy {
+            target: ProxyTarget::Gitea,
+            body_limit: None,
+        };
+        assert_eq!(
+            gateway.classify_request(Some("git.genarrative.world"), "/"),
+            route
+        );
+        assert_eq!(
+            gateway.classify_request(Some("git.genarrative.world:443"), "/api/v1/repos"),
+            route
+        );
+        assert_eq!(
+            gateway.classify_request(Some("GIT.GENARRATIVE.WORLD"), "/assets/app.js"),
+            route
+        );
+        assert_eq!(
+            gateway.classify_request(Some("dev.genarrative.world"), "/api/creation-entry/config"),
+            classify_path("/api/creation-entry/config")
+        );
+    }
+
+    #[test]
+    fn gitea_routes_bypass_maintenance_body_limit_and_protection() {
+        let route = RouteDecision::Proxy {
+            target: ProxyTarget::Gitea,
+            body_limit: None,
+        };
+
+        assert!(!route.applies_maintenance_gate());
+        assert!(!route.is_api_like());
+        assert_eq!(route.body_limit(), None);
+        assert_eq!(protection_class_for_route(&route, "/api/v1/repos"), None);
+        assert!(should_disable_accel_buffering(&route));
+    }
+
+    #[test]
+    fn normalizes_gateway_hosts_for_matching() {
+        assert_eq!(
+            normalize_gateway_host("Git.Genarrative.World:443"),
+            Some("git.genarrative.world".to_string())
+        );
+        assert_eq!(
+            normalize_gateway_host("git.genarrative.world."),
+            Some("git.genarrative.world".to_string())
+        );
+        assert!(normalize_gateway_host("git.genarrative.world/path").is_none());
+        assert!(normalize_gateway_host("[::1]:3000").is_none());
+        assert!(normalize_gateway_host("bad\r\nhost").is_none());
+    }
+
+    #[test]
+    fn validates_gitea_host_routing_config() {
+        let config = GatewayConfig {
+            gitea_hosts: vec!["git.genarrative.world".to_string()],
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            gitea_upstream: Some("127.0.0.1:3000".parse().unwrap()),
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            gitea_hosts: vec!["git.genarrative.world".to_string()],
+            gitea_upstream: Some("127.0.0.1:8082".parse().unwrap()),
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_err());
+
+        let config = GatewayConfig {
+            gitea_hosts: vec!["git.genarrative.world".to_string()],
+            gitea_upstream: Some("127.0.0.1:3000".parse().unwrap()),
+            ..test_gateway_config()
+        };
+        assert!(config.validate().is_ok());
     }
 
     #[test]
@@ -3576,6 +3893,22 @@ mod tests {
     fn rejects_path_traversal_for_static_files() {
         assert!(sanitize_static_path(Path::new("/srv/web"), "/assets/app.js").is_some());
         assert!(sanitize_static_path(Path::new("/srv/web"), "/assets/../secret").is_none());
+        assert!(sanitize_static_path(Path::new("/srv/web"), "/assets/%2e%2e/secret").is_none(),);
+        assert!(sanitize_static_path(Path::new("/srv/web"), "/assets%2fsecret").is_none());
+        assert!(sanitize_static_path(Path::new("/srv/web"), "/assets/%GG").is_none());
+    }
+
+    #[test]
+    fn decodes_percent_encoded_static_path_segments() {
+        assert_eq!(
+            sanitize_static_path(
+                Path::new("/srv/web"),
+                "/Icons/Admurin%27s%20Pixel%20Items/General/Singles/499_Iron_Gear.png",
+            ),
+            Some(PathBuf::from(
+                "/srv/web/Icons/Admurin's Pixel Items/General/Singles/499_Iron_Gear.png",
+            )),
+        );
     }
 
     #[test]