modify:进程插件开发环境目录结构变更
This commit is contained in:
@@ -366,7 +366,7 @@ load_mode = "external" # 独立进程运行，经 Zenoh 注册路由
|
||||
|
||||
- 网关进程内 import；路由由网关盘扫 TOML 生成；契约校验在网关启动时执行
|
||||
|
||||
**external 进程插件**（本地开发目录 `workers/`，不入库）：
|
||||
**external 进程插件**（本地开发目录 `workers/`，自包含项目，不入库）：
|
||||
|
||||
- 与网关**零导入关系**：只依赖 `chongming-worker` SDK + zenoh，仅经 Zenoh 通讯
|
||||
- 路由注册：worker 启动时 put 描述符到 `chongming/routes/<type>/...`，退出时 delete；每 10s 周期重发布自愈
|
||||
@@ -376,12 +376,15 @@ load_mode = "external" # 独立进程运行，经 Zenoh 注册路由
|
||||
路由注册与网关侧插件盘扫（`config/workers/*/config.toml`）解耦：**网关容器无需
|
||||
放置 external 插件的配置文件**，盘扫发现的 external 条目仅用于启动日志观测；
|
||||
inline 插件仍按盘扫在网关进程内加载，不受影响
|
||||
- 代码结构与 inline 插件完全一致（Plugin 基类 + router/ + models/），示例见本地 `workers/demo/`
|
||||
- 运行：
|
||||
- 每个插件是**自包含项目**（`workers/<name>/` = 打包 zip 根 = 容器工作目录，
|
||||
开发即产物），代码结构与 inline 插件完全一致（Plugin 基类 + router/ + models/），
|
||||
示例见本地 `workers/demo/`；新项目用 `uv run gen_plugin <name> --process` 生成骨架
|
||||
- 运行（在插件项目根 `workers/<name>/` 下）：
|
||||
|
||||
```bash
|
||||
uv run worker_serve --type demo # 本地调试
|
||||
chongming-worker --type demo # 容器入口（chongming-worker SDK console script）
|
||||
cd workers/demo
|
||||
uv run worker_serve --type demo # 本地调试（首次先 uv sync 装依赖）
|
||||
./start.sh # 与容器一致的启动方式（uv sync + 启动）
|
||||
```
|
||||
|
||||
- 生产部署：进程插件与网关**分别打包到不同容器**
|
||||
@@ -391,28 +394,32 @@ load_mode = "external" # 独立进程运行，经 Zenoh 注册路由
|
||||
|
||||
### 进程插件打包
|
||||
|
||||
将 external 进程插件一键打包为可部署 zip（插件代码 + 配置 + 依赖清单 + 容器入口）：
|
||||
`build_plugin` 把插件项目根直接压缩为可部署 zip（开发目录即产物，
|
||||
插件代码 + 配置 + 依赖清单 + 容器入口都在 `workers/<name>/` 内）：
|
||||
|
||||
```bash
|
||||
uv run build_plugin demo # → dist/demo.zip
|
||||
uv run build_plugin demo --output /tmp/pkg
|
||||
```
|
||||
|
||||
产物布局（zip 根即容器工作目录）：
|
||||
产物布局（= 项目根，zip 根即容器工作目录）：
|
||||
|
||||
```text
|
||||
workers/<name>/ 插件代码（模块 workers.<name>）
|
||||
config/workers/<name>/ 插件注册 + 端点配置
|
||||
config/zenoh_config.json5 Zenoh 会话配置
|
||||
config.toml 最小根配置（自动生成，仅 [zenoh] 节，不泄露网关配置）
|
||||
config.toml 最小根配置（仅 [zenoh] 节，worker 启动必需）
|
||||
pyproject.toml uv 依赖清单（chongming-worker 内网 git 源）
|
||||
start.sh 容器入口：uv sync + worker_serve --type <name>
|
||||
```
|
||||
|
||||
- 插件扩展依赖（可选）：在 `workers/<name>/requirements.txt` 中逐行声明，打包时自动合并进 `pyproject.toml` 的 dependencies
|
||||
- 打包自动排除 `__pycache__` / `*.pyc` / `.venv` 等，`start.sh` 权限强制 0o755
|
||||
- 插件扩展依赖（可选）：直接在项目根 `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 路由描述符，与盘扫解耦）
|
||||
- 打包前校验：`workers/<name>/` 项目根、项目内 `config/workers/<name>/config.toml`
|
||||
（含 `[workers]` 节）、`config/zenoh_config.json5` 与根 `config.toml`（含 `[zenoh]`）必须存在，
|
||||
`load_mode` 非 `external` 时告警
|
||||
- 插件配置随 zip 部署在**插件容器**（worker 自读）；网关侧无需放置（RouteRegistry 常驻订阅 Zenoh 路由描述符，与盘扫解耦）
|
||||
|
||||
---
|
||||
|
||||
@@ -562,7 +569,7 @@ uv pip install -e utils/<name> # 安装/更新工具包
|
||||
| **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 注册路由 |
|
||||
| **demo**（进程插件示例） | `workers/demo/`（本地自包含项目，不入库） | 独立进程运行（load_mode=external），经 Zenoh 注册路由 |
|
||||
|
||||
---
|
||||
|
||||
@@ -634,7 +641,7 @@ uv run build --only mbank,prepare,vue
|
||||
|
||||
```bash
|
||||
uv run serve # 启动开发服务器
|
||||
uv run gen_plugin <name> # 生成统一风格插件骨架
|
||||
uv run gen_plugin <name> # 生成统一风格插件骨架（--process 生成进程插件项目）
|
||||
uv run gen_models # 生成 Pydantic 模型
|
||||
uv run build pyinstaller # PyInstaller 打包
|
||||
uv run build nuitka # Nuitka 打包
|
||||
|
||||
+76
-57
@@ -13,7 +13,7 @@
|
||||
| 模式 | 运行位置 | 目录 | 路由来源 | 契约校验位置 |
|
||||
| ---- | -------- | ---- | -------- | ------------ |
|
||||
| **inline**（默认） | 网关进程内 import | `src/plugins/<name>/`（chongming-plugins 仓库） | 网关盘扫 TOML 生成 | 网关启动时 |
|
||||
| **external（进程插件）** | 独立进程 | `workers/<name>/`（本地开发目录，**不入库**） | Worker 经 Zenoh 发布路由描述符，网关动态挂载 | **Worker 进程内** |
|
||||
| **external（进程插件）** | 独立进程 | `workers/<name>/`（本地开发目录，**自包含项目**，不入库） | Worker 经 Zenoh 发布路由描述符，网关动态挂载 | **Worker 进程内** |
|
||||
|
||||
进程插件的特点：
|
||||
|
||||
@@ -89,40 +89,48 @@ WorkerManager 据此做负载均衡，网关侧无需任何改动。
|
||||
|
||||
## 3. 目录结构约定
|
||||
|
||||
进程插件代码放在本地开发目录 `workers/<name>/`（**gitignore，不入库**）：
|
||||
进程插件是**自包含项目**：`workers/<name>/` 即项目根，同时也是打包 zip 的根
|
||||
（**gitignore，不入库**）。开发目录与容器工作目录完全一致，开发即产物：
|
||||
|
||||
```text
|
||||
workers/<name>/
|
||||
├── __init__.py # Plugin 子类 + create_workers / cleanup 模块级入口
|
||||
├── global_var.py # 模块级共享状态（Database、API client 等）
|
||||
├── router/ # RPC 端点实现
|
||||
│ ├── __init__.py # 导入所有端点模块
|
||||
│ └── <操作名>.py # 每个端点一个文件，@rpc_method 装饰器
|
||||
├── models/ # 数据模型（gen_models 自动生成，勿手动修改）
|
||||
│ ├── __init__.py
|
||||
│ └── pydantic.py # 请求/响应 Pydantic 模型
|
||||
├── requirements.txt # 扩展依赖（可选，每行一个包，打包时并入 pyproject.toml）
|
||||
└── README.md # 插件说明（可选）
|
||||
workers/<name>/ # 项目根 = zip 根 = 容器工作目录
|
||||
├── workers/<name>/ # 插件代码（模块 workers.<name>）
|
||||
│ ├── __init__.py # Plugin 子类 + create_workers / cleanup 模块级入口
|
||||
│ ├── global_var.py # 模块级共享状态（Database、API client 等）
|
||||
│ ├── router/ # RPC 端点实现
|
||||
│ │ ├── __init__.py # 导入所有端点模块
|
||||
│ │ └── <操作名>.py # 每个端点一个文件，@rpc_method 装饰器
|
||||
│ ├── models/ # 数据模型（gen_models 自动生成，勿手动修改）
|
||||
│ │ ├── __init__.py
|
||||
│ │ └── pydantic.py # 请求/响应 Pydantic 模型
|
||||
│ └── README.md # 插件说明（可选）
|
||||
├── config/
|
||||
│ ├── zenoh_config.json5 # Zenoh 会话配置
|
||||
│ └── workers/<name>/ # 插件注册 + 端点配置
|
||||
│ ├── config.toml # [workers] 节注册 + [worker] 元信息 + [workers.config]
|
||||
│ └── <操作名>.toml # 每个端点一个定义文件
|
||||
├── config.toml # 最小根配置（仅 [zenoh] 节，worker 启动必需）
|
||||
├── pyproject.toml # uv 依赖清单（chongming-worker + 扩展依赖）
|
||||
└── start.sh # 容器入口（uv sync + uv run worker_serve --type <name>）
|
||||
```
|
||||
|
||||
> 参考示例：`config/workers/demo/` 中的注册与端点配置（`demo` / `hello.toml`），
|
||||
> 以及 `workers/demo/`（本地目录，配合 `test_worker_isolation.py` 使用）。
|
||||
> 参考示例：`workers/demo/`（完整项目，含 5 个端点，配合 `test_worker_isolation.py` /
|
||||
> `test_process_mode_e2e.py` 使用）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 开发流程
|
||||
|
||||
### 第 1 步：创建插件代码
|
||||
### 第 1 步：生成项目骨架
|
||||
|
||||
```bash
|
||||
mkdir -p workers/demo/router
|
||||
mkdir -p workers/demo/models
|
||||
touch workers/demo/__init__.py
|
||||
touch workers/demo/global_var.py
|
||||
touch workers/demo/router/__init__.py
|
||||
uv run gen_plugin demo --process # 生成完整进程插件项目（含示例操作）
|
||||
uv run gen_plugin demo hello storage --process # 指定初始操作
|
||||
uv run gen_plugin demo add --process # 为已有项目增量添加操作
|
||||
```
|
||||
|
||||
`workers/demo/__init__.py`（与 inline 插件完全一致，推荐 Plugin 基类风格）：
|
||||
生成的代码位于 `workers/demo/workers/demo/`，其中 `__init__.py`（与 inline 插件
|
||||
完全一致，推荐 Plugin 基类风格）：
|
||||
|
||||
```python
|
||||
import logging
|
||||
@@ -154,15 +162,16 @@ cleanup = _plugin.cleanup
|
||||
```
|
||||
|
||||
> 注意：`module` 注册为 `workers.<name>` 时，`sys.path` 需包含项目根目录——
|
||||
> `worker_serve` 已自动处理（console script 启动时会显式把 CWD 加入 `sys.path`）。
|
||||
> `worker_serve` 已自动处理（console script 启动时会显式把 CWD 加入 `sys.path`），
|
||||
> 只需在项目根 `workers/<name>/` 下运行。
|
||||
|
||||
### 第 2 步：插件注册配置
|
||||
|
||||
创建 `config/workers/<name>/config.toml`，`[workers]` 节注册插件
|
||||
创建 `workers/<name>/config/workers/<name>/config.toml`，`[workers]` 节注册插件
|
||||
（**关键：`load_mode = "external"`**）：
|
||||
|
||||
```toml
|
||||
# config/workers/demo/config.toml
|
||||
# workers/demo/config/workers/demo/config.toml
|
||||
[workers]
|
||||
type = "demo" # 插件类型（worker type）
|
||||
module = "workers.demo" # Python 模块路径（进程插件用 workers.<name>）
|
||||
@@ -188,7 +197,7 @@ greeting_prefix = "Hello"
|
||||
|
||||
### 第 3 步：端点 TOML 定义
|
||||
|
||||
每个端点一个文件，如 `config/workers/<name>/hello.toml`：
|
||||
每个端点一个文件，如 `workers/<name>/config/workers/<name>/hello.toml`：
|
||||
|
||||
```toml
|
||||
[GET]
|
||||
@@ -207,14 +216,14 @@ timestamp = { type = "float", required = true }
|
||||
### 第 4 步：生成 Pydantic 模型
|
||||
|
||||
```bash
|
||||
uv run gen_models config/workers/demo workers/demo
|
||||
uv run gen_models workers/demo/config/workers/demo workers/demo/workers/demo
|
||||
```
|
||||
|
||||
在 `workers/<name>/models/` 下生成 `pydantic.py` 与 `__init__.py`。
|
||||
在 `workers/<name>/workers/<name>/models/` 下生成 `pydantic.py` 与 `__init__.py`。
|
||||
|
||||
### 第 5 步：实现 RPC 端点
|
||||
|
||||
`workers/<name>/router/hello.py`：
|
||||
`workers/<name>/workers/<name>/router/hello.py`：
|
||||
|
||||
```python
|
||||
import time
|
||||
@@ -232,7 +241,7 @@ async def hello(request: HelloGetRequest) -> HelloGetResponse:
|
||||
)
|
||||
```
|
||||
|
||||
`workers/<name>/router/__init__.py`：
|
||||
`workers/<name>/workers/<name>/router/__init__.py`：
|
||||
|
||||
```python
|
||||
from . import hello
|
||||
@@ -253,17 +262,23 @@ __all__ = ["hello"]
|
||||
|
||||
### 第 6 步：本地调试
|
||||
|
||||
在**插件项目根** `workers/<name>/` 下运行（worker 以 CWD 为工作目录读配置/import 代码）：
|
||||
|
||||
```bash
|
||||
uv run worker_serve --type demo # 本地调试（开发环境）
|
||||
cd workers/demo
|
||||
uv sync # 首次：安装依赖（项目独立 venv，与容器一致）
|
||||
uv run worker_serve --type demo # 本地调试
|
||||
uv run worker_serve --type demo --count 1 # 覆盖副本数
|
||||
chongming-worker --type demo # 容器入口（console script）
|
||||
./start.sh # 与容器一致的启动方式
|
||||
# 开发期复用仓库 venv（已装好 SDK）时，用 --project 指向仓库根：
|
||||
uv run --project .. worker_serve --type demo
|
||||
```
|
||||
|
||||
启动后预期日志：
|
||||
|
||||
```text
|
||||
[ demo ] 路由发布完成: 1 端点 + 无元信息
|
||||
[ demo ] Worker 进程就绪，等待退出信号...
|
||||
[demo] 路由发布完成: 5 端点 + 无元信息
|
||||
[demo] Worker 进程就绪，等待退出信号...
|
||||
```
|
||||
|
||||
> 若配置了 `load_mode` 非 `"external"`，会输出告警：网关也会在进程内加载该插件，
|
||||
@@ -272,10 +287,10 @@ chongming-worker --type demo # 容器入口（console script
|
||||
### 第 7 步：验证
|
||||
|
||||
```bash
|
||||
# 1. 进程隔离性（阻断 chongming 导入 + AST 检查 import 语句）
|
||||
# 1. 进程隔离性（阻断 chongming 导入 + AST 检查 import 语句；自动切到 demo 项目根）
|
||||
uv run python test_worker_isolation.py
|
||||
|
||||
# 2. 端到端（需先启动网关 uv run serve，且被测插件 load_mode = "external"）：
|
||||
# 2. 端到端（需先启动网关 uv run serve）：从 demo 项目根拉起 worker 进程，
|
||||
# 路由动态注册 → 跨进程 RPC → 退出摘除(404) → 重启恢复
|
||||
uv run python test_process_mode_e2e.py
|
||||
```
|
||||
@@ -287,26 +302,28 @@ uv run build_plugin demo # → dist/demo.zip
|
||||
uv run build_plugin demo --output /tmp/pkg # 指定输出目录
|
||||
```
|
||||
|
||||
打包前校验（任一不满足即失败退出）：
|
||||
打包 = 项目根直接压缩（开发目录即产物，zip 根即容器工作目录），自动排除
|
||||
`__pycache__` / `*.pyc` / `.venv` / `*.egg-info` / `.git`，`start.sh` 权限强制 0o755。
|
||||
|
||||
- `workers/<name>/` 插件代码目录存在
|
||||
- `config/workers/<name>/config.toml` 存在且含 `[workers]` 节
|
||||
- `config/zenoh_config.json5` 存在
|
||||
- `load_mode` 非 `"external"` 时**告警**（不阻断，但会造成重复服务）
|
||||
|
||||
产物布局（**zip 根即容器工作目录**）：
|
||||
产物布局与 §3 完全一致（**zip 根即容器工作目录**）：
|
||||
|
||||
```text
|
||||
workers/<name>/ 插件代码（模块 workers.<name>）
|
||||
config/workers/<name>/ 插件注册 + 端点配置
|
||||
config/zenoh_config.json5 Zenoh 会话配置
|
||||
config.toml 最小根配置（自动生成，仅 [zenoh] 节，不泄露网关配置）
|
||||
config.toml 最小根配置（仅 [zenoh] 节，worker 启动必需）
|
||||
pyproject.toml uv 依赖清单（chongming-worker 内网 git 源 + orjson + 扩展依赖）
|
||||
start.sh 容器入口：uv sync --no-dev + uv run worker_serve --type <name>
|
||||
```
|
||||
|
||||
扩展依赖：`workers/<name>/requirements.txt` 中逐行声明（`#` 开头为注释），
|
||||
打包时自动合并进 `pyproject.toml` 的 dependencies。
|
||||
打包前校验（任一不满足即失败退出）：
|
||||
|
||||
- `workers/<name>/` 项目根存在
|
||||
- `workers/<name>/config/workers/<name>/config.toml` 存在且含 `[workers]` 节
|
||||
- `workers/<name>/config/zenoh_config.json5` 与 `workers/<name>/config.toml`（含 `[zenoh]`）存在
|
||||
- `load_mode` 非 `"external"` 时**告警**（不阻断，但会造成重复服务）
|
||||
|
||||
扩展依赖：直接在项目根 `pyproject.toml` 的 `dependencies` 中追加（如 `"minio"`）。
|
||||
|
||||
### 第 9 步：容器部署
|
||||
|
||||
@@ -321,7 +338,7 @@ cd /app
|
||||
- 生产部署时进程插件与网关**分别打包到不同容器**：
|
||||
- 网关容器：`chongming` + 依赖
|
||||
- 进程插件容器：插件代码 + `chongming-worker` + 依赖
|
||||
- `config/workers/<name>/` 仅部署在**插件容器**（worker 自读）；网关侧无需放置
|
||||
- 插件配置随 zip 部署在**插件容器**（worker 自读）；网关侧无需放置
|
||||
（RouteRegistry 常驻订阅 Zenoh 路由描述符，与盘扫解耦）
|
||||
|
||||
---
|
||||
@@ -335,7 +352,7 @@ cd /app
|
||||
### 5.1 配置
|
||||
|
||||
```toml
|
||||
# config/workers/<name>/config.toml
|
||||
# workers/<name>/config/workers/<name>/config.toml
|
||||
[workers.config.storage]
|
||||
endpoint = "192.168.1.10:9000" # Minio 地址 host:port（不带协议前缀）
|
||||
access_key = "minioadmin"
|
||||
@@ -395,7 +412,7 @@ API 一览（`chongming_worker.storage.StorageClient`）：
|
||||
|
||||
### 5.3 参考示例
|
||||
|
||||
`workers/demo` 演示了 4 个文件传输端点（`config/workers/demo/` 下对应 TOML）：
|
||||
`workers/demo` 演示了 4 个文件传输端点（项目内 `config/workers/demo/` 下对应 TOML）：
|
||||
|
||||
- `POST /demo/presign_upload` — filename → object_key + 预签名 PUT URL（设备直传）
|
||||
- `GET /demo/presign_download` — object_key → 预签名 GET URL（设备直取）
|
||||
@@ -405,7 +422,7 @@ API 一览（`chongming_worker.storage.StorageClient`）：
|
||||
配置后重启 worker 即可用；未配置时这些端点返回「storage 未配置」错误（降级演示）。
|
||||
|
||||
> 依赖：minio SDK 随 `chongming-worker` 一起安装（utils/worker pyproject 已声明），
|
||||
> 进程插件无需额外 `requirements.txt`。SDK 侧 `chongming_worker.storage` 不依赖网关包，
|
||||
> 进程插件无需额外依赖。SDK 侧 `chongming_worker.storage` 不依赖网关包，
|
||||
> 隔离性约束与打包流程均不受影响。
|
||||
|
||||
---
|
||||
@@ -416,7 +433,7 @@ API 一览（`chongming_worker.storage.StorageClient`）：
|
||||
|
||||
- `chongming-worker`（worker SDK：`chongming_worker.*`）
|
||||
- `zenoh` / `pydantic` 等第三方库
|
||||
- 插件自身的扩展依赖（requirements.txt）
|
||||
- 插件自身的扩展依赖（项目根 `pyproject.toml` 中声明）
|
||||
|
||||
由 `test_worker_isolation.py` 双重保证：
|
||||
|
||||
@@ -445,12 +462,12 @@ Worker 进程启动时自读 TOML 并**在自己进程内**做三方一致性校
|
||||
|
||||
| 现象 | 原因 / 处理 |
|
||||
| ---- | ----------- |
|
||||
| 启动告警「load_mode 不是 external」 | 进程插件必须在 `config/workers/<name>/config.toml` `[workers]` 节设置 `load_mode = "external"`，否则网关内副本与外部进程重复服务 |
|
||||
| 契约校验失败、进程退出 | 检查 TOML 端点（subject/方法节）与 `@rpc_method(subject=..., method=...)` 是否一致；模型缺失时重跑 `uv run gen_models config/workers/<name> workers/<name>` |
|
||||
| 启动告警「load_mode 不是 external」 | 进程插件必须在 `workers/<name>/config/workers/<name>/config.toml` `[workers]` 节设置 `load_mode = "external"`，否则网关内副本与外部进程重复服务 |
|
||||
| 契约校验失败、进程退出 | 检查 TOML 端点（subject/方法节）与 `@rpc_method(subject=..., method=...)` 是否一致；模型缺失时重跑 `uv run gen_models workers/<name>/config/workers/<name> workers/<name>/workers/<name>` |
|
||||
| `TypeError: rpc_method() got an unexpected keyword argument 'stream'` | venv 里是旧版 chongming-worker（git 源拉取），本地未 push 的框架改动不生效；联调时 `uv pip install -e utils/worker` |
|
||||
| 路由没出现 | worker 是否就绪（日志「路由发布完成」）；网关 RouteRegistry 是否订阅（启动流程 5.1）；每 10s 自愈重发布，稍等或重启 worker |
|
||||
| 路由一直 404 | worker 是否已退出（优雅退出会摘除路由）；进程被 SIGKILL 时描述符残留，重启 worker 后重发布自愈覆盖 |
|
||||
| 找不到插件配置 | `worker_serve` 须在项目根目录下运行（读 `config/workers/<name>/config.toml`，`--config` 可指定全局配置路径） |
|
||||
| 找不到插件配置 | `worker_serve` 须在**插件项目根** `workers/<name>/` 下运行（读 `config/workers/<name>/config.toml`，`--config` 可指定全局配置路径） |
|
||||
| storage.* 端点报「storage 未配置」 | 插件 config.toml 未配置 `[workers.config.storage]`（或 `enabled = false` / 连接失败降级）。补齐配置后重启 worker；启动日志可见「对象存储已就绪」或「storage 连接失败」告警 |
|
||||
| 容器内 import `workers.demo` 失败 | 确认在容器工作目录（zip 根）启动，`start.sh` 内含 `cd "$(dirname "$0")"`，worker_serve 会把 CWD 加入 sys.path |
|
||||
|
||||
@@ -459,10 +476,12 @@ Worker 进程启动时自读 TOML 并**在自己进程内**做三方一致性校
|
||||
## 9. 相关命令速查
|
||||
|
||||
```bash
|
||||
uv run gen_plugin <name> --process # 生成进程插件项目骨架
|
||||
cd workers/<name> # 以下均在插件项目根下执行
|
||||
uv run worker_serve --type <name> # 本地调试独立 Worker 进程
|
||||
chongming-worker --type <name> # 容器入口（console script）
|
||||
uv run build_plugin <name> [--output <dir>] # 进程插件打包 → dist/<name>.zip
|
||||
uv run gen_models config/workers/<name> workers/<name> # 生成模型到进程插件目录
|
||||
./start.sh # 与容器一致的启动方式（uv sync + 启动）
|
||||
cd .. && uv run build_plugin <name> # 进程插件打包 → dist/<name>.zip
|
||||
uv run gen_models workers/<name>/config/workers/<name> workers/<name>/workers/<name> # 生成模型
|
||||
uv run python test_worker_isolation.py # 进程隔离性测试
|
||||
uv run python test_process_mode_e2e.py # 端到端测试（先启动网关）
|
||||
```
|
||||
|
||||
+61
-19
@@ -2,9 +2,10 @@
|
||||
build_plugin 打包命令冒烟测试
|
||||
|
||||
验证进程插件打包产物的完整性与错误路径：
|
||||
1. demo 插件打包成功，zip 内含代码/配置/最小根配置/依赖清单/可执行 start.sh
|
||||
2. 插件代码目录缺失时报 FileNotFoundError
|
||||
3. 插件 config.toml 缺失时报 FileNotFoundError
|
||||
1. demo 插件打包成功，zip = 项目根直接压缩（代码/配置/最小根配置/依赖清单/可执行 start.sh）
|
||||
2. 打包排除 __pycache__ / .venv / *.pyc 等非产物内容
|
||||
3. 插件项目目录缺失时报 FileNotFoundError
|
||||
4. 插件项目内配置缺失时报 FileNotFoundError
|
||||
|
||||
运行: uv run python test_build_plugin.py
|
||||
"""
|
||||
@@ -16,9 +17,10 @@ import zipfile
|
||||
from pathlib import Path
|
||||
|
||||
SRC = Path(__file__).parent
|
||||
sys.path.insert(0, str(SRC / "utils" / "cli" / "src"))
|
||||
sys.path.insert(0, str(SRC.parent / "utils" / "cli" / "src"))
|
||||
|
||||
from chongming_cli import build_plugin as bp # noqa: E402
|
||||
from chongming_cli import gen_plugin as gp # noqa: E402
|
||||
|
||||
failures = []
|
||||
|
||||
@@ -47,9 +49,9 @@ with zipfile.ZipFile(zip_path) as z:
|
||||
check("包含 start.sh", "start.sh" in names)
|
||||
check("不包含 __pycache__", not any("__pycache__" in n for n in names))
|
||||
|
||||
# 最小根配置：仅 [zenoh] 节，不含网关侧敏感配置
|
||||
# 最小根配置：worker 启动需 [zenoh] 节，且不含网关侧敏感配置
|
||||
root_conf = tomllib.loads(z.read("config.toml").decode())
|
||||
check("根配置仅含 [zenoh] 节", set(root_conf.keys()) == {"zenoh"}, str(sorted(root_conf)))
|
||||
check("根配置含 [zenoh] 节", "zenoh" in root_conf, str(sorted(root_conf)))
|
||||
check(
|
||||
"根配置不泄露网关 [security] 密钥",
|
||||
"secret_key" not in z.read("config.toml").decode(),
|
||||
@@ -66,7 +68,7 @@ with zipfile.ZipFile(zip_path) as z:
|
||||
)
|
||||
check(
|
||||
"pyproject 声明 chongming-worker git 源",
|
||||
pyproject["tool"]["uv"]["sources"]["chongming-worker"]["git"] == bp.CHONGMING_WORKER_GIT,
|
||||
pyproject["tool"]["uv"]["sources"]["chongming-worker"]["git"] == gp.CHONGMING_WORKER_GIT,
|
||||
)
|
||||
|
||||
# start.sh：可执行 + 指向正确的插件 type
|
||||
@@ -76,31 +78,71 @@ with zipfile.ZipFile(zip_path) as z:
|
||||
check("start.sh 可执行（0o755）", perms == 0o755, oct(perms))
|
||||
|
||||
|
||||
# ========== 2. 错误路径：插件代码目录缺失 ==========
|
||||
# ========== 2. 打包排除非产物内容（临时最小项目） ==========
|
||||
def make_mini_project(proj: Path) -> None:
|
||||
"""构造一个结构合法的迷你插件项目（含需要排除的垃圾文件）。"""
|
||||
(proj / "workers" / "mini" / "router").mkdir(parents=True)
|
||||
(proj / "workers" / "mini" / "__init__.py").write_text("", encoding="utf-8")
|
||||
(proj / "workers" / "mini" / "router" / "__init__.py").write_text("", encoding="utf-8")
|
||||
conf = proj / "config" / "workers" / "mini"
|
||||
conf.mkdir(parents=True)
|
||||
(conf / "config.toml").write_text(
|
||||
'[workers]\ntype = "mini"\nmodule = "workers.mini"\nload_mode = "external"\n',
|
||||
encoding="utf-8",
|
||||
)
|
||||
(proj / "config" / "zenoh_config.json5").write_text("{}", encoding="utf-8")
|
||||
(proj / "config.toml").write_text('[zenoh]\njson5_path = "config/zenoh_config.json5"\n', encoding="utf-8")
|
||||
(proj / "pyproject.toml").write_text("[project]\nname = \"mini-worker\"\n", encoding="utf-8")
|
||||
(proj / "start.sh").write_text("#!/usr/bin/env bash\necho mini\n", encoding="utf-8")
|
||||
(proj / "start.sh").chmod(0o755)
|
||||
# 垃圾内容：缓存目录、字节码、虚拟环境
|
||||
(proj / "workers" / "mini" / "__pycache__" / "x.pyc").parent.mkdir(parents=True)
|
||||
(proj / "workers" / "mini" / "__pycache__" / "x.pyc").write_bytes(b"x")
|
||||
(proj / "workers" / "mini" / "y.pyc").write_bytes(b"y")
|
||||
(proj / ".venv" / "bin" / "pip").parent.mkdir(parents=True)
|
||||
(proj / ".venv" / "bin" / "pip").write_text("", encoding="utf-8")
|
||||
|
||||
|
||||
orig_workers = bp.WORKERS_DIR
|
||||
bp.WORKERS_DIR = tmp / "no_workers"
|
||||
mini_proj = tmp / "workers" / "mini"
|
||||
make_mini_project(mini_proj)
|
||||
bp.WORKERS_DIR = tmp / "workers"
|
||||
try:
|
||||
bp.build_plugin_package("ghost", output_dir=tmp / "dist")
|
||||
check("缺插件代码目录应抛 FileNotFoundError", False)
|
||||
except FileNotFoundError:
|
||||
check("缺插件代码目录应抛 FileNotFoundError", True)
|
||||
zip_path = bp.build_plugin_package("mini", output_dir=tmp / "dist")
|
||||
with zipfile.ZipFile(zip_path) as z:
|
||||
names = set(z.namelist())
|
||||
check("排除 __pycache__", not any("__pycache__" in n for n in names), str(sorted(names)))
|
||||
check("排除 *.pyc", not any(n.endswith(".pyc") for n in names))
|
||||
check("排除 .venv", not any(n.startswith(".venv") for n in names))
|
||||
check("保留代码与配置", {"workers/mini/__init__.py", "config/workers/mini/config.toml"} <= names)
|
||||
finally:
|
||||
bp.WORKERS_DIR = orig_workers
|
||||
|
||||
|
||||
# ========== 3. 错误路径：插件配置缺失 ==========
|
||||
orig_conf_dir = bp.PLUGINS_CONFIG_DIR
|
||||
bp.PLUGINS_CONFIG_DIR = tmp / "no_config"
|
||||
# ========== 3. 错误路径：插件项目目录缺失 ==========
|
||||
bp.WORKERS_DIR = tmp / "no_workers"
|
||||
try:
|
||||
bp.build_plugin_package("demo", output_dir=tmp / "dist")
|
||||
bp.build_plugin_package("ghost", output_dir=tmp / "dist")
|
||||
check("缺插件项目目录应抛 FileNotFoundError", False)
|
||||
except FileNotFoundError:
|
||||
check("缺插件项目目录应抛 FileNotFoundError", True)
|
||||
finally:
|
||||
bp.WORKERS_DIR = orig_workers
|
||||
|
||||
|
||||
# ========== 4. 错误路径：项目内插件配置缺失 ==========
|
||||
# 只建代码目录、不建 config/workers/<name>/config.toml
|
||||
(orig_workers / "ghost").mkdir(parents=True)
|
||||
try:
|
||||
bp.build_plugin_package("ghost", output_dir=tmp / "dist")
|
||||
check("缺插件配置应抛 FileNotFoundError", False)
|
||||
except FileNotFoundError:
|
||||
check("缺插件配置应抛 FileNotFoundError", True)
|
||||
finally:
|
||||
bp.PLUGINS_CONFIG_DIR = orig_conf_dir
|
||||
shutil.rmtree(orig_workers / "ghost", ignore_errors=True)
|
||||
|
||||
|
||||
# ========== 4. 错误路径：插件名不合法 ==========
|
||||
# ========== 5. 错误路径：插件名不合法 ==========
|
||||
try:
|
||||
bp.build_plugin_package("Bad-Name", output_dir=tmp / "dist")
|
||||
check("非法插件名应抛 ValueError", False)
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
"""
|
||||
混合模式（external 插件）端到端测试
|
||||
进程插件（external 模式）端到端测试
|
||||
|
||||
前置条件:
|
||||
1. 网关正常运行（uv run serve）；example 插件配置为 external：
|
||||
config/workers/example/config.toml [workers] 节 load_mode = "external"
|
||||
2. 本脚本自己拉起/停止独立 worker 进程（uv run worker_serve --type example）
|
||||
1. 网关正常运行（uv run serve）
|
||||
2. demo 进程插件（workers/demo/，load_mode = "external"）
|
||||
|
||||
验证:
|
||||
本脚本从 demo 插件项目根（= 打包 zip 根）拉起/停止独立 worker 进程
|
||||
（worker_serve --type demo），验证:
|
||||
1. worker 启动后 → HTTP 路由动态出现且跨进程 RPC 可调
|
||||
2. worker 优雅退出 → 路由动态摘除（404）
|
||||
3. worker 重启 → 路由恢复
|
||||
@@ -18,13 +18,17 @@ import urllib.request
|
||||
from pathlib import Path
|
||||
|
||||
GATEWAY_URL = "http://localhost:8000"
|
||||
TEST_URL = f"{GATEWAY_URL}/api/v1/calc/add?a=3&b=4"
|
||||
TEST_URL = f"{GATEWAY_URL}/api/v1/demo/hello?name=chongming"
|
||||
POLL_TIMEOUT = 30.0
|
||||
|
||||
# 优先使用 venv 控制台脚本（uv sync 后生成），不存在时退回 uv run
|
||||
_WORKER_CMD = [str(Path(sys.executable).parent / "worker_serve"), "--type", "example"]
|
||||
# 插件项目根（= 容器工作目录 = zip 根）：worker 在项目根下读配置/import 代码
|
||||
REPO = Path(__file__).parent.parent
|
||||
PROJECT = REPO / "workers" / "demo"
|
||||
|
||||
# 优先使用仓库 venv 控制台脚本（避免在插件项目内新建 venv），否则退回 uv run --project
|
||||
_WORKER_CMD = [str(Path(sys.executable).parent / "worker_serve"), "--type", "demo"]
|
||||
if not Path(_WORKER_CMD[0]).exists():
|
||||
_WORKER_CMD = ["uv", "run", "worker_serve", "--type", "example"]
|
||||
_WORKER_CMD = ["uv", "run", "--project", str(REPO), "worker_serve", "--type", "demo"]
|
||||
|
||||
PASS = 0
|
||||
FAIL = 0
|
||||
@@ -63,9 +67,10 @@ def wait_http(target_status=200, timeout=POLL_TIMEOUT):
|
||||
|
||||
|
||||
def run():
|
||||
# 1. 拉起独立 worker 进程
|
||||
# 1. 拉起独立 worker 进程（CWD = 插件项目根，与容器一致）
|
||||
proc = subprocess.Popen(
|
||||
_WORKER_CMD,
|
||||
cwd=str(PROJECT),
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.STDOUT,
|
||||
text=True,
|
||||
@@ -83,6 +88,7 @@ def run():
|
||||
# 3. 重启 worker → 路由恢复
|
||||
proc2 = subprocess.Popen(
|
||||
_WORKER_CMD,
|
||||
cwd=str(PROJECT),
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.STDOUT,
|
||||
text=True,
|
||||
@@ -103,5 +109,5 @@ def run():
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
print("提示: 请先以 load_mode=process 启动网关 (uv run serve)\n")
|
||||
print(f"提示: 请先启动网关 (uv run serve)；worker 将从 {PROJECT} 拉起\n")
|
||||
sys.exit(run())
|
||||
|
||||
@@ -4,12 +4,22 @@ Worker 进程隔离性测试
|
||||
验证进程插件与网关完全隔离：阻断 chongming（网关包）的两种导入路径后，
|
||||
worker 侧全链路（SDK 导入 → 插件配置自读 → 插件 import → 契约校验）仍可用。
|
||||
|
||||
与容器行为一致：chdir 到插件项目根 workers/demo/（= 打包 zip 根），
|
||||
worker_serve 即以该目录为 CWD 读配置、并把 CWD 加入 sys.path。
|
||||
|
||||
任何对 chongming.* / src.chongming.* 的导入都会直接触发 ImportError。
|
||||
"""
|
||||
import os
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
SRC = Path(__file__).parent
|
||||
REPO = SRC.parent
|
||||
|
||||
# 模拟容器：CWD = 插件项目根（zip 根），并把它置于 sys.path 首位
|
||||
PROJECT = REPO / "workers" / "demo"
|
||||
os.chdir(PROJECT)
|
||||
sys.path.insert(0, str(PROJECT))
|
||||
sys.path.insert(0, str(SRC))
|
||||
|
||||
# 阻断网关包导入（两种访问路径）。chongming_worker / zenoh / pydantic 等不受影响。
|
||||
|
||||
Reference in New Issue
Block a user