billai/WEBHOOK_SETUP.md

# 自动部署配置指南

这个指南将帮助你配置 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 服务源代码