Files

T

lixi b26b2af089 docs: CI Runner 手册补充国内网络问题修法并同步清单状态

- 镜像加速、DEFAULT_ACTIONS_URL、runner 重注册清残留等实操要点
- 门禁：mkdocs build --strict 通过

2026-09-04 16:35:08 +08:00

4.6 KiB

Raw Blame History

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.19（建议 1.21+）：Gitea 页面右下角或 gitea --version。
编辑 app.ini（常见位置 /etc/gitea/app.ini 或 Gitea 安装目录 custom/conf/app.ini），加入/确认：
```
[actions]
ENABLED = true
```
重启 Gitea：sudo systemctl restart gitea（按你的部署方式调整）。
网页版验证：管理后台出现「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 步：验证

管理后台 → Actions → Runners：patbond-runner 显示 Idle。
patbond-api 仓库 Settings → Actions 确认已启用（默认继承全局）。
推送 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
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 载体」从 🟡 改为 ✅。

4.6 KiB Raw Blame History Unescape Escape