chongming/chongming-core

Fork 0

Files

T

chakcy c0b9d7e75f modify 进程插件开发文档

2026-08-21 14:55:31 +08:00

32 KiB

Raw Blame History

Chongming-Zenoh

基于 FastAPI + Zenoh + MQTT + Vue 3 的配置驱动微服务网关平台。

通过 TOML 配置文件定义 RPC 端点，自动生成 Pydantic 模型与 FastAPI 路由，同时暴露 HTTP 和 MQTT 双通道。底层基于 Zenoh 分布式消息协议实现 RPC 通信，Worker 插件可独立开发、按副本数水平扩展。

核心特性

特性	说明
FastAPI + Uvicorn	高性能异步 Web 框架，自动生成 OpenAPI 文档
Zenoh 服务发现	基于 liveliness 的 Worker 注册与 RPC 调用，负载均衡 + 超时重试
MQTT 集成	amqtt Broker（内嵌或外部），MQTT ↔ Worker 双向桥接
动态路由生成	扫描 `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` 控制
Argon2id 密码哈希	Rust 实现的高性能密码安全方案
异步 SQLite	aiosqlite + SQLModel，多进程并发安全
本地文件存储	内置文件上传/下载端点
流媒体代理	ffmpeg + MediaMTX RTSP 流转发
构建打包	PyInstaller / Nuitka 一键打包为独立可执行文件
Vue 3 前端	Element Plus UI、Pinia 状态管理、类型安全的 API 客户端

项目结构

chongming-zenoh/
├── config.toml                   # 应用主配置
├── pyproject.toml                # 项目依赖与脚本入口
├── config/                       # 配置文件目录
│   ├── zenoh_config.json5        # Zenoh 会话配置
│   └── workers/                  # Worker 路由定义（TOML）
│       ├── config.toml           # 旧式全局插件注册（仅作兜底兼容）
│       ├── auth/                 # 鉴权插件（config.toml = 插件注册 + 运行时配置）
│       ├── doubao/               # 豆包视觉理解插件
│       ├── aibox_sophon_adapter/ # AI Box 设备心跳监控插件
│       └── example/              # 示例插件（四则运算 / MQTT 端点）
├── src/
│   ├── chongming/                # 核心应用
│   │   ├── app/
│   │   │   ├── core/             # WorkerManager, RouteGenerator, MQTTBridge, contracts(契约校验), auth
│   │   │   └── routes/           # 内置路由（文件上传等）
│   ├── chongming-web/            # Vue 3 前端
│   │   └── src/
│   │       ├── api/generated/    # 自动生成 API 客户端
│   │       ├── views/            # 页面组件
│   │       └── router/           # Vue Router 配置
│   └── plugins/                  # Worker 插件源码（inline 模式）
│       ├── auth/                 # JWT 鉴权
│       ├── doubao/               # 豆包 AI（支持 AICC 安全通道）
│       ├── aibox_sophon_adapter/ # 设备心跳 + 告警
│       └── example/              # 演示示例
├── workers/                      # 进程插件（external 模式，本地开发目录，不入库；
│   └── demo/                     #   生产在独立容器部署，示例见本地目录）
├── utils/                        # 独立工具包
│   ├── bytedance/   # 字节跳动安全通信 SDK
│   ├── cli/         # 命令脚本集合（build / gen_models / gen_plugin，chongming-cli）
│   ├── config/      # TOML 配置加载
│   ├── database/    # 异步 SQLite 封装
│   ├── jwt/         # Rust JWT 编解码
│   ├── password/    # Rust Argon2id 哈希
│   ├── request/     # Zenoh RPC 客户端
│   ├── stream_manager/  # ffmpeg RTSP 流管理
│   └── worker/      # Worker 框架核心
├── data/
│   ├── storage/chongming/        # SQLite 数据库文件
│   └── uploads/                  # 文件上传目录
├── logs/                         # 日志目录
├── resources/                    # 模块银行打包资源
├── test_mqtt_e2e.py              # MQTT 端到端测试
├── publisher.py / subscriber.py  # MQTT 收发示例
└── README.md

多仓库结构与开发工作流

