docs(ci): runner 设置记录(决定用 1 个 mac-pangolin-2 + 清理/持久化)

记录 pangolin CI 的 self-hosted runner:决定保留 1 个(mac-pangolin-2,项目级、 mac host 模式、label nas、复用 jiu 的 relay 13000),含 config、为何 host+mac、 relay 原因、已删 orphan(mac-pangolin id5)的清理命令、持久化(launchd)TODO。登记进 docs/index.html。 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-25 18:52:54 +08:00
parent 65bd7c381b
commit 034a585e3b
2 changed files with 73 additions and 0 deletions
@@ -0,0 +1,68 @@
+# Pangolin CI Runner 记录
+
+> gitea Actions self-hosted runner 设置记录。CI 工作流见 `.gitea/workflows/ci.yml`(9 个 job)。
+
+## 决定:用 1 个 runner
+
+| 项 | 值 |
+|---|---|
+| 名称 | **mac-pangolin-2**(gitea id 6) |
+| 级别 | **项目级**(绑 `wangjia/pangolin`,只服务本仓库) |
+| 机器 | mac 本机(`/Users/wangjia/bin/act_runner` v0.6.1) |
+| 执行模式 | **host**(非容器) |
+| label | `nas`(即 `runs-on: nas`) |
+| 连接 | 经 jiu 的 TCP relay `127.0.0.1:13000` → NAS gitea `192.168.3.200:3000` |
+
+### 为什么是 host 模式 + mac
+- ci.yml 的 9 个 job **全是 docker-in-docker**(每个 job 内部 `docker run …` 拉 golang/flutter/redis 等镜像)。container 模式(像 jiu 的 `ubuntu-latest:docker://catthehacker`)在非特权容器里跑不了 DinD,所以必须 **host 模式**。
+- mac 的 Docker Desktop 能跑 Linux 容器,host 模式下 `docker run <linux-image>` 可用。
+- 理想归宿其实是 **NAS(Linux)host runner**(给 NAS 现有 runner 加 `nas:host` label),mac 只是当前落点。
+
+### 为什么要 relay(13000)
+mac 上的 Shadowrocket 网络扩展会拦截 act_runner 这个 Go 二进制的流量,直连 NAS gitea 失败。jiu 已有一个常驻 python TCP relay(`~/bin/tcp_relay.py`,`127.0.0.1:13000 → 192.168.3.200:3000`),act_runner 连本地 relay 绕过。pangolin runner **复用**这个 relay。
+
+## 配置文件:`~/.act_runner_pangolin2_config.yaml`
+```yaml
+log:
+  level: info
+runner:
+  file: /Users/wangjia/.act_runner_pangolin2     # 注册凭证(.runner),勿入 git
+  capacity: 1
+  timeout: 3h
+  labels:
+    - "nas:host"
+cache:
+  enabled: true
+host:
+  workdir_parent: /Users/wangjia/.cache/act-pangolin2
+```
+
+## 当前运行方式(临时,非持久)
+```bash
+export PATH="/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+/Users/wangjia/bin/act_runner daemon --config /Users/wangjia/.act_runner_pangolin2_config.yaml
+```
+> ⚠️ 当前是后台进程,**mac 重启就没了**。要持久化见下「持久化 TODO」。
+
+## 已删除:mac-pangolin(第一次注册的,id 5)
+第一次注册的 runner(label `nas`,config `~/.act_runner_pangolin_config.yaml`)。job 调试时已从 **gitea 删除注册**(API DELETE,204)。本机残留待清:
+```bash
+# orphan daemon 进程(拿不到任务、空转报 "unregistered runner",无害但占进程)
+pkill -f 'act_runner_pangolin_config.yaml'   # 只匹配 orphan,不碰 -2 和 jiu
+# orphan 文件
+rm -f  ~/.act_runner_pangolin ~/.act_runner_pangolin_config.yaml
+rm -rf ~/.cache/act-pangolin
+```
+
+## 持久化 TODO(让 runner 开机自启、不随 session/重启消失)
+仿 jiu 的 `com.jiu.act-runner`(launchd + relay-aware start script):
+1. 写 start 脚本(确保 relay 13000 在 → 起 daemon),仿 `~/bin/act_runner_start.sh`。
+2. 写 `~/Library/LaunchAgents/com.pangolin.act-runner.plist`(RunAtLoad + KeepAlive)。
+3. `launchctl load ~/Library/LaunchAgents/com.pangolin.act-runner.plist`。
+4. 加载前先停掉当前临时 daemon:`pkill -f act_runner_pangolin2_config.yaml`。
+
+> 或者换路线:在 **NAS** 上给现有 runner 加 `nas:host` label + 重启,把 pangolin CI 迁到 NAS(Linux,更稳),mac 这个就可退役。
+
+## 验证
+- gitea → 仓库 Settings → Actions → Runners 应只见 **mac-pangolin-2**(online)。
+- 向 `main` 开 PR 触发 9 个 job;首次全绿见 run #298(commit `65bd7c3`)。
@@ -120,6 +120,11 @@
 </a>

 <h2>排障 / Runbook</h2>
+<a class="doc" href="ci-runner.md">
+  <div class="t">CI Runner 设置记录 <span class="tag md">MD</span></div>
+  <div class="d">gitea Actions self-hosted runner 记录:决定用 1 个(mac-pangolin-2,项目级·mac host·label nas·复用 jiu relay)、已删 orphan 的清理命令、持久化 TODO。CI 首跑 run #298 9/9 全绿。</div>
+  <div class="path">docs/ci-runner.md</div>
+</a>
 <a class="doc" href="macos-sysext-realize-troubleshooting.html">
  <div class="t">macOS 系统扩展 realize 失败（code=4）踩坑复盘 <span class="tag html">HTML</span></div>
  <div class="d">PacketTunnel 系统扩展无法激活的三个叠加配置 bug 排查与修复。</div>