modify: worker 管理多进程副本

README.md

@@ -238,7 +238,7 @@ worker/<type>/<worker_id>/__admin__
 | `restart`   | 重启该副本，副本槽位（index）由管理循环驱动，重新生成新 `worker_id`（`worker-<index>-<epoch>-<pid>`）并经 liveliness 更新 |
 | `stop`      | 停止该副本                                                             |
 | `drain`     | **优雅排空**：摘除 liveliness/业务 Queryable 隔绝新请求，等待正在处理的在途请求完成后再退出，管理循环不重建（数量-1） |
-| `rescale`   | 按 `data.scale` 把**当前进程内**该类型副本数调整为指定值（`data:{"scale":N}`），并把 `[workers].count` 写回本进程侧配置 |
+| `rescale`   | 按 `data.scale` 把**当前进程内**该类型副本数调整为指定值（`data:{"scale":N}`）；**两种口径**：不带 `instance_id` 时为「全局对称分摊」（写回全局 count + 各实例均分），带 `instance_id + absolute=true` 且命中本实例时为「逐实例精细扩缩」（只改该实例绝对副本数），target 非本实例则安全忽略 |
 | `config_set`| 更新 `[workers.config]` 运行时配置（路由配置除外）；成功则写回配置并重启该类型全部对应副本，任一失败返回失败信息 |
 
 ### REST 管理端点（仅超管）
@@ -250,7 +250,9 @@ worker/<type>/<worker_id>/__admin__
 | `POST` | `/api/v1/admin/workers/<type>/stop`     | 停止 single 副本 / 某插件全部副本      |
 | `GET`  | `/api/v1/admin/workers/<type>/config`   | 读取该插件的现有 `[workers.config]`（展示当前值） |
 | `POST` | `/api/v1/admin/workers/<type>/config`   | 更新配置（body `{updates:{k:v}}`），下发并重启 |
-| `POST` | `/api/v1/admin/workers/<type>/scale`    | 调整该类型副本数（body `{count:N}`），扩缩容 + 持久化 |
+| `POST` | `/api/v1/admin/workers/<type>/scale`            | 调整该类型副本数（body `{count:<全局总量>}`）：写全局 count → 清除逐实例定制回均分 → 广播全部存活实例，**全局对称分摊**
+| `GET`  | `/api/v1/admin/workers/<type>/instances`        | 按外部进程实例（instance_id）分组读取该类型副本（供前端逐实例精细扩缩展示） |
+| `POST` | `/api/v1/admin/workers/<type>/scale_instance`   | **逐实例精细扩缩**（body `{instance_id, count}`）：只把指定实例的副本数调到 N，其余实例不动，持久化到 `instcounts` 覆盖表 |
 
 > 旧版运行时未声明 `__admin__` 管理能力时，管理指令会超时（HTTP 502，见日志提示）。
 
@@ -267,7 +269,8 @@ worker/<type>/<worker_id>/__admin__
 - **扩容**：新增副本槽位（`WorkerPool` 新增 `_managed_worker` 管理循环，新副本注册 liveliness 后可被负载均衡）。
 - **缩容**：随机挑选多余副本触发 **`drain`（优雅排空）**——先摘除 liveliness/业务 Queryable **隔绝新请求**，等待正在处理的**在途请求完成**后再关闭该副本（`in-flight` 计数实现），避免中断业务；管理循环不重建。
 - **目标数量持久化**：`rescale` 把 `[workers].count` 写回 `config.toml`，网关/进程重启后按新数量加载。
-- **统一协议**：inline 与 external 共用。网关对 inline 直接调整本进程 `WorkerPool`；对 external 经 Zenoh 向任一存活副本下发 `rescale`，由其**所在进程内**的池扩缩并写回自身配置（无需重启整个进程/容器）。
+- **统一协议**：inline 与 external 共用。网关对 inline 直接调整本进程 `WorkerPool`；对 external 经 Zenoh **向该类型全部存活实例广播 `rescale`**（不只是挑一个副本），由各实例按其 quota 扩缩并写回自身配置（无需重启整个进程/容器）。
+- **逐实例 vs 全局**：`/scale` 是对某个类型的**全局对称扩缩**；若外部进程有多个（多机/多容器），`/scale` 会把全局总量均分到每个存活实例。要单独调整**某一个**外部实例的副本数，见下文「外部进程实例粒度扩缩」。
 
 ### 全局副本数协调（多网关）
 
