84 lines
4.6 KiB
Markdown
84 lines
4.6 KiB
Markdown
# 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`），加入/确认：
|
||
|
||
```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 同机即可）：
|
||
|
||
```bash
|
||
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 配置：
|
||
|
||
```bash
|
||
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 |
|
||
| 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 载体」从 🟡 改为 ✅。
|