[NEDONION]

背景

仓库此前没有任何 CI（无 .github/ 目录），发布全靠本地跑 build-and-push.sh 再手动登服务器。

架构：不用 SSH

构建跑在 GitHub 云端 runner，部署跑在服务器上的自托管 runner：

build  (ubuntu-latest) → 构建镜像、推 ACR      ← 不占用服务器资源
deploy (self-hosted)   → docker compose pull   ← 只做拉取重启，几秒钟

自托管 runner 主动向 GitHub 轮询任务，纯出站连接。因此服务器不需要开放 SSH 或任何入站端口，GitHub Secrets 里也不存放服务器凭据 —— Secrets 从 7 个减到 3 个（ACR_USERNAME / ACR_PASSWORD / DEPLOY_PATH）。

runner 本身就是 docker-compose.yml 里的一个服务，跟其他容器一起起停，不需要单独安装或配置 systemd。用 PAT 换取一次性注册令牌，退出时自动注销，不留僵尸 runner。

新增

• ci.yml —— PR 校验：后端 mvn compile、前端 pnpm build、nginx -t，不碰服务器
• deploy.yml —— push main 后：构建推 ACR → 自托管 runner 拉取重启 → 健康检查
• deploy/runner/ —— runner 镜像与启动脚本

三个实现上的坑（已处理，注释里写明原因）

1. 部署命令必须显式限定服务名。 runner 自己也在 compose 里，裸的 up -d 会把它一起重建，当场杀掉正在执行的部署任务。
2. 项目目录必须挂载到与宿主机完全相同的绝对路径。 compose 把相对路径解析成绝对路径后交给宿主机守护进程按宿主机文件系统查找，容器内外路径不一致就会挂载错位置。
3. 健康检查用服务名而非 localhost。 脚本跑在 runner 容器内，localhost 指向 runner 自己。

顺带修掉的不一致

build-and-push.sh 里 REPO="acr"，推的是 lucas_acr/acr:*；而 docker-compose.yml 拉的是 lucas_acr/rag-agent-platform:* —— 两边仓库名对不上。以 compose 为准统一。

版本可追溯 / 回滚

镜像同时打 <sha> 和 latest。部署时把 commit SHA 写进服务器 .env 的 IMAGE_TAG，所以「线上跑的是哪个 commit」随时可查，回滚只需改这一行再 up -d。未设置时回落 latest，手动流程不受影响。

⚠️ 安全约束

deploy.yml 只允许 push 到 main 触发，绝不能加 pull_request。这是公开仓库 —— 一旦 fork 的 PR 能触发工作流，任何人都能在服务器上执行任意代码。已在工作流注释和 DEPLOY.md 中标注。

另：CI 只对服务器 .env 做 IMAGE_TAG 一行的原地替换，不覆盖、不读取、不外传。

验证

• ✅ 三个 CI 检查全绿
• ✅ runner 镜像构建通过，镜像内 docker / compose / jq 与 runner 脚本齐备
• ✅ entrypoint 在缺变量、PAT 无效等情况下给出可读失败原因（此前 set -e 会让报错在提示打印前就终止，已修）
• ✅ compose 在 DEPLOY_PATH 变化时挂载源与目标始终一致
• ✅ deploy.yml 三个 run 步骤通过 bash -n，确认不含 pull_request 触发器
• ✅ nginx -t 用 --network none 复现出 CI 的失败条件后再验证修复

⚠️ 端到端未验证 —— 需要真实 PAT 和服务器，首次运行才能确认。

🤖 Generated with Claude Code