sycommon-python-lib 0.2.7a47__tar.gz → 0.2.7a48__tar.gz

{sycommon_python_lib-0.2.7a47 → sycommon_python_lib-0.2.7a48}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sycommon-python-lib
-Version: 0.2.7a47
+Version: 0.2.7a48
 Summary: Add your description here
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown

{sycommon_python_lib-0.2.7a47 → sycommon_python_lib-0.2.7a48}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sycommon-python-lib"
-version = "0.2.7a47"
+version = "0.2.7a48"
 description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.11"

sycommon_python_lib-0.2.7a48/src/sycommon/agent/middleware/sitecustomize.py

@@ -0,0 +1,300 @@
+"""技能接口白名单客户端注入脚本（部署到沙箱 site-packages）。
+
+Python 解释器启动时（未传 -S）自动 import 本模块。它负责 Python HTTP 库的
+请求拦截：
+
+  1. 读环境变量 SKILL_API_WHITELIST（JSON）。无此 env → 不管控（全放行，fail-open）。
+  2. monkeypatch urllib / httpx / requests / aiohttp，发请求前做 path 级前缀匹配，
+     未命中抛 PermissionError（LLM 能看到清晰错误）。
+
+  ⚠️ shell 命令（curl/wget 等）的拦截【不】在本文件处理——sitecustomize 只在
+     `python` 启动时执行，纯 shell 命令不会触发它。shell 拦截由主进程中间件把
+     curl/wget 包装函数【内联】到每条 execute 命令前缀实现（见 skill_api_whitelist.py）。
+
+URL 匹配核心逻辑复用同目录 skill_wl_check.py。
+
+另外提供【独立于白名单】的 header 注入：当环境变量 SYT_API_AUTHZ 非空时，
+对 host 命中 SYT_BASE_URL 的请求自动补 X-Sy-Api-Authz 头。这是云平台网关的
+鉴权要求，对所有沙箱技能请求生效（不门控白名单），由中间件无条件 export
+SYT_API_AUTHZ + 推送本 sitecustomize 触发。
+
+注意：本模块在沙箱子进程里运行，不依赖主进程内存。配置全部来自环境变量。
+"""
+
+import json
+import os
+import sys
+from urllib.parse import urlparse
+
+# SKILL_API_WHITELIST 存在即「启用管控」；allowlist 为空时「全拦截」。
+_ENABLED = "SKILL_API_WHITELIST" in os.environ
+
+# 把沙箱 site-packages 里存放本模块的目录加入 sys.path，以便 import skill_wl_check。
+_HERE = os.path.dirname(os.path.abspath(__file__))
+if _HERE not in sys.path:
+    sys.path.insert(0, _HERE)
+
+
+def _load_check():
+    """加载同目录 skill_wl_check，返回其 match 函数；失败返回 None。"""
+    try:
+        import skill_wl_check  # type: ignore
+        return skill_wl_check
+    except Exception as e:  # pragma: no cover
+        sys.stderr.write("[sitecustomize] 加载 skill_wl_check 失败，白名单禁用: %s\n" % e)
+        return None
+
+
+def _patch_urllib(match):
+    import urllib.request
+
+    _orig = urllib.request.urlopen
+
+    def _urlopen(url, *args, **kwargs):
+        actual = url.full_url if isinstance(url, urllib.request.Request) else url
+        if actual and not match(str(actual)):
+            raise PermissionError(
+                "[SkillApiWhitelist] 拦截: URL 不在白名单内 (urlopen, %s)" % actual)
+        return _orig(url, *args, **kwargs)
+
+    urllib.request.urlopen = _urlopen
+
+
+def _patch_httpx(match):
+    try:
+        import httpx
+    except ImportError:
+        return
+
+    _orig_sync = httpx.Client.send
+
+    def _send(self, request, **kwargs):
+        if not match(str(request.url)):
+            raise PermissionError(
+                "[SkillApiWhitelist] 拦截: URL 不在白名单内 (httpx, %s)" % request.url)
+        return _orig_sync(self, request, **kwargs)
+
+    httpx.Client.send = _send
+
+    if hasattr(httpx, "AsyncClient"):
+        _orig_async = httpx.AsyncClient.send
+
+        async def _asend(self, request, **kwargs):
+            if not match(str(request.url)):
+                raise PermissionError(
+                    "[SkillApiWhitelist] 拦截: URL 不在白名单内 (httpx.async, %s)" % request.url)
+            return await _orig_async(self, request, **kwargs)
+
+        httpx.AsyncClient.send = _asend
+
+
+def _patch_requests(match):
+    try:
+        import requests
+    except ImportError:
+        return
+
+    _orig = requests.Session.request
+
+    def _request(self, method, url, *args, **kwargs):
+        if not match(str(url)):
+            raise PermissionError(
+                "[SkillApiWhitelist] 拦截: URL 不在白名单内 (requests %s, %s)"
+                % (method.upper(), url))
+        return _orig(self, method, url, *args, **kwargs)
+
+    requests.Session.request = _request
+
+
+def _patch_aiohttp(match):
+    try:
+        import aiohttp
+    except ImportError:
+        return
+    if not hasattr(aiohttp.ClientSession, "_request"):
+        return
+
+    _orig = aiohttp.ClientSession._request
+
+    async def _request(self, method, str_or_url, **kwargs):
+        if not match(str(str_or_url)):
+            raise PermissionError(
+                "[SkillApiWhitelist] 拦截: URL 不在白名单内 (aiohttp %s, %s)"
+                % (method, str_or_url))
+        return await _orig(self, method, str_or_url, **kwargs)
+
+    aiohttp.ClientSession._request = _request
+
+
+# =============== header 注入（独立于白名单）===============
+# 云平台网关要求请求带 X-Sy-Api-Authz 头。仅当 host 命中 SYT_BASE_URL 的 host
+# 才补该头，其它域名（内网 OCR / 企微 / 合同比对内网 / MCP 后端等）不注入。
+# 门控：环境变量 SYT_API_AUTHZ 非空。调用方已显式设过同名头则不覆盖。
+
+_AUTHZ_HEADER = "X-Sy-Api-Authz"
+
+
+def _syt_host():
+    """解析 SYT_BASE_URL 的 host（小写）。失败返回 None。"""
+    base = os.environ.get("SYT_BASE_URL", "").strip()
+    if not base:
+        return None
+    try:
+        return (urlparse(base).hostname or "").lower() or None
+    except Exception:
+        return None
+
+
+def _host_matches_syt(url) -> bool:
+    """请求 URL 的 host 是否等于 SYT_BASE_URL 的 host。"""
+    host = _syt_host()
+    if not host:
+        return False
+    try:
+        return (urlparse(str(url)).hostname or "").lower() == host
+    except Exception:
+        return False
+
+
+def _patch_urllib_hdr():
+    import urllib.request
+
+    _orig = urllib.request.urlopen
+
+    def _urlopen(url, *args, **kwargs):
+        # 只能给 Request 对象补头；裸 str URL 在 urlopen 层无 headers 概念，跳过
+        if isinstance(url, urllib.request.Request) and _host_matches_syt(url.full_url):
+            url.add_header(_AUTHZ_HEADER, os.environ["SYT_API_AUTHZ"])
+        return _orig(url, *args, **kwargs)
+
+    urllib.request.urlopen = _urlopen
+
+
+def _patch_requests_hdr():
+    try:
+        import requests
+    except ImportError:
+        return
+
+    _orig = requests.Session.request
+
+    def _request(self, method, url, *args, **kwargs):
+        if _host_matches_syt(url):
+            headers = kwargs.get("headers")
+            if headers is None:
+                headers = {}
+            if isinstance(headers, dict):
+                if _AUTHZ_HEADER not in headers:
+                    headers[_AUTHZ_HEADER] = os.environ["SYT_API_AUTHZ"]
+                kwargs["headers"] = headers
+            else:
+                # list / 其它形态：保守起见交给底层，避免破坏既有结构
+                pass
+        return _orig(self, method, url, *args, **kwargs)
+
+    requests.Session.request = _request
+
+
+def _patch_httpx_hdr():
+    try:
+        import httpx
+    except ImportError:
+        return
+
+    def _apply(request):
+        if request is not None and _host_matches_syt(request.url):
+            request.headers.setdefault(_AUTHZ_HEADER, os.environ["SYT_API_AUTHZ"])
+
+    _orig_sync = httpx.Client.send
+
+    def _send(self, request, **kwargs):
+        _apply(request)
+        return _orig_sync(self, request, **kwargs)
+
+    httpx.Client.send = _send
+
+    if hasattr(httpx, "AsyncClient"):
+        _orig_async = httpx.AsyncClient.send
+
+        async def _asend(self, request, **kwargs):
+            _apply(request)
+            return await _orig_async(self, request, **kwargs)
+
+        httpx.AsyncClient.send = _asend
+
+
+def _patch_aiohttp_hdr():
+    try:
+        import aiohttp
+    except ImportError:
+        return
+    if not hasattr(aiohttp.ClientSession, "_request"):
+        return
+
+    _orig = aiohttp.ClientSession._request
+
+    async def _request(self, method, str_or_url, **kwargs):
+        if _host_matches_syt(str_or_url):
+            headers = kwargs.get("headers")
+            if isinstance(headers, dict):
+                if _AUTHZ_HEADER not in headers:
+                    headers[_AUTHZ_HEADER] = os.environ["SYT_API_AUTHZ"]
+            elif headers is None:
+                kwargs["headers"] = {_AUTHZ_HEADER: os.environ["SYT_API_AUTHZ"]}
+            else:
+                # list / CIMultiDict 等其它形态：跳过，避免破坏结构
+                pass
+        return await _orig(self, method, str_or_url, **kwargs)
+
+    aiohttp.ClientSession._request = _request
+
+
+def _install_header_injection():
+    """装 header 注入 patch（独立于白名单）。
+
+    门控：环境变量 SYT_API_AUTHZ 非空。任一库 import 失败都不阻断。
+    """
+    val = os.environ.get("SYT_API_AUTHZ", "").strip()
+    if not val:
+        return
+    if not _syt_host():
+        sys.stderr.write(
+            "[sitecustomize] SYT_API_AUTHZ 已设置但 SYT_BASE_URL 无法解析 host，"
+            "跳过 header 注入\n")
+        return
+    _patch_urllib_hdr()
+    _patch_requests_hdr()
+    _patch_httpx_hdr()
+    _patch_aiohttp_hdr()
+
+
+def _install():
+    if not _ENABLED:
+        return
+    check = _load_check()
+    if check is None:
+        return
+    # allowlist 为空（明确禁止）时也走校验——match 必然 False，从而全拦截。
+    match = check.match
+    _patch_urllib(match)
+    _patch_httpx(match)
+    _patch_requests(match)
+    _patch_aiohttp(match)
+
+
+# 保留解析结果（供排查）
+try:
+    _WHITELIST_RAW = json.loads(os.environ.get("SKILL_API_WHITELIST", "{}"))
+except Exception:
+    _WHITELIST_RAW = {}
+
+try:
+    _install()
+except Exception as _e:  # 任何 patch 失败都不能阻断进程启动
+    sys.stderr.write("[sitecustomize] 白名单安装失败（fail-open）: %s\n" % _e)
+
+# header 注入独立于白名单，单独 try/except，互不影响
+try:
+    _install_header_injection()
+except Exception as _e:
+    sys.stderr.write("[sitecustomize] header 注入安装失败（fail-open）: %s\n" % _e)

