更新生产部署配置，调整工作流以支持 prod 分支，移除不再使用的数据库网络变量，并优化文档说明

.gitea/workflows/deploy-production.yaml

@@ -1,13 +1,15 @@
 name: Deploy production
 on:
   push:
-    branches: [main]
+    branches: [prod]
   workflow_dispatch:
 
 jobs:
   deploy:
-    # Reuse the runner that deploys zhixing-system to the same Docker host.
+    # Manual runs must also select prod before receiving production credentials.
-    runs-on: ubuntu-latest
+    if: ${{ github.ref == 'refs/heads/prod' }}
+    # Match the label of tencent-prod-runner on server B, not its runner name.
+    runs-on: tencent-prod
     steps:
       - name: Checkout
         uses: https://github.com/actions/checkout@v4
@@ -22,7 +24,6 @@ jobs:
           WQ_PASSWORD: ${{ secrets.WQ_PASSWORD }}
           ENCRYPTION_KEY: ${{ secrets.ENCRYPTION_KEY }}
           ADMIN_USERNAME: ${{ vars.ADMIN_USERNAME }}
-          DATABASE_NETWORK: ${{ vars.DATABASE_NETWORK }}
           PUBLIC_ORIGIN: ${{ vars.PUBLIC_ORIGIN }}
           MCP_ENABLED: ${{ vars.MCP_ENABLED }}
         run: bash scripts/deploy-production.sh

compose.production.yaml

