Chongming-Zenoh

基于 FastAPI + Zenoh + MQTT + Vue 3 的配置驱动微服务网关平台。

核心理念：通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型，同时暴露 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 实现的高性能密码安全方案
• 对象存储代理：集成 nanio（S3 兼容）文件上传/下载
• 构建打包：支持 PyInstaller / Nuitka 一键打包为独立可执行文件
• Vue 3 前端：Element Plus UI、Pinia 状态管理、自动生成类型安全的 API 客户端

---

项目结构

chongming-zenoh/
├── config.toml                   # 应用主配置（含 MQTT、Zenoh、DB 等）
├── pyproject.toml                # 项目依赖与工具配置
├── config/                       # 配置文件目录
│   ├── zenoh_config.json5        # Zenoh 会话配置
│   └── workers/                  # Worker 路由定义（TOML）
│       ├── config.toml           # 插件注册列表
│       ├── auth/                 # 鉴权插件（login / register / me / …）
│       ├── doubao/               # 豆包视觉理解插件
│       └── example/              # 示例插件（add / heartbeat / …）
├── src/
│   ├── chongming/                # 核心应用
│   │   ├── app/
│   │   │   ├── core/             # WorkerManager, RouteGenerator, MQTTBridge, auth
│   │   │   └── routes/           # 内置路由（存储上传等）
│   │   └── scripts/              # build, gen_models
│   ├── chongming-web/            # Vue 3 前端
│   │   └── src/
│   │       ├── api/generated/    # 自动生成 API 客户端
│   │       ├── views/            # 页面组件
│   │       └── 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/       # 本地数据存储
├── logs/                         # 日志目录
└── resources/                    # 模块银行打包资源

---

快速开始

环境要求

• Python >= 3.12
• Rust 工具链（用于编译 jwt / password 扩展）
• Node.js >= 22（前端开发）
• uv 包管理器

安装与启动

uv sync                          # 安装依赖 + 编译 Rust 扩展
uv run serve                     # 启动服务（开发模式，热重载）

服务启动后可用：

通道	地址	说明
HTTP	http://localhost:8000	REST API + Swagger 文档
MQTT	mqtt://localhost:1883	内嵌 Broker，Worker 桥接
Nanio	http://localhost:9000	S3 兼容对象存储
Swagger	http://localhost:8000/docs	OpenAPI 文档

前端开发

cd src/chongming-web
npm install && npm run dev        # http://localhost:5173

---

架构与数据流

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]

启动流程：

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 插件 → 启动 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 则跳过）

快速测试

# 终端 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 自动跳过响应发布：

@rpc_method(subject="example.heartbeat", method="MQTT")
async def heartbeat(worker_id: str = "") -> None:
    return None  # Bridge 跳过发布

配置

# 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

# 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>/ — __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 导入

详见 插件开发指南。

常用命令

uv run serve                              # 启动开发服务器
uv run python -m chongming.scripts.gen_models  # 生成 Pydantic 模型
uv run build pyinstaller                  # PyInstaller 打包
uv run build nuitka                       # Nuitka 打包
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	参数列表（"name: type" 格式）
auth_required	<操作>.toml	是否需要 JWT 鉴权
internal	<操作>.toml	true 则仅限内部 RPC，不注册 HTTP 路由
cacheable	<操作>.toml	端点是否可缓存
summary	<操作>.toml	端点描述（用于 OpenAPI / 日志）

---

内置插件

插件	HTTP 前缀	MQTT 主题前缀	说明
auth	/auth	auth.*	注册、登录、JWT 鉴权、个人信息、改密
doubao	/doubao	doubao.*	火山引擎豆包视觉理解模型
example	/calc	example.*	四则运算 + 访问计数 + MQTT 心跳示例

---

工具包

包名	说明	技术栈
chongming-config	TOML 配置加载、TypedDict 类型定义	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-worker	Worker 框架核心（@rpc_method、运行时）	Python

---

更多文档

• 配置说明
• 插件开发指南
• 前端开发指南
• Worker 框架