本仓库（chongming-core）只跟踪网关核心代码，其余资产分布在独立仓库中：

目录 / 包	独立仓库	说明
`src/chongming/`	本仓库（chongming-core）	网关核心（FastAPI + Zenoh）
`utils/<name>/`	`chongming-utils-*`（9 个，见「工具包列表」）	工具包，由 `uv sync` 按 git 源安装
`utils/cli/`	`chongming-utils-cli`（规划中，暂以 path 源安装）	命令脚本集合（build / build_plugin / gen_models / gen_plugin）
`src/plugins/`	`chongming-plugins`	Worker 插件源码
`config/`	`chongming-config`	应用与 Worker 路由配置
`src/chongming-web/`	`chongming-web`	Vue 3 前端

首次克隆（开发环境引导）

git clone http://124.71.68.6:3000/chongming/chongming-core.git chongming-zenoh
cd chongming-zenoh
git clone http://124.71.68.6:3000/chongming/chongming-plugins.git src/plugins
git clone http://124.71.68.6:3000/chongming/chongming-config.git config
git clone http://124.71.68.6:3000/chongming/chongming-web.git src/chongming-web
uv sync     # utils/* 由 uv 按 pyproject 的 git 源自动安装，无需手工 clone

开发与发布检查清单

修改 utils/<name>（工具包）：

在 utils/<name> 内提交并 push 到对应远程
回主仓库执行 uv lock --upgrade-package <包名> 刷新版本 pin
uv sync 后运行相关测试
主仓库提交 uv.lock

修改 src/plugins/ / config/ / src/chongming-web/：

在对应子仓库内提交并 push
回主仓库启动验证（uv run serve + 相关测试）

发布前总检查：

所有子仓库 git status 干净且已 push
uv.lock 与各 git 源最新提交一致
配置中无硬编码凭据——密钥一律走环境变量： VOLC_ACCESSKEY（豆包 Ark Key）、AIBOX_MQTT_URI（AI Box 外部 Broker URI）
uv run python test_mqtt_e2e.py 等测试通过

快速开始

环境要求

Python >= 3.12
Rust 工具链（用于编译 jwt / password 扩展）
Node.js >= 22（前端开发）
uv 包管理器
ffmpeg（可选，stream_manager 需要）

安装与启动

首次克隆：先按「多仓库结构与开发工作流」拉取 src/plugins / config / src/chongming-web 子仓库，再执行以下步骤。

# 同步依赖（自动编译 Rust 扩展 + 安装 Python 包）
uv sync

# 启动服务（开发模式，热重载）
uv run serve

服务启动后：

通道	地址	说明
HTTP	`http://localhost:8000`	REST API
Swagger	`http://localhost:8000/docs`	OpenAPI 交互文档
MQTT	`mqtt://localhost:1883`	内嵌 Broker

前端开发

cd src/chongming-web
npm install
npm run dev          # http://localhost:5173

架构与数据流

