xtquant-share 1.3.0__tar.gz → 1.4.0__tar.gz

{xtquant_share-1.3.0/xtquant_share.egg-info → xtquant_share-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtquant-share
-Version: 1.3.0
+Version: 1.4.0
 Summary: Xtreme Quant Share - eXtreme transparent sharing proxy for XtQuant on macOS/Linux
 Author-email: Jason Hu <63170682@qq.com>
 License-Expression: GPL-3.0-only
@@ -50,6 +50,7 @@ Dynamic: license-file
 - ✅ **认证加密** - 支持 HMAC token 认证，可选 SSL/TLS 加密
 - ✅ **断线重连** - 自动检测断线并重连，指数退避策略
 - ✅ **心跳保活** - 定期心跳检测，保持连接活跃
+- ✅ **服务实例标识** - `get_instance_id()` 轻量感知 server 重启；行情订阅幂等自动去重，阻断底层 miniquote 订阅累积
 - ✅ **异步回调** - 支持交易事件（on_stock_*）与行情 tick 订阅回调（`xtdata.register_quote_callback` + `subscribe_whole_quote`）
 - ✅ **无感切换** - 大QMT ↔ miniQMT 无感切换（行情侧），自动探测 miniQMT 可用性，不可用自动切 bigqmt 通道（复用 xtquant_big_convert）
 - ✅ **完整日志** - API调用日志，记录函数名、参数、耗时
@@ -801,6 +802,7 @@ print(status)
 
 | 版本 | 日期 | 更新内容 |
 |------|------|----------|
+| 1.4.0 | 2026-10-03 | 新增 `get_instance_id()` 服务实例标识（轻量感知 server 重启）；行情订阅幂等（重复订阅自动释放旧 seq，阻断 miniquote 订阅累积泄漏） |
 | 1.1.1 | 2026-03-18 | 新增 xtview 模块支持（视图控制、调度任务管理），兼容不同 xtquant 版本 |
 | 1.1.0 | 2026-03-17 | 交易功能优化完善、`xqshare-server` 命令、`.env` 配置支持、远程对象传输性能优化 |
 | 1.0.4 | 2026-03-09 | JSON 输出优化：远程 DataFrame 高效序列化、`--compact` 参数、全局参数位置灵活、嵌套结构支持 |

{xtquant_share-1.3.0 → xtquant_share-1.4.0}/README.md

@@ -8,6 +8,7 @@
 - ✅ **认证加密** - 支持 HMAC token 认证，可选 SSL/TLS 加密
 - ✅ **断线重连** - 自动检测断线并重连，指数退避策略
 - ✅ **心跳保活** - 定期心跳检测，保持连接活跃
+- ✅ **服务实例标识** - `get_instance_id()` 轻量感知 server 重启；行情订阅幂等自动去重，阻断底层 miniquote 订阅累积
 - ✅ **异步回调** - 支持交易事件（on_stock_*）与行情 tick 订阅回调（`xtdata.register_quote_callback` + `subscribe_whole_quote`）
 - ✅ **无感切换** - 大QMT ↔ miniQMT 无感切换（行情侧），自动探测 miniQMT 可用性，不可用自动切 bigqmt 通道（复用 xtquant_big_convert）
 - ✅ **完整日志** - API调用日志，记录函数名、参数、耗时
@@ -759,6 +760,7 @@ print(status)
 
 | 版本 | 日期 | 更新内容 |
 |------|------|----------|
+| 1.4.0 | 2026-10-03 | 新增 `get_instance_id()` 服务实例标识（轻量感知 server 重启）；行情订阅幂等（重复订阅自动释放旧 seq，阻断 miniquote 订阅累积泄漏） |
 | 1.1.1 | 2026-03-18 | 新增 xtview 模块支持（视图控制、调度任务管理），兼容不同 xtquant 版本 |
 | 1.1.0 | 2026-03-17 | 交易功能优化完善、`xqshare-server` 命令、`.env` 配置支持、远程对象传输性能优化 |
 | 1.0.4 | 2026-03-09 | JSON 输出优化：远程 DataFrame 高效序列化、`--compact` 参数、全局参数位置灵活、嵌套结构支持 |

{xtquant_share-1.3.0 → xtquant_share-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "xtquant-share"
-version = "1.3.0"
+version = "1.4.0"
 description = "Xtreme Quant Share - eXtreme transparent sharing proxy for XtQuant on macOS/Linux"
 readme = "README.md"
 license = "GPL-3.0-only"

{xtquant_share-1.3.0 → xtquant_share-1.4.0}/tests/test_quote_events.py

@@ -30,7 +30,7 @@ sys.modules['xtquant.xttype'] = mock_xttype
 from xqshare.server import _init_logging
 _init_logging("WARNING")
 
-from xqshare.server import LoggingProxy, _QuoteEventCallback
+from xqshare.server import LoggingProxy, XtQuantService, _QuoteEventCallback
 from xqshare.client import RemoteQuoteCallback
 from xqshare.auth import AccountLevel
 
@@ -118,6 +118,83 @@ class TestQuoteEventCallback:
         finally:
             qec.stop()
 
+    def test_register_idempotent_per_client(self):
+        """同一 client_info 重复 register（断线重连后新 netref）应覆盖旧 entry 而非累积"""
+        qec = _QuoteEventCallback()
+        try:
+            old_cb = MagicMock()
+            new_cb = MagicMock()
+            qec.register(old_cb, client_info="c1@127.0.0.1:1")
+            qec.register(new_cb, client_info="c1@127.0.0.1:1")
+
+            assert len(qec._subscribers) == 1, "重连后旧 netref 应被覆盖，不累积"
+            entry = next(iter(qec._subscribers.values()))
+            assert entry['callback'] is new_cb
+        finally:
+            qec.stop()
+
+    def test_register_without_client_info_no_dedup(self):
+        """client_info 为 None 时不做幂等去重（保持原语义，按 id 累积）"""
+        qec = _QuoteEventCallback()
+        try:
+            qec.register(MagicMock())
+            qec.register(MagicMock())
+            assert len(qec._subscribers) == 2
+        finally:
+            qec.stop()
+
+    def test_clear_client_callbacks(self):
+        """clear_client_callbacks 只清理指定 client 的回调，不影响其他 client"""
+        qec = _QuoteEventCallback()
+        try:
+            cb1, cb2, cb3 = MagicMock(), MagicMock(), MagicMock()
+            qec.register(cb1, client_info="c1@127.0.0.1:1")
+            qec.register(cb2, client_info="c1@127.0.0.1:1")
+            qec.register(cb3, client_info="c2@127.0.0.1:2")
+
+            qec.clear_client_callbacks("c1@127.0.0.1:1")
+
+            remaining = [e['callback'] for e in qec._subscribers.values()]
+            assert remaining == [cb3], "只应保留其他 client 的回调"
+        finally:
+            qec.stop()
+
+    def test_on_disconnect_clears_quote_subscribers(self):
+        """on_disconnect 应清理该连接注册的 quote 回调，避免 netref 累积泄漏"""
+        qec = _QuoteEventCallback()
+        original = XtQuantService._quote_event_callback
+        XtQuantService._quote_event_callback = qec
+        try:
+            service = XtQuantService()
+            service._client_info = "c1@127.0.0.1:1"
+            service._traders = []
+            qec.register(MagicMock(), client_info="c1@127.0.0.1:1")
+            qec.register(MagicMock(), client_info="c2@127.0.0.1:2")
+
+            service.on_disconnect(MagicMock())
+
+            remaining = [e['client_info'] for e in qec._subscribers.values()]
+            assert remaining == ["c2@127.0.0.1:2"], "断开连接的客户端回调应被清理"
+        finally:
+            qec.stop()
+            XtQuantService._quote_event_callback = original
+
+    def test_on_disconnect_without_quote_callback(self):
+        """quote 单例未初始化时 on_disconnect 不应报错，也不应创建单例"""
+        original = XtQuantService._quote_event_callback
+        XtQuantService._quote_event_callback = None
+        try:
+            service = XtQuantService()
+            service._client_info = "c1@127.0.0.1:1"
+            service._traders = []
+
+            service.on_disconnect(MagicMock())
+
+            assert XtQuantService._quote_event_callback is None, \
+                "不应在断开时懒创建 quote 单例"
+        finally:
+            XtQuantService._quote_event_callback = original
+
 
 class TestLoggingProxyQuoteIntercept:
     """LoggingProxy 拦截 xtdata 订阅并接管 callback"""
@@ -143,8 +220,10 @@ class TestLoggingProxyQuoteIntercept:
 
             kwargs = mock.subscribe_whole_quote.call_args.kwargs
             assert kwargs["callback"] is qec, "原生 callback 应由服务端路由器接管"
-            assert len(qec._subscribers) == 1 and next(iter(qec._subscribers.values())) is client_cb, \
-                "客户端回调应注册到路由器"
+            assert len(qec._subscribers) == 1, "客户端回调应注册到路由器"
+            entry = next(iter(qec._subscribers.values()))
+            assert entry['callback'] is client_cb
+            assert entry['client_info'] == "test-client", "应记录 client_info 供断线清理"
         finally:
             qec.stop()
 
@@ -193,6 +272,54 @@ class TestLoggingProxyQuoteIntercept:
         finally:
             qec.stop()
 
+    def test_subscribe_idempotent_unsubscribe_old_seq(self):
+        """同一 client 重复订阅同一 code_list，应先 unsubscribe 旧 seq 再订阅（防 miniquote 累积）"""
+        mock = MagicMock()
+        mock.subscribe_whole_quote.side_effect = [1, 2]
+        mock.unsubscribe_quote = MagicMock()
+        qec = _QuoteEventCallback()
+        try:
+            proxy = self._proxy(mock, qec)
+            client_cb = MagicMock()
+            proxy.subscribe_whole_quote(["000001.SZ"], callback=client_cb)  # seq=1
+            proxy.subscribe_whole_quote(["000001.SZ"], callback=client_cb)  # seq=2，先 unsubscribe 1
+
+            mock.unsubscribe_quote.assert_called_once_with(1)
+            assert mock.subscribe_whole_quote.call_count == 2
+        finally:
+            qec.stop()
+
+    def test_subscribe_different_codes_no_unsubscribe(self):
+        """不同 code_list 的订阅互不影响，不应触发 unsubscribe"""
+        mock = MagicMock()
+        mock.subscribe_whole_quote.side_effect = [1, 2]
+        mock.unsubscribe_quote = MagicMock()
+        qec = _QuoteEventCallback()
+        try:
+            proxy = self._proxy(mock, qec)
+            proxy.subscribe_whole_quote(["000001.SZ"])
+            proxy.subscribe_whole_quote(["000002.SZ"])
+
+            mock.unsubscribe_quote.assert_not_called()
+        finally:
+            qec.stop()
+
+    def test_subscription_seq_record_and_clear(self):
+        """seq 管理：record → get 命中，clear 后 unsubscribe 所有 seq"""
+        qec = _QuoteEventCallback()
+        try:
+            key = ("subscribe_whole_quote", ("000001.SZ",))
+            qec.record_subscription("c1", key, 1)
+            assert qec.get_subscription_seq("c1", key) == 1
+            assert qec.get_subscription_seq("c1", ("subscribe_whole_quote", ("000002.SZ",))) is None
+
+            unsubscribed = []
+            qec.clear_client_subscriptions("c1", lambda seq: unsubscribed.append(seq))
+            assert unsubscribed == [1]
+            assert qec.get_subscription_seq("c1", key) is None
+        finally:
+            qec.stop()
+
 
 class TestRemoteQuoteCallback:
     """客户端行情回调接收器"""

{xtquant_share-1.3.0 → xtquant_share-1.4.0}/tests/test_server.py

@@ -195,6 +195,49 @@ class TestXtQuantService:
         assert "test_token" not in service._tokens
 
 
+class TestTraderCallbackCleanup:
+    """测试 trader 事件路由器线程的清理（防泄漏）"""
+
+    def test_on_disconnect_stops_trader_event_callback(self):
+        """on_disconnect 应停止该连接创建的事件路由器 dispatch 线程"""
+        from xqshare.server import _TraderEventCallback
+        service = XtQuantService()
+        service._conn = Mock()
+        service._conn.peer = "127.0.0.1:12345"
+        service._client_info = "test_client@127.0.0.1:12345"
+        trader = Mock()
+        cb = _TraderEventCallback()
+        service._traders = [(trader, cb)]
+        try:
+            service.on_disconnect(service._conn)
+
+            assert cb._running is False, "on_disconnect 应停止事件路由器线程"
+            trader.stop.assert_called_once()
+        finally:
+            cb.stop()
+
+    def test_trader_event_callback_stop_terminates_thread(self):
+        """_TraderEventCallback.stop() 应让 dispatch daemon 线程退出"""
+        from xqshare.server import _TraderEventCallback
+        cb = _TraderEventCallback()
+        thread = cb._event_thread
+        assert thread.is_alive(), "dispatch 线程应在创建后运行"
+
+        cb.stop()
+        thread.join(timeout=3.0)
+        assert not thread.is_alive(), "stop() 后 dispatch 线程应退出"
+
+    def test_trader_event_callback_stop_idempotent(self):
+        """stop() 多次调用应无副作用"""
+        from xqshare.server import _TraderEventCallback
+        cb = _TraderEventCallback()
+        thread = cb._event_thread
+        cb.stop()
+        cb.stop()
+        thread.join(timeout=3.0)
+        assert not thread.is_alive()
+
+
 class TestSSLContext:
     """测试 SSL 上下文创建"""
     
@@ -434,5 +477,26 @@ class TestInitDatadirReader:
             XtQuantService._xtdata = original_xtdata
 
 
+class TestInstanceId:
+    """服务实例标识（instance_id）与订阅幂等辅助函数"""
+
+    def test_instance_id_is_nonempty_str(self):
+        from xqshare import server as server_mod
+        assert isinstance(server_mod._INSTANCE_ID, str)
+        assert len(server_mod._INSTANCE_ID) > 0
+
+    def test_exposed_get_instance_id(self):
+        from xqshare import server as server_mod
+        svc = XtQuantService()
+        assert svc.exposed_get_instance_id() == server_mod._INSTANCE_ID
+
+    def test_normalize_code_key(self):
+        from xqshare.server import _normalize_code_key
+        assert _normalize_code_key(["000001.SZ"]) == ("000001.SZ",)
+        assert _normalize_code_key(["SZ", "SH"]) == ("SH", "SZ")  # 排序去序
+        assert _normalize_code_key("000001.SZ") == ("000001.SZ",)
+        assert _normalize_code_key(("000001.SZ", "000002.SZ")) == ("000001.SZ", "000002.SZ")
+
+
 if __name__ == "__main__":
     pytest.main([__file__, "-v"])

{xtquant_share-1.3.0 → xtquant_share-1.4.0}/xqshare/__init__.py

@@ -4,7 +4,7 @@ XtQuant Share (xqshare) - Transparent remote proxy for xtquant library
 Allows using xtquant on macOS/Linux by proxying calls to a Windows server.
 """
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"
 __author__ = "Jason Hu"
 
 from .client import (

{xtquant_share-1.3.0 → xtquant_share-1.4.0}/xqshare/server.py

@@ -13,6 +13,7 @@ import logging
 import functools
 import json
 import threading
+import uuid
 from datetime import datetime
 from typing import Any, Dict, Optional
 
@@ -563,12 +564,20 @@ class _QuoteEventCallback:
         # key 用 id(netref)（本地内存地址）而非 netref 本身：
         # set 的 add/discard 会对 netref 求 hash（触发 RPC），客户端断开后
         # 该 RPC 会抛 EOFError，导致 dispatch 线程崩溃。id() 是纯本地操作。
-        self._subscribers = {}  # id(client_callback_netref) -> client_callback_netref
+        # value 记录 client_info，供 on_disconnect 按连接清理（修复 netref 累积泄漏）。
+        self._subscribers = {}  # id(client_callback_netref) -> {callback, client_info}
+        # 订阅幂等：client_info -> {code_key -> seq}。code_key = (方法名, 规范化code_list)。
+        # 同一 client 重复订阅同一 code_key 时先 unsubscribe 旧 seq 再订阅，
+        # 避免 miniquote 侧订阅累积（曾导致 miniquote 内存泄漏拖垮整机）。
+        self._subscriptions = {}
         self._running = True
         self._queue = []
         self._queue_lock = threading.Lock()
         self._event_thread = threading.Thread(target=self._dispatch_loop, daemon=True)
         self._event_thread.start()
+        # 订阅者数量告警水位：超过阈值打 warning，用于观察是否仍存在泄漏
+        self._max_subscribers_warning = _get_max_quote_subscribers()
+        self._warned = False
 
     def __call__(self, data):
         """使路由器可被 xtquant 作为函数式 callback 调用。
@@ -604,7 +613,7 @@ class _QuoteEventCallback:
                 continue
             for payload in batch:
                 with self._lock:
-                    callbacks = list(self._subscribers.values())
+                    callbacks = [entry['callback'] for entry in self._subscribers.values()]
                 for cb in callbacks:
                     try:
                         cb.exposed_on_quote_event(payload)
@@ -613,15 +622,90 @@ class _QuoteEventCallback:
                         logger.warning(f"[QuoteEvent] 推送到客户端失败，自动移除: {e}")
                         self.unregister(cb)
 
-    def register(self, client_callback):
+    def register(self, client_callback, client_info: Optional[str] = None):
         with self._lock:
-            self._subscribers[id(client_callback)] = client_callback
+            if client_info is not None:
+                # 幂等化：同一 client_info 重复 register（客户端断线重连后新 netref
+                # 的 id 不同）时，先移除该 client 的旧 entry，避免按 id(netref) 累积。
+                stale = [
+                    cid for cid, entry in self._subscribers.items()
+                    if entry['client_info'] == client_info
+                ]
+                for cid in stale:
+                    self._subscribers.pop(cid, None)
+            self._subscribers[id(client_callback)] = {
+                'callback': client_callback,
+                'client_info': client_info,
+            }
+        self._maybe_warn_subscriber_count()
         logger.info(f"[QuoteEvent] 注册订阅者 total={len(self._subscribers)}")
 
     def unregister(self, client_callback):
         with self._lock:
             self._subscribers.pop(id(client_callback), None)
 
+    def clear_client_callbacks(self, client_info: Optional[str]):
+        """按连接清理该客户端注册的所有 quote 回调（on_disconnect 调用）。"""
+        if client_info is None:
+            return
+        with self._lock:
+            stale = [
+                cid for cid, entry in self._subscribers.items()
+                if entry['client_info'] == client_info
+            ]
+            for cid in stale:
+                self._subscribers.pop(cid, None)
+        if stale:
+            logger.info(
+                f"[QuoteEvent] 清理断开客户端的订阅者: client={client_info} "
+                f"removed={len(stale)} total={len(self._subscribers)}"
+            )
+
+    def get_subscription_seq(self, client_info: Optional[str], code_key):
+        """查该 client 是否已订阅过 code_key，返回旧 seq（未订阅返回 None）。"""
+        with self._lock:
+            subs = self._subscriptions.get(client_info)
+            if subs:
+                return subs.get(code_key)
+        return None
+
+    def record_subscription(self, client_info: Optional[str], code_key, seq):
+        """记录该 client 对 code_key 的最新订阅 seq（供下次重复订阅时先释放旧 seq）。"""
+        if client_info is None or seq is None:
+            return
+        with self._lock:
+            self._subscriptions.setdefault(client_info, {})[code_key] = seq
+
+    def clear_client_subscriptions(self, client_info: Optional[str], unsubscribe_func):
+        """清理该 client 的所有 miniquote 订阅（unsubscribe 所有 seq），on_disconnect 调用。"""
+        if client_info is None:
+            return
+        with self._lock:
+            subs = self._subscriptions.pop(client_info, None)
+        if not subs:
+            return
+        for seq in subs.values():
+            try:
+                unsubscribe_func(seq)
+            except Exception as exc:
+                logger.warning(f"[QuoteEvent] 清理订阅失败 seq={seq}: {exc}")
+        logger.info(
+            f"[QuoteEvent] 清理断开客户端的订阅: client={client_info} removed={len(subs)}"
+        )
+
+    def _maybe_warn_subscriber_count(self):
+        """订阅者数量超过水位时打 warning（回落时复位，便于反复告警）。"""
+        n = len(self._subscribers)
+        if n > self._max_subscribers_warning:
+            if not self._warned:
+                self._warned = True
+                logger.warning(
+                    f"[QuoteEvent] 订阅者数量异常: total={n} "
+                    f"(阈值 {self._max_subscribers_warning})，可能存在回调泄漏"
+                )
+        elif self._warned:
+            self._warned = False
+
     def stop(self):
         self._running = False
 
@@ -634,6 +718,40 @@ _QUOTE_SUBSCRIBE_CALLBACK_POS = {
 }
 
 
+# ==================== 服务实例标识 ====================
+
+# server 进程启动时生成的唯一标识，用于让客户端轻量感知 server 重启：
+# 客户端通过 get_instance_id() 对比该值，一旦变化说明 server 重启过，
+# 内存态的订阅/回调状态已丢失，需要重新订阅。避免用「重复订阅 + seq 回退」
+# 这种重且带副作用的方式探测重启（曾导致 miniquote 订阅累积泄漏）。
+_INSTANCE_ID = uuid.uuid4().hex
+
+
+def _normalize_code_key(code_list) -> tuple:
+    """把订阅的 code_list 规范化为可哈希的元组，用于订阅幂等去重。
+
+    subscribe_whole_quote 的 code_list 是 list（如 ['688523.SH'] / ['SH','SZ']），
+    subscribe_quote/quote2 的 stock_code 是单个 str。统一转成排序后的 tuple。
+    """
+    if isinstance(code_list, (list, tuple, set)):
+        return tuple(sorted(str(c) for c in code_list))
+    if isinstance(code_list, str):
+        return (code_list,)
+    return (str(code_list),)
+
+
+def _unsubscribe_safely(target, seq):
+    """安全地取消一个 miniquote 订阅（unsubscribe_quote），失败不抛出。"""
+    if seq is None:
+        return
+    try:
+        unsubscribe = getattr(target, 'unsubscribe_quote', None)
+        if unsubscribe is not None:
+            unsubscribe(seq)
+    except Exception as exc:
+        logger.warning(f"[QuoteEvent] 取消旧订阅失败 seq={seq}: {exc}")
+
+
 # ==================== download 类调用超时隔离 ====================
 
 # 需要超时/线程隔离的 download 类方法名（盘后券商挂起会永久阻塞 worker 线程）
@@ -655,6 +773,15 @@ def _get_download_timeout() -> int:
 DOWNLOAD_TIMEOUT_SECONDS = _get_download_timeout()
 
 
+def _get_max_quote_subscribers() -> int:
+    """读取 quote 订阅者告警水位，默认 500，可用 env XQSHARE_MAX_QUOTE_SUBSCRIBERS 覆盖。"""
+    raw = os.environ.get("XQSHARE_MAX_QUOTE_SUBSCRIBERS", "500")
+    try:
+        return int(raw)
+    except (TypeError, ValueError):
+        return 500
+
+
 def _call_download_with_timeout(fn, *args, timeout=None, name=None, **kwargs):
     """在独立 daemon 线程执行下载，主线程带超时等待。
 
@@ -752,6 +879,7 @@ class LoggingProxy:
         if callable(attr):
             def wrapper(*args, **kwargs):
                 full_name = f"{target_name}.{name}"
+                _sub_key = None  # 订阅幂等：本次调用的 code_key，供 _log_call 后记录 seq
 
                 # 权限检查
                 if permission_checker and account_level:
@@ -788,20 +916,30 @@ class LoggingProxy:
                 if target_name == 'xtdata' and quote_event_callback is not None:
                     if name in _QUOTE_SUBSCRIBE_CALLBACK_POS:
                         pos = _QUOTE_SUBSCRIBE_CALLBACK_POS[name]
+                        # 订阅幂等：提取 code_key（方法名 + 规范化 code_list），
+                        # 同一 client 重复订阅时先 unsubscribe 旧 seq，避免 miniquote 累积。
+                        _code_list = _deliver(args[0]) if args else kwargs.get('stock_code')
+                        if _code_list is not None:
+                            _sub_key = (name, _normalize_code_key(_code_list))
                         client_callback = kwargs.pop('callback', None)
                         if client_callback is not None:
-                            # 客户端传了接收器（netref），注册到路由器
-                            quote_event_callback.register(client_callback)
+                            # 客户端传了接收器（netref），注册到路由器（带 client_info 供断线清理）
+                            quote_event_callback.register(client_callback, get_client_info())
                             kwargs['callback'] = quote_event_callback
                         elif len(args) > pos:
                             args = list(args)
                             if args[pos] is not None:
-                                quote_event_callback.register(args[pos])
+                                quote_event_callback.register(args[pos], get_client_info())
                             args[pos] = quote_event_callback
                             args = tuple(args)
                         else:
                             # 未传回调：仍用服务端路由器接管（此时无订阅者，数据被丢弃）
                             kwargs['callback'] = quote_event_callback
+                        # 幂等：重复订阅先释放旧 seq（失败不阻断本次订阅）
+                        if _sub_key is not None:
+                            old_seq = quote_event_callback.get_subscription_seq(get_client_info(), _sub_key)
+                            if old_seq is not None:
+                                _unsubscribe_safely(target, old_seq)
 
                 # download 类调用统一加超时隔离：对直通底层 xtquant 的 download
                 # 方法（无 exposed_* 封装的）包进 _call_download_with_timeout，
@@ -814,6 +952,12 @@ class LoggingProxy:
                 else:
                     result = _log_call(full_name, get_client_info(), attr, *args, **kwargs)
 
+                # 订阅幂等：记录本次订阅返回的 seq，供下次重复订阅时先释放旧 seq
+                if _sub_key is not None:
+                    _seq = _deliver(result)
+                    if isinstance(_seq, int):
+                        quote_event_callback.record_subscription(get_client_info(), _sub_key, _seq)
+
                 # 如果返回的是复杂对象（非基本类型），递归包装
                 if result is not None and hasattr(result, '__class__'):
                     if not isinstance(result, (int, float, str, bool, list, dict, tuple, type(None), bytes)):
@@ -915,9 +1059,21 @@ class XtQuantService(rpyc.Service):
     def on_disconnect(self, conn):
         client_info = getattr(self, '_client_info', 'unknown')
         logger.info(f"[断开] 客户端离开: {client_info}")
-        # 自动清理本次连接创建的所有 trader 实例，防止 session 资源泄漏
+        # 清理本连接注册的 quote 行情回调（根因：netref 随重连累积，只进不出）
+        qec = XtQuantService._quote_event_callback
+        if qec is not None:
+            qec.clear_client_callbacks(client_info)
+            # 清理本连接向 miniquote 建立的所有订阅（unsubscribe 所有 seq），
+            # 避免 miniquote 侧订阅累积泄漏（根因：反复订阅不取消）。
+            qec.clear_client_subscriptions(
+                client_info,
+                lambda seq: _unsubscribe_safely(XtQuantService._xtdata, seq),
+            )
+        # 自动清理本次连接创建的所有 trader 实例及其事件路由器，
+        # 含停止 _TraderEventCallback 的 dispatch daemon 线程（否则线程持
+        # 有回调对象与 netref，随断线累积泄漏）
         traders = getattr(self, '_traders', [])
-        for trader in traders:
+        for trader, event_callback in traders:
             # disconnect() 在部分 xtquant 版本中不存在，仅作可选清理
             if hasattr(trader, 'disconnect'):
                 try:
@@ -930,6 +1086,12 @@ class XtQuantService(rpyc.Service):
                 logger.info(f"[清理Trader] 已自动 stop trader | client={client_info}")
             except Exception as e:
                 logger.warning(f"[清理Trader] stop trader 失败: {e} | client={client_info}")
+            if event_callback is not None and hasattr(event_callback, 'stop'):
+                try:
+                    event_callback.stop()
+                    logger.info(f"[清理Trader] 已停止事件路由器线程 | client={client_info}")
+                except Exception as e:
+                    logger.warning(f"[清理Trader] 停止事件路由器线程失败: {e} | client={client_info}")
 
     def _delayed_disconnect(self, delay: float = 0.5):
         """延迟断开连接，确保异常能传输到客户端"""
@@ -976,6 +1138,16 @@ class XtQuantService(rpyc.Service):
     def exposed_heartbeat(self):
         return "pong"
 
+    @log_api_call("get_instance_id")
+    def exposed_get_instance_id(self):
+        """返回本 server 进程的实例标识。
+
+        供客户端轻量感知 server 重启：该值在每次 server 进程启动时变化。
+        客户端可周期性对比（例如复用现有 heartbeat 流程或单独轮询），
+        一旦变化即说明订阅/回调等内存态已丢失，需要重新订阅。
+        """
+        return _INSTANCE_ID
+
     # ==================== 模块代理接口 ====================
 
     @log_api_call("get_xtdata")
@@ -1098,13 +1270,13 @@ class XtQuantService(rpyc.Service):
 
         logger.info(f"[创建Trader] userdata_path={userdata_path} | session_id={session_id}")
 
-        # 记录 trader 实例，供 on_disconnect 时自动清理
-        self._traders.append(trader)
-
         # 每个 trader 独立一个事件路由器，用于把 on_stock_* 推送给远端客户端
         event_callback = _TraderEventCallback()
         trader.register_callback(event_callback)
 
+        # 记录 trader + 事件路由器，供 on_disconnect 时自动清理（含停止线程）
+        self._traders.append((trader, event_callback))
+
         # 用 LoggingProxy 包装 trader，支持日志记录、序列化和事件回调透传
         return LoggingProxy(
             trader, 'xttrader',
@@ -1143,8 +1315,8 @@ class XtQuantService(rpyc.Service):
         )
         trader.register_callback(adapter)
 
-        # 记录 trader 实例，供 on_disconnect 时自动清理
-        self._traders.append(trader)
+        # 记录 trader + 事件路由器，供 on_disconnect 时自动清理（含停止线程）
+        self._traders.append((trader, event_callback))
 
         return LoggingProxy(
             trader, 'xttrader',
@@ -1176,18 +1348,23 @@ class XtQuantService(rpyc.Service):
 
         logger.info(f"[创建并连接大QMT Trader] account_id={account_id} | session_id={session_id}")
 
-        start_result = trader.start()
-        logger.info(f"[大QMT Trader] start() 返回: {start_result}")
-        if start_result not in (0, None):
-            raise RuntimeError(f"启动大QMT 交易线程失败，错误码: {start_result}")
-
-        # bigqmt connect() 同步：内部 RPC ping + 合成 on_account_status；失败抛异常
-        connect_result = trader.connect()
-        logger.info(f"[大QMT Trader] connect() 返回: {connect_result}")
-        if connect_result not in (0, None):
-            raise ConnectionError(f"大QMT 连接失败: 错误码 {connect_result}")
+        try:
+            start_result = trader.start()
+            logger.info(f"[大QMT Trader] start() 返回: {start_result}")
+            if start_result not in (0, None):
+                raise RuntimeError(f"启动大QMT 交易线程失败，错误码: {start_result}")
+
+            # bigqmt connect() 同步：内部 RPC ping + 合成 on_account_status；失败抛异常
+            connect_result = trader.connect()
+            logger.info(f"[大QMT Trader] connect() 返回: {connect_result}")
+            if connect_result not in (0, None):
+                raise ConnectionError(f"大QMT 连接失败: 错误码 {connect_result}")
+        except Exception:
+            # 失败路径也要停止事件路由器线程，避免泄漏
+            event_callback.stop()
+            raise
 
-        self._traders.append(trader)
+        self._traders.append((trader, event_callback))
 
         return LoggingProxy(
             trader, 'xttrader',
@@ -1247,48 +1424,56 @@ class XtQuantService(rpyc.Service):
 
         logger.info(f"[创建并连接Trader] userdata_path={userdata_path} | session_id={session_id}")
 
-        start_result = trader.start()
-        logger.info(f"[Trader] start() 返回: {start_result}")
-        if start_result not in (0, None):
-            raise RuntimeError(f"启动交易线程失败，错误码: {start_result}")
-
-        connect_result = trader.connect()
-        logger.info(f"[Trader] connect() 返回: {connect_result}")
-        if connect_result not in (0, None):
-            error_codes = {
-                -1: "交易服务器未连接",
-                -2: "账号未登录",
-                -3: "请求超时",
-                -4: "资金账号不存在",
-            }
-            raise ConnectionError(f"连接失败: {error_codes.get(connect_result, f'错误码 {connect_result}')}")
-
-        # 等待真实的交易连接建立
-        connected = callback.wait_for_connected(connect_timeout)
-        logger.info(f"[Trader] on_connected 回调状态: {connected}")
-        if not connected:
-            # 某些版本的 xtquant 可能不会触发 on_connected 回调，
-            # 尝试用 query_stock_asset 验证连接是否真正可用
-            logger.info("[Trader] on_connected 未触发，尝试 query_stock_asset 验证连接...")
-            try:
-                from xtquant.xttype import StockAccount
-                account_id = os.environ.get("QMT_ACCOUNT_ID")
-                if account_id:
-                    test_account = StockAccount(account_id)
-                    asset = trader.query_stock_asset(test_account)
-                    logger.info(f"[Trader] query_stock_asset 验证成功: {asset}")
-                    connected = True
-            except Exception as e:
-                logger.warning(f"[Trader] query_stock_asset 验证失败: {e}")
+        try:
+            start_result = trader.start()
+            logger.info(f"[Trader] start() 返回: {start_result}")
+            if start_result not in (0, None):
+                raise RuntimeError(f"启动交易线程失败，错误码: {start_result}")
+
+            connect_result = trader.connect()
+            logger.info(f"[Trader] connect() 返回: {connect_result}")
+            if connect_result not in (0, None):
+                error_codes = {
+                    -1: "交易服务器未连接",
+                    -2: "账号未登录",
+                    -3: "请求超时",
+                    -4: "资金账号不存在",
+                }
+                raise ConnectionError(f"连接失败: {error_codes.get(connect_result, f'错误码 {connect_result}')}")
+
+            # 等待真实的交易连接建立
+            connected = callback.wait_for_connected(connect_timeout)
+            logger.info(f"[Trader] on_connected 回调状态: {connected}")
+            if not connected:
+                # 某些版本的 xtquant 可能不会触发 on_connected 回调，
+                # 尝试用 query_stock_asset 验证连接是否真正可用
+                logger.info("[Trader] on_connected 未触发，尝试 query_stock_asset 验证连接...")
+                try:
+                    from xtquant.xttype import StockAccount
+                    account_id = os.environ.get("QMT_ACCOUNT_ID")
+                    if account_id:
+                        test_account = StockAccount(account_id)
+                        asset = trader.query_stock_asset(test_account)
+                        logger.info(f"[Trader] query_stock_asset 验证成功: {asset}")
+                        connected = True
+                except Exception as e:
+                    logger.warning(f"[Trader] query_stock_asset 验证失败: {e}")
 
-        if not connected:
-            trader.stop()
-            raise TimeoutError(
-                f"等待交易连接建立超时（{connect_timeout}秒），"
-                "请检查 MiniQMT 是否已登录交易账号，或设置更长的 --connect-timeout"
-            )
+            if not connected:
+                raise TimeoutError(
+                    f"等待交易连接建立超时（{connect_timeout}秒），"
+                    "请检查 MiniQMT 是否已登录交易账号，或设置更长的 --connect-timeout"
+                )
+        except Exception:
+            # 失败路径：停止 trader 与事件路由器线程，避免泄漏
+            try:
+                trader.stop()
+            except Exception:
+                pass
+            callback.stop()
+            raise
 
-        self._traders.append(trader)
+        self._traders.append((trader, callback))
 
         return LoggingProxy(
             trader, 'xttrader',

{xtquant_share-1.3.0 → xtquant_share-1.4.0/xtquant_share.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xtquant-share
-Version: 1.3.0
+Version: 1.4.0
 Summary: Xtreme Quant Share - eXtreme transparent sharing proxy for XtQuant on macOS/Linux
 Author-email: Jason Hu <63170682@qq.com>
 License-Expression: GPL-3.0-only
@@ -50,6 +50,7 @@ Dynamic: license-file
 - ✅ **认证加密** - 支持 HMAC token 认证，可选 SSL/TLS 加密
 - ✅ **断线重连** - 自动检测断线并重连，指数退避策略
 - ✅ **心跳保活** - 定期心跳检测，保持连接活跃
+- ✅ **服务实例标识** - `get_instance_id()` 轻量感知 server 重启；行情订阅幂等自动去重，阻断底层 miniquote 订阅累积
 - ✅ **异步回调** - 支持交易事件（on_stock_*）与行情 tick 订阅回调（`xtdata.register_quote_callback` + `subscribe_whole_quote`）
 - ✅ **无感切换** - 大QMT ↔ miniQMT 无感切换（行情侧），自动探测 miniQMT 可用性，不可用自动切 bigqmt 通道（复用 xtquant_big_convert）
 - ✅ **完整日志** - API调用日志，记录函数名、参数、耗时
@@ -801,6 +802,7 @@ print(status)
 
 | 版本 | 日期 | 更新内容 |
 |------|------|----------|
+| 1.4.0 | 2026-10-03 | 新增 `get_instance_id()` 服务实例标识（轻量感知 server 重启）；行情订阅幂等（重复订阅自动释放旧 seq，阻断 miniquote 订阅累积泄漏） |
 | 1.1.1 | 2026-03-18 | 新增 xtview 模块支持（视图控制、调度任务管理），兼容不同 xtquant 版本 |
 | 1.1.0 | 2026-03-17 | 交易功能优化完善、`xqshare-server` 命令、`.env` 配置支持、远程对象传输性能优化 |
 | 1.0.4 | 2026-03-09 | JSON 输出优化：远程 DataFrame 高效序列化、`--compact` 参数、全局参数位置灵活、嵌套结构支持 |