crewplus 0.3.4__tar.gz → 0.3.5__tar.gz

{crewplus-0.3.4 → crewplus-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: crewplus
-Version: 0.3.4
+Version: 0.3.5
 Summary: Base services for CrewPlus AI applications
 Author-Email: Tim Liu <tim@opsmateai.com>
 License: MIT

{crewplus-0.3.4 → crewplus-0.3.5}/crewplus/vectorstores/milvus/vdb_service.py

@@ -5,7 +5,9 @@
 # @Last Modified time: 2025-10-09
 
 import asyncio
+import hashlib
 import logging
+import threading
 import time
 import uuid
 from collections import defaultdict
@@ -99,19 +101,42 @@ class VDBService(object):
     """
     _client: MilvusClient
     _async_client: Optional[AsyncMilvusClient] = None
+    # `_instances` / `_async_instances` 的 key 是 f"{conn_key}:{collection_name}"，
+    # 不是裸 collection_name。历史上只用 collection_name 且本 dict 是类级共享的，
+    # 于是「同名 collection 分处两个 Zilliz 集群」时后来者会拿到前者的 store —— 数据被
+    # 静默写进别的租户的集群。加上 conn_key 前缀后该情形结构上不可能发生。
+    # 构造 key 一律走 self._instance_key()，不要手写拼接。
     _instances: Dict[str, Milvus] = {}
     _async_instances: Dict[str, Milvus] = {}
     _async_instance_locks: Dict[str, asyncio.Lock] = defaultdict(asyncio.Lock)
 
+    # 进程级 MilvusClient 缓存：同一组连接参数只建一条 gRPC 连接。
+    #
+    # 必须显式判缓存，不能只靠「固定别名」：pymilvus 的 connections.connect() 对已存在的
+    # 别名不做复用 —— 只校验地址是否一致，随后照样新建 GrpcHandler 并覆盖注册表，旧
+    # handler 既不 close 也不再可达。
+    #
+    # 为什么需要：VDBService.__init__ 每次都会真去建一条连接并注册进 pymilvus 的进程级
+    # 全局单例，而本包从不 disconnect；worker 用 --pool=threads，Celery 的
+    # worker_max_tasks_per_child 只支持 prefork，进程从不回收。于是「每任务一个
+    # VDBService」= 每任务一条新连接，批量摄取/删除时建连速率会打到每秒十几次，压垮网络
+    # 路径上的 per-pod/per-node 资源（2026-08-14 / 08-16 两次生产事故，单次建连失败率 57%）。
+    _clients: Dict[str, MilvusClient] = {}
+    # 每个 alias 一把创建锁：建连是网络 I/O（超时+退避最长 ~21s），不能让 A 集群的慢建连
+    # 阻塞 B 集群的首次建连。_clients_meta_lock 只保护锁字典本身（纯内存，微秒级）。
+    # 同一写法的先例：crewplus-search 的 _store_cache_key_locks。
+    _client_locks: Dict[str, threading.Lock] = {}
+    _clients_meta_lock = threading.Lock()
+
     schema: str
     embedding_function: Embeddings
     index_params: dict
     connection_args: dict
     settings: dict
     
-    def __init__(self, settings: dict = None, endpoint: str = None, token: str = None, schema: str = None, logger: logging.Logger = None):
+    def __init__(self, settings: dict = None, endpoint: str = None, token: str = None, schema: str = None, logger: logging.Logger = None, reuse_connection: bool = True):
         """
-        Initializes the VDBService. 
+        Initializes the VDBService.
 
         Can be initialized in two ways:
         1. By providing a full `settings` dictionary for complex configurations.
@@ -126,6 +151,9 @@ class VDBService(object):
             token (str, optional): The token for authenticating with the Zilliz cluster.
             schema (str, optional): Default schema for new collections. Defaults to None.
             logger (logging.Logger, optional): Logger instance. Defaults to None.
+            reuse_connection (bool): 是否复用进程内已有的同参数连接。默认 True。
+                传 False 恢复旧行为（本实例独占一条连接、不进进程缓存），仅作为出问题时
+                无需回滚包版本的逃生口 —— 正常情况下不应有人传它。
         """
         self.logger = logger or logging.getLogger(__name__)
         self.collection_schema = None
@@ -162,9 +190,20 @@ class VDBService(object):
 
         self._provider = provider # Store provider for lazy initialization
 
-        # Create separate aliases for sync and async clients to avoid connection handler race conditions.
-        self.sync_alias = f"crewplus-vdb-sync-{uuid.uuid4()}"
-        self.async_alias = f"crewplus-vdb-async-{uuid.uuid4()}"
+        # 别名从「每实例一个 uuid4」改为「按连接参数派生」。
+        #
+        # uuid4 别名让每个实例都往 pymilvus 的进程级注册表里塞一条独立连接，而且
+        # langchain_milvus 会把 connection_args['alias'] 原样传给它自己的 MilvusClient
+        # （langchain_milvus 0.2.1: self._milvus_client = MilvusClient(**connection_args)），
+        # 所以别名不稳定时 get_vector_store 也会各建各的连接。派生别名后，主 client 与所有
+        # langchain Milvus 实例落在同一个别名上，稳态下每个连接键只有一条活连接。
+        #
+        # 一个变量控制全部行为：reuse_connection=False 时 conn_key 取随机值 —— 别名与
+        # _instances 前缀的生成方式保持单一，逃生口不引入第二条代码路径。
+        self._reuse_connection = reuse_connection
+        self._conn_key = self._connection_key(provider) if reuse_connection else uuid.uuid4().hex
+        self.sync_alias = f"crewplus-vdb-sync-{self._conn_key}"
+        self.async_alias = f"crewplus-vdb-async-{self._conn_key}"
 
         # The default alias in connection_args should be the sync one, as langchain_milvus
         # primarily uses a synchronous client and will pick up this alias.
@@ -220,25 +259,79 @@ class VDBService(object):
             self.logger.error(f"Unsupported vector store provider: {provider}")
             raise NotImplementedError(f"Vector store provider '{provider}' is not supported.")
 
-    def _initialize_milvus_client(self, provider: str) -> MilvusClient:
+    def _connection_key(self, provider: str) -> str:
+        """由连接身份派生的稳定 key：参数相同 -> 复用同一条连接。
+
+        token/password 必须纳入 —— 凭据不同必须走不同连接，否则跨租户串凭据。用 sha256
+        截断而不是明文，是因为该 key 会被拼进 alias，而 alias 会出现在 INFO 日志里。
+        channel_options 刻意不纳入：它是常量（gRPC keepalive 参数），只会让 key 变长。
         """
-        Initializes and returns a MilvusClient with a retry mechanism.
+        args = self._get_milvus_client_args(provider)
+        parts = [
+            provider,
+            str(args.get("uri") or ""),
+            str(args.get("host") or ""),
+            str(args.get("port") or ""),
+            str(args.get("db_name") or ""),
+            str(args.get("user") or ""),
+            str(args.get("token") or args.get("password") or ""),
+        ]
+        return hashlib.sha256("|".join(parts).encode("utf-8")).hexdigest()[:32]
+
+    def _instance_key(self, collection_name: str) -> str:
+        """`_instances` / `_async_instances` 的缓存 key。
+
+        带 conn_key 前缀，让同名 collection 在不同集群/不同凭据下互不串用。
         """
+        return f"{self._conn_key}:{collection_name}"
+
+    def _create_milvus_client(self, provider: str, alias: str) -> MilvusClient:
+        """真正建连（含一次带退避的重试）。是否缓存由调用方决定。"""
         client_args = self._get_milvus_client_args(provider)
-        client_args["alias"] = self.sync_alias
+        client_args["alias"] = alias
 
         try:
             # First attempt to connect
             return MilvusClient(**client_args)
         except Exception as e:
             self.logger.error(f"Failed to initialize MilvusClient, trying again. Error: {e}")
-            # Second attempt after failure
+            # 退避后再试。原来是紧贴着重打，实测第二次成功率仅 9.6%（08-16：2105 次首次
+            # 失败里只有 201 次被第二次救回），却把建连总量放大了 30% —— 在一个「建连速率
+            # 就是病因」的故障里等于浇油。与异步版保持一致，睡 1 秒。
+            time.sleep(1)
             try:
                 return MilvusClient(**client_args)
             except Exception as e_retry:
                 self.logger.error(f"Failed to initialize MilvusClient on retry. Final error: {e_retry}")
                 raise RuntimeError(f"Could not initialize MilvusClient after retry: {e_retry}")
 
+    @classmethod
+    def _get_client_lock(cls, alias: str) -> threading.Lock:
+        with cls._clients_meta_lock:
+            return cls._client_locks.setdefault(alias, threading.Lock())
+
+    def _initialize_milvus_client(self, provider: str) -> MilvusClient:
+        """返回本进程内该连接参数对应的 MilvusClient，没有则建一条并缓存。"""
+        alias = self.sync_alias
+
+        if not self._reuse_connection:
+            # 逃生口：旧行为。刻意不写入 _clients —— 每实例一条缓存条目才是真泄漏。
+            return self._create_milvus_client(provider, alias)
+
+        cached = VDBService._clients.get(alias)  # 快路径：CPython 下 dict.get 是原子操作
+        if cached is not None:
+            return cached
+
+        with VDBService._get_client_lock(alias):  # 只串行化同一 alias 的并发首建
+            cached = VDBService._clients.get(alias)  # 双检：并发涌入的线程只让一个真去建
+            if cached is not None:
+                return cached
+
+            client = self._create_milvus_client(provider, alias)
+            VDBService._clients[alias] = client
+            self.logger.info(f"MilvusClient created and cached, alias={alias}")
+            return client
+
     def _initialize_async_milvus_client(self, provider: str) -> AsyncMilvusClient:
         """
         Initializes and returns an AsyncMilvusClient with a retry mechanism.
@@ -283,6 +376,34 @@ class VDBService(object):
             self._async_client = AsyncMilvusClient(**client_args)
         return self._async_client
 
+    def close(self) -> None:
+        """作废本连接：移出进程缓存、断开、并清掉挂在它上面的 langchain 实例。
+
+        只在确认连接不可用时调用。这条连接是进程内共享的，关掉会影响所有正在用同一
+        endpoint+凭据的调用方 —— 它们会在下次构造 VDBService 时自动重建，所以是安全的，
+        代价只是多一次握手。
+
+        为什么需要它：`_instances` 历史上只在 drop_collection 里被删过，没有健康检查也没有
+        TTL，一条坏掉的 langchain Milvus 实例会被后续所有任务无条件复用，把整个 pod 的剩余
+        生命周期拖死。这是既有缺陷（与连接复用无关），此处一并补上补救路径。
+        """
+        with VDBService._get_client_lock(self.sync_alias):
+            VDBService._clients.pop(self.sync_alias, None)
+            try:
+                connections.disconnect(self.sync_alias)
+            except Exception as e:
+                self.logger.warning(f"disconnect({self.sync_alias}) failed: {e}")
+
+            # 只清本连接键下的实例，别动其他租户的
+            prefix = f"{self._conn_key}:"
+            for cache in (VDBService._instances, VDBService._async_instances):
+                for k in [k for k in cache if k.startswith(prefix)]:
+                    cache.pop(k, None)
+
+        self._client = None
+        self._async_client = None
+        self.logger.info(f"VDBService connection closed and evicted, alias={self.sync_alias}")
+
     def get_vector_field(self, collection_name: str) -> str:
         """
         Retrieves the vector field name for a given collection from a cached instance.
@@ -296,10 +417,11 @@ class VDBService(object):
         Raises:
             ValueError: If no cached instance is found for the collection.
         """
-        if collection_name in self._instances:
-            return self._instances[collection_name]._vector_field
-        if collection_name in self._async_instances:
-            return self._async_instances[collection_name]._vector_field
+        cache_key = self._instance_key(collection_name)
+        if cache_key in self._instances:
+            return self._instances[cache_key]._vector_field
+        if cache_key in self._async_instances:
+            return self._async_instances[cache_key]._vector_field
         
         self.logger.warning(f"No cached instance found for collection '{collection_name}' to get vector field. Creating a temporary sync instance.")
         # As a fallback, create a temporary sync instance to fetch the schema info.
@@ -516,9 +638,10 @@ class VDBService(object):
             raise ValueError("collection_name must be provided.")
 
         # Check for a cached instance. If found, return it immediately.
-        if collection_name in self._instances:
+        cache_key = self._instance_key(collection_name)
+        if cache_key in self._instances:
             self.logger.info(f"Returning existing vector store instance for collection: {collection_name}")
-            return self._instances[collection_name]
+            return self._instances[cache_key]
 
         self.logger.info(f"Creating new vector store instance for collection: {collection_name}")
         if embeddings is None:
@@ -555,7 +678,7 @@ class VDBService(object):
         )
 
         # Cache the newly created instance.
