202 lines
8.4 KiB
Markdown
202 lines
8.4 KiB
Markdown
# 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 客户端
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```text
|
||
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](https://docs.astral.sh/uv/) 包管理器
|
||
|
||
### 安装与启动
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone <repo-url>
|
||
cd chongming-zenoh
|
||
|
||
# 2. 安装 Python 依赖（自动编译 Rust 扩展）
|
||
uv sync
|
||
|
||
# 3. 启动服务（开发模式，含热重载）
|
||
uv run serve
|
||
```
|
||
|
||
访问 API 文档：`http://localhost:8000/docs`
|
||
|
||
### 前端开发
|
||
|
||
```bash
|
||
cd src/chongming-web
|
||
npm install
|
||
npm run dev # 开发服务器 http://localhost:5173
|
||
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[响应]
|
||
```
|
||
|
||
启动流程：
|
||
|
||
```
|
||
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` 工厂函数
|
||
|
||
详见 [插件开发指南](src/plugins/README.md) 和 [配置说明](config/README.md)。
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
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 |
|
||
|
||
---
|
||
|
||
## 更多文档
|
||
|
||
- [配置说明](config/README.md)
|
||
- [插件开发指南](src/plugins/README.md)
|
||
- [前端开发指南](src/chongming-web/README.md)
|
||
- [Worker 框架](utils/worker/README.md)
|