ci: harden maintenance and api deploy checkout

docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md

@@ -95,6 +95,8 @@
 
 全量发布流水线的 `DATABASE` 参数必须同时传给 Stdb 发布和 API 发布：Stdb 发布负责把 wasm 发布到目标数据库，API 发布必须在重启 `genarrative-api.service` 前把同一个库名写入 `/etc/genarrative/api-server.env` 的 `GENARRATIVE_SPACETIME_DATABASE`，并同步 `GENARRATIVE_SPACETIME_SERVER_URL`。否则 api-server 会继续读取环境文件中的旧库名，出现 wasm 已发布到新库但 HTTP facade 仍访问旧库的错位。
 
+API 发布阶段只使用上游 API 构建产物，不应回退到上游源码 commit 执行部署脚本；部署脚本应始终取 `SOURCE_BRANCH` 最新提交。否则全量流水线在修复部署脚本后仍可能按旧 `COMMIT_HASH` checkout，继续执行不认识新参数的旧版 `production-api-deploy.sh`。
+
 ## Nginx 规则
 
 生产正式入口只保留必要路由：
@@ -134,6 +136,7 @@ Nginx 配置文件分为两类：
 - `api-server` 发布、SpacetimeDB 模块发布、数据库导入、服务器配置变更必须进入维护模式。
 - 普通页面在维护模式下展示 `/maintenance.html`。
 - `/admin/api/*` 在维护模式下返回 503。
+- `/v1/database/<database>/subscribe` 与 `/v1/identity` 在维护模式下返回 503，阻断已打开前端继续通过 SpacetimeDB SDK 访问运行时数据。
 - 静态资源仍允许访问，避免维护页样式和资源加载失败。
 - 发布成功后自动解除维护模式。
 - 发布失败时保持维护模式，并通过邮件通知人工处理。