patbond-doc/docs/development/ci-runner-setup.md

Gitea Actions Runner 启用手册

目标：让 patbond-api/.gitea/workflows/ci.yml 在每次 push(dev)/PR 时自动执行 ./mvnw -B clean test（含 Testcontainers，需 Docker）。 适用：自建 Gitea（http://132.232.242.77，nginx 反代，Ubuntu）。 全程在服务器上操作，约 10 分钟。

第 1 步：Gitea 侧开启 Actions

1. 确认版本 ≥ 1.19（建议 1.21+）：Gitea 页面右下角或 gitea --version。

2. 编辑 app.ini（常见位置 /etc/gitea/app.ini 或 Gitea 安装目录 custom/conf/app.ini），加入/确认：

   [actions]
   ENABLED = true
   

3. 重启 Gitea：sudo systemctl restart gitea（按你的部署方式调整）。

4. 网页版验证：管理后台出现「Actions → Runners」菜单即成功。

第 2 步：获取注册令牌

• 全站级（推荐，一台 runner 服务所有仓库）：管理后台 → Actions → Runners → 创建 Runner，复制注册令牌（REGISTRATION TOKEN）。
• 或仓库级：patbond-api 仓库 Settings → Actions → Runners 里获取（只服务该仓库）。

第 3 步：启动 act_runner（Docker 方式，推荐）

在装有 Docker 的机器上（与 Gitea 同机即可）：

docker run -d --name act_runner --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v act_runner_data:/data \
  -e GITEA_INSTANCE_URL=http://132.232.242.77 \
  -e GITEA_RUNNER_REGISTRATION_TOKEN=<第2步的令牌> \
  -e GITEA_RUNNER_NAME=patbond-runner \
  -e GITEA_RUNNER_LABELS='ubuntu-latest:docker://docker.io/catthehacker/ubuntu:act-latest' \
  docker.io/gitea/act_runner:latest

要点：

• -v /var/run/docker.sock：runner 需要控制宿主 Docker 来起 job 容器。
• 标签 ubuntu-latest 必须存在——工作流里 runs-on: ubuntu-latest 靠它匹配； catthehacker/ubuntu:act-latest 镜像自带 node/git，能跑 actions/checkout 等 JS Action。

让 job 里的 Testcontainers 拿到 Docker（关键一步）

我们的门禁在 job 容器内还要再起 postgres:18 容器，所以 job 容器也要挂 docker.sock。 生成并修改 runner 配置：

docker exec act_runner act_runner generate-config > /tmp/config.yaml
# 编辑 /tmp/config.yaml，在 container 段加：
#   container:
#     options: "-v /var/run/docker.sock:/var/run/docker.sock"
docker cp /tmp/config.yaml act_runner:/data/config.yaml
docker restart act_runner
# 注意：runner 以 CONFIG_FILE=/data/config.yaml 生效，若镜像未自动读取，
# 重新以 -e CONFIG_FILE=/data/config.yaml 运行容器。

第 4 步：验证

1. 管理后台 → Actions → Runners：patbond-runner 显示 Idle。
2. patbond-api 仓库 Settings → Actions 确认已启用（默认继承全局）。
3. 推送 dev 分支（或手动 re-run），仓库「Actions」页应出现运行记录， backend-test job 全绿（首跑要拉镜像与 Maven 依赖，10 分钟内正常）。

常见问题

现象	处理
docker run 报 permission denied ... docker.sock	当前用户不在 docker 组：sudo usermod -aG docker $USER，退出 SSH 重登生效
拉镜像 dial tcp ...443: i/o timeout	服务器直连 Docker Hub 不通。配镜像加速后 sudo systemctl restart docker：腾讯云机器优先内网源 https://mirror.ccs.tencentyun.com，公共源如 https://docker.1ms.run（可用性随时间变化，失效就换）。写入 /etc/docker/daemon.json 的 registry-mirrors 数组
job 卡在 actions/checkout 或 setup-java 拉不下来	runner 访问不了 github.com（与上一条通常同时出现）。两种解法：a) app.ini 的 [actions] 加 DEFAULT_ACTIONS_URL = https://gitea.com（用 gitea.com 上的 Action 镜像仓）后重启 Gitea；b) 把工作流的 setup-java 步骤删掉，改用自带 JDK17 的 job 镜像（ci.yml 头部注释已写明）
Testcontainers 报 Could not find a valid Docker environment	第 3 步的 container.options 没生效，job 容器内没有 docker.sock
CI 秒失败、steps 为空	第一动作：在本机复现 CI 的第一个 step（通常是 git clone --depth 1 https://git.patbond.cn/<owner>/<repo>.git）。本机同样失败 ⇒ 问题在 Gitea/网络侧，与 runner 无关；本机成功 ⇒ 再查 runner。2026-09-11 的事件中，先查 runner 走了两次弯路，本机复现一步到位（见事件复盘）
跨仓比较 CI 状态得出「runner 还活着」	必须核对状态的时间戳：某仓「最新提交 success」可能是前一天的旧记录。用 curl .../commits/<sha>/status 看 created_at
git clone 报 bad pack header / early EOF 而 push 正常	二者走不同方向：push 是 receive-pack，clone 是 upload-pack。检查 Gitea 的 gitconfig 是否被注入 uploadpack.packObjectsHook（sudo grep -rn packObjectsHook /var/lib/gitea/*/. gitconfig），并核对服务器暴露面清单
runner 显示 offline	docker logs act_runner 看注册错误；令牌只能用一次，重新注册需删 /data/.runner；重试 docker run 前先 docker rm -f act_runner 清残留容器
Maven 每次全量下载依赖很慢	在 config.yaml 的 container.options 追加 -v act_m2:/root/.m2 做持久缓存

安全习惯：runner 注册成功后，到管理后台 → Actions → Runners 重置注册令牌（不影响已注册的 runner）。

启用完成后，把 docs/development/feature-checklist.md 第 6 节「CI 载体」从 🟡 改为 ✅。