graph TB
    HTTP[HTTP 客户端] -->|REST API| API[FastAPI 动态路由]
    MQTT[MQTT 客户端] -->|chongming/+/+| BRIDGE[MQTT Bridge<br/>纯客户端模式]

    REG[RouteRegistry<br/>订阅 chongming/routes/**] -->|动态挂载/摘除 HTTP 路由| API
    API --> WM[WorkerManager<br/>随机负载均衡 + 超时重试]
    BRIDGE --> WM

    subgraph GW[网关进程 chongming]
        API
        REG
        BRIDGE
        WM
    end

    WM -->|Zenoh Query| IW[inline Worker 副本<br/>网关进程内加载]
    WM -->|Zenoh Query| EW[external Worker 进程<br/>独立容器，零网关依赖]
    EW -.->|发布路由描述符<br/>chongming/routes/**| REG

    IW --> DB[(SQLite)]
    EW --> DB
    EW -->|AI 调用| AI[豆包 API]

启动流程：

uv run serve → FastAPI lifespan:
  1. setup_storage()           — 本地文件系统存储
  2. setup_zenoh()             — Zenoh peer 会话
  3. setup_mqtt_broker()       — 内嵌 amqtt Broker（子进程 + 文件锁单例；
                                  `use_embedded_broker=false` 时跳过，改用外部 Broker）
  4. setup_worker_manager()    — WorkerManager + 定期 liveliness 刷新
  5. load_workers()            — 按插件 [workers].load_mode 分派:
       inline   → 进程内 import 插件 → 启动 Worker 协程
       external → 跳过（独立进程运行，盘扫条目仅观测）
  5.1 setup_route_registry()   — 常驻订阅 chongming/routes/**，external 插件路由动态挂载/摘除
  6. validate_contracts()      — inline 插件三方契约校验，失败终止启动
  7. register_routes()         — inline 插件盘扫生成 HTTP 路由
  8. setup_mqtt()              — MQTT Bridge（inline 主题静态收集 + external 主题动态推送）

端点类型与路由注册

端点类型

TOML 文件中的节类型决定端点暴露方式：

节类型	HTTP 路由	OpenAPI 文档	MQTT	请求模型命名
`[GET]`	✅	✅	✅	`XxxGetRequest / XxxGetResponse`
`[POST]`	✅	✅	✅	`XxxPostRequest / XxxPostResponse`
`[MQTT]`	❌	❌	✅	`XxxMqttRequest`（无 response_model）

两种路由注册方式

方式一：TOML 动态路由（标准 JSON 端点）

通过 config/workers/<插件>/*.toml 定义端点，自动生成 FastAPI 路由。适用于参数和响应可被 Pydantic 模型描述的标准接口。

# config/workers/example/add.toml
[GET]
summary = "加法运算"
params = ["a: float", "b: float"]

[GET.response_model]
result = { type = "float", required = true }

方式二：插件自定义路由（特殊端点）

当端点无法用 TOML 描述时（如 multipart/form-data 上传），插件暴露 APIRouter 实例，网关自动发现并注册。

# src/plugins/<name>/routes.py
from fastapi import APIRouter, UploadFile, File

router = APIRouter(prefix="/<prefix>", tags=["<worker_type>"])

@router.post("/upload")
async def upload(file: UploadFile = File(...)):
    ...

约定：插件 __init__.py 中导入 router 实例（from .routes import router），网关通过 getattr(module, "router", None) 自动发现。

流式端点（SSE）

基于 Zenoh Query/Reply 原生"多回复"实现流式输出：Worker 的 @rpc_method 返回生成器时，框架逐块 query.reply() 推送（见 utils/worker README「流式端点」），网关以 SSE （text/event-stream）逐块转发给 HTTP 客户端。无额外端口、无额外进程、无新依赖；未声明 stream 的端点行为与之前完全一致。

TOML 配置

在方法节中声明 stream = true（示例 config/workers/example/stream_chat.toml）：

[POST]
summary = "模拟 AI 流式对话（SSE，逐 token 输出）"
auth_required = false
stream = true
timeout = 300.0             # 流总寿命上限（秒，zenoh query deadline 硬上限）
stream_idle_timeout = 10.0  # 网关侧连续无数据块的最大间隔（秒）
params = ["prompt: str", "tokens: int"]

字段	默认值	说明
`stream`	`false`	流式端点：以 SSE（`text/event-stream`）输出
`timeout`	`3.0`	流总寿命上限（秒）。流式端点必须配大（如 300s），到期后 zenoh 丢弃后续回复
`stream_idle_timeout`	`10.0`	空闲超时（秒）：超过该间隔无新数据块则网关终止流

timeout（总寿命硬上限）与 stream_idle_timeout（空闲超时）是两回事，流式场景两个都要配。

请求与响应

请求与普通端点一致（GET 走 query/path 参数，POST/PUT/PATCH 走 body 模型），鉴权依赖同样生效
响应为 text/event-stream，每块一个 data: {json}\n\n 事件（SSE 标准分帧）
响应头：Cache-Control: no-cache、X-Accel-Buffering: no（配合反代关闭缓冲）
OpenAPI 不声明流式端点的响应 schema（逐块 JSON dict，无法用单一模型描述）

curl -N -X POST localhost:8000/api/v1/calc/stream_chat \
  -H 'Content-Type: application/json' -d '{"prompt":"你好","tokens":3}'
# data: {"token":"你好·1","index":0}
# data: {"token":"你好·2","index":1}
# data: {"token":"你好·3","index":2}
# data: {"done":true}

错误语义

场景	表现
无可用 worker（首个数据块前）	HTTP 503（与普通端点一致）
Worker 中途异常 / 流式端点初始化失败	SSE error 事件 `data: {"error":"..."}` 收尾（HTTP 200 已提交，无法再改状态码）
空闲超时	SSE error 事件 `data: {"error":"流式空闲超时 ..."}` 收尾
客户端断开	网关终止迭代，Worker 侧 reply 失败自动停流，不空转

部署注意

生产环境经 nginx 反代时需关闭缓冲，否则 SSE 会被整段缓冲、失去逐块即时性：

location /api/v1/ {
    proxy_buffering off;
}

本地联调前注意

流式能力在 chongming-worker 框架（utils/worker/，独立仓库）。本地未 push 的框架改动不会自动生效——venv 里安装的是 uv sync 从 git 源拉取的旧版副本，旧版 @rpc_method 不认 stream 参数，会报 TypeError: rpc_method() got an unexpected keyword argument 'stream' 并连锁导致契约校验失败（启动终止）。本地联调时先以可编辑方式装入 venv：

uv pip install -e utils/worker

正式发布仍走「开发与发布检查清单」流程（工具包 push → uv lock --upgrade-package chongming-worker → uv sync，可编辑安装会被锁文件版本替换）。

测试

uv run python test_stream_worker.py      # Worker 框架流式回复单测
uv run python test_stream_gateway.py     # 网关 call_stream 单测
uv run python test_stream_e2e_zenoh.py   # 真实 Zenoh 会话端到端（peer 模式，无需 router）
uv run python test_stream_route.py       # 路由层 SSE 输出与兼容性回归（非流式端点不变）

进程插件与混合部署

两种插件运行模式按插件粒度共存，在 config/workers/<name>/config.toml 的 [workers] 节声明：

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/<type>/...，退出时 delete；每 10s 周期重发布自愈
- 服务发现：liveliness worker/<type>/<id>（与 inline 副本同一机制，网关无需改动）
worker 进程自读 TOML 并在自己进程内做契约校验（chongming_worker.contracts）；网关 RouteRegistry 常驻订阅描述符后动态挂载/摘除 HTTP 路由（type 级 2s 防抖）。路由注册与网关侧插件盘扫（config/workers/*/config.toml）解耦：网关容器无需放置 external 插件的配置文件，盘扫发现的 external 条目仅用于启动日志观测； inline 插件仍按盘扫在网关进程内加载，不受影响
代码结构与 inline 插件完全一致（Plugin 基类 + router/ + models/），示例见本地 workers/demo/

运行：

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 语句）

进程插件打包

将 external 进程插件一键打包为可部署 zip（插件代码 + 配置 + 依赖清单 + 容器入口）：

uv run build_plugin demo              # → dist/demo.zip
uv run build_plugin demo --output /tmp/pkg

产物布局（zip 根即容器工作目录）：

workers/<name>/                插件代码（模块 workers.<name>）
config/workers/<name>/         插件注册 + 端点配置
config/zenoh_config.json5      Zenoh 会话配置
config.toml                    最小根配置（自动生成，仅 [zenoh] 节，不泄露网关配置）
pyproject.toml                 uv 依赖清单（chongming-worker 内网 git 源）
start.sh                       容器入口：uv sync + worker_serve --type <name>

插件扩展依赖（可选）：在 workers/<name>/requirements.txt 中逐行声明，打包时自动合并进 pyproject.toml 的 dependencies
容器内部署：unzip <name>.zip -d /app && cd /app && ./start.sh（镜像需预装 uv）
打包前校验：workers/<name>/ 与 config/workers/<name>/config.toml 必须存在，load_mode 非 external 时告警
config/workers/<name>/ 仅部署在插件容器（worker 自读）；网关侧无需放置（RouteRegistry 常驻订阅 Zenoh 路由描述符，与盘扫解耦）

MQTT 协议

Topic 约定

方向	Topic	说明
请求	`chongming/<type>/<op>`	MQTT → Worker
响应	`chongming/<type>/<op>/response`	Worker → MQTT（`None` 时跳过）

Broker 来源（内嵌 vs 外部）

网关默认启动内嵌 amqtt Broker（子进程 + 文件锁单例），[<env>.mqtt].use_embedded_broker 控制 Broker 来源：

[development.mqtt]
enabled = true
host = "0.0.0.0"          # true 时为内嵌 Broker 监听地址；false 时为外部 Broker 地址
port = 1883
use_embedded_broker = true   # true（默认）网关启动 amqtt Broker；false 连接外部 Broker

use_embedded_broker = true（默认）：网关启动内嵌 amqtt Broker 子进程，MQTT Bridge 作为客户端连回自身。
use_embedded_broker = false：网关不启动 Broker，MQTT Bridge 直接连接 host:port 指向的外部 MQTT Broker（如独立部署的 EMQX/Mosquitto）。host 需改为外部 Broker 地址，enabled = false 时整个 MQTT 通道关闭。

Broker 认证（用户名/密码）

[<env>.mqtt].username / password 配置 Broker 认证（可选，默认匿名）：

[development.mqtt]
enabled = true
host = "0.0.0.0"
port = 1883
username = "chongming"   # 可选；内嵌/外部 Broker 均生效
password = "change-me"

内嵌 Broker（use_embedded_broker=true）：配置后启用认证（amqtt FileAuthPlugin + argon2 哈希），所有客户端（含网关 Bridge）必须携带该账号密码连接；未配置则保持匿名。
外部 Broker：网关 Bridge 以该账号密码连接，broker 侧需自行创建对应账号。
客户端连接示例：mqtt://chongming:change-me@localhost:1883/（密码含特殊字符时需百分号编码，如 @ → %40；网关 Bridge 内部自动处理）。
注意：密码明文存放于配置，生产环境建议使用外部 Broker + 环境变量注入。

自定义订阅主题

除内置的 chongming/<type>/<op> 接口外，可将外部 MQTT 主题桥接到任意 Worker。推荐在插件自己的配置 config/workers/<type>/config.toml 中通过 [[workers.mqtt_topics]] 声明（目标 worker 即该插件本身）：

# config/workers/aibox_sophon_adapter/config.toml
[[workers.mqtt_topics]]
topic = "box/aibox_sophon/board_ping"         # 支持 +（单级）/ #（多级，须在末尾）通配符
subject = "aibox_sophon_adapter.board_ping" # 可选，{1} {2}... 对应通配符捕获值
response_topic = "/board_ping/response"     # 可选，响应主题；默认 "<实际主题>/response"

subject 缺省为 <插件类型>.<topic 最后一段>；response_topic 缺省为 <实际匹配主题>/response。
网关发现插件时自动收集所有 [[workers.mqtt_topics]]，MQTT Bridge 一并订阅并路由。
多条自定义主题按配置顺序匹配，先匹配者优先；内置 chongming/... 接口最后兜底。
全局 [<env>.mqtt].custom_topics 仍可作为通用兜底（不依赖具体插件时使用，可选）。

请求负载格式（信封协议）

MQTT 请求负载为信封结构，控制字段与业务数据分离：

{
  "meta": {
    "method": "GET",      // 可选，默认 GET；MQTT 专用端点需显式 "MQTT"
    "timeout": 30,        // 可选，RPC 超时（秒），默认 30
    "cacheable": false    // 可选，是否允许结果缓存，默认 false
  },
  "data": { "a": 3, "b": 5 }   // 业务参数，传给 Worker
}

非信封格式的负载会被网关丢弃并告警（严格协议，设备侧请按此格式发布）。
HTTP 通道由网关自动组装信封（注入 method / user_info），无需调用方关心。

快速测试

# 终端 1：启动服务
uv run serve

# 终端 2：端到端测试
python test_mqtt_e2e.py

# 手动测试
python subscriber.py                             # 监听所有响应
python publisher.py example add '{"a":3,"b":5}'  # 调用 add

开发指南

添加新 Worker 插件

1. 创建 src/plugins/<name>/ — __init__.py（Plugin 子类）, global_var.py, router/, models/
2. 创建 config/workers/<name>/config.toml，在 [workers] 节注册插件
   （type / module / factory / cleanup / count + [workers.config] 运行时配置）
3. 创建 config/workers/<name>/*.toml 端点定义
4. 运行 uv run gen_models 生成模型
5. 实现 router/<op>.py，引用 models/pydantic.py 中的模型
6. 更新 router/__init__.py 导入

推荐用脚手架一步生成骨架：uv run gen_plugin <name> [operation ...]。启动时网关会做契约校验：TOML 路由缺少对应 @rpc_method 将导致启动失败，模型缺失/孤儿等不一致以警告日志提示。

为现有插件添加新端点

1. 创建 config/workers/<name>/<op>.toml
2. 运行 uv run gen_models
3. 创建 router/<op>.py → 引用生成的模型
4. 更新 router/__init__.py
5. 重启服务

流式端点（SSE）在此基础上额外两步：TOML 方法节声明 stream = true 并配大 timeout； @rpc_method(..., stream=True) 函数返回生成器（yield 逐块），详见上文「流式端点（SSE）」。

常用命令

uv run serve                                    # 启动开发服务
uv run gen_plugin <name>                        # 生成统一风格插件骨架
uv run gen_models   # 生成 Pydantic 模型
uv run build        # 构建打包（PyInstaller/Nuitka）
uv run worker_serve --type <name>               # 独立 Worker 进程（本地调试，load_mode=external）
chongming-worker --type <name>                  # 独立 Worker 进程（容器入口）
uv pip install -e utils/<name>                  # 安装/更新工具包

插件列表

插件	路径	功能
auth	`src/plugins/auth/`	用户注册/登录/资料管理，JWT 鉴权，管理员初始化
doubao	`src/plugins/doubao/`	豆包视觉理解，支持 AICC 安全通信通道
aibox_sophon_adapter	`src/plugins/aibox_sophon_adapter/`	AI Box 设备心跳监控、离线检测、告警上报与查询、视频上传
example	`src/plugins/example/`	四则运算 + 心跳演示（含 MQTT 端点示例）
demo（进程插件示例）	`workers/demo/`（本地目录，不入库）	独立进程运行（load_mode=external），经 Zenoh 注册路由

工具包列表

包名	路径	语言	说明
chongming-config	`utils/config/`	Python	TOML 配置加载，TypedDict 类型安全
chongming-database	`utils/database/`	Python	aiosqlite + SQLModel 异步数据库封装
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`）
chongming-stream-manager	`utils/stream_manager/`	Python	ffmpeg + MediaMTX RTSP 流代理管理
bytedance	`utils/bytedance/`	Python	字节跳动 AICC 安全通信 SDK（Jeddak 等）

配置说明

应用配置：根目录 config.toml，包含环境、服务器、安全、MQTT 等全局设置
插件加载模式：按插件粒度声明在 config/workers/<name>/config.toml 的 [workers] 节
- load_mode = "inline"（默认）：插件在网关进程内加载
- load_mode = "external"：插件以独立进程运行（进程编排交给 Docker/K8s，进程入口 uv run worker_serve --type <name>），经 Zenoh 在 chongming/routes/** 注册路由，网关动态挂载 HTTP 端点（RouteRegistry 常驻订阅，无需在网关侧保留插件配置）
- 两种模式可同时存在（混合部署）
进程插件与网关完全隔离：进程插件只依赖 chongming-worker SDK + zenoh，与网关（chongming 包）零导入关系，仅通过 Zenoh（chongming/routes/** 注册路由、 worker/<type>/<id> 服务发现）通讯。workers/ 目录仅为开发便利， 生产部署时进程插件与网关分别打包到不同容器：
- 网关容器：chongming（含 src/chongming/）+ 依赖
- 进程插件容器：插件代码（workers/<name>/）+ chongming-worker + 依赖，入口 chongming-worker --type <name>（或 uv run worker_serve --type <name>），打包: uv run build_plugin <name> → dist/<name>.zip（见「进程插件打包」）
Zenoh 配置：config/zenoh_config.json5
插件注册：config/workers/<name>/config.toml 的 [workers] 节，定义加载方式、副本数与运行时配置（旧全局 config/workers/config.toml 仅作兜底兼容）
路由定义：config/workers/<name>/*.toml，每个端点一个文件

详细配置说明见 config/README.md。

构建部署

# PyInstaller 打包
uv run build pyinstaller

# Nuitka 打包
uv run build nuitka

# 仅重新打包 .mbank 模块文件（第三方依赖不变时，更新只需替换 mbank 文件）
uv run build --only mbank

# 只执行指定步骤，跳过其余流程
uv run build --only mbank,prepare,vue

构建过程包括：模块加密打包 → 资源复制 → PyInstaller/Nuitka 打包 → 数据库初始化 → 前端编译 → VFS 挂载。

--only <step> 可选步骤：mbank（模块打包）、prepare（准备构建目录）、 obfuscate（PyArmor 混淆，仅 pyinstaller 模式）、pack（PyInstaller/Nuitka 打包）、 clean（清理临时文件）、vue（Vue 前端构建）；可逗号分隔或重复传多个。

详见插件开发指南。

常用命令

uv run serve                              # 启动开发服务器
uv run gen_plugin <name>                  # 生成统一风格插件骨架
uv run gen_models  # 生成 Pydantic 模型
uv run build pyinstaller                  # PyInstaller 打包
uv run build nuitka                       # Nuitka 打包
uv run build_plugin <name>                # 进程插件打包 → dist/<name>.zip
chongming-worker --type <name>            # 独立 Worker 进程（进程插件容器入口）
uv pip install -e utils/<name>            # 安装/更新工具包子包

TOML 配置字段速查

字段	位置	说明
`count`	`<插件>/config.toml`	Worker 副本数（`[workers]` 节）
`router_prefix`	`<插件>/config.toml`	API 路由前缀
`defaults.timeout`	`<插件>/config.toml`	默认超时（秒）
`defaults.cacheable`	`<插件>/config.toml`	是否缓存 RPC 结果
`params`	`<操作>.toml`	参数列表（`"name: type"` 格式）
`auth_required`	`<操作>.toml`	是否需要 JWT 鉴权
`internal`	`<操作>.toml`	`true` 则仅限内部 RPC，不注册 HTTP 路由
`cacheable`	`<操作>.toml`	端点是否可缓存
`summary`	`<操作>.toml`	端点描述（用于 OpenAPI / 日志）
`stream`	`<操作>.toml`	`true` 则流式输出（SSE），需同时配大 `timeout`
`stream_idle_timeout`	`<操作>.toml`	流式空闲超时（秒，默认 10），超时无新数据块则终止流

内置插件

插件	HTTP 前缀	MQTT 主题前缀	说明
auth	`/auth`	`auth.*`	注册、登录、JWT 鉴权、个人信息、改密
doubao	`/doubao`	`doubao.*`	火山引擎豆包视觉理解模型
example	`/calc`	`example.*`	四则运算 + 访问计数 + MQTT 心跳示例
aibox_sophon_adapter	`/aibox`	`aibox_sophon_adapter.*`	AI Box 设备心跳适配 + 视频上传

32 KiB Raw Blame History Unescape Escape

Chongming-Zenoh

核心特性

项目结构

多仓库结构与开发工作流

首次克隆（开发环境引导）

开发与发布检查清单

快速开始

环境要求

安装与启动

前端开发

架构与数据流

端点类型与路由注册

端点类型

两种路由注册方式

方式一：TOML 动态路由（标准 JSON 端点）

方式二：插件自定义路由（特殊端点）

流式端点（SSE）

TOML 配置

请求与响应

错误语义

部署注意

本地联调前注意

测试

进程插件与混合部署

进程插件打包

MQTT 协议

Topic 约定

Broker 来源（内嵌 vs 外部）

Broker 认证（用户名/密码）

自定义订阅主题

请求负载格式（信封协议）

快速测试

开发指南

添加新 Worker 插件

为现有插件添加新端点

常用命令

插件列表

工具包列表

配置说明

构建部署

常用命令

TOML 配置字段速查

内置插件

更多文档

32 KiB

Raw Blame History