cloud-mcp/RUNNER_SETUP.md

# Gitea Act Runner 快速设置指南

## 问题：没有匹配 ubuntu-latest 标签的在线运行器

这个错误表示工作流找不到匹配标签的 Runner。有两种解决方案：

## 解决方案一：使用 self-hosted 标签（推荐，最简单）

我已经将工作流文件更新为使用 `runs-on: self-hosted`，这样会匹配任何自托管的 Runner，不需要特定标签。

### 注册 Runner（使用 self-hosted）

```bash
# 1. 下载 Act Runner
cd /tmp
wget https://gitea.com/gitea/act_runner/releases/download/v0.2.6/act_runner-linux-amd64
chmod +x act_runner-linux-amd64
sudo mv act_runner-linux-amd64 /usr/local/bin/act_runner

# 2. 注册 Runner（不指定标签，或使用 self-hosted）
act_runner register \
  --instance <your-gitea-url> \
  --token <runner-token> \
  --name my-runner

# 或者明确指定 self-hosted 标签
act_runner register \
  --instance <your-gitea-url> \
  --token <runner-token> \
  --name my-runner \
  --labels self-hosted
```

**获取 Runner Token**：
1. 进入 Gitea：**Site Administration** → **Actions** → **Runners**
2. 点击 **New Runner**
3. 复制显示的 Token

### 运行 Runner

```bash
# 直接运行（测试用）
act_runner daemon

# 或作为系统服务运行（推荐）
sudo tee /etc/systemd/system/gitea-act-runner.service > /dev/null <<EOF
[Unit]
Description=Gitea Act Runner
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt
ExecStart=/usr/local/bin/act_runner daemon
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl daemon-reload
sudo systemctl enable gitea-act-runner
sudo systemctl start gitea-act-runner
sudo systemctl status gitea-act-runner
```

## 解决方案二：注册带有 ubuntu-latest 标签的 Runner

如果你想使用 `ubuntu-latest` 标签，注册时需要指定：

```bash
act_runner register \
  --instance <your-gitea-url> \
  --token <runner-token> \
  --name my-runner \
  --labels ubuntu-latest:docker://node:20-bullseye
```

## 验证 Runner 状态

### 1. 检查 Runner 是否运行

```bash
# 检查进程
ps aux | grep act_runner

# 检查服务状态
sudo systemctl status gitea-act-runner

# 查看日志
sudo journalctl -u gitea-act-runner -f
```

### 2. 在 Gitea 中查看 Runner

1. 进入 **Site Administration** → **Actions** → **Runners**
2. 应该能看到你的 Runner 显示为 **在线** 状态
3. 检查 Runner 的标签是否包含 `self-hosted` 或 `ubuntu-latest`

### 3. 测试工作流

1. 在 Gitea 仓库中进入 **Actions** 标签页
2. 选择 **Deploy to Server** 工作流
3. 点击 **Run workflow**
4. 应该不再显示"没有匹配的 Runner"错误

## 常见问题

### Runner 注册失败

**错误：连接被拒绝**
- 检查 Gitea URL 是否正确
- 确保 Gitea Actions 已启用
- 检查网络连接

**错误：Token 无效**
- 确保从 Gitea 正确复制了 Token
- Token 有时效性，如果过期需要重新生成

### Runner 显示离线

1. **检查 Runner 进程**：
   ```bash
   ps aux | grep act_runner
   ```

2. **重启 Runner**：
   ```bash
   sudo systemctl restart gitea-act-runner
   ```

3. **查看日志**：
   ```bash
   sudo journalctl -u gitea-act-runner -n 50
   ```

### 工作流仍然找不到 Runner

1. **检查标签匹配**：
   - 工作流使用 `runs-on: self-hosted`
   - Runner 必须注册时包含 `self-hosted` 标签，或者不指定标签（默认匹配）

2. **重新注册 Runner**：
   ```bash
   # 停止 Runner
   sudo systemctl stop gitea-act-runner
   
   # 删除旧配置（通常在 ~/.config/act_runner/）
   rm -rf ~/.config/act_runner
   
   # 重新注册
   act_runner register --instance <url> --token <token> --name my-runner --labels self-hosted
   
   # 启动 Runner
   sudo systemctl start gitea-act-runner
   ```

## 快速检查清单

- [ ] Act Runner 已下载并安装
- [ ] Runner 已成功注册
- [ ] Runner 正在运行（`ps aux | grep act_runner`）
- [ ] 在 Gitea 中能看到 Runner 显示为在线
- [ ] Runner 标签包含 `self-hosted`（或不指定标签）
- [ ] 工作流文件使用 `runs-on: self-hosted`
- [ ] Gitea Secrets 已配置（SERVER_HOST, SERVER_USERNAME, SERVER_SSH_KEY）

## 下一步

完成 Runner 设置后：
1. 推送代码触发工作流，或
2. 在 Gitea Actions 页面手动触发工作流
3. 查看工作流执行日志

如果还有问题，查看 Gitea 和 Runner 的日志获取详细错误信息。