184 lines
7.0 KiB
Markdown
184 lines
7.0 KiB
Markdown
# Gitea Git Hooks vs Woodpecker CI — 方案评估报告
|
||
|
||
> 报告日期: 2026-07-12
|
||
> 评估对象: cma-management 项目全流程自动化
|
||
> 场景: 单服务器、单开发者（全栈Bot）、前端Vue3 + 后端FastAPI
|
||
|
||
---
|
||
|
||
## 1. 当前环境状态
|
||
|
||
| 组件 | 版本 | 状态 |
|
||
|------|------|------|
|
||
| Gitea | 1.22.6 (Docker) | ✅ 正常运行 |
|
||
| Woodpecker Server | v3.12.0 (Docker) | ❌ OAuth集成故障 |
|
||
| Woodpecker Agent | v3.12.0 (Docker) | ❌ 无任务可执行 |
|
||
| cma-management | main分支 | ✅ Git仓库正常 |
|
||
|
||
---
|
||
|
||
## 2. 核心发现
|
||
|
||
### Woodpecker CI 故障根因
|
||
|
||
```
|
||
GetRepo: invalid character 'o' in literal null (expecting 'u')
|
||
```
|
||
|
||
- Woodpecker v3.12.0 调用 Gitea API 获取仓库信息时，Gitea 返回了非预期的 null 响应
|
||
- JSON 解析器期望一个对象（`{`），但收到了 `null`（字母 `n` 的 ascii 是 110，`o` 是 111 — 所以错误信息中出现了 `'o'` 字符）
|
||
- 这是一个 **Woodpecker 与 Gitea 1.22 之间的兼容性 bug**，需要等待上游修复
|
||
- Cron 任务每 30 分钟重复失败，Webhook 调用也返回 400
|
||
- **结论：Woodpecker CI 在当前环境下不可用，且无短期可修复的 workaround**
|
||
|
||
### Gitea Git Hooks 机制已验证
|
||
|
||
Gitea 使用 `hooks/post-receive` → `hooks/post-receive.d/*` 的 hook 分发机制：
|
||
|
||
```
|
||
hooks/post-receive # 主脚本（Gitea自动生成）
|
||
hooks/post-receive.d/
|
||
├── gitea # Gitea内部hook（处理Webhook/Gitea Actions等）
|
||
└── deploy # 自定义部署hook ← 我们添加的
|
||
```
|
||
|
||
关键发现：
|
||
- Hook 脚本在 **Gitea Docker 容器内**以 `git` 用户（UID 1000）身份运行
|
||
- 容器与宿主机共享 Gitea 数据卷，但无法直接访问宿主机文件系统或 systemd
|
||
- Gitea 容器内已安装 SSH 客户端，可通过 SSH 回到宿主机执行命令
|
||
|
||
---
|
||
|
||
## 3. 方案对比
|
||
|
||
| 维度 | Git Hooks ✅（本方案） | Woodpecker CI ❌ |
|
||
|------|:---------------------:|:----------------:|
|
||
| **实现复杂度** | ★☆☆ 极简 — 1个shell脚本 | ★★★ 复杂 — 需要修复OAuth bug |
|
||
| **运维成本** | ★☆☆ 零 — 无额外服务 | ★★★ 高 — Docker容器+SSH密钥+Agent维护 |
|
||
| **故障排查** | ★★☆ 直接看push输出 | ★★★ 日志链路长：Gitea→OAuth→Woodpecker→Agent→容器 |
|
||
| **流水线可视化** | ❌ 无Web UI（push输出可见） | ✅ 有Web UI（但当前不可用） |
|
||
| **安全性（沙箱隔离）** | ❌ 直接在宿主机执行 | ✅ Docker容器隔离 |
|
||
| **多步骤并行** | ❌ 顺序执行 | ✅ 支持并行 |
|
||
| **Secrets管理** | ⚠️ 使用现有SSH密钥 | ✅ 内置Secrets管理 |
|
||
| **是否满足当前需求** | ✅ **完全满足** | ❌ 当前不可用 |
|
||
| **资源占用** | 0（零额外资源） | ~256MB内存 + Docker容器 |
|
||
| **PR集成** | 不需要（单开发者） | 需要但用不到 |
|
||
| **push到部署耗时** | ~10-15秒（含build） | ~20-30秒（含容器启动） |
|
||
|
||
### 详细分析
|
||
|
||
#### Git Hooks 为什么更适合这个场景？
|
||
|
||
1. **单服务器** — 所有操作都在本机，SSH回环比Docker容器隔离更直接
|
||
2. **单开发者（Bot）** — 不需要多用户协作、不需要PR流水线
|
||
3. **已有 deploy.sh** — 部署逻辑已封装好，hook只需要触发它
|
||
4. **零额外基础设施** — 不增加新的Docker容器，不增加API调用链路
|
||
5. **即时反馈** — `git push` 输出中直接看到构建部署日志
|
||
6. **Woodpecker 方案做了多余的事** — 它的 `.woodpecker/main.yml` 用 SSH key 从容器SSH回宿主机部署，而我们直接用 Gitea hook SSH 回宿主机 — 逻辑完全相同，但少了一层 Woodpecker 中间件
|
||
|
||
#### Woodpecker 的优势（在这个场景下用不到）
|
||
|
||
- 多容器环境下的沙箱隔离 → 单服务器，信任域内
|
||
- 并行步骤/矩阵构建 → 构建+部署是线性流程
|
||
- Web UI 流水线可视化 → push输出可见，部署频率低（一天几次）
|
||
|
||
---
|
||
|
||
## 4. 推荐方案：方案A（Git Hooks）
|
||
|
||
**明确推荐 Git Hooks 方案，并已实际部署验证通过。**
|
||
|
||
### 已实施的实现
|
||
|
||
#### a) Gitea Post-Receive Hook
|
||
|
||
**位置**: `/data/git/repositories/sxbh_admin/cma-management.git/hooks/post-receive.d/deploy`
|
||
（实际路径: `/root/docker/gitea/gitea/data/git/repositories/sxbh_admin/cma-management.git/hooks/post-receive.d/deploy`）
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# 每次 push 到 main 分支后，通过 SSH 到宿主机执行部署
|
||
set -e
|
||
|
||
HOST="172.17.0.1"
|
||
SSH_KEY="/data/git/.ssh/id_ed25519"
|
||
SSH_CMD="ssh -i ${SSH_KEY} -o StrictHostKeyChecking=no root@${HOST}"
|
||
|
||
while read oldrev newrev refname; do
|
||
if [ "$refname" = "refs/heads/main" ]; then
|
||
${SSH_CMD} '
|
||
cd /root/cma-management
|
||
git pull origin main
|
||
bash deploy.sh
|
||
'
|
||
fi
|
||
done
|
||
```
|
||
|
||
#### b) 部署脚本（已修复）
|
||
|
||
**位置**: `/root/cma-management/deploy.sh`
|
||
|
||
修复内容：
|
||
- 移除 `pnpm build --no-frozen-lockfile`（Vite不认识该选项）
|
||
- 后端 pip install 使用 `source venv/bin/activate`（解决 Ubuntu PEP 668 externally-managed-environment）
|
||
|
||
#### c) SSH 密钥配置
|
||
|
||
- 使用已有的 `id_ed25519_ci_deploy` 密钥（原为 Woodpecker 准备）
|
||
- 公钥已添加到宿主机的 `~/.ssh/authorized_keys`
|
||
- 私钥存放在 Gitea 容器内 `/data/git/.ssh/id_ed25519`
|
||
- 容器内 `git` 用户可读
|
||
|
||
### 工作流程
|
||
|
||
```
|
||
开发者 push → Gitea 接收 → post-receive hook 触发
|
||
→ post-receive.d/deploy 执行
|
||
→ SSH 到宿主机（172.17.0.1）
|
||
→ cd /root/cma-management
|
||
→ git pull origin main
|
||
→ bash deploy.sh
|
||
→ [1/4] pnpm build（前端构建）
|
||
→ [2/4] cp dist/* /var/www/cma/（前端部署）
|
||
→ [3/4] pip install（后端依赖更新）
|
||
→ [4/4] systemctl restart cma-backend（后端重启）
|
||
← 部署完成 ✓
|
||
← SSH 返回
|
||
← push 完成
|
||
```
|
||
|
||
### 验证结果
|
||
|
||
已通过实际 push 验证（3次自动部署均成功）：
|
||
- 前端构建耗时: ~8-9秒
|
||
- 前端部署: ~1秒
|
||
- 后端依赖更新: ~1秒
|
||
- 后端服务重启: ~2秒
|
||
- **总计: ~12-15秒完成全流程部署**
|
||
|
||
---
|
||
|
||
## 5. 后续建议
|
||
|
||
### Woodpecker CI 保留（可选）
|
||
- **不要删除** Woodpecker 容器，上游修复后可以重新启用
|
||
- 未来如果需要多环境部署、并行测试等高级功能，Woodpecker 仍是更好的选择
|
||
- 当前版本（v3.12.0 + Gitea 1.22）存在兼容性问题，升级 Gitea 或 Woodpecker 任一版本可能修复
|
||
|
||
### 扩展考虑
|
||
- 如果需要部署失败通知，可以在 hook 中添加企业微信/钉钉 webhook
|
||
- 如果需要增量构建，可以在 hook 中检测改动的文件路径（仅构建有改动的部分）
|
||
- 如果需要回滚，hook 可以保留上次构建的备份
|
||
|
||
---
|
||
|
||
## 6. 文件变更清单
|
||
|
||
| 文件 | 操作 | 说明 |
|
||
|------|------|------|
|
||
| `hooks/post-receive.d/deploy` | **新建** | Gitea 自动部署 hook |
|
||
| `/root/cma-management/deploy.sh` | **修改** | 移除 `--no-frozen-lockfile`，使用 venv pip |
|
||
| `/root/cma-management/scripts/post-receive-hook.sh` | **新建** | Hook 脚本的版本控制副本 |
|
||
| `/root/cma-management/docs/ci-comparison-report.md` | **新建** | 本报告 |
|