remote-cmd-manager 2.1.0__tar.gz → 2.2.0__tar.gz

{remote_cmd_manager-2.1.0/remote_cmd_manager.egg-info → remote_cmd_manager-2.2.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: remote_cmd_manager
-Version: 2.1.0
-Summary: SSH 远程服务器管理工具 / Python SSH remote server management tool
+Version: 2.2.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
 Project-URL: Homepage, https://github.com/Vae-Scrooge/remote-cmd
@@ -9,8 +9,8 @@ Project-URL: Repository, https://github.com/Vae-Scrooge/remote-cmd
 Project-URL: Documentation, https://github.com/Vae-Scrooge/remote-cmd#readme
 Project-URL: Bug Tracker, https://github.com/Vae-Scrooge/remote-cmd/issues
 Project-URL: Download, https://pypi.org/project/remote_cmd_manager/
-Keywords: ssh,remote,server-management,sysadmin,devops
-Classifier: Development Status :: 4 - Beta
+Keywords: ssh,remote,server-management,sysadmin,devops,cross-platform
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: System Administrators
 Classifier: License :: OSI Approved :: MIT License
@@ -21,6 +21,9 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Topic :: System :: Systems Administration
 Classifier: Topic :: System :: Networking
 Classifier: Environment :: Console
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -42,7 +45,7 @@ Requires-Dist: ruff>=0.4; extra == "dev"
 Requires-Dist: mypy>=1.10; extra == "dev"
 Requires-Dist: keyring>=24.0; extra == "dev"
 Provides-Extra: docs
-Requires-Dist: pdoc<16,>=15; extra == "docs"
+Requires-Dist: pdoc==15.0.4; extra == "docs"
 Dynamic: license-file
 
 <p align="center">
@@ -54,6 +57,7 @@ Dynamic: license-file
   <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>
 
+<p align="center"><strong>Tested on Linux, macOS, and Windows</strong></p>
 <h1 align="center">Remote CMD — SSH Server Management<br><small>Without the Overhead</small></h1>
 
 <p align="center">
@@ -71,12 +75,6 @@ Dynamic: license-file
   <a href="#contributing">Contributing</a>
 </p>
 
-<p align="center">
-  <a href="https://asciinema.org/a/9yLeYj73muPUuAQY" target="_blank">
-    <img src="https://asciinema.org/a/9yLeYj73muPUuAQY.svg" width="720" alt="Demo">
-  </a>
-</p>
-
 ---
 
 **Remote CMD** is a lightweight Python CLI + API for managing servers over SSH. Add hosts, run commands, transfer files, and organize hosts with tags — no Ansible DSL or shell loops required.
@@ -88,32 +86,27 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.1.0 Release Highlights
+## v2.2.0 Release Highlights
 
-v2.1.0 contains both major implementation changes and a final release-hardening pass. See the
+v2.2.0 bounds batch-execution resource usage, makes concurrent SQLite writers safe, tightens
+retry classification, and hardens the release pipeline. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### Major Implementation Changes
+### Resource & Reliability
 
-- Paramiko command execution drains stdout and stderr before retrieving the exit status, preventing SSH channel-window deadlocks on large output.
-- Paramiko command timeouts are wall-clock enforced; a silent or hung command closes its channel and raises `SSHCommandTimeoutError`.
-- `AsyncBatchExecutor` now uses `AsyncConnectionPool` for multi-host and retry workloads, reusing connections across attempts.
-- `pool_factory` enables caller-supplied pools; external pools are caller-owned and never closed by either executor, while internally created pools are closed automatically after `execute()`.
-- Retries classify permanent failures (authentication, credentials, configuration, validation, and programming errors) as non-retryable; unknown `Exception` subclasses remain retryable for backward compatibility. `retry_delay` is now the exponential-backoff base and full jitter is applied with a 60-second cap.
-- Unknown hosts produce per-host failure results instead of aborting a multi-host batch, and duplicate host names are executed once.
-- The exception hierarchy adds `SSHAuthenticationError`, `SSHTimeoutError`, `SSHCommandTimeoutError`, `CredentialError`, and the `ConfigurationError` alias without removing existing catch paths.
-- Environment-variable names are validated before shell interpolation, and command text is excluded from library logs and execution errors.
-- `remote-cmd run` supports `--timeout/-T` for command execution limits.
+- Internal batch pools are now created lazily per host, capped at one connection, and closed as soon as that host (including all retries) finishes; batch-wide live internal connections are bounded by `max_concurrency` instead of retaining one idle connection per host until the batch ends.
+- SQLite writes now use `BEGIN IMMEDIATE` with a configurable `busy_timeout` (default 5000 ms), and the initial `journal_mode=WAL` switch is retried; concurrent `remote-cmd` processes writing the same `hosts.db` no longer fail with `database is locked` or lose updates. Schema and `db_version` are unchanged.
+- Pool closure raises the new `PoolClosedError` (still catchable as `RuntimeError`); retry classification is corrected so bare `RuntimeError` is retryable again (v2.0 behavior) while pool closure remains non-retryable. Typed permanent and transient errors are unchanged.
 
-### Final Release Hardening
+### Release Engineering
 
-- Sync and async pools re-check their closed state after semaphore acquisition, preventing a shutdown race from issuing a connection from a closed pool.
-- `BatchExecutor(use_async=True)` now reports an actionable error when called from an active event loop; use `AsyncBatchExecutor.execute()` there instead.
-- The Paramiko stderr drain join is bounded to prevent an exceptional reader path from blocking the caller indefinitely.
+- Publish workflow: artifact actions aligned, run-scoped artifact names, duplicate version publication now fails instead of being skipped, `twine check` validates distributions, and the release tag is verified against the package version. Trusted Publishing and the GitHub Release → PyPI flow are unchanged.
+- CI documentation drift detection: `docs/api` is regenerated and compared on relevant changes, failing when tracked generated docs are stale (`pdoc` pinned to `15.0.4` on Python 3.12).
+- Release metadata validation: a lightweight gate checks the single-source version, the `pyproject.toml` dynamic-version attribute, `[Unreleased]` and matching `[x.y.z]` CHANGELOG headings, and (on release) that the git tag matches the package version.
 
 ## Table of Contents
 
-- [v2.1.0 Release Highlights](#v210-release-highlights)
+- [v2.2.0 Release Highlights](#v220-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -270,6 +263,20 @@ with SSHClient(config) as client:
 
 ---
 
+## Cross-Platform Support
+
+`remote-cmd` is a pure-Python client, **tested and supported on Linux, macOS, and Windows**. No native dependencies or platform-specific builds are required.
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | ✅ Fully tested | Primary development platform |
+| macOS | ✅ Supported | Use `brew install openssh` for a newer OpenSSH |
+| Windows | ✅ Supported | PowerShell / CMD / WSL all work |
+
+> **Note on Windows file permissions:** Credential encryption keys are protected with `0600` permissions on Unix. On Windows this restriction is not enforced by the filesystem — the key file is still encrypted at rest. For production Windows use, consider adding filesystem-level ACLs.
+
+---
+
 ## Installation
 
 ```bash
@@ -309,14 +316,14 @@ are simply not exported.
 | [Changelog](./CHANGELOG.md) | Release history |
 | [Mobile Remote Guide](./MOBILE-REMOTE-GUIDE.md) | Manage servers from your phone |
 
-> **Note:** The documentation center and tutorials are maintained in **Chinese**. See
+> **Note:** The documentation center and tutorials are maintained in **English**. See
 > [README.zh-CN.md](./README.zh-CN.md) for the Chinese version of this page.
 
 ---
 
 ## Project Status
 
-**Beta.** The core API is stable. Breaking changes will be communicated via semantic versioning.
+**Stable.** The core API is stable and versioned under semantic versioning. Breaking changes are communicated via major-version bumps, and the public API surface has been stable since the 1.x line.
 
 **Roadmap:**
 - [x] Async SSH operations (parallel execution) — v1.1.0

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.2.0}/README.md

@@ -7,6 +7,7 @@
   <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>
 
+<p align="center"><strong>Tested on Linux, macOS, and Windows</strong></p>
 <h1 align="center">Remote CMD — SSH Server Management<br><small>Without the Overhead</small></h1>
 
 <p align="center">
@@ -24,12 +25,6 @@
   <a href="#contributing">Contributing</a>
 </p>
 
-<p align="center">
-  <a href="https://asciinema.org/a/9yLeYj73muPUuAQY" target="_blank">
-    <img src="https://asciinema.org/a/9yLeYj73muPUuAQY.svg" width="720" alt="Demo">
-  </a>
-</p>
-
 ---
 
 **Remote CMD** is a lightweight Python CLI + API for managing servers over SSH. Add hosts, run commands, transfer files, and organize hosts with tags — no Ansible DSL or shell loops required.
@@ -41,32 +36,27 @@ pip install remote_cmd_manager && remote-cmd host add web-01 192.168.1.10 ubuntu
 
 ---
 
-## v2.1.0 Release Highlights
+## v2.2.0 Release Highlights
 
-v2.1.0 contains both major implementation changes and a final release-hardening pass. See the
+v2.2.0 bounds batch-execution resource usage, makes concurrent SQLite writers safe, tightens
+retry classification, and hardens the release pipeline. See the
 [full migration notes](./CHANGELOG.md) before upgrading automated callers.
 
-### Major Implementation Changes
+### Resource & Reliability
 
-- Paramiko command execution drains stdout and stderr before retrieving the exit status, preventing SSH channel-window deadlocks on large output.
-- Paramiko command timeouts are wall-clock enforced; a silent or hung command closes its channel and raises `SSHCommandTimeoutError`.
-- `AsyncBatchExecutor` now uses `AsyncConnectionPool` for multi-host and retry workloads, reusing connections across attempts.
-- `pool_factory` enables caller-supplied pools; external pools are caller-owned and never closed by either executor, while internally created pools are closed automatically after `execute()`.
-- Retries classify permanent failures (authentication, credentials, configuration, validation, and programming errors) as non-retryable; unknown `Exception` subclasses remain retryable for backward compatibility. `retry_delay` is now the exponential-backoff base and full jitter is applied with a 60-second cap.
-- Unknown hosts produce per-host failure results instead of aborting a multi-host batch, and duplicate host names are executed once.
-- The exception hierarchy adds `SSHAuthenticationError`, `SSHTimeoutError`, `SSHCommandTimeoutError`, `CredentialError`, and the `ConfigurationError` alias without removing existing catch paths.
-- Environment-variable names are validated before shell interpolation, and command text is excluded from library logs and execution errors.
-- `remote-cmd run` supports `--timeout/-T` for command execution limits.
+- Internal batch pools are now created lazily per host, capped at one connection, and closed as soon as that host (including all retries) finishes; batch-wide live internal connections are bounded by `max_concurrency` instead of retaining one idle connection per host until the batch ends.
+- SQLite writes now use `BEGIN IMMEDIATE` with a configurable `busy_timeout` (default 5000 ms), and the initial `journal_mode=WAL` switch is retried; concurrent `remote-cmd` processes writing the same `hosts.db` no longer fail with `database is locked` or lose updates. Schema and `db_version` are unchanged.
+- Pool closure raises the new `PoolClosedError` (still catchable as `RuntimeError`); retry classification is corrected so bare `RuntimeError` is retryable again (v2.0 behavior) while pool closure remains non-retryable. Typed permanent and transient errors are unchanged.
 
-### Final Release Hardening
+### Release Engineering
 
-- Sync and async pools re-check their closed state after semaphore acquisition, preventing a shutdown race from issuing a connection from a closed pool.
-- `BatchExecutor(use_async=True)` now reports an actionable error when called from an active event loop; use `AsyncBatchExecutor.execute()` there instead.
-- The Paramiko stderr drain join is bounded to prevent an exceptional reader path from blocking the caller indefinitely.
+- Publish workflow: artifact actions aligned, run-scoped artifact names, duplicate version publication now fails instead of being skipped, `twine check` validates distributions, and the release tag is verified against the package version. Trusted Publishing and the GitHub Release → PyPI flow are unchanged.
+- CI documentation drift detection: `docs/api` is regenerated and compared on relevant changes, failing when tracked generated docs are stale (`pdoc` pinned to `15.0.4` on Python 3.12).
+- Release metadata validation: a lightweight gate checks the single-source version, the `pyproject.toml` dynamic-version attribute, `[Unreleased]` and matching `[x.y.z]` CHANGELOG headings, and (on release) that the git tag matches the package version.
 
 ## Table of Contents
 
-- [v2.1.0 Release Highlights](#v210-release-highlights)
+- [v2.2.0 Release Highlights](#v220-release-highlights)
 - [Why Remote CMD?](#why-remote-cmd)
 - [Quick Start](#quick-start)
 - [Use Cases](#use-cases)
@@ -223,6 +213,20 @@ with SSHClient(config) as client:
 
 ---
 
+## Cross-Platform Support
+
+`remote-cmd` is a pure-Python client, **tested and supported on Linux, macOS, and Windows**. No native dependencies or platform-specific builds are required.
+
+| Platform | Status | Notes |
+|----------|--------|-------|
+| Linux | ✅ Fully tested | Primary development platform |
+| macOS | ✅ Supported | Use `brew install openssh` for a newer OpenSSH |
+| Windows | ✅ Supported | PowerShell / CMD / WSL all work |
+
+> **Note on Windows file permissions:** Credential encryption keys are protected with `0600` permissions on Unix. On Windows this restriction is not enforced by the filesystem — the key file is still encrypted at rest. For production Windows use, consider adding filesystem-level ACLs.
+
+---
+
 ## Installation
 
 ```bash
@@ -262,14 +266,14 @@ are simply not exported.
 | [Changelog](./CHANGELOG.md) | Release history |
 | [Mobile Remote Guide](./MOBILE-REMOTE-GUIDE.md) | Manage servers from your phone |
 
-> **Note:** The documentation center and tutorials are maintained in **Chinese**. See
+> **Note:** The documentation center and tutorials are maintained in **English**. See
 > [README.zh-CN.md](./README.zh-CN.md) for the Chinese version of this page.
 
 ---
 
 ## Project Status
 
-**Beta.** The core API is stable. Breaking changes will be communicated via semantic versioning.
+**Stable.** The core API is stable and versioned under semantic versioning. Breaking changes are communicated via major-version bumps, and the public API surface has been stable since the 1.x line.
 
 **Roadmap:**
 - [x] Async SSH operations (parallel execution) — v1.1.0

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.2.0}/pyproject.toml

@@ -5,16 +5,16 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "remote_cmd_manager"
 dynamic = ["version"]
-description = "SSH 远程服务器管理工具 / Python SSH remote server management tool"
+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"
 license = { text = "MIT" }
 authors = [
     { name = "Vae-Scrooge", email = "vaescrooge@gmail.com" },
 ]
-keywords = ["ssh", "remote", "server-management", "sysadmin", "devops"]
+keywords = ["ssh", "remote", "server-management", "sysadmin", "devops", "cross-platform"]
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Developers",
     "Intended Audience :: System Administrators",
     "License :: OSI Approved :: MIT License",
@@ -25,6 +25,9 @@ classifiers = [
     "Topic :: System :: Systems Administration",
     "Topic :: System :: Networking",
     "Environment :: Console",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
 ]
 dependencies = [
     "paramiko>=3.0",
@@ -50,8 +53,10 @@ dev = [
     # 测试 keyring 凭据提供者（生产为可选依赖，测试环境固定安装）
     "keyring>=24.0",
 ]
-# 文档生成（pdoc>=16 需 Python>=3.10，固定到 15.x 以兼容 requires-python>=3.9）
-docs = ["pdoc>=15,<16"]
+# 文档生成（pdoc>=16 需 Python>=3.10，固定到 15.x 以兼容 requires-python>=3.9）。
+# 精确 pin 15.0.4：pdoc HTML 输出随版本/解释器变化，docs/api 漂移门禁
+# （scripts/check_docs_drift.py）要求生成结果可复现。
+docs = ["pdoc==15.0.4"]
 
 [project.urls]
 Homepage = "https://github.com/Vae-Scrooge/remote-cmd"

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.2.0}/remote_cmd/__init__.py

@@ -48,7 +48,7 @@ Remote CMD - SSH 远程服务器管理工具
     - 文档: 参见 docs/ 目录
 
 Author: Vae-Scrooge
-Version: 2.1.0（单一真相源见 remote_cmd._version）
+Version: 2.2.0（单一真相源见 remote_cmd._version）
 License: MIT
 """
 

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.2.0}/remote_cmd/_version.py

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

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.2.0}/remote_cmd/core/async_connection_pool.py

@@ -26,6 +26,7 @@ from remote_cmd.service._pool_policy import (
     lifetime_expired,
     should_close,
 )
+from remote_cmd.utils.exceptions import PoolClosedError
 
 logger = logging.getLogger(__name__)
 
@@ -120,17 +121,18 @@ class AsyncConnectionPool:
 
         Raises:
             SSHConnectionError: 创建连接失败
-            RuntimeError: 连接池已关闭（close_all 之后）
+            PoolClosedError: 连接池已关闭（close_all 之后），
+                同时是 RuntimeError 子类（既有捕获行为不变）
         """
         if self._closed:
-            raise RuntimeError("connection pool is closed")
+            raise PoolClosedError("connection pool is closed")
         await self._semaphore.acquire()
         # 竞态守卫：等待信号量期间 close_all() 可能已完成——
         # 取得槽位后必须复查，已关闭则归还槽位并抛出既有错误，
         # 否则会向调用方发放来自已关闭池的连接
         if self._closed:
             self._semaphore.release()
-            raise RuntimeError("connection pool is closed")
+            raise PoolClosedError("connection pool is closed")
         try:
             # 优先复用空闲连接
             while not self._free.empty():

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.2.0}/remote_cmd/core/ssh_client.py

@@ -20,7 +20,7 @@ import socket
 import stat
 import threading
 from dataclasses import dataclass
-from pathlib import Path
+from pathlib import Path, PurePosixPath
 from typing import Any, Optional
 
 import paramiko
@@ -729,13 +729,16 @@ class SSHClient:
         sftp = self._get_sftp()
 
         def _makedirs(sftp_client: paramiko.SFTPClient, remote_path: str) -> None:
-            if remote_path == "/":
+            # 远端路径始终是 POSIX 语义，必须用 PurePosixPath 处理，
+            # 不能用本地 Path（在 Windows 上 WindowsPath 对 "/" 的处理会导致无限递归）。
+            p = PurePosixPath(remote_path)
+            if p == PurePosixPath("/") or p == PurePosixPath("."):
                 return
             try:
-                sftp_client.stat(remote_path)
+                sftp_client.stat(str(p))
             except OSError:
-                _makedirs(sftp_client, str(Path(remote_path).parent))
-                sftp_client.mkdir(remote_path)
+                _makedirs(sftp_client, str(p.parent))
+                sftp_client.mkdir(str(p))
 
         try:
             _makedirs(sftp, path)

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.2.0}/remote_cmd/core/sync_connection_pool.py

