DDUp/docs/gitea-runner-setup.md

# Gitea Actions Runner 安装和排查指南

## 问题：工作流一直显示"等待中"

如果 Gitea Actions 工作流一直显示"等待中"状态，通常是因为 Runner 没有正确运行或标签不匹配。

---

## 第一步：在 Gitea 中获取 Runner 注册信息

1. **登录 Gitea**（`http://124.221.55.225:3000`）
2. **进入仓库**：`Rocky/DDUp`
3. **进入 Settings（设置）** -> **Actions** -> **Runners**
4. **点击 "Add Runner"** 或 **"注册 Runner"**
5. **选择平台**：`linux` / `amd64`
6. **复制注册命令**（类似下面的格式）：

```bash
# 示例命令（实际命令以 Gitea 页面为准）
./gitea-runner register \
  --instance http://124.221.55.225:3000 \
  --token <你的TOKEN> \
  --labels "self-hosted:linux:amd64" \
  --name "vitals-deploy-runner"
```

---

## 第二步：在服务器上安装和注册 Runner

SSH 登录到你的服务器（`VM-16-14-ubuntu`）：

```bash
ssh root@VM-16-14-ubuntu
```

### 1. 创建 Runner 目录

```bash
mkdir -p /opt/gitea-runner
cd /opt/gitea-runner
```

### 2. 下载 Gitea Runner

```bash
# 下载最新版本的 Gitea Runner
curl -L https://dl.gitea.com/runner/gitea-runner-linux-amd64 -o gitea-runner
chmod +x gitea-runner
```

### 3. 注册 Runner

使用第一步从 Gitea 页面复制的注册命令（替换 `<你的TOKEN>`）：

```bash
./gitea-runner register \
  --instance http://124.221.55.225:3000 \
  --token <你的TOKEN> \
  --labels "self-hosted:linux:amd64" \
  --name "vitals-deploy-runner"
```

**重要提示：**
- 注册时设置的 `--labels` 必须包含 `self-hosted`
- 如果设置了多个标签（如 `self-hosted:linux:amd64`），在 `deploy.yml` 中需要匹配这些标签

### 4. 将 Runner 配置为系统服务

创建 systemd 服务文件：

```bash
cat > /etc/systemd/system/gitea-runner.service << 'EOF'
[Unit]
Description=Gitea Actions Runner
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/gitea-runner
ExecStart=/opt/gitea-runner/gitea-runner daemon
Restart=always
RestartSec=5s

[Install]
WantedBy=multi-user.target
EOF
```

启动并启用服务：

```bash
systemctl daemon-reload
systemctl enable gitea-runner
systemctl start gitea-runner
```

### 5. 检查 Runner 状态

```bash
# 查看服务状态
systemctl status gitea-runner

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

---

## 第三步：验证 Runner 是否在线

1. **回到 Gitea 仓库页面**
2. **进入 Settings -> Actions -> Runners**
3. **检查 Runner 列表**，应该能看到你刚注册的 Runner，状态应该是 **"在线"** 或 **"Online"**

如果显示 **"离线"** 或 **"Offline"**，检查：
- Runner 服务是否运行：`systemctl status gitea-runner`
- 网络连接是否正常：Runner 需要能访问 `http://124.221.55.225:3000`
- 防火墙是否阻止了连接

---

## 第四步：检查 deploy.yml 中的标签匹配

打开 `.gitea/workflows/deploy.yml`，确认 `runs-on` 与 Runner 注册时的标签匹配：

**情况 A：** 如果注册时标签是 `self-hosted`（只有一个标签）

```yaml
runs-on: self-hosted
```

**情况 B：** 如果注册时标签是 `self-hosted:linux:amd64`（多个标签）

```yaml
runs-on: [self-hosted, linux, amd64]
```

或者：

```yaml
runs-on: self-hosted:linux:amd64
```

---

## 第五步：重新触发工作流

1. **修改并推送代码**（触发新的工作流运行）：

```bash
# 在本地或服务器上
git commit --allow-empty -m "trigger: test gitea actions"
git push origin main
```

2. **在 Gitea 中查看 Actions 页面**，应该能看到新的工作流开始执行

---

## 常见问题排查

### 问题 1：Runner 显示离线

**解决方案：**
```bash
# 重启 Runner 服务
systemctl restart gitea-runner

# 查看详细日志
journalctl -u gitea-runner -n 50
```

### 问题 2：工作流一直等待，Runner 在线但就是不执行

**可能原因：**
- 标签不匹配
- Runner 版本过旧

**解决方案：**
1. 检查 `deploy.yml` 中的 `runs-on` 是否与 Runner 标签完全匹配
2. 更新 Runner 到最新版本：

```bash
cd /opt/gitea-runner
curl -L https://dl.gitea.com/runner/gitea-runner-linux-amd64 -o gitea-runner
chmod +x gitea-runner
systemctl restart gitea-runner
```

### 问题 3：Runner 执行失败，提示权限错误

**解决方案：**
确保 Runner 有执行脚本和 Docker 的权限：

```bash
# 确保 deploy.sh 有执行权限
chmod +x /opt/apps/vitals/deploy.sh

# 确保 Runner 用户（通常是 root）在 docker 组中
usermod -aG docker root
```

### 问题 4：无法连接到 Gitea 服务器

**解决方案：**
检查网络连接和防火墙：

```bash
# 测试连接
curl -I http://124.221.55.225:3000

# 如果 Gitea 使用 HTTPS，确保 Runner 能访问 HTTPS 地址
```

---

## 验证部署脚本

在手动测试部署脚本是否正常：

```bash
# SSH 到服务器
ssh root@VM-16-14-ubuntu

# 测试脚本
/opt/apps/vitals/deploy.sh
```

如果手动执行成功，但通过 Gitea Actions 执行失败，检查：
- Runner 的工作目录
- 环境变量
- 权限问题

---

## 快速检查清单

- [ ] Gitea Actions 已启用
- [ ] Runner 已下载并注册
- [ ] Runner 服务正在运行（`systemctl status gitea-runner`）
- [ ] Runner 在 Gitea 中显示为"在线"
- [ ] `deploy.yml` 中的 `runs-on` 标签与 Runner 标签匹配
- [ ] `deploy.sh` 有执行权限
- [ ] 手动执行 `deploy.sh` 可以成功

完成以上所有步骤后，工作流应该能正常执行了。