docs(deploy): document production runtime image gate

docs/DEPLOYMENT.md

@@ -34,6 +34,9 @@
 - Production DB/Redis 独立于 staging：`xiaoxia-postgres-production:5432`、`xiaoxia-redis-production:6379`
 - 宿主端口：Postgres `5433`、Redis `6380`、API `8001`、Web `3002`
 - 只允许通过 tag/release 触发生产应用部署
+- API/Worker 必须来自专用构建机或 CI 产出的 runtime image tar：`/var/lib/xiaoxia-saas-production/runtime-images-<tag>.tar`
+- 生产机只能 `docker load` runtime image tar、构建轻量 Web nginx artifact、执行迁移和重启容器
+- 禁止在生产机上构建 API/Worker 镜像；当前生产机资源为 2 核/约 1.7GiB 内存，且承载 Gitea/Web/API/DB/Redis/Worker，不是构建机
 - 必须替换所有密钥和 `CHANGE_ME` 项
 
 ---
@@ -107,6 +110,10 @@ Staging 当前可以保持 no-op；Production 开启前必须先验证 SMTP/Redi
 - Actions 先同步代码到 `/var/lib/xiaoxia-saas-staging/repo`。
 - Actions 再复制 `/var/lib/xiaoxia-saas-staging/.env` 到部署工作目录。
 - Actions 最终调用 `infra/docker/deploy-staging.sh`。
+- Production tag deploy 会传入 `RELEASE_VERSION=${GITHUB_REF_NAME}`。
+- Production deploy 必须先上传 runtime image tar；缺少 tar 时 `infra/docker/deploy-production.sh` 必须失败，防止代码已更新但 API/Worker 仍运行旧镜像。
+- API/Worker runtime image tar 构建命令：`scripts/build_release_images.sh <tag>`。
+- runtime image tar 生产部署入口：`scripts/deploy_release_images_production.sh <tag> <tar>` 或由 tag deploy 调用 `infra/docker/deploy-production.sh` 加载 `/var/lib/xiaoxia-saas-production/runtime-images-<tag>.tar`。
 
 ---
 
@@ -118,3 +125,4 @@ Staging 当前可以保持 no-op；Production 开启前必须先验证 SMTP/Redi
 - OSS、数据库、Redis、JWT 密钥必须通过服务器环境文件注入。
 - 生产环境必须设置 `DEBUG=false`。
 - staging / production 不允许开启 `AUTO_CREATE_SCHEMA` 绕过 Alembic。
+- 生产机禁止构建 API/Worker runtime 镜像；如发现需要构建，先补构建机/CI 产物流程，不得临时开启生产构建。

tests/unit/test_release_scripts.py

@@ -154,6 +154,15 @@ def test_subscription_api_is_not_wired_to_ui_until_backend_exists():
     assert importers == []
 
 
+def test_deployment_docs_forbid_production_runtime_builds():
+    docs = Path("docs/DEPLOYMENT.md").read_text(encoding="utf-8")
+
+    assert "runtime-images-<tag>.tar" in docs
+    assert "禁止在生产机上构建 API/Worker 镜像" in docs
+    assert "不是构建机" in docs
+    assert "缺少 tar 时 `infra/docker/deploy-production.sh` 必须失败" in docs
+
+
 def test_runtime_image_release_scripts_keep_builds_off_production():
     build_script = Path("scripts/build_release_images.sh").read_text(encoding="utf-8")
     deploy_script = Path("scripts/deploy_release_images_production.sh").read_text(encoding="utf-8")