worldquant-alpha-system/docs/deployment-gitea.md

# Gitea 生产部署

本方案在目标 Linux 服务器上由已有 Gitea Runner 构建并启动 Docker Compose，复用已有 PostgreSQL。入口绑定 `127.0.0.1:8112`，由宿主机反向代理提供公网 HTTPS。现有 `compose.yaml`、`compose.public.yaml` 保持独立，不与生产文件叠加。

## 1. 填写配置和数据库账号密码

进入 **Gitea 仓库 → 设置 → Actions → Secrets / Variables**，按下表创建同名配置。敏感值填写在 Secrets，工作流仅在部署步骤通过环境变量注入，不生成服务器凭据文件。

| 位置 | 名称 | 填写内容 |
| --- | --- | --- |
| Secrets（必填） | `DATABASE_URL` | `postgresql+asyncpg://数据库账号:数据库密码@数据库网络别名:5432/数据库名` |
| 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。

数据库连接串示例（实际填写时替换示例值）：

```text
postgresql+asyncpg://wq_user:YOUR_PASSWORD@postgresql:5432/wq_alpha
```

生成加密密钥：

```bash
python3 -c 'import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())'
```

`DATABASE_URL` 的用户名和密码中的特殊字符须做 URL 百分号编码，例如 `@` → `%40`、`#` → `%23`、`/` → `%2F`、`%` → `%25`。在 Gitea 输入框填写值本身，不添加包裹引号，不填写 `DATABASE_URL=` 前缀。管理员密码中的 `$`、引号等按原样填写，由环境变量传递，无需 shell 转义。不要在日志打印变量，或开启 `set -x`。

在现有 PostgreSQL 管理界面先创建专用数据库与账号，账号须可连接并拥有该库中应用 schema 的建表和迁移权限。确认网络存在、数据库别名可解析、PostgreSQL 允许该 Docker 网络访问。应用使用异步驱动 `asyncpg`；远程数据库或强制 TLS 的实例需另外按该实例的 TLS 配置调整连接参数，此模板默认同机 Docker 网络。

如果从已有安装迁移数据，需恢复完整数据库并沿用原 `ENCRYPTION_KEY`；修改管理员环境变量不会重置已有管理员密码。

WorldQuant 凭据由环境变量管理，启动时加密写入数据库；页面只保留连接操作。修改 `WQ_PASSWORD` 后重新运行部署即可更新。`WQ_EMAIL` 必须与已有绑定账户一致，避免混入其他账户数据；生产不读取 `account.json` 或本地 `.env`。

## 2. 配置 Gitea Runner

沿用已成功部署 `zhixing-system` 的运行器标签 **`ubuntu-latest`**，无需注册新的 `wq-production` 运行器。该运行器的执行环境须能通过 Docker CLI/Compose 操作同一台 1Panel 服务器的 Docker daemon；可以复用现有 Docker 连接方式，不强制 host 模式。

