f6c515157c
- 新增完整的 Python 实现，替代 Go 版本 - 添加 Web 登录界面和仪表板 - 实现 JWT 认证和 API 密钥管理 - 添加数据库存储功能 - 保持与 Go 版本一致的目录结构和启动脚本 - 包含完整的文档和测试脚本
189 lines
4.8 KiB
Markdown
189 lines
4.8 KiB
Markdown
# 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. 安装依赖
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 2. 配置环境
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 文件配置 Jenkins 和数据库连接
|
||
```
|
||
|
||
### 3. 启动服务
|
||
```bash
|
||
# 启动 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
|
||
```
|
||
|
||
## 📋 配置说明
|
||
|
||
### 环境分发配置
|
||
```yaml
|
||
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"
|
||
```
|
||
|
||
### 防抖配置
|
||
```yaml
|
||
deduplication:
|
||
enabled: true
|
||
window_seconds: 300 # 5分钟防抖窗口
|
||
strategy: "commit_branch" # commit_hash + branch
|
||
cache_ttl: 3600 # 缓存1小时
|
||
```
|
||
|
||
### 队列配置
|
||
```yaml
|
||
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
|
||
```
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
pytest
|
||
|
||
# 运行特定测试
|
||
pytest tests/test_webhook_service.py
|
||
|
||
# 运行性能测试
|
||
pytest tests/test_performance.py
|
||
```
|
||
|
||
## 📊 监控指标
|
||
|
||
- Webhook 接收率
|
||
- 任务队列长度
|
||
- Jenkins 构建成功率
|
||
- 响应时间分布
|
||
- 防抖命中率
|
||
|
||
## 🔒 安全特性
|
||
|
||
- Webhook 签名验证
|
||
- API 密钥认证
|
||
- 请求频率限制
|
||
- 输入验证和清理
|
||
- 安全日志记录 |