ActiveBuilder

ActiveBuilder 是一个 Python 控制台项目，用于接收 GitHub Webhook 推送事件并自动执行构建和部署脚本。

功能特性

• 🚀 Webhook 接收: 监听指定端口，处理来自 GitHub 的 Webhook 推送事件
• 🔐 安全验证: 使用 HMAC-SHA256 验证 Webhook 请求的合法性
• 📝 YAML 配置: 支持全局和项目级别的灵活配置
• 🔧 脚本执行: 自动执行构建脚本和后钩脚本
• 📊 并行处理: 支持多项目并行构建，提高效率
• 📋 完整日志: 记录完整的构建过程和错误信息
• 🌐 RESTful API: 提供丰富的 API 接口用于监控和管理

系统要求

• Python 版本: Python 3.10 或更高版本
• 操作系统: Linux, macOS, Windows
• 内存: 建议 512MB 以上
• 磁盘空间: 根据项目大小而定，建议预留足够空间用于构建缓存

Python 版本兼容性

ActiveBuilder 使用了 Python 3.10+ 的新特性：

• 新的类型注解语法 (str | None 替代 Optional[str])
• 内置类型的泛型支持 (dict[str, Any] 替代 Dict[str, Any])

如果您使用的是较旧的 Python 版本，请升级到 Python 3.10 或更高版本。

快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置文件

复制示例配置文件并根据实际情况修改：

cp config.yaml.example config.yaml

编辑 config.yaml：

global:
  secret: "your-webhook-secret"
  port: 8080
  host: "0.0.0.0"

projects:
  my-project:
    build_script: "/path/to/build-script.sh"
    post_hook_script: "/path/to/deploy-script.sh"

3. 准备构建脚本

参考 scripts/example-build.sh 和 scripts/example-post-hook.sh 创建你的构建和部署脚本。

4. 启动服务

# 使用配置文件中的设置启动
python main.py

# 或者使用命令行参数覆盖配置
python main.py -p 8080 -H 0.0.0.0

# 启用调试模式
python main.py --debug

注意: 程序会优先使用配置文件中的 port 和 host 设置，命令行参数 -p 和 -H 可以覆盖这些设置。

或者使用 gunicorn 启动（推荐生产环境）：

gunicorn -w 4 -b 0.0.0.0:8080 main:app

配置说明

全局配置

global:
  secret: "webhook-secret"          # 默认 Webhook 验证密钥
  port: 8080                        # 服务端口
  host: "0.0.0.0"                   # 监听地址
  log_level: "INFO"                 # 日志级别
  log_file: "activebuilder.log"     # 日志文件
  max_concurrent_builds: 5          # 最大并发构建数

项目配置

projects:
  project-name:                     # 项目名称（必须与 GitHub 仓库名一致）
    webhook_secret: "secret"        # 项目专用密钥（可选，覆盖全局密钥）
    build_script: "/path/to/build.sh"     # 构建脚本路径（必填）
    post_hook_script: "/path/to/deploy.sh" # 后钩脚本路径（可选）

脚本编写

环境变量

脚本执行时会自动设置以下环境变量：

• ACTIVEBUILDER_PROJECT: 项目名称
• ACTIVEBUILDER_BUILD_ID: 构建ID
• ACTIVEBUILDER_SCRIPT_TYPE: 脚本类型 (build/post_hook)
• ACTIVEBUILDER_LOG_FILE: 构建日志文件路径
• ACTIVEBUILDER_REPO_URL: 仓库URL
• ACTIVEBUILDER_BRANCH: 分支名称
• ACTIVEBUILDER_COMMIT_SHA: 提交SHA
• ACTIVEBUILDER_COMMIT_MESSAGE: 提交消息
• ACTIVEBUILDER_EVENT_TYPE: 事件类型 (push/pull_request)

构建脚本示例

#!/bin/bash
set -e

echo "开始构建项目: $ACTIVEBUILDER_PROJECT"

# 克隆代码
git clone $ACTIVEBUILDER_REPO_URL /tmp/build
cd /tmp/build
git checkout $ACTIVEBUILDER_BRANCH

# 安装依赖并构建
npm install
npm run build

echo "构建完成"

部署脚本示例

#!/bin/bash
set -e

echo "开始部署项目: $ACTIVEBUILDER_PROJECT"

# 备份当前版本
cp -r /var/www/app /var/backups/app-$(date +%Y%m%d-%H%M%S)

# 部署新版本
cp -r /tmp/build/dist/* /var/www/app/

# 重启服务
systemctl restart nginx

echo "部署完成"

API 接口

Webhook 接收

POST /webhook

接收 GitHub Webhook 推送事件。

健康检查

GET /health

返回服务健康状态。

服务状态

GET /status

返回服务运行状态和统计信息。

构建管理

GET /builds/<build_id>          # 获取构建状态
DELETE /builds/<build_id>       # 取消构建

项目管理

GET /projects                           # 列出所有项目
GET /projects/<project>/builds          # 获取项目构建历史
POST /projects/<project>/validate       # 验证项目配置

日志查看

GET /logs/<project>                     # 获取项目日志列表
GET /logs/<project>/<log_file>          # 查看具体日志文件

配置管理

POST /config/reload                     # 重新加载配置

GitHub Webhook 配置

1. 在 GitHub 仓库设置中，进入 "Settings" > "Webhooks"
2. 点击 "Add webhook"
3. 设置 Payload URL: http://your-server:8080/webhook
4. 设置 Content type: application/json
5. 设置 Secret: 与配置文件中的 secret 一致
6. 选择触发事件: "Just the push event" 或 "Let me select individual events"
7. 确保 "Active" 选项被勾选

安全注意事项

1. 密钥管理: 确保 Webhook 密钥足够复杂且定期更换
2. 脚本权限: 构建和部署脚本应使用最小权限原则
3. 网络安全: 建议使用 HTTPS 和防火墙保护服务
4. 日志安全: 避免在日志中记录敏感信息
5. 文件权限: 确保配置文件和脚本文件权限设置正确

故障排除

常见问题

1. Webhook 验证失败

   • 检查 GitHub Webhook 配置中的 Secret 是否与配置文件一致
   • 确认 Content-Type 设置为 application/json

2. 脚本执行失败

   • 检查脚本文件是否存在且具有执行权限
   • 查看构建日志了解具体错误信息

3. 端口占用

   • 使用 lsof -i :8080 检查端口占用情况
   • 修改配置文件中的端口设置

日志查看

# 查看主服务日志
tail -f activebuilder.log

# 查看项目构建日志
tail -f logs/project-name/build-20240101-120000.log

开发和贡献

项目结构

activebuilder/
├── main.py                 # 主程序入口
├── requirements.txt        # Python 依赖
├── config.yaml.example     # 配置文件示例
├── src/                    # 源代码目录
│   ├── __init__.py
│   ├── config.py          # 配置管理
│   ├── webhook_handler.py # Webhook 处理
│   ├── script_executor.py # 脚本执行
│   ├── build_manager.py   # 构建管理
│   ├── logger.py          # 日志系统
│   └── routes.py          # API 路由
├── scripts/               # 示例脚本
│   ├── example-build.sh
│   └── example-post-hook.sh
└── logs/                  # 日志目录（自动创建）

运行测试

# 安装测试依赖
pip install pytest pytest-cov

# 运行测试
pytest tests/

# 生成覆盖率报告
pytest --cov=src tests/

许可证

MIT License

支持

如有问题或建议，请提交 Issue 或 Pull Request。