feat: 添加 Gitea webhook 自动部署功能
- 新增独立的 webhook 服务 (Go, 端口 9000) - HMAC-SHA256 签名验证 - 零停机热更新部署 - 自动清理旧镜像 - 完整配置文档 WEBHOOK_SETUP.md - 精简 README 版本历史为表格形式
This commit is contained in:
CHE LIANG ZHAO
490
WEBHOOK_SETUP.md
Normal file
490
WEBHOOK_SETUP.md
Normal file
@@ -0,0 +1,490 @@
|
||||
# 自动部署配置指南
|
||||
|
||||
这个指南将帮助你配置 Gitea webhook 以实现代码推送时的自动部署。
|
||||
|
||||
## 整体架构
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A[🏠 Gitea<br/>代码仓库] -->|Push Event| B[🔗 Webhook Service<br/>Port 9000]
|
||||
B -->|验证签名| C{签名有效?}
|
||||
C -->|❌ 无效| D[拒绝请求]
|
||||
C -->|✅ 有效| E{主分支?}
|
||||
E -->|❌ 否| F[跳过部署]
|
||||
E -->|✅ 是| G[📜 Deploy Script<br/>deploy.sh]
|
||||
G --> H[📥 git pull<br/>拉取最新代码]
|
||||
H --> I[🔨 热更新部署<br/>零停机]
|
||||
I --> J[🧹 清理旧镜像]
|
||||
J --> K[🏥 健康检查]
|
||||
K --> L[✅ 部署完成]
|
||||
|
||||
style A fill:#f9f,stroke:#333
|
||||
style B fill:#bbf,stroke:#333
|
||||
style G fill:#bfb,stroke:#333
|
||||
style L fill:#9f9,stroke:#333
|
||||
```
|
||||
|
||||
## 第一步：生成 Webhook Secret
|
||||
|
||||
打开终端，运行以下命令生成安全的随机密钥：
|
||||
|
||||
```bash
|
||||
# Linux / macOS
|
||||
openssl rand -hex 32
|
||||
|
||||
# Windows PowerShell
|
||||
[System.BitConverter]::ToString([System.Security.Cryptography.RandomNumberGenerator]::GetBytes(32)).Replace('-','').ToLower()
|
||||
```
|
||||
|
||||
示例输出：
|
||||
```
|
||||
a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
|
||||
```
|
||||
|
||||
## 第二步：配置 docker-compose.yaml
|
||||
|
||||
编辑 `docker-compose.yaml` 文件中的 webhook 服务配置：
|
||||
|
||||
### 设置 Secret
|
||||
|
||||
```yaml
|
||||
webhook:
|
||||
environment:
|
||||
WEBHOOK_SECRET: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" # 替换为你生成的 Secret
|
||||
```
|
||||
|
||||
### 配置仓库路径（关键）
|
||||
|
||||
**重要！** 根据你的部署方式修改挂载路径：
|
||||
|
||||
#### 如果使用本地路径部署：
|
||||
|
||||
```yaml
|
||||
webhook:
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
- /home/user/billai:/app # 替换为你的实际路径
|
||||
```
|
||||
|
||||
#### 如果在云服务器上部署：
|
||||
|
||||
```yaml
|
||||
webhook:
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
- /opt/billai:/app # 替换为你的实际路径
|
||||
```
|
||||
|
||||
### 网络配置说明
|
||||
|
||||
**webhook 服务对外暴露 9000 端口**，用于接收 Gitea webhook 事件。
|
||||
|
||||
这样的好处是：
|
||||
- ✅ 支持外部 Gitea 服务器的 webhook 回调
|
||||
- ✅ 灵活的部署架构
|
||||
- ✅ 支持多种网络拓扑
|
||||
|
||||
**Webhook 访问地址：**
|
||||
|
||||
- 本地访问：`http://localhost:9000/webhook`
|
||||
- 内部网络：`http://<internal-ip>:9000/webhook`
|
||||
- 公网访问：`http://<public-ip>:9000/webhook`
|
||||
- 通过域名：`http://webhook.yourdomain.com:9000/webhook`
|
||||
|
||||
## 第三步：启动 Webhook 服务
|
||||
|
||||
```bash
|
||||
# 进入项目根目录
|
||||
cd /path/to/billai
|
||||
|
||||
# 构建并启动 webhook 服务
|
||||
docker-compose up -d webhook
|
||||
|
||||
# 验证服务是否启动
|
||||
docker-compose logs webhook
|
||||
|
||||
# 测试健康检查
|
||||
curl http://localhost:9000/health
|
||||
```
|
||||
|
||||
输出应该显示：
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"time": "2026-01-13T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## 第四步：配置 Gitea Webhook
|
||||
|
||||
### 4.1 进入 Gitea 仓库设置
|
||||
|
||||
1. 打开 Gitea 管理界面
|
||||
2. 找到你的 BillAI 仓库
|
||||
3. 点击 **设置 (Settings)** → **Webhooks**
|
||||
|
||||
### 4.2 添加新 Webhook
|
||||
|
||||
点击 "添加 Webhook (Add Webhook)" 按钮，选择 "Gitea"
|
||||
|
||||
### 4.3 填写 Webhook 配置
|
||||
|
||||
| 字段 | 值 |
|
||||
|------|-----|
|
||||
| **目标 URL** | `http://<your-server-ip>:9000/webhook` |
|
||||
| **内容类型** | `application/json` |
|
||||
| **密钥** | `a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6` (你生成的 Secret) |
|
||||
| **事件** | ✓ 推送事件 (Push Events) |
|
||||
| **活跃** | ✓ 是 |
|
||||
|
||||
### 4.4 配置说明
|
||||
|
||||
#### 目标 URL
|
||||
|
||||
根据 Gitea 部署方式选择合适的 URL：
|
||||
|
||||
**情况 1：Gitea 和 webhook 都在同一台机器**
|
||||
|
||||
```
|
||||
http://localhost:9000/webhook
|
||||
```
|
||||
|
||||
**情况 2：Gitea 在不同机器，webhook 在 Docker**
|
||||
|
||||
使用 webhook 所在服务器的 IP 地址：
|
||||
```
|
||||
http://<webhook-server-ip>:9000/webhook
|
||||
```
|
||||
|
||||
**情况 3：使用域名访问**
|
||||
|
||||
```
|
||||
http://webhook.yourdomain.com:9000/webhook
|
||||
或
|
||||
https://webhook.yourdomain.com/webhook (需要配置反向代理处理 HTTPS)
|
||||
```
|
||||
|
||||
#### 防火墙配置
|
||||
|
||||
确保防火墙允许 9000 端口的入站连接：
|
||||
|
||||
```bash
|
||||
# Linux (ufw)
|
||||
sudo ufw allow 9000/tcp
|
||||
|
||||
# Linux (iptables)
|
||||
sudo iptables -A INPUT -p tcp --dport 9000 -j ACCEPT
|
||||
|
||||
# Windows Firewall (PowerShell)
|
||||
New-NetFirewallRule -DisplayName "Allow Webhook" -Direction Inbound -LocalPort 9000 -Protocol TCP -Action Allow
|
||||
```
|
||||
|
||||
### 4.5 测试 Webhook
|
||||
|
||||
在 Gitea webhook 设置页面，找到刚添加的 webhook，点击 "测试 (Test)" 按钮。
|
||||
|
||||
预期响应：
|
||||
```json
|
||||
{
|
||||
"message": "非主分支，跳过部署"
|
||||
}
|
||||
```
|
||||
|
||||
（这是因为测试会使用一个默认的测试分支）
|
||||
|
||||
## 第五步：网络配置
|
||||
|
||||
### 防火墙配置
|
||||
|
||||
在部署前，确保服务器防火墙允许以下端口：
|
||||
|
||||
```bash
|
||||
# 允许 9000 端口（webhook）
|
||||
sudo ufw allow 9000/tcp
|
||||
|
||||
# 允许 3000 端口（前端web）- 已配置
|
||||
sudo ufw allow 3000/tcp
|
||||
|
||||
# 允许 80 端口（HTTP，如果使用）
|
||||
sudo ufw allow 80/tcp
|
||||
|
||||
# 允许 443 端口（HTTPS，如果使用）
|
||||
sudo ufw allow 443/tcp
|
||||
```
|
||||
|
||||
### 可选：Nginx 反向代理配置
|
||||
|
||||
如果需要通过 HTTPS 访问 webhook，可以配置 Nginx 反向代理：
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 443 ssl http2;
|
||||
server_name webhook.yourdomain.com;
|
||||
|
||||
ssl_certificate /path/to/cert.pem;
|
||||
ssl_certificate_key /path/to/key.pem;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:9000;
|
||||
proxy_set_header Host $host;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
}
|
||||
|
||||
# HTTP 重定向到 HTTPS
|
||||
server {
|
||||
listen 80;
|
||||
server_name webhook.yourdomain.com;
|
||||
return 301 https://$server_name$request_uri;
|
||||
}
|
||||
```
|
||||
|
||||
## 第六步：测试自动部署
|
||||
|
||||
现在你可以测试自动部署功能：
|
||||
|
||||
```bash
|
||||
# 进入仓库目录
|
||||
cd /path/to/billai
|
||||
|
||||
# 做一些改动
|
||||
echo "# 测试自动部署" >> README.md
|
||||
|
||||
# 提交并推送到主分支
|
||||
git add .
|
||||
git commit -m "test: 测试自动部署功能"
|
||||
git push origin master
|
||||
```
|
||||
|
||||
### 监控部署过程
|
||||
|
||||
```bash
|
||||
# 查看 webhook 服务日志
|
||||
docker-compose logs -f webhook
|
||||
|
||||
# 查看部署脚本日志
|
||||
docker exec billai-webhook tail -f /tmp/billai_deploy.log
|
||||
|
||||
# 查看其他服务日志
|
||||
docker-compose logs -f server
|
||||
docker-compose logs -f web
|
||||
docker-compose logs -f analyzer
|
||||
```
|
||||
|
||||
## 常见问题排查
|
||||
|
||||
### 问题 1：Webhook 签名验证失败
|
||||
|
||||
**症状**：日志中出现 "无效的签名"
|
||||
|
||||
**解决方案**：
|
||||
- 确认 Gitea 中设置的 Secret 与 docker-compose.yaml 中的 WEBHOOK_SECRET 完全相同
|
||||
- 检查是否有多余空格或特殊字符
|
||||
|
||||
```bash
|
||||
# 在 docker-compose.yaml 中查看
|
||||
grep WEBHOOK_SECRET docker-compose.yaml
|
||||
|
||||
# 在 Gitea 中重新复制 Secret，确保没有多余空格
|
||||
```
|
||||
|
||||
### 问题 2：无法连接到 Webhook 服务
|
||||
|
||||
**症状**：Gitea webhook 测试失败
|
||||
|
||||
**解决方案**：
|
||||
1. 检查 webhook 容器是否运行：
|
||||
```bash
|
||||
docker-compose ps webhook
|
||||
```
|
||||
|
||||
2. 检查端口是否正确暴露：
|
||||
```bash
|
||||
docker-compose logs webhook | grep "listen"
|
||||
```
|
||||
|
||||
3. 检查防火墙规则：
|
||||
```bash
|
||||
# Linux
|
||||
netstat -tulpn | grep 9000
|
||||
sudo ufw status
|
||||
|
||||
# Windows
|
||||
netstat -ano | findstr 9000
|
||||
```
|
||||
|
||||
4. 测试本地连接：
|
||||
```bash
|
||||
curl http://localhost:9000/health
|
||||
```
|
||||
|
||||
5. 如果是远程连接，测试网络连通性：
|
||||
```bash
|
||||
# 从 Gitea 服务器测试
|
||||
curl http://<webhook-server-ip>:9000/health
|
||||
|
||||
netstat -ano | findstr 9000 # Windows
|
||||
```
|
||||
|
||||
4. 测试本地连接：
|
||||
|
||||
```bash
|
||||
curl http://localhost:9000/health
|
||||
```
|
||||
|
||||
### 问题 3：部署脚本无法执行
|
||||
|
||||
**症状**：日志中显示 "部署脚本执行失败"
|
||||
|
||||
**解决方案**：
|
||||
1. 检查 deploy.sh 是否存在：
|
||||
```bash
|
||||
ls -la deploy.sh
|
||||
```
|
||||
|
||||
2. 检查文件权限：
|
||||
```bash
|
||||
chmod +x deploy.sh
|
||||
```
|
||||
|
||||
3. 检查容器内的环境：
|
||||
```bash
|
||||
docker exec billai-webhook bash -c "ls -la /app/deploy.sh"
|
||||
```
|
||||
|
||||
4. 查看详细错误信息：
|
||||
```bash
|
||||
docker exec billai-webhook tail -f /tmp/billai_deploy.log
|
||||
```
|
||||
|
||||
### 问题 4：Docker 操作权限不足
|
||||
|
||||
**症状**：日志中显示 "permission denied" 或 "Cannot connect to Docker daemon"
|
||||
|
||||
**解决方案**：
|
||||
1. 检查 Docker Socket 是否正确挂载：
|
||||
```yaml
|
||||
webhook:
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock
|
||||
```
|
||||
|
||||
2. 检查 Docker Socket 权限：
|
||||
```bash
|
||||
ls -l /var/run/docker.sock
|
||||
chmod 666 /var/run/docker.sock # 可能需要 sudo
|
||||
```
|
||||
|
||||
3. 确保 webhook 容器以正确的用户运行（通常是 root）
|
||||
|
||||
### 问题 5：部署后服务无法启动
|
||||
|
||||
**症状**：健康检查超时，部署失败
|
||||
|
||||
**解决方案**：
|
||||
1. 检查 docker-compose build 是否成功：
|
||||
```bash
|
||||
docker-compose build
|
||||
```
|
||||
|
||||
2. 检查依赖服务是否启动：
|
||||
```bash
|
||||
docker-compose ps
|
||||
```
|
||||
|
||||
3. 查看各服务的详细日志：
|
||||
```bash
|
||||
docker-compose logs server
|
||||
docker-compose logs web
|
||||
docker-compose logs analyzer
|
||||
```
|
||||
|
||||
4. 增加健康检查的超时时间（修改 deploy.sh 中的 sleep 时间）
|
||||
|
||||
## 监控和维护
|
||||
|
||||
### 定期检查 Webhook 状态
|
||||
|
||||
```bash
|
||||
# 查看最近 50 条日志
|
||||
docker-compose logs --tail=50 webhook
|
||||
|
||||
# 实时监控日志
|
||||
docker-compose logs -f webhook
|
||||
```
|
||||
|
||||
### 查看部署历史
|
||||
|
||||
部署脚本的日志保存在：`/tmp/billai_deploy.log`
|
||||
|
||||
```bash
|
||||
# 查看部署历史
|
||||
docker exec billai-webhook cat /tmp/billai_deploy.log
|
||||
|
||||
# 持续监控
|
||||
docker exec billai-webhook tail -f /tmp/billai_deploy.log
|
||||
```
|
||||
|
||||
### 禁用/启用自动部署
|
||||
|
||||
如果需要临时禁用自动部署，修改 deploy.sh：
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# 临时禁用部署，取消下面的注释
|
||||
# exit 0
|
||||
|
||||
# ... 后续脚本内容
|
||||
```
|
||||
|
||||
然后重新启动 webhook 服务：
|
||||
```bash
|
||||
docker-compose restart webhook
|
||||
```
|
||||
|
||||
## 高级配置
|
||||
|
||||
### 只部署特定分支
|
||||
|
||||
编辑 webhook/main.go，修改分支检查逻辑：
|
||||
|
||||
```go
|
||||
// 检查分支，修改条件为只部署 master 和 develop 分支
|
||||
if !strings.Contains(payload.Ref, "master") &&
|
||||
!strings.Contains(payload.Ref, "develop") {
|
||||
// 跳过部署
|
||||
}
|
||||
```
|
||||
|
||||
### 添加 Slack 通知
|
||||
|
||||
修改 deploy.sh，在部署完成后发送 Slack 消息：
|
||||
|
||||
```bash
|
||||
# 在部署完成后添加
|
||||
curl -X POST -H 'Content-type: application/json' \
|
||||
--data "{\"text\":\"BillAI 部署完成！\"}" \
|
||||
YOUR_SLACK_WEBHOOK_URL
|
||||
```
|
||||
|
||||
### 限制部署频率
|
||||
|
||||
在 webhook/main.go 中添加速率限制，防止频繁部署。
|
||||
|
||||
## 安全建议
|
||||
|
||||
1. **使用强密钥**：确保 WEBHOOK_SECRET 是随机生成的强密钥
|
||||
2. **限制网络访问**：只允许 Gitea 服务器的 IP 访问 webhook
|
||||
3. **HTTPS**：在生产环境中使用 HTTPS 而不是 HTTP
|
||||
4. **日志监控**：定期检查部署日志，及时发现问题
|
||||
5. **备份**：在部署前备份重要数据
|
||||
|
||||
## 相关文件
|
||||
|
||||
- [webhook/README.md](../webhook/README.md) - Webhook 服务文档
|
||||
- [deploy.sh](../deploy.sh) - 部署脚本
|
||||
- [docker-compose.yaml](../docker-compose.yaml) - Docker Compose 配置
|
||||
- [webhook/main.go](../webhook/main.go) - Webhook 服务源代码
|
||||
Reference in New Issue
Block a user