{sycommon_python_lib-0.2.7a47 → sycommon_python_lib-0.2.7a48}/src/sycommon/agent/middleware/skill_api_whitelist.py

@@ -26,6 +26,7 @@ import os
 import re
 import shlex
 from typing import Optional
+from urllib.parse import urlparse
 
 from langchain.agents.middleware.types import AgentMiddleware
 from langchain_core.messages import ToolMessage
@@ -35,12 +36,17 @@ from sycommon.logging.kafka_log import SYLogger
 
 # 命令路径形如  skills/system/sy-oa-skill/workflow-todo/scripts/x.py
 #               skills/user/sy-oa-skill/SKILL.md
-# 拆为 system/user/shengye-platform 多层后,顶层段是 system|user|shengye-platform,
-# 需跳过它取【第二段】作域级技能名(如 sy-oa-skill / oa),配合 SkillApiWhitelist
-# 按顶级域配置。(?<![\w]) 否定左查找:要求 skills 前不是单词字符,避免误匹配 myskills/。
+# _SKILL_TOP_RE：白名单配置提取用——限定 system|user|shengye-platform 三层后取第二段
+# 作域级技能名(如 sy-oa-skill / oa)，配合 SkillApiWhitelist 按顶级域配置。
+# (?<![\w]) 否定左查找:要求 skills 前不是单词字符,避免误匹配 myskills/。
 _SKILL_TOP_RE = re.compile(
     r'(?<![\w])skills/(?:system|user|shengye-platform)/([A-Za-z0-9_\-]+)(?:/|$)')
 
