novalon-website/woodpecker-debug-guide.md

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

## 🔍 问题现象

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

---

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

### 1. 查看 Woodpecker CI 日志

```bash
# 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 环境变量

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

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

### 3. 检查 Webhook 接收情况

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

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

---

## 🔧 常见问题及解决方案

### 问题 1: Webhook 地址配置错误

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

**检查**:
```bash
# 检查 WOODPECKER_HOST
docker exec woodpecker-server env | grep WOODPECKER_HOST

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

**解决**:
```bash
# 修改环境变量
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

**检查**:
```bash
# 检查 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"

**检查**:
```bash
# 检查仓库是否在 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 未创建

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

**可能的原因**:
- Woodpecker 全局配置中限制了某些分支
- 仓库设置中的分支保护

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

---

### 问题 5: 数据库问题

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

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

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

---

## 🧪 测试 Webhook 接收

在 Woodpecker CI 服务器上执行：

```bash
# 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 日志输出
```bash
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 环境变量
```bash
docker exec woodpecker-server env | grep WOODPECKER > /tmp/woodpecker-env.txt
cat /tmp/woodpecker-env.txt
```

---

## 🎯 快速修复方案

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

### 方案 A: 重启 Woodpecker CI

```bash
docker restart woodpecker-server
docker restart woodpecker-agent
```

### 方案 B: 重新同步仓库

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

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

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

```bash
# 获取 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