@@ -26,6 +26,7 @@ from remote_cmd.service._pool_policy import (
     lifetime_expired,
     should_close,
 )
+from remote_cmd.utils.exceptions import PoolClosedError
 
 logger = logging.getLogger(__name__)
 
@@ -111,17 +112,18 @@ class SyncConnectionPool:
 
         Raises:
             SSHConnectionError: 创建连接失败
-            RuntimeError: 连接池已关闭（close_all 之后）
+            PoolClosedError: 连接池已关闭（close_all 之后），
+                同时是 RuntimeError 子类（既有捕获行为不变）
         """
         if self._closed:
-            raise RuntimeError("connection pool is closed")
+            raise PoolClosedError("connection pool is closed")
         self._semaphore.acquire()
         # 竞态守卫：等待信号量期间 close_all() 可能已完成——
         # 取得槽位后必须复查，已关闭则归还槽位并抛出既有错误，
         # 否则会向调用方发放来自已关闭池的连接
         if self._closed:
             self._semaphore.release()
-            raise RuntimeError("connection pool is closed")
+            raise PoolClosedError("connection pool is closed")
         try:
             # 优先复用空闲连接
             while not self._free.empty():

{remote_cmd_manager-2.1.0 → remote_cmd_manager-2.2.0}/remote_cmd/repository/sqlite_host_repository.py

@@ -21,6 +21,7 @@ import json
 import logging
 import sqlite3
 import threading
+import time
 from typing import Optional
 
 from remote_cmd.core.host import Host
@@ -64,6 +65,9 @@ CREATE TABLE IF NOT EXISTS meta (
 );
 """
 