+# _SKILL_ANY_RE：技能命令判定用（宽松）——匹配任意 skills/<...>/ 前缀。
+# 用于 header 注入等对所有技能命令（含用户自行拷贝到非 system 目录的技能）生效的能力，
+# 与白名单配置是否启用解耦。同样 (?<![\w]) 避免误匹配 myskills/。
+_SKILL_ANY_RE = re.compile(r'(?<![\w])skills/[A-Za-z0-9_\-]+(?:/|$)')
+
 # BASE_URL 占位符 ${VAR}
 _PLACEHOLDER_RE = re.compile(r'\$\{([A-Z_][A-Z0-9_]*)\}')
 
@@ -167,26 +173,51 @@ def _load_resource_bytes(filename: str) -> bytes:
             f"读取注入脚本 {filename} 失败，请确认已随包安装(package_data): {e}") from e
 
 
-def _build_shell_guard() -> str:
+def _build_shell_guard(with_whitelist: bool = False,
+                       with_header: bool = False) -> str:
     """生成内联到命令前缀的 curl/wget 包装函数（shell）。
 
-    在 SKILL_API_WHITELIST 已 export 的命令里生效：调用 curl/wget 前先抽取
-    参数里首个 http(s) URL，用沙箱 python3 调 skill_wl_check.match 校验，
-    未命中则 return 1 拦截。skill_wl_check 与 sitecustomize 同处 site-packages，
-    python3 启动时 sitecustomize 会 import 它并把该目录加入 sys.path。
+    抽取参数里【最后一个】 http(s) URL 到 _u，按需承担两类职责（可同时启用，
+    先白名单校验、再注入 header）：
+      - with_whitelist：用沙箱 python3 调 skill_wl_check.match 校验 _u，未命中 return 1。
+      - with_header：_u 的 host 命中 $__SYT_HOST__ 时追加 -H "X-Sy-Api-Authz:
+        $SYT_API_AUTHZ"（原参数已含同名头则不重复加）。
 
-    覆盖 curl / wget；其它 shell 出网方式(nc/裸 /dev/tcp 等)不覆盖。
+    skill_wl_check 与 sitecustomize 同处 site-packages，python3 启动时 sitecustomize
+    会 import 它并把该目录加入 sys.path。覆盖 curl / wget；其它 shell 出网方式
+    (nc/裸 /dev/tcp 等)不覆盖。
     """