执行环境需要 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` 互斥保护预检、迁移和服务切换。锁容器不启动、不携带凭据，正常结束或失败时删除；竞争失败的任务不会删除其他任务的锁。

如果 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 流式响应需要关闭代理缓冲，并允许长连接/足够长的读取超时。

首次部署建议在 Gitea Actions 页面手动运行工作流。需要在服务器排障运行时，须先从安全渠道将上表必填配置注入当前进程环境，再执行：

```bash
bash scripts/deploy-production.sh
```

固定 Compose 项目名为 `wq-alpha-production`，后端保持一个实例、一个 worker。脚本先验证 Compose，构建按 Git 提交标记的镜像，再检查密钥格式和数据库连通性；随后停止 web/backend、执行一次性迁移、启动服务并等待健康检查。Web 健康检查同时覆盖页面和经 Caddy 转发的数据库健康接口。迁移或启动失败时非零退出并显示容器状态，不继续标记成功。

首次部署完成后，检查公网 `/api/v1/health`，再通过真实域名登录并确认页面、写请求和 Cookie 正常。容器健康通过不能替代 HTTPS、DNS 和真实 Gitea Runner 验收。

## 4. 升级、备份和失败处理

升级包含停机窗口；提前结束或暂停长时间任务。每次发布前通过现有数据库管理工具备份专用库，并在独立安全位置备份加密密钥及必要配置，先在独立库验证恢复。此工作流不会自动备份或自动恢复数据库。

构建及预检失败时旧服务继续运行。停止服务后的迁移或健康检查失败需要人工处理；不要对可能已变更的 schema 直接自动降级。脚本在 Actions 日志输出切换前的镜像 ID/标签，成功后输出当前提交标识；保留旧镜像且不执行 prune。请保留部署日志作为回退参考，不再依赖宿主机版本记录文件。

如旧代码与当前 schema 兼容，可检出旧提交并指定其镜像标签启动；否则先停止应用，使用经过验证的备份恢复数据库，再用原加密密钥和对应旧版本启动。数据库恢复会丢失备份后的写入，必须人工确认后执行。本配置没有自动数据库降级，也不承诺无停机升级。

以下排查命令不依赖凭据环境变量（可能含业务信息的日志请勿公开）：

```bash
docker ps -a --filter label=com.docker.compose.project=wq-alpha-production
docker logs --tail=100 wq-alpha-production-backend-1
docker logs --tail=100 wq-alpha-production-web-1
```

普通维护不要使用 `down -v`。这里的数据库由外部管理，备份与恢复应在数据库管理端进行。

## 配置依据

采用 compound 经验 1 中的生产/开发隔离、显式外部网络、必填凭据、固定项目名、独立迁移和部署健康检查。未照搬旧项目端口、业务 Job 或卷权限初始化：本应用后端不写 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)。

## 5. 1Panel 夜间全量目录同步

在 1Panel 的计划任务中建立 Shell 脚本任务，执行周期由 1Panel 设置，例如每天深夜执行。每次命令明确指定一个范围：

```bash
docker exec wq-alpha-production-backend-1 \
  python -m app.cli catalog-sync \
  --region USA --universe TOP3000 --delay 1
```

`--instrument-type` 默认 `EQUITY`，`--wait-timeout` 默认 `21600` 秒（六小时）。容器已持有部署时注入的环境，定时脚本无需再次填写数据库、密码或加密密钥；不要加 `-it`。容器命令继承环境的行为见 [Docker exec 官方文档](https://docs.docker.com/reference/cli/docker/container/exec/)。启动前在网页完成 WorldQuant 连接，人工验证仍在网页处理。

CLI 只创建持久化任务并等待，不启动另一个同步执行器；后端必须正在运行。相同范围的活动全量任务复用同一任务 ID。任务先完整更新数据集清单，再逐个同步所有字段，每个数据集独立完整发布。普通单集失败保留上一版并继续其他数据集；鉴权和网络连接问题暂停全量任务。任务面板可查看阶段、当前数据集、字段分页位置、成功/失败统计，并取消或重试。

1Panel 执行日志保存 CLI 输出的任务 ID、状态变化、检查点和最终汇总。也可使用 `docker logs --tail=100 wq-alpha-production-backend-1` 排查执行器；命令不输出平台认证信息。不要公开包含研究数据的日志。

失败或部分失败时按日志中的任务 ID 从检查点继续，已成功发布的数据集不会重抓：

```bash
docker exec wq-alpha-production-backend-1 \
  python -m app.cli catalog-sync --resume-job TASK_ID --wait-timeout 21600
```

退出码：`0` 全部成功，`1` 失败/部分失败/取消，`2` 参数错误，`3` 需要连接或人工验证，`4` 等待超时。超时只结束 CLI 等待，后台任务继续；重复执行同范围命令可继续等待活动任务。恢复前先处理连接或验证问题。服务重启后由原执行器恢复持久化检查点；定时调度仅由 1Panel 负责。

真实平台协议和 1Panel 实际触发效果不属于模拟验收。