billai/WEBHOOK_SETUP.md

自动部署配置指南

这个指南将帮助你配置 Gitea webhook 以实现代码推送时的自动部署。

整体架构

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

打开终端，运行以下命令生成安全的随机密钥：

# 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

webhook:
  environment:
    WEBHOOK_SECRET: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"  # 替换为你生成的 Secret

配置仓库路径（关键）

重要！ 根据你的部署方式修改挂载路径：

如果使用本地路径部署：

webhook:
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock
    - /home/user/billai:/app  # 替换为你的实际路径

如果在云服务器上部署：

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 服务

# 进入项目根目录
cd /path/to/billai

# 构建并启动 webhook 服务
docker-compose up -d webhook

# 验证服务是否启动
docker-compose logs webhook

# 测试健康检查
curl http://localhost:9000/health

输出应该显示：

{
  "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 端口的入站连接：

# 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)" 按钮。

预期响应：

{
  "message": "非主分支，跳过部署"
}

（这是因为测试会使用一个默认的测试分支）

第五步：网络配置

防火墙配置

在部署前，确保服务器防火墙允许以下端口：

# 允许 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 反向代理：

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;
}

第六步：测试自动部署

现在你可以测试自动部署功能：

# 进入仓库目录
cd /path/to/billai

# 做一些改动
echo "# 测试自动部署" >> README.md

# 提交并推送到主分支
git add .
git commit -m "test: 测试自动部署功能"
git push origin master

监控部署过程

# 查看 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 完全相同
• 检查是否有多余空格或特殊字符

# 在 docker-compose.yaml 中查看
grep WEBHOOK_SECRET docker-compose.yaml

# 在 Gitea 中重新复制 Secret，确保没有多余空格

问题 2：无法连接到 Webhook 服务

症状：Gitea webhook 测试失败

解决方案：

1. 检查 webhook 容器是否运行：

docker-compose ps webhook

2. 检查端口是否正确暴露：

docker-compose logs webhook | grep "listen"

3. 检查防火墙规则：

# Linux
netstat -tulpn | grep 9000
sudo ufw status

# Windows
netstat -ano | findstr 9000

4. 测试本地连接：

curl http://localhost:9000/health

5. 如果是远程连接，测试网络连通性：

# 从 Gitea 服务器测试
curl http://<webhook-server-ip>:9000/health

netstat -ano | findstr 9000  # Windows

4. 测试本地连接：

curl http://localhost:9000/health

问题 3：部署脚本无法执行

症状：日志中显示 "部署脚本执行失败"

解决方案：

1. 检查 deploy.sh 是否存在：

ls -la deploy.sh

2. 检查文件权限：

chmod +x deploy.sh

3. 检查容器内的环境：

docker exec billai-webhook bash -c "ls -la /app/deploy.sh"

4. 查看详细错误信息：

docker exec billai-webhook tail -f /tmp/billai_deploy.log

问题 4：Docker 操作权限不足

症状：日志中显示 "permission denied" 或 "Cannot connect to Docker daemon"

解决方案：

1. 检查 Docker Socket 是否正确挂载：

webhook:
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock

2. 检查 Docker Socket 权限：

ls -l /var/run/docker.sock
chmod 666 /var/run/docker.sock  # 可能需要 sudo

3. 确保 webhook 容器以正确的用户运行（通常是 root）

问题 5：部署后服务无法启动

症状：健康检查超时，部署失败

解决方案：

1. 检查 docker-compose build 是否成功：

docker-compose build

2. 检查依赖服务是否启动：

docker-compose ps

3. 查看各服务的详细日志：

docker-compose logs server
docker-compose logs web
docker-compose logs analyzer

4. 增加健康检查的超时时间（修改 deploy.sh 中的 sleep 时间）

监控和维护

定期检查 Webhook 状态

# 查看最近 50 条日志
docker-compose logs --tail=50 webhook

# 实时监控日志
docker-compose logs -f webhook

查看部署历史

部署脚本的日志保存在：/tmp/billai_deploy.log

# 查看部署历史
docker exec billai-webhook cat /tmp/billai_deploy.log

# 持续监控
docker exec billai-webhook tail -f /tmp/billai_deploy.log

禁用/启用自动部署

如果需要临时禁用自动部署，修改 deploy.sh：

#!/bin/bash

# 临时禁用部署，取消下面的注释
# exit 0

# ... 后续脚本内容

然后重新启动 webhook 服务：

docker-compose restart webhook

高级配置

只部署特定分支

编辑 webhook/main.go，修改分支检查逻辑：

// 检查分支，修改条件为只部署 master 和 develop 分支
if !strings.Contains(payload.Ref, "master") && 
   !strings.Contains(payload.Ref, "develop") {
    // 跳过部署
}

添加 Slack 通知

修改 deploy.sh，在部署完成后发送 Slack 消息：

# 在部署完成后添加
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 服务文档
• deploy.sh - 部署脚本
• docker-compose.yaml - Docker Compose 配置
• webhook/main.go - Webhook 服务源代码