-    check_cmd = (
-        'python3 -c \'import skill_wl_check,sys; '
-        'sys.exit(0 if skill_wl_check.match(sys.argv[1]) else 1)\' "$_u"'
-    )
-    # 单个命令的函数体模板：抽取 URL → 校验 → 通过则 command <CMD> "$@"
+    wl_block = ""
+    if with_whitelist:
+        check_cmd = (
+            'python3 -c \'import skill_wl_check,sys; '
+            'sys.exit(0 if skill_wl_check.match(sys.argv[1]) else 1)\' "$_u"'
+        )
+        wl_block = (
+            f'if [ -n "$_u" ] && ! {check_cmd}; then '
+            'echo "[SkillApiWhitelist] 拦截 shell 请求: $_u" 1>&2; return 1; fi; '
+        )
+    hdr_block = ""
+    if with_header:
+        # 从 _u 取 host（小写）：剥 scheme/path/query/fragment/userinfo/port
+        hdr_block = (
+            'if [ -n "$_u" ] && [ -n "$__SYT_HOST__" ] && [ -n "$SYT_API_AUTHZ" ]; then '
+            '_h="${_u#*://}"; _h="${_h%%/*}"; _h="${_h%%\\?*}"; _h="${_h%%#*}"; '
+            '_h="${_h##*@}"; _h="${_h%%:*}"; '
+            'case "$(printf "%s" "$_h" | tr "A-Z" "a-z")" in '
+            '"$__SYT_HOST__") '
+            'case " $* " in *"X-Sy-Api-Authz"*) :;; *) '
+            'set -- "$@" -H "X-Sy-Api-Authz: $SYT_API_AUTHZ";; '
+            'esac;; '
+            'esac; '
+            'fi; '
+        )
+    if not wl_block and not hdr_block:
+        return ""
     body = (
-        '() { local _u; for _a in "$@"; do '
+        '() { local _u _a _h; for _a in "$@"; do '
         'case "$_a" in http://*|https://*) _u="$_a";; esac; done; '
-        f'if [ -n "$_u" ] && ! {check_cmd}; then '
-        'echo "[SkillApiWhitelist] 拦截 shell 请求: $_u" 1>&2; return 1; fi; '
+        + wl_block + hdr_block +
         'command {CMD} "$@"; };'
     )
     guard = "curl" + body.replace("{CMD}", "curl") + " wget" + body.replace("{CMD}", "wget")
