freeleaps-ops/apps/gitea-webhook-ambassador-python/USAGE.md

# 🚀 Gitea Webhook Ambassador 使用指南

## 📋 目录
1. [快速开始](#快速开始)
2. [配置说明](#配置说明)
3. [API 接口](#api-接口)
4. [数据库管理](#数据库管理)
5. [监控和日志](#监控和日志)
6. [故障排除](#故障排除)

## 🚀 快速开始

### 1. 环境准备

```bash
# 克隆项目
cd freeleaps-ops/apps/gitea-webhook-ambassador-python

# 运行快速设置脚本
chmod +x scripts/setup.sh
./scripts/setup.sh
```

### 2. 配置环境

编辑 `.env` 文件，配置必要的参数：

```bash
# 编辑配置文件
nano .env
```

**必需配置**：
```env
# Jenkins 配置
JENKINS_USERNAME=your_jenkins_username
JENKINS_TOKEN=your_jenkins_api_token

# 安全配置
SECURITY_SECRET_KEY=your-secret-key-here-make-it-long-and-random
```

### 3. 启动服务

```bash
# 方法1: 使用启动脚本
chmod +x scripts/start.sh
./scripts/start.sh

# 方法2: 手动启动
# 启动 Redis
docker run -d --name webhook-redis -p 6379:6379 redis:alpine

# 激活虚拟环境
source venv/bin/activate

# 启动 API 服务
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 新终端启动 Celery worker
celery -A app.tasks.jenkins_tasks worker --loglevel=info --concurrency=4

# 新终端启动定时任务
celery -A app.tasks.jenkins_tasks beat --loglevel=info
```

### 4. 验证安装

访问以下地址验证服务是否正常：

- **API 文档**: http://localhost:8000/docs
- **健康检查**: http://localhost:8000/health
- **监控指标**: http://localhost:8000/metrics

## ⚙️ 配置说明

### 环境分发配置

编辑 `config/environments.yaml` 文件：

```yaml
environments:
  dev:
    branches: ["dev", "develop", "development", "feature/*"]
    jenkins_job: "alpha-build"
    jenkins_url: "https://jenkins-alpha.freeleaps.com"
    priority: 2
    
  prod:
    branches: ["prod", "production", "main", "master", "release/*"]
    jenkins_job: "production-build"
    jenkins_url: "https://jenkins-prod.freeleaps.com"
    priority: 1
```

### 防抖配置

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

## 🔧 API 接口

### Webhook 端点

**POST** `/webhook/gitea`

接收 Gitea webhook 事件：

```bash
curl -X POST "http://localhost:8000/webhook/gitea" \
  -H "Content-Type: application/json" \
  -H "X-Gitea-Signature: your-secret-key" \
  -d '{
    "ref": "refs/heads/dev",
    "before": "abc123",
    "after": "def456",
    "repository": {
      "full_name": "freeleaps/my-project",
      "clone_url": "https://gitea.freeleaps.com/freeleaps/my-project.git"
    },
    "pusher": {
      "login": "developer",
      "email": "dev@freeleaps.com"
    }
  }'
```

### 健康检查

**GET** `/health`

```bash
curl http://localhost:8000/health
```

响应示例：
```json
{
  "status": "healthy",
  "timestamp": 1640995200.0,
  "services": {
    "redis": "healthy",
    "celery": "healthy"
  }
}
```

### 队列状态

**GET** `/health/queue`

```bash
curl http://localhost:8000/health/queue
```

响应示例：
```json
{
  "status": "healthy",
  "queue_stats": {
    "active_tasks": 2,
    "queued_tasks": 5,
    "worker_count": 4,
    "total_queue_length": 7
  }
}
```

### 监控指标

**GET** `/metrics`

```bash
curl http://localhost:8000/metrics
```

返回 Prometheus 格式的监控指标。

## 🗄️ 数据库管理

### 创建项目映射

使用 Python 脚本创建项目映射：

```python
# create_mapping.py
import asyncio
from app.services.database_service import get_database_service

async def create_mapping():
    db_service = get_database_service()
    
    mapping_data = {
        "repository_name": "freeleaps/my-project",
        "default_job": "default-build",
        "branch_jobs": [
            {"branch_name": "dev", "job_name": "alpha-build"},
            {"branch_name": "main", "job_name": "production-build"}
        ],
        "branch_patterns": [
            {"pattern": r"feature/.*", "job_name": "feature-build"},
            {"pattern": r"hotfix/.*", "job_name": "hotfix-build"}
        ]
    }
    
    success = await db_service.create_project_mapping(mapping_data)
    print(f"创建映射: {'成功' if success else '失败'}")

if __name__ == "__main__":
    asyncio.run(create_mapping())
```

运行脚本：
```bash
python create_mapping.py
```

### 查看触发日志

```python
# view_logs.py
import asyncio
from app.services.database_service import get_database_service

async def view_logs():
    db_service = get_database_service()
    
    logs = await db_service.get_trigger_logs(
        repository_name="freeleaps/my-project",
        limit=10
    )
    
    for log in logs:
        print(f"[{log['created_at']}] {log['repository_name']} - {log['branch_name']} - {log['status']}")

if __name__ == "__main__":
    asyncio.run(view_logs())
```

## 📊 监控和日志

### 日志查看

```bash
# 查看应用日志
tail -f logs/app.log

# 查看 Celery 日志
tail -f logs/celery.log
```

### 监控面板

使用 Grafana 创建监控面板：

1. 访问 http://localhost:3000 (Grafana)
2. 用户名: `admin`, 密码: `admin`
3. 添加 Prometheus 数据源: http://prometheus:9090
4. 导入监控面板

### 关键指标

- **webhook_requests_total**: Webhook 请求总数
- **webhook_request_duration_seconds**: 请求响应时间
- **queue_size**: 队列长度
- **dedup_hits_total**: 防抖命中次数

## 🔧 故障排除

### 常见问题

#### 1. Redis 连接失败

```bash
# 检查 Redis 状态
docker ps | grep redis

# 重启 Redis
docker restart webhook-redis
```

#### 2. Celery Worker 无法启动

```bash
# 检查 Celery 配置
celery -A app.tasks.jenkins_tasks inspect active

# 重启 Worker
pkill -f "celery.*worker"
celery -A app.tasks.jenkins_tasks worker --loglevel=info
```

#### 3. Jenkins 连接失败

```bash
# 测试 Jenkins 连接
curl -u username:token https://jenkins.example.com/api/json
```

#### 4. 数据库错误

```bash
# 检查数据库文件
ls -la webhook_ambassador.db

# 重新初始化数据库
rm webhook_ambassador.db
python -c "from app.services.database_service import get_database_service; get_database_service()"
```

### 日志级别调整

编辑 `.env` 文件：

```env
LOGGING_LEVEL=DEBUG  # 开发环境
LOGGING_LEVEL=INFO   # 生产环境
```

### 性能调优

#### 增加并发处理能力

```env
QUEUE_MAX_CONCURRENT=20
```

#### 调整防抖窗口

```env
DEDUPLICATION_WINDOW_SECONDS=600  # 10分钟
```

## 🐳 Docker 部署

### 使用 Docker Compose

```bash
# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f api
```

### 生产环境部署

```bash
# 构建镜像
docker build -t webhook-ambassador:latest .

# 运行容器
docker run -d \
  --name webhook-ambassador \
  -p 8000:8000 \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/logs:/app/logs \
  --env-file .env \
  webhook-ambassador:latest
```

## 📞 支持

如果遇到问题，请检查：

1. 日志文件中的错误信息
2. 健康检查端点返回的状态
3. 监控指标中的异常数据
4. 网络连接和防火墙设置

更多帮助请参考项目文档或提交 Issue。