chongming-core/README.md

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 插件

1. 创建 src/plugins/<name>/ 目录结构
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 工厂函数

详见 插件开发指南 和 配置说明。

常用命令

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

---

更多文档

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