sycommon-python-lib 0.2.10a17__tar.gz → 0.2.10a18__tar.gz

{sycommon_python_lib-0.2.10a17 → sycommon_python_lib-0.2.10a18}/PKG-INFO

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

{sycommon_python_lib-0.2.10a17 → sycommon_python_lib-0.2.10a18}/pyproject.toml

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

{sycommon_python_lib-0.2.10a17 → sycommon_python_lib-0.2.10a18}/src/sycommon/alert/api.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 from typing import Optional
 
 from sycommon.alert.ao import AlertAo
+from sycommon.alert.ratelimit import safe_invoke
 from sycommon.alert.sdk import alert
 from sycommon.alert.sdk_selfcheck import get_msg
 
@@ -21,11 +22,16 @@ LEVEL_FATAL = AlertAo.LEVEL_FATAL
 
 def _alert_inner(level: str, template_no: str, title: str, detail: str,
                  err: Optional[Exception]) -> None:
-    ao = AlertAo(level=level, templateNo=template_no or None,
-                 title=title or None, detail=detail or None)
-    if err is not None:
-        ao.errorMsg = get_msg(err)
-    alert(ao)
+    # send_alert 已有 try/except 红线;此处 safe_invoke 为门面层的第二道闸
+    # (未来实现变化也不外漏)。
+    def _send() -> None:
+        ao = AlertAo(level=level, templateNo=template_no or None,
+                     title=title or None, detail=detail or None)
+        if err is not None:
+            ao.errorMsg = get_msg(err)
+        alert(ao)
+
+    safe_invoke("alert_inner", _send)
 
 
 # ---------------- AlertSdk ----------------

{sycommon_python_lib-0.2.10a17 → sycommon_python_lib-0.2.10a18}/src/sycommon/alert/bridge.py

@@ -11,6 +11,7 @@ import asyncio
 import re
 
 from sycommon.alert.monitor import register_db_stats, start_monitors
+from sycommon.alert.ratelimit import safe_invoke
 from sycommon.logging.kafka_log import SYLogger
 
 
@@ -39,11 +40,19 @@ def _sqlalchemy_pool_stats() -> dict:
 
 
 async def init_alert_monitors() -> None:
-    """启动默认监控(GC + 连接池饱和度)。engine 未初始化时跳过池监控。"""
-    stats = _sqlalchemy_pool_stats()
-    if stats:
-        register_db_stats(_sqlalchemy_pool_stats)
-    start_monitors()
+    """启动默认监控(GC + 连接池饱和度)。engine 未初始化时跳过池监控。
+
+    隔离红线:接线过程任何异常只打日志,绝不带崩宿主启动。
+    (start_monitors 内部 asyncio.get_running_loop 要求在事件循环线程上
+    调用 — 不能丢 executor,直接同步执行 + safe_invoke 兜底。)
+    """
+    def _wire() -> None:
+        stats = _sqlalchemy_pool_stats()
+        if stats:
+            register_db_stats(_sqlalchemy_pool_stats)
+        start_monitors()
+
+    safe_invoke("init_alert_monitors", _wire)
 
 
 __all__ = ["init_alert_monitors", "register_db_stats"]

{sycommon_python_lib-0.2.10a17 → sycommon_python_lib-0.2.10a18}/src/sycommon/alert/guard.py

@@ -17,6 +17,7 @@ from typing import Callable, TypeVar
 from sycommon.alert import api
 from sycommon.alert.api import (LEVEL_CRITICAL, LEVEL_FATAL, LEVEL_INFO,
                                 LEVEL_WARN)
+from sycommon.alert.ratelimit import safe_invoke
 
 T = TypeVar('T')
 
@@ -25,7 +26,8 @@ def alert_on_exception(level: str, title: str, template_no: str = "") -> Callabl
     """方法异常告警装饰器(@XxxAlert 切面等价)。
 
     detail 为 "执行方法 模块.函数"(Java buildDetail 的
-    "执行方法 %s:%s" — declaringClass:method)。
+    "执行方法 %s:%s" — declaringClass:method)。告警发送异常被 safe_invoke
+    吞掉,raise 的是业务原始异常。
     """
 
     def deco(fn: Callable) -> Callable:
@@ -37,8 +39,8 @@ def alert_on_exception(level: str, title: str, template_no: str = "") -> Callabl
                 try:
                     return await fn(*args, **kwargs)
                 except Exception as e:  # noqa: BLE001
-                    api._alert_inner(level, template_no, title,
-                                     f"执行方法 {where}", e)
+                    safe_invoke("guard alert", lambda: api._alert_inner(
+                        level, template_no, title, f"执行方法 {where}", e))
                     raise
             return async_wrapper
 
@@ -47,7 +49,8 @@ def alert_on_exception(level: str, title: str, template_no: str = "") -> Callabl
             try:
                 return fn(*args, **kwargs)
             except Exception as e:  # noqa: BLE001
-                api._alert_inner(level, template_no, title, f"执行方法 {where}", e)
+                safe_invoke("guard alert", lambda: api._alert_inner(
+                    level, template_no, title, f"执行方法 {where}", e))
                 raise
         return wrapper
 

{sycommon_python_lib-0.2.10a17 → sycommon_python_lib-0.2.10a18}/src/sycommon/alert/monitor.py

@@ -57,14 +57,24 @@ def start_monitors() -> None:
     if _started:
         return
     _started = True
-    loop = asyncio.get_running_loop()
-    interval = get_int("sy-alert.gc-monitor.scan-interval-seconds", 10)
-    SYLogger.info(f"GC监控开启, 扫描间隔为: {interval} 秒")
-    loop.create_task(_gc_monitor_loop(interval))
-    if _db_stats_func is not None:
-        ds_interval = get_int("sy-alert.datasource.scan-interval-seconds", 10)
-        SYLogger.info(f"数据库连接池饱和度监控启动, 每 {ds_interval} 秒执行一次")
-        loop.create_task(_db_monitor_loop(ds_interval))
+    # 隔离红线:挂载阶段任何异常(取配置/建任务)只打日志,绝不带崩宿主启动。
+    try:
+        loop = asyncio.get_running_loop()
+    except RuntimeError:
+        SYLogger.error("[alert] 监控件挂载失败(无运行中事件循环,不影响服务)")
+        _started = False
+        return
+    try:
+        interval = get_int("sy-alert.gc-monitor.scan-interval-seconds", 10)
+        SYLogger.info(f"GC监控开启, 扫描间隔为: {interval} 秒")
+        loop.create_task(_gc_monitor_loop(interval))
+        if _db_stats_func is not None:
+            ds_interval = get_int("sy-alert.datasource.scan-interval-seconds", 10)
+            SYLogger.info(f"数据库连接池饱和度监控启动, 每 {ds_interval} 秒执行一次")
+            loop.create_task(_db_monitor_loop(ds_interval))
+    except Exception as e:  # noqa: BLE001
+        SYLogger.error(f"[alert] 监控件挂载失败(不影响服务): {e}")
+        _started = False
 
 
 async def _gc_monitor_loop(interval_s: int) -> None:
@@ -138,10 +148,13 @@ async def _db_monitor_loop(interval_s: int) -> None:
                     continue
                 rate = in_use / max_open
                 title = "数据库连接池"