@@ -329,42 +360,69 @@ class SkillApiWhitelistMiddleware(AgentMiddleware):
         if not command:
             return await handler(request)
 
-        skill_name = self._extract_skill_name(command)
-        if skill_name is None:
-            # 非技能命令（无 skills/<顶级技能>/）→ 不管控
+        # 技能命令判定（宽松）：任意 skills/.../ 前缀即算（含用户拷贝到非 system
+        # 目录的技能）。header 注入等对所有技能命令生效的能力以此为门控。
+        if not _SKILL_ANY_RE.search(command):
+            # 非技能命令 → 不注入任何前缀
             return await handler(request)
 
-        # 延迟导入避免模块加载期循环依赖
+        # 白名单配置提取（限定三层后取第二段）
+        skill_name = self._extract_skill_name(command)
         from sycommon.config.SkillApiWhitelistConfig import SkillApiWhitelistConfig
-        cfg = SkillApiWhitelistConfig.from_config(skill_name)
-        if cfg is None or not cfg.enabled:
-            # 未配置 / 禁用 → 全放行（向后兼容）
-            return await handler(request)
+        cfg = (SkillApiWhitelistConfig.from_config(skill_name)
+               if skill_name is not None else None)
+        whitelist_on = bool(cfg and cfg.enabled)
 
         # 主进程解析占位符 ${VAR}（数据源：os.environ + sandbox env 字典）
         env_lookup = self._env_lookup()
         resolved = []
