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

🚀 Gitea Webhook Ambassador 使用指南

📋 目录

1. 快速开始
2. 配置说明
3. API 接口
4. 数据库管理
5. 监控和日志
6. 故障排除

🚀 快速开始

1. 环境准备

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

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

2. 配置环境

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

# 编辑配置文件
nano .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. 启动服务

# 方法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 文件：

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

防抖配置

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

🔧 API 接口

Webhook 端点

POST /webhook/gitea

接收 Gitea webhook 事件：

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

curl http://localhost:8000/health

响应示例：

{
  "status": "healthy",
  "timestamp": 1640995200.0,
  "services": {
    "redis": "healthy",
    "celery": "healthy"
  }
}

队列状态

GET /health/queue

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

响应示例：

{
  "status": "healthy",
  "queue_stats": {
    "active_tasks": 2,
    "queued_tasks": 5,
    "worker_count": 4,
    "total_queue_length": 7
  }
}

监控指标

GET /metrics

curl http://localhost:8000/metrics

返回 Prometheus 格式的监控指标。

🗄️ 数据库管理

创建项目映射

使用 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())

运行脚本：

python create_mapping.py

查看触发日志

# 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())

📊 监控和日志

日志查看

# 查看应用日志
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 连接失败

# 检查 Redis 状态
docker ps | grep redis

# 重启 Redis
docker restart webhook-redis

2. Celery Worker 无法启动

# 检查 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 连接失败

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

4. 数据库错误

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

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

日志级别调整

编辑 .env 文件：

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

性能调优

增加并发处理能力

QUEUE_MAX_CONCURRENT=20

调整防抖窗口

DEDUPLICATION_WINDOW_SECONDS=600  # 10分钟

🐳 Docker 部署

使用 Docker Compose

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

# 查看服务状态
docker-compose ps

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

生产环境部署

# 构建镜像
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。