modify: 添加 internal 路由屏蔽
This commit is contained in:
@@ -1,57 +1,201 @@
|
||||
# chongming Core
|
||||
# Chongming-Zenoh
|
||||
|
||||
基于 FastAPI 的微服务网关脚手架，集成 Zenoh、Worker 框架、动态路由、模块银行何对象存储。
|
||||
基于 **FastAPI + Zenoh + Vue 3** 的**配置驱动微服务网关平台**。
|
||||
|
||||
核心理念：通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型和 FastAPI 路由，
|
||||
底层通过 Zenoh 分布式消息协议进行 RPC 通信。Worker 插件可独立开发、热加载、水平扩展。
|
||||
|
||||
---
|
||||
|
||||
## 核心特性
|
||||
|
||||
- **FastAPI + Uvicorn**：高性能异步 Web 框架
|
||||
- **Zenoh 服务发现**：基于 Zenoh 的 Worker 注册与 RPC 调用
|
||||
- **动态路由生成**：根据 `config/workers` 下的 TOML 配置自动生成 API 端点
|
||||
- **Worker 框架**：使用 `@rpc_method` 装饰器定义 RPC 方法，支持自动生成 Pydantic 模型
|
||||
- **模块银行（module-bank）**：将 Python 模块加密打包为 SQLite 数据库，支持动态导入
|
||||
- **对象存储代理**：集成 `nanio` （S3 兼容）文件上传/下载
|
||||
- **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
|
||||
.
|
||||
├── config/ # 配置文件目录
|
||||
│ ├── workers/ # Worker 路由配置
|
||||
│ └── zenoh_config.json5 # Zenoh 配置
|
||||
├── public/ # 公共启动文件（main.py, server.py）
|
||||
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/ # FastAPI 应用、路由、核心组件
|
||||
│ │ └── scripts/ # 工具脚本（build, gen_models）
|
||||
│ └── plugins/ # Worker 插件源码
|
||||
├── utils/ # 子工具包（worker, request, jwt）
|
||||
├── build_nuitka/ # Nuitka 打包配置示例
|
||||
└── pyproject.toml # 项目依赖与工具配置
|
||||
│ ├── 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/ # 模块银行打包资源
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 安装依赖 （推荐使用 uv）
|
||||
### 环境要求
|
||||
|
||||
- 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
|
||||
```
|
||||
|
||||
2. 启动服务（开发模式）
|
||||
|
||||
```bash
|
||||
# 3. 启动服务（开发模式，含热重载）
|
||||
uv run serve
|
||||
```
|
||||
|
||||
3. 访问 API 文档：`http://localhost:8000/docs`
|
||||
访问 API 文档：`http://localhost:8000/docs`
|
||||
|
||||
## 构建
|
||||
### 前端开发
|
||||
|
||||
- PyInstaller：`uv run build pyinstaller`
|
||||
- Nuitka：`uv run build nuitka`
|
||||
```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 |
|
||||
|
||||
---
|
||||
|
||||
## 更多文档
|
||||
|
||||
- Worker 开发指南（待补充）
|
||||
- [配置说明](http://124.71.68.6:3000/chongming/chongming-config/src/branch/master/README.md)
|
||||
- [配置说明](config/README.md)
|
||||
- [插件开发指南](src/plugins/README.md)
|
||||
- [前端开发指南](src/chongming-web/README.md)
|
||||
- [Worker 框架](utils/worker/README.md)
|
||||
|
||||
Reference in New Issue
Block a user