deploy/nginx/genarrative-dev-http.conf

@@ -48,8 +48,30 @@ server {
         try_files $uri =404;
     }
 
-    # 开发服也不恢复旧一体化 API、生成资源代理和健康检查公网入口。
-    location ~ ^/(api|generated-|healthz) {
+    # 临时兼容主站仍在使用的 /api/* HTTP facade；前端完成 SpacetimeDB SDK 迁移后删除。
+    location ~ ^/api(?:/|$) {
+        default_type application/json;
+
+        if ($genarrative_maintenance) {
+            return 503 '{"ok":false,"error":{"code":"MAINTENANCE","message":"服务维护中"}}';
+        }
+
+        proxy_pass http://127.0.0.1:8082;
+        proxy_http_version 1.1;
+        proxy_buffering off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        add_header X-Accel-Buffering no always;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Request-Id $request_id;
+    }
+
+    # 开发服仍不恢复旧生成资源代理和健康检查公网入口。
+    location ~ ^/(generated-|healthz) {
         return 404;
     }
 

deploy/nginx/genarrative.conf

@@ -62,8 +62,30 @@ server {
         try_files $uri =404;
     }
 
-    # 生产公网不再暴露旧一体化 API、生成资源代理和健康检查入口。
-    location ~ ^/(api|generated-|healthz) {
+    # 临时兼容主站仍在使用的 /api/* HTTP facade；前端完成 SpacetimeDB SDK 迁移后删除。
+    location ~ ^/api(?:/|$) {
+        default_type application/json;
+
+        if ($genarrative_maintenance) {
+            return 503 '{"ok":false,"error":{"code":"MAINTENANCE","message":"服务维护中"}}';
+        }
+
+        proxy_pass http://127.0.0.1:8082;
+        proxy_http_version 1.1;
+        proxy_buffering off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        add_header X-Accel-Buffering no always;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header X-Forwarded-Host $host;
+        proxy_set_header X-Request-Id $request_id;
+    }
+
+    # 生产公网不再暴露旧生成资源代理和健康检查入口。
+    location ~ ^/(generated-|healthz) {
         return 404;
     }
 

docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md

@@ -43,9 +43,9 @@
 
 ## 生产架构
 
-- Nginx 作为唯一公网入口，负责 HTTPS、静态站点、后台静态页面、维护页与 `/admin/api/` 反向代理。
+- Nginx 作为唯一公网入口，负责 HTTPS、静态站点、后台静态页面、维护页、`/admin/api/` 反向代理，以及临时兼容期的主站 `/api/*` 反向代理。
 - SpacetimeDB 作为系统服务运行，监听 `127.0.0.1:3101`，数据根目录为 `/stdb`。`3000` 保留给部署机本机 Git/Web 服务，禁止再让 SpacetimeDB 占用该端口。
-- Rust `api-server` 作为系统服务运行，监听 `127.0.0.1:8082`，只被 Nginx 的 `/admin/api/` 访问。
+- Rust `api-server` 作为系统服务运行，监听 `127.0.0.1:8082`。当前临时兼容期仍允许 Nginx 将主站 `/api/*` 与 `/admin/api/` 反向代理到该服务；前端完成 SpacetimeDB SDK / bindings 直连迁移后，再删除公网 `/api/*` 反代。
 - 主站与后台前端构建为静态文件，发布到服务器固定目录，不放入 Jenkins 目录，也不跟随 Docker 镜像。
 - 除网站静态发布外，`api-server` 发布、SpacetimeDB 模块发布、数据库导入、服务器配置变更都必须先进入维护模式。
 
@@ -100,22 +100,24 @@
 - `/`：主站静态页面。
 - `/admin/`：后台前端静态页面，后台构建时使用 `/admin/` 作为 base path。
 - `/admin/api/`：反向代理到 `http://127.0.0.1:8082/admin/api/`。
+- `/api` 与 `/api/*`：临时反向代理到 `http://127.0.0.1:8082`，保留原始请求 URI，用于兼容当前主站前端仍在使用的 HTTP facade。
 - HTTP 到 HTTPS：`production-https` 模式只保留 301 重定向。
 - `/maintenance.html`：维护中页面。
 
-移除这些公网反向代理：
+当前仍需移除这些公网反向代理：
 
-- `/api/*`
 - `/generated-*`
 - 公网 `/healthz`
 - 其他旧的一体化 web server 代理入口。
 
+`/api/*` 仅作为临时兼容债务保留，不代表生产长期 API 暴露策略。后续主站前端完成 SpacetimeDB SDK / bindings 接入后，必须从 Nginx 模板中删除 `/api` 与 `/api/*` 反代，并恢复其公网 404 行为。
+
 SpacetimeDB 公网路由默认保持收敛，只按实际前端 SDK 需要暴露最小集合。禁止开放可远程发布数据库或管理实例的通用入口。
 
 Nginx 配置文件分为两类：
 
 - `deploy/nginx/genarrative.conf`：生产正式域名 HTTPS 配置，`genarrative.example.com` 只是占位域名，安装时必须替换为真实 `SERVER_NAME`，并要求 `/etc/letsencrypt/live/<SERVER_NAME>/fullchain.pem` 与 `privkey.pem` 已存在。
-- `deploy/nginx/genarrative-dev-http.conf`：开发服无域名时的 HTTP-only 配置，只允许 `DEPLOY_TARGET=development` 使用。没有域名时，`SERVER_NAME` 填开发机 IP 或临时主机名。它仍复用同一套静态目录、后台 API 反代和 SpacetimeDB SDK 最小公网路由，不恢复旧 `/api/*`、`/generated-*` 或公网 `/healthz`。
+- `deploy/nginx/genarrative-dev-http.conf`：开发服无域名时的 HTTP-only 配置，只允许 `DEPLOY_TARGET=development` 使用。没有域名时，`SERVER_NAME` 填开发机 IP 或临时主机名。它仍复用同一套静态目录、后台 API 反代、临时主站 `/api/*` 反代和 SpacetimeDB SDK 最小公网路由，不恢复旧 `/generated-*` 或公网 `/healthz`。
 
 ## 维护模式