fix(browser): 修复内置有头浏览器与并发端口占满

Author: genz27

Dockerfile.headed

@@ -5,8 +5,18 @@ WORKDIR /app
 ENV PYTHONDONTWRITEBYTECODE=1 \
     PYTHONUNBUFFERED=1 \
     ALLOW_DOCKER_HEADED_CAPTCHA=true \
+    DISPLAY=:99 \
+    PERSONAL_BROWSER_HEADLESS=0 \
     PLAYWRIGHT_BROWSERS_PATH=0
 
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        fluxbox \
+        x11-utils \
+        xauth \
+        xvfb \
+    && rm -rf /var/lib/apt/lists/*
+
 # 在镜像构建阶段预装 Playwright Chromium，供 personal/browser 模式复用
 COPY requirements.txt ./
 

README.md

@@ -72,6 +72,7 @@ docker-compose -f docker-compose.warp.yml logs -f
 > 适用于你有虚拟化桌面需求、希望在容器里启用有头浏览器打码的场景。  
 > 该模式默认启动 `Xvfb + Fluxbox` 实现容器内部可视化，并设置 `ALLOW_DOCKER_HEADED_CAPTCHA=true`。  
 > 仅开放应用端口，不提供任何远程桌面连接端口。
+> `personal` 内置浏览器现在默认按有头模式启动；如需临时切回无头，可额外设置环境变量 `PERSONAL_BROWSER_HEADLESS=true`。
 
 ```bash
 # 启动有头模式（首次建议带 --build）

config/setting_example.toml

@@ -55,6 +55,7 @@ base_url = ""   # 缓存文件访问的基础URL, 留空则使用服务器地址
 
 [captcha]
 captcha_method = "browser"  # 打码方式: yescaptcha/browser/personal/remote_browser
+browser_launch_background = true  # 有头浏览器是否默认后台启动；设为 false 可直接看到窗口
 browser_recaptcha_settle_seconds = 3.0  # reload/clr 就绪后的额外稳态等待
 browser_count = 1  # browser 模式的有头浏览器实例数量
 personal_project_pool_size = 4  # personal 模式下单个 Token 默认维护的项目池数量（仅影响项目轮换，不决定打码标签页数量）

docker-compose.headed.yml

@@ -2,6 +2,7 @@ version: '3.8'
 
 services:
   flow2api-headed:
+    init: true
     build:
       context: .
       dockerfile: Dockerfile.headed
@@ -16,5 +17,7 @@ services:
     environment:
       - PYTHONUNBUFFERED=1
       - ALLOW_DOCKER_HEADED_CAPTCHA=true
+      - DISPLAY=:99
+      - XVFB_SCREEN=1440x900x24
     shm_size: "2gb"
     restart: unless-stopped

docker/entrypoint.headed.sh

@@ -1,6 +1,10 @@
 #!/bin/sh
 set -eu
 
+DISPLAY_VALUE="${DISPLAY:-:99}"
+XVFB_SCREEN_VALUE="${XVFB_SCREEN:-1440x900x24}"
+export DISPLAY="${DISPLAY_VALUE}"
+
 resolve_browser_path() {
 python - <<'PY'
 from playwright.sync_api import sync_playwright
@@ -17,7 +21,32 @@ if [ -z "${BROWSER_EXECUTABLE_PATH:-}" ] || [ ! -x "${BROWSER_EXECUTABLE_PATH:-}
     fi
 fi
 
-echo "[entrypoint] starting flow2api (headless browser mode)"
+if [ "${ALLOW_DOCKER_HEADED_CAPTCHA:-true}" = "true" ] || [ "${ALLOW_DOCKER_HEADED_CAPTCHA:-1}" = "1" ]; then
+    display_suffix="$(printf '%s' "${DISPLAY}" | sed 's/^://; s/\..*$//')"
+    socket_path="/tmp/.X11-unix/X${display_suffix}"
+
+    mkdir -p /tmp/.X11-unix
+    rm -f "/tmp/.X${display_suffix}-lock"
+
+    echo "[entrypoint] starting Xvfb on DISPLAY=${DISPLAY} (${XVFB_SCREEN_VALUE})"
+    Xvfb "${DISPLAY}" -screen 0 "${XVFB_SCREEN_VALUE}" -ac +extension RANDR >/tmp/xvfb.log 2>&1 &
+
+    waited=0
+    while [ ! -S "${socket_path}" ] && [ "${waited}" -lt 100 ]; do
+        sleep 0.1
+        waited=$((waited + 1))
+    done
+
+    if [ ! -S "${socket_path}" ]; then
+        echo "[entrypoint] failed to start Xvfb, socket not ready: ${socket_path}" >&2
+        exit 1
+    fi
+
+    echo "[entrypoint] starting Fluxbox on DISPLAY=${DISPLAY}"
+    fluxbox >/tmp/fluxbox.log 2>&1 &
+fi
+
+echo "[entrypoint] starting flow2api (headed browser mode)"
 if [ -n "${BROWSER_EXECUTABLE_PATH:-}" ] && [ -x "${BROWSER_EXECUTABLE_PATH}" ]; then
     echo "[entrypoint] browser executable: ${BROWSER_EXECUTABLE_PATH}"
     "${BROWSER_EXECUTABLE_PATH}" --version || true

src/main.py

@@ -144,6 +144,12 @@ async def auto_unban_task():
         await auto_unban_task_handle
     except asyncio.CancelledError:
         pass
+    # Close shared HTTP session pools
+    try:
+        await flow_client.close()
+        print("✓ Flow client HTTP session closed")
+    except Exception as e:
+        print(f"⚠ Flow client close failed: {e}")
     # Close browser if initialized
     if browser_service:
         await browser_service.close()

src/services/browser_captcha_personal.py

@@ -52,6 +52,20 @@ def _is_truthy_env(name: str) -> bool:
     return value.strip().lower() in {"1", "true", "yes", "on"}
 
 
+def _get_optional_bool_env(name: str) -> Optional[bool]:
+    """读取可选布尔环境变量，未设置或无法识别时返回 None。"""
+    value = os.environ.get(name)
+    if value is None:
+        return None
+
+    normalized = value.strip().lower()
+    if normalized in {"1", "true", "yes", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "off"}:
+        return False
+    return None
+
+
 ALLOW_DOCKER_HEADED = (
     _is_truthy_env("ALLOW_DOCKER_HEADED_CAPTCHA")
     or _is_truthy_env("ALLOW_DOCKER_BROWSER_CAPTCHA")
@@ -555,7 +569,7 @@ class BrowserCaptchaService:
 
     def __init__(self, db=None):
         """初始化服务"""
-        self.headless = True  # 无头模式
+        self.headless = self._resolve_headless_mode()  # 默认改为有头，可用环境变量回退到无头
         self.browser = None
         self._initialized = False
         self.website_key = "6LdsFiUsAAAAAIjVDZcuLhaHiDn5nnHVXVRQGeMV"
@@ -640,6 +654,18 @@ async def reload_config(self):
             f"fingerprint_ttl {old_fingerprint_ttl}s->{self._fingerprint_cache_ttl_seconds}s"
         )
 
+    def _resolve_headless_mode(self) -> bool:
+        """personal 模式默认改为有头，仅在显式环境变量要求时回退到无头。"""
+        for env_name in ("PERSONAL_BROWSER_HEADLESS", "FLOW2API_PERSONAL_HEADLESS"):
+            override = _get_optional_bool_env(env_name)
+            if override is not None:
+                debug_logger.log_info(
+                    f"[BrowserCaptcha] Personal headless 模式由环境变量 {env_name} 控制: {override}"
+                )
+                return override
+
+        return False
+
     def _refresh_runtime_tunables(self):
         """刷新运行时调优参数，缺省时使用保守的低开销默认值。"""
         try:
@@ -1454,6 +1480,7 @@ async def initialize(self):
                     self._proxy_url = f"{protocol}://{host}:{port}"
                     debug_logger.log_info(f"[BrowserCaptcha] Personal 浏览器代理: {self._proxy_url}")
 
+                launch_in_background = bool(getattr(config, "browser_launch_background", True))
                 browser_args = [
                     '--disable-quic',
                     '--disable-features=UseDnsHttpsSvcb',
@@ -1463,7 +1490,6 @@ async def initialize(self):
                     '--disable-infobars',
                     '--hide-scrollbars',
                     '--window-size=1280,720',
-                    '--window-position=3000,3000',
                     '--profile-directory=Default',
                     '--disable-background-networking',
                     '--disable-sync',
@@ -1473,6 +1499,20 @@ async def initialize(self):
                     '--no-default-browser-check',
                     '--no-zygote',
                 ]
+                if launch_in_background and not self.headless:
+                    browser_args.extend([
+                        '--start-minimized',
+                        '--disable-background-timer-throttling',
+                        '--disable-renderer-backgrounding',
+                        '--disable-backgrounding-occluded-windows',
+                    ])
+                    if sys.platform.startswith("win"):
+                        browser_args.append('--window-position=-32000,-32000')
+                    else:
+                        browser_args.append('--window-position=3000,3000')
+                    debug_logger.log_info("[BrowserCaptcha] Personal 有头浏览器将以后台模式启动")
+                elif not self.headless:
+                    debug_logger.log_info("[BrowserCaptcha] Personal 有头浏览器将以可见窗口模式启动")
                 if proxy_server_arg:
                     browser_args.append(proxy_server_arg)
                 if self._proxy_ext_dir:
@@ -1503,7 +1543,7 @@ async def initialize(self):
                 debug_logger.log_info(
                     "[BrowserCaptcha] nodriver 启动上下文: "
                     f"docker={IS_DOCKER}, display={display_value or '<empty>'}, "
-                    f"uid={effective_uid}, headless={self.headless}, sandbox=False, "
+                    f"uid={effective_uid}, headless={self.headless}, background={launch_in_background}, sandbox=False, "
                     f"executable={browser_executable_path or '<auto>'}, "
                     f"args={' '.join(effective_launch_args)}"
                 )