@@ -32,9 +32,7 @@ x-backend: &backend
     AI_OUTPUT_TOKENS: ${AI_OUTPUT_TOKENS:-4096}
     AI_TIMEOUT: ${AI_TIMEOUT:-180}
     WQ_BASE_URL: ${WQ_BASE_URL:-https://api.worldquantbrain.com}
-  networks:
+  # Reach the remote PostgreSQL endpoint through the default network's egress.
-    - default
-    - database
 
 services:
   backend:
@@ -89,10 +87,6 @@ services:
       start_period: 10s
     restart: unless-stopped
 
-networks:
-  database:
-    external: true
-    name: ${DATABASE_NETWORK:?Set the existing PostgreSQL Docker network}
 volumes:
   caddy_data:
   caddy_config:

docs/deployment-gitea.md

@@ -1,6 +1,8 @@
 # Gitea 生产部署
 
-本方案在目标 Linux 服务器上由已有 Gitea Runner 构建并启动 Docker Compose，复用已有 PostgreSQL。入口绑定 `127.0.0.1:8112`，由宿主机反向代理提供公网 HTTPS。现有 `compose.yaml`、`compose.public.yaml` 保持独立，不与生产文件叠加。
+本方案使用两台服务器：A 服务器托管 Gitea 和项目仓库；B 服务器运行 `tencent-prod-runner`，拉取 A 上的 `prod` 分支代码，在 B 上构建镜像并启动 Docker Compose。工作流通过标签 `tencent-prod` 选择该运行器。
+
+PostgreSQL 位于独立数据库服务器或云数据库，B 上的应用通过 `DATABASE_URL` 访问它，不依赖同机数据库容器或外部 Docker 网络。应用入口绑定 **B 服务器**的 `127.0.0.1:8112`，由 B 的宿主机反向代理提供公网 HTTPS。现有 `compose.yaml`、`compose.public.yaml` 保持独立，不与生产文件叠加。
 
 ## 1. 填写配置和数据库账号密码
 
@@ -8,22 +10,23 @@
 
 | 位置 | 名称 | 填写内容 |
 | --- | --- | --- |
-| Secrets（必填） | `DATABASE_URL` | `postgresql+asyncpg://数据库账号:数据库密码@数据库网络别名:5432/数据库名` |
+| Secrets（必填） | `DATABASE_URL` | `postgresql+asyncpg://数据库账号:数据库密码@远程数据库域名或IP:端口/数据库名`，地址须能从 B 的应用容器访问 |
 | Secrets（必填） | `ADMIN_PASSWORD` | 系统初始管理员密码，至少 12 字符，与数据库密码独立 |
 | Secrets（必填） | `ENCRYPTION_KEY` | 下面命令生成的 Fernet 密钥，升级保持不变 |
 | Secrets（必填） | `WQ_EMAIL` | WorldQuant 登录邮箱 |
 | Secrets（必填） | `WQ_PASSWORD` | WorldQuant 登录密码，按原样填写，不加引号 |
-| Variables（必填） | `DATABASE_NETWORK` | PostgreSQL 所在的现有 Docker 网络，例如 `1panel-network` |
 | Variables（必填） | `PUBLIC_ORIGIN` | 实际 HTTPS 来源，例如 `https://alpha.your-domain.com`，不带路径或末尾 `/` |
 | Variables（可选） | `ADMIN_USERNAME` | 初始管理员账号，默认 `admin` |
 | Variables（可选） | `MCP_ENABLED` | 设置 `true` 启用 MCP；未配置时默认关闭 |
 
-端口与 AI 限制使用 `compose.production.yaml` 的默认值，不需要在 Gitea 配置：`WEB_PORT=8112`、`AI_REQUEST_LIMIT=12`、`AI_TOOL_LIMIT=12`、`AI_OUTPUT_TOKENS=4096`、`AI_TIMEOUT=180`。需要调整时修改 Compose 中对应默认值；工作流不再读取这些同名 Gitea Variables。
+端口与 AI 限制使用 `compose.production.yaml` 的默认值，不需要在 Gitea 配置：`WEB_PORT=8112`、`AI_REQUEST_LIMIT=12`、`AI_TOOL_LIMIT=12`、`AI_OUTPUT_TOKENS=4096`、`AI_TIMEOUT=180`。需要调整时修改 Compose 中对应默认值；工作流不再读取这些同名 Gitea Variables。原有 `DATABASE_NETWORK` 不再使用，无需在 B 上创建同名外部网络。
+
+已配置的 `PROD_SSH_KEY`、`PROD_HOST`、`PROD_PORT`、`PROD_USER`、`PROD_KNOWN_HOSTS` 可以继续保留供远程运维使用。本流程由 B 的 Runner 直接部署，不读取这些 SSH Secrets；镜像在 B 本机构建和使用，也不读取 `REGISTRY_USERNAME`、`REGISTRY_PASSWORD`。
 
 数据库连接串示例（实际填写时替换示例值）：
 
 ```text
-postgresql+asyncpg://wq_user:YOUR_PASSWORD@postgresql:5432/wq_alpha
+postgresql+asyncpg://wq_user:YOUR_PASSWORD@db.example.com:5432/wq_alpha
 ```
 
 生成加密密钥：
@@ -34,7 +37,9 @@ python3 -c 'import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_
 
 `DATABASE_URL` 的用户名和密码中的特殊字符须做 URL 百分号编码，例如 `@` → `%40`、`#` → `%23`、`/` → `%2F`、`%` → `%25`。在 Gitea 输入框填写值本身，不添加包裹引号，不填写 `DATABASE_URL=` 前缀。管理员密码中的 `$`、引号等按原样填写，由环境变量传递，无需 shell 转义。不要在日志打印变量，或开启 `set -x`。
 
-在现有 PostgreSQL 管理界面先创建专用数据库与账号，账号须可连接并拥有该库中应用 schema 的建表和迁移权限。确认网络存在、数据库别名可解析、PostgreSQL 允许该 Docker 网络访问。应用使用异步驱动 `asyncpg`；远程数据库或强制 TLS 的实例需另外按该实例的 TLS 配置调整连接参数，此模板默认同机 Docker 网络。
+在远程 PostgreSQL 管理界面先创建专用数据库与账号，账号须可连接并拥有该库中应用 schema 的建表和迁移权限。数据库安全组、白名单或防火墙须允许 B 的实际出口地址访问数据库端口，且 B 的应用容器须能解析并访问数据库地址；使用私网地址时先确保 B 与数据库的私网路由连通。不要在连接串中沿用只在 A 上可解析的数据库容器名，也不要使用 `localhost` 或 `127.0.0.1` 指向远程数据库。
+
+应用使用异步驱动 `asyncpg`；强制 TLS 或自定义 CA 的实例需按该实例要求配置兼容的连接参数及证书，不应直接假定其控制台提供的其他驱动连接串可用。部署脚本会在停止旧服务前，从 B 的后端容器进行真实数据库连接预检。
 
 如果从已有安装迁移数据，需恢复完整数据库并沿用原 `ENCRYPTION_KEY`；修改管理员环境变量不会重置已有管理员密码。
 
@@ -42,19 +47,27 @@ WorldQuant 凭据由环境变量管理，启动时加密写入数据库；页面
 
 ## 2. 配置 Gitea Runner
 
-沿用已成功部署 `zhixing-system` 的运行器标签 **`ubuntu-latest`**，无需注册新的 `wq-production` 运行器。该运行器的执行环境须能通过 Docker CLI/Compose 操作同一台 1Panel 服务器的 Docker daemon；可以复用现有 Docker 连接方式，不强制 host 模式。
+使用 B 服务器上已注册的 **`tencent-prod-runner`**，工作流的 `runs-on` 填写其标签 **`tencent-prod`**。只有 B 上用于生产部署的运行器应持有此标签。
+
+运行器的执行环境须通过 Docker CLI/Compose 操作 **B 宿主机的 Docker daemon**。可以沿用现有 host 或 Docker 执行模式：host 模式需要执行用户有权访问 B 的 Docker；容器模式需要部署步骤所在的作业容器能够访问 B 的 Docker socket（通常是 `/var/run/docker.sock`），且具有 Docker CLI/Compose。只给 Runner 管理容器挂载 socket 并不能证明作业容器内也可访问；不要将部署命令连接到 A 的远程 Docker 或临时 Docker-in-Docker 实例。
+
+Runner 注册的 Gitea 地址及仓库克隆地址必须能从 B 和作业执行环境访问，应使用 A 的实际域名或可达 IP；不能使用指向 A 本机的 `localhost`、`127.0.0.1` 或仅在 A 的 Docker 网络内可解析的容器名。
 
 执行环境需要 Git、Bash、Node.js 20（checkout v4）以及支持 `up --wait --wait-timeout` 的 Docker Compose。本流程不需要 `flock` 或预建 `/opt/wq-alpha`。服务器需能访问 checkout action、基础镜像仓库和依赖源。
 
-在仓库启用 Actions，`main` push 或手动运行会部署。Secrets 通过部署步骤的环境变量注入，`--env-file /dev/null` 防止误读开发 `.env`。构建可并行；构建完成后，以 Docker 唯一容器名 `wq-alpha-production-deploy-lock` 互斥保护预检、迁移和服务切换。锁容器不启动、不携带凭据，正常结束或失败时删除；竞争失败的任务不会删除其他任务的锁。
+在仓库启用 Actions，向 **`prod`** push 会部署；手动运行也须选择 **`prod`**，选择其他分支时本版工作流会跳过部署任务。Checkout 使用本次触发的提交，构建和迁移均在 B 的执行环境完成，无需 A 通过 SSH 再复制代码到 B。
+
+本次修改仅在 `prod` 分支。`main` 中的旧工作流仍配置为 `main` push → `ubuntu-latest`，不会随 `prod` 的修改自动停用；如需停用旧部署，须另行修改 `main` 的工作流。
+
+Secrets 仍在 A 的 Gitea 仓库设置中管理，通过部署步骤的环境变量注入 B 上的作业，`--env-file /dev/null` 防止误读开发 `.env`。构建可并行；构建完成后，以 B 的 Docker 唯一容器名 `wq-alpha-production-deploy-lock` 互斥保护预检、迁移和服务切换。锁容器不启动、不携带凭据，正常结束或失败时删除；竞争失败的任务不会删除其他任务的锁。
 
 如果 Runner 被强制终止或 Docker 断连，可能留下锁容器。先确认没有本项目部署正在执行，再手动运行 `docker rm wq-alpha-production-deploy-lock` 后重试。不要在部署进行时删除锁。
 
 ## 3. 配置反向代理并首次运行
 
-为 `PUBLIC_ORIGIN` 对应域名配置 HTTPS，转发至 **`http://127.0.0.1:8112`**（或你的 `WEB_PORT`）。代理须运行在宿主机网络中；独立 bridge 容器中的 `127.0.0.1` 不指向宿主机。若使用容器化 1Panel/OpenResty，先确认其网络模式。AI 流式响应需要关闭代理缓冲，并允许长连接/足够长的读取超时。
+将 `PUBLIC_ORIGIN` 对应域名解析到 **B 服务器**，在 B 配置 HTTPS 反向代理，转发至 **`http://127.0.0.1:8112`**（或你的 `WEB_PORT`）。此回环地址只对 B 本机有效；A 上的代理不能通过它访问 B。代理须运行在 B 的宿主机网络中；独立 bridge 容器中的 `127.0.0.1` 不指向宿主机。若使用容器化 1Panel/OpenResty，先确认其网络模式。AI 流式响应需要关闭代理缓冲，并允许长连接/足够长的读取超时。
 
-首次部署建议在 Gitea Actions 页面手动运行工作流。需要在服务器排障运行时，须先从安全渠道将上表必填配置注入当前进程环境，再执行：
+首次部署建议在 Gitea Actions 页面选择 **`prod`** 分支手动运行工作流，确认任务由 `tencent-prod-runner` 接收。需要在服务器排障运行时，在 **B 服务器的 `prod` 检出目录**中先从安全渠道将上表必填配置注入当前进程环境，再执行：
 
 ```bash
 bash scripts/deploy-production.sh
@@ -62,6 +75,8 @@ bash scripts/deploy-production.sh
 
 固定 Compose 项目名为 `wq-alpha-production`，后端保持一个实例、一个 worker。脚本先验证 Compose，构建按 Git 提交标记的镜像，再检查密钥格式和数据库连通性；随后停止 web/backend、执行一次性迁移、启动服务并等待健康检查。Web 健康检查同时覆盖页面和经 Caddy 转发的数据库健康接口。迁移或启动失败时非零退出并显示容器状态，不继续标记成功。
 
+从旧服务器切换时，若旧实例仍连接同一生产数据库，须在 B 上执行迁移前停止旧实例及其定时任务。脚本和部署锁只管理 B 上的容器，不会停止 A 上的旧应用，也不能协调两台服务器对同一数据库的迁移和写入。
+
 首次部署完成后，检查公网 `/api/v1/health`，再通过真实域名登录并确认页面、写请求和 Cookie 正常。容器健康通过不能替代 HTTPS、DNS 和真实 Gitea Runner 验收。
 
 ## 4. 升级、备份和失败处理
@@ -72,7 +87,7 @@ bash scripts/deploy-production.sh
 
 如旧代码与当前 schema 兼容，可检出旧提交并指定其镜像标签启动；否则先停止应用，使用经过验证的备份恢复数据库，再用原加密密钥和对应旧版本启动。数据库恢复会丢失备份后的写入，必须人工确认后执行。本配置没有自动数据库降级，也不承诺无停机升级。
 
-以下排查命令不依赖凭据环境变量（可能含业务信息的日志请勿公开）：
+以下排查命令在 **B 服务器**运行，不依赖凭据环境变量（可能含业务信息的日志请勿公开）：
 
 ```bash
 docker ps -a --filter label=com.docker.compose.project=wq-alpha-production
@@ -84,13 +99,13 @@ docker logs --tail=100 wq-alpha-production-web-1
 
 ## 配置依据
 
-采用 compound 经验 1 中的生产/开发隔离、显式外部网络、必填凭据、固定项目名、独立迁移和部署健康检查。未照搬旧项目端口、业务 Job 或卷权限初始化：本应用后端不写 named volume，已有镜像使用 UID 10001。
+生产/开发配置隔离，使用必填凭据、固定项目名、独立迁移和部署健康检查。生产服务使用 Compose 默认网络互通，并通过该网络访问远程 PostgreSQL；无需预建数据库 Docker 网络。本应用后端不写 named volume，已有镜像使用 UID 10001。
 
-凭据存放在 Gitea Secrets，通过步骤级环境变量交给 Compose，不落地到配置文件。Docker 容器仍需持有运行时配置，因此拥有 Runner 或 Docker 管理权限的人仍可能读取它们。若此前手动创建了旧 `.env.production`，新流程不再读取它；确认配置已迁移到 Gitea 并妥善备份密钥后可自行移除旧文件。相关官方资料：[Compose 外部网络](https://docs.docker.com/reference/compose-file/networks/)、[环境变量插值](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/)、[Gitea Runner 标签](https://gitea.com/gitea/runner/src/branch/main/README.md)。
+凭据存放在 Gitea Secrets，通过步骤级环境变量交给 Compose，不落地到配置文件。Docker 容器仍需持有运行时配置，因此拥有 Runner 或 Docker 管理权限的人仍可能读取它们。若此前手动创建了旧 `.env.production`，新流程不再读取它；确认配置已迁移到 Gitea 并妥善备份密钥后可自行移除旧文件。相关官方资料：[Compose 网络](https://docs.docker.com/compose/how-tos/networking/)、[环境变量插值](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/)、[Gitea Runner 2.x 标签](https://docs.gitea.com/runner/2/labels/)、[Gitea 分支上下文](https://docs.gitea.com/usage/actions/actions-variables/)。
 
 ## 5. 1Panel 夜间全量目录同步
 
-在 1Panel 的计划任务中建立 Shell 脚本任务，执行周期由 1Panel 设置，例如每天深夜执行。每次命令明确指定一个范围：
+在 **B 服务器**的 1Panel 计划任务中建立 Shell 脚本任务，执行周期由 1Panel 设置，例如每天深夜执行。每次命令明确指定一个范围：
 
 ```bash
 docker exec wq-alpha-production-backend-1 \

scripts/deploy-production.sh

@@ -6,7 +6,7 @@ umask 077
 
 cd "$(dirname "${BASH_SOURCE[0]}")/.."
 # Fail before touching the host; never read a checkout's local .env file.
-for key in WQ_EMAIL WQ_PASSWORD DATABASE_URL ADMIN_PASSWORD ENCRYPTION_KEY DATABASE_NETWORK PUBLIC_ORIGIN; do
+for key in WQ_EMAIL WQ_PASSWORD DATABASE_URL ADMIN_PASSWORD ENCRYPTION_KEY PUBLIC_ORIGIN; do
   if [[ -z "${!key:-}" ]]; then
     echo "Missing required Gitea configuration: $key" >&2
     exit 1