-                # Java PoolMonitor:detail = name+"饱和："+desc;desc 形态
-                # "活跃数: %d, 等待数: %d, 总数: %d, 最大数: %d, 名称: %s"(4 轮
-                # 审核对齐 — 此前是自造的使用率文案)。max<=5 且无等待 → 忽略告警。
-                desc = (f"活跃数: {in_use}, 等待数: 0, 总数: 0, "
+                # Java PoolMonitor:detail = name+"饱和："+PoolStatus.desc();
+                # desc 按 totalSize 分流(PoolStatus.desc 字节码 4:ifeq):
+                # totalSize==0 用 4 字段 "活跃数: %d, 等待数: %d, 最大数: %d,
+                # 名称: %s",非 0 用 5 字段版。SQLAlchemy pool 无 total 暴露 →
+                # 4 字段版(此前误用 5 字段版硬填 0,按 jar 纠正)。
+                # max<=5 且无等待 → 忽略告警。
+                desc = (f"活跃数: {in_use}, 等待数: 0, "
                         f"最大数: {max_open}, 名称: {title}")
                 detail = title + "饱和：" + desc
                 if max_open <= 5:

{sycommon_python_lib-0.2.10a17 → sycommon_python_lib-0.2.10a18}/src/sycommon/alert/queue.py

@@ -23,6 +23,7 @@ import time
 from typing import List
 
 from sycommon.alert.ao import AlertAo
+from sycommon.alert.ratelimit import safe_invoke
 from sycommon.alert.sdk_selfcheck import self_check_alert
 
 
@@ -39,7 +40,11 @@ class BoundedAlarmQueue:
         self._cond = asyncio.Condition()
 
     async def offer(self, item: AlertAo) -> bool:
-        """对齐 Java offer(T):返回是否入队成功。"""
+        """对齐 Java offer(T):返回是否入队成功。
+
+        隔离红线:丢弃分支的自检发送经 safe_invoke — 自检通道异常绝不带崩
+        入队调用方(业务线程)。
+        """
         async with self._cond:
             # 分支 1:队头(最低最旧)堆积超时自检(仅 is_check 且队列非空)。
             if self.is_check and self._items:
@@ -47,10 +52,10 @@ class BoundedAlarmQueue:
                 if first is not None and first.time and first.time > 0:
                     stuck_ms = int(time.time() * 1000) - first.time
                     if stuck_ms > self.block_timeout_ms:
-                        self_check_alert(
+                        safe_invoke("queue backlog self-check", lambda: self_check_alert(
                             f"{self.name}-消息堆积",
                             f"堆积时间={stuck_ms} ms 队列大小={len(self._items)}, "
-                            f"告警详情:{first.get_key_msg()}")
+                            f"告警详情:{first.get_key_msg()}"))
 
             # 分支 2:未满直接有序插入。
             if len(self._items) < self.capacity:
@@ -59,19 +64,22 @@ class BoundedAlarmQueue:
                 return True
 
             # 分支 3:满且新条优先级高于队头最低者 → 驱逐队头,入新。
-            if item.compare_to(self._items[0]) > 0:
+            # 空列表守卫:capacity<=0 且队空时 items[0] 会 IndexError
+            # (九审探针;Go 侧 len>0 守卫同款 — Java 此处裸 first() 会
+            # NoSuchElementException,属 Java 自身缺陷,不复制)。
+            if self._items and item.compare_to(self._items[0]) > 0:
                 evicted = self._items.pop(0)
                 self._insert(item)
                 if self.is_check:
-                    self_check_alert(
-                        f"{self.name}-队列已满,丢弃队列消息", evicted.get_key_msg())
+                    safe_invoke("queue evict self-check", lambda: self_check_alert(
+                        f"{self.name}-队列已满,丢弃队列消息", evicted.get_key_msg()))
                 self._cond.notify()
                 return True
 
             # 分支 4:满且新条不高于最低者 → 丢弃新消息。
             if self.is_check:
-                self_check_alert(
-                    f"{self.name}-队列已满,丢弃新消息", item.get_key_msg())
+                safe_invoke("queue drop self-check", lambda: self_check_alert(
+                    f"{self.name}-队列已满,丢弃新消息", item.get_key_msg()))
             return False
 
     def _insert(self, item: AlertAo) -> None:

sycommon_python_lib-0.2.10a18/src/sycommon/alert/ratelimit.py

@@ -0,0 +1,82 @@
+"""ratelimit.py — 发送侧限频(消费 pacing)+ 隔离红线 safe_invoke。
+
+对齐 Go infra/alert/ratelimit.go(Java SDK 无发送限频,两库同为补强):
+  - sy-alert.rate-limit.max-per-second:每秒最多发送的告警【条数】(默认 100),
+    <=0 = 不限(回到 Java 行为,逃生口);
+  - 令牌桶按条计数:一批 N 条消耗 N 个令牌;不足则阻塞【专用消费线程】
+    (阻塞不影响业务线程;停机 cancel 优先于限率等待);
+  - 桶容量(突发额度)= rate;rate<单批上限(100)时抬到 100 — 允许一次
+    整批,防止 rate<batch 永等死锁。
+
+配置读取时点:start()(含懒启动)一次性读入;改配置需重启进程生效。
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+
+from sycommon.logging.kafka_log import SYLogger
+
+SEND_RATE_KEY = "sy-alert.rate-limit.max-per-second"
+DEFAULT_SEND_RATE_PS = 100
+
+
+class SendRateLimiter:
+    """单实例令牌桶(仅消费线程使用;加锁为测试与复用安全)。
+
+    burst(桶容量/突发额度)= rate;rate<单批上限(MAX_BATCH_SIZE=100)时抬到
+    100 — 允许一次整批,防止 rate<batch 永等死锁(与 Go ratelimit.go 同款)。
+    """
+
+    def __init__(self, rate_per_sec: int, max_batch: int = 100):
+        self.rate = float(rate_per_sec)
+        self._max_batch = float(max_batch)
+        self._burst = self.rate
+        if 0 < self._burst < self._max_batch:
+            self._burst = self._max_batch
+        self._tokens = self._burst
+        self._last = time.monotonic()
+        self._lock = threading.Lock()
+
+    async def acquire(self, n: int) -> None:
+        """等到 n 个令牌才返回。不限速(n<=0)立即返回;CancelledError(停机)
+        传播给消费循环既有 except 分支处理 — 不因限率卡停机。"""
+        if self.rate <= 0 or n <= 0:
+            return
+        while True:
+            with self._lock:
+                now = time.monotonic()
+                self._tokens = min(self._burst,
+                                   self._tokens + (now - self._last) * self.rate)
+                self._last = now
+                if self._tokens >= n:
+                    self._tokens -= n
+                    return
+                wait = (n - self._tokens) / self.rate
+            await asyncio.sleep(wait + 0.001)  # +1ms 防浮点取整自旋
+
+
+def send_rate_per_sec(read_cfg=None) -> int:
+    """读限频配置(env relaxed binding:SY_ALERT_RATE_LIMIT_MAX_PER_SECOND 自动命中)。
+
+    read_cfg:测试注入 (key, default) -> int;缺省走 alert.env.get_int。
+    """
+    if read_cfg is not None:
+        return read_cfg(SEND_RATE_KEY, DEFAULT_SEND_RATE_PS)
+    from sycommon.alert.env import get_int
+    return get_int(SEND_RATE_KEY, DEFAULT_SEND_RATE_PS)
+
+
+def safe_invoke(what: str, fn) -> None:
+    """隔离红线:alert 模块自身的异常只转 error 日志,绝不传播到宿主调用栈
+    ("alert 自身报错不能引发集成项目报错")。"""
+    try:
+        fn()
+    except asyncio.CancelledError:
+        raise  # 停机信号必须穿透,不能当 alert 自身错误吞掉
+    except Exception as e:  # noqa: BLE001
+        try:
+            SYLogger.error(f"[alert] {what} failed (isolated, host unaffected): {e}")
+        except Exception:  # noqa: BLE001  日志器本身也炸的终极兜底
+            pass

{sycommon_python_lib-0.2.10a17 → sycommon_python_lib-0.2.10a18}/src/sycommon/alert/sdk.py

@@ -33,6 +33,7 @@ import aiohttp
 from sycommon.alert.ao import AlertAo, get_count_string
 from sycommon.alert.env import active_profile, app_name_of_sdk, get_property, local_ip
 from sycommon.alert.queue import BoundedAlarmQueue
+from sycommon.alert.ratelimit import SendRateLimiter, safe_invoke, send_rate_per_sec
 from sycommon.alert.sdk_selfcheck import get_msg, self_check_alert_err
 from sycommon.logging.kafka_log import SYLogger
 from sycommon.tools.snowflake import Snowflake
@@ -73,6 +74,7 @@ class _InnerSDK:
         self._thread: Optional[threading.Thread] = None
         self._started = False
         self._lock = threading.Lock()
+        self.limiter: Optional[SendRateLimiter] = None  # _ensure_started 时按配置建
 
     # ---------------- 专用线程生命周期 ----------------
 
@@ -90,6 +92,8 @@ class _InnerSDK:
                 return self._loop, self.queue
             self.queue = BoundedAlarmQueue("告警SDK", QUEUE_CAPACITY,
                                            QUEUE_BLOCK_TIMEOUT_MS, is_check=True)
+            # 发送限频(消费线程专用 pacing;见 ratelimit.py)— 启动时一次读配置。
+            self.limiter = SendRateLimiter(send_rate_per_sec(), MAX_BATCH_SIZE)
             self._loop = asyncio.new_event_loop()
             self._thread = threading.Thread(
                 target=self._run, args=(self._loop, self.queue),
@@ -111,14 +115,22 @@ class _InnerSDK:
         except Exception as e:  # noqa: BLE001  线程兜底:消费线程永不带崩进程
             SYLogger.error(f"告警SDK消费线程异常退出: {e}")
         finally:
-            self._started = False
+            # 代际判定:仅当 self._loop 仍是本代 loop 时才清 started —
+            # stop() join 超时后新一代可能已启动,旧线程收尾不得抹掉新代
+            # 标志(否则下一条告警再拉一代,孤儿线程空转)。
+            # 判定+写必须同锁,与 _ensure_started 的启动序列互斥。
+            with self._lock:
+                if self._loop is loop:
+                    self._started = False
             if main_task is not None:
                 # stop() 经 loop.stop() 退出 run_forever — cancel 后给
                 # session.close 清理一次收尾机会(限时,不拖停机)。
                 main_task.cancel()
                 try:
                     loop.run_until_complete(main_task)
-                except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                except BaseException:  # noqa: BLE001  收尾兜底:消费协程被
+                    # cancel 后仍可能从 finally 段抛任意异常(含 session.close
+                    # 的 CancelledError 重入);吞掉只为收尾,不影响任何语义。
                     pass
             try:
                 loop.close()
@@ -144,6 +156,10 @@ class _InnerSDK:
                     continue
                 if len(batch) == 1 and batch[0].traceId:
                     trace_id = batch[0].traceId
+                # 发送限频(消费线程专用 pacing):一批 N 条消耗 N 个令牌,
+                # 不足则等待(停机 cancel 优先)。见 ratelimit.py。
+                if self.limiter is not None:
+                    await self.limiter.acquire(len(batch))
                 await self.send_to_alert_gateway(session, batch, trace_id, queue)
             except asyncio.CancelledError:
                 SYLogger.error("应用系统停机，停止消费")
@@ -162,11 +178,12 @@ class _InnerSDK:
         offer 本身非阻塞(Java offer 同款),等待上限 OFFER_TIMEOUT_S。
         异常对齐 Java sendAlert 的 catch:warn("发送告警失败")+
         SelfCheck("告警SDK-发送系统告警失败",null,e)。
+        隔离红线:任何 alert 内部异常到此为止,绝不传播到调用方栈。
         """
         if ao is None:
             return False
         try:
-            self.init_alert_env(ao)
+            safe_invoke("init_alert_env", lambda: self.init_alert_env(ao))
             ao.calc_priority()
             loop, queue = self._ensure_started()
             fut = asyncio.run_coroutine_threadsafe(queue.offer(ao), loop)
@@ -181,7 +198,7 @@ class _InnerSDK:
         if ao is None:
             return False
         try:
-            self.init_alert_env(ao)
+            safe_invoke("init_alert_env", lambda: self.init_alert_env(ao))
             ao.calc_priority()
             loop, queue = self._ensure_started()
             fut = asyncio.run_coroutine_threadsafe(queue.offer(ao), loop)
@@ -236,6 +253,11 @@ class _InnerSDK:
         ) as resp:
             text = await resp.text()
             SYLogger.info(f"send result status={resp.status}, body={text}")
