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 客户端

---

## 项目结构

```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)