ci: harden maintenance and api deploy checkout

deploy/nginx/genarrative-dev-http.conf

@@ -77,6 +77,10 @@ server {
 
     # 仅开放前端 SpacetimeDB SDK 运行所需的最小公网路由。
     location ~ ^/v1/database/[^/]+/subscribe$ {
+        if ($genarrative_maintenance) {
+            return 503;
+        }
+
         proxy_pass http://127.0.0.1:3101;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
@@ -86,6 +90,10 @@ server {
     }
 
     location ^~ /v1/identity {
+        if ($genarrative_maintenance) {
+            return 503;
+        }
+
         proxy_pass http://127.0.0.1:3101;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;

deploy/nginx/genarrative.conf

@@ -91,6 +91,10 @@ server {
 
     # SpacetimeDB 只开放 TypeScript SDK 运行所需的最小公网路由。
     location ~ ^/v1/database/[^/]+/subscribe$ {
+        if ($genarrative_maintenance) {
+            return 503;
+        }
+
         proxy_pass http://127.0.0.1:3101;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
@@ -100,6 +104,10 @@ server {
     }
 
     location ^~ /v1/identity {
+        if ($genarrative_maintenance) {
+            return 503;
+        }
+
         proxy_pass http://127.0.0.1:3101;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;

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 访问运行时数据。
 - 静态资源仍允许访问，避免维护页样式和资源加载失败。
 - 发布成功后自动解除维护模式。
 - 发布失败时保持维护模式，并通过邮件通知人工处理。

jenkins/Jenkinsfile.production-api-deploy

@@ -73,12 +73,17 @@ pipeline {
           extensions: [[$class: 'CleanBeforeCheckout']],
           userRemoteConfigs: [[url: "${GIT_REMOTE_URL}"]],
         ])
+        script {
+          if (params.COMMIT_HASH?.trim()) {
+            echo "API 发布脚本 checkout 将忽略上游构建 commit=${params.COMMIT_HASH}，改用 ${params.SOURCE_BRANCH ?: 'master'} 最新提交，避免发布阶段回退到旧部署脚本。构建产物仍由 BUILD_NUMBER_TO_DEPLOY 决定。"
+          }
+        }
         sh '''
           bash -lc '
             set -euo pipefail
             chmod +x scripts/jenkins-checkout-source.sh
             SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
-            COMMIT_HASH="${COMMIT_HASH:-}" \
+            COMMIT_HASH="" \
             GIT_REMOTE_URL="${GIT_REMOTE_URL}" \
             SOURCE_COMMIT_FILE=".jenkins-source-commit" \
             scripts/jenkins-checkout-source.sh