houhuan
2bc7460f1f
- 添加FastAPI应用基础结构，包括主入口、路由和模型定义
- 实现Webhook接收端点(/webhook/{namespace})和健康检查(/health)
- 添加管理后台路由和模板，支持端点、目标、渠道和模板管理
- 包含SQLite数据库模型定义和初始化逻辑
- 添加日志记录和统计服务
- 包含Dockerfile和配置示例文件
- 添加项目文档，包括设计、流程图和验收标准
52 lines
2.0 KiB
Markdown
52 lines
2.0 KiB
Markdown
# 架构设计
|
||
|
||
## 总体架构
|
||
```mermaid
|
||
flowchart LR
|
||
A[Incoming Webhook] --> B[FastAPI /webhook/{namespace}]
|
||
B --> C[Router]
|
||
C --> D[Targets Forwarder]
|
||
B --> E[Event Template]
|
||
E --> F[Channels Sender]
|
||
D --> G[External Webhook Targets]
|
||
F --> H[Feishu]
|
||
F --> I[WeCom]
|
||
```
|
||
|
||
## 模块分层
|
||
- 接入层：`app/main.py`（FastAPI 入口与 Webhook 接收）
|
||
- 管理后台：`app/admin.py`（端点、规则、模板与渠道的增删改查）
|
||
- 领域模型与持久化：`app/db.py`, `app/models.py`
|
||
- 规则引擎：`app/services/engine.py`（树形规则 + 动作编排）
|
||
- 通知发送：`app/services/notify.py`
|
||
- 统计与日志：`app/services/stats.py`, `app/logging.py`
|
||
|
||
## 关键接口
|
||
- `engine.process(endpoint_id, payload) -> (routed: List, notified: List)`
|
||
- `_exec_forward(target, payload) -> Result`（内部使用）
|
||
- `_exec_notify(channel, msg) -> Result`（内部使用）
|
||
- 管理接口：`/admin/*` 用于维护端点、规则树、动作、模板与渠道
|
||
|
||
## 数据契约
|
||
- 输入：示例 JSON 结构，关键字段存在于顶层与 `trans_order_info`
|
||
- 输出：`{"namespace": str, "routed": [...], "notified": [...]}`，其中：
|
||
- `routed`：每个转发目标的执行摘要（目标名、是否成功、失败原因）
|
||
- `notified`：每个通知渠道的执行摘要（渠道名、是否成功、失败原因）
|
||
|
||
## 异常策略
|
||
- 超时与网络错误重试；失败记录结构化日志
|
||
- 非致命错误不影响其他目标或渠道发送
|
||
|
||
## 部署与运行（概要）
|
||
- 本地直接运行：
|
||
- 创建并激活虚拟环境（可选）
|
||
- 执行 `pip install -r requirements.txt`
|
||
- 启动服务：`uvicorn app.main:app --host 0.0.0.0 --port 8080`
|
||
- Docker 部署：
|
||
- 构建镜像：`docker build -t webhook-relay .`
|
||
- 运行容器示例：
|
||
- `docker run -d --name webhook-relay -p 8080:8080 webhook-relay`
|
||
- 默认使用 SQLite 数据库，路径由环境变量 `DB_PATH` 控制，默认值为 `sqlite:///./config/data.db`
|
||
- 如需持久化，可将宿主机目录挂载到容器内 `/app/config` 目录
|
||
|