109 lines
5.2 KiB
Markdown
109 lines
5.2 KiB
Markdown
|
# {{app_name}}
|
|||
|
|
|
|||
|
|
基于 **chongming 网关**的宿主项目（由 chongming 项目模板初始化）：
|
|||
|
|
|
|||
|
|
- **网关本体**：`chongming-gateway` 包（FastAPI + Zenoh），从私有源按版本依赖，不在本仓库
|
|||
|
|
- **本仓库负责**：宿主骨架（`public/`，可执行文件入口）、内置插件（`src/plugins/`）、
|
|||
|
|
配置（`config/`）、构建与交付产物
|
|||
|
|
|
|||
|
|
## 快速开始
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
uv sync # 同步依赖（网关与 chongming-* 工具包从私有源安装）
|
|||
|
|
uv run serve # 启动服务（开发模式，热重载）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
| 通道 | 地址 | 说明 |
|
|||
|
|
| ---- | ---- | ---- |
|
|||
|
|
| HTTP | `http://localhost:8000` | REST API（`config.toml` 的 `prefix` 为 `/api/v1`） |
|
|||
|
|
| Swagger | `http://localhost:8000/docs` | OpenAPI 交互文档（调试模式开启） |
|
|||
|
|
| MQTT | `mqtt://localhost:1883` | 内嵌 Broker（`use_embedded_broker = true`） |
|
|||
|
|
|
|||
|
|
开箱示例（内置插件 `example`）：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
curl 'http://localhost:8000/api/v1/example/hello?name=world'
|
|||
|
|
# {"message":"hello, world!","count":1}
|
|||
|
|
|
|||
|
|
curl -X POST http://localhost:8000/api/v1/example/hello \
|
|||
|
|
-H 'Content-Type: application/json' -d '{"name":"world"}'
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 目录结构
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
├── config.toml # 应用主配置（环境、服务器、缓存、MQTT、打包清单）
|
|||
|
|
├── pyproject.toml # 宿主依赖（chongming-gateway 等）
|
|||
|
|
├── plugins_deps.toml # 内置插件专属依赖（打包收集用）
|
|||
|
|
├── public/ # 可执行文件打包骨架：main.py / server.py / utils / 运行时 config.toml
|
|||
|
|
├── config/ # 项目配置
|
|||
|
|
│ ├── zenoh_config.json5 # Zenoh 会话配置
|
|||
|
|
│ └── workers/<type>/ # 插件注册（config.toml）与端点定义（<op>.toml）
|
|||
|
|
├── src/plugins/ # 内置插件源码（inline，网关进程内加载）
|
|||
|
|
│ └── example/ # 最小示例：Plugin 生命周期 + @rpc_method + 模型
|
|||
|
|
├── workers/ # 进程插件本地开发目录（external，不入库；生产独立容器）
|
|||
|
|
└── resources/ # 构建产物（plugins.mbank 等）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 新增插件 / 端点
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
uv run gen_plugin <name> [operation ...] # 一键生成内置插件骨架（含 config/ 注册与端点 TOML）
|
|||
|
|
uv run gen_models config/workers/<name> src/plugins/<name> # 改 TOML 后重新生成模型
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
手写流程（参考 `src/plugins/example/` 的四个文件）：
|
|||
|
|
|
|||
|
|
1. `config/workers/<name>/config.toml`：`[workers]` 注册（`type` / `module = "plugins.<name>"` /
|
|||
|
|
`factory` / `cleanup` / `count` / `load_mode`）+ `[worker]` 路由前缀与端点默认值
|
|||
|
|
2. `config/workers/<name>/<op>.toml`：端点定义（`[GET]` / `[POST]` / `[MQTT]` 分节 + `params` + `response_model`）
|
|||
|
|
3. `uv run gen_models ...` 生成 `models/pydantic.py`
|
|||
|
|
4. `router/<op>.py`：`@rpc_method(subject="<name>.<op>", method=...)` 实现；
|
|||
|
|
在 `router/__init__.py` 导入
|
|||
|
|
|
|||
|
|
启动时网关会做**契约校验**：TOML 里的 HTTP 路由缺少对应 `@rpc_method` 会直接启动失败。
|
|||
|
|
|
|||
|
|
进程插件（`load_mode = "external"`，独立进程/容器部署）：
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
uv run gen_plugin <name> --process # 生成自包含插件项目 workers/<name>/
|
|||
|
|
cd workers/<name> && uv run chongming-worker --type <name> # 本地调试
|
|||
|
|
uv run build_plugin <name> # 打包 → dist/<name>.zip（容器入口 start.sh）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 配置
|
|||
|
|
|
|||
|
|
- **应用配置**：根 `config.toml`（开发读 `[development]`；`[default].env` 切换环境）
|
|||
|
|
- **插件注册与端点**：`config/workers/<type>/config.toml`、`config/workers/<type>/<op>.toml`
|
|||
|
|
- **Zenoh**：`config/zenoh_config.json5`
|
|||
|
|
|
|||
|
|
常用开关：
|
|||
|
|
|
|||
|
|
| 配置 | 位置 | 说明 |
|
|||
|
|
| ---- | ---- | ---- |
|
|||
|
|
| `cache.backend` | 根 `config.toml` | `sqlite`（单机默认）/ `redis`（多实例共享） |
|
|||
|
|
| `mqtt.use_embedded_broker` | 根 `config.toml` | `true` 自带 Broker；`false` 连外部 Broker |
|
|||
|
|
| `workers.count` | 插件 `config.toml` | 副本数（多网关共享 cache 时按在线网关分摊） |
|
|||
|
|
| `workers.load_mode` | 插件 `config.toml` | `inline`（默认）/ `external` |
|
|||
|
|
|
|||
|
|
## 打包与部署
|
|||
|
|
|
|||
|
|
```bash
|
|||
|
|
uv run build pyinstaller # 打包可执行文件 → build/chongming
|
|||
|
|
uv run build nuitka # Nuitka 打包（Linux 需宿主 patchelf）
|
|||
|
|
uv run build --encrypt --license # 对外分发：加密插件模块 + 注入授权公钥
|
|||
|
|
uv run build --only mbank # 只重新生成 plugins.mbank（插件热更新只需替换该文件）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
- 无前端时跳过 vue 步骤：`uv run build pyinstaller --only mbank,prepare,pack`
|
|||
|
|
- 插件代码在 `plugins.mbank` 里 → 换文件即可热更新；**网关本体是普通依赖** →
|
|||
|
|
升级网关需改 `pyproject.toml` 版本（或 `uv lock --upgrade-package chongming-gateway`）
|
|||
|
|
并重新 `uv run build`
|
|||
|
|
- 新增插件用了新第三方包时：`pyproject.toml` 追加依赖 + `plugins_deps.toml` 声明
|
|||
|
|
（否则打包产物运行到加载插件时才报 ImportError）
|
|||
|
|
|
|||
|
|
## 进一步文档
|
|||
|
|
|
|||
|
|
网关主体、插件开发、进程插件、Worker 运维等完整文档在 chongming-core（chongming-zenoh）仓库的
|
|||
|
|
`README.md` 与 `docs/`；本仓库的管理端点、实例定向、MQTT 协议等用法与之一致。
|