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

Gitea 生产部署

本方案在目标 Linux 服务器上由 Gitea host 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

端口与 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。

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

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

生成加密密钥：

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

在目标 Docker 宿主机直接运行专用 Runner，注册标签 wq-production:host，工作流的 runs-on 对应 wq-production。建议专用 Runner 配置 runner.capacity: 1。不要使用指向其他机器的 Docker context；这里的 host 模式也不能被当成“容器化 Runner 自动进入宿主机”。

Runner 用户需要 Docker 权限，以及写入预先创建的 /opt/wq-alpha 目录的权限。该目录仅保存锁文件和版本记录，不保存凭据。宿主机需具备 Git、Bash、Node.js 20（checkout v4）、flock（通常由 util-linux 提供）和支持 up --wait --wait-timeout 的 Docker Compose v2 或 v5。镜像使用锁文件构建，服务器需能访问 GitHub checkout action、基础镜像仓库和依赖源。本地验证环境为 Docker Engine 29.6.2、Compose 5.3.1；你的 Gitea/Runner 版本需在首次运行核验。

在 Gitea 仓库启用 Actions，提交并推送这些配置后，main 的 push 或手动运行会部署。Runner 应只接收可信仓库的任务，因为它具备生产主机 Docker 权限。凭据通过上述 Secrets 注入，脚本使用 --env-file /dev/null 防止误读检出目录的开发 .env。部署脚本用 /opt/wq-alpha/deploy.lock 实现跨 checkout 的互斥，冲突部署直接失败，可稍后重新运行。

3. 配置反向代理并首次运行

为 PUBLIC_ORIGIN 对应域名配置 HTTPS，转发至 http://127.0.0.1:8112（或你的 WEB_PORT）。代理须运行在宿主机网络中；独立 bridge 容器中的 127.0.0.1 不指向宿主机。若使用容器化 1Panel/OpenResty，先确认其网络模式。AI 流式响应需要关闭代理缓冲，并允许长连接/足够长的读取超时。

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

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 直接自动降级。脚本将切换前的镜像 ID/标签记录到 /opt/wq-alpha/previous-images.txt，最后成功的提交记录到 current-release.txt，保留旧镜像且不执行 prune。失败重试前另存这些记录，避免后续尝试覆盖回退参考。

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

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

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 外部网络、环境变量插值、Gitea Runner 标签。