-        for pat in cfg.allowlist:
-            if "${" in pat:
-                expanded = _resolve_placeholders(pat, env_lookup)
-                if expanded:
-                    resolved.append(expanded)
-            else:
-                resolved.append(pat)
-
-        # 推送注入脚本（惰性，每后端实例一次）
-        await self._ensure_sitecustomize()
-
-        # 序列化白名单 + PYTHONPATH(shell 启动 python 时自动 import sitecustomize)
-        # + shell guard(curl/wget 拦截) + export SKILL_API_WHITELIST
-        payload = json.dumps({"skill": skill_name, "allowlist": resolved},
-                             ensure_ascii=False)
-        guard = _build_shell_guard()
-        prefix_parts = [
-            f"export SKILL_API_WHITELIST={shlex.quote(payload)}",
-            f'export PYTHONPATH="{_WL_DIR}:$PYTHONPATH"',
-            guard,
-        ]
+        if whitelist_on:
+            for pat in cfg.allowlist:
+                if "${" in pat:
+                    expanded = _resolve_placeholders(pat, env_lookup)
+                    if expanded:
+                        resolved.append(expanded)
+                else:
+                    resolved.append(pat)
+
+        # header 注入所需：SYT_API_AUTHZ（缺则不注入）+ SYT_BASE_URL 的 host
+        syt_authz = env_lookup("SYT_API_AUTHZ")
+        header_on = bool(syt_authz and syt_authz.strip())
+        syt_host = ""
+        if header_on:
+            syt_base = env_lookup("SYT_BASE_URL") or ""
+            try:
+                syt_host = (urlparse(syt_base).hostname or "").lower()
+            except Exception:
+                syt_host = ""
+            header_on = bool(syt_host)
+
+        # 推送注入脚本（惰性，每后端实例一次）。
+        # 只要【白名单 或 header 注入】任一启用就要推 .wl（sitecustomize）。
+        if whitelist_on or header_on:
+            await self._ensure_sitecustomize()
+
+        # 组装命令前缀
+        prefix_parts: list[str] = []
+        if whitelist_on:
+            payload = json.dumps({"skill": skill_name, "allowlist": resolved},
+                                 ensure_ascii=False)
+            prefix_parts.append(f"export SKILL_API_WHITELIST={shlex.quote(payload)}")
+        if header_on:
+            prefix_parts.append(
+                f"export SYT_API_AUTHZ={shlex.quote(syt_authz)}")
+            prefix_parts.append(f'export __SYT_HOST__={shlex.quote(syt_host)}')
+        if whitelist_on or header_on:
+            # PYTHONPATH(shell 启动 python 时自动 import sitecustomize)
+            prefix_parts.append(f'export PYTHONPATH="{_WL_DIR}:$PYTHONPATH"')
+            guard = _build_shell_guard(with_whitelist=whitelist_on,
+                                       with_header=header_on)
+            if guard:
+                prefix_parts.append(guard)
+
+        if not prefix_parts:
+            return await handler(request)
+
         # 每个 part 之间用 '; ' 分隔（而非空格）—— export 语句之间、函数定义与后续命令
         # 之间都需要语句分隔符；末尾留一个 ';' 与原命令隔开。
         prefix = "; ".join(prefix_parts) + "; "
@@ -372,5 +430,11 @@ class SkillApiWhitelistMiddleware(AgentMiddleware):
         new_command = prefix + command
         new_args = {**args, "command": new_command} if isinstance(args, dict) else args
         new_tc = {**tc, "args": new_args}
-        SYLogger.info("[Whitelist] 注入子技能 %s 白名单(%d 条)", skill_name, len(resolved))
+        tags = []
+        if whitelist_on:
+            tags.append(f"白名单({len(resolved)}条)")
+        if header_on:
+            tags.append("Authz头注入")
+        SYLogger.info("[Whitelist] 技能 %s 注入: %s", skill_name or "<user>",
+                      "+".join(tags) if tags else "(空)")
         return await handler(request.override(tool_call=new_tc))

