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

modify: 说明文档

Browse Source
This commit is contained in:
chakcy
2026-08-05 18:18:48 +08:00
parent 42aa007253
commit 44ffee79c7
3 changed files with 186 additions and 181 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+181 -177
View File
@@ -2,24 +2,27 @@
基于 **FastAPI + Zenoh + MQTT + Vue 3** 的**配置驱动微服务网关平台**。
核心理念：通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型，同时暴露 **HTTP** 和 **MQTT** 双通道。
底层通过 Zenoh 分布式消息协议进行 RPC 通信，Worker 插件可独立开发、热加载、水平扩展。
通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型与 FastAPI 路由，同时暴露 **HTTP** 和 **MQTT** 双通道。底层基于 Zenoh 分布式消息协议实现 RPC 通信，Worker 插件可独立开发、热加载、水平扩展。
---
## 核心特性
- **FastAPI + Uvicorn**：高性能异步 Web 框架，自动生成 OpenAPI 文档
- **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 实现的高性能密码安全方案
- **文件存储**：本地文件系统上传/下载
- **构建打包**：支持 PyInstaller / Nuitka 一键打包为独立可执行文件
- **Vue 3 前端**：Element Plus UI、Pinia 状态管理、自动生成类型安全的 API 客户端
| 特性 | 说明 |
| --------------------- | -------------------------------------------------------------- |
| **FastAPI + Uvicorn** | 高性能异步 Web 框架，自动生成 OpenAPI 文档 |
| **Zenoh 服务发现** | 基于 liveliness 的 Worker 注册与 RPC 调用，负载均衡 + 超时重试 |
| **MQTT 集成** | 内嵌 amqtt Broker，MQTT ↔ Worker 双向桥接 |
| **动态路由生成** | 扫描 `config/workers/*.toml` 自动注册 HTTP 路由 |
| **Worker 框架** | `@rpc_method` 装饰器 + 自动参数解析 + Pydantic 模型绑定 |
| **自动化模型生成** | `gen_models` 根据 TOML 配置生成请求/响应模型 |
| **JWT 鉴权** | Rust 实现，路由级 `auth_required` 控制 |
| **Argon2id 密码哈希** | Rust 实现的高性能密码安全方案 |
| **异步 SQLite** | aiosqlite + SQLModel，多进程并发安全 |
| **本地文件存储** | 内置文件上传/下载端点 |
| **流媒体代理** | ffmpeg + MediaMTX RTSP 流转发 |
| **构建打包** | PyInstaller / Nuitka 一键打包为独立可执行文件 |
| **Vue 3 前端** | Element Plus UI、Pinia 状态管理、类型安全的 API 客户端 |
---
@@ -27,20 +30,21 @@
```text
chongming-zenoh/
├── config.toml # 应用主配置（含 MQTT、Zenoh、DB 等）
├── pyproject.toml # 项目依赖与工具配置
├── config.toml # 应用主配置
├── pyproject.toml # 项目依赖与脚本入口
├── config/ # 配置文件目录
│ ├── zenoh_config.json5 # Zenoh 会话配置
│ └── workers/ # Worker 路由定义（TOML）
│ ├── config.toml # 插件注册列表
│ ├── auth/ # 鉴权插件（login / register / me / …）
│ ├── doubao/ # 豆包视觉理解插件
│ └── example/ # 示例插件（add / heartbeat / …）
│ ├── aibox_sophon_adapter/ # AI Box 设备心跳监控插件
│ └── example/ # 示例插件（四则运算 / MQTT 端点）
├── src/
│ ├── chongming/ # 核心应用
│ │ ├── app/
│ │ │ ├── core/ # WorkerManager, RouteGenerator, MQTTBridge, auth
│ │ │ └── routes/ # 内置路由（存储上传等）
│ │ │ └── routes/ # 内置路由（文件上传等）
│ │ └── scripts/ # build, gen_models
│ ├── chongming-web/ # Vue 3 前端
│ │ └── src/
@@ -49,18 +53,26 @@ chongming-zenoh/
│ │ └── router/ # Vue Router 配置
│ └── plugins/ # Worker 插件源码
│ ├── 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/ # 本地数据存储
│ ├── doubao/ # 豆包 AI（支持 AICC 安全通道）
│ ├── aibox_sophon_adapter/ # 设备心跳 + 告警
│ └── example/ # 演示示例
├── utils/ # 独立工具包
│ ├── bytedance/ # 字节跳动安全通信 SDK
│ ├── config/ # TOML 配置加载
│ ├── database/ # 异步 SQLite 封装
│ ├── jwt/ # Rust JWT 编解码
│ ├── password/ # Rust Argon2id 哈希
│ ├── request/ # Zenoh RPC 客户端
│ ├── stream_manager/ # ffmpeg RTSP 流管理
│ └── worker/ # Worker 框架核心
├── data/
│ ├── storage/chongming/ # SQLite 数据库文件
│ └── uploads/ # 文件上传目录
├── logs/ # 日志目录
└── resources/ # 模块银行打包资源
├── resources/ # 模块银行打包资源
├── test_mqtt_e2e.py # MQTT 端到端测试
├── publisher.py / subscriber.py # MQTT 收发示例
└── README.md
```
---
@@ -73,27 +85,32 @@ chongming-zenoh/
- Rust 工具链（用于编译 `jwt` / `password` 扩展）
- Node.js >= 22（前端开发）
- [uv](https://docs.astral.sh/uv/) 包管理器
- ffmpeg（可选，stream_manager 需要）
### 安装与启动
```bash
uv sync # 安装依赖 + 编译 Rust 扩展
uv run serve # 启动服务（开发模式，热重载）
# 同步依赖（自动编译 Rust 扩展 + 安装 Python 包）
uv sync
# 启动服务（开发模式，热重载）
uv run serve
```
服务启动后可用：
服务启动后：
| 通道 | 地址 | 说明 |
| ------- | ---------------------------- | ------------------------ |
| HTTP | `http://localhost:8000` | REST API + Swagger 文档 |
| MQTT | `mqtt://localhost:1883` | 内嵌 Broker，Worker 桥接 |
| Swagger | `http://localhost:8000/docs` | OpenAPI 文档 |
| 通道 | 地址 | 说明 |
| ------- | ---------------------------- | ---------------- |
| HTTP | `http://localhost:8000` | REST API |
| Swagger | `http://localhost:8000/docs` | OpenAPI 交互文档 |
| MQTT | `mqtt://localhost:1883` | 内嵌 Broker |
### 前端开发
```bash
cd src/chongming-web
npm install && npm run dev # http://localhost:5173
npm install
npm run dev # http://localhost:5173
```
---
@@ -102,201 +119,188 @@ npm install && npm run dev # http://localhost:5173
```mermaid
graph TB
HTTP[HTTP 客户端] -->|REST API| FastAPI[FastAPI 路由<br/>自动生成]
MQTT[MQTT 客户端] -->|chongming/+/+| Bridge[MQTT Bridge<br/>内嵌 Broker]
HTTP[HTTP 客户端] -->|REST API| FastAPI[FastAPI 路由<br/>TOML 自动生成]
MQTT[MQTT 客户端] -->|chongming/+/+| Bridge[MQTT Bridge<br/>纯客户端模式]
FastAPI --> WM[WorkerManager]
FastAPI --> WM[WorkerManager<br/>随机负载均衡 + 超时重试]
Bridge --> WM
WM -->|Zenoh Query| W1[Worker 副本 1]
WM -->|负载均衡| W2[Worker 副本 2]
WM -->|超时重试| W3[Worker 副本 N]
WM -->|Zenoh Query| W2[Worker 副本 2]
WM -->|Zenoh Query| W3[Worker 副本 N]
W1 & W2 & W3 -->|插件业务逻辑| DB[(SQLite)]
W1 & W2 & W3 -->|AI 调用| AI[豆包 API]
```
启动流程：
**启动流程**：
```
uv run serve → FastAPI lifespan:
1. setup_storage() — 本地文件系统存储
2. setup_zenoh() — Zenoh peer 会话
3. setup_worker_manager() — WorkerManager + liveliness 刷新
4. load_workers() — 动态 import 插件 → 启动 Worker 协程
5. register_routes() — 扫描 config/workers/ 生成 HTTP 路由
6. setup_mqtt() — 内嵌 Broker + MQTT→Worker 桥接
1. setup_storage() — 本地文件系统存储
2. setup_zenoh() — Zenoh peer 会话
3. setup_worker_manager() — WorkerManager + 定期 liveliness 刷新
4. load_workers() — 动态 import 插件 → 启动 Worker 协程
5. register_routes() — 扫描 config/workers/ 生成 HTTP 路由
6. setup_mqtt() — 内嵌 Broker（子进程）+ MQTT Bridge
```
---
## 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"]
```
| 节类型 | HTTP 路由 | OpenAPI 文档 | MQTT | 请求模型命名 |
| -------- | --------- | ------------ | ---- | ------------------------------------- |
| `[GET]` | ✅ | ✅ | ✅ | `XxxGetRequest / XxxGetResponse` |
| `[POST]` | ✅ | ✅ | ✅ | `XxxPostRequest / XxxPostResponse` |
| `[MQTT]` | ❌ | ❌ | ✅ | `XxxMqttRequest`（无 response_model） |
### 两种路由注册方式
本项目支持两种路由注册方式，根据场景选用：
#### 方式一：TOML 动态路由（标准 JSON 端点）
通过 `config/workers/<插件>/*.toml` 定义 `[GET]` / `[POST]` 节，网关自动生成 FastAPI 路由。
适用于参数和响应可被 Pydantic 模型描述的标准 JSON 接口。
- 路由生成流程：`TOML 配置 → 自动生成 Pydantic 模型 → 注册 FastAPI 路由`
- 底层 RPC：`FastAPI 路由 → WorkerManager.call() → Zenoh Query → Worker @rpc_method → 响应`
通过 `config/workers/<插件>/*.toml` 定义端点，自动生成 FastAPI 路由。适用于参数和响应可被 Pydantic 模型描述的标准接口。
```toml
# config/workers/example/add.toml
[GET]
summary = "加法"
summary = "加法运算"
params = ["a: float", "b: float"]
[GET.response_model]
result = { type = "float", required = true }
```
#### 方式二：插件自定义路由（特殊端点）
当端点无法用 TOML 描述时（如 `multipart/form-data` 文件上传），插件可在模块顶层暴露
一个 `APIRouter` 实例，网关在 `load_workers()` 阶段自动发现并注册（无需修改网关代码）。
**约定**：插件模块（`__init__.py`）需导入并暴露一个名为 `router` 的 `APIRouter` 实例：
```python
# src/plugins/<name>/__init__.py
from .routes import router # 暴露给网关自动发现
```
当端点无法用 TOML 描述时（如 `multipart/form-data` 上传），插件暴露 `APIRouter` 实例，网关自动发现并注册。
```python
# src/plugins/<name>/routes.py
from fastapi import APIRouter, UploadFile, File, Form
from fastapi import APIRouter, UploadFile, File
router = APIRouter(prefix="/<prefix>", tags=["<worker_type>"])
@router.post("/upload")
async def upload(
file: UploadFile = File(...),
param1: str = Form(...),
):
async def upload(file: UploadFile = File(...)):
...
return {"result": "ok"}
```
- 全局前缀（如 `/api/v1`）由网关自动注入，插件无需关心
- tags 应与 TOML 自动生成的端点保持一致（使用 worker_type）
- TOML 配置中对应端点应设 `internal = true`，避免重复注册
> **约定**：插件 `__init__.py` 中导入 `router` 实例（`from .routes import router`），网关通过 `getattr(module, "router", None)` 自动发现。
### HTTP / MQTT 调用路径
---
同一端点通过**不同通道**到达 Worker 的路径对比：
## MQTT 协议
| 通道 | 调用路径 | 适用场景 |
| -------- | --------------------------------------------------------------------------------------- | ------------------------------ |
| **HTTP** | `客户端 → FastAPI 路由 → WorkerManager.call() → Zenoh Query → Worker` | REST API、Web 前端、文件上传 |
| **MQTT** | `MQTT 客户端 → 内嵌 Broker → MQTT Bridge → WorkerManager.call() → Zenoh Query → Worker` | IoT 设备上报、心跳、低带宽环境 |
### Topic 约定
HTTP 和 MQTT 最终都通过 Zenoh RPC 调用 Worker 的 `@rpc_method` 处理函数，业务逻辑完全共享。
| 方向 | Topic | 说明 |
| ---- | -------------------------------- | ------------------------------ |
| 请求 | `chongming/<type>/<op>` | MQTT → Worker |
| 响应 | `chongming/<type>/<op>/response` | Worker → MQTT（`None` 时跳过） |
### 快速测试
```bash
# 终端 1：启动服务
uv run serve
# 终端 2：端到端测试
python test_mqtt_e2e.py
# 手动测试
python subscriber.py # 监听所有响应
python publisher.py example add '{"a":3,"b":5}' # 调用 add
```
┌──────────────────────────────┐
│ WorkerManager │
│ (负载均衡 / 超时重试) │
└──────────┬───────────────────┘
│ Zenoh Query
┌──────────▼───────────────────┐
│ Worker 副本池 │
│ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ W1 │ │ W2 │ │ W3 │ │
│ └──┬──┘ └──┬──┘ └──┬──┘ │
│ │ │ │ │
│ @rpc_method 处理函数 │
└────────────────────────────────┘
HTTP 请求到达 ▲ ▲ MQTT 消息到达
┌───────┘ └───────┐
FastAPI 路由（TOML 自动生成） MQTT Bridge
插件自定义路由（router 约定） (chongming/+/+)
```
---
## 开发指南
### 添加新 Worker 插件
1. 创建 `src/plugins/<name>/` — `__init__.py`, `global_var.py`, `router/`, `models/`
2. 注册到 `config/workers/config.toml`
3. 创建 `config/workers/<name>/*.toml` 端点定义
4. `uv run gen_models config/workers/<name>/ src/plugins/<name>/`
5. 实现 `router/<op>.py`，引用生成的模型
6. 更新 `router/__init__.py` 导入
```text
1. 创建 src/plugins/<name>/ — __init__.py, global_var.py, router/, models/
2. 注册到 config/workers/config.toml 的 [[workers]]
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 导入
```
### 为现有插件添加新端点
```text
1. 创建 config/workers/<name>/<op>.toml
2. 运行 uv run python -m chongming.scripts.gen_models
3. 创建 router/<op>.py → 引用生成的模型
4. 更新 router/__init__.py
5. 重启服务
```
### 常用命令
```bash
uv run serve # 启动开发服务
uv run python -m chongming.scripts.gen_models # 生成 Pydantic 模型
uv run python -m chongming.scripts.build # 构建打包（PyInstaller/Nuitka）
uv pip install -e utils/<name> # 安装/更新工具包
```
---
## 插件列表
| 插件 | 路径 | 功能 |
| ------------------------ | ----------------------------------- | ------------------------------------------------------- |
| **auth** | `src/plugins/auth/` | 用户注册/登录/资料管理，JWT 鉴权，管理员初始化 |
| **doubao** | `src/plugins/doubao/` | 豆包视觉理解，支持 AICC 安全通信通道 |
| **aibox_sophon_adapter** | `src/plugins/aibox_sophon_adapter/` | AI Box 设备心跳监控、离线检测、告警上报与查询、视频上传 |
| **example** | `src/plugins/example/` | 四则运算 + 心跳演示（含 MQTT 端点示例） |
---
## 工具包列表
| 包名 | 路径 | 语言 | 说明 |
| ---------------------------- | ----------------------- | ----------- | ---------------------------------------------- |
| **chongming-config** | `utils/config/` | Python | TOML 配置加载，TypedDict 类型安全 |
| **chongming-database** | `utils/database/` | Python | aiosqlite + SQLModel 异步数据库封装 |
| **chongming-jwt** | `utils/jwt/` | Rust + PyO3 | JWT 编解码，支持 HS256/384/512 + RS256/384/512 |
| **chongming-password** | `utils/password/` | Rust + PyO3 | Argon2id 密码哈希与验证 |
| **chongming-request** | `utils/request/` | Python | Zenoh RPC 直连客户端 |
| **chongming-worker** | `utils/worker/` | Python | Worker 框架核心：装饰器、运行时、配置加载 |
| **chongming-stream-manager** | `utils/stream_manager/` | Python | ffmpeg + MediaMTX RTSP 流代理管理 |
| **bytedance** | `utils/bytedance/` | Python | 字节跳动 AICC 安全通信 SDK（Jeddak 等） |
---
## 配置说明
- **应用配置**：根目录 `config.toml`，包含环境、服务器、安全、MQTT 等全局设置
- **Zenoh 配置**：`config/zenoh_config.json5`
- **Worker 注册**：`config/workers/config.toml`，定义加载的插件及其副本数
- **路由定义**：`config/workers/<name>/*.toml`，每个端点一个文件
详细配置说明见 [`config/README.md`](config/README.md)。
---
## 构建部署
```bash
# PyInstaller 打包
uv run python -m chongming.scripts.build pyinstaller
# Nuitka 打包
uv run python -m chongming.scripts.build nuitka
```
构建过程包括：模块加密打包 → 资源复制 → PyInstaller/Nuitka 打包 → 数据库初始化 → 前端编译 → VFS 挂载。
详见 [插件开发指南](src/plugins/README.md)。