freeleaps-ops/apps/gitea-webhook-ambassador-python

Gitea Webhook Ambassador (Python)

一个高性能的 Python webhook 服务，用于连接 Gitea 和 Jenkins，支持智能分发、高并发处理和防抖策略。

🚀 新特性

1. 智能分发策略

• dev 分支 → 触发 alpha 环境构建
• prod 分支 → 触发生产环境构建
• 其他分支 → 可配置的默认策略

2. 高并发处理

• 异步任务队列: 使用 Celery + Redis 处理高并发
• 任务排队机制: 防止构建丢失，确保任务按序执行
• 负载均衡: 支持多 worker 实例

3. 防抖策略

• 基于 commit hash + 分支的去重: 防止重复触发
• 时间窗口防抖: 在指定时间窗口内的相同提交只触发一次
• 智能去重: 支持配置去重策略

🏗️ 架构设计

Gitea Webhook → FastAPI → Celery Queue → Jenkins Workers
     ↓              ↓           ↓            ↓
  验证签名      路由分发    任务排队     并发执行
     ↓              ↓           ↓            ↓
  防抖检查      环境判断    持久化存储   状态反馈

📁 项目结构

gitea-webhook-ambassador-python/
├── app/
│   ├── __init__.py
│   ├── main.py                 # FastAPI 应用入口
│   ├── config.py               # 配置管理
│   ├── models/                 # 数据模型
│   │   ├── __init__.py
│   │   ├── gitea.py           # Gitea webhook 模型
│   │   └── jenkins.py         # Jenkins 任务模型
│   ├── services/              # 业务逻辑
│   │   ├── __init__.py
│   │   ├── webhook_service.py # Webhook 处理服务
│   │   ├── jenkins_service.py # Jenkins 集成服务
│   │   ├── queue_service.py   # 队列管理服务
│   │   └── dedup_service.py   # 防抖服务
│   ├── api/                   # API 路由
│   │   ├── __init__.py
│   │   ├── webhook.py         # Webhook 端点
│   │   ├── health.py          # 健康检查
│   │   └── admin.py           # 管理接口
│   ├── core/                  # 核心组件
│   │   ├── __init__.py
│   │   ├── security.py        # 安全验证
│   │   ├── database.py        # 数据库连接
│   │   └── cache.py           # 缓存管理
│   └── tasks/                 # Celery 任务
│       ├── __init__.py
│       └── jenkins_tasks.py   # Jenkins 任务处理
├── tests/                     # 测试文件
├── docker/                    # Docker 配置
├── requirements.txt           # Python 依赖
├── docker-compose.yml         # 开发环境
└── README.md

🛠️ 技术栈

• Web 框架: FastAPI
• 任务队列: Celery + Redis
• 数据库: PostgreSQL (生产) / SQLite (开发)
• 缓存: Redis
• 监控: Prometheus + Grafana
• 日志: Structured logging with JSON
• 测试: pytest + pytest-asyncio

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境

cp .env.example .env
# 编辑 .env 文件配置 Jenkins 和数据库连接

3. 启动服务

# 启动 Redis
docker run -d -p 6379:6379 redis:alpine

# 启动 Celery worker
celery -A app.tasks worker --loglevel=info

# 启动 FastAPI 应用
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

📋 配置说明

环境分发配置

environments:
  dev:
    branches: ["dev", "develop", "development"]
    jenkins_job: "alpha-build"
    jenkins_url: "https://jenkins-alpha.example.com"
  prod:
    branches: ["prod", "production", "main", "master"]
    jenkins_job: "production-build"
    jenkins_url: "https://jenkins-prod.example.com"
  default:
    jenkins_job: "default-build"
    jenkins_url: "https://jenkins-default.example.com"

防抖配置

deduplication:
  enabled: true
  window_seconds: 300  # 5分钟防抖窗口
  strategy: "commit_branch"  # commit_hash + branch
  cache_ttl: 3600  # 缓存1小时

队列配置

queue:
  max_concurrent: 10
  max_retries: 3
  retry_delay: 60  # 秒
  priority_levels: 3

🔧 API 接口

Webhook 端点

POST /webhook/gitea

健康检查

GET /health
GET /health/queue
GET /health/jenkins

管理接口

GET /admin/queue/status
GET /admin/queue/stats
POST /admin/queue/clear

🧪 测试

# 运行所有测试
pytest

# 运行特定测试
pytest tests/test_webhook_service.py

# 运行性能测试
pytest tests/test_performance.py

📊 监控指标

• Webhook 接收率
• 任务队列长度
• Jenkins 构建成功率
• 响应时间分布
• 防抖命中率

🔒 安全特性

• Webhook 签名验证
• API 密钥认证
• 请求频率限制
• 输入验证和清理
• 安全日志记录