{sycommon_python_lib-0.2.7a47 → sycommon_python_lib-0.2.7a48}/src/sycommon/rabbitmq/rabbitmq_client.py

@@ -1,7 +1,7 @@
 import asyncio
 import inspect
 import json
-from typing import Optional, Callable, Coroutine, Dict, Any, Union
+from typing import Optional, Callable, Dict, Any, Union
 from aio_pika import Message, DeliveryMode, ExchangeType
 from aio_pika.abc import (
     AbstractChannel,
@@ -165,12 +165,14 @@ class RabbitMQClient:
                 f"开始迁移队列 '{self.queue_name}'，添加 x-max-priority={self.max_priority}")
 
             # 删除旧队列（空且无消费者，安全）
+            # if_unused/if_empty=True 兜底：探测到删除之间若有消息进入或消费者上线，
+            # 服务端会拒绝删除（406）而不是静默丢消息，消除 TOCTOU 窗口。
             channel, _ = await self.connection_pool.acquire_channel()
             try:
                 await channel.queue_delete(
                     queue_name=self.queue_name,
-                    if_unused=False,
-                    if_empty=False,
+                    if_unused=True,
+                    if_empty=True,
                 )
             finally:
                 await channel.close()
@@ -336,12 +338,46 @@ class RabbitMQClient:
             if was_consuming and self._message_handler:
                 if self._queue:
                     logger.info("🔄 检测到重连前处于消费状态，尝试自动恢复消费...")
+                    # 复用旧 consumer_tag（哨兵 "__recovering__" 除外）：
+                    # 避免 aio-pika RobustQueue._consumers 里残留旧 tag 导致
+                    # aiormq DuplicateConsumerTag，或产生双消费者/幽灵回调。
+                    recover_tag = (
+                        self._consumer_tag
+                        if self._consumer_tag and self._consumer_tag != "__recovering__"
+                        else None
+                    )
                     try:
-                        self._consumer_tag = await self.start_consuming()
+                        self._consumer_tag = await self.start_consuming(
+                            consumer_tag=recover_tag)
                         logger.info(f"✅ 消费已自动恢复: {self._consumer_tag}")
                     except Exception as e:
+                        # 恢复失败必须置 None（而不是留哨兵），
+                        # 否则监控 health check(_consumer_tag is None)永远失效，
+                        # 消费者真丢了却显示健康。
+                        self._consumer_tag = None
                         logger.error(f"❌ 自动恢复消费失败: {e}")
+
+                    # 恢复后要同步监控侧的 _consumer_tags,否则:
+                    #  - consume_task 已在跑但 _consumer_tags 无记录(此前 finally 已清)
+                    #  - 监控 _restart_consumer_if_needed 会误判"假死"把健康的
+                    #    consume_task cancel 重启,造成不必要的消费者抖动。
+                    # 用 self.queue_name 反查 client_name(监控以 client_name 为键)。
+                    if self._consumer_tag:
+                        try:
+                            from sycommon.rabbitmq.rabbitmq_service_consumer_manager import (
+                                RabbitMQConsumerManager,
+                            )
+                            for name, mgr_client in getattr(
+                                    RabbitMQConsumerManager, "_clients", {}).items():
+                                if mgr_client is self:
+                                    RabbitMQConsumerManager._consumer_tags[name] = \
+                                        self._consumer_tag
+                                    break
+                        except Exception as sync_err:
+                            logger.debug(f"同步监控 consumer_tags 失败(忽略): {sync_err}")
                 else:
+                    # 队列对象无效，置 None 让监控能检测到并兜底重启
+                    self._consumer_tag = None
                     logger.warning("⚠️ 队列对象无效，暂缓恢复消费，等待监控器兜底")
 
     async def set_message_handler(self, handler: Callable) -> None:
@@ -403,7 +439,7 @@ class RabbitMQClient:
             except Exception as e:
                 logger.error(f"异步任务执行失败: {e}", exc_info=True)
 