+            # 非 2xx 不再静默当成功:抛错由消费循环对齐 Java 的
+            # SelfCheck+sleep 语义(此前网关 5xx 会被当"发送完成"吞掉)。
+            if not 200 <= resp.status < 300:
+                raise RuntimeError(
+                    f"网关返回非 2xx: status={resp.status} body={text[:256]}")
         SYLogger.info(f"批量发送 {len(batch)} 条告警完成")
 
     async def stop(self) -> None:
@@ -297,10 +319,10 @@ async def stop() -> None:
 
 
 def alert(ao: AlertAo) -> None:
-    """对齐 Java InnerSdk.alert(AlertAo)。"""
+    """对齐 Java InnerSdk.alert(AlertAo)。隔离红线:alert 内部异常不外漏。"""
     if ao is None:
         return
-    _get_inner().send_alert(ao)
+    safe_invoke("alert", lambda: _get_inner().send_alert(ao))
 
 
 async def alert_async(ao: AlertAo) -> bool:

{sycommon_python_lib-0.2.10a17 → sycommon_python_lib-0.2.10a18}/src/sycommon/alert/sdk_selfcheck.py

@@ -197,25 +197,42 @@ def self_check_alert(msg: str, detail: str = "") -> None:
 
 
 def self_check_alert_err(msg: str, detail: str, err: Optional[Exception]) -> None:
-    """对齐 Java SelfCheckAlert.alert(String, String, Exception)。"""
-    _self_check_inner(msg, detail, get_msg(err))
-
-
-def _self_check_inner(msg: str, detail: str, err_stack: str) -> None:
-    if _UNITTEST:
-        return  # 单测静默:不自检、不外发(含 warn 日志噪音)
-    SYLogger.warning(f"系统自检告警: {msg} {detail} {err_stack}")
-    if not _limiter.try_acquire():
-        SYLogger.warning(f"系统自检异常频率过高 不发送告警 {msg}")
-        return
-    trace_id = ""
+    """对齐 Java SelfCheckAlert.alert(String, String, Exception)。
+
+    markdown 异常信息段用 stack 前 256;日志第三参用 ex.getMessage()(仅消息)。
+    """
+    _self_check_inner(msg, detail, get_msg(err),
+                      err_log=str(err) if err is not None else "")
+
+
+def _self_check_inner(msg: str, detail: str, err_stack: str,
+                      err_log: str = "") -> None:
+    # 隔离红线:自检通道自身任何异常到此为止(队列 offer/监控循环等业务栈
+    # 上的调用点绝不被自检带崩)。
     try:
-        from sycommon.middleware.context import current_trace_id
-        trace_id = current_trace_id.get() or ""
-    except Exception:
-        trace_id = SYLogger.get_trace_id() or ""
-    _get_worker().submit({"msg": msg, "detail": detail, "err": err_stack,
-                          "trace_id": trace_id})
+        if _UNITTEST:
+            return  # 单测静默:不自检、不外发(含 warn 日志噪音)
+        # Java alert 首行第三参 = ex.getMessage()(字节码 33),非 stack。
+        SYLogger.warning(f"系统自检告警: {msg} {detail} {err_log}")
+        if not _limiter.try_acquire():
+            SYLogger.warning(f"系统自检异常频率过高 不发送告警 {msg}")
+            return
+        trace_id = ""
+        try:
+            from sycommon.middleware.context import current_trace_id
+            trace_id = current_trace_id.get() or ""
+        except Exception:
+            trace_id = SYLogger.get_trace_id() or ""
+        # Java lambda 捕获 alert() 调用时刻(now)与 traceId 一起入队 —
+        # markdown 展示的是【检测时刻】而非实际 HTTP 发出时刻。
+        _get_worker().submit({"msg": msg, "detail": detail, "err": err_stack,
+                              "trace_id": trace_id,
+                              "sent_at": datetime.now()})
+    except Exception as e:  # noqa: BLE001
+        try:
+            SYLogger.error(f"[alert] self-check failed (isolated, host unaffected): {e}")
+        except Exception:  # noqa: BLE001
+            pass
 
 
 def _iso_local_date_time(dt: datetime) -> str:
@@ -239,15 +256,20 @@ def _iso_local_date_time(dt: datetime) -> str:
 
 def build_self_check_markdown(item: dict) -> str:
     """对齐 Java alertInner 的 markdown 组装。"""
-    now = _iso_local_date_time(datetime.now())
+    # Java lambda 捕获 alert() 时刻的 now;入队项携带 sent_at(缺省回退当前)。
+    now = _iso_local_date_time(item.get('sent_at') or datetime.now())
     md = (
         f"`{_t256(item.get('msg'))}` \n>应用：{_t256(app_name_of_sdk())}"
         f" \n>IP：{_t256(local_ip())}"
         f" \n>环境：{_t256(active_profile())}"
         f" \n>时间：<font color=\"comment\">{now}</font>"
         f" \n>traceId：<font color=\"comment\">{_t256(item.get('trace_id'))}</font> \n"
-        f">详情：{_t256(item.get('detail'))}\n"
     )
+    # Java 字节码 117-121:StringUtils.isNotEmpty(detail) 才追加详情段 —
+    # 空 detail 不产生 ">详情：" 行(此前无条件写,已按 jar 复核对齐)。
+    detail = item.get('detail')
+    if detail:
+        md += f">详情：{_t256(detail)}\n"
     if item.get('err'):
         md += f">异常信息：\n{_t256(item['err'])}"
     return md