## 项目简介

这是一个可配置的 Webhook 中继与通知系统，用于：
- 统一接收外部支付/业务系统的 Webhook 请求
- 按规则将请求转发到内部多个目标系统
- 根据事件与模板生成消息，推送到飞书、企业微信等 IM 渠道

核心特性：
- 通过 Web 管理后台 `/admin` 管理端点、规则树、动作、消息模板与通知渠道
- 支持树形规则：按 `remark`、`event_define_no` 等字段组合匹配
- 支持转发（forward）与通知（notify）两类动作
- 消息模板支持变量与继承，可在父规则设置通用模板，在子规则覆盖变量
- 所有请求与分发结果写入 SQLite 数据库，便于审计与排查

## 技术栈与目录结构

- 语言与框架：Python 3.12 + FastAPI
- 数据库：SQLite（可通过 `DB_PATH` 切换到其他 SQLAlchemy 支持的数据库）
- HTTP 客户端：httpx

主要目录：
- `app/main.py`：FastAPI 入口，`/webhook/{namespace}` 与 `/health`
- `app/admin.py`：管理后台路由（端点、规则、动作、模板、渠道、日志）
- `app/db.py`：SQLAlchemy 模型与会话管理
- `app/services/engine.py`：规则引擎，实现树形规则匹配与动作编排
- `app/services/notify.py`：飞书与企业微信的实际发送封装
- `templates/admin/`：管理后台的 HTML 模板
- `config/data.db`：默认 SQLite 数据库文件（若不存在会自动创建）
- `docs/webhook-relay/`：6A 工作流下的对齐、设计、任务与流程文档

## 本地运行（开发环境）

1. 安装依赖：
   - 可选：创建虚拟环境
   - 执行：`pip install -r requirements.txt`

2. 初始化数据库并启动服务：
   - 进入项目根目录：`cd e:\2025Code\python\webhock`
   - 启动：`uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload`

3. 访问入口：
   - Webhook 接口：`POST http://localhost:8080/webhook/{namespace}`
   - 健康检查：`GET http://localhost:8080/health`
   - 管理后台：`GET http://localhost:8080/admin/endpoints`

## Docker 部署

项目包含 `Dockerfile`，可直接构建镜像部署：

1. 构建镜像：
   - 在项目根目录执行  
     `docker build -t webhook-relay .`

2. 运行容器（基础示例）：
   - `docker run -d --name webhook-relay -p 8080:8080 webhook-relay`

   默认配置：
   - 工作目录：`/app`
   - 配置与数据库目录：`/app/config`
   - 默认数据库：`sqlite:///./config/data.db`

3. 使用持久化存储：
   - 在宿主机创建配置/数据目录，例如：`/srv/webhook-relay/config`
   - 将初始配置文件与数据库（可选）放入该目录
   - 启动容器时挂载目录：
     - `docker run -d --name webhook-relay -p 8080:8080 -v /srv/webhook-relay/config:/app/config webhook-relay`

4. 自定义数据库：
   - 通过环境变量 `DB_PATH` 覆盖默认数据库连接：
     - 例如：`-e DB_PATH="sqlite:///./config/data.db"`（默认值）
     - 或者：`-e DB_PATH="postgresql+psycopg2://user:pass@host:5432/dbname"`（需要自行安装驱动并调整镜像）

## 管理后台与规则配置概览

管理后台主要页面：
- 端点管理（Endpoints）：维护不同业务线/系统对应的 `namespace`
- 目标管理（Targets）：配置转发目标的名称、URL 与超时时间
- 渠道管理（Channels）：配置飞书/企微等机器人 Webhook
- 模板管理（Templates）：配置消息模板内容
- 端点详情：以树形方式配置 ProcessingRule 与 RuleAction，支持：
  - 根规则与子规则
  - 动作类型：转发或通知
  - 模板变量与模板继承
- 日志页面：查看 RequestLog 与 DeliveryLog 记录

典型流程：
1. 在 “Targets” 中配置内部系统的 Webhook URL
2. 在 “Channels” 中配置飞书/企微机器人地址
3. 在 “Templates” 中配置通用或专用消息模板
4. 在 “Endpoints” 中创建业务端点，并在详情页中：
   - 创建根规则，按 `remark` 或其他字段区分不同业务来源
   - 在子规则中根据 `event_define_no` 等字段区分事件类型
   - 为规则添加 Forward/Notify 动作，绑定目标、渠道与模板变量

## 推到 Gitea 与服务器部署建议

1. 在本地完成配置与验证后，将整个仓库推送到 Gitea：
   - 初始化 git 仓库（如尚未初始化）：`git init`
   - 添加远程并推送到 Gitea 项目

2. 在服务器上通过 Gitea 拉取代码：
   - 使用 Gitea 的 “克隆” 地址在服务器执行 `git clone`

3. 在服务器上构建并运行 Docker 镜像：
   - `docker build -t webhook-relay .`
   - 准备持久化目录并挂载配置/数据库
   - `docker run -d --name webhook-relay -p 8080:8080 -v /srv/webhook-relay/config:/app/config webhook-relay`

4. 如需进一步自动化（CI/CD）：
   - 可以在 Gitea 中配置 Actions 或 Webhook，在推送时自动触发服务器上的构建与重启逻辑
   - 具体流水线脚本可根据你的服务器环境与习惯单独设计

更详细的架构、流程与用例说明可参考：
- `docs/webhook-relay/ALIGNMENT_webhook-relay.md`
- `docs/webhook-relay/DESIGN_webhook-relay.md`
- `docs/webhook-relay/FLOWCHART.md`
- `docs/webhook-relay/ACCEPTANCE_webhook-relay.md`