docs: 说明文件重整（README 改使用导向，运维细节移入 docs/worker-management.md）
This commit is contained in:
+19
-51
@@ -27,9 +27,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 2. 运行原理
|
||||
|
||||
### 2.1 架构
|
||||
## 2. 工作机制（简述）
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
@@ -37,7 +35,7 @@ graph TB
|
||||
REG[网关 RouteRegistry<br/>订阅 chongming/routes/**] -->|动态挂载/摘除| API
|
||||
API --> WM[WorkerManager<br/>负载均衡 + 超时重试]
|
||||
|
||||
subgraph GW[网关容器 chongming]
|
||||
subgraph GW[网关容器]
|
||||
API
|
||||
REG
|
||||
WM
|
||||
@@ -54,36 +52,18 @@ graph TB
|
||||
WS -.->|SIGTERM 时 delete 摘除| REG
|
||||
```
|
||||
|
||||
### 2.2 Worker 进程启动流程（`chongming_worker.process.worker_serve`）
|
||||
`chongming-worker --type demo` 启动后的流程：
|
||||
|
||||
```text
|
||||
chongming-worker --type demo
|
||||
1. 读全局 config.toml（仅 [zenoh] 节）→ 打开 Zenoh 会话
|
||||
2. 自读 config/workers/demo/config.toml 的 [workers] 节（load_plugin_config 展平）
|
||||
3. import 插件模块（plugins.<name> / workers.<name>）→ 触发 @rpc_method 注册
|
||||
4. 进程内契约校验（TOML ↔ 注册表 ↔ 生成模型），硬失败则退出（退出码 1）
|
||||
5. create_workers 创建 Worker 副本（默认 count 个，--count 可覆盖）
|
||||
6. RoutePublisher 发布路由描述符 → 网关动态挂载 HTTP 路由
|
||||
7. 等待退出信号；期间每 10s 周期性重发布（网关后启动 / 样本丢失时自愈）
|
||||
8. SIGTERM/SIGINT → 摘除路由 → cleanup → 取消副本任务 → 关闭会话
|
||||
```
|
||||
1. 读根 `config.toml` 的 `[zenoh]` 节打开会话，自读
|
||||
`config/workers/demo/config.toml` 的 `[workers]` 节（含 `[workers.config]` 运行时配置）
|
||||
2. import 插件模块触发 `@rpc_method` 注册 → **进程内契约校验**（不通过则退出码 1）
|
||||
3. `create_workers` 创建副本（默认 `count` 个，`--count` 可覆盖），注册 liveliness
|
||||
4. 经 Zenoh 把路由描述符 put 到 `chongming/routes/<type>/<route_id>`，网关动态挂载 HTTP 路由；
|
||||
每 10s 重发布（网关后启动或样本丢失时自愈）
|
||||
5. 收到 SIGTERM/SIGINT → delete 描述符（路由摘除）→ cleanup → 关闭会话
|
||||
|
||||
### 2.3 路由注册与摘除协议
|
||||
|
||||
- **发布**：路由描述符 put 到 `chongming/routes/<type>/<route_id>`，其中
|
||||
`route_id = <subject 的 . 替换为 _>__<METHOD>`（如 `demo_hello__GET`），
|
||||
描述符为 TOML 兼容 dict + `schema_version=1` + `type=<插件名>`
|
||||
- **元信息**：插件声明了 `[[workers.mqtt_topics]]` 时，额外发布
|
||||
`chongming/routes/<type>/__meta__`（含 mqtt_topics），网关据此动态订阅外部主题
|
||||
- **自愈**：每 10s 重发布一次全部描述符（`ANNOUNCE_INTERVAL`），网关后启动或样本丢失可恢复
|
||||
- **摘除**：优雅退出时 delete 全部已发布 key，网关 2s 防抖后摘除 HTTP 端点（请求变 404）
|
||||
- **网关侧**：RouteRegistry 常驻订阅 `chongming/routes/**`，与盘扫解耦——
|
||||
**网关容器无需放置 external 插件的配置文件**
|
||||
|
||||
### 2.4 服务发现
|
||||
|
||||
Worker 副本经 liveliness 注册 `worker/<type>/<id>`（与 inline 副本同一机制），
|
||||
WorkerManager 据此做负载均衡，网关侧无需任何改动。
|
||||
要点：网关容器**无需**放置 external 插件的配置文件（RouteRegistry 常驻订阅，与盘扫解耦）；
|
||||
描述符字段与 keyexpr 细节见 [线协议规范](plugin-wire-protocol.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -114,8 +94,7 @@ workers/<name>/ # 项目根 = zip 根 = 容器工作目录
|
||||
└── start.sh # 容器入口（uv sync + uv run chongming-worker --type <name>）
|
||||
```
|
||||
|
||||
> 参考示例：`workers/demo/`（完整项目，含 5 个端点，配合 `test_worker_isolation.py` /
|
||||
> `test_process_mode_e2e.py` 使用）。
|
||||
> 参考示例：`workers/demo/`（完整项目，含 5 个端点）。
|
||||
|
||||
---
|
||||
|
||||
@@ -291,16 +270,10 @@ uv run --project .. chongming-worker --type demo
|
||||
> 若配置了 `load_mode` 非 `"external"`，会输出告警：网关也会在进程内加载该插件，
|
||||
> 外部进程将与网关内副本**重复服务**。
|
||||
|
||||
### 第 7 步：验证
|
||||
### 第 7 步：联调验证
|
||||
|
||||
```bash
|
||||
# 1. 进程隔离性（阻断 chongming 导入 + AST 检查 import 语句；自动切到 demo 项目根）
|
||||
uv run python test_worker_isolation.py
|
||||
|
||||
# 2. 端到端（需先启动网关 uv run serve）：从 demo 项目根拉起 worker 进程，
|
||||
# 路由动态注册 → 跨进程 RPC → 退出摘除(404) → 重启恢复
|
||||
uv run python test_process_mode_e2e.py
|
||||
```
|
||||
启动网关（`uv run serve`）后调用插件路由即可验证端到端：网关日志可见路由动态挂载，
|
||||
worker 退出后路由自动摘除（请求变 404），重启 worker 后恢复。
|
||||
|
||||
### 第 8 步：打包
|
||||
|
||||
@@ -442,11 +415,8 @@ API 一览（`chongming_worker.storage.StorageClient`）：
|
||||
- `zenoh` / `pydantic` 等第三方库
|
||||
- 插件自身的扩展依赖（项目根 `pyproject.toml` 中声明）
|
||||
|
||||
由 `test_worker_isolation.py` 双重保证：
|
||||
|
||||
1. **运行时阻断**：`sys.modules["chongming"] = None` 后走完整链路
|
||||
（SDK 导入 → 插件配置自读 → 插件 import → 契约校验），任何网关依赖立即 ImportError
|
||||
2. **静态检查**：AST 解析 SDK 各模块源码，确认无 `chongming` / `chongming.*` import 语句
|
||||
隔离性由框架保证：SDK 导入链路中一旦出现 `chongming` / `chongming.*` 的 import，
|
||||
运行时立即 `ImportError`（启动即暴露），无需等到部署阶段。
|
||||
|
||||
---
|
||||
|
||||
@@ -476,7 +446,7 @@ Worker 进程启动时自读 TOML 并**在自己进程内**做三方一致性校
|
||||
| 路由一直 404 | worker 是否已退出（优雅退出会摘除路由）；进程被 SIGKILL 时描述符残留，重启 worker 后重发布自愈覆盖 |
|
||||
| 找不到插件配置 | `chongming-worker` 须在**插件项目根** `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 |
|
||||
| 容器内 import `workers.demo` 失败 | 确认在容器工作目录（zip 根）启动，`start.sh` 内含 `cd "$(dirname "$0")"`，启动入口会把 CWD 加入 sys.path |
|
||||
|
||||
---
|
||||
|
||||
@@ -489,8 +459,6 @@ uv run chongming-worker --type <name> # 本地调试独立 Worker
|
||||
./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 # 端到端测试（先启动网关）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user