lixi
f9b1358b37
CI / docs-build (push) Successful in 1m59s
安全事件（已闭环，服务恢复）： - 根因链：Gitea 3000 对公网开放 → 外部调用 /api/internal/manager/add-logger 注入 gitconfig 的 uploadpack.packObjectsHook → 指向不存在的脚本 → upload-pack 发 NAK 后无法产出 pack → 全仓 HTTPS clone 失败（CI 全挂） - 攻击未达成代码执行（hook 目标脚本不存在）；三仓 ref 与本地逐一核对未被篡改； 无系统层入侵（无陌生 key/crontab/挖矿进程/陌生登录） - 新建常设「服务器暴露面清单」：补上服务器侧「决策变了环境没跟上」的核对机制 （Nacos 在 ADR-002 移除后仍暴露公网近两个月） - CI Runner 手册排障表增三条：CI 秒失败先在本机复现 checkout、跨仓比 CI 须核对时间戳、clone 坏而 push 正常时查 packObjectsHook 注入 M3.5 交付报告：03 后端资料与头像（api 334→379）、04 契约冻结 v1.4.0 （31→32 路径、矩阵 173→181 格、11 格红转绿）、05 资料页与头像 UI（flutter 526→597） Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
87 lines
5.5 KiB
Markdown
87 lines
5.5 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 |
|
||
| **CI 秒失败、`steps` 为空** | **第一动作：在本机复现 CI 的第一个 step**（通常是 `git clone --depth 1 https://git.patbond.cn/<owner>/<repo>.git`）。本机同样失败 ⇒ 问题在 Gitea/网络侧，与 runner 无关；本机成功 ⇒ 再查 runner。2026-09-11 的事件中，先查 runner 走了两次弯路，本机复现一步到位（见[事件复盘](iterations/iteration-3.5/07-security-incident-20260911.md)） |
|
||
| 跨仓比较 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`），并核对[服务器暴露面清单](server-exposure.md) |
|
||
| 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 载体」从 🟡 改为 ✅。
|