chongming/chongming-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

modify: mqtt broker 适配

Browse Source
This commit is contained in:
chakcy
2026-07-24 16:33:23 +08:00
parent a9ff99959d
commit a29155e033
12 changed files with 781 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+160 -85
View File
@@ -1,22 +1,23 @@
# Chongming-Zenoh
基于 **FastAPI + Zenoh + Vue 3** 的**配置驱动微服务网关平台**。
基于 **FastAPI + Zenoh + MQTT + Vue 3** 的**配置驱动微服务网关平台**。
核心理念：通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型和 FastAPI 路由，
底层通过 Zenoh 分布式消息协议进行 RPC 通信。Worker 插件可独立开发、热加载、水平扩展。
核心理念：通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型，同时暴露 **HTTP** 和 **MQTT** 双通道。
底层通过 Zenoh 分布式消息协议进行 RPC 通信，Worker 插件可独立开发、热加载、水平扩展。
---
## 核心特性
- **FastAPI + Uvicorn**：高性能异步 Web 框架，自动生成 OpenAPI 文档
- **Zenoh 服务发现**：基于 Zenoh liveliness 的 Worker 注册与 RPC 调用，支持负载均衡、超时重试
- **动态路由生成**：根据 `config/workers` 下的 TOML 配置自动生成 API 端点，无需手写路由代码
- **Worker 框架**：使用 `@rpc_method` 装饰器定义 RPC 方法，自动参数解析与 Pydantic 模型绑定
- **自动化模型生成**：`gen_models` 脚本根据 TOML 配置自动生成请求/响应 Pydantic 模型
- **JWT 鉴权**：Rust 实现的 JWT 编码/验证，支持路由级别的 `auth_required` 控制
- **Zenoh 服务发现**：基于 Zenoh liveliness 的 Worker 注册与 RPC 调用，负载均衡 + 超时重试
- **MQTT 集成**：内嵌 amqtt Broker，MQTT 消息自动桥接到 Worker 插件，支持请求/响应与单向上报
- **动态路由生成**：扫描 `config/workers` TOML 配置自动生成 HTTP 路由，`[MQTT]` 节单独处理
- **Worker 框架**：`@rpc_method` 装饰器定义 RPC 方法，自动参数解析与 Pydantic 模型绑定
- **自动化模型生成**：`gen_models` 脚本根据 TOML 配置生成请求/响应 Pydantic 模型（含 MQTT）
- **JWT 鉴权**：Rust 实现，路由级别 `auth_required` 控制
- **Argon2id 密码哈希**：Rust 实现的高性能密码安全方案
- **对象存储代理**：集成 `nanio`（S3 兼容）文件上传/下载
- **对象存储代理**：集成 nanio（S3 兼容）文件上传/下载
- **构建打包**：支持 PyInstaller / Nuitka 一键打包为独立可执行文件
- **Vue 3 前端**：Element Plus UI、Pinia 状态管理、自动生成类型安全的 API 客户端
@@ -26,41 +27,37 @@
```text
chongming-zenoh/
├── config.toml # 应用主配置
├── config.toml # 应用主配置（含 MQTT、Zenoh、DB 等）
├── pyproject.toml # 项目依赖与工具配置
├── config/ # 配置文件目录
│ ├── README.md # 配置说明
│ ├── zenoh_config.json5 # Zenoh 会话配置
│ └── workers/ # Worker 路由定义
│ ├── config.toml # Worker 插件注册列表
│ ├── auth/ # 鉴权插件 TOML
│ ├── doubao/ # 豆包插件 TOML
│ └── example/ # 示例插件 TOML
│ └── workers/ # Worker 路由定义（TOML）
│ ├── config.toml # 插件注册列表
│ ├── auth/ # 鉴权插件（login / register / me / …）
│ ├── doubao/ # 豆包视觉理解插件
│ └── example/ # 示例插件（add / heartbeat / …）
├── src/
│ ├── chongming/ # 核心应用
│ │ ├── app/
│ │ │ ├── core/ # WorkerManager、RouteGenerator、鉴权
│ │ │ ├── core/ # WorkerManager, RouteGenerator, MQTTBridge, auth
│ │ │ └── routes/ # 内置路由（存储上传等）
│ │ └── scripts/ # 工具脚本（build, gen_models）
│ │ └── scripts/ # build, gen_models
│ ├── chongming-web/ # Vue 3 前端
│ │ ├── src/
│ │ │ ├── api/generated/ # 自动生成的 API 客户端（@hey-api/openapi-ts）
│ │ │ ├── views/ # 页面组件
│ │ │ ├── router/ # 路由配置
│ │ │ └── stores/ # Pinia 状态管理
│ │ └── vite.config.ts
│ │ └── src/
│ │ ├── api/generated/ # 自动生成 API 客户端
│ │ ├── views/ # 页面组件
│ │ └── router/ # Vue Router 配置
│ └── plugins/ # Worker 插件源码
│ ├── auth/ # 鉴权（注册/登录/用户信息/改密）
│ ├── doubao/ # 豆包视觉理解
│ └── example/ # 示例（四则运算）
├── utils/ # 子工具包（独立 Python 包）
│ ├── config/ # 配置加载
│ ├── database/ # 异步 SQLite 封装
│ ├── jwt/ # JWT 编码/验证（Rust）
│ ├── password/ # Argon2id 密码哈希（Rust）
│ ├── request/ # Zenoh 客户端封装
│ └── worker/ # Worker 框架核心
├── public/ # 公共启动文件
│ ├── auth/ # JWT 鉴权
│ ├── doubao/ # 豆包 AI
│ └── example/ # 示例（含 MQTT 端点）
├── utils/ # 7 个独立工具包
│ ├── config/ database/ jwt/ lock/
│ ├── password/ request/ worker/
├── test_mqtt_e2e.py # MQTT 端到端测试脚本
├── publisher.py # MQTT 发布示例
├── subscriber.py # MQTT 订阅示例
├── test_amqtt.py # amqtt Broker 独立测试
├── data/storage/chongming/ # 本地数据存储
├── logs/ # 日志目录
└── resources/ # 模块银行打包资源
@@ -74,32 +71,30 @@ chongming-zenoh/
- Python >= 3.12
- Rust 工具链（用于编译 `jwt` / `password` 扩展）
- Node.js >= 22（用于前端开发）
- Node.js >= 22（前端开发）
- [uv](https://docs.astral.sh/uv/) 包管理器
### 安装与启动
```bash
# 1. 克隆项目
git clone <repo-url>
cd chongming-zenoh
# 2. 安装 Python 依赖（自动编译 Rust 扩展）
uv sync
# 3. 启动服务（开发模式，含热重载）
uv run serve
uv sync # 安装依赖 + 编译 Rust 扩展
uv run serve # 启动服务（开发模式，热重载）
```
访问 API 文档：`http://localhost:8000/docs`
服务启动后可用：
| 通道 | 地址 | 说明 |
| ------- | ---------------------------- | ------------------------ |
| HTTP | `http://localhost:8000` | REST API + Swagger 文档 |
| MQTT | `mqtt://localhost:1883` | 内嵌 Broker，Worker 桥接 |
| Nanio | `http://localhost:9000` | S3 兼容对象存储 |
| Swagger | `http://localhost:8000/docs` | OpenAPI 文档 |
### 前端开发
```bash
cd src/chongming-web
npm install
npm run dev # 开发服务器 http://localhost:5173
npm run build # 生产构建
npm install && npm run dev # http://localhost:5173
```
---
@@ -107,42 +102,122 @@ npm run build # 生产构建
## 架构与数据流
```mermaid
graph LR
A[用户请求] --> B[FastAPI 路由<br/>自动生成]
B --> C{鉴权检查}
C -->|通过| D[WorkerManager.call]
D --> E[Zenoh Query]
E --> F[Worker Queryable]
F --> G[插件业务逻辑]
G --> H[响应]
graph TB
HTTP[HTTP 客户端] -->|REST API| FastAPI[FastAPI 路由<br/>自动生成]
MQTT[MQTT 客户端] -->|chongming/+/+| Bridge[MQTT Bridge<br/>内嵌 Broker]
FastAPI --> WM[WorkerManager]
Bridge --> WM
WM -->|Zenoh Query| W1[Worker 副本 1]
WM -->|负载均衡| W2[Worker 副本 2]
WM -->|超时重试| W3[Worker 副本 N]
W1 & W2 & W3 -->|插件业务逻辑| DB[(SQLite)]
W1 & W2 & W3 -->|AI 调用| AI[豆包 API]
```
启动流程：
```
serve() → FastAPI lifespan:
uv run serve → FastAPI lifespan:
1. setup_nanio() — 本地 S3 子进程
2. setup_s3() — boto3 S3 客户端
3. setup_zenoh() — Zenoh peer 会话
4. setup_worker_manager() — WorkerManager + liveliness 发现
5. load_workers() — 动态 import 插件
6. register_routes() — 扫描 config/workers/ 生成路由
4. setup_worker_manager() — WorkerManager + liveliness 刷新
5. load_workers() — 动态 import 插件 → 启动 Worker 协程
6. register_routes() — 扫描 config/workers/ 生成 HTTP 路由
7. setup_mqtt() — 内嵌 Broker + MQTT→Worker 桥接
```
---
## MQTT 集成
### 协议约定
| 方向 | Topic | Payload |
| ---- | -------------------------------- | ------------------------------------------ |
| 请求 | `chongming/<type>/<op>` | `{"_method":"MQTT","param1":"value1",...}` |
| 响应 | `chongming/<type>/<op>/response` | 由 Worker 返回（`None` 则跳过） |
### 快速测试
```bash
# 终端 1: 启动服务
uv run serve
# 终端 2: 端到端测试
python test_mqtt_e2e.py
# 或手动测试
python subscriber.py # 监听所有响应
python publisher.py example add '{"a":3,"b":5,"_method":"MQTT"}' # 有响应
python publisher.py example heartbeat '{"worker_id":"node-1","_method":"MQTT"}' # 无响应
```
### 无响应模式（心跳上报等）
Worker 返回 `None` 时，MQTT Bridge 自动跳过响应发布：
```python
@rpc_method(subject="example.heartbeat", method="MQTT")
async def heartbeat(worker_id: str = "") -> None:
return None # Bridge 跳过发布
```
### 配置
```toml
# config.toml — 按环境区分
[development.mqtt]
enabled = true # false 禁用 MQTT
host = "localhost"
port = 1883
[development.mqtt.broker]
# 可选：amqtt Broker 高级参数
```
---
## 开发指南
### 端点类型说明
TOML 文件中的节类型决定端点暴露方式：
| 节类型 | HTTP 路由 | OpenAPI | MQTT | 请求模型命名 | 备注 |
| -------- | --------- | ------- | ---- | ------------------------- | ------------------- |
| `[GET]` | ✅ | ✅ | ✅ | `XxxGetRequest/Response` | |
| `[POST]` | ✅ | ✅ | ✅ | `XxxPostRequest/Response` | |
| `[MQTT]` | ❌ | ❌ | ✅ | `XxxMqttRequest` | 无 `response_model` |
```toml
# config/workers/example/add.toml
[GET]
summary = "Add via HTTP GET"
params = ["a: float", "b: float"]
[POST]
summary = "Add via HTTP POST"
params = ["a: float", "b: float"]
[MQTT]
summary = "Add via MQTT"
params = ["a: float", "b: float"]
```
### 添加新 Worker 插件
1. 创建 `src/plugins/<name>/` 目录结构
2. 在 `config/workers/config.toml` 注册插件
1. 创建 `src/plugins/<name>/` — `__init__.py`, `global_var.py`, `router/`, `models/`
2. 注册到 `config/workers/config.toml`
3. 创建 `config/workers/<name>/*.toml` 端点定义
4. 运行 `uv run python -m chongming.scripts.gen_models` 生成模型
5. 实现 `router/*.py` 业务逻辑
6. 实现 `__init__.py` 工厂函数
4. `uv run gen_models config/workers/<name>/ src/plugins/<name>/`
5. 实现 `router/<op>.py`，引用生成的模型
6. 更新 `router/__init__.py` 导入
详见 [插件开发指南](src/plugins/README.md) 和 [配置说明](config/README.md)。
详见 [插件开发指南](src/plugins/README.md)。
### 常用命令
@@ -156,27 +231,27 @@ uv pip install -e utils/<name> # 安装/更新工具包子包
### TOML 配置字段速查
| 字段 | 位置 | 说明 |
| -------------------- | --------------------- | --------------------------------------------------- |
| `count` | `workers/config.toml` | Worker 副本数 |
| `router_prefix` | `<插件>/config.toml` | API 路由前缀 |
| `defaults.timeout` | `<插件>/config.toml` | 默认超时（秒） |
| `defaults.cacheable` | `<插件>/config.toml` | 是否缓存 RPC 结果 |
| `params` | `<操作>.toml` `[GET]` | GET 参数列表（`"name: type"`） |
| `auth_required` | `<操作>.toml` | 是否需要 JWT 鉴权 |
| `internal` | `<操作>.toml` | 设为 `true` 则仅允许内部 RPC 调用，不注册 HTTP 路由 |
| `cacheable` | `<操作>.toml` | 端点是否可缓存 |
| `summary` | `<操作>.toml` | 端点描述（OpenAPI docs） |
| 字段 | 位置 | 说明 |
| -------------------- | --------------------- | --------------------------------------- |
| `count` | `workers/config.toml` | Worker 副本数 |
| `router_prefix` | `<插件>/config.toml` | API 路由前缀 |
| `defaults.timeout` | `<插件>/config.toml` | 默认超时（秒） |
| `defaults.cacheable` | `<插件>/config.toml` | 是否缓存 RPC 结果 |
| `params` | `<操作>.toml` | 参数列表（`"name: type"` 格式） |
| `auth_required` | `<操作>.toml` | 是否需要 JWT 鉴权 |
| `internal` | `<操作>.toml` | `true` 则仅限内部 RPC，不注册 HTTP 路由 |
| `cacheable` | `<操作>.toml` | 端点是否可缓存 |
| `summary` | `<操作>.toml` | 端点描述（用于 OpenAPI / 日志） |
---
## 内置插件
| 插件 | 路由前缀 | 说明 |
| ----------- | --------- | -------------------------------------------- |
| **auth** | `/auth` | 用户注册、登录、JWT 鉴权、个人信息、密码修改 |
| **doubao** | `/doubao` | 火山引擎豆包视觉理解模型集成 |
| **example** | `/calc` | 四则运算示例（加/减/乘/除）+ 访问计数器 |
| 插件 | HTTP 前缀 | MQTT 主题前缀 | 说明 |
| ----------- | --------- | ------------- | ------------------------------------ |
| **auth** | `/auth` | `auth.*` | 注册、登录、JWT 鉴权、个人信息、改密 |
| **doubao** | `/doubao` | `doubao.*` | 火山引擎豆包视觉理解模型 |
| **example** | `/calc` | `example.*` | 四则运算 + 访问计数 + MQTT 心跳示例 |
---
@@ -185,10 +260,10 @@ uv pip install -e utils/<name> # 安装/更新工具包子包
| 包名 | 说明 | 技术栈 |
| -------------------- | --------------------------------------------- | ----------- |
| `chongming-config` | TOML 配置加载、TypedDict 类型定义 | Python |
| `chongming-database` | 异步 SQLite 封装（aiosqlite + SQLModel） | Python |
| `chongming-database` | 异步 SQLite（aiosqlite + SQLModel） | Python |
| `chongming-jwt` | JWT 编码/验证（HS256/384/512, RS256/384/512） | Rust + PyO3 |
| `chongming-password` | Argon2id 密码哈希与验证 | Rust + PyO3 |
| `chongming-request` | Zenoh Worker 直连客户端（负载均衡、超时重试） | Python |
| `chongming-request` | Zenoh Worker 客户端（负载均衡、超时重试） | Python |
| `chongming-worker` | Worker 框架核心（`@rpc_method`、运行时） | Python |
---