@@ -286,7 +289,21 @@ worker/<type>/<worker_id>/__admin__
   launch_worker_count = "toml"   # "toml"（默认)=启动用 toml 的 count 覆盖并写回 cache；"cache"=cache 为单一事实来源，toml 仅在缺失时引导
   ```
 
-- **进程插件（external）不受该开关影响**：网关只对 **inline** 插件用 cache 解析启动副本数（见「启动流程」第 5 步 `load_workers`）；external 插件由外部编排按其自身配置 `config/workers/<type>/config.toml` 的 `count` 启动，不经网关、也不读 cache。运行时 `scale` 对 external 仍走「向存活副本下发 rescale」路径，同样与该开关无关。
+- **进程插件（external）实例粒度参与分摊**：网关只对 **inline** 插件用 cache 解析启动副本数（见「启动流程」第 5 步 `load_workers`），external 插件的启动副本数由外部编排按自身配置决定；但**运行时的缩放**上，external 并不退化为“每进程全额”，而是同样在**共享 cache 上登记实例参与方**来分摊，避免多实例把副本翻倍：
+  - **实例登记 + 心跳租约**：每个 external 进程启动时向 `worker:cm:instances:<type>` 登记自身参与方（`[instance_id, ts]`），并每 15s 心跳续约；超过租约（60s）未心跳的死实例会被清理。`divmod` 按存活参与方 N 均分全局 count（余量补靠前实例），`N==1` 时退化为全额（单部署零影响）。
+  - **实例标识默认唯一**：`--instance` / 环境变量 `CHONGMING_WORKER_INSTANCE` 显式指定（跨重启稳定、逐实例精细扩缩可持续命中）；缺省回退 `{hostname}:{pid}`——**同一机器并行多个未指定 `--instance` 的进程也能靠 pid 区分**，不会因为 id 相同被并成一个参与方导致副本翻倍或前端只显示一个实例。注意缺省 id 随进程重启变化。
+  - **广播 + 幂等收敛**：`/scale` 写全局 count 后向该类型**全部存活实例**广播 `rescale`，各实例读同一全局 count + 同一份参与方列表算出的 quota 一致，重复 rescale 也幂等，因此任意地收敛到同一预期状态。
+  - **前提**：external 需共用共享 `[cache]`（多实例 redis 或共享卷 diskcache）；`cache is None` 时退化为全额（仅单实例安全）。
+
+### 外部进程实例粒度扩缩（逐实例精细扩缩）
+
+当同一个类型跑多个外部进程（多机/多容器）时，除了 `scale` 的**全局对称扩缩**，还可以只对**某一个实例**精确扩缩：
+
+- **语义**：把目标实例的副本数**绝对值**设为 N，其它实例不动；与全局 `scale` 共存——全局对称是默认/一键复位，逐实例是定制覆盖。
+- **覆盖表**：每个实例的绝对目标存 cache 键 `worker:cm:instcounts:<type>` = `{instance_id: 绝对副本数}`。有记录的实例按绝对数执行；没记录的实例回退到全局均分。一旦用 `scale_instance` 定制了某实例，之后 `scale`（全局）会**清除整张覆盖表**回到均分（显式“复位”），因此两者不会互相干扰。
+- **命中判断**：rescale 的下发必须命中**本实例**才执行（`instance_id` 与 `register_instance` 一致），目标是其它实例则安全忽略，避免误缩。
+- **REST / UI**：`POST /admin/workers/<type>/scale_instance`（body `{instance_id, count}`）下发；`GET /admin/workers/<type>/instances` 供前端按实例分组展示当前副本数。前端用「调整数量」（全局对称）和「逐实例精细扩缩」表格（实例 id / 模式 / 当前副本数 / 目标 + 应用）两个入口。
+- **协调前提**：与外部广播缩放一致，需共享 `[cache]`，且外部进程用稳定的 `--instance` / `CHONGMING_WORKER_INSTANCE`（缺省 `{hostname}:{pid}` 虽唯一但重启会变，跨重启持续命中请显式指定）。
 
 ### inline worker 宿主级领导选举（gunicorn 多 worker 兼容）
 
@@ -314,7 +331,10 @@ inline worker 的生命周期交给**基于分布式锁的宿主级领导选举*
 - **登录**：经 auth 插件 `POST /auth/login` 领取管理 Token（无需手填 JWT），从 JWT 解析当前用户与超管标识。
 - **鉴权**：仅 `is_superuser=true` 可管理；权限不足时前端/后端弹出对应提示（403）。
 - **列表分页**：展示副本（插件类型 / 副本 ID / 模式 inline|external / 状态），内置分页。
-- **操作**：单副本重启、批量重启（选中）、插件级重启全部副本、更新插件配置（弹窗展示现有配置值，点行带入编辑）、**调整副本数量**（当前数 + `el-input-number` 设目标 + 应用，可扩缩容）。
+- **查询与筛选**：列表顶部统一筛选栏——关键字搜索（插件类型 / 副本 ID / 实例 ID）、模式筛选（全部 / inline / external）、副本数 ≥ N 过滤；**同时作用于下方「逐实例精细扩缩」分组表**（副本数过滤仅对分组表生效），筛选条件变化自动回到第一页。
+- **操作**：单副本重启、批量重启（选中）、插件级重启全部副本、更新插件配置（弹窗展示现有配置值，点行带入编辑；支持对象/数组等嵌套值的**结构化 JSON 编辑与校验/格式化**）、**调整副本数量**（当前数 + `el-input-number` 设目标 + 应用，可扩缩容）。
+- **逐实例精细扩缩**：按外部进程实例（instance_id）**分组**展示（实例 id / 模式 / 当前副本数），每行可设目标副本数并「应用」——仅调整该实例，其余实例不动；全局「调整数量」后分组表也会自动刷新。
+- **自动刷新**：页面每 10s 轮询总副本列表**与**逐实例分组表，扩缩容/重启/停止等异步结果无需手动刷新即可反映。
 - **auth 核心插件**：配置不可更改，不在列表中展示（`Worker` 列表自动过滤 `worker_type == "auth"`）。
 - 调小副本数会**触发优雅排空**并在前端确认提示中说明。