ipclick 0.6.0__tar.gz → 0.7.0__tar.gz

{ipclick-0.6.0 → ipclick-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ipclick
-Version: 0.6.0
+Version: 0.7.0
 Summary: IPClick Tool
 License: MIT
 License-File: LICENSE
@@ -34,7 +34,7 @@ Requires-Dist: niquests (>=3.21.0,<4.0.0) ; extra == "niquests"
 Requires-Dist: patchright (>=1.61.2,<2.0.0) ; extra == "linux"
 Requires-Dist: patchright (>=1.61.2,<2.0.0) ; extra == "patchright"
 Requires-Dist: playwright (>=1.60.0,<2.0.0) ; extra == "playwright"
-Requires-Dist: protobuf (>=6.33.2,<8.0.0)
+Requires-Dist: protobuf (>=7.35.1,<8.0.0)
 Requires-Dist: python-box[all] (>=7.4.1,<8.0.0)
 Requires-Dist: typing-extensions (>=4.16.0,<5.0.0)
 Requires-Dist: uuid-utils (>=0.17.0,<0.18.0)
@@ -155,6 +155,16 @@ max_concurrent_rpcs = 0    # 0 = max_workers × 8。这一项决定"排队能排
 实测并发 100 时：单进程 196.6 → 331.1 QPS，四进程 → 544.6 QPS；
 1000 并发的成功率从 25.8%（异步客户端）回到 100%。详见 CHANGELOG 的 0.6.0 一节。
 
+0.7.0 起还可以把服务端换成协程（实验性，默认关）：
+
+```toml
+[SERVER]
+async_mode = true    # grpc.aio + 协程，不再一请求一线程。实测端到端 1.8×
+```
+
+**协程和多进程不是二选一**：协程解决并发模型，多进程解决多核，单进程再优化
+也只能用一个核。两者叠加才是终态。默认关的理由见 CHANGELOG 的 0.7.0 一节。
+
 初始化配置（推荐）：
 
 ```bash
@@ -293,6 +303,11 @@ IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -w
 `[CLUSTER].allow_remote_install`：它等于允许调用方在那台机器上跑 pip，
 是从"能代发 HTTP 请求"到"能改本机 Python 环境"的实质提权。
 
+> **一个例外，说在前面**：Web 管理端「生成部署材料」产出的子节点 `ipclick.toml`
+> 里，这一项是**打开**的——理由是那份配置本来就由主控生成，你已经信任它了，
+> 否则逐台 SSH 上去装适配器很烦。不想要就把生成出来的那一行改成 `false`，
+> 之后主控的组件页对这台会返回"未开启"。
+
 **从 curl 导入**：浏览器 DevTools 里对着请求「复制为 cURL」，粘进输入框就能自动
 填好 URL / 方法 / 请求头 / 请求体。认不出的参数会明确列出来，不静默丢弃。
 
@@ -310,7 +325,7 @@ IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -w
 
 ### 能改什么、不能改什么
 
-- **能改**（写回 toml，保留注释与格式，改动前留 `.bak`）：69 项，分 12 组——服务端、
+- **能改**（写回 toml，保留注释与格式，改动前留 `.bak`）：74 项，分 12 组——服务端、
   日志、下载行为、重试、连接池、按 host 限流、浏览器渲染、代理、集群、链路记录、
   Web 管理端、客户端与压缩。
 - **不能改**：`[SECURITY]` 全部（令牌、TLS、SSRF 三个开关）、Web 自己的登录凭据、
@@ -520,7 +535,7 @@ docker run -d -p 9528:9528 --name ipclick ipclick:latest              # gRPC
 docker run -d -p 9528:9528 -p 9527:9527 --name ipclick ipclick:latest  # 再带上 Web 管理端
 ```
 
-镜像多阶段构建、非 root 运行。详细说明见 [`docker/构建.md`](docker/构建.md)。
+镜像多阶段构建、非 root 运行。详细说明见 [`docker/构建.md`](https://github.com/yuanqimanong/IPClick/blob/master/docker/%E6%9E%84%E5%BB%BA.md)。
 
 ## 🚧 已知限制
 

{ipclick-0.6.0 → ipclick-0.7.0}/README.md

@@ -110,6 +110,16 @@ max_concurrent_rpcs = 0    # 0 = max_workers × 8。这一项决定"排队能排
 实测并发 100 时：单进程 196.6 → 331.1 QPS，四进程 → 544.6 QPS；
 1000 并发的成功率从 25.8%（异步客户端）回到 100%。详见 CHANGELOG 的 0.6.0 一节。
 
+0.7.0 起还可以把服务端换成协程（实验性，默认关）：
+
+```toml
+[SERVER]
+async_mode = true    # grpc.aio + 协程，不再一请求一线程。实测端到端 1.8×
+```
+
+**协程和多进程不是二选一**：协程解决并发模型，多进程解决多核，单进程再优化
+也只能用一个核。两者叠加才是终态。默认关的理由见 CHANGELOG 的 0.7.0 一节。
+
 初始化配置（推荐）：
 
 ```bash
@@ -248,6 +258,11 @@ IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -w
 `[CLUSTER].allow_remote_install`：它等于允许调用方在那台机器上跑 pip，
 是从"能代发 HTTP 请求"到"能改本机 Python 环境"的实质提权。
 
+> **一个例外，说在前面**：Web 管理端「生成部署材料」产出的子节点 `ipclick.toml`
+> 里，这一项是**打开**的——理由是那份配置本来就由主控生成，你已经信任它了，
+> 否则逐台 SSH 上去装适配器很烦。不想要就把生成出来的那一行改成 `false`，
+> 之后主控的组件页对这台会返回"未开启"。
+
 **从 curl 导入**：浏览器 DevTools 里对着请求「复制为 cURL」，粘进输入框就能自动
 填好 URL / 方法 / 请求头 / 请求体。认不出的参数会明确列出来，不静默丢弃。
 
@@ -265,7 +280,7 @@ IPCLICK_WEB_USER=ops IPCLICK_WEB_PASSWORD=... ipclick run -w
 
 ### 能改什么、不能改什么
 
-- **能改**（写回 toml，保留注释与格式，改动前留 `.bak`）：69 项，分 12 组——服务端、
+- **能改**（写回 toml，保留注释与格式，改动前留 `.bak`）：74 项，分 12 组——服务端、
   日志、下载行为、重试、连接池、按 host 限流、浏览器渲染、代理、集群、链路记录、
   Web 管理端、客户端与压缩。
 - **不能改**：`[SECURITY]` 全部（令牌、TLS、SSRF 三个开关）、Web 自己的登录凭据、
@@ -475,7 +490,7 @@ docker run -d -p 9528:9528 --name ipclick ipclick:latest              # gRPC
 docker run -d -p 9528:9528 -p 9527:9527 --name ipclick ipclick:latest  # 再带上 Web 管理端
 ```
 
-镜像多阶段构建、非 root 运行。详细说明见 [`docker/构建.md`](docker/构建.md)。
+镜像多阶段构建、非 root 运行。详细说明见 [`docker/构建.md`](https://github.com/yuanqimanong/IPClick/blob/master/docker/%E6%9E%84%E5%BB%BA.md)。
 
 ## 🚧 已知限制
 

{ipclick-0.6.0 → ipclick-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ipclick"
-version = "0.6.0"
+version = "0.7.0"
 description = "IPClick Tool"
 authors = [
     { name = "元气码农少女酱", email = "1276162429@qq.com" }
@@ -12,7 +12,11 @@ dependencies = [
     "curl-cffi>=0.16.0,<0.17.0",
     "grpcio>=1.83.0,<2.0.0",
     "grpcio-health-checking>=1.83.0,<2.0.0",
-    "protobuf>=6.33.2,<8.0.0",
+    # 下限必须 >= 生成代码的 gencode 版本：src/ipclick/dto/proto/task_pb2.py 里
+    # 有 ValidateProtobufRuntimeVersion(..., 7, 35, 1) 的硬校验，运行时低于它
+    # 就直接 import 失败。实际上 grpcio-health-checking 也顶着同一个下限，
+    # 所以写 6.33.2 装不出问题——但那是靠别人兜着，不是这里声明对了。
+    "protobuf>=7.35.1,<8.0.0",
     "click>=8.4.2,<9.0.0",
     "fake-useragent>=2.2.0,<3.0.0",
     "loguru>=0.7.3,<0.8.0",
@@ -69,6 +73,9 @@ dev = [
     "pytest>=9.1.1",
     "pytest-cov>=7.0.0",
     "pytest-asyncio>=1.0.0",
+    # 并行跑测试。整套串行 72 秒、-n 4 只要 25 秒（2.8×），而 CI 上测试这一步
+    # 本来就占整个 job 的 79%（177s / 223s）。
+    "pytest-xdist>=3.6.0",
     # 测试里现生成自签名证书，用来做真实的 TLS/mTLS 握手
     "cryptography>=42.0.0",
 ]

{ipclick-0.6.0 → ipclick-0.7.0}/src/ipclick/__init__.py

@@ -29,7 +29,7 @@ try:
     __version__ = importlib.metadata.version("ipclick")
     __author__ = importlib.metadata.metadata("ipclick")["Author"]
 except importlib.metadata.PackageNotFoundError:  # pragma: no cover - 仅在未安装时走到
-    __version__ = "0.6.0"
+    __version__ = "0.7.0"
     __author__ = "元气码农少女酱"
 
 

{ipclick-0.6.0 → ipclick-0.7.0}/src/ipclick/adapters/base.py

@@ -1,12 +1,13 @@
 from abc import ABC, abstractmethod
-from collections.abc import Callable, Iterator
+import asyncio
+from collections.abc import AsyncIterator, Callable, Iterator
 from dataclasses import dataclass, field
 import functools
 from random import randrange, uniform
 import re
 import threading
 import time
-from typing import Any
+from typing import Any, cast
 
 from ipclick.adapters.settings import DEFAULT_RETRY_STATUS_CODES, AdapterSettings
 from ipclick.dto.response import Response
@@ -186,6 +187,90 @@ def retry(
     return decorator
 
 
+def aretry(
+    max_retries_attr: str = "max_retries", retry_delay_attr: str = "retry_delay"
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """:func:`retry` 的异步版。
+
+    单独写一份而不是复用同步那个：里面的 ``time.sleep`` 在协程里会**阻塞整个
+    事件循环**——不是拖慢这一个请求，是让同一个循环上所有在飞的请求一起停住。
+    默认退避 1+2+4 秒，一次重试就能把整个 worker 冻结七秒，而现象是"毫不相干的
+    请求也集体变慢"，极难联想到是某个失败请求在退避。
+
+    行为与同步版逐条对齐：只重试真正值得重试的，ValidationError / AdapterError
+    直接抛（重试改变不了参数写错或依赖没装）。
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(func)
+        async def wrapper(self: Any, *args: Any, **kwargs: Any) -> Response:
+            requested_retries = kwargs.get("max_retries")
+            max_retries = max(
+                0, int(requested_retries) if requested_retries is not None else getattr(self, max_retries_attr, 3)
+            )
+            requested_delay = kwargs.get("retry_delay")
+            base_delay = _coerce_delay(
+                requested_delay if requested_delay is not None else getattr(self, retry_delay_attr, 1.0),
+                default=1.0,
+            )
+            url = args[0] if args else kwargs.get("url", "unknown")
+            allowed = kwargs.get("allowed_status_codes") or None
+
+            settings: AdapterSettings | None = getattr(self, "settings", None)
+            retry_codes = settings.retry_codes if settings else DEFAULT_RETRY_STATUS_CODES
+            exponent = settings.backoff_exponent if settings else 2.0
+            max_backoff = settings.max_backoff if settings else MAX_RETRY_DELAY
+
+            last_exception: Exception | None = None
+            for attempt in range(max_retries + 1):
+                start_time = time.monotonic()
+                try:
+                    result = await func(self, *args, **kwargs)
+                    if hasattr(result, "elapsed_ms") and result.elapsed_ms == 0:
+                        result.elapsed_ms = int((time.monotonic() - start_time) * 1000)
+                    if hasattr(result, "attempts"):
+                        result.attempts = attempt + 1
+
+                    status = getattr(result, "status_code", None)
+                    if (
+                        attempt < max_retries
+                        and isinstance(status, int)
+                        and status in retry_codes
+                        and not (allowed and status in allowed)
+                    ):
+                        sleep_time = _backoff(attempt, base_delay, exponent, max_backoff)
+                        get_recorder().record_retry(getattr(self, "adapter_name", "unknown"), "status_code")
+                        log.warning(
+                            f"Download {url} returned {status}, retrying {attempt + 1}/{max_retries} "
+                            f"in {sleep_time:.1f}s..."
+                        )
+                        await asyncio.sleep(sleep_time)
+                        continue
+                    return result
+
+                except (ValidationError, AdapterError):
+                    raise
+                except Exception as e:
+                    last_exception = e
+                    if attempt >= max_retries:
+                        return Response.error_response(url, e, attempts=attempt + 1)
+                    sleep_time = _backoff(attempt, base_delay, exponent, max_backoff)
+                    get_recorder().record_retry(getattr(self, "adapter_name", "unknown"), "exception")
+                    log.warning(
+                        f"Download {url} failed, retrying {attempt + 1}/{max_retries} "
+                        f"in {sleep_time:.1f}s... Error: {e}"
+                    )
+                    await asyncio.sleep(sleep_time)
+
+            return Response.error_response(
+                url, last_exception or Exception("Max retries exceeded"), attempts=max_retries + 1
+            )
+
+        return wrapper
+
+    return decorator
+
+
 def _backoff(
     attempt: int,
     base_delay: float,
@@ -371,6 +456,46 @@ class DownloaderAdapter(ABC):
         """
         raise NotImplementedError
 
+    #: 这个适配器有没有自己的异步实现。
+    #:
+    #: 服务端的异步模式据此决定走哪条路：True 就 await adownload()，
+    #: False 就把同步的 download() 丢进线程池。**默认 False**——这一条是
+    #: 整套异步化能做成"加法"而不是破坏性变更的关键：项目支持注册自定义
+    #: 适配器（见 README），它们只实现了同步 download()，不该因为服务端换了
+    #: 并发模型就集体失效。
+    supports_async: bool = False
+
+    async def adownload(self, url: str, **kwargs: Any) -> Response:
+        """异步执行一次请求。
+
+        默认实现把同步的 :meth:`download` 丢进线程池——**语义完全一致，
+        只是拿不到协程的好处**（那个线程仍然是稀缺资源）。真正想要收益的
+        适配器覆写此方法并把 ``supports_async`` 置 True。
+
+        为什么不把 download 直接改成 async：那会打断每一个第三方适配器，
+        而它们看不到任何提示——基类方法签名变了，子类的同步实现会被当成
+        协程去 await，报出来的错误（"object Response can't be used in
+        'await' expression"）和真正的原因（"你的适配器该改成 async 了"）
+        之间没有任何字面联系。
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(None, functools.partial(self.download, url, **kwargs))
+
+    async def adownload_stream(self, url: str, **kwargs: Any) -> "AsyncIterator[StreamEvent]":
+        """异步流式。默认把同步迭代器逐个搬到线程池里取。
+
+        逐个搬而不是一次性取完：流式的意义就在于响应体不整个进内存，
+        先 list() 再 yield 等于把这个性质丢掉。
+        """
+        loop = asyncio.get_running_loop()
+        iterator = await loop.run_in_executor(None, functools.partial(self.download_stream, url, **kwargs))
+        sentinel = object()
+        while True:
+            item = await loop.run_in_executor(None, next, iterator, sentinel)
+            if item is sentinel:
+                return
+            yield cast(StreamEvent, item)
+
     def download_stream(
         self,
         url: str,

{ipclick-0.6.0 → ipclick-0.7.0}/src/ipclick/adapters/browser_adapter.py

@@ -47,7 +47,12 @@ from ipclick.adapters.base import (
     raise_if_script_error,
     retry,
 )
-from ipclick.adapters.browser_settings import BLOCKABLE_RESOURCES, WAIT_UNTIL_CHOICES, BrowserSettings
+from ipclick.adapters.browser_settings import (
+    BLOCKABLE_RESOURCES,
+    WAIT_UNTIL_CHOICES,
+    BrowserSettings,
+    resolve_max_pages,
+)
 from ipclick.adapters.settings import AdapterSettings
 from ipclick.dto.response import Response
 from ipclick.exceptions import AdapterError, ValidationError
@@ -83,6 +88,8 @@ class _BrowserWorker:
     def __init__(self, settings: BrowserSettings, engine: str):
         self._settings: BrowserSettings = settings
         self._engine: str = engine
+        #: 上一次算出来的页面上限，只用于变化时打一条日志，避免每次重建都刷屏
+        self._resolved_pages: int = 0
         self._loop: asyncio.AbstractEventLoop | None = None
         self._thread: threading.Thread | None = None
         self._start_lock: threading.Lock = threading.Lock()
@@ -146,8 +153,14 @@ class _BrowserWorker:
             launched = await browser_engines.launch(self._engine, self._settings)
             self._playwright = launched.driver
             self._browser = launched.browser
-            # 信号量跟着浏览器一起重建：旧的那个可能还扣着已经消失的页面的额度
-            self._semaphore = asyncio.Semaphore(self._settings.max_pages)
+            # 信号量跟着浏览器一起重建：旧的那个可能还扣着已经消失的页面的额度。
+            # max_pages = 0 时按本机内存推导（浏览器页面是内存瓶颈，不是 CPU），
+            # 每次重建都重算一次——机器上别的进程占了多少内存是会变的。
+            limit = resolve_max_pages(self._settings.max_pages, self._engine)
+            if limit != self._resolved_pages:
+                self._resolved_pages = limit
+                log.info(f"{self._engine} 页面并发上限：{limit}（max_pages={self._settings.max_pages or 'auto'}）")
+            self._semaphore = asyncio.Semaphore(limit)
             return self._browser
 
     @staticmethod

{ipclick-0.6.0 → ipclick-0.7.0}/src/ipclick/adapters/browser_engines.py

@@ -34,7 +34,7 @@ import sys
 import threading
 from typing import Any, final
 
-from ipclick.adapters.browser_settings import BrowserSettings
+from ipclick.adapters.browser_settings import BrowserSettings, describe_max_pages
 from ipclick.exceptions import AdapterError, ConfigError
 from ipclick.utils import module_probe
 from ipclick.utils.log_util import log
@@ -484,7 +484,10 @@ async def _launch_playwright_like(api: Any, engine: str, settings: BrowserSettin
         await driver.stop()
         raise AdapterError(f"浏览器启动失败（{engine} / {settings.kind}）：{e}。{INSTALL_HINTS[engine]}") from e
 
-    log.info(f"{engine} 浏览器已启动：{settings.kind}, headless={settings.headless}, 页面上限 {settings.max_pages}")
+    log.info(
+        f"{engine} 浏览器已启动：{settings.kind}, headless={settings.headless}, "
+        f"页面上限 {describe_max_pages(settings.max_pages, engine)}"
+    )
     return LaunchedBrowser(driver=driver, browser=browser)
 
 
@@ -551,7 +554,10 @@ async def _launch_camoufox(settings: BrowserSettings) -> LaunchedBrowser:
         await driver.stop()
         raise AdapterError(f"Camoufox 启动失败：{e}。{INSTALL_HINTS['camoufox']}") from e
 
-    log.info(f"camoufox 浏览器已启动：headless={settings.headless}, 页面上限 {settings.max_pages}")
+    log.info(
+        f"camoufox 浏览器已启动：headless={settings.headless}, "
+        f"页面上限 {describe_max_pages(settings.max_pages, 'camoufox')}"
+    )
     return LaunchedBrowser(driver=driver, browser=browser)
 
 

{ipclick-0.6.0 → ipclick-0.7.0}/src/ipclick/adapters/browser_settings.py

@@ -9,6 +9,7 @@
 """
 
 from dataclasses import dataclass, field
+import os
 from typing import Any
 
 
@@ -85,7 +86,10 @@ class BrowserSettings:
     #: 默认拦截的资源类型。图片 / 字体 / 视频对取 HTML 没用，拦掉能省大量时间和带宽。
     block_resources: tuple[str, ...] = ("image", "media", "font")
 
-    #: 同时打开的页面上限。无头浏览器每个页面几十上百 MB，不设上限很容易把机器打满。
+    #: 同时打开的页面上限。``0`` = 按本机内存自动推导（见 :func:`resolve_max_pages`）。
+    #:
+    #: 默认仍是 4 而不是 0——自动推导会因机器而异，静默改变既有部署的行为不合适。
+    #: 想让它跟着机器走就显式写 0。
     max_pages: int = 4
 
     #: 是否允许请求携带 automation_script（在页面里执行任意 JS）。
@@ -161,7 +165,11 @@ class BrowserSettings:
             script_timeout=_as_float(timeout.get("script_exec"), defaults.script_timeout),
             wait_until=wait_until,
             block_resources=block_resources,
-            max_pages=_as_int(config.get("max_pages"), defaults.max_pages),
+            # minimum=0 是关键：0 不是"非法的小值"，而是"按可用内存自动推导"这个
+            # 特性的开关（见 resolve_max_pages）。用默认的 minimum=1 会把它判成
+            # 低于下限、静默回落到静态默认值 4 —— 于是 max_pages = 0 和不写这一行
+            # 完全等价，整个自动推导从配置文件根本走不到。
+            max_pages=_as_int(config.get("max_pages"), defaults.max_pages, minimum=0),
             allow_scripts=bool(config.get("allow_scripts", defaults.allow_scripts)),
             proxy_gateway=gateway,
             proxy_bypass=_as_str_tuple(proxy.get("bypass_list")),
@@ -171,4 +179,123 @@ class BrowserSettings:
         )
 
 
-__all__ = ["BLOCKABLE_RESOURCES", "BROWSER_KINDS", "WAIT_UNTIL_CHOICES", "BrowserSettings"]
+__all__ = [
+    "BLOCKABLE_RESOURCES",
+    "BROWSER_KINDS",
+    "WAIT_UNTIL_CHOICES",
+    "BrowserSettings",
+    "describe_max_pages",
+    "resolve_max_pages",
+]
+
+
+#: 每个并发页面的内存预算（MB），按引擎区分。
+#:
+#: 这些不是精确值，是**保守的量级**：真实占用随页面复杂度浮动很大（一个静态
+#: 页几十 MB，一个重 JS 的应用能到几百）。取保守值的理由是失败代价不对称——
+#: 少开一个页面只是慢一点，多开一个把机器推进 swap 就是请求从几秒变几分钟、
+#: 看起来像卡死，而且很难从现象联想到是并发开太大。
+#:
+#: camoufox 明显更贵：它是 Firefox 加一整套反检测扩展，单个 context 的开销
+#: 高于 Chromium 系。配置注释里"内存紧张的机器（≤4GB）建议设成 1~2"说的
+#: 就是它。
+ENGINE_PAGE_BUDGET_MB: dict[str, int] = {
+    "camoufox": 400,
+    "playwright": 250,
+    "patchright": 250,
+    "drissionpage": 250,
+}
+DEFAULT_PAGE_BUDGET_MB = 300
+
+#: 自动推导时给系统留的余量（MB）。把内存吃到一滴不剩比少开几个页面糟得多。
+MEMORY_HEADROOM_MB = 1024
+
+#: 自动推导的硬上限。再多的页面收益也会被目标站点和网络吃掉，
+#: 而每个页面都是一份实打实的内存。
+MAX_AUTO_PAGES = 16
+
+
+def available_memory_mb() -> int | None:
+    """本机可用内存（MB）。读不出来返回 None，由调用方回落到静态默认值。
+
+    优先读 cgroup 的限额而不是宿主机总量：容器里 ``/proc/meminfo`` 报的是
+    **宿主机**的内存，照它推导会在一个 512MB 的容器里开出十几个页面，
+    然后被 OOM killer 杀掉——而现象只是"容器莫名其妙重启"。
+    """
+    import os
+    from pathlib import Path as _Path
+
+    limits: list[int] = []
+
+    # cgroup v2 → v1，取能读到的那个
+    for path, current in (
+        ("/sys/fs/cgroup/memory.max", "/sys/fs/cgroup/memory.current"),
+        ("/sys/fs/cgroup/memory/memory.limit_in_bytes", "/sys/fs/cgroup/memory/memory.usage_in_bytes"),
+    ):
+        try:
+            raw = _Path(path).read_text(encoding="utf-8").strip()
+            if raw in ("max", ""):
+                continue
+            total = int(raw)
+            # 没设限时内核会报一个天文数字，那等于"不受限"
+            if total <= 0 or total > (1 << 50):
+                continue
+            used = int(_Path(current).read_text(encoding="utf-8").strip() or 0)
+            limits.append(max(0, total - used) // (1024 * 1024))
+            break
+        except (OSError, ValueError):
+            continue
+
+    try:
+        meminfo = _Path("/proc/meminfo").read_text(encoding="utf-8")
+        for line in meminfo.splitlines():
+            if line.startswith("MemAvailable:"):
+                limits.append(int(line.split()[1]) // 1024)
+                break
+    except (OSError, ValueError, IndexError):
+        pass
+
+    if not limits:
+        try:
+            page_size = os.sysconf("SC_PAGE_SIZE")
+            limits.append(os.sysconf("SC_AVPHYS_PAGES") * page_size // (1024 * 1024))
+        except (ValueError, OSError, AttributeError):
+            return None
+
+    return min(limits) if limits else None
+
+
+def resolve_max_pages(configured: int, engine: str) -> int:
+    """算出真正生效的页面并发上限。
+
+    ``configured > 0`` 就照用——显式配置永远优先，自动推导不该覆盖人的决定。
+
+    ``configured == 0`` 时按**内存**推导，而不是 CPU 核数。这一点容易搞反：
+    浏览器页面是内存瓶颈不是 CPU 瓶颈，按核数算的话一台 16 核 4GB 的机器会
+    开出 16 个 camoufox 页面（约 6.4GB），直接换页。CPU 核数只做上限——
+    页面渲染确实要 CPU，开得比核数多也没意义。
+    """
+    if configured > 0:
+        return configured
+
+    budget = ENGINE_PAGE_BUDGET_MB.get(engine.lower(), DEFAULT_PAGE_BUDGET_MB)
+    available = available_memory_mb()
+    if available is None:
+        # 读不出内存就退回静态默认值，别自作聪明
+        return BrowserSettings.max_pages
+
+    usable = max(0, available - MEMORY_HEADROOM_MB)
+    by_memory = usable // budget
+    by_cpu = os.cpu_count() or 1
+    return max(1, min(by_memory, by_cpu, MAX_AUTO_PAGES))
+
+
+def describe_max_pages(configured: int, engine: str) -> str:
+    """给人看的页面上限。
+
+    只显示配置的原始值会误导：配了 ``0``（自动推导）的人看到"页面上限 0"，
+    合理的推断是"并发被关掉了"或"这个特性没生效"，而实际生效的是推导出来的
+    那个数。状态页、CLI、启动日志三处都曾这么显示。
+    """
+    resolved = resolve_max_pages(configured, engine)
+    return str(resolved) if configured > 0 else f"{resolved}（auto）"