# Genarrative Nginx compression policy

本配置片段由 `scripts/jenkins-server-provision.sh` 在安装 Nginx 站点配置时展开。

## 请求体大小

- 生产、开发服和容器模板都在通用 `location ~ ^/api(?:/|$)` 内设置 `client_max_body_size 64m`。
- 该值只用于让携带参考图 Data URL 的创作接口抵达 `api-server`；不要把它当作业务上传上限。Rust 路由仍通过 `DefaultBodyLimit` 和解码后字节校验限制具体接口，例如拼图参考图路由只放宽到 12 MiB 请求体，图片字节继续按业务规则拒绝。
- 若线上看到 `413 Request Entity Too Large`，并且 access log 里 `request_time=0.000 upstream_status=-`，通常是 Nginx 没有加载该模板或未 reload；先执行 `nginx -T | grep client_max_body_size` 和 `nginx -t` 再检查 `api-server`。

## gzip

- `deploy/nginx/genarrative.conf` 与 `deploy/nginx/genarrative-dev-http.conf` 默认开启 gzip。
- 覆盖 `application/json`，用于降低 `/api/runtime/*/gallery` 这类 JSON 列表接口的公网带宽占用。
- 当前推荐等级为 `gzip_comp_level 5`，兼顾 2C/2G 服务器 CPU 与压缩收益。
- Pingora 影子网关已通过 `GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED=true`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL=5` 与 `GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=1024` 承接 gzip parity；网关会把压缩算法收敛到 gzip allowlist，并按 `gzip_min_length 1024` 避免压缩小响应，同时沿用 Nginx `gzip_types` 边界不压缩图片资源。改动后必须运行 `npm run check:pingora-gateway-smoke` 验证小响应不压缩、图片资源不压缩，以及 `Accept-Encoding: gzip` 和 `Accept-Encoding: br, gzip` 的大响应都返回 gzip。

## Brotli

- Brotli 只在目标服务器 Nginx 接受 brotli 指令时开启。
- Pingora 当前正式化口径固定为 gzip-only，不承接 Brotli；做 Nginx -> Pingora canary 时，Brotli 仍由 Nginx 或更前置代理决定是否启用。直连 Pingora 时，不把 Brotli parity 作为切换门禁，避免使用 Pingora 0.8.1 里尚未通过可解压端到端验证的 Brotli compressor 路径。
- Ubuntu / apt 系统的 `Genarrative-Server-Provision` 会安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`；非 apt 系统暂不自动安装，仍按下面的能力探测结果决定是否启用。
- Provision 脚本通过临时配置执行 `nginx -t` 做能力探测；探测配置会先 `include /etc/nginx/modules-enabled/*.conf`，避免 Ubuntu 动态模块已安装但测试配置未加载模块导致误判。可用时把模板中的 `# __GENARRATIVE_BROTLI_DIRECTIVES__` 替换为 brotli 指令，不可用时保留注释说明。
- 不要直接在静态模板里无条件写 `brotli on;`，否则没有 brotli 模块的服务器会 `nginx -t` 失败并回滚。
- 不要用 `nginx -V | grep brotli` 判断 brotli 是否可用；Ubuntu apt 安装的 brotli 是动态模块，不会出现在普通编译参数里。应检查包、`/etc/nginx/modules-enabled/` 的 `load_module` 配置，或用包含 `include /etc/nginx/modules-enabled/*.conf` 的临时配置执行 `nginx -t`。

## Pingora upstream timeouts

- Pingora 影子网关已显式配置上游连接 / 读 / 写 timeout，避免正式 canary 时依赖 Pingora 默认值。
- 默认连接超时为 `3000ms`；没有 Nginx 显式长超时的代理路由读取超时为 `60s`。
- 通用 `/api`、公开列表 / 详情和 SpacetimeDB subscribe 读取超时为 `3600s`，写上游超时为 `3600s`，对齐当前 Nginx `proxy_read_timeout` / `proxy_send_timeout` 口径。
- 超时会返回 JSON `504 GATEWAY_UPSTREAM_TIMEOUT`，由 `npm run check:pingora-gateway-smoke` 覆盖。

## Pingora static cache policy

