diff --git a/skill/gitea/runner-management.md b/skill/gitea/runner-management.md index 5dc8fa2..e80f46e 100644 --- a/skill/gitea/runner-management.md +++ b/skill/gitea/runner-management.md @@ -29,6 +29,7 @@ Gitea Act Runner 是 Gitea Actions 的 CI/CD 执行器,兼容 GitHub Actions w - **macOS ARM64**: 使用 **Host Mode** 以支持 Android SDK - **Windows**: 使用 **Host Mode**(需在 workflow 中指定 `shell: powershell`) - **Linux**: 两种模式均可,Docker Mode 隔离性更好 +- **Docker Mode**: 必须使用 `catthehacker/ubuntu:act-*` 镜像(内置 Docker CLI) **Windows Host Mode 注意事项**: - Bash 默认不可用,需在 workflow 中指定 shell: @@ -577,9 +578,51 @@ labels: ```yaml labels: - "ubuntu-latest:docker://catthehacker/ubuntu:act-latest" - - "ubuntu-22.04:docker://catthehacker/ubuntu:act-latest" + - "ubuntu-22.04:docker://catthehacker/ubuntu:act-22.04" + - "ubuntu-20.04:docker://catthehacker/ubuntu:act-20.04" + - "linux:docker://catthehacker/ubuntu:act-latest" ``` +### Docker Mode 镜像选择(重要) + +**必须使用包含 Docker CLI 的镜像**,否则 `docker/login-action`、`docker/build-push-action` 等 actions 会失败。 + +| 镜像 | Docker CLI | 适用场景 | +|------|------------|---------| +| `catthehacker/ubuntu:act-latest` | ✅ 有 | **推荐**,CI/CD 专用镜像 | +| `catthehacker/ubuntu:act-22.04` | ✅ 有 | Ubuntu 22.04 兼容 | +| `node:16-bullseye` | ❌ 无 | **不推荐**,仅适合纯 Node.js 项目 | +| `golang:1.21` | ❌ 无 | **不推荐**,仅适合纯 Go 项目 | + +**catthehacker/ubuntu:act-* 预装工具**: +- Docker CLI (`/usr/bin/docker`) +- Docker Buildx +- git, curl, wget, jq +- Node.js, Python +- 常用编译工具 + +**工作原理**: +``` +workflow: runs-on: ubuntu-latest + ↓ +runner 查找 label: ubuntu-latest:docker://镜像名 + ↓ +启动 job 容器(使用该镜像) + ↓ +在 job 容器内执行 steps + ↓ +docker/login-action 调用 `docker login` 命令 + ↓ +需要 job 容器内有 docker CLI ← 关键! +``` + +**常见错误**: +``` +Unable to locate executable file: docker. Please verify either the file path exists +or the file can be found within a directory specified by the PATH environment variable. +``` +此错误表示 job 容器内缺少 docker 命令,需要更换为包含 Docker CLI 的镜像。 + ### Workflow 匹配 **方法 1: 组合 label(推荐,最精确)** @@ -993,6 +1036,106 @@ nohup act_runner daemon --config ~/.config/gitea/runners/runner-macbook-pro/conf tail -f ~/.config/gitea/runners/runner-macbook-pro/runner.log ``` +### 8. 恢复被删除的 Runner(从服务器删除但本地文件仍在) + +**场景**:Runner 在 Gitea 服务器上被删除,但本地目录和配置文件仍在。需要重新注册并上线。 + +**恢复步骤**: + +```bash +# 1. 进入 runner 目录 +cd ~/.config/gitea/runners/runner-Mac-mini4-host + +# 2. 停止旧进程(如果仍在运行) +if [ -f pid ]; then + kill $(cat pid) 2>/dev/null || true + rm -f pid +fi + +# 3. 加载 Gitea 配置 +source ~/.config/gitea/config.env + +# 4. 获取注册令牌(优先全局,失败则降级到组织) +echo "获取注册令牌..." +response=$(curl -s -w "\n%{http_code}" \ + -H "Authorization: token $GITEA_TOKEN" \ + "${GITEA_URL}/api/v1/admin/runners/registration-token") +http_code=$(echo "$response" | tail -n1) +body=$(echo "$response" | sed '$d') + +if [ "$http_code" != "200" ]; then + echo "全局令牌权限不足,尝试组织令牌..." + if [ -n "$GITEA_DEFAULT_ORG" ]; then + org_name="$GITEA_DEFAULT_ORG" + else + read -p "请输入组织名称: " org_input + org_name="$org_input" + fi + response=$(curl -s -w "\n%{http_code}" -X POST \ + -H "Authorization: token $GITEA_TOKEN" \ + "${GITEA_URL}/api/v1/orgs/$org_name/actions/runners/registration-token") + http_code=$(echo "$response" | tail -n1) + body=$(echo "$response" | sed '$d') +fi + +if [ "$http_code" != "200" ]; then + echo "❌ 获取注册令牌失败" + exit 1 +fi + +registration_token=$(echo "$body" | jq -r '.token') + +# 5. 生成标签(基于系统环境) +OS=$(uname -s) +case "$OS" in + Darwin) os_label="macOS" ;; + Linux) os_label="ubuntu" ;; + *) os_label="unknown" ;; +esac + +ARCH=$(uname -m) +case "$ARCH" in + arm64|aarch64) arch_label="ARM64" ;; + x86_64) arch_label="x64" ;; + *) arch_label="unknown" ;; +esac + +combined=$(echo "${OS}-${ARCH}" | tr '[:upper:]' '[:lower:]') +labels="self-hosted:host,${os_label}:host,${arch_label}:host,${combined}:host" + +# 6. 重新注册 runner +act_runner register \ + --config config.yaml \ + --instance "$GITEA_URL" \ + --token "$registration_token" \ + --name "runner-Mac-mini4-host" \ + --labels "$labels" \ + --no-interactive + +if [ $? -ne 0 ]; then + echo "❌ 注册失败" + exit 1 +fi + +# 7. 启动 runner daemon +nohup act_runner daemon --config config.yaml > runner.log 2>&1 & +echo $! > pid +sleep 2 + +if ps -p $(cat pid) > /dev/null 2>&1; then + echo "✅ Runner 恢复成功 (PID: $(cat pid))" + echo "日志: tail -f runner.log" +else + echo "❌ Runner 启动失败" + exit 1 +fi +``` + +**说明**: +- 恢复后 runner 会获得新的 ID 和 token,但名称和 labels 保持不变 +- 旧的 `.runner` 文件会被新的覆盖 +- 确保 `config.yaml` 中的 labels 配置为空(`labels: []`),注册时会使用命令行参数 + ## Quick Reference | 任务 | 命令 | @@ -1001,6 +1144,7 @@ tail -f ~/.config/gitea/runners/runner-macbook-pro/runner.log | 创建 runner | `/gitea-create-runner`(自动安装、配置、启动)| | 列出 runners | `/gitea-list-runners` | | 删除 runner | `/gitea-delete-runner` | +| 恢复 runner | 参考「恢复被删除的 Runner」章节 | | 手动启动 | `nohup act_runner daemon --config > 2>&1 &` | | 停止 runner | `pkill -f "act_runner daemon --config.*"` | | 查看状态 | `ps aux \| grep act_runner` | @@ -1016,6 +1160,9 @@ tail -f ~/.config/gitea/runners/runner-macbook-pro/runner.log ## 版本 -- **文档版本**: 1.0 -- **最后更新**: 2026-01-12 +- **文档版本**: 1.2 +- **最后更新**: 2026-01-24 +- **更新内容**: + - Docker Mode 镜像选择说明(必须使用包含 Docker CLI 的镜像) + - Runner 恢复流程 - **兼容性**: act_runner 0.2.13+, macOS ARM64, Linux