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

# Gitea Webhook Ambassador (Python Enhanced Version)

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

## 🚀 快速开始

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

```bash
# 安装依赖
./devbox install

# 初始化数据库
./devbox init

# 启动服务
./devbox start

# 查看状态
./devbox status

# 查看日志
./devbox logs

# 停止服务
./devbox stop
```

### 方式二：使用 Makefile

```bash
# 安装依赖
make install

# 初始化数据库
make init

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

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

# 查看状态
make status

# 查看日志
make logs

# 停止服务
make stop
```

### 方式三：直接使用 Python

```bash
# 创建虚拟环境
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` 文件：

```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 接收端点

## 🛠️ 开发

### 运行测试
```bash
# 使用 devbox
./devbox test

# 使用 Makefile
make test

# 直接运行
python test_enhanced_features.py
```

### 代码检查
```bash
# 使用 Makefile
make lint

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

### 清理
```bash
# 使用 devbox
./devbox clean

# 使用 Makefile
make clean
```

## 🐳 Docker 部署

### 构建镜像
```bash
# 使用 Makefile
make docker-build

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

### 运行容器
```bash
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 版本

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

2. **启动 Python 服务**
   ```bash
   cd /path/to/python-version
   ./devbox install
   ./devbox init
   ./devbox start
   ```

3. **验证服务**
   ```bash
   ./devbox status
   curl http://localhost:8000/api/health
   ```

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

## 🆘 故障排除

### 常见问题

**1. 端口被占用**
```bash
# 检查端口占用
lsof -i :8000

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

**2. 虚拟环境问题**
```bash
# 重新创建虚拟环境
rm -rf venv
./devbox install
```

**3. 数据库问题**
```bash
# 重新初始化数据库
./devbox init
```

**4. 权限问题**
```bash
# 设置脚本权限
chmod +x devbox
```

### 日志查看
```bash
# 查看实时日志
./devbox follow

# 查看最新日志
./devbox logs

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

## 📞 支持

如有问题，请检查：
1. 服务状态：`./devbox status`
2. 日志信息：`./devbox logs`
3. 配置文件：`configs/config.yaml`
4. 网络连接：`curl http://localhost:8000/api/health`