From 3a359fa48516f0349ecdc21f002f9c9ae79aa179 Mon Sep 17 00:00:00 2001
From: chakcy <947105045@qq.com>
Date: Fri, 2 Oct 2026 11:54:46 +0800
Subject: [PATCH] =?UTF-8?q?modify:=20=E5=BE=AE=E6=9C=8D=E5=8A=A1=E6=BC=94?=
=?UTF-8?q?=E8=BF=9B?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
.gitignore | 5 +-
README.md | 28 ++-
src/chongming/app/__init__.py | 4 +-
src/chongming/app/core/mqtt_bridge.py | 29 ++-
src/chongming/app/core/route_generator.py | 20 ++
src/chongming/app/core/worker_manager.py | 247 ++++++++++++++++++----
src/chongming/app/routes/__init__.py | 3 +-
src/chongming/app/routes/storage.py | 53 -----
test.png | Bin 341696 -> 0 bytes
test/test_call_stats.py | 13 +-
test/test_instance_targeting.py | 220 +++++++++++++++++++
test/test_instance_targeting_http.py | 207 ++++++++++++++++++
test/test_mqtt_custom_topics.py | 40 +++-
test/test_passthrough_optimization.py | 66 +++++-
test/test_stream_e2e_zenoh.py | 6 +-
test/test_stream_route.py | 12 +-
16 files changed, 821 insertions(+), 132 deletions(-)
delete mode 100644 src/chongming/app/routes/storage.py
delete mode 100644 test.png
create mode 100644 test/test_instance_targeting.py
create mode 100644 test/test_instance_targeting_http.py
diff --git a/.gitignore b/.gitignore
index 37c5793..4b8930c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,4 +41,7 @@ config
# lib
lib
auto.crt
-auto.key
\ No newline at end of file
+auto.key
+
+*.pem
+*.key
\ No newline at end of file
diff --git a/README.md b/README.md
index 42838f9..2aad3df 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,7 @@
| 特性 | 说明 |
| --------------------- | -------------------------------------------------------------------- |
| **FastAPI + Uvicorn** | 高性能异步 Web 框架，自动生成 OpenAPI 文档 |
-| **Zenoh 服务发现** | 基于 liveliness 的 Worker 注册与 RPC 调用，负载均衡 + 超时重试 |
+| **Zenoh 服务发现** | 基于 liveliness 的 Worker 注册与 RPC 调用，负载均衡 + 实例定向 + 超时重试 |
| **MQTT 集成** | amqtt Broker（内嵌或外部），MQTT ↔ Worker 双向桥接 |
| **动态路由生成** | 扫描 `config/workers/*/*.toml` 自动注册 HTTP 路由 |
| **Worker 框架** | `@rpc_method` 装饰器 + `Plugin` 基类统一生命周期 + Pydantic 模型绑定 |
@@ -194,7 +194,7 @@ graph TB
MQTT[MQTT 客户端] -->|chongming/+/+| BRIDGE[MQTT Bridge
纯客户端模式]
REG[RouteRegistry
订阅 chongming/routes/**] -->|动态挂载/摘除 HTTP 路由| API
- API --> WM[WorkerManager
随机负载均衡 + 超时重试]
+ API --> WM[WorkerManager
随机负载均衡 / 实例定向 + 超时重试]
BRIDGE --> WM
subgraph GW[网关进程 chongming]
@@ -328,6 +328,30 @@ worker///__admin__
- **REST / UI**：`POST /admin/workers//scale_instance`（body `{instance_id, count}`）下发；`GET /admin/workers//instances` 供前端按实例分组展示当前副本数。前端用「调整数量」（全局对称）和「逐实例精细扩缩」表格（实例 id / 模式 / 当前副本数 / 目标 + 应用）两个入口。
- **协调前提**：与外部广播缩放一致，需共享 `[cache]`，且外部进程用稳定的 `--instance` / `CHONGMING_WORKER_INSTANCE`（缺省 `{hostname}:{pid}` 虽唯一但重启会变，跨重启持续命中请显式指定）。
+### 实例定向调用（把请求固定到某个进程实例）
+
+默认情况下，同 type 的多个副本（含 inline 与 external 进程）逐请求**随机负载均衡**（`random.choice`），这是绝大多数无状态插件想要的。若某插件持有**只存在于某个进程本地**的状态（本地 SQLite/文件、串口或其他设备连接），需要请求固定打到那个进程上，可用**实例定向**：
+
+- **指定方式（三种入口，语义一致）**：
+ - HTTP：请求头 `X-Chongming-Instance: <实例id>`
+ - MQTT：信封载荷顶层加控制字段 `target_instance`（网关读后**摘除**，业务 side 看不到该字段）
+ - 程序内调用：`worker_manager.call(...)` / `call_raw(...)` / `call_stream(...)` 的 `instance_id=` 参数（`utils/request` 的独立 Client 不支持定向）
+- **实例 id 取值**：worker 侧按 `--instance` → `CHONGMING_WORKER_INSTANCE` → `CHONGMING_GATEWAY_ID` → `{hostname}:{pid}` 的顺序解析（`current_instance_id()`）；网关侧定向寻址 inline 副本时用网关自身实例 id（`CHONGMING_GATEWAY_ID`，缺省 hostname）。两侧缺省值在容器环境（K8s 给网关进程注入 `CHONGMING_GATEWAY_ID`）下**自动一致**，无需额外配置；裸机同一台跑多个网关时请显式指定，否则默认实例 id 里的 pid 不同会导致对不上。人可读的取值列表见 `GET /api/v1/admin/workers//instances`。
+- **粒度**：定向到**进程实例**；若该实例内有多个副本，请求仍在这几个副本之间随机均衡（即“实例固定、副本仍均衡”）。
+- **实例离线时严格报错**：返回 HTTP 503 并附已识别实例列表，**不会静默回退到其它实例**——回退会让粘滞状态的插件跑在错误副本上，产生难查的数据错乱。MQTT 同理（响应主题收到 `{"error": ...}`）。
+- **重试不跨实例**：调用失败重试只在同实例内换副本；实例内已无可换副本时立即失败，不重复打同一个副本。流式端点本身不重试，实例离线即失败。
+- **缓存按实例隔离**：定向且 `cacheable=true` 时缓存键带实例前缀，避免取到其它实例的结果。
+- **身份来源与开销**：副本的实例身份取自其 admin status 回复的 `instance_id`（Python/Rust 两种运行时都会返回），网关**按需查询并缓存**——未使用定向功能时零额外开销，不定向的请求路径与行为完全不变；首次定向到某实例时会对该类型的新副本各发一次轻量 status 查询（每个副本只查一次，inline 副本无需查询）。副本重启后 id 变化，会重新查询一次。
+- **版本要求**：worker 端需运行带 `instance_id` 上报的运行时（当前 Python/Rust SDK 均满足）；读不出身份的副本会被排除在定向之外（不定向的调用不受影响）。
+
+```bash
+# 等价于把这次请求固定到实例 edge-01 的那个进程
+curl -H 'X-Chongming-Instance: edge-01' http://127.0.0.1:8000/api/v1/demo/state
+
+# MQTT：载荷顶层带 target_instance（网关转发前会摘掉它）
+# topic: chongming/demo/state payload: {"meta":{}, "data":{}, "target_instance":"edge-01"}
+```
+
### inline worker 宿主级领导选举（gunicorn 多 worker 兼容）
inline worker 的生命周期交给**基于分布式锁的宿主级领导选举**（取代“每 gunicorn worker 各自拉起”），key `inline_owner:` 按网关隔离：
diff --git a/src/chongming/app/__init__.py b/src/chongming/app/__init__.py
index e2012d1..21a877e 100644
--- a/src/chongming/app/__init__.py
+++ b/src/chongming/app/__init__.py
@@ -20,10 +20,9 @@ from fastapi.middleware.cors import CORSMiddleware
from chongming_config import get_config
from .core.logger import get_logger
-# from .core.static_files import SVFSStaticFiles
from sqlite_vfs.contrib.fastapi_static import SVFSStaticFiles
from .core import lifespan_setup, call_stats
-from .routes import storage_router, stats_router, worker_admin_router, auth_router
+from .routes import stats_router, worker_admin_router, auth_router
config = get_config()
@@ -311,7 +310,6 @@ if vfs_db_path := config[env].get("file_system", {}).get("path", None):
static_files_handler = SVFSStaticFiles(vfs_db_path=vfs_db_path)
app.mount("/static", static_files_handler, name="static")
-app.include_router(storage_router)
app.include_router(stats_router)
app.include_router(worker_admin_router)
app.include_router(auth_router)
diff --git a/src/chongming/app/core/mqtt_bridge.py b/src/chongming/app/core/mqtt_bridge.py
index e6112c7..25d1f03 100644
--- a/src/chongming/app/core/mqtt_bridge.py
+++ b/src/chongming/app/core/mqtt_bridge.py
@@ -169,6 +169,15 @@ class MQTTBridge:
except orjson.JSONDecodeError:
return
+ # 实例定向控制字段：与 HTTP 的 X-Chongming-Instance 头同义，指定请求发往的
+ # worker 进程实例。必须在下面归一化之前取出——归一化只保留 meta/data 两键，
+ # 之后控制字段就不在载荷里了。
+ target_instance: Optional[str] = None
+ if isinstance(pl, dict):
+ ti = pl.pop("target_instance", None)
+ if isinstance(ti, str) and ti.strip():
+ target_instance = ti.strip()
+
# 信封协议: {"meta": {...}, "data": {...}}
# 兼容非信封载荷（如第三方设备原始报文）: 整包视为业务数据、meta 置空，
# 与 worker 运行时 runtime.py 的容错语义一致（method 默认 GET）——
@@ -194,7 +203,7 @@ class MQTTBridge:
for ct, compiled in self._compiled:
matched = compiled.match(t)
if matched:
- await self._route_custom(ct, matched, pl, t)
+ await self._route_custom(ct, matched, pl, t, target_instance)
return
# 2. 内置接口 chongming/{worker}/{operation}
@@ -204,7 +213,7 @@ class MQTTBridge:
wt, op = parts[1], parts[2]
subj = f"{wt}.{op}"
rt = f"{MQTT_TOPIC_PREFIX}/{wt}/{op}/response"
- await self._route(wt, subj, pl, rt)
+ await self._route(wt, subj, pl, rt, target_instance)
def _fill(self, template: str, matched: re.Match) -> str:
"""用匹配到的通配符值填充模板中的 {1} {2}... 占位符"""
@@ -214,7 +223,8 @@ class MQTTBridge:
template = template.replace("{" + str(i) + "}", g)
return template
- async def _route_custom(self, ct: dict, matched: re.Match, pl: dict, topic: str):
+ async def _route_custom(self, ct: dict, matched: re.Match, pl: dict, topic: str,
+ target_instance: Optional[str] = None):
worker = ct.get("worker", "")
# subject 默认 "."，与内置 <插件>.<操作> 约定一致
subject_tpl = ct.get("subject")
@@ -225,15 +235,22 @@ class MQTTBridge:
# response_topic 默认 "<实际匹配主题>/response"
rt_tpl = ct.get("response_topic")
rt = self._fill(rt_tpl, matched) if rt_tpl else f"{topic}/response"
- await self._route(worker, subject, pl, rt)
+ await self._route(worker, subject, pl, rt, target_instance)
- async def _route(self, wt: str, subj: str, pl: dict, rt: str):
+ async def _route(self, wt: str, subj: str, pl: dict, rt: str,
+ target_instance: Optional[str] = None):
+ """把一次 MQTT 请求转成 worker RPC。
+
+ target_instance 为实例定向目标（来自载荷顶层的 target_instance 控制字段，
+ 已在 _handle 归一化前摘除）；缺省时跨实例随机均衡，行为与以往一致。
+ """
logger.info(f"MQTT -> {subj}")
meta = pl.get("meta") or {}
try:
r = await self._wm.call(worker_type=wt, subject=subj, payload=pl,
timeout=float(meta.get("timeout", 30)),
- cacheable=bool(meta.get("cacheable", False)))
+ cacheable=bool(meta.get("cacheable", False)),
+ instance_id=target_instance or None)
if r is not None:
await self._pub(rt, r)
except RuntimeError as e:
diff --git a/src/chongming/app/core/route_generator.py b/src/chongming/app/core/route_generator.py
index 21924f5..e9b2236 100644
--- a/src/chongming/app/core/route_generator.py
+++ b/src/chongming/app/core/route_generator.py
@@ -24,6 +24,21 @@ from .call_stats import spawn, record_call
logger = get_logger("route_generator")
+# 实例定向请求头：给定后该请求固定发往指定 worker 进程实例（同一实例下的多个副本
+# 之间仍随机均衡），不参与跨实例的随机负载均衡。取值 = 实例身份（外部进程启动参数
+# --instance / CHONGMING_WORKER_INSTANCE；inline 副本为网关自身实例 id）。
+# 未携带该头时行为与以往完全一致（全类型随机均衡）。
+INSTANCE_HEADER = "X-Chongming-Instance"
+
+
+def _instance_from_request(request: Request) -> Optional[str]:
+ """从请求头读取定向实例 id；空串/未携带视为不定向。"""
+ value = request.headers.get(INSTANCE_HEADER)
+ if value:
+ value = value.strip()
+ return value or None
+
+
# 简单类型映射
TYPE_MAP: Dict[str, Any] = {
"float": float,
@@ -348,6 +363,7 @@ def _make_body_endpoint(worker_manager: WorkerManager, rc: RouteConfig, worker_t
payload=payload_bytes,
timeout=timeout,
cacheable=cacheable,
+ instance_id=_instance_from_request(request),
)
duration_ms = (time.perf_counter() - start) * 1000
_spawn_call_record(
@@ -409,6 +425,7 @@ def _make_raw_body_endpoint(worker_manager: WorkerManager, rc: RouteConfig, work
payload=payload,
timeout=timeout,
cacheable=cacheable,
+ instance_id=_instance_from_request(request),
)
duration_ms = (time.perf_counter() - start) * 1000
_spawn_call_record(
@@ -472,6 +489,7 @@ def _make_query_endpoint(worker_manager: WorkerManager, rc: RouteConfig, worker_
payload=payload_bytes,
timeout=timeout,
cacheable=cacheable,
+ instance_id=_instance_from_request(request),
)
duration_ms = (time.perf_counter() - start) * 1000
_spawn_call_record(
@@ -515,6 +533,7 @@ def _make_query_endpoint(worker_manager: WorkerManager, rc: RouteConfig, worker_
payload=payload_bytes,
timeout=timeout,
cacheable=cacheable,
+ instance_id=_instance_from_request(request),
)
duration_ms = (time.perf_counter() - start) * 1000
_spawn_call_record(
@@ -648,6 +667,7 @@ def _make_stream_endpoint(
payload=payload,
timeout=timeout,
idle_timeout=idle_timeout,
+ instance_id=_instance_from_request(request),
)
except RuntimeError as e:
duration_ms = (time.perf_counter() - start) * 1000
diff --git a/src/chongming/app/core/worker_manager.py b/src/chongming/app/core/worker_manager.py
index b763b73..1a3e178 100644
--- a/src/chongming/app/core/worker_manager.py
+++ b/src/chongming/app/core/worker_manager.py
@@ -112,6 +112,15 @@ class WorkerManager:
self._launch_worker_count = launch_worker_count
self._workers_cache: Dict[str, List[str]] = {} # type -> list of worker key_exprs
self._local_workers: Dict[str, List[str]] = {} # type -> list of locally registered workers
+ # ── 实例级定向（把请求固定到某个进程实例而非随机负载均衡）──
+ # 副本经 liveliness 只暴露 worker//，实例身份取自副本 admin status
+ # 的 instance_id（Python/Rust 运行时均返回），故定向索引按需查询并缓存：
+ # _instance_index[type][instance_id] = [worker//, ...]
+ # _instance_unknown[type] = [已查询但身份不可得的副本 key, ...]
+ # 只缓存已查询过的副本；每次按需刷新时整表重建并对新副本补查询、对离线副本剪枝。
+ self._instance_index: Dict[str, Dict[str, List[str]]] = {}
+ self._instance_unknown: Dict[str, List[str]] = {}
+ self._instance_locks: Dict[str, asyncio.Lock] = {}
self._lock = asyncio.Lock()
self._refresh_interval = 15 # seconds
# 当前网关心跳标识：优先环境变量（多实例需唯一，尤其同宿主多网关须显式指定），
@@ -406,23 +415,112 @@ class WorkerManager:
logger.error(f"刷新 worker 列表失败: {e}")
await asyncio.sleep(self._refresh_interval)
- async def get_worker(self, worker_type: str) -> Optional[str]:
- """获取一个可用的 worker 地址（简单随机负载均衡）
+ def _all_workers(self, worker_type: str) -> List[str]:
+ """该类型当前全部候选副本（liveliness 列表优先，启动初期回退本地注册表）。"""
+ workers = list(self._workers_cache.get(worker_type, []))
+ if not workers:
+ workers = list(self._local_workers.get(worker_type, []))
+ return workers
+
+ async def _query_instance_id(self, worker_type: str, worker_key: str) -> Optional[str]:
+ """问单个副本要它的实例身份（admin status 的 instance_id）。
+
+ 复用单副本管理协议 worker///__admin__；查询失败或副本运行旧版
+ 运行时（回复无 instance_id）返回 None，由调用方归入 unknown 组。
+ """
+ wid = worker_key.split("/")[2] if "/" in worker_key else worker_key
+ try:
+ reply = await self._send_admin_cmd(worker_type, wid, "query", timeout=2.0)
+ except Exception as e: # noqa: BLE001 - 单副本查询失败不影响其它副本
+ logger.warning("[instance] %s/%s 身份查询失败: %s", worker_type, wid, e)
+ return None
+ iid = reply.get("instance_id") if isinstance(reply, dict) else None
+ return str(iid) if iid else None
+
+ async def _refresh_instance_map(self, worker_type: str) -> Dict[str, List[str]]:
+ """重建某类型的「实例 → 副本」索引，并按需补查询新副本。
+
+ 只对从未查询过的副本发一次 admin status（本地注册的 inline 副本直接返回
+ 网关自身实例，零查询）；已查询过的副本沿用缓存，因此常规路径是纯内存查询，
+ 仅新上线副本会引入一次额外 RPC。离线副本在重建时被剪枝。
+ """
+ workers = self._all_workers(worker_type)
+ known = self._instance_index.get(worker_type, {})
+ unknown = set(self._instance_unknown.get(worker_type, []))
+ # 反查已有归属：副本 -> 实例（副本 key 唯一，一个副本只属一个实例）
+ owner = {w: iid for iid, ws in known.items() for w in ws}
+
+ index: Dict[str, List[str]] = {}
+ still_unknown: List[str] = []
+ queried = owner.keys() | unknown
+ for w in workers:
+ if w in queried:
+ iid = owner.get(w)
+ else:
+ # 本地注册（inline）副本天然属于本网关实例，无需查询
+ iid = self._gateway_id if w in self._local_workers.get(worker_type, []) else None
+ if iid is None:
+ iid = await self._query_instance_id(worker_type, w)
+ if iid is None:
+ still_unknown.append(w)
+ if iid:
+ index.setdefault(iid, []).append(w)
+
+ self._instance_index[worker_type] = index
+ self._instance_unknown[worker_type] = still_unknown
+ return index
+
+ async def _instance_workers(self, worker_type: str, instance_id: str) -> List[str]:
+ """取某实例下该类型的在线副本 key 列表（无则空表）。"""
+ index = self._instance_index.get(worker_type)
+ if index is None:
+ # 同类型并发请求只让一个跑刷新，其余等结果，避免重复查询同一批副本
+ lock = self._instance_locks.setdefault(worker_type, asyncio.Lock())
+ async with lock:
+ index = self._instance_index.get(worker_type)
+ if index is None:
+ index = await self._refresh_instance_map(worker_type)
+ return index.get(instance_id, [])
+
+ async def get_worker(
+ self, worker_type: str, instance_id: Optional[str] = None
+ ) -> Optional[str]:
+ """获取一个可用的 worker 地址。
+
+ instance_id 为 None 时按简单随机负载均衡挑选（默认，行为不变）；
+ 指定实例时只在该实例的在线副本中挑选，把请求固定到那个进程实例。
+ 实例无在线副本（或该实例在旧版运行时下无法识别身份）返回 None。
读路径无锁：_workers_cache 由 refresh_workers 整表原子替换，
_local_workers 由同步方法修改，单事件循环内读取安全。
"""
- workers = self._workers_cache.get(worker_type, [])
- # 如果缓存为空，回退到本地注册表（适用于启动初期 refresh_workers 尚未执行时）
- if not workers:
- local = self._local_workers.get(worker_type, [])
- if local:
- return random.choice(local)
- return None
- return random.choice(workers)
+ if instance_id:
+ return await self._pick_from_instance(worker_type, instance_id)
+ workers = self._all_workers(worker_type)
+ return random.choice(workers) if workers else None
+
+ async def _pick_from_instance(
+ self, worker_type: str, instance_id: str
+ ) -> Optional[str]:
+ """在指定实例的在线副本中随机挑一个（定向路径，永不跨实例回退）。
+
+ 定向的语义就是"必须打在同一个进程实例上"，因此实例离线时返回 None 让
+ 调用方报错，而不是悄悄换成别的实例——后者会让粘滞状态类的插件跑在错误
+ 副本上，产生难查的数据错乱。
+ """
+ candidates = await self._instance_workers(worker_type, instance_id)
+ if candidates:
+ return random.choice(candidates)
+ logger.warning(
+ "[instance] 目标实例 %s 下无 %s 的在线副本（已识别实例: %s；%d 个副本读不出身份）",
+ instance_id, worker_type, sorted(self._instance_index.get(worker_type, {})),
+ len(self._instance_unknown.get(worker_type, [])),
+ )
+ return None
async def _pick_other_worker(
- self, worker_type: str, exclude: List[str]
+ self, worker_type: str, exclude: List[str],
+ instance_id: Optional[str] = None,
) -> Optional[str]:
"""
选择一个不同于已尝试列表的 worker。
@@ -430,10 +528,17 @@ class WorkerManager:
Args:
worker_type: Worker 类型
exclude: 已尝试（需排除）的 worker key_expr 列表
+ instance_id: 定向实例；给定时只在同实例内换副本，绝不跨实例
Returns:
可用的 worker key_expr，若无其他可用则返回 None
"""
+ if instance_id:
+ candidates = [
+ w for w in await self._instance_workers(worker_type, instance_id)
+ if w not in exclude
+ ]
+ return random.choice(candidates) if candidates else None
workers = self._workers_cache.get(worker_type, [])
candidates = [w for w in workers if w not in exclude]
if candidates:
@@ -455,24 +560,37 @@ class WorkerManager:
return False
return True
- async def _raise_no_worker(self, worker_type: str) -> None:
+ async def _no_worker_message(
+ self, worker_type: str, instance_id: Optional[str] = None
+ ) -> str:
"""
- 无可用 Worker 时的统一诊断：列出当前已知的所有 worker 类型并抛 RuntimeError。
+ 无可用 Worker 时的统一诊断文案。
- 供 call() / call_stream() 共用，保证两类调用错误信息一致。
+ 供 call() / call_stream() 共用，保证两类调用错误信息一致；定向（instance_id）
+ 调用额外列出当前已识别实例，便于区分"实例名写错"与"实例离线"。
"""
all_known = list(self._workers_cache.keys())
local_known = list(self._local_workers.keys())
all_types = sorted(set(all_known + local_known))
- msg = (
- f"类型 '{worker_type}' 没有可用 Worker。"
- f"当前已知的 Worker 类型: {all_types if all_types else '(无)'}。"
- f"请检查: 1) config/workers/config.toml 是否配置了该类型 "
- f"2) 插件初始化是否成功（查看启动日志中的 '加载 Worker 插件失败' 错误）"
- f"3) Worker 进程是否正常运行"
- )
- logger.warning(msg)
- raise RuntimeError(msg)
+ msg = f"类型 '{worker_type}' 没有可用 Worker。"
+ if instance_id:
+ msg = (
+ f"类型 '{worker_type}' 的实例 '{instance_id}' 没有在线副本（定向调用不"
+ f"跨实例回退）。已识别实例: "
+ f"{sorted(self._instance_index.get(worker_type, {})) or '(无)'}。"
+ f"请检查: 1) 该实例 id 是否写错（取值见 GET "
+ f"/admin/workers/{worker_type}/instances 或副本启动时的 --instance）"
+ f" 2) 该实例进程是否在线 3) 该实例的 worker 是否运行旧版运行时"
+ f"（不支持实例身份上报）"
+ )
+ else:
+ msg += (
+ f"当前已知的 Worker 类型: {all_types if all_types else '(无)'}。"
+ f"请检查: 1) config/workers/config.toml 是否配置了该类型 "
+ f"2) 插件初始化是否成功（查看启动日志中的 '加载 Worker 插件失败' 错误）"
+ f"3) Worker 进程是否正常运行"
+ )
+ return msg
async def call_stream(
self,
@@ -481,6 +599,7 @@ class WorkerManager:
payload: Dict[str, Any],
timeout: float = 300.0,
idle_timeout: float = 10.0,
+ instance_id: Optional[str] = None,
) -> AsyncGenerator[bytes, None]:
"""
流式调用：消费 Worker 的多回复流，逐块产出 JSON 字节。
@@ -499,19 +618,21 @@ class WorkerManager:
payload: 请求参数（信封格式，由路由层构造）
timeout: 流总寿命上限（秒），需大于业务最长生成时长
idle_timeout: 空闲超时（秒），超时抛 StreamIdleTimeoutError
+ instance_id: 定向进程实例（None=随机负载均衡）；流本身不可重试，
+ 故实例离线时直接报错，不会中途改派到别的实例
Yields:
bytes: 每个回复块的 JSON 字节
Raises:
- RuntimeError: 无可用 worker
+ RuntimeError: 无可用 worker（含定向实例无在线副本）
StreamIdleTimeoutError: 空闲超时
"""
# 急切解析 worker：无可用时立即抛错，让路由层映射 HTTP 503
# （异步生成器函数体在首次迭代才执行，故这里用普通 async 函数返回内部生成器）
- worker_expr = await self.get_worker(worker_type)
+ worker_expr = await self.get_worker(worker_type, instance_id=instance_id)
if not worker_expr:
- await self._raise_no_worker(worker_type)
+ raise RuntimeError(await self._no_worker_message(worker_type, instance_id))
full_key = f"{worker_expr}/{subject}"
reply_iter = self.session.get(
@@ -602,6 +723,7 @@ class WorkerManager:
timeout: float = 3.0,
retries: int = 1,
cacheable: bool = False,
+ instance_id: Optional[str] = None,
) -> Any:
"""
统一调用入口（dict 语义，MQTT Bridge 等调用方使用）
@@ -613,6 +735,8 @@ class WorkerManager:
timeout: 单次调用超时（秒）
retries: 失败重试次数
cacheable: 是否允许缓存结果（若为 False 则跳过缓存读写）
+ instance_id: 定向进程实例；给定时请求固定发往该实例（不参与随机
+ 负载均衡，重试也只在该实例内换副本），None=默认随机均衡
Returns:
Dict[str, Any]: 调用结果（worker 回复解析后的 dict）
@@ -620,10 +744,18 @@ class WorkerManager:
# cacheable=False 时不计算 cache_key，省一次排序序列化
cache_key = None
if cacheable:
- cache_key = f"{worker_type}:{subject}:{orjson.dumps(payload, option=orjson.OPT_SORT_KEYS).decode()}"
+ # 定向调用的缓存键含实例名：定向通常用于读取该实例的本地状态
+ # （本地库/设备连接），共用缓存会拿到其它实例的结果
+ cache_key = (
+ f"{worker_type}:{subject}"
+ f":{orjson.dumps(payload, option=orjson.OPT_SORT_KEYS).decode()}"
+ )
+ if instance_id:
+ cache_key = f"{instance_id}@{cache_key}"
reply_bytes = await self._call_impl(
worker_type, subject, orjson.dumps(payload),
timeout=timeout, retries=retries, cacheable=cacheable, cache_key=cache_key,
+ instance_id=instance_id,
)
return orjson.loads(reply_bytes) if reply_bytes else {}
@@ -635,6 +767,7 @@ class WorkerManager:
timeout: float = 3.0,
retries: int = 1,
cacheable: bool = False,
+ instance_id: Optional[str] = None,
) -> bytes:
"""
统一调用入口（bytes 语义，HTTP 端点透传用）：返回 worker 回复的原始字节。
@@ -652,6 +785,7 @@ class WorkerManager:
timeout: 单次调用超时（秒）
retries: 失败重试次数
cacheable: 是否允许缓存结果（缓存原始字节）
+ instance_id: 定向进程实例（见 call()）；None=默认随机均衡
Returns:
bytes: worker 回复的原始字节（空回复兜底 b"{}"，与 call() 的 {} 语义一致）
@@ -660,9 +794,12 @@ class WorkerManager:
cache_key = None
if cacheable:
cache_key = f"{worker_type}:{subject}:{hashlib.sha256(payload).hexdigest()}"
+ if instance_id:
+ cache_key = f"{instance_id}@{cache_key}"
return await self._call_impl(
worker_type, subject, payload,
timeout=timeout, retries=retries, cacheable=cacheable, cache_key=cache_key,
+ instance_id=instance_id,
)
async def _call_impl(
@@ -674,11 +811,13 @@ class WorkerManager:
retries: int = 1,
cacheable: bool = False,
cache_key: Optional[str] = None,
+ instance_id: Optional[str] = None,
) -> bytes:
"""
- 调用实现：缓存 > 负载均衡 > 超时重试，返回回复的原始字节。
+ 调用实现：缓存 > 选副本（随机均衡/实例定向）> 超时重试，返回回复的原始字节。
call() / call_raw() 共用本实现，仅入参出参形态不同（dict ↔ bytes）。
+ instance_id 给定时选副本与重试都被约束在该实例内（定向语义，不跨实例回退）。
"""
# 1. 缓存检查（仅在 cacheable=True 时检查）
if cacheable and cache_key is not None:
@@ -695,16 +834,39 @@ class WorkerManager:
logger.debug(f"命中共享缓存: {cache_key}")
return disk_val
- # 2. 获取可用 worker
- worker_expr = await self.get_worker(worker_type)
+ # 2. 获取可用 worker（instance_id 给定时固定到该实例，否则随机均衡）
+ worker_expr = await self.get_worker(worker_type, instance_id=instance_id)
if not worker_expr:
- await self._raise_no_worker(worker_type)
+ raise RuntimeError(await self._no_worker_message(worker_type, instance_id))
full_key = f"{worker_expr}/{subject}"
last_error = None
tried_workers: List[str] = []
+ async def _switch_worker(why: str) -> bool:
+ """换一个副本重试；返回是否值得继续（定向调用只在同实例内换副本）。
+
+ 换完更新闭包外层的 worker_expr / full_key。定向实例内已无未试副本时
+ 返回 False —— 继续循环只会重复打同一个坏副本，白等一整轮超时。
+ """
+ nonlocal worker_expr, full_key, last_error
+ new_worker = await self._pick_other_worker(
+ worker_type, tried_workers, instance_id=instance_id
+ )
+ if new_worker:
+ if new_worker != worker_expr:
+ logger.info(f"{why}切换 Worker: {worker_expr} -> {new_worker}")
+ worker_expr = new_worker
+ full_key = f"{worker_expr}/{subject}"
+ return True
+ # 没有任何未试过的副本可换：继续循环只会重复打同一个副本（若它已死，
+ # 白等一整轮超时；若它已回业务错误，结果必然相同），直接结束重试。
+ # 保留具体失败原因（last_error 已由调用方按场景写入），便于定位。
+ scope = f"实例 '{instance_id}' 内" if instance_id else ""
+ last_error = f"{scope}已无其它未试副本可换（{why}）：{last_error}"
+ return False
+
for attempt in range(retries + 1):
# 记录已尝试的 worker
if worker_expr not in tried_workers:
@@ -735,11 +897,8 @@ class WorkerManager:
f"Worker {worker_expr} 无回复，尝试重试 {attempt+1}/{retries+1}"
)
last_error = f"Worker {worker_expr} 无回复"
- # 换一个 worker 重试
- new_worker = await self._pick_other_worker(worker_type, tried_workers)
- if new_worker:
- worker_expr = new_worker
- full_key = f"{worker_expr}/{subject}"
+ if not await _switch_worker("无回复"):
+ break
continue
reply = first_reply
@@ -760,11 +919,8 @@ class WorkerManager:
logger.warning(f"Worker 返回错误: {error_msg} (尝试 {attempt+1}/{retries+1})")
last_error = f"Worker {worker_expr} 返回错误: {error_msg}"
# 错误回复（含 Zenoh 超时）也换一个 worker 重试
- new_worker = await self._pick_other_worker(worker_type, tried_workers)
- if new_worker:
- logger.info(f"错误后切换 Worker: {worker_expr} -> {new_worker}")
- worker_expr = new_worker
- full_key = f"{worker_expr}/{subject}"
+ if not await _switch_worker("错误后"):
+ break
continue # 重试
except asyncio.TimeoutError:
logger.warning(
@@ -772,11 +928,8 @@ class WorkerManager:
)
last_error = f"Worker {worker_expr} 超时 (>{timeout}s)"
# 超时后换一个 worker 重试，避免打到仍在处理中的同一个 worker
- new_worker = await self._pick_other_worker(worker_type, tried_workers)
- if new_worker:
- logger.info(f"超时后切换 Worker: {worker_expr} -> {new_worker}")
- worker_expr = new_worker
- full_key = f"{worker_expr}/{subject}"
+ if not await _switch_worker("超时后"):
+ break
continue
except Exception as e:
logger.error(f"调用 worker 异常: {e}")
@@ -784,7 +937,7 @@ class WorkerManager:
raise RuntimeError(
f"Worker '{worker_type}' 调用失败 (已尝试 {len(tried_workers)} 个 Worker, "
- f"共 {retries + 1} 次, timeout={timeout}s): {last_error}"
+ f"实际尝试 {attempt + 1} 次/上限 {retries + 1} 次, timeout={timeout}s): {last_error}"
)
# ------------------------------------------------------------------
diff --git a/src/chongming/app/routes/__init__.py b/src/chongming/app/routes/__init__.py
index 8599271..194527a 100644
--- a/src/chongming/app/routes/__init__.py
+++ b/src/chongming/app/routes/__init__.py
@@ -1,6 +1,5 @@
-from .storage import router as storage_router
from .stats import router as stats_router
from .worker_admin import router as worker_admin_router
from .auth import router as auth_router
-__all__ = ["storage_router", "stats_router", "worker_admin_router", "auth_router"]
\ No newline at end of file
+__all__ = ["stats_router", "worker_admin_router", "auth_router"]
\ No newline at end of file
diff --git a/src/chongming/app/routes/storage.py b/src/chongming/app/routes/storage.py
deleted file mode 100644
index 7a85fee..0000000
--- a/src/chongming/app/routes/storage.py
+++ /dev/null
@@ -1,53 +0,0 @@
-# src/chongming/app/routes/storage.py
-import os
-import uuid
-import urllib.parse
-import aiofiles
-
-from fastapi import APIRouter, UploadFile, File, Form, HTTPException, Request
-from fastapi.responses import FileResponse
-
-
-router = APIRouter(prefix="/api/v1/storage", tags=["Storage"])
-
-
-@router.post("/upload", summary="上传文件")
-async def upload_file(
- request: Request,
- file: UploadFile = File(...),
- worker_type: str = Form(...),
-):
- """上传文件到本地存储"""
- upload_root = request.app.state.upload_root
- object_key = f"{worker_type}/{uuid.uuid4()}/{file.filename}"
- dest = os.path.join(upload_root, object_key)
- os.makedirs(os.path.dirname(dest), exist_ok=True)
-
- async with aiofiles.open(dest, "wb") as afp:
- while chunk := await file.read(1024 * 1024):
- await afp.write(chunk)
-
- file_size = os.path.getsize(dest)
- return {
- "file_key": object_key,
- "bucket": "local",
- "filename": file.filename,
- "content_type": file.content_type,
- "size": file_size,
- }
-
-@router.get("/download/{file_key:path}")
-async def download_file(request: Request, file_key: str):
- """从本地存储下载文件"""
- upload_root = request.app.state.upload_root
- path = os.path.join(upload_root, file_key)
- if not os.path.isfile(path):
- raise HTTPException(404, "文件不存在")
-
- raw_filename = file_key.split('/')[-1]
- encoded = urllib.parse.quote(raw_filename, safe='')
- return FileResponse(
- path,
- filename=raw_filename,
- headers={"Content-Disposition": f"attachment; filename*=UTF-8''{encoded}"},
- )
diff --git a/test.png b/test.png
deleted file mode 100644
index 9e9527beadefad6103f0506703eb6550155c09cd..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 341696
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