houhuan
2bc7460f1f
- 添加FastAPI应用基础结构，包括主入口、路由和模型定义
- 实现Webhook接收端点(/webhook/{namespace})和健康检查(/health)
- 添加管理后台路由和模板，支持端点、目标、渠道和模板管理
- 包含SQLite数据库模型定义和初始化逻辑
- 添加日志记录和统计服务
- 包含Dockerfile和配置示例文件
- 添加项目文档，包括设计、流程图和验收标准
119 lines
5.1 KiB
Markdown
119 lines
5.1 KiB
Markdown
## 项目简介
|
||
|
||
这是一个可配置的 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`
|
||
|