- Pingora 直连静态响应会显式写入 `Cache-Control`，避免公网入口切换后 HTML 入口页或 Vite 指纹资源依赖框架默认头。
- 默认 `GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL=no-cache`，覆盖 `index.html`、`admin/index.html`、目录 index 和 SPA fallback。
- 默认 `GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL=public, max-age=31536000, immutable`，只覆盖 `/assets/*` 与 `/admin/assets/*` 中带 Vite 指纹文件名的资源；非指纹静态和 ACME challenge 默认 `GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL=no-cache`。
- Pingora 静态响应同时写入弱 `ETag`、`Last-Modified` 与 `Accept-Ranges: bytes`，并对 `If-None-Match` / `If-Modified-Since` 返回 `304`；这层只负责浏览器协商缓存，不改变上面的 `Cache-Control` 分档。
- Pingora 静态文件支持单段 `Range: bytes=`：合法范围返回 `206` 与 `Content-Range`，越界范围返回 `416` 与 `Content-Range: bytes */<len>`，`HEAD + Range` 只返回头。多段 range 暂按完整文件返回，不启用 multipart 响应。`If-Range` 日期匹配时继续返回局部内容，日期旧于文件或弱 ETag 校验器时回完整 `200`。`206` / `304` / `416` 均不做 gzip 压缩，避免局部内容语义和 `Content-Range` 漂移。
- Pingora 静态路由只允许 `GET` / `HEAD`。非读取方法命中静态候选时返回 `405` 与 `Allow: GET, HEAD`；缺失文件仍返回 `404`，避免错误客户端把静态入口当作可写接口。
- `npm run check:pingora-gateway-smoke` 会用固定 `X-Request-Id` 对账静态 `304` / `405` / `206` / `416` 的 Pingora access log 行，并同时校验 method / path / status；该 smoke 还会让 direct live 自动发现首页里的普通静态资源和 Vite 指纹资源，确认指纹资源 GET / HEAD / `If-None-Match` 304 / `Range: bytes=0-0` 以及 `public, max-age=31536000, immutable` 缓存头，确保本地静态响应状态和指纹 chunk 长缓存都可进入直连切换证据链。direct live JSON 只给静态 GET / HEAD / 304 / Range 写入白名单 `headers`，包括 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`，便于证据包归档后复盘静态缓存与 Range 响应头。

## Pingora TLS / redirect

- 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` 精确读取。
- 同一公网 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`，证明 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 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` 反查结果，以及静态响应头白名单证据。`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`、`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

- `deploy/nginx/snippets/genarrative-pingora-canary.conf` 是默认不启用的人工前缀 canary 入口，只在需要验证 Nginx -> Pingora handoff 时临时 include。它使用 `/__genarrative_pingora_canary/` 前缀改写后转发到 `127.0.0.1:18081`，并返回 `X-Genarrative-Nginx-Handoff: pingora-canary`。
- `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 是前缀 canary 之后、direct 直连之前的真实路径 canary。它只能在 Nginx `http` 上下文人工 include，默认监听 `127.0.0.1:18083`，覆盖 `/api/creation-entry/config`、`/v1/identity`、`/v1/database/<db>/subscribe`、`/assets/app.js` 和拒绝入口，并写入独立 `/var/log/nginx/genarrative-pingora-realpath-canary.access.log`；不要把它 include 到生产 `443` server 内作为 location 覆盖。
- 真实路径 canary 片段使用 `access_log ... genarrative_upstream`，如果以独立文件放入 `/etc/nginx/conf.d/`，文件加载顺序必须晚于定义 `log_format genarrative_upstream` 的主站配置。当前目标机可使用 `/etc/nginx/conf.d/zz-genarrative-pingora-realpath-canary.conf`；若站点把 `log_format` 移到全局 Nginx 配置，则需确保它仍在所有 `conf.d` server include 之前加载。启用前必须先跑 `nginx -t`，不要用会早于 `genarrative.conf` 加载的文件名。
- 启用 Nginx canary 前，目标机必须已经有持久 `genarrative-pingora-gateway.service` 运行在 `127.0.0.1:18081`，且带真实 `api-server`、SpacetimeDB、静态目录和 `/var/log/genarrative/pingora-gateway.access.log` 完成本机 shadow 验收；不要从一次性 `/tmp` 网关进程直接切到 Nginx handoff。
- 启用前必须运行 `npm run check:nginx-pingora-canary`；目标 agent 有 Nginx 时运行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`，同时做两个 snippet 的静态护栏和真实 `nginx -t`。本机或 CI 可运行 `npm run check:pingora-canary-docker`，用 Docker Nginx、真实 Pingora 和 mock 上游复现前缀 canary 与真实路径 canary 两条 handoff 链路。
- 前缀 canary reload 后运行 `GENARRATIVE_PINGORA_CANARY_BASE_URL=http://127.0.0.1 GENARRATIVE_PINGORA_CANARY_HOST=<域名> npm run check:pingora-canary-live`，再用 `scripts/check-pingora-canary-access-log-parity.mjs` 对账 `/var/log/nginx/genarrative.access.log` 与 `/var/log/genarrative/pingora-gateway.access.log`。
- 真实路径 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 / 构建环境跑聚合门禁，并按目标机已启用的 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，只允许端口不同。

## 验证

```bash
dpkg -l 'libnginx-mod-http-brotli-*'
ls -l /etc/nginx/modules-enabled/*brotli*
nginx -T 2>/dev/null | grep -Ei 'brotli|load_module'

curl -sSI -H 'Accept-Encoding: gzip' \
  http://<host>/api/runtime/puzzle/gallery \
  | grep -iE 'content-encoding|vary|content-type|content-length'

curl -sSI -H 'Accept-Encoding: br' \
  http://<host>/api/runtime/puzzle/gallery \
  | grep -iE 'content-encoding|vary|content-type|content-length'
```

预期：

- gzip 可用时返回 `Content-Encoding: gzip`。
- br 可用时返回 `Content-Encoding: br`。
- 响应头应包含 `Vary: Accept-Encoding`。