# 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 分钟内正常）。

## 常见问题

| 现象 | 处理 |
| --- | --- |
| job 卡在 `actions/checkout` 或 `setup-java` 拉不下来 | runner 访问不了 github.com。两种解法：a) `app.ini` 的 `[actions]` 加 `DEFAULT_ACTIONS_URL = https://gitea.com`（用 gitea.com 上的 Action 镜像仓）；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` |
| Maven 每次全量下载依赖很慢 | 在 config.yaml 的 container.options 追加 `-v act_m2:/root/.m2` 做持久缓存 |

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