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

- 镜像加速、DEFAULT_ACTIONS_URL、runner 重注册清残留等实操要点 - 门禁：mkdocs build --strict 通过
2026-09-04 16:35:08 +08:00
parent 3ac756fa14
commit b26b2af089
2 changed files with 7 additions and 3 deletions
@@ -71,9 +71,13 @@ docker restart act_runner

 | 现象 | 处理 |
 | --- | --- |
-| 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 头部注释已写明） |
+| `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` |
+| 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 载体」从 🟡 改为 ✅。