-        self._instances[collection_name] = vdb
+        self._instances[cache_key] = vdb
 
         return vdb
 
@@ -584,11 +707,13 @@ class VDBService(object):
             self.logger.error("aget_vector_store called with no collection_name.")
             raise ValueError("collection_name must be provided.")
 
-        lock = self._async_instance_locks[collection_name]
+        # 锁也按 conn_key 分片：不同集群的同名 collection 不该互相阻塞。
+        cache_key = self._instance_key(collection_name)
+        lock = self._async_instance_locks[cache_key]
         async with lock:
-            if collection_name in self._async_instances:
+            if cache_key in self._async_instances:
                 self.logger.info(f"Returning existing async vector store instance for collection: {collection_name} (post-lock)")
-                return self._async_instances[collection_name]
+                return self._async_instances[cache_key]
 
             self.logger.info(f"Creating new async vector store instance for collection: {collection_name}")
             if embeddings is None:
@@ -612,7 +737,7 @@ class VDBService(object):
             self.logger.info(f"Swapping to async alias for instance of collection {collection_name}")
             vdb.aclient._using = self.async_alias
 
-            self._async_instances[collection_name] = vdb
+            self._async_instances[cache_key] = vdb
             return vdb
 
     async def _acreate_milvus_instance_with_retry(
@@ -638,12 +763,17 @@ class VDBService(object):
                     # --- START: CRITICAL FIX ---
                     # Manually connect within the thread before creating the Milvus instance.
                     # This ensures pymilvus registers the connection details for the current thread.
-                    try:
-                        connections.connect(**conn_args)
-                        self.logger.info(f"Successfully connected to Milvus with alias '{self.sync_alias}' in thread.")
-                    except Exception as e:
-                        self.logger.error(f"Failed to manually connect in thread: {e}")
-                        raise
+                    #
+                    # 已有同名连接就直接复用：pymilvus 的 connect() 对已存在的别名不做复用，
+                    # 只校验地址一致，随后照样新建 GrpcHandler 并覆盖注册表 —— 会把
+                    # _clients 里缓存的那条主连接的 handler 顶掉（旧的既不 close 也不再可达）。
+                    if not connections.has_connection(self.sync_alias):
+                        try:
+                            connections.connect(**conn_args)
+                            self.logger.info(f"Successfully connected to Milvus with alias '{self.sync_alias}' in thread.")
+                        except Exception as e:
+                            self.logger.error(f"Failed to manually connect in thread: {e}")
+                            raise
 
                     # Now, creating the Milvus instance will find the existing connection via the alias.
                     instance = Milvus(
@@ -729,8 +859,9 @@ class VDBService(object):
             raise RuntimeError(f"An error occurred while dropping collection '{collection_name}'.") from e
         finally:
             # Whether successful or not, remove the stale instance from the cache.
-            if collection_name in self._instances:
-                del self._instances[collection_name]
+            cache_key = self._instance_key(collection_name)
+            if cache_key in self._instances:
+                del self._instances[cache_key]
                 self.logger.info(f"Removed '{collection_name}' from instance cache.")
 
     async def adrop_collection(self, collection_name: str) -> None:
@@ -759,8 +890,9 @@ class VDBService(object):
             raise RuntimeError(f"An error occurred while dropping collection '{collection_name}' asynchronously.") from e
         finally:
             # Whether successful or not, remove the stale instance from the cache.
-            if collection_name in self._async_instances:
-                del self._async_instances[collection_name]
+            cache_key = self._instance_key(collection_name)
+            if cache_key in self._async_instances:
+                del self._async_instances[cache_key]
                 self.logger.info(f"Removed '{collection_name}' from instance cache.")
 
     def delete_data_by_filter(self, collection_name: str = None, filter: str = None) -> None:

{crewplus-0.3.4 → crewplus-0.3.5}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "crewplus"
-version = "0.3.4"
+version = "0.3.5"
 description = "Base services for CrewPlus AI applications"
 authors = [
     { name = "Tim Liu", email = "tim@opsmateai.com" },

crewplus-0.3.5/tests/test_vdb_service_connection_reuse.py

@@ -0,0 +1,189 @@
+# -*- coding: utf-8 -*-
+"""VDBService 连接复用与缓存隔离的回归测试。
+
+背景：2026-08-14 / 08-16 两次生产事故。VDBService.__init__ 每次都会真去建一条 gRPC 连接并
+注册进 pymilvus 的进程级全局单例，而本包从不 disconnect；worker 用 --pool=threads，Celery 的
+worker_max_tasks_per_child 只支持 prefork，进程从不回收。结果「每任务一个 VDBService」= 每
+任务一条新连接，批量摄取/删除时建连速率打到每秒十几次，单次建连失败率 57%。
+
+这些测试锁住三件事，防止改回去：
+1. 同参数构造 N 次只建 1 条连接；
+2. 不同 endpoint / 不同 token 绝不共享连接（凭据隔离）；
+3. `_instances` 的 key 带连接身份 —— 同名 collection 分处两个集群时不会串数据。
+
+全部用 mock，不碰真实 Milvus。
+"""
+import threading
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from crewplus.vectorstores.milvus.vdb_service import VDBService
+
+
+ENDPOINT_A = "https://in01-aaaaaaaaaaaaaaa.az-eastus2.vectordb.zillizcloud.com:19530"
+ENDPOINT_B = "https://in01-bbbbbbbbbbbbbbb.az-eastus2.vectordb.zillizcloud.com:19530"
+TOKEN_A = "token-tenant-a"
+TOKEN_B = "token-tenant-b"
+
+
+@pytest.fixture(autouse=True)
+def _clean_process_caches():
+    """每个用例前后清空类级缓存 —— 它们是进程级的，会跨用例串。"""
+    VDBService._clients.clear()
+    VDBService._instances.clear()
+    VDBService._async_instances.clear()
+    yield
+    VDBService._clients.clear()
+    VDBService._instances.clear()
+    VDBService._async_instances.clear()
+
+
+@pytest.fixture
+def milvus_client_factory():
+    """替换 MilvusClient，返回每次调用都不同的 mock，并记录调用次数。"""
+    with patch("crewplus.vectorstores.milvus.vdb_service.MilvusClient") as m:
+        m.side_effect = lambda **kwargs: MagicMock(name=f"client-{m.call_count}")
+        yield m
+
+
+def test_same_params_build_one_connection(milvus_client_factory):
+    """同一组 endpoint+token 构造 50 次，只应真建 1 条连接。"""
+    services = [VDBService(endpoint=ENDPOINT_A, token=TOKEN_A) for _ in range(50)]
+
+    assert milvus_client_factory.call_count == 1, (
+        "每次构造都建连 = 事故复现。连接数必须与构造次数解耦。"
+    )
+    # 50 个实例拿到的是同一个 client 对象
+    assert len({id(s._client) for s in services}) == 1
+    # 别名也必须稳定，否则 langchain_milvus 会照着新别名再建一条
+    assert len({s.sync_alias for s in services}) == 1
+    assert len(VDBService._clients) == 1
+
+
+def test_different_endpoint_never_shares_connection(milvus_client_factory):
+    """不同集群必须各自建连。"""
+    a = VDBService(endpoint=ENDPOINT_A, token=TOKEN_A)
+    b = VDBService(endpoint=ENDPOINT_B, token=TOKEN_A)
+
+    assert milvus_client_factory.call_count == 2
+    assert a.sync_alias != b.sync_alias
+    assert a._client is not b._client
+
+
+def test_different_token_never_shares_connection(milvus_client_factory):
+    """同集群但凭据不同也必须各自建连 —— 否则跨租户串凭据。"""
+    a = VDBService(endpoint=ENDPOINT_A, token=TOKEN_A)
+    b = VDBService(endpoint=ENDPOINT_A, token=TOKEN_B)
+
+    assert milvus_client_factory.call_count == 2, (
+        "token 必须参与连接键，否则 B 的写入会以 A 的凭据执行。"
+    )
+    assert a.sync_alias != b.sync_alias
+
+
+def test_token_not_leaked_into_alias(milvus_client_factory):
+    """别名会进 INFO 日志，明文 token 不许出现在里面。"""
+    svc = VDBService(endpoint=ENDPOINT_A, token=TOKEN_A)
+    assert TOKEN_A not in svc.sync_alias
+    assert TOKEN_A not in svc.async_alias
+
+
+def test_instance_cache_key_isolates_same_collection_across_clusters(milvus_client_factory):
+    """同名 collection 分处两个集群时，_instances 不许串。
+
+    这是数据安全项：串了会把一个租户的文件静默写进另一个租户的向量库。
+    """
+    a = VDBService(endpoint=ENDPOINT_A, token=TOKEN_A)
+    b = VDBService(endpoint=ENDPOINT_B, token=TOKEN_B)
+
+    collection = "cp_shared_name_2026081700ab"  # 迁移/恢复场景下两边会同名
+    store_a, store_b = MagicMock(name="store-a"), MagicMock(name="store-b")
+
+    with patch.object(VDBService, "_check_collection_exists", return_value=True), \
+         patch.object(VDBService, "_create_milvus_instance_with_retry", side_effect=[store_a, store_b]):
+        got_a = a.get_vector_store(collection, embeddings=MagicMock())
+        got_b = b.get_vector_store(collection, embeddings=MagicMock())
+
+    assert got_a is store_a
+    assert got_b is store_b, (
+        "B 拿到了 A 的 store —— 数据会被写进 A 的集群。缓存 key 必须带连接身份。"
+    )
+    assert len(VDBService._instances) == 2
+
+
+def test_same_cluster_same_collection_shares_instance(milvus_client_factory):
+    """同集群同 collection 仍应复用 —— 这才是缓存的本意。"""
+    a = VDBService(endpoint=ENDPOINT_A, token=TOKEN_A)
+    b = VDBService(endpoint=ENDPOINT_A, token=TOKEN_A)
+
+    collection = "cp_kb_2026081700ab"
+    store = MagicMock(name="store")
+
+    with patch.object(VDBService, "_check_collection_exists", return_value=True), \
+         patch.object(VDBService, "_create_milvus_instance_with_retry", return_value=store):
+        assert a.get_vector_store(collection, embeddings=MagicMock()) is store
+        assert b.get_vector_store(collection, embeddings=MagicMock()) is store
+
+    assert len(VDBService._instances) == 1
+
+
+def test_reuse_connection_false_restores_old_behavior(milvus_client_factory):
+    """逃生口：传 False 恢复独占连接，且不污染进程缓存。"""
+    a = VDBService(endpoint=ENDPOINT_A, token=TOKEN_A, reuse_connection=False)
+    b = VDBService(endpoint=ENDPOINT_A, token=TOKEN_A, reuse_connection=False)
+
+    assert milvus_client_factory.call_count == 2
+    assert a.sync_alias != b.sync_alias
+    assert VDBService._clients == {}, "退出口不得写入进程缓存，否则每实例一条才是真泄漏。"
+
+
+def test_close_evicts_client_and_instances(milvus_client_factory):
+    """close() 必须同时清掉客户端缓存和挂在该连接上的 langchain 实例。"""
+    svc = VDBService(endpoint=ENDPOINT_A, token=TOKEN_A)
+    other = VDBService(endpoint=ENDPOINT_B, token=TOKEN_B)
+
+    VDBService._instances[svc._instance_key("cp_x")] = MagicMock()
+    VDBService._instances[other._instance_key("cp_x")] = MagicMock()
+
+    with patch("crewplus.vectorstores.milvus.vdb_service.connections") as conns:
+        svc.close()
+        conns.disconnect.assert_called_once_with(svc.sync_alias)
+
+    assert svc.sync_alias not in VDBService._clients
+    assert svc._instance_key("cp_x") not in VDBService._instances
+    # 别动别的租户
+    assert other._instance_key("cp_x") in VDBService._instances
+    assert other.sync_alias in VDBService._clients
+
+
+def test_close_then_reconstruct_rebuilds(milvus_client_factory):
+    """close() 之后再构造应重新建连（失效路径可恢复）。"""
+    VDBService(endpoint=ENDPOINT_A, token=TOKEN_A).close()
+    VDBService(endpoint=ENDPOINT_A, token=TOKEN_A)
+    assert milvus_client_factory.call_count == 2
+
+
+def test_concurrent_construction_builds_one_connection(milvus_client_factory):
+    """50 线程并发构造（worker 是 --pool=threads --concurrency=50）只应建 1 条连接。"""
+    barrier = threading.Barrier(50)
+    results, errors = [], []
+
+    def worker():
+        try:
+            barrier.wait(timeout=10)
+            results.append(VDBService(endpoint=ENDPOINT_A, token=TOKEN_A))
+        except Exception as e:  # pragma: no cover
+            errors.append(e)
+
+    threads = [threading.Thread(target=worker) for _ in range(50)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join(timeout=20)
+
+    assert not errors, f"并发构造抛错: {errors}"
+    assert len(results) == 50
+    assert milvus_client_factory.call_count == 1, (
+        "双检锁失效：并发下建了多条连接。"
+    )