remote-cmd-manager 2.4.0__tar.gz → 2.6.0__tar.gz

{remote_cmd_manager-2.4.0/remote_cmd_manager.egg-info → remote_cmd_manager-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.4.0
+Version: 2.6.0
 Summary: Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more.
 Author-email: Vae-Scrooge <vaescrooge@gmail.com>
 License: MIT
@@ -15,7 +15,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -27,17 +26,17 @@ Classifier: Environment :: Console
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: Microsoft :: Windows
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: paramiko>=3.0
+Requires-Dist: paramiko<6,>=5.0
 Requires-Dist: click>=8.0
 Requires-Dist: cryptography>=41.0
 Requires-Dist: rich>=13.0
 Requires-Dist: PyYAML>=6.0
 Requires-Dist: aiofiles>=3.0
 Provides-Extra: async
-Requires-Dist: asyncssh>=2.14.0; extra == "async"
+Requires-Dist: asyncssh<3,>=2.24.0; extra == "async"
 Provides-Extra: cloud
 Requires-Dist: boto3>=1.34; extra == "cloud"
 Provides-Extra: dev
@@ -46,6 +45,7 @@ Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
 Requires-Dist: pytest-cov>=4.0; extra == "dev"
 Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: asyncssh<3,>=2.24.0; extra == "dev"
 Requires-Dist: keyring>=24.0; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: pdoc==15.0.4; extra == "docs"
@@ -55,7 +55,7 @@ Dynamic: license-file
   <img src="https://img.shields.io/pypi/v/remote_cmd_manager?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI" alt="PyPI">
   <img src="https://img.shields.io/pypi/dm/remote_cmd_manager?style=for-the-badge&logo=python&logoColor=white&label=Downloads" alt="Downloads">
   <img src="https://img.shields.io/github/stars/Vae-Scrooge/remote-cmd?style=for-the-badge&logo=github" alt="Stars">
-  <img src="https://img.shields.io/badge/python-3.9%2B-blue?style=for-the-badge&logo=python" alt="Python">
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python" alt="Python">
   <img src="https://img.shields.io/github/license/Vae-Scrooge/remote-cmd?style=for-the-badge" alt="License">
   <img src="https://img.shields.io/github/actions/workflow/status/Vae-Scrooge/remote-cmd/ci.yml?style=for-the-badge&logo=githubactions&label=CI" alt="CI">
 </p>
@@ -89,30 +89,32 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.4.0 Release Highlights
+## v2.6.0 Release Highlights
 
-v2.4.0 adds an opt-in retained-output cap for batch execution and cleans up logging
-handler resources, with default behavior and public result schemas unchanged. See the
-[full migration notes](./CHANGELOG.md) before upgrading automated callers.
+v2.6.0 is an architecture and runtime-scalability release: the compatibility facade
+moved out of `core` (eliminating the `core → service` dependency) and a process-wide
+live-connection budget was added for fleet-scale resource control. Public APIs remain
+backward compatible. See the [full migration notes](./CHANGELOG.md).
 
-### Bounded Batch Output
+### Architecture
 
-- `BatchExecutor` / `AsyncBatchExecutor` accept an optional `max_output_bytes` (default `None`): `None` keeps full `stdout`/`stderr`, while a positive value caps each host's retained streams and appends a `[output truncated: N bytes omitted]` marker.
-- Truncation is deterministic and UTF-8 byte-boundary safe, applies to `stdout` and `stderr` independently, and never changes command success/failure or exit codes.
-- The cap bounds the retained `BatchResult`; the SSH client may still hold full output transiently during execution, so it is not a process-wide RSS limit.
+- `HostManager` now lives in `remote_cmd.api.host_manager`; `remote_cmd.core.host_manager` remains a re-export shim, so existing imports keep working.
+- Pool policy helpers moved to `remote_cmd.core.pool_policy` (shim kept at the old path); `core` no longer imports `service`.
+- The async kernel's worker queue now converts unexpected per-host errors into failure results, so a single internal error can no longer stall an entire batch.
 
-### Reliability
+### Global Connection Budget
 
-- `setup_logging` now closes previous root-logger handlers before removing them, avoiding unclosed-file resource warnings when logging is reconfigured.
-- Connection-pool lifetime wording in the documentation now matches the actual behavior: internal pools are created lazily per host and closed as soon as that host finishes (including its retries).
+- New `ConnectionBudget` (exported from `remote_cmd`): caps **live** SSH connections process-wide across pools and executors — idle pooled connections count, and slots release on close/cleanup/`close_all`.
+- One instance can be shared by both kernels via `connection_budget=` on `BatchExecutor`, `AsyncBatchExecutor`, `SyncConnectionPool`, and `AsyncConnectionPool`.
+- Optional `acquire_timeout` raises the transient `BudgetTimeoutError`; the default (`None`) keeps unlimited behavior.
 
 ### Compatibility
 
-- Default behavior is unchanged (`max_output_bytes=None` retains full output) and the public `BatchResult` / `BatchHostResult` schemas are unchanged.
+- All existing imports and constructor signatures keep working; new parameters are optional and default to previous behavior.
 
 ## Table of Contents
 
-- [v2.4.0 Release Highlights](#v240-release-highlights)
+- [v2.6.0 Release Highlights](#v260-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -262,6 +264,7 @@ with SSHClient(config) as client:
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
 | **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
+| **Global Connection Budget** | Optional `ConnectionBudget` caps live SSH connections process-wide across pools and executors |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |
 | **Secure Logging** | Structured logging that filters sensitive data (`SensitiveDataFilter`) |
@@ -350,7 +353,7 @@ Good first issues are labelled `good first issue` in the
 developed independently as a focused alternative to heavyweight tools for the
 ad-hoc SSH tasks that come up in day-to-day server work.
 
-- **Project health:** CI runs on every PR, Python 3.9+ is supported, and the
+- **Project health:** CI runs on every PR, Python 3.10+ is supported, and the
   public API is versioned under [semantic versioning](https://semver.org/).
 - **Your code, your servers:** usage stays open under the MIT license — nothing
   is telemetry-driven or locked behind a service.

{remote_cmd_manager-2.4.0 → remote_cmd_manager-2.6.0}/README.md

@@ -2,7 +2,7 @@
   <img src="https://img.shields.io/pypi/v/remote_cmd_manager?style=for-the-badge&logo=pypi&logoColor=white&label=PyPI" alt="PyPI">
   <img src="https://img.shields.io/pypi/dm/remote_cmd_manager?style=for-the-badge&logo=python&logoColor=white&label=Downloads" alt="Downloads">
   <img src="https://img.shields.io/github/stars/Vae-Scrooge/remote-cmd?style=for-the-badge&logo=github" alt="Stars">
-  <img src="https://img.shields.io/badge/python-3.9%2B-blue?style=for-the-badge&logo=python" alt="Python">
+  <img src="https://img.shields.io/badge/python-3.10%2B-blue?style=for-the-badge&logo=python" alt="Python">
   <img src="https://img.shields.io/github/license/Vae-Scrooge/remote-cmd?style=for-the-badge" alt="License">
   <img src="https://img.shields.io/github/actions/workflow/status/Vae-Scrooge/remote-cmd/ci.yml?style=for-the-badge&logo=githubactions&label=CI" alt="CI">
 </p>
@@ -36,30 +36,32 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.4.0 Release Highlights
+## v2.6.0 Release Highlights
 
-v2.4.0 adds an opt-in retained-output cap for batch execution and cleans up logging
-handler resources, with default behavior and public result schemas unchanged. See the
-[full migration notes](./CHANGELOG.md) before upgrading automated callers.
+v2.6.0 is an architecture and runtime-scalability release: the compatibility facade
+moved out of `core` (eliminating the `core → service` dependency) and a process-wide
+live-connection budget was added for fleet-scale resource control. Public APIs remain
+backward compatible. See the [full migration notes](./CHANGELOG.md).
 
-### Bounded Batch Output
+### Architecture
 
-- `BatchExecutor` / `AsyncBatchExecutor` accept an optional `max_output_bytes` (default `None`): `None` keeps full `stdout`/`stderr`, while a positive value caps each host's retained streams and appends a `[output truncated: N bytes omitted]` marker.
-- Truncation is deterministic and UTF-8 byte-boundary safe, applies to `stdout` and `stderr` independently, and never changes command success/failure or exit codes.
-- The cap bounds the retained `BatchResult`; the SSH client may still hold full output transiently during execution, so it is not a process-wide RSS limit.
+- `HostManager` now lives in `remote_cmd.api.host_manager`; `remote_cmd.core.host_manager` remains a re-export shim, so existing imports keep working.
+- Pool policy helpers moved to `remote_cmd.core.pool_policy` (shim kept at the old path); `core` no longer imports `service`.
+- The async kernel's worker queue now converts unexpected per-host errors into failure results, so a single internal error can no longer stall an entire batch.
 
-### Reliability
+### Global Connection Budget
 
-- `setup_logging` now closes previous root-logger handlers before removing them, avoiding unclosed-file resource warnings when logging is reconfigured.
-- Connection-pool lifetime wording in the documentation now matches the actual behavior: internal pools are created lazily per host and closed as soon as that host finishes (including its retries).
+- New `ConnectionBudget` (exported from `remote_cmd`): caps **live** SSH connections process-wide across pools and executors — idle pooled connections count, and slots release on close/cleanup/`close_all`.
+- One instance can be shared by both kernels via `connection_budget=` on `BatchExecutor`, `AsyncBatchExecutor`, `SyncConnectionPool`, and `AsyncConnectionPool`.
+- Optional `acquire_timeout` raises the transient `BudgetTimeoutError`; the default (`None`) keeps unlimited behavior.
 
 ### Compatibility
 
-- Default behavior is unchanged (`max_output_bytes=None` retains full output) and the public `BatchResult` / `BatchHostResult` schemas are unchanged.
+- All existing imports and constructor signatures keep working; new parameters are optional and default to previous behavior.
 
 ## Table of Contents
 
-- [v2.4.0 Release Highlights](#v240-release-highlights)
+- [v2.6.0 Release Highlights](#v260-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -209,6 +211,7 @@ with SSHClient(config) as client:
 | **Tag System** | Filter hosts by tag (e.g., `production`, `web`, `db`) |
 | **Batch Ops** | Run commands across any host group, synchronously or asynchronously; optional per-host retained-output cap (`max_output_bytes`) |
 | **Async Kernel** | `AsyncSSHClient` / `AsyncConnectionPool` / `AsyncBatchExecutor` via the `[async]` extra |
+| **Global Connection Budget** | Optional `ConnectionBudget` caps live SSH connections process-wide across pools and executors |
 | **Task Runner** | Track and schedule long-running remote tasks with statuses (`TaskRunner`) |
 | **Connection Test** | Test all host SSH connections and report status |
 | **Secure Logging** | Structured logging that filters sensitive data (`SensitiveDataFilter`) |
@@ -297,7 +300,7 @@ Good first issues are labelled `good first issue` in the
 developed independently as a focused alternative to heavyweight tools for the
 ad-hoc SSH tasks that come up in day-to-day server work.
 
-- **Project health:** CI runs on every PR, Python 3.9+ is supported, and the
+- **Project health:** CI runs on every PR, Python 3.10+ is supported, and the
   public API is versioned under [semantic versioning](https://semver.org/).
 - **Your code, your servers:** usage stays open under the MIT license — nothing
   is telemetry-driven or locked behind a service.

{remote_cmd_manager-2.4.0 → remote_cmd_manager-2.6.0}/pyproject.toml

@@ -7,7 +7,7 @@ name = "remote_cmd_manager"
 dynamic = ["version"]
 description = "Cross-platform SSH remote server management tool (Linux/macOS/Windows) — lightweight, zero-configuration CLI and Python API for managing servers over SSH. Supports host CRUD, batch commands, file transfer, credential encryption, async execution, and more."
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 license = { text = "MIT" }
 authors = [
     { name = "Vae-Scrooge", email = "vaescrooge@gmail.com" },
@@ -19,7 +19,6 @@ classifiers = [
     "Intended Audience :: System Administrators",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -33,7 +32,7 @@ classifiers = [
     "Operating System :: Microsoft :: Windows",
 ]
 dependencies = [
-    "paramiko>=3.0",
+    "paramiko>=5.0,<6",
     "click>=8.0",
     "cryptography>=41.0",
     "rich>=13.0",
@@ -43,22 +42,24 @@ dependencies = [
 
 [project.optional-dependencies]
 # 异步原生执行内核：启用 BatchExecutor(use_async=True) / AsyncSSHClient / AsyncConnectionPool 时需要
-async = ["asyncssh>=2.14.0"]
+# 下限锁定在 2.24.x：2.23.x 及更早版本存在 2026 年公开 CVE（SCP 路径穿越等）。
+async = ["asyncssh>=2.24.0,<3"]
 # 云平台主机发现（Phase 4 预留）
 cloud = ["boto3>=1.34"]
 # 开发与测试
+# 包含 async extra：默认测试套件会 import 异步模块，仅装 dev 无法收集。
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
     "pytest-cov>=4.0",
     "ruff>=0.4",
     "mypy>=1.10",
+    "asyncssh>=2.24.0,<3",
     # 测试 keyring 凭据提供者（生产为可选依赖，测试环境固定安装）
     "keyring>=24.0",
 ]
-# 文档生成（pdoc>=16 需 Python>=3.10，固定到 15.x 以兼容 requires-python>=3.9）。
-# 精确 pin 15.0.4：pdoc HTML 输出随版本/解释器变化，docs/api 漂移门禁
-# （scripts/check_docs_drift.py）要求生成结果可复现。
+# 文档生成。pdoc 固定到 15.0.4：docs/api 漂移门禁（scripts/check_docs_drift.py）
+# 要求生成结果可复现。
 docs = ["pdoc==15.0.4"]
 
 [project.urls]
@@ -88,7 +89,7 @@ markers = [
 ]
 
 [tool.ruff]
-target-version = "py39"
+target-version = "py310"
 line-length = 100
 
 [tool.ruff.lint]
@@ -109,6 +110,12 @@ ignore = [
     "N812",
     "N999",
     "B904",
+    # PEP 604 / 新式导入重写推迟到 v2.6（保持 v2.5 变更面最小）
+    "UP006", # dict/list 泛型重写
+    "UP007", # Union -> X|Y
+    "UP035", # typing.* 导入重写
+    "UP041", # IOError -> TimeoutError 别名
+    "UP045", # Optional -> X|None
 ]
 
 [tool.ruff.lint.per-file-ignores]

{remote_cmd_manager-2.4.0 → remote_cmd_manager-2.6.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.4.0（单一真相源见 remote_cmd._version）
+Version: 2.6.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 
@@ -74,8 +74,9 @@ try:
 except ImportError:  # pragma: no cover - 依赖 asyncssh，未安装时不导出异步符号
     _HAS_ASYNC = False
 
+from remote_cmd.api.host_manager import HostManager
+from remote_cmd.core.budget import ConnectionBudget
 from remote_cmd.core.host import Host
-from remote_cmd.core.host_manager import HostManager
 from remote_cmd.core.ssh_client import SSHClient
 from remote_cmd.core.sync_connection_pool import SyncConnectionPool
 
@@ -96,10 +97,16 @@ from remote_cmd.service import (
     HostService,
     SSHService,
 )
-from remote_cmd.service.batch_executor import BatchExecutor, BatchHostResult, BatchResult
+from remote_cmd.service.batch_executor import (
+    BatchExecutor,
+    BatchHostResult,
+    BatchResult,
+    OutputPolicy,
+)
 from remote_cmd.service.credential_provider import KeyringCredentialProvider
 from remote_cmd.service.task_runner import Task, TaskRunner, TaskStatus
 from remote_cmd.utils.crypto import CredentialEncryption
+from remote_cmd.utils.exceptions import BudgetTimeoutError, PlaintextCredentialWarning
 from remote_cmd.utils.logging_utils import (
     SensitiveDataFilter,
     get_logger,
@@ -134,6 +141,10 @@ if _HAS_ASYNC:
         "BatchExecutor",
         "BatchResult",
         "BatchHostResult",
+        "OutputPolicy",
+        "PlaintextCredentialWarning",
+        "ConnectionBudget",
+        "BudgetTimeoutError",
         "SyncConnectionPool",
         "TaskRunner",
         "Task",
@@ -167,6 +178,10 @@ else:
         "BatchExecutor",
         "BatchResult",
         "BatchHostResult",
+        "OutputPolicy",
+        "PlaintextCredentialWarning",
+        "ConnectionBudget",
+        "BudgetTimeoutError",
         "SyncConnectionPool",
         "TaskRunner",
         "Task",

{remote_cmd_manager-2.4.0 → remote_cmd_manager-2.6.0}/remote_cmd/_version.py

@@ -9,4 +9,4 @@
 - ``__version__`` 由 ``remote_cmd/__init__.py`` 导入并继续作为公共 API 导出。
 """
 
-__version__ = "2.4.0"
+__version__ = "2.6.0"

remote_cmd_manager-2.6.0/remote_cmd/api/__init__.py

@@ -0,0 +1,22 @@
+"""
+API facade 包（向后兼容层）
+
+存放从 ``core`` 迁出的公共兼容 facade，使核心层（``core``）保持对
+``service`` 的零依赖。当前包含:
+
+    - :class:`remote_cmd.api.host_manager.HostManager`：v1.x 的 HostManager
+      API，内部委托给 HostService + JsonHostRepository。
+
+旧导入路径 ``remote_cmd.core.host_manager`` 仍然可用（re-export shim），
+但新代码应使用 ``remote_cmd.api.host_manager`` 或直接使用 HostService。
+
+依赖方向（v2.6 契约）::
+
+    cli / api → service → core → utils
+    repository ← service / cli
+    core 绝不 import service / cli / api 的实现
+"""
+
+from remote_cmd.api.host_manager import HostManager
+
+__all__ = ["HostManager"]

{remote_cmd_manager-2.4.0/remote_cmd/core → remote_cmd_manager-2.6.0/remote_cmd/api}/host_manager.py

@@ -1,12 +1,18 @@
 """
-主机管理模块（向后兼容层）
+主机管理模块（向后兼容 facade，canonical 位置）
 
-保持原有 API 兼容，内部委托给新的 Repository + Service 层。
+保持原有 HostManager API 兼容，内部委托给新的 Repository + Service 层。
 
 新的代码应直接使用:
     - remote_cmd.core.host.Host (代替 Host)
     - remote_cmd.service.host_service.HostService (代替 HostManager)
     - remote_cmd.repository.json_host_repository.JsonHostRepository
+    - remote_cmd.api.host_manager.HostManager（本模块；仅在需要旧 API 时）
+
+v2.6 架构说明：
+    本模块自 ``remote_cmd.core.host_manager`` 迁至 ``remote_cmd.api``，
+    使 ``core`` 层不再依赖 ``service`` 层。旧导入路径由
+    ``remote_cmd.core.host_manager`` 的 re-export shim 保持可用。
 """
 
 import logging

{remote_cmd_manager-2.4.0 → remote_cmd_manager-2.6.0}/remote_cmd/core/async_connection_pool.py

@@ -19,13 +19,14 @@ import uuid
 from typing import Any, Optional
 
 from remote_cmd.core.async_ssh_client import AsyncSSHClient
-from remote_cmd.core.ssh_client import ConnectionConfig
-from remote_cmd.service._pool_policy import (
+from remote_cmd.core.budget import ConnectionBudget
+from remote_cmd.core.pool_policy import (
     ConnectionMeta,
     idle_expired,
     lifetime_expired,
     should_close,
 )
+from remote_cmd.core.ssh_client import ConnectionConfig
 from remote_cmd.utils.exceptions import PoolClosedError
 
 logger = logging.getLogger(__name__)
@@ -40,6 +41,9 @@ class AsyncConnectionPool:
         max_lifetime: 连接最大生命周期（秒），超过自动关闭
         idle_timeout: 空闲超时（秒），超过自动关闭
         health_check_interval: 后台清理任务周期（秒）
+        connection_budget: 可选的全局连接预算（v2.6）。提供时本池创建的
+            每条存活连接都占用一个预算槽位（含空闲连接），连接关闭/清理/
+            close_all 时释放；跨多个池共享同一预算实例可获得全局连接上限
     """
 
     def __init__(
@@ -50,6 +54,7 @@ class AsyncConnectionPool:
         idle_timeout: int = 300,
         health_check_interval: int = 60,
         client_factory: Optional[Any] = None,
+        connection_budget: Optional[ConnectionBudget] = None,
     ) -> None:
         """
         Args:
@@ -60,6 +65,7 @@ class AsyncConnectionPool:
             health_check_interval: 后台清理任务周期（秒）
             client_factory: 客户端工厂，默认为 AsyncSSHClient；测试可注入
                 mock（与 SyncConnectionPool 对齐）
+            connection_budget: 可选的全局连接预算（ConnectionBudget）
         """
         self.config = config
         self._max = max_connections
@@ -68,6 +74,7 @@ class AsyncConnectionPool:
         self._health_check_interval = health_check_interval
         # 客户端工厂：默认为 AsyncSSHClient；测试可注入 mock
         self._client_factory = client_factory or AsyncSSHClient
+        self._connection_budget = connection_budget
 
         # 容器
         self._connections: list[AsyncSSHClient] = []
@@ -190,10 +197,16 @@ class AsyncConnectionPool:
     # ------------------------------------------------------------------
     async def _create_connection(self) -> AsyncSSHClient:
         client = self._client_factory(self.config)
+        if self._connection_budget is not None:
+            await self._connection_budget.acquire_async()
         try:
             await client.connect()
         except Exception:  # noqa: BLE001
-            # 信号量由 acquire() 的 except 统一释放，此处不再释放
+            # 信号量由 acquire() 的 except 统一释放，此处不再释放。
+            # 连接预算仅在成功建连后由 _close_connection 释放；
+            # 建连失败立即归还预算，避免预算泄漏
+            if self._connection_budget is not None:
+                await self._connection_budget.release_async()
             self._total_failed += 1
             raise
         self._connections.append(client)
@@ -237,8 +250,14 @@ class AsyncConnectionPool:
         with contextlib.suppress(Exception):
             await conn.disconnect()
         self._meta.pop(id(conn), None)
-        if conn in self._connections:
+        tracked = conn in self._connections
+        if tracked:
             self._connections.remove(conn)
+        # exactly-once：仅对仍被池追踪的连接释放预算。
+        # close_all 与 release 可能对同一连接重复调用 _close_connection，
+        # 用 tracked 守卫避免预算被超额释放（BoundedSemaphore 会抛 ValueError）
+        if tracked and self._connection_budget is not None:
+            await self._connection_budget.release_async()
 
     # ------------------------------------------------------------------
     # 后台监控