billai/webhook

Webhook 服务

用于监听 Gitea webhook 事件，自动触发服务器拉取最新代码并重新构建部署。

特性

• ✅ 接收 Gitea webhook 推送事件
• ✅ HMAC-SHA256 签名验证
• ✅ 仅处理主分支 (master/main) 的推送
• ✅ 自动执行部署脚本
• ✅ 异步部署，快速响应
• ✅ 零停机热更新

配置

环境变量

变量	说明	默认值
WEBHOOK_PORT	webhook 服务监听端口	9000
WEBHOOK_SECRET	Gitea webhook 签名密钥	your-webhook-secret
REPO_PATH	仓库根目录路径	/app

部署脚本

脚本位置: /app/deploy.sh

执行以下操作:

1. 拉取最新代码 (git pull)
2. 热更新部署（零停机）
3. 自动清理旧镜像
4. 健康检查

安全性

设置 Webhook Secret

在 Gitea 中配置 webhook 时，需要设置 Secret：

1. 生成一个随机密钥：

openssl rand -hex 32
# 输出示例: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

2. 在 Docker 容器中设置环境变量：

environment:
  WEBHOOK_SECRET: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Gitea Webhook 配置

1. 进入仓库设置

在 Gitea 中打开仓库，进入 设置 → Webhook

2. 添加新 Webhook

• URL: http://<your-server>:9000/webhook
• 内容类型: application/json
• 密钥: 使用上面生成的 Secret
• 触发器: 勾选 推送事件
• 活跃: 是

3. 测试连接

点击 "测试" 按钮验证连接

日志

查看部署日志：

# 查看容器日志
docker logs billai-webhook

# 查看部署脚本日志
docker exec billai-webhook tail -f /tmp/billai_deploy.log

访问端点

• Webhook: POST /webhook
• 健康检查: GET /health

工作流

Gitea Push Event
      ↓
Webhook Service (port 9000)
      ↓
验证 HMAC-SHA256 签名
      ↓
检查分支 (仅主分支)
      ↓
异步触发部署脚本
      ↓
执行 git pull
      ↓
执行 docker-compose build/up
      ↓
健康检查
      ↓
部署完成

故障排除

签名验证失败

• 检查 Gitea 中配置的 Secret 是否与环境变量 WEBHOOK_SECRET 一致

部署脚本无法执行

• 确保 deploy.sh 存在于仓库根目录
• 检查文件权限：chmod +x deploy.sh
• 检查容器内是否有 git、docker 等工具

Docker 操作失败

• 确保容器有权限访问 Docker Socket
• 在 docker-compose 中正确挂载 Docker Socket：

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

示例 docker-compose 配置

参考项目根目录的 docker-compose.yaml