-    async def start_consuming(self) -> Optional[ConsumerTag]:
+    async def start_consuming(self, consumer_tag: Optional[ConsumerTag] = None) -> Optional[ConsumerTag]:
         if self._closed:
             raise RuntimeError("客户端已关闭，无法启动消费")
 
@@ -425,7 +461,40 @@ class RabbitMQClient:
         if not self._queue:
             raise RuntimeError("未配置队列名或队列初始化失败")
 
-        self._consumer_tag = await self._queue.consume(self._process_message_callback)
+        # 防止重复注册消费：aio-pika RobustQueue._consumers 里若已有消费者，
+        # 再次 consume() 会在同一队列上挂多个回调（双消费/重复处理）。
+        # 注意：aiormq basic_consume 的 RPC 会占用 channel.lock 直到收到 Consume-Ok，
+        # 服务端收到 Basic.Consume 后可能立即开始投递，此时 RPC 锁未释放、
+        # _consumer_tag 尚未赋值，若已有消费者在跑则绝不能再来一次。
+        #
+        # 必须严格判断"非空 dict":getattr 拿到的是非 dict(如 MagicMock)或空 dict
+        # 时都不能进分支 —— 空 dict 会让 next(iter(...)) 抛 StopIteration,
+        # 且在 async 里被包成 RuntimeError,导致消费恢复假性失败、tag 被置 None。
+        #
+        # 两种幂等跳过：
+        #  A. 未显式传 tag + 已有消费者 → 复用任意现有 tag(去重,防双消费)
+        #  B. 显式传 tag X + _consumers 里已含 X → 该 tag 已在消费,直接复用,
+        #     避免对同一 tag 重复 basic_consume 触发 aiormq DuplicateConsumerTag
+        #     (此情况发生在 connect() 恢复路径与 aio-pika Robust 自动 restore 撞车)。
+        #     若 _consumers 含的是别的 tag(理论上不应发生,Robust 用相同 tag restore),
+        #     则仍按显式 tag 真正 consume,交给服务端校验。
+        existing = getattr(self._queue, "_consumers", None)
+        if isinstance(existing, dict):
+            if existing and consumer_tag is None:
+                self._consumer_tag = next(iter(existing))
+                logger.warning(
+                    f"队列 '{getattr(self._queue, 'name', '?')}' 已有 {len(existing)} 个消费者，"
+                    f"跳过重复注册(复用现有 tag: {self._consumer_tag})")
+                return self._consumer_tag
+            if consumer_tag is not None and consumer_tag in existing:
+                self._consumer_tag = consumer_tag
+                logger.info(
+                    f"队列 '{getattr(self._queue, 'name', '?')}' 的 tag {consumer_tag} "
+                    f"已在消费,跳过重复注册(幂等)")
+                return self._consumer_tag
+
+        self._consumer_tag = await self._queue.consume(
+            self._process_message_callback, consumer_tag=consumer_tag)
         logger.info(f"开始消费队列: {self._queue.name}，tag: {self._consumer_tag}")
         return self._consumer_tag
 

{sycommon_python_lib-0.2.7a47 → sycommon_python_lib-0.2.7a48}/src/sycommon/rabbitmq/rabbitmq_pool.py

@@ -293,9 +293,10 @@ class RabbitMQConnectionPool:
             return channel, conn
         except Exception as e:
             logger.error(f"❌ [CHANNEL_FAIL] 创建独立通道失败: {e}")
-            # 通道创建失败可能是连接已失效，触发连接重建以便下次使用新连接
-            # 不在持有锁的情况下调用 force_reconnect，避免死锁
-            self._initialized = False
+            # 通道级失败不应废掉整个连接池：连接本身可能仍健康，
+            # 置 _initialized=False 会导致 is_pool_initialized() 返回 False、
+            # 监控失明且 wait_for_pool_ready 超时。让调用方重试即可，
+            # 连接级问题由 _ensure_connection/is_alive 的心跳机制兜底。
             raise
 
     async def force_reconnect(self):