# 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 密钥认证
- 请求频率限制
- 输入验证和清理
- 安全日志记录