+# 写锁等待上限（毫秒）：多进程并发写同一数据库时，等待对方短事务提交/回滚
+DEFAULT_BUSY_TIMEOUT_MS = 5000
+
 
 class SqliteHostRepository(HostRepository):
     """
@@ -74,6 +78,7 @@ class SqliteHostRepository(HostRepository):
         migrate_from: JSON 文件路径，用于自动迁移（仅首次使用）
         auto_create: 是否自动创建表和数据库，默认 True
         encryption: 可选的凭据加密器（设置后 save() 自动加密 password）
+        busy_timeout_ms: 写锁等待上限（毫秒），默认 5000
 
     注意: 密码的加密依赖传入 encryption。若直接以明文密码调用 save()
     且未提供 encryption，明文会被持久化到数据库。请勿绕过 HostService。
@@ -85,11 +90,13 @@ class SqliteHostRepository(HostRepository):
         migrate_from: Optional[str] = None,
         auto_create: bool = True,
         encryption: Optional[CredentialEncryption] = None,
+        busy_timeout_ms: int = DEFAULT_BUSY_TIMEOUT_MS,
     ) -> None:
         self._db_path = db_path
         self._lock = threading.Lock()
         self._encryption = encryption
         self._guard = PasswordGuard(encryption)
+        self._busy_timeout_ms = busy_timeout_ms
 
         if auto_create:
             self._init_db()
@@ -103,7 +110,7 @@ class SqliteHostRepository(HostRepository):
 
     def _init_db(self) -> None:
         """初始化数据库：创建表和索引"""
-        with self._txn() as conn:
+        with self._txn(write=True) as conn:
             conn.execute(CREATE_TABLE_SQL)
             conn.execute(CREATE_META_SQL)
             for idx_sql in CREATE_INDEXES_SQL:
@@ -117,30 +124,66 @@ class SqliteHostRepository(HostRepository):
         logger.debug(f"SQLite database initialized: {self._db_path}")
 
     def _get_conn(self) -> sqlite3.Connection:
-        """获取数据库连接（线程安全）"""
+        """获取数据库连接（线程安全）。
+
+        PRAGMA 顺序约定：``busy_timeout`` 必须最先设置——首次并发打开同一
+        数据库文件时，``journal_mode=WAL`` 本身需要短暂排他锁，若 busy
+        handler 尚未生效会立即抛 ``database is locked``（v2.2 多进程回归）。
+
+        注意：SQLite 的 journal_mode 切换不经过 busy handler，即使设置了
+        ``busy_timeout`` 仍会直接返回 SQLITE_BUSY；因此在首次并发切换到
+        WAL 时使用有界重试（上限即 busy_timeout）等待其他连接的短事务结束。
+        """
         conn = sqlite3.connect(self._db_path, check_same_thread=False)
         conn.row_factory = sqlite3.Row
-        conn.execute("PRAGMA journal_mode=WAL;")
+        # 多进程/多连接写入争用：等待对方事务结束而不是立即失败
+        conn.execute(f"PRAGMA busy_timeout={self._busy_timeout_ms};")
+        self._enable_wal(conn)
         conn.execute("PRAGMA foreign_keys=ON;")
         return conn
 
+    def _enable_wal(self, conn: sqlite3.Connection) -> None:
+        """启用 WAL；对 journal_mode 切换的 SQLITE_BUSY 做有界重试。
+
+        数据库已是 WAL 时该 PRAGMA 只读取模式、不取排他锁，直接返回；
+        仅首次从其他模式切换到 WAL 的竞态需要重试。
+        """
+        deadline = time.monotonic() + self._busy_timeout_ms / 1000.0
+        while True:
+            try:
+                conn.execute("PRAGMA journal_mode=WAL;")
+                return
+            except sqlite3.OperationalError as e:
+                message = str(e).lower()
+                if "locked" not in message and "busy" not in message:
+                    raise
+                if time.monotonic() >= deadline:
+                    raise
+                time.sleep(0.05)
+
     @contextlib.contextmanager
-    def _txn(self):
+    def _txn(self, write: bool = False):
         """
         事务 + 连接生命周期上下文
 
         包装 ``with conn:`` 与 ``conn.close()`` 为单一上下文：
         - 进入时打开新连接并执行 PRAGMA
+        - ``write=True`` 时以 ``BEGIN IMMEDIATE`` 预先取得写锁（等待受
+          ``busy_timeout`` 约束）；避免 deferred 事务在写升级时因快照过期
+          直接返回 SQLITE_BUSY（busy handler 不适用该场景）
         - 退出时先 ``conn.__exit__`` 提交/回滚，再 ``conn.close()`` 释放 fd
 
         解决 ``with self._get_conn() as conn:`` 不自动 close 导致的 fd 累积泄漏
         （sqlite3.Connection.__exit__ 仅管理事务边界，不释放连接句柄）。
 
         所有读写操作都应通过 ``with self._lock, self._txn() as conn:`` 使用，
-        保证 ``self._lock`` 串行化的同时每次操作后释放 fd。
+        保证 ``self._lock`` 串行化的同时每次操作后释放 fd；写操作使用
+        ``self._txn(write=True)``。
         """
         conn = self._get_conn()
         try:
+            if write:
+                conn.execute("BEGIN IMMEDIATE")
             with conn:  # 事务：commit 或 rollback
                 yield conn
         finally:
@@ -204,7 +247,7 @@ class SqliteHostRepository(HostRepository):
 
     def save(self, host: Host) -> None:
         """保存或更新主机"""
-        with self._lock, self._txn() as conn:
+        with self._lock, self._txn(write=True) as conn:
             tags_json = json.dumps(host.tags or [], ensure_ascii=False)
             # 配置了加密器时，明文密码先加密再落库
             password = self._guard.encrypt(host.password)
@@ -248,7 +291,7 @@ class SqliteHostRepository(HostRepository):
 
     def delete(self, name: str) -> None:
         """按名称删除主机"""
-        with self._lock, self._txn() as conn:
+        with self._lock, self._txn(write=True) as conn:
             cursor = conn.execute("DELETE FROM hosts WHERE name = ?", (name,))
             conn.commit()