novalon-website/woodpecker-debug-guide.md

Woodpecker CI 自动触发问题诊断指南

🔍 问题现象

• ✅ Git Webhook 推送成功
• ✅ 手动触发 CI 可以工作
• ❌ 推送代码后 CI 不会自动触发
• ❌ Woodpecker CI 设置中 "批准要求" 已改为 "无"

---

📝 需要在生产环境执行的命令

1. 查看 Woodpecker CI 日志

# SSH 到 Woodpecker CI 服务器
ssh user@139.155.109.62

# 查看 Woodpecker 容器日志
docker logs woodpecker-server --tail 100

# 查看 Webhook 相关日志
docker logs woodpecker-server --tail 200 2>&1 | grep -i "webhook"

# 查看仓库相关日志
docker logs woodpecker-server --tail 200 2>&1 | grep -i "novalon-website"

# 查看错误日志
docker logs woodpecker-server --tail 200 2>&1 | grep -iE "(error|fail|warn)"

2. 检查 Woodpecker CI 环境变量

# 查看 Woodpecker 环境变量
docker exec woodpecker-server env | grep WOODPECKER

# 关键环境变量检查
WOODPECKER_HOST                    # 应该设置为服务器地址
WOODPECKER_WEBHOOK_HOST            # Webhook 地址
WOODPECKER_OPEN                    # 是否开放访问
WOODPECKER_DEFAULT_PIPELINE        # 默认 Pipeline 配置

3. 检查 Webhook 接收情况

# 实时查看日志
docker logs woodpecker-server -f

# 然后推送代码，观察日志输出

---

🔧 常见问题及解决方案

问题 1: Webhook 地址配置错误

症状: Webhook 发送成功，但 Woodpecker 没有响应

检查:

# 检查 WOODPECKER_HOST
docker exec woodpecker-server env | grep WOODPECKER_HOST

# 应该返回类似：
# WOODPECKER_HOST=https://ci.f.novalon.cn

解决:

# 修改环境变量
docker stop woodpecker-server
docker rm woodpecker-server

# 重新启动，设置正确的 HOST
docker run -d \
  --name=woodpecker-server \
  -e WOODPECKER_HOST=https://ci.f.novalon.cn \
  -e WOODPECKER_WEBHOOK_HOST=https://ci.f.novalon.cn \
  # ... 其他配置
  woodpeckerci/woodpecker-server:latest

---

问题 2: Webhook Secret 不匹配

症状: Webhook 返回 401 Unauthorized

检查:

# 检查 Git Webhook 的 Secret
curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-GitHub-Event: push" \
  # ... 其他 headers \
  http://your-woodpecker-server/hook

解决:

1. 在 Woodpecker CI 中设置 WOODPECKER_WEBHOOK_SECRET
2. 在 Git Webhook 中配置相同的 Secret

---

问题 3: 仓库未正确同步

症状: Woodpecker 日志显示 "repository not found"

检查:

# 检查仓库是否在 Woodpecker 中正确注册
docker exec woodpecker-server sqlite3 /var/lib/woodpecker/woodpecker.sqlite \
  "SELECT * FROM repos WHERE repo_full_name = 'novalon/novalon-website';"

解决:

1. 在 Woodpecker CI Web 界面中删除仓库
2. 重新同步仓库
3. 重新激活仓库

---

问题 4: 分支过滤配置问题

症状: Webhook 接收成功，但 Pipeline 未创建

检查:

# 查看 Woodpecker 日志中关于分支的日志
docker logs woodpecker-server --tail 200 2>&1 | grep -i "branch"

可能的原因:

• Woodpecker 全局配置中限制了某些分支
• 仓库设置中的分支保护

解决:

1. 检查 Woodpecker 全局配置
2. 检查仓库设置中的分支过滤

---

问题 5: 数据库问题

症状: Woodpecker 日志显示数据库错误

检查:

# 检查数据库连接
docker logs woodpecker-server 2>&1 | grep -i "database\|sqlite\|mysql\|postgres"

解决:

1. 检查数据库服务是否运行
2. 检查数据库连接配置
3. 检查数据库权限

---

🧪 测试 Webhook 接收

在 Woodpecker CI 服务器上执行：

# 1. 启动日志监控
docker logs woodpecker-server -f &

# 2. 在另一个终端推送代码
# git push origin release/v1.0.0

# 3. 观察日志输出
# 应该看到类似：
# "received webhook from gitea"
# "found repository novalon/novalon-website"
# "creating pipeline for push event"

---

📊 诊断清单

请提供以下信息：

1. Woodpecker CI 日志输出

docker logs woodpecker-server --tail 100 > /tmp/woodpecker-logs.txt
cat /tmp/woodpecker-logs.txt

2. Webhook 推送详情

在 Git 仓库的 Webhook 设置中：

• 点击最新的推送记录
• 查看 Request Body
• 查看 Response Body
• 查看 HTTP Status Code

3. Woodpecker CI 环境变量

docker exec woodpecker-server env | grep WOODPECKER > /tmp/woodpecker-env.txt
cat /tmp/woodpecker-env.txt

---

🎯 快速修复方案

如果日志查看困难，可以尝试以下方案：

方案 A: 重启 Woodpecker CI

docker restart woodpecker-server
docker restart woodpecker-agent

方案 B: 重新同步仓库

1. 在 Woodpecker CI Web 界面中删除 novalon/novalon-website 仓库
2. 在设置中重新同步仓库列表
3. 重新激活仓库
4. 重新配置仓库设置（批准要求改为 "无"）

方案 C: 使用 API 触发（备选方案）

如果自动触发始终无法工作，可以使用 API 手动触发：

# 获取 Woodpecker Token
# 在 Woodpecker CI 用户设置中生成

# 使用 API 触发 Pipeline
curl -X POST \
  "https://ci.f.novalon.cn/api/repos/novalon/novalon-website/pipelines" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "release/v1.0.0",
    "event": "push"
  }'

---

📞 联系支持

如果以上方法都无法解决问题：

1. 收集所有日志和配置信息
2. 访问 Woodpecker CI GitHub Issues: https://github.com/woodpecker-ci/woodpecker/issues
3. 提供详细的错误信息和环境配置

---

最后更新: 2026-03-28