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. 复制注册命令（类似下面的格式）：

# 示例命令（实际命令以 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）：

ssh root@VM-16-14-ubuntu

1. 创建 Runner 目录

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

2. 下载 Gitea Runner

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

3. 注册 Runner

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

./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 服务文件：

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

启动并启用服务：

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

5. 检查 Runner 状态

# 查看服务状态
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（只有一个标签）

runs-on: self-hosted

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

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

或者：

runs-on: self-hosted:linux:amd64

---

第五步：重新触发工作流

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

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

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

---

常见问题排查

问题 1：Runner 显示离线

解决方案：

# 重启 Runner 服务
systemctl restart gitea-runner

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

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

可能原因：

• 标签不匹配
• Runner 版本过旧

解决方案：

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

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 的权限：

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

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

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

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

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

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

---

验证部署脚本

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

# 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 可以成功

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