Chongming-Zenoh
基于 FastAPI + Zenoh + Vue 3 的配置驱动微服务网关平台。
核心理念：通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型和 FastAPI 路由， 底层通过 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控制 - Argon2id 密码哈希：Rust 实现的高性能密码安全方案
- 对象存储代理：集成
nanio（S3 兼容）文件上传/下载 - 构建打包：支持 PyInstaller / Nuitka 一键打包为独立可执行文件
- Vue 3 前端：Element Plus UI、Pinia 状态管理、自动生成类型安全的 API 客户端
项目结构
chongming-zenoh/
├── config.toml # 应用主配置
├── pyproject.toml # 项目依赖与工具配置
├── config/ # 配置文件目录
│ ├── README.md # 配置说明
│ ├── zenoh_config.json5 # Zenoh 会话配置
│ └── workers/ # Worker 路由定义
│ ├── config.toml # Worker 插件注册列表
│ ├── auth/ # 鉴权插件 TOML
│ ├── doubao/ # 豆包插件 TOML
│ └── example/ # 示例插件 TOML
├── src/
│ ├── chongming/ # 核心应用
│ │ ├── app/
│ │ │ ├── core/ # WorkerManager、RouteGenerator、鉴权
│ │ │ └── routes/ # 内置路由（存储上传等）
│ │ └── scripts/ # 工具脚本（build, gen_models）
│ ├── chongming-web/ # Vue 3 前端
│ │ ├── src/
│ │ │ ├── api/generated/ # 自动生成的 API 客户端（@hey-api/openapi-ts）
│ │ │ ├── views/ # 页面组件
│ │ │ ├── router/ # 路由配置
│ │ │ └── stores/ # Pinia 状态管理
│ │ └── vite.config.ts
│ └── plugins/ # Worker 插件源码
│ ├── auth/ # 鉴权（注册/登录/用户信息/改密）
│ ├── doubao/ # 豆包视觉理解
│ └── example/ # 示例（四则运算）
├── utils/ # 子工具包（独立 Python 包）
│ ├── config/ # 配置加载
│ ├── database/ # 异步 SQLite 封装
│ ├── jwt/ # JWT 编码/验证（Rust）
│ ├── password/ # Argon2id 密码哈希（Rust）
│ ├── request/ # Zenoh 客户端封装
│ └── worker/ # Worker 框架核心
├── public/ # 公共启动文件
├── data/storage/chongming/ # 本地数据存储
├── logs/ # 日志目录
└── resources/ # 模块银行打包资源
快速开始
环境要求
- Python >= 3.12
- Rust 工具链（用于编译
jwt/password扩展） - Node.js >= 22（用于前端开发）
- uv 包管理器
安装与启动
# 1. 克隆项目
git clone <repo-url>
cd chongming-zenoh
# 2. 安装 Python 依赖（自动编译 Rust 扩展）
uv sync
# 3. 启动服务（开发模式，含热重载）
uv run serve
访问 API 文档：http://localhost:8000/docs
前端开发
cd src/chongming-web
npm install
npm run dev # 开发服务器 http://localhost:5173
npm run build # 生产构建
架构与数据流
graph LR
A[用户请求] --> B[FastAPI 路由<br/>自动生成]
B --> C{鉴权检查}
C -->|通过| D[WorkerManager.call]
D --> E[Zenoh Query]
E --> F[Worker Queryable]
F --> G[插件业务逻辑]
G --> H[响应]
启动流程：
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/ 生成路由
开发指南
添加新 Worker 插件
- 创建
src/plugins/<name>/目录结构 - 在
config/workers/config.toml注册插件 - 创建
config/workers/<name>/*.toml端点定义 - 运行
uv run python -m chongming.scripts.gen_models生成模型 - 实现
router/*.py业务逻辑 - 实现
__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 [GET] |
GET 参数列表（"name: type"） |
auth_required |
<操作>.toml |
是否需要 JWT 鉴权 |
internal |
<操作>.toml |
设为 true 则仅允许内部 RPC 调用，不注册 HTTP 路由 |
cacheable |
<操作>.toml |
端点是否可缓存 |
summary |
<操作>.toml |
端点描述（OpenAPI docs） |
内置插件
| 插件 | 路由前缀 | 说明 |
|---|---|---|
| auth | /auth |
用户注册、登录、JWT 鉴权、个人信息、密码修改 |
| doubao | /doubao |
火山引擎豆包视觉理解模型集成 |
| example | /calc |
四则运算示例（加/减/乘/除）+ 访问计数器 |
工具包
| 包名 | 说明 | 技术栈 |
|---|---|---|
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 |