modify: 统一插件风格
This commit is contained in:
@@ -2,7 +2,7 @@
|
||||
|
||||
基于 **FastAPI + Zenoh + MQTT + Vue 3** 的**配置驱动微服务网关平台**。
|
||||
|
||||
通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型与 FastAPI 路由，同时暴露 **HTTP** 和 **MQTT** 双通道。底层基于 Zenoh 分布式消息协议实现 RPC 通信，Worker 插件可独立开发、热加载、水平扩展。
|
||||
通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型与 FastAPI 路由，同时暴露 **HTTP** 和 **MQTT** 双通道。底层基于 Zenoh 分布式消息协议实现 RPC 通信，Worker 插件可独立开发、按副本数水平扩展。
|
||||
|
||||
---
|
||||
|
||||
@@ -13,8 +13,9 @@
|
||||
| **FastAPI + Uvicorn** | 高性能异步 Web 框架，自动生成 OpenAPI 文档 |
|
||||
| **Zenoh 服务发现** | 基于 liveliness 的 Worker 注册与 RPC 调用，负载均衡 + 超时重试 |
|
||||
| **MQTT 集成** | 内嵌 amqtt Broker，MQTT ↔ Worker 双向桥接 |
|
||||
| **动态路由生成** | 扫描 `config/workers/*.toml` 自动注册 HTTP 路由 |
|
||||
| **动态路由生成** | 扫描 `config/workers/*/*.toml` 自动注册 HTTP 路由 |
|
||||
| **Worker 框架** | `@rpc_method` 装饰器 + `Plugin` 基类统一生命周期 + Pydantic 模型绑定 |
|
||||
| **启动契约校验** | TOML 路由 ↔ `@rpc_method` ↔ 生成模型三方一致性校验，fail fast |
|
||||
| **自动化模型生成** | `gen_models` 根据 TOML 配置生成请求/响应模型 |
|
||||
| **插件脚手架** | `gen_plugin` 一键生成风格统一的 Worker 插件骨架 |
|
||||
| **JWT 鉴权** | Rust 实现，路由级 `auth_required` 控制 |
|
||||
@@ -36,15 +37,15 @@ chongming-zenoh/
|
||||
├── config/ # 配置文件目录
|
||||
│ ├── zenoh_config.json5 # Zenoh 会话配置
|
||||
│ └── workers/ # Worker 路由定义（TOML）
|
||||
│ ├── config.toml # 插件注册列表
|
||||
│ ├── auth/ # 鉴权插件（login / register / me / …）
|
||||
│ ├── config.toml # 旧式全局插件注册（仅作兜底兼容）
|
||||
│ ├── auth/ # 鉴权插件（config.toml = 插件注册 + 运行时配置）
|
||||
│ ├── doubao/ # 豆包视觉理解插件
|
||||
│ ├── aibox_sophon_adapter/ # AI Box 设备心跳监控插件
|
||||
│ └── example/ # 示例插件（四则运算 / MQTT 端点）
|
||||
├── src/
|
||||
│ ├── chongming/ # 核心应用
|
||||
│ │ ├── app/
|
||||
│ │ │ ├── core/ # WorkerManager, RouteGenerator, MQTTBridge, auth
|
||||
│ │ │ ├── core/ # WorkerManager, RouteGenerator, MQTTBridge, contracts(契约校验), auth
|
||||
│ │ │ └── routes/ # 内置路由（文件上传等）
|
||||
│ │ └── scripts/ # build, gen_models, gen_plugin
|
||||
│ ├── chongming-web/ # Vue 3 前端
|
||||
@@ -211,17 +212,34 @@ async def upload(file: UploadFile = File(...)):
|
||||
```toml
|
||||
# config/workers/aibox_sophon_adapter/config.toml
|
||||
[[workers.mqtt_topics]]
|
||||
topic = "/board_ping" # 支持 +（单级）/ #（多级，须在末尾）通配符
|
||||
topic = "box/aibox_sophon/board_ping" # 支持 +（单级）/ #（多级，须在末尾）通配符
|
||||
subject = "aibox_sophon_adapter.board_ping" # 可选，{1} {2}... 对应通配符捕获值
|
||||
response_topic = "/board_ping/response" # 可选，响应主题；默认 "<实际主题>/response"
|
||||
```
|
||||
|
||||
- `subject` 缺省为 `<插件类型>.<topic 最后一段>`；`response_topic` 缺省为 `<实际匹配主题>/response`。
|
||||
- 网关发现插件时自动收集所有 `[[workers.mqtt_topics]]`，MQTT Bridge 一并订阅并路由。
|
||||
- 请求负载同样支持 `_method` / `_timeout` / `_cacheable` 控制字段。
|
||||
- 多条自定义主题按配置顺序匹配，先匹配者优先；内置 `chongming/...` 接口最后兜底。
|
||||
- 全局 `[<env>.mqtt].custom_topics` 仍可作为通用兜底（不依赖具体插件时使用，可选）。
|
||||
|
||||
### 请求负载格式（信封协议）
|
||||
|
||||
MQTT 请求负载为信封结构，控制字段与业务数据分离：
|
||||
|
||||
```json
|
||||
{
|
||||
"meta": {
|
||||
"method": "GET", // 可选，默认 GET；MQTT 专用端点需显式 "MQTT"
|
||||
"timeout": 30, // 可选，RPC 超时（秒），默认 30
|
||||
"cacheable": false // 可选，是否允许结果缓存，默认 false
|
||||
},
|
||||
"data": { "a": 3, "b": 5 } // 业务参数，传给 Worker
|
||||
}
|
||||
```
|
||||
|
||||
- 非信封格式的负载会被网关丢弃并告警（严格协议，设备侧请按此格式发布）。
|
||||
- HTTP 通道由网关自动组装信封（注入 method / user_info），无需调用方关心。
|
||||
|
||||
### 快速测试
|
||||
|
||||
```bash
|
||||
@@ -243,14 +261,19 @@ python publisher.py example add '{"a":3,"b":5}' # 调用 add
|
||||
### 添加新 Worker 插件
|
||||
|
||||
```text
|
||||
1. 创建 src/plugins/<name>/ — __init__.py, global_var.py, router/, models/
|
||||
2. 注册到 config/workers/config.toml 的 [[workers]]
|
||||
1. 创建 src/plugins/<name>/ — __init__.py（Plugin 子类）, global_var.py, router/, models/
|
||||
2. 创建 config/workers/<name>/config.toml，在 [workers] 节注册插件
|
||||
（type / module / factory / cleanup / count + [workers.config] 运行时配置）
|
||||
3. 创建 config/workers/<name>/*.toml 端点定义
|
||||
4. 运行 uv run python -m chongming.scripts.gen_models 生成模型
|
||||
5. 实现 router/<op>.py，引用 models/pydantic.py 中的模型
|
||||
6. 更新 router/__init__.py 导入
|
||||
```
|
||||
|
||||
> 推荐用脚手架一步生成骨架：`uv run gen_plugin <name> [operation ...]`。
|
||||
> 启动时网关会做**契约校验**：TOML 路由缺少对应 `@rpc_method` 将导致启动失败，
|
||||
> 模型缺失/孤儿等不一致以警告日志提示。
|
||||
|
||||
### 为现有插件添加新端点
|
||||
|
||||
```text
|
||||
@@ -303,7 +326,7 @@ uv pip install -e utils/<name> # 安装/更新工具包
|
||||
|
||||
- **应用配置**：根目录 `config.toml`，包含环境、服务器、安全、MQTT 等全局设置
|
||||
- **Zenoh 配置**：`config/zenoh_config.json5`
|
||||
- **Worker 注册**：`config/workers/config.toml`，定义加载的插件及其副本数
|
||||
- **插件注册**：`config/workers/<name>/config.toml` 的 `[workers]` 节，定义加载方式、副本数与运行时配置（旧全局 `config/workers/config.toml` 仅作兜底兼容）
|
||||
- **路由定义**：`config/workers/<name>/*.toml`，每个端点一个文件
|
||||
|
||||
详细配置说明见 [`config/README.md`](config/README.md)。
|
||||
@@ -339,7 +362,7 @@ uv pip install -e utils/<name> # 安装/更新工具包子包
|
||||
|
||||
| 字段 | 位置 | 说明 |
|
||||
| -------------------- | --------------------- | --------------------------------------- |
|
||||
| `count` | `workers/config.toml` | Worker 副本数 |
|
||||
| `count` | `<插件>/config.toml` | Worker 副本数（`[workers]` 节） |
|
||||
| `router_prefix` | `<插件>/config.toml` | API 路由前缀 |
|
||||
| `defaults.timeout` | `<插件>/config.toml` | 默认超时（秒） |
|
||||
| `defaults.cacheable` | `<插件>/config.toml` | 是否缓存 RPC 结果 |
|
||||
|
||||
Reference in New Issue
Block a user