# Woodpecker CI 自动触发问题完整排查指南

## 📋 问题现象

- ✅ 手动触发 CI 可以正常工作
- ❌ 推送代码后 CI 不会自动触发

---

## 🔍 排查步骤（按优先级）

### 步骤 1: 检查 Git Webhook 配置 ⭐⭐⭐⭐⭐

**这是最可能的原因！**

#### 操作步骤

1. 访问 Git 仓库设置页面：
   ```
   https://git.f.novalon.cn/novalon/novalon-website/settings/hooks
   ```

2. 检查是否存在 Woodpecker CI 的 Webhook：
   - ✅ 如果存在 → 继续步骤 3
   - ❌ 如果不存在 → 执行步骤 2

3. 查看 Webhook 详情：
   - **URL**: 应该是 `http://woodpecker-server/hook` 或类似格式
   - **Secret**: 如果配置了，确保与 Woodpecker CI 一致
   - **Trigger events**: 必须包含 `Push events`

4. 查看 "Recent Deliveries"：
   - ✅ 如果有记录 → 查看响应状态码（应该是 200）
   - ❌ 如果没有记录 → Webhook 未触发，检查触发事件配置

#### 如何添加 Webhook

如果 Webhook 不存在，需要添加：

```bash
# Webhook URL 格式
http://your-woodpecker-server/hook

# 或使用 Secret
http://your-woodpecker-server/hook?secret=your-secret

# 触发事件
✅ Push events
✅ Pull request events
✅ Tag push events（可选）
```

---

### 步骤 2: 检查 Woodpecker CI 仓库设置 ⭐⭐⭐⭐

#### 操作步骤

1. 访问 Woodpecker CI Web 界面
2. 选择 `novalon/novalon-website` 仓库
3. 点击仓库设置（Settings）

#### 检查项

- **Active**: ✅ 必须启用
- **Trusted**: ✅ 建议启用（允许使用 volumes 等特权操作）
- **Protected**: ❌ 如果启用，会限制自动触发
- **Configuration**: 确认配置文件路径正确（`.woodpecker.yml`）

---

### 步骤 3: 检查 Woodpecker CI 全局配置 ⭐⭐⭐

如果可以访问 Woodpecker CI 服务器：

#### 检查环境变量

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

# 关键环境变量
WOODPECKER_OPEN=true                    # 允许公开访问
WOODPECKER_HOST=http://your-server      # 服务器地址
WOODPECKER_WEBHOOK_HOST=http://your-server  # Webhook 地址
```

#### 检查日志

```bash
# 查看 Woodpecker CI 日志
docker logs woodpecker-server --tail 100

# 查找 webhook 相关日志
docker logs woodpecker-server 2>&1 | grep -i webhook
```

---

### 步骤 4: 检查配置文件语法 ⭐⭐

#### 使用 YAML 验证器

```bash
# 安装 yamllint
pip install yamllint

# 验证配置文件
yamllint .woodpecker.yml
```

#### 在线验证

访问 https://www.yamllint.com/ 粘贴配置文件内容验证。

---

### 步骤 5: 检查提交信息 ⭐

确认提交信息不包含跳过 CI 的关键词：

```bash
# 查看最近的提交信息
git log --oneline -5

# 跳过 CI 的关键词（避免使用）
[skip ci]
[ci skip]
[no ci]
***NO_CI***
```

---

## 🛠️ 快速测试方案

### 方案 1: 使用简化的配置文件

创建 `.woodpecker-test.yml`：

```yaml
steps:
  test:
    image: alpine
    commands:
      - echo "CI is working!"
```

然后在 Woodpecker CI 设置中将配置文件改为 `.woodpecker-test.yml`。

### 方案 2: 手动触发测试

1. 在 Woodpecker CI 界面手动触发 Pipeline
2. 观察是否能正常执行
3. 如果手动触发正常，说明配置文件没问题，问题在 Webhook

### 方案 3: 检查 Webhook 发送记录

在 Git 仓库的 Webhook 设置中：
1. 找到 "Recent Deliveries"
2. 查看最近的发送记录
3. 点击查看详情：
   - **Request**: 查看发送的数据
   - **Response**: 查看服务器响应
   - **Status code**: 应该是 200

---

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

### 问题 1: Webhook 发送失败（404 Not Found）

**原因**: Woodpecker CI 仓库未激活

**解决**:
1. 访问 Woodpecker CI Web 界面
2. 找到并激活 `novalon/novalon-website` 仓库

---

### 问题 2: Webhook 发送失败（401 Unauthorized）

**原因**: Webhook Secret 不匹配

**解决**:
1. 检查 Woodpecker CI 的 `WOODPECKER_WEBHOOK_SECRET` 配置
2. 在 Git Webhook 设置中配置相同的 Secret

---

### 问题 3: Webhook 发送成功但 CI 未触发

**原因**: 配置文件中的 `when` 条件限制

**解决**:
1. 检查配置文件中的 `when` 条件
2. 确保包含正确的分支和事件
3. 临时移除 `when` 条件测试

---

### 问题 4: Woodpecker CI 日志显示 "repo not found"

**原因**: 仓库权限问题

**解决**:
1. 在 Woodpecker CI 中重新授权访问仓库
2. 检查 OAuth token 是否过期

---

## 🎯 推荐操作流程

### 立即执行（5分钟）

1. **检查 Git Webhook 配置**
   - 访问仓库设置 → Webhooks
   - 确认有 Woodpecker CI 的 Webhook
   - 查看 "Recent Deliveries"

2. **手动触发测试**
   - 在 Woodpecker CI 中手动触发 Pipeline
   - 确认配置文件正确

### 短期执行（30分钟）

1. **重新配置 Webhook**（如果需要）
   - 删除旧的 Webhook
   - 添加新的 Webhook
   - 测试发送

2. **检查 Woodpecker CI 设置**
   - 确认仓库已激活
   - 启用 "Trusted" 选项
   - 取消分支保护

### 中期执行（如果问题持续）

1. **查看 Woodpecker CI 日志**
   - 检查服务器日志
   - 查找错误信息

2. **联系管理员**
   - 如果没有服务器访问权限
   - 提供详细的错误信息

---

## 📝 诊断信息收集

如果以上步骤都无法解决，请收集以下信息：

```bash
# 1. Git Webhook 配置截图
# 2. Webhook "Recent Deliveries" 截图
# 3. Woodpecker CI 仓库设置截图
# 4. 手动触发的 Pipeline 日志
# 5. 配置文件内容
```

---

## ✅ 成功标志

当以下条件满足时，CI 应该能够自动触发：

- ✅ Git Webhook 配置正确且有发送记录
- ✅ Woodpecker CI 仓库已激活
- ✅ 配置文件语法正确
- ✅ when 条件包含当前分支
- ✅ 提交信息不包含跳过关键词

---

**最后更新**: 2026-03-28