Nicolas f6c515157c feat: 添加 Python 版本的 Gitea Webhook Ambassador

- 新增完整的 Python 实现，替代 Go 版本
- 添加 Web 登录界面和仪表板
- 实现 JWT 认证和 API 密钥管理
- 添加数据库存储功能
- 保持与 Go 版本一致的目录结构和启动脚本
- 包含完整的文档和测试脚本

2025-07-20 21:17:10 +08:00

7.0 KiB

Raw Blame History

Gitea Webhook Ambassador (Python Enhanced Version)

这是一个用 Python 重写的 Gitea Webhook Ambassador 服务，提供与 Go 版本相同的功能，但增加了 Web 界面和更多管理功能。

🚀 快速开始

方式一：使用 devbox 脚本（推荐，与 Go 版本一致）

# 安装依赖
./devbox install

# 初始化数据库
./devbox init

# 启动服务
./devbox start

# 查看状态
./devbox status

# 查看日志
./devbox logs

# 停止服务
./devbox stop

方式二：使用 Makefile

# 安装依赖
make install

# 初始化数据库
make init

# 启动服务（前台运行）
make run

# 启动服务（后台运行）
make start

# 查看状态
make status

# 查看日志
make logs

# 停止服务
make stop

方式三：直接使用 Python

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 初始化数据库
python -c "from app.models.database import create_tables; create_tables()"

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

📁 目录结构（与 Go 版本一致）

gitea-webhook-ambassador-python/
├── app/                    # 应用代码
│   ├── auth/              # 认证模块
│   ├── handlers/          # API 处理器
│   ├── models/            # 数据模型
│   ├── templates/         # HTML 模板
│   ├── static/            # 静态文件
│   └── main_enhanced.py   # 主应用入口
├── cmd/                   # 命令行工具（与 Go 版本一致）
│   └── server/           # 服务器启动
├── configs/              # 配置文件（与 Go 版本一致）
│   └── config.yaml       # 主配置文件
├── data/                 # 数据目录（与 Go 版本一致）
│   └── *.db             # SQLite 数据库文件
├── logs/                 # 日志目录（与 Go 版本一致）
│   └── service.log      # 服务日志
├── devbox               # 启动脚本（与 Go 版本一致）
├── Makefile             # 构建脚本（与 Go 版本一致）
├── requirements.txt     # Python 依赖
└── README_ENHANCED.md   # 本文档

🔧 配置

编辑 configs/config.yaml 文件：

server:
  port: 8000
  webhookPath: "/webhook"
  secretHeader: "X-Gitea-Signature"
  secretKey: "admin-secret-key-change-in-production"

jenkins:
  url: "http://jenkins.example.com"
  username: "jenkins-user"
  token: "jenkins-api-token"
  timeout: 30

admin:
  token: "admin-api-token"

database:
  path: "data/gitea-webhook-ambassador.db"

logging:
  level: "info"
  format: "text"
  file: "logs/service.log"

worker:
  poolSize: 10
  queueSize: 100
  maxRetries: 3
  retryBackoff: 1

eventCleanup:
  interval: 3600
  expireAfter: 7200

🌐 Web 界面

启动服务后，访问以下地址：

登录页面: http://localhost:8000
仪表板: http://localhost:8000/dashboard
API 文档: http://localhost:8000/docs

默认登录凭据

用户名: admin
密码: admin-secret-key-change-in-production

📊 功能特性

✅ 与 Go 版本相同的功能

Gitea Webhook 接收和处理
Jenkins 任务触发
项目映射配置
分支模式匹配
重试机制
日志记录

🆕 Python 版本增强功能

Web 登录界面: 基于 Bootstrap 5 的现代化界面
数据库存储: SQLite 数据库存储 API 密钥和配置
JWT 认证: 7 天有效期的 JWT 令牌
前端仪表板: 多标签页管理界面
自动重定向: 未认证用户自动跳转到登录页
健康检查: 服务状态监控
统计信息: 请求统计和性能指标

🔌 API 端点

认证相关

POST /api/auth/login - 用户登录
GET /api/auth/verify - 验证 JWT 令牌

项目管理

GET /api/projects - 获取项目列表
POST /api/projects - 创建新项目
PUT /api/projects/{id} - 更新项目
DELETE /api/projects/{id} - 删除项目

API 密钥管理

GET /api/keys - 获取 API 密钥列表
POST /api/keys - 创建新 API 密钥
DELETE /api/keys/{id} - 删除 API 密钥

系统监控

GET /api/health - 健康检查
GET /api/stats - 统计信息
GET /api/logs - 日志查看

Webhook 处理

POST /webhook - Gitea Webhook 接收端点

🛠️ 开发

运行测试

# 使用 devbox
./devbox test

# 使用 Makefile
make test

# 直接运行
python test_enhanced_features.py

代码检查

# 使用 Makefile
make lint

# 直接运行
flake8 app/ --max-line-length=120 --ignore=E501,W503

清理

# 使用 devbox
./devbox clean

# 使用 Makefile
make clean

🐳 Docker 部署

构建镜像

# 使用 Makefile
make docker-build

# 直接构建
docker build -t gitea-webhook-ambassador:latest .

运行容器

docker run -d \
  --name gitea-webhook-ambassador \
  -p 8000:8000 \
  -v $(pwd)/configs:/app/configs \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/logs:/app/logs \
  gitea-webhook-ambassador:latest

📈 与 Go 版本对比

特性	Go 版本	Python 版本
启动方式	`./devbox start`	`./devbox start`
目录结构	标准 Go 项目结构	与 Go 版本一致
配置文件	`configs/config.yaml`	`configs/config.yaml`
日志目录	`logs/`	`logs/`
数据目录	`data/`	`data/`
Web 界面	❌ 无	✅ 完整仪表板
数据库	❌ 无	✅ SQLite
JWT 认证	❌ 无	✅ 7天有效期
API 密钥管理	❌ 无	✅ 数据库存储
健康检查	✅ 基础	✅ 增强版
性能	🚀 极高	🚀 高

🔄 迁移指南

从 Go 版本迁移到 Python 版本

停止 Go 服务
```
cd /path/to/go-version
./devbox stop
```

启动 Python 服务

cd /path/to/python-version
./devbox install
./devbox init
./devbox start

验证服务

./devbox status
curl http://localhost:8000/api/health

配置 Webhook
- 更新 Gitea Webhook URL 为新的 Python 服务地址
- 确保 Jenkins 配置正确

🆘 故障排除

常见问题

1. 端口被占用

# 检查端口占用
lsof -i :8000

# 停止占用进程
sudo kill -9 <PID>

2. 虚拟环境问题

# 重新创建虚拟环境
rm -rf venv
./devbox install

3. 数据库问题

# 重新初始化数据库
./devbox init

4. 权限问题

# 设置脚本权限
chmod +x devbox

日志查看

# 查看实时日志
./devbox follow

# 查看最新日志
./devbox logs

# 查看完整日志
tail -f logs/service.log

📞 支持

如有问题，请检查：

服务状态：./devbox status
日志信息：./devbox logs
配置文件：configs/config.yaml
网络连接：curl http://localhost:8000/api/health

7.0 KiB Raw Blame History