From ade4f394bca31e11a0a717bdfa27a68acd0c3c5f Mon Sep 17 00:00:00 2001 From: chakcy <947105045@qq.com> Date: Fri, 14 Aug 2026 18:22:59 +0800 Subject: [PATCH] =?UTF-8?q?modify:=20README=20=E8=A1=A5=E5=85=85=E6=B7=B7?= =?UTF-8?q?=E5=90=88=E9=83=A8=E7=BD=B2=E4=B8=8E=E8=BF=9B=E7=A8=8B=E6=8F=92?= =?UTF-8?q?=E4=BB=B6=E9=9A=94=E7=A6=BB=E6=9E=B6=E6=9E=84=EF=BC=88=E5=8A=A8?= =?UTF-8?q?=E6=80=81=E8=B7=AF=E7=94=B1=E6=B3=A8=E5=86=8C/=E5=AE=B9?= =?UTF-8?q?=E5=99=A8=E9=83=A8=E7=BD=B2/=E5=91=BD=E4=BB=A4=E5=85=A5?= =?UTF-8?q?=E5=8F=A3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 96 +++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 68 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 25bc019..afb461d 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,9 @@ | **动态路由生成** | 扫描 `config/workers/*/*.toml` 自动注册 HTTP 路由 | | **Worker 框架** | `@rpc_method` 装饰器 + `Plugin` 基类统一生命周期 + Pydantic 模型绑定 | | **启动契约校验** | TOML 路由 ↔ `@rpc_method` ↔ 生成模型三方一致性校验，fail fast | +| **混合部署** | inline（网关进程内）与 external（独立进程）两种插件模式按插件粒度共存 | +| **动态路由注册** | external 插件经 Zenoh 注册路由，网关动态挂载/摘除 HTTP 端点 | +| **进程插件隔离** | 进程插件与网关零导入关系，仅经 Zenoh 通讯，可独立打包到不同容器 | | **自动化模型生成** | `gen_models` 根据 TOML 配置生成请求/响应模型 | | **插件脚手架** | `gen_plugin` 一键生成风格统一的 Worker 插件骨架 | | **JWT 鉴权** | Rust 实现，路由级 `auth_required` 控制 | @@ -172,18 +175,27 @@ npm run dev # http://localhost:5173 ```mermaid graph TB - HTTP[HTTP 客户端] -->|REST API| FastAPI[FastAPI 路由
TOML 自动生成] - MQTT[MQTT 客户端] -->|chongming/+/+| Bridge[MQTT Bridge
纯客户端模式] + HTTP[HTTP 客户端] -->|REST API| API[FastAPI 动态路由] + MQTT[MQTT 客户端] -->|chongming/+/+| BRIDGE[MQTT Bridge
纯客户端模式] - FastAPI --> WM[WorkerManager
随机负载均衡 + 超时重试] - Bridge --> WM + REG[RouteRegistry
订阅 chongming/routes/**] -->|动态挂载/摘除 HTTP 路由| API + API --> WM[WorkerManager
随机负载均衡 + 超时重试] + BRIDGE --> WM - WM -->|Zenoh Query| W1[Worker 副本 1] - WM -->|Zenoh Query| W2[Worker 副本 2] - WM -->|Zenoh Query| W3[Worker 副本 N] + subgraph GW[网关进程 chongming] + API + REG + BRIDGE + WM + end - W1 & W2 & W3 -->|插件业务逻辑| DB[(SQLite)] - W1 & W2 & W3 -->|AI 调用| AI[豆包 API] + WM -->|Zenoh Query| IW[inline Worker 副本
网关进程内加载] + WM -->|Zenoh Query| EW[external Worker 进程
独立容器，零网关依赖] + EW -.->|发布路由描述符
chongming/routes/**| REG + + IW --> DB[(SQLite)] + EW --> DB + EW -->|AI 调用| AI[豆包 API] ``` **启动流程**： @@ -192,10 +204,14 @@ graph TB uv run serve → FastAPI lifespan: 1. setup_storage() — 本地文件系统存储 2. setup_zenoh() — Zenoh peer 会话 - 3. setup_worker_manager() — WorkerManager + 定期 liveliness 刷新 - 4. load_workers() — 动态 import 插件 → 启动 Worker 协程 - 5. register_routes() — 扫描 config/workers/ 生成 HTTP 路由 - 6. setup_mqtt() — 内嵌 Broker（子进程）+ MQTT Bridge + 3. setup_mqtt_broker() — 内嵌 Broker（子进程 + 文件锁单例） + 4. setup_worker_manager() — WorkerManager + 定期 liveliness 刷新 + 5. load_workers() — 按插件 [workers].load_mode 分派: + inline → 进程内 import 插件 → 启动 Worker 协程 + external → 跳过（独立进程运行），启动 RouteRegistry 订阅 chongming/routes/** + 6. validate_contracts() — inline 插件三方契约校验，失败终止启动 + 7. register_routes() — inline 插件盘扫生成 HTTP 路由 + 8. setup_mqtt() — MQTT Bridge（inline 主题静态收集 + external 主题动态推送） ``` --- @@ -247,6 +263,41 @@ async def upload(file: UploadFile = File(...)): --- +## 进程插件与混合部署 + +两种插件运行模式**按插件粒度共存**，在 `config/workers//config.toml` 的 `[workers]` 节声明： + +```toml +load_mode = "inline" # 默认：插件在网关进程内加载 +load_mode = "external" # 独立进程运行，经 Zenoh 注册路由 +``` + +**inline 插件**（`src/plugins/`，chongming-plugins 仓库）： + +- 网关进程内 import；路由由网关盘扫 TOML 生成；契约校验在网关启动时执行 + +**external 进程插件**（本地开发目录 `workers/`，不入库）： + +- 与网关**零导入关系**：只依赖 `chongming-worker` SDK + zenoh，仅经 Zenoh 通讯 + - 路由注册：worker 启动时 put 描述符到 `chongming/routes//...`，退出时 delete；每 10s 周期重发布自愈 + - 服务发现：liveliness `worker//`（与 inline 副本同一机制，网关无需改动） +- worker 进程自读 TOML 并在**自己进程内**做契约校验（`chongming_worker.contracts`）； + 网关 RouteRegistry 订阅描述符后动态挂载/摘除 HTTP 路由（type 级 2s 防抖） +- 代码结构与 inline 插件完全一致（Plugin 基类 + router/ + models/），示例见本地 `workers/demo/` +- 运行： + + ```bash + uv run worker_serve --type demo # 本地调试 + chongming-worker --type demo # 容器入口（chongming-worker SDK console script） + ``` + +- 生产部署：进程插件与网关**分别打包到不同容器** + - 网关容器：`chongming` + 依赖 + - 进程插件容器：插件代码 + `chongming-worker` + 依赖 +- 隔离性由 `test_worker_isolation.py` 保证（阻断 chongming 导入 + AST 检查 import 语句） + +--- + ## MQTT 协议 ### Topic 约定 @@ -342,7 +393,8 @@ uv run serve # 启动开发服务 uv run gen_plugin # 生成统一风格插件骨架 uv run python -m chongming.scripts.gen_models # 生成 Pydantic 模型 uv run python -m chongming.scripts.build # 构建打包（PyInstaller/Nuitka） -uv run worker_serve --type # 以独立进程运行 Worker（load_mode=external） +uv run worker_serve --type # 独立 Worker 进程（本地调试，load_mode=external） +chongming-worker --type # 独立 Worker 进程（容器入口） uv pip install -e utils/ # 安装/更新工具包 ``` @@ -369,7 +421,7 @@ uv pip install -e utils/ # 安装/更新工具包 | **chongming-jwt** | `utils/jwt/` | Rust + PyO3 | JWT 编解码，支持 HS256/384/512 + RS256/384/512 | | **chongming-password** | `utils/password/` | Rust + PyO3 | Argon2id 密码哈希与验证 | | **chongming-request** | `utils/request/` | Python | Zenoh RPC 直连客户端 | -| **chongming-worker** | `utils/worker/` | Python | Worker 框架核心：装饰器、运行时、配置加载 | +| **chongming-worker** | `utils/worker/` | Python | Worker 框架核心：装饰器、运行时、契约校验、独立进程入口（`chongming-worker`） | | **chongming-stream-manager** | `utils/stream_manager/` | Python | ffmpeg + MediaMTX RTSP 流代理管理 | | **bytedance** | `utils/bytedance/` | Python | 字节跳动 AICC 安全通信 SDK（Jeddak 等） | @@ -421,6 +473,7 @@ uv run gen_plugin # 生成统一风格插件骨架 uv run python -m chongming.scripts.gen_models # 生成 Pydantic 模型 uv run build pyinstaller # PyInstaller 打包 uv run build nuitka # Nuitka 打包 +chongming-worker --type # 独立 Worker 进程（进程插件容器入口） uv pip install -e utils/ # 安装/更新工具包子包 ``` @@ -451,19 +504,6 @@ uv pip install -e utils/ # 安装/更新工具包子包 --- -## 工具包 - -| 包名 | 说明 | 技术栈 | -| -------------------- | --------------------------------------------- | ----------- | -| `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)