duplicate from hkfires

Dockerfile

@@ -0,0 +1,31 @@
+# 使用一个轻量的 Python 官方镜像作为基础
+FROM python:3.11-slim-bookworm
+
+# 设置工作目录，后续的命令都在这个目录下执行
+WORKDIR /app
+
+# 安装运行 Playwright 所需的最小系统依赖集
+# 在同一层中清理 apt 缓存以减小镜像体积
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libatk1.0-0 libatk-bridge2.0-0 libcups2 libdbus-1-3 libdrm2 libgbm1 libgtk-3-0 \
+    libnspr4 libnss3 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxdamage1 \
+    libxext6 libxfixes3 libxrandr2 libxrender1 libxtst6 ca-certificates \
+    fonts-liberation libasound2 libpangocairo-1.0-0 libpango-1.0-0 libu2f-udev xvfb \
+    && rm -rf /var/lib/apt/lists/*
+
+# 拷贝并安装 Python 依赖
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 下载 camoufox
+RUN camoufox fetch
+
+# 将项目中的所有文件拷贝到工作目录
+COPY . .
+
+# 暴露 Hugging Face Spaces 期望的端口（仅在服务器模式下使用）
+EXPOSE 7860
+
+
+# 设置容器启动时要执行的命令
+CMD ["python", "main.py"]

README.md

@@ -1,12 +1,9 @@
 ---
 title: AIStudioBuildWS
-emoji: 🐢
-colorFrom: blue
-colorTo: pink
-sdk: gradio
-sdk_version: 6.14.0
-python_version: '3.13'
-app_file: app.py
+emoji: 🏆
+colorFrom: pink
+colorTo: red
+sdk: docker
 pinned: false
 ---
 

browser/cookie_validator.py

@@ -0,0 +1,85 @@
+import time
+import sys
+from playwright.sync_api import TimeoutError, Error as PlaywrightError
+
+
+class CookieValidator:
+    """Cookie验证器，负责定期验证Cookie的有效性。"""
+
+    def __init__(self, page, context, logger):
+        """
+        初始化Cookie验证器
+
+        Args:
+            page: 主页面实例
+            context: 浏览器上下文
+            logger: 日志记录器
+        """
+        self.page = page
+        self.context = context
+        self.logger = logger
+
+    
+    def validate_cookies_in_main_thread(self):
+        """
+        在主线程中执行Cookie验证（由主线程调用）
+
+        Returns:
+            bool: Cookie是否有效
+        """
+        validation_page = None
+        try:
+            # 创建新标签页（在主线程中执行）
+            self.logger.info("开始Cookie验证...")
+            validation_page = self.context.new_page()
+
+            # 访问验证URL
+            validation_url = "https://aistudio.google.com/apps"
+            validation_page.goto(validation_url, wait_until='domcontentloaded', timeout=30000)
+
+            # 等待页面加载
+            validation_page.wait_for_timeout(2000)
+
+            # 获取最终URL
+            final_url = validation_page.url
+
+            # 检查是否被重定向到登录页面
+            if "accounts.google.com/v3/signin/identifier" in final_url:
+                self.logger.error("Cookie验证失败: 被重定向到登录页面")
+                return False
+
+            if "accounts.google.com/v3/signin/accountchooser" in final_url:
+                self.logger.error("Cookie验证失败: 被重定向到账户选择页面")
+                return False
+
+            # 如果没有跳转到登录页面，就算成功
+            self.logger.info("Cookie验证成功")
+            return True
+
+        except TimeoutError:
+            self.logger.error("Cookie验证失败: 页面加载超时")
+            return False
+
+        except PlaywrightError as e:
+            self.logger.error(f"Cookie验证失败: {e}")
+            return False
+
+        except Exception as e:
+            self.logger.error(f"Cookie验证失败: {e}")
+            return False
+
+        finally:
+            # 关闭验证标签页
+            if validation_page:
+                try:
+                    validation_page.close()
+                except Exception:
+                    pass  # 忽略关闭错误
+
+    def shutdown_instance_on_cookie_failure(self):
+        """
+        因Cookie失效而关闭实例
+        """
+        self.logger.error("Cookie失效，关闭实例")
+        time.sleep(1)
+        sys.exit(1)

browser/instance.py

@@ -0,0 +1,278 @@
+import os
+import signal
+import time
+from playwright.sync_api import TimeoutError, Error as PlaywrightError
+from utils.logger import setup_logging
+from utils.cookie_manager import CookieManager
+from browser.navigation import handle_successful_navigation, KeepAliveError
+from browser.cookie_validator import CookieValidator
+from camoufox.sync_api import Camoufox
+from camoufox.exceptions import InvalidIP, InvalidProxy
+from utils.paths import logs_dir
+from utils.common import parse_headless_mode, ensure_dir, parse_proxy_config
+from utils.url_helper import extract_url_path, mask_url_for_logging, mask_path_for_logging
+
+
+def run_browser_instance(config, shutdown_event=None):
+    """
+    根据最终合并的配置，启动并管理一个单独的 Camoufox 浏览器实例。
+    使用CookieManager统一管理Cookie加载，避免重复的扫描逻辑。
+    """
+    # 重置信号处理器，确保子进程能响应 SIGTERM
+    signal.signal(signal.SIGTERM, signal.SIG_DFL)
+    # 忽略 SIGINT (Ctrl+C)，让主进程统一处理
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+
+    cookie_source = config.get('cookie_source')
+    if not cookie_source:
+        # 使用默认logger进行错误报告
+        logger = setup_logging(os.path.join(logs_dir(), 'app.log'))
+        logger.error("错误: 配置中缺少cookie_source对象")
+        return
+
+    instance_label = cookie_source.display_name
+    logger = setup_logging(
+        os.path.join(logs_dir(), 'app.log'), prefix=instance_label
+    )
+    diagnostic_tag = instance_label.replace(os.sep, "_")
+
+    expected_url = config.get('url')
+    proxy = config.get('proxy')
+    headless_setting = config.get('headless', 'virtual')
+
+    # 使用CookieManager加载Cookie
+    cookie_manager = CookieManager(logger)
+    all_cookies = []
+
+    try:
+        # 直接使用CookieSource对象加载Cookie
+        cookies = cookie_manager.load_cookies(cookie_source)
+        all_cookies.extend(cookies)
+
+    except Exception as e:
+        logger.error(f"从Cookie来源加载时出错: {e}")
+        return
+
+    # 3. 检查是否有任何Cookie可用
+    if not all_cookies:
+        logger.error("错误: 没有可用的Cookie（既没有有效的JSON文件，也没有环境变量）")
+        return
+
+    cookies = all_cookies
+
+    headless_mode = parse_headless_mode(headless_setting)
+    launch_options = {"headless": headless_mode}
+    # launch_options["block_images"] = True  # 禁用图片加载
+    
+    if proxy:
+        proxy_config = parse_proxy_config(proxy)
+        if not proxy_config:
+            logger.error("错误: 代理配置无效，无法启动浏览器实例")
+            return
+        logger.info(f"使用代理: {proxy_config.get('server', proxy)} 访问")
+        launch_options["proxy"] = proxy_config
+        launch_options["geoip"] = True
+    
+    screenshot_dir = logs_dir()
+    ensure_dir(screenshot_dir)
+
+    # 重启控制变量
+    max_retries = int(os.getenv("MAX_RESTART_RETRIES", "5"))
+    retry_count = 0
+    base_delay = 3
+
+    while True:
+        # 检查是否收到全局关闭信号
+        if shutdown_event and shutdown_event.is_set():
+            logger.info("检测到全局关闭事件，浏览器实例不再启动，准备退出")
+            return
+
+        try:
+            with Camoufox(**launch_options) as browser:
+                context = browser.new_context()
+                context.add_cookies(cookies)
+                page = context.new_page()
+
+                # 创建Cookie验证器
+                cookie_validator = CookieValidator(page, context, logger)
+
+                # ####################################################################
+                # ############ 增强的 page.goto() 错误处理和日志记录 ###############
+                # ####################################################################
+                
+                response = None
+                try:
+                    logger.info(f"正在导航到: {mask_url_for_logging(expected_url)} (超时设置为 90 秒)")
+                    # page.goto() 会返回一个 response 对象，我们可以用它来获取状态码等信息
+                    response = page.goto(expected_url, wait_until='domcontentloaded', timeout=90000)
+                    
+                    # 检查HTTP响应状态码
+                    if response:
+                        logger.info(f"导航初步成功，服务器响应状态码: {response.status} {response.status_text}")
+                        if not response.ok: # response.ok 检查状态码是否在 200-299 范围内
+                            logger.warning(f"警告：页面加载成功，但HTTP状态码表示错误: {response.status}")
+                            # 即使状态码错误，也保存快照以供分析
+                            page.screenshot(path=os.path.join(screenshot_dir, f"WARN_http_status_{response.status}_{diagnostic_tag}.png"))
+                    else:
+                        # 对于非http/https的导航（如 about:blank），response可能为None
+                        logger.warning("page.goto 未返回响应对象，可能是一个非HTTP导航")
+
+                except TimeoutError:
+                    # 这是最常见的错误：超时
+                    logger.error(f"导航到 {mask_url_for_logging(expected_url)} 超时 (超过90秒)")
+                    logger.error("可能原因：网络连接缓慢、目标网站服务器无响应、代理问题、或页面资源被阻塞")
+                    # 尝试保存诊断信息
+                    try:
+                        # 截图对于看到页面卡在什么状态非常有帮助（例如，空白页、加载中、Chrome错误页）
+                        screenshot_path = os.path.join(screenshot_dir, f"FAIL_timeout_{diagnostic_tag}.png")
+                        page.screenshot(path=screenshot_path, full_page=True)
+                        logger.info(f"已截取超时时的屏幕快照: {screenshot_path}")
+                        
+                        # 保存HTML可以帮助分析DOM结构，即使在无头模式下也很有用
+                        html_path = os.path.join(screenshot_dir, f"FAIL_timeout_{diagnostic_tag}.html")
+                        with open(html_path, 'w', encoding='utf-8') as f:
+                            f.write(page.content())
+                        logger.info(f"已保存超时时的页面HTML: {html_path}")
+                    except Exception as diag_e:
+                        logger.error(f"在尝试进行超时诊断（截图/保存HTML）时发生额外错误: {diag_e}")
+                    return # 超时后，后续操作无意义，直接终止
+
+                except PlaywrightError as e:
+                    # 捕获其他Playwright相关的网络错误，例如DNS解析失败、连接被拒绝等
+                    error_message = str(e)
+                    logger.error(f"导航到 {mask_url_for_logging(expected_url)} 时发生 Playwright 网络错误")
+                    logger.error(f"错误详情: {error_message}")
+                    
+                    # Playwright的错误信息通常很具体，例如 "net::ERR_CONNECTION_REFUSED"
+                    if "net::ERR_NAME_NOT_RESOLVED" in error_message:
+                        logger.error("排查建议：检查DNS设置或域名是否正确")
+                    elif "net::ERR_CONNECTION_REFUSED" in error_message:
+                        logger.error("排查建议：目标服务器可能已关闭，或代理/防火墙阻止了连接")
+                    elif "net::ERR_INTERNET_DISCONNECTED" in error_message:
+                        logger.error("排查建议：检查本机的网络连接")
+                    
+                    # 同样，尝试截图，尽管此时页面可能完全无法访问
+                    try:
+                        screenshot_path = os.path.join(screenshot_dir, f"FAIL_network_error_{diagnostic_tag}.png")
+                        page.screenshot(path=screenshot_path)
+                        logger.info(f"已截取网络错误时的屏幕快照: {screenshot_path}")
+                    except Exception as diag_e:
+                        logger.error(f"在尝试进行网络错误诊断（截图）时发生额外错误: {diag_e}")
+
+                    error_message_lower = error_message.lower()
+                    if "proxy" in error_message_lower or "ns_error_proxy" in error_message_lower or "err_proxy" in error_message_lower:
+                        raise KeepAliveError(f"代理连接错误: {error_message}")
+                    return # 网络错误，终止
+
+                # --- 如果导航没有抛出异常，继续执行后续逻辑 ---
+                
+                logger.info("页面初步加载完成，正在检查并处理初始弹窗...")
+                page.wait_for_timeout(2000)
+                
+                final_url = page.url
+                logger.info(f"导航完成。最终URL为: {mask_url_for_logging(final_url)}")
+
+                # ... 你原有的URL检查逻辑保持不变 ...
+                if "accounts.google.com/v3/signin/identifier" in final_url:
+                    logger.error("检测到Google登录页面（需要输入邮箱）。Cookie已完全失效")
+                    page.screenshot(path=os.path.join(screenshot_dir, f"FAIL_identifier_page_{diagnostic_tag}.png"))
+                    return
+
+                # 提取路径部分进行匹配（允许域名重定向）
+                expected_path = extract_url_path(expected_url).split('?')[0]
+                final_path = extract_url_path(final_url)
+
+                if expected_path and expected_path in final_path:
+                    logger.info(f"URL验证通过。预期路径: {mask_path_for_logging(expected_path)}")
+
+                    # --- 新的健壮策略：等待加载指示器消失 ---
+                    # 这是解决竞态条件的关键。错误消息或内容只在初始加载完成后才会出现。
+                    spinner_locator = page.locator('mat-spinner')
+                    try:
+                        logger.info("正在等待加载指示器 (spinner) 消失... (最长等待30秒)")
+                        # 我们等待spinner变为'隐藏'状态或从DOM中消失。
+                        spinner_locator.wait_for(state='hidden', timeout=30000)
+                        logger.info("加载指示器已消失。页面已完成异步加载")
+                    except TimeoutError:
+                        logger.error("页面加载指示器在30秒内未消失。页面可能已卡住")
+                        page.screenshot(path=os.path.join(screenshot_dir, f"FAIL_spinner_stuck_{diagnostic_tag}.png"))
+                        raise KeepAliveError("页面加载指示器超时")
+
+                    # --- 现在我们可以安全地检查错误消息 ---
+                    # 我们使用最具体的文本以避免误判。
+                    auth_error_text = "authentication error"
+                    auth_error_locator = page.get_by_text(auth_error_text, exact=False)
+
+                    # 这里我们只需要很短的超时时间，因为页面应该是稳定的。
+                    if auth_error_locator.is_visible(timeout=2000):
+                        logger.error(f"检测到认证失败的错误横幅: '{auth_error_text}'. Cookie已过期或无效")
+                        screenshot_path = os.path.join(screenshot_dir, f"FAIL_auth_error_banner_{diagnostic_tag}.png")
+                        page.screenshot(path=screenshot_path)
+                        
+                        # html_path = os.path.join(screenshot_dir, f"FAIL_auth_error_banner_{diagnostic_tag}.html")
+                        # with open(html_path, 'w', encoding='utf-8') as f:
+                        #     f.write(page.content())
+                        # logger.info(f"已保存包含错误信息的页面HTML: {html_path}")
+                        return # 明确的失败，因此我们退出。
+
+                    # --- 如果没有错误，进行最终确认（作为后备方案） ---
+                    logger.info("未检测到认证错误横幅。进行最终确认")
+                    login_button_cn = page.get_by_role('button', name='登录')
+                    login_button_en = page.get_by_role('button', name='Login')
+                    
+                    if login_button_cn.is_visible(timeout=1000) or login_button_en.is_visible(timeout=1000):
+                        logger.error("页面上仍显示'登录'按钮。Cookie无效")
+                        page.screenshot(path=os.path.join(screenshot_dir, f"FAIL_login_button_visible_{diagnostic_tag}.png"))
+                        return
+
+                    # --- 如果所有检查都通过，我们假设成功 ---
+                    logger.info("所有验证通过，确认已成功登录")
+
+                    handle_successful_navigation(page, logger, diagnostic_tag, shutdown_event, cookie_validator)
+                elif "accounts.google.com/v3/signin/accountchooser" in final_url:
+                    logger.warning("检测到Google账户选择页面。登录失败或Cookie已过期")
+                    page.screenshot(path=os.path.join(screenshot_dir, f"FAIL_chooser_click_failed_{diagnostic_tag}.png"))
+                    return
+                else:
+                    logger.error(f"导航到了意外的URL")
+                    logger.error(f"  预期路径: {mask_path_for_logging(expected_path)}")
+                    logger.error(f"  最终路径: {mask_path_for_logging(final_path)}")
+                    logger.error(f"  最终URL: {mask_url_for_logging(final_url)}")
+                    page.screenshot(path=os.path.join(screenshot_dir, f"FAIL_unexpected_url_{diagnostic_tag}.png"))
+                    return
+
+                # 如果运行到这里且没有异常，表示实例正常结束（例如收到关闭信号）
+                # 正常结束时重置重试计数器
+                retry_count = 0
+                return
+
+        except (InvalidProxy, InvalidIP, KeepAliveError) as e:
+            if isinstance(e, (InvalidProxy, InvalidIP)):
+                retry_reason = f"代理/GeoIP 处理失败: {e}"
+                logger.error(retry_reason)
+            else:
+                retry_reason = str(e)
+            retry_count += 1
+            if retry_count > max_retries:
+                logger.error(f"重试次数已达上限 ({max_retries})，实例不再重启，退出")
+                return
+            
+            # 指数退避：3秒、6秒、12秒、24秒...最长60秒
+            delay = min(base_delay * (2 ** (retry_count - 1)), 60)
+            logger.error(f"浏览器实例出现错误 (重试 {retry_count}/{max_retries})，将在 {delay} 秒后重启浏览器实例: {retry_reason}")
+            time.sleep(delay)
+            continue
+        except KeyboardInterrupt:
+            logger.info(f"用户中断，正在关闭...")
+            return
+        except SystemExit as e:
+            # 捕获Cookie验证失败时��系统退出
+            if e.code == 1:
+                logger.error("Cookie验证失败，关闭进程实例")
+            else:
+                logger.info(f"实例正常退出，退出码: {e.code}")
+            return
+        except Exception as e:
+            # 这是一个最终的捕获，用于捕获所有未预料到的错误
+            logger.exception(f"运行 Camoufox 实例时发生未预料的严重错误: {e}")
+            return

browser/navigation.py

@@ -0,0 +1,150 @@
+import time
+import os
+import random
+from playwright.sync_api import Page, expect
+from utils.paths import logs_dir
+from utils.common import ensure_dir
+from browser.ws_helper import reconnect_ws, get_ws_status, dismiss_interaction_modal, click_in_iframe, PageLocators
+
+class KeepAliveError(Exception):
+    pass
+
+def handle_popup_dialog(page: Page, logger=None):
+    """
+    检查并处理弹窗。
+    交替点击 Got it 和 Continue to the app 按钮直到没有弹窗。
+    """
+    logger.info("开始处理弹窗...")
+    
+    # 定义需要查找的按钮列表
+    button_names = ["Got it", "Continue to the app"]
+    max_iterations = 10  # 最多尝试10轮，防止死循环
+    total_clicks = 0
+    
+    try:
+        for iteration in range(max_iterations):
+            clicked_in_round = False
+            
+            # 等待页面稳定
+            time.sleep(1)
+            
+            # 每轮交替尝试点击所有按钮
+            for button_name in button_names:
+                try:
+                    button_locator = page.locator(f'button:visible:has-text("{button_name}")')
+                    if button_locator.count() > 0 and button_locator.first.is_visible():
+                        # logger.info(f"检测到弹窗: 点击 '{button_name}'")
+                        button_locator.first.click(force=True, timeout=2000)
+                        total_clicks += 1
+                        clicked_in_round = True
+                        time.sleep(1)
+                except:
+                    pass
+            
+            if not clicked_in_round:
+                break
+        
+        if total_clicks > 0:
+            logger.info(f"弹窗处理完成, 共点击 {total_clicks} 次")
+        else:
+            logger.info("未检测到弹窗")
+    except Exception as e:
+        logger.info(f"检查弹窗时发生意外：{e}，将继续执行...")
+
+def handle_successful_navigation(page: Page, logger, cookie_file_config, shutdown_event=None, cookie_validator=None):
+    """
+    在成功导航到目标页面后，执行后续操作（处理弹窗、保持运行）。
+    """
+    logger.info("已成功到达目标页面")
+    page.click('body') # 给予页面焦点
+
+    # 检查并处理弹窗
+    handle_popup_dialog(page, logger=logger)
+
+    # 保存登录成功截图
+    try:
+        from datetime import datetime
+        screenshot_dir = logs_dir()
+        ensure_dir(screenshot_dir)
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        screenshot_path = os.path.join(screenshot_dir, f"SUCCESS_{cookie_file_config}_{timestamp}.png")
+        page.screenshot(path=screenshot_path)
+        logger.info(f"已保存登录成功截图: {screenshot_path}")
+    except Exception as e:
+        logger.warning(f"保存截图失败: {e}")
+
+    if cookie_validator:
+        logger.info("Cookie验证器已创建，将定期验证Cookie有效性")
+
+    logger.info("实例将保持运行状态。每8-15秒随机点击一次页面以保持活动")
+
+    # 等待页面加载和渲染
+    time.sleep(15)
+
+    # 创建 PageLocators 缓存对象，复用 locator 避免内存泄漏
+    locators = PageLocators(page)
+
+    # 记录初始WS状态
+    last_ws_status = get_ws_status(page, logger, locators)
+    logger.info(f"初始WS状态: {last_ws_status}")
+
+    # 添加Cookie验证计数器
+    click_counter = 0
+
+    while True:
+        # 检查是否收到关闭信号
+        if shutdown_event and shutdown_event.is_set():
+            logger.info("收到关闭信号，正在优雅退出保持活动循环...")
+            break
+
+        try:
+            # 检测并关闭interaction-modal遮罩层（如果出现）
+            dismiss_interaction_modal(page, logger, locators)
+
+            # 在iframe内随机移动并点击保活
+            click_in_iframe(page, logger, locators)
+            click_counter += 1
+
+            # 检查WS状态是否发生变化
+            current_ws_status = get_ws_status(page, logger, locators)
+            if current_ws_status != last_ws_status:
+                logger.warning(f"WS状态变更: {last_ws_status} -> {current_ws_status}")
+
+                # 如果状态变成IDLE，尝试重连
+                if current_ws_status == "IDLE":
+                    logger.info("WS状态为IDLE，尝试重连...")
+                    reconnect_ws(page, logger, locators)
+                    current_ws_status = get_ws_status(page, logger, locators)
+                
+                last_ws_status = current_ws_status
+
+            # 每720次点击（约2小时）执行一次完整的Cookie验证
+            if cookie_validator and click_counter >= 720:  # 720 * ~10秒 ≈ 7200秒 ≈ 2小时
+                is_valid = cookie_validator.validate_cookies_in_main_thread()
+
+                if not is_valid:
+                    cookie_validator.shutdown_instance_on_cookie_failure()
+                    return
+
+                click_counter = 0  # 重置计数器
+
+            # 使用可中��的随机睡眠（8-15秒），每秒检查一次关闭信号
+            sleep_duration = random.randint(8, 15)
+            for _ in range(sleep_duration):
+                if shutdown_event and shutdown_event.is_set():
+                    logger.info("收到关闭信号，正在优雅退出保持活动循环...")
+                    return
+                time.sleep(1)
+
+        except Exception as e:
+            logger.error(f"在保持活动循环中出错: {e}")
+            # 在保持活动循环中出错时截屏
+            try:
+                screenshot_dir = logs_dir()
+                ensure_dir(screenshot_dir)
+                screenshot_filename = os.path.join(screenshot_dir, f"FAIL_keep_alive_error_{cookie_file_config}.png")
+                page.screenshot(path=screenshot_filename, full_page=True)
+                logger.info(f"已在保持活动循环出错时截屏: {screenshot_filename}")
+            except Exception as screenshot_e:
+                logger.error(f"在保持活动循环出错时截屏失败: {screenshot_e}")
+            raise KeepAliveError(f"在保持活动循环时出错: {e}")

browser/ws_helper.py

@@ -0,0 +1,348 @@
+import time
+import random
+from playwright.sync_api import Page, FrameLocator
+
+
+class PageLocators:
+    """
+    缓存常用的 Locator 对象，避免每次保活循环都创建新对象导致内存泄漏。
+    Playwright 的 Locator 是惰性的，可以安全复用。
+    """
+    
+    def __init__(self, page: Page):
+        self.page = page
+        # 缓存常用的 locator
+        self._modal = None
+        self._iframe = None
+        self._frame = None
+        self._ws_status = None
+        self._disconnect_btn = None
+        self._connect_btn = None
+    
+    @property
+    def modal(self):
+        """interaction-modal 遮罩层"""
+        if self._modal is None:
+            self._modal = self.page.locator('div.interaction-modal')
+        return self._modal
+    
+    @property
+    def iframe(self):
+        """Preview iframe 元素"""
+        if self._iframe is None:
+            self._iframe = self.page.locator('iframe[title="Preview"]')
+        return self._iframe
+    
+    @property
+    def frame(self):
+        """Preview iframe 的 FrameLocator"""
+        if self._frame is None:
+            self._frame = self.page.frame_locator('iframe[title="Preview"]')
+        return self._frame
+    
+    @property
+    def ws_status(self):
+        """WS 状态文本元素"""
+        if self._ws_status is None:
+            self._ws_status = self.frame.locator('text=/WS:\\s*(CONNECTED|IDLE|CONNECTING|RECONNECTING)/i').first
+        return self._ws_status
+    
+    @property
+    def disconnect_btn(self):
+        """Disconnect 按钮"""
+        if self._disconnect_btn is None:
+            self._disconnect_btn = self.frame.locator('button:has-text("Disconnect")')
+        return self._disconnect_btn
+    
+    @property
+    def connect_btn(self):
+        """Connect 按钮"""
+        if self._connect_btn is None:
+            self._connect_btn = self.frame.locator('button:has-text("Connect")')
+        return self._connect_btn
+
+
+def get_preview_frame(page: Page, logger=None) -> FrameLocator:
+    """
+    获取预览iframe的FrameLocator。
+    """
+    try:
+        # 查找title为"Preview"的iframe
+        frame = page.frame_locator('iframe[title="Preview"]')
+        return frame
+    except Exception as e:
+        if logger:
+            logger.warning(f"获取Preview iframe失败: {e}")
+        return None
+
+
+def get_ws_status(page: Page, logger=None, locators: PageLocators = None) -> str:
+    """
+    获取页面中WS连接状态（在iframe内部）。
+    返回: CONNECTED, IDLE, CONNECTING, RECONNECTING 或 UNKNOWN
+    
+    Args:
+        page: Playwright Page 对象
+        logger: 日志记录器
+        locators: 可选的 PageLocators 缓存对象，传入可避免重复创建 locator
+    """
+    try:
+        if locators:
+            status_element = locators.ws_status
+        else:
+            frame = get_preview_frame(page, logger)
+            if not frame:
+                return "UNKNOWN"
+            status_element = frame.locator('text=/WS:\\s*(CONNECTED|IDLE|CONNECTING|RECONNECTING)/i').first
+        
+        if status_element.is_visible(timeout=3000):
+            text = status_element.text_content()
+            if text:
+                if "RECONNECTING" in text.upper():
+                    return "RECONNECTING"
+                elif "CONNECTED" in text.upper():
+                    return "CONNECTED"
+                elif "IDLE" in text.upper():
+                    return "IDLE"
+                elif "CONNECTING" in text.upper():
+                    return "CONNECTING"
+        return "UNKNOWN"
+    except Exception as e:
+        if logger:
+            logger.warning(f"获取WS状态时出错: {e}")
+        return "UNKNOWN"
+
+
+def click_disconnect(page: Page, logger=None, locators: PageLocators = None) -> bool:
+    """
+    点击Disconnect按钮断开WS连接（在iframe内部）。
+    
+    Args:
+        page: Playwright Page 对象
+        logger: 日志记录器
+        locators: 可选的 PageLocators 缓存对象
+    """
+    try:
+        if locators:
+            disconnect_btn = locators.disconnect_btn
+        else:
+            frame = get_preview_frame(page, logger)
+            if not frame:
+                return False
+            disconnect_btn = frame.locator('button:has-text("Disconnect")')
+        
+        if disconnect_btn.count() > 0 and disconnect_btn.first.is_visible(timeout=3000):
+            disconnect_btn.first.click(timeout=5000)
+            if logger:
+                logger.info("已点击 Disconnect 按钮")
+            time.sleep(1)
+            return True
+        if logger:
+            logger.warning("未找到可见的 Disconnect 按钮")
+        return False
+    except Exception as e:
+        if logger:
+            logger.warning(f"点击 Disconnect 按钮失败: {e}")
+        return False
+
+
+def click_connect(page: Page, logger=None, locators: PageLocators = None) -> bool:
+    """
+    点击Connect按钮建立WS连接（在iframe内部）。
+    
+    Args:
+        page: Playwright Page 对象
+        logger: 日志记录器
+        locators: 可选的 PageLocators 缓存对象
+    """
+    try:
+        if locators:
+            connect_btn = locators.connect_btn
+        else:
+            frame = get_preview_frame(page, logger)
+            if not frame:
+                return False
+            connect_btn = frame.locator('button:has-text("Connect")')
+        
+        if connect_btn.count() > 0 and connect_btn.first.is_visible(timeout=3000):
+            connect_btn.first.click(timeout=5000)
+            if logger:
+                logger.info("已点击 Connect 按钮")
+            time.sleep(1)
+            return True
+        if logger:
+            logger.warning("未找到可见的 Connect 按钮")
+        return False
+    except Exception as e:
+        if logger:
+            logger.warning(f"点击 Connect 按钮失败: {e}")
+        return False
+
+
+def wait_for_ws_connected(page: Page, logger=None, timeout: int = 30, locators: PageLocators = None) -> bool:
+    """
+    等待WS状态变为CONNECTED。
+    """
+    start_time = time.time()
+    while time.time() - start_time < timeout:
+        status = get_ws_status(page, logger, locators)
+        if status == "CONNECTED":
+            return True
+        time.sleep(1)
+    return False
+
+
+def reconnect_ws(page: Page, logger=None, locators: PageLocators = None) -> str:
+    """
+    执行断开再连接的流程，并返回最终WS状态。
+    流程：关闭遮罩 -> Disconnect -> 等待IDLE -> Connect -> 等待CONNECTED -> 获取状态
+    
+    Args:
+        page: Playwright Page 对象
+        logger: 日志记录器
+        locators: 可选的 PageLocators 缓存对象
+    """
+    if logger:
+        logger.info("开始执行WS重连流程: Disconnect -> Connect")
+    
+    # 先关闭 interaction-modal 遮罩层（如果存在）
+    dismiss_interaction_modal(page, logger, locators)
+    
+    # 先断开连接
+    click_disconnect(page, logger, locators)
+    time.sleep(2)
+    
+    # 检查是否变为IDLE
+    status = get_ws_status(page, logger, locators)
+    if logger:
+        logger.info(f"断开后WS状态: {status}")
+    
+    # 再连接
+    click_connect(page, logger, locators)
+    time.sleep(2)
+    
+    # 等待连接成功
+    if wait_for_ws_connected(page, logger, timeout=15, locators=locators):
+        status = get_ws_status(page, logger, locators)
+        if logger:
+            logger.info(f"重连后WS状态: {status}")
+        return status
+    else:
+        status = get_ws_status(page, logger, locators)
+        if logger:
+            logger.warning(f"WS重连超时，当前状态: {status}")
+        return status
+
+
+def dismiss_interaction_modal(page: Page, logger=None, locators: PageLocators = None) -> bool:
+    """
+    检测并关闭 interaction-modal 遮罩层。
+    通过在 iframe 区域内模拟鼠标移动来触发遮罩层关闭。
+    
+    Args:
+        page: Playwright Page 对象
+        logger: 日志记录器
+        locators: 可选的 PageLocators 缓存对象
+    
+    返回: True 如果成功关闭遮罩，False 如果未找到遮罩或关闭失败
+    """
+    try:
+        if locators:
+            modal = locators.modal
+            iframe = locators.iframe
+        else:
+            modal = page.locator('div.interaction-modal')
+            iframe = page.locator('iframe[title="Preview"]')
+        
+        if modal.count() == 0 or not modal.first.is_visible(timeout=500):
+            return False
+        
+        if logger:
+            logger.info("检测到 interaction-modal 遮罩层，尝试关闭...")
+        
+        if iframe.count() > 0:
+            iframe_box = iframe.first.bounding_box()
+            if iframe_box:
+                # 随机起点
+                curr_x = iframe_box['x'] + random.randint(50, int(iframe_box['width']) - 50)
+                curr_y = iframe_box['y'] + random.randint(50, int(iframe_box['height']) - 50)
+                
+                # 持续连续移动直到遮罩关闭，最多尝试30次
+                for i in range(30):
+                    # 从当前位置随机移动一段距离
+                    delta_x = random.randint(-30, 30)
+                    delta_y = random.randint(-20, 20)
+                    curr_x = max(iframe_box['x'] + 20, min(iframe_box['x'] + iframe_box['width'] - 20, curr_x + delta_x))
+                    curr_y = max(iframe_box['y'] + 20, min(iframe_box['y'] + iframe_box['height'] - 20, curr_y + delta_y))
+                    
+                    page.mouse.move(curr_x, curr_y)
+                    time.sleep(0.05)
+                    
+                    # 每次移动后检查遮罩是否关闭
+                    if modal.count() == 0 or not modal.first.is_visible(timeout=100):
+                        if logger:
+                            logger.info("已成功关闭 interaction-modal 遮罩层")
+                        return True
+        
+        return False
+    except Exception as e:
+        if logger:
+            logger.debug(f"关闭 interaction-modal 时出错: {e}")
+        return False
+
+
+def click_in_iframe(page: Page, logger=None, locators: PageLocators = None) -> bool:
+    """
+    在 iframe 内随机移动鼠标并点击一次，用于保活。
+    避开顶部（状态栏和按钮区域）和右侧区域。
+    
+    Args:
+        page: Playwright Page 对象
+        logger: 日志记录器
+        locators: 可选的 PageLocators 缓存对象
+    
+    返回: True 如果成功点击，False 如果失败
+    """
+    try:
+        if locators:
+            iframe = locators.iframe
+        else:
+            iframe = page.locator('iframe[title="Preview"]')
+        
+        if iframe.count() == 0:
+            return False
+        
+        iframe_box = iframe.first.bounding_box()
+        if not iframe_box:
+            return False
+        
+        # 安全区域：避开顶部80像素（状态栏+按钮）和右侧200像素（按钮区域）
+        safe_left = iframe_box['x'] + 50
+        safe_right = iframe_box['x'] + iframe_box['width'] - 200
+        safe_top = iframe_box['y'] + 80
+        safe_bottom = iframe_box['y'] + iframe_box['height'] - 50
+        
+        # 确保安全区域有效
+        if safe_right <= safe_left or safe_bottom <= safe_top:
+            return False
+        
+        # 随机起点（在安全区域内）
+        curr_x = random.randint(int(safe_left), int(safe_right))
+        curr_y = random.randint(int(safe_top), int(safe_bottom))
+        
+        # 随机移动几步（保持在安全区域内）
+        for _ in range(random.randint(3, 6)):
+            delta_x = random.randint(-30, 30)
+            delta_y = random.randint(-20, 20)
+            curr_x = max(int(safe_left), min(int(safe_right), curr_x + delta_x))
+            curr_y = max(int(safe_top), min(int(safe_bottom), curr_y + delta_y))
+            page.mouse.move(curr_x, curr_y)
+            time.sleep(0.05)
+        
+        # 点击当前位置
+        page.mouse.click(curr_x, curr_y)
+        return True
+    except Exception as e:
+        if logger:
+            logger.debug(f"在 iframe 内点击失败: {e}")
+        return False

main.py

@@ -0,0 +1,484 @@
+import os
+import threading
+import multiprocessing
+import signal
+import sys
+import time
+
+# 加载 .env 文件（仅在非 Docker 环境且文件存在时）
+def load_env_file():
+    """加载 .env 文件，不影响已存在的环境变量"""
+    if os.environ.get("DOCKER_ENV") or os.path.exists("/.dockerenv"):
+        return  # Docker 环境，跳过加载
+    try:
+        from dotenv import load_dotenv
+        env_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), ".env")
+        if os.path.exists(env_path):
+            load_dotenv(env_path, override=False)  # override=False 不覆盖已有环境变量
+    except ImportError:
+        pass  # python-dotenv 未安装，跳过
+
+load_env_file()
+
+from browser.instance import run_browser_instance
+from utils.logger import setup_logging
+from utils.paths import cookies_dir, logs_dir
+from utils.cookie_manager import CookieManager
+from utils.common import clean_env_value, ensure_dir
+
+# 全局变量
+app_running = False
+flask_app = None
+# 使用 multiprocessing.Event 实现跨进程通信
+shutdown_event = multiprocessing.Event()
+
+
+class ProcessManager:
+    """进程管理器，负责跟踪和管理浏览器进程"""
+
+    def __init__(self):
+        self.processes = {}  # {process_id: process_info}
+        self.lock = threading.RLock()
+        ensure_dir(logs_dir())
+        self.logger = setup_logging(str(logs_dir() / 'app.log'), prefix="manager")
+
+    def add_process(self, process, config=None):
+        """添加进程到管理器"""
+        with self.lock:
+            pid = process.pid if process and hasattr(process, 'pid') else None
+
+            # 允许添加PID为None的进程（可能还在启动中），但会记录这个情况
+            if pid is None:
+                # 使用临时ID作为key，等获得真实PID后再更新
+                temp_id = f"temp_{len(self.processes)}"
+                self.logger.warning(f"进程PID暂时为None，使用临时ID {temp_id}")
+            else:
+                temp_id = pid
+
+            process_info = {
+                'process': process,
+                'config': config,
+                'pid': pid,
+                'is_alive': True,
+                'start_time': time.time()
+            }
+            self.processes[temp_id] = process_info
+
+    def update_temp_pids(self):
+        """更新临时PID为真实PID"""
+        with self.lock:
+            temp_ids = [k for k in self.processes.keys() if isinstance(k, str) and k.startswith("temp_")]
+            for temp_id in temp_ids:
+                process_info = self.processes[temp_id]
+                process = process_info['process']
+
+                if process and hasattr(process, 'pid') and process.pid is not None:
+                    # 更新为真实PID
+                    self.processes[process.pid] = process_info
+                    del self.processes[temp_id]
+                    process_info['pid'] = process.pid
+
+    def remove_process(self, pid):
+        """从管理器中移除进程"""
+        with self.lock:
+            if pid in self.processes:
+                del self.processes[pid]
+
+    def get_alive_processes(self):
+        """获取所有存活进程"""
+        with self.lock:
+            # 首先尝试更新临时PID
+            self.update_temp_pids()
+
+            alive = []
+            dead_pids = []
+
+            for pid, info in self.processes.items():
+                process = info['process']
+                try:
+                    # 检查进程是否真实存在且是子进程
+                    if process and hasattr(process, 'is_alive') and process.is_alive():
+                        alive.append(process)
+                    else:
+                        dead_pids.append(pid)
+                except (ValueError, ProcessLookupError) as e:
+                    # 进程已经不存在
+                    dead_pids.append(pid)
+                    self.logger.warning(f"进程 {pid} 检查时出错: {e}")
+
+            # 清理死进程记录
+            for pid in dead_pids:
+                self.remove_process(pid)
+
+            return alive
+
+    def terminate_all(self, timeout=10):
+        """优雅地终止所有进程"""
+        with self.lock:
+            # logger = setup_logging(str(logs_dir() / 'app.log'), prefix="signal")
+            # 直接使用 self.logger，避免重复 setup_logging
+
+            # 首先更新临时PID
+            self.update_temp_pids()
+
+            if not self.processes:
+                self.logger.info("没有活跃的进程需要关闭")
+                return
+
+            self.logger.info(f"开始关闭 {len(self.processes)} 个进程...")
+
+            # 第一阶段：发送SIGTERM信号
+            active_pids = []
+            for pid, info in list(self.processes.items()):
+                process = info['process']
+                try:
+                    # 检查进程对象是否有效且进程存活
+                    if process and hasattr(process, 'is_alive') and process.is_alive() and pid is not None:
+                        self.logger.info(f"发送SIGTERM给进程 {pid} (运行时长: {time.time() - info['start_time']:.1f}秒)")
+                        process.terminate()
+                        active_pids.append(pid)
+                    else:
+                        self.logger.info(f"进程 {pid if pid is not None else 'None'} 已经停止或无效")
+                except (ValueError, ProcessLookupError, AttributeError) as e:
+                    self.logger.warning(f"进程 {pid if pid is not None else 'None'} 访问出错: {e}")
+
+            if not active_pids:
+                self.logger.info("所有进程已经停止")
+                return
+
+            # 第二阶段：等待进程退出
+            self.logger.info(f"等待 {len(active_pids)} 个进程优雅退出...")
+            start_wait = time.time()
+            while time.time() - start_wait < 5:  # 最多等待5秒
+                still_alive = []
+                for pid in active_pids:
+                    if pid in self.processes:
+                        process = self.processes[pid]['process']
+                        try:
+                            if process and hasattr(process, 'is_alive') and process.is_alive():
+                                still_alive.append(pid)
+                        except (ValueError, ProcessLookupError, AttributeError):
+                                pass
+                if not still_alive:
+                    self.logger.info("所有进程已优雅退出")
+                    return
+                time.sleep(0.5)
+            
+            self.logger.info(f"仍有 {len(still_alive)} 个进程在运行，准备强制关闭...")
+
+            # 第三阶段：强制杀死仍在运行的进程
+            for pid in active_pids:
+                if pid in self.processes and pid is not None:
+                    process = self.processes[pid]['process']
+                    try:
+                        if process and hasattr(process, 'is_alive') and process.is_alive():
+                            self.logger.warning(f"进程 {pid} 未响应SIGTERM，强制终止")
+                            process.kill()
+                    except (ValueError, ProcessLookupError, AttributeError) as e:
+                        self.logger.info(f"进程 {pid} 已终止: {e}")
+
+            self.logger.info("所有进程关闭完成")
+
+    def get_count(self):
+        """获取管理的进程总数"""
+        with self.lock:
+            return len(self.processes)
+
+    def get_alive_count(self):
+        """获取存活进程数"""
+        return len(self.get_alive_processes())
+
+
+# 全局进程管理器
+process_manager = ProcessManager()
+
+
+def load_instance_configurations(logger):
+    """
+    使用CookieManager解析环境变量和Cookies目录，为每个Cookie来源创建独立的浏览器实例配置。
+    """
+    # 1. 读取所有实例共享的URL
+    shared_url = clean_env_value(os.getenv("CAMOUFOX_INSTANCE_URL"))
+    if not shared_url:
+        logger.error("错误: 缺少环境变量 CAMOUFOX_INSTANCE_URL。所有实例需要一个共享的目标URL")
+        return None, None
+
+    # 2. 读取全局设置
+    global_settings = {
+        "headless": clean_env_value(os.getenv("CAMOUFOX_HEADLESS")) or "virtual",
+        "url": shared_url  # 所有实例都使用这个URL
+    }
+
+    proxy_value = clean_env_value(os.getenv("CAMOUFOX_PROXY"))
+    if proxy_value:
+        global_settings["proxy"] = proxy_value
+
+    # 3. 使用CookieManager检测所有Cookie来源
+    cookie_manager = CookieManager(logger)
+    sources = cookie_manager.detect_all_sources()
+
+    # 检查是否有任何Cookie来源
+    if not sources:
+        logger.error("错误: 未找到任何Cookie来源（既没有JSON文件，也没有环境变量Cookie）")
+        return None, None
+
+    # 4. 为每个Cookie来源创建实例配置
+    instances = []
+    for source in sources:
+        if source.type == "file":
+            instances.append({
+                "cookie_file": source.identifier,
+                "cookie_source": source
+            })
+        elif source.type == "env_var":
+            # 从环境变量名中提取索引，如 "USER_COOKIE_1" -> 1
+            env_index = source.identifier.split("_")[-1]
+            try:
+                env_cookie_index = int(env_index)
+            except ValueError:
+                logger.warning(f"警告: 无法解析 Cookie 环境变量索引，跳过来源: {source.identifier}")
+                continue
+
+            instance_config = {
+                "cookie_file": None,
+                "env_cookie_index": env_cookie_index,
+                "cookie_source": source
+            }
+
+            # 支持每实例独立代理：CAMOUFOX_PROXY_N 对应 USER_COOKIE_N
+            instance_proxy_var = f"CAMOUFOX_PROXY_{env_cookie_index}"
+            instance_proxy_value = clean_env_value(os.getenv(instance_proxy_var))
+            if instance_proxy_value:
+                instance_config["proxy"] = instance_proxy_value
+                logger.info(f"检测到 {source.display_name} 的独立代理配置: {instance_proxy_var}")
+
+            instances.append(instance_config)
+
+    logger.info(f"将启动 {len(instances)} 个浏览器实例")
+
+    return global_settings, instances
+
+def start_browser_instances(run_mode="standalone"):
+    """启动浏览器实例的核心逻辑"""
+    global app_running, process_manager, shutdown_event
+
+    log_dir = logs_dir()
+    logger = setup_logging(str(log_dir / 'app.log'))
+    logger.info("---------------------Camoufox 实例管理器开始启动---------------------")
+    start_delay = int(os.getenv("INSTANCE_START_DELAY", "30"))
+    logger.info(f"运行模式: {run_mode}; 实例启动间隔: {start_delay} 秒")
+
+    global_settings, instance_profiles = load_instance_configurations(logger)
+    if not instance_profiles:
+        logger.error("错误: 环境变量中未找到任何实例配置")
+        return
+
+    for i, profile in enumerate(instance_profiles, 1):
+        if not app_running:
+            break
+
+        final_config = global_settings.copy()
+        final_config.update(profile)
+
+        if 'url' not in final_config:
+            logger.warning(f"警告: 跳过一个无效的配置项 (缺少 url): {profile}")
+            continue
+
+        cookie_source = final_config.get('cookie_source')
+
+        if cookie_source:
+            if cookie_source.type == "file":
+                logger.info(
+                    f"正在启动第 {i}/{len(instance_profiles)} 个浏览器实例 (file: {cookie_source.display_name})..."
+                )
+            elif cookie_source.type == "env_var":
+                logger.info(
+                    f"正在启动第 {i}/{len(instance_profiles)} 个浏览器实例 (env: {cookie_source.display_name})..."
+                )
+        else:
+            logger.error(f"错误: 配置中缺少cookie_source对象")
+            continue
+
+        # 传递 shutdown_event 给子进程
+        process = multiprocessing.Process(target=run_browser_instance, args=(final_config, shutdown_event))
+        process.start()
+        # 等待一小段时间让进程获得PID，然后再添加到管理器
+        time.sleep(0.1)
+        process_manager.add_process(process, final_config)
+
+        # 等待配置的时间，避免并发启动导致的高CPU占用
+        # 即使是最后一个实例，也等待一段时间让其初始化，然后再进入主循环
+        time.sleep(start_delay)
+
+    # 等待所有进程
+    previous_count = None
+    last_log_time = 0
+    try:
+        while app_running:
+            alive_processes = process_manager.get_alive_processes()
+            current_count = len(alive_processes)
+
+            # 仅在数量变化或间隔一段时间后再记录，避免过于频繁的日志
+            now = time.time()
+            if current_count != previous_count or now - last_log_time >= 600:
+                logger.info(f"当前运行的浏览器实例数: {current_count}")
+                previous_count = current_count
+                last_log_time = now
+
+            if not alive_processes:
+                logger.info("所有浏览器进程已结束，主进程即将退出")
+                break
+
+            # 等待进程并清理死进程
+            for process in alive_processes:
+                try:
+                    process.join(timeout=1)
+                except:
+                    pass
+
+            time.sleep(1)
+    except KeyboardInterrupt:
+        logger.info("捕获到键盘中断信号，等待信号处理器完成关闭...")
+        # 不在这里关闭进程，让信号处理器统一处理
+        pass
+
+    # 确保在所有进程结束后退出
+    logger.info("浏览器实例管理器运行结束")
+
+def run_standalone_mode():
+    """独立模式"""
+    global app_running
+    app_running = True
+
+    start_browser_instances(run_mode="standalone")
+
+def run_server_mode():
+    """服务器模式"""
+    global app_running, flask_app
+
+    log_dir = logs_dir()
+    server_logger = setup_logging(str(log_dir / 'app.log'), prefix="server")
+
+    # 动态导入 Flask（只在需要时）
+    try:
+        from flask import Flask, jsonify
+        flask_app = Flask(__name__)
+    except ImportError:
+        server_logger.error("错误: 服务器模式需要 Flask，请安装: pip install flask")
+        return
+
+    app_running = True
+
+    # 在后台线程中启动浏览器实例
+    browser_thread = threading.Thread(target=lambda: start_browser_instances(run_mode="server"), daemon=True)
+    browser_thread.start()
+
+    # 定义路由
+    @flask_app.route('/health')
+    def health_check():
+        """健康检查端点"""
+        global process_manager
+        running_count = process_manager.get_alive_count()
+        total_count = process_manager.get_count()
+        return jsonify({
+            'status': 'healthy',
+            'browser_instances': total_count,
+            'running_instances': running_count,
+            'message': f'Application is running with {running_count} active browser instances'
+        })
+
+    @flask_app.route('/')
+    def index():
+        """主页端点"""
+        global process_manager
+        running_count = process_manager.get_alive_count()
+        total_count = process_manager.get_count()
+        return jsonify({
+            'status': 'running',
+            'browser_instances': total_count,
+            'running_instances': running_count,
+            'run_mode': 'server',
+            'message': 'Camoufox Browser Automation is running in server mode'
+        })
+
+    # 禁用 Flask 的默认日志
+    import logging
+    log = logging.getLogger('werkzeug')
+    log.setLevel(logging.ERROR)
+
+    # 启动 Flask 服务器
+    try:
+        flask_app.run(host='0.0.0.0', port=7860, debug=False)
+    except KeyboardInterrupt:
+        server_logger.info("服务器正在关闭...")
+
+def signal_handler(signum, frame):
+    """统一的信号处理器 - 只有主进程应该执行这个逻辑"""
+    global app_running, process_manager, shutdown_event
+
+    # 立即设置日志，确保能看到后续信息
+    logger = setup_logging(str(logs_dir() / 'app.log'), prefix="signal")
+    logger.info(f"接收到信号 {signum}，开始处理...")
+
+    # 检查是否是主进程，防止子进程执行关闭逻辑
+    current_pid = os.getpid()
+
+    # 使用一个简单的方法来判断：如果是子进程，通常没有全局变量 process_manager 的控制权
+    # 或者通过判断 multiprocessing.current_process().name
+    if multiprocessing.current_process().name != 'MainProcess':
+         # 子进程接收到信号，通常应该由主进程来管理，或者子进程会因为主进程发送的SIGTERM而终止
+         # 这里我们选择忽略，让主进程通过terminate来管理，或者子进程通过shutdown_event来退出
+         logger.info(f"子进程 {current_pid} 接收到信号 {signum}，忽略主进程信号处理逻辑")
+         return
+
+    logger.info(f"主进程 {current_pid} 接收到信号 {signum}，正在关闭应用...")
+
+    # 1. 立即设置全局标志，阻止新的进程创建
+    app_running = False
+
+    # 2. 设置跨进程关闭事件，通知所有子进程优雅退出
+    try:
+        shutdown_event.set()
+        logger.info("已设置全局关闭事件 (shutdown_event)")
+    except Exception as e:
+        logger.error(f"设置关闭事件时发生错误: {e}")
+
+    # 3. 调用进程管理器的优雅终止方法
+    try:
+        process_manager.terminate_all(timeout=10)
+    except Exception as e:
+        logger.error(f"调用 terminate_all 时发生错误: {e}")
+
+    logger.info("应用关闭流程结束，主进程退出")
+    sys.exit(0)
+
+def main():
+    """主入口函数"""
+    # 初始化必要的目录
+    ensure_dir(logs_dir())
+    ensure_dir(cookies_dir())
+
+    # 注册信号处理器 - 添加更多信号的捕获
+    signal.signal(signal.SIGTERM, signal_handler)
+    signal.signal(signal.SIGINT, signal_handler)
+    # 在某些环境中可能还有其他信号
+    try:
+        signal.signal(signal.SIGQUIT, signal_handler)
+    except (ValueError, AttributeError):
+        pass
+    try:
+        signal.signal(signal.SIGHUP, signal_handler)
+    except (ValueError, AttributeError):
+        pass
+
+    # 检查运行模式环境变量
+    hg_mode = os.getenv('HG', '').lower()
+
+    if hg_mode == 'true':
+        run_server_mode()
+    else:
+        run_standalone_mode()
+
+if __name__ == "__main__":
+    multiprocessing.freeze_support()
+    main()

requirements.txt

@@ -0,0 +1,34 @@
+camoufox[geoip]==0.4.11
+aiohappyeyeballs==2.6.1
+aiohttp==3.12.13
+aiosignal==1.3.2
+attrs==25.3.0
+browserforge==1.2.3
+certifi==2025.6.15
+charset-normalizer==3.4.2
+click==8.2.1
+frozenlist==1.7.0
+flask==3.0.0
+geoip2==5.1.0
+greenlet==3.2.3
+idna==3.10
+language-tags==1.2.0
+lxml==5.4.0
+maxminddb==2.7.0
+multidict==6.5.0
+numpy==2.3.0
+orjson==3.10.18
+platformdirs==4.3.8
+playwright==1.52.0
+propcache==0.3.2
+pyee==13.0.0
+PySocks==1.7.1
+requests==2.32.4
+screeninfo==0.8.1
+tqdm==4.67.1
+typing_extensions==4.14.0
+ua-parser==1.0.1
+ua-parser-builtins==0.18.0.post1
+urllib3==2.4.0
+yarl==1.20.1
+python-dotenv>=1.0.0

utils/common.py

@@ -0,0 +1,99 @@
+"""
+通用工具函数
+提供项目中常用的基础功能
+"""
+
+import os
+from pathlib import Path
+from urllib.parse import urlsplit, unquote
+
+def clean_env_value(value):
+    """
+    清理环境变量值，去除首尾空白字符
+
+    Args:
+        value: 环境变量的原始值
+
+    Returns:
+        str or None: 清理后的值，如果为空或None则返回None
+    """
+    if value is None:
+        return None
+    stripped = value.strip()
+    return stripped or None
+
+
+def parse_headless_mode(headless_setting):
+    """
+    解析headless模式配置
+
+    Args:
+        headless_setting: headless配置值
+
+    Returns:
+        bool or str: True表示headless，False表示有界面，'virtual'表示虚拟模式
+    """
+    if str(headless_setting).lower() == 'true':
+        return True
+    elif str(headless_setting).lower() == 'false':
+        return False
+    else:
+        return 'virtual'
+
+
+def ensure_dir(path):
+    """
+    确保目录存在，如果不存在则创建
+
+    Args:
+        path: 目录路径（可以是字符串或Path对象）
+    """
+    if isinstance(path, str):
+        path = Path(path)
+    os.makedirs(path, exist_ok=True)
+
+
+def parse_proxy_config(proxy_value):
+    """
+    解析代理配置字符串为 Playwright/Camoufox 需要的 dict 结构
+
+    支持格式:
+    - scheme://user:pass@host:port
+    - scheme://host:port
+    - host:port
+    - user:pass@host:port (默认 http)
+
+    Returns:
+        dict or None: {"server": "...", "username": "...", "password": "..."} 或 None
+    """
+    if not proxy_value:
+        return None
+
+    proxy_value = proxy_value.strip()
+    if not proxy_value:
+        return None
+
+    if "://" in proxy_value:
+        parsed = urlsplit(proxy_value)
+        if not parsed.hostname:
+            return {"server": proxy_value}
+        scheme = parsed.scheme
+    else:
+        parsed = urlsplit(f"//{proxy_value}")
+        if not parsed.hostname:
+            return {"server": proxy_value}
+        scheme = "http"
+
+    host = parsed.hostname
+    if host and ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    server = f"{scheme}://{host}"
+    if parsed.port:
+        server += f":{parsed.port}"
+
+    result = {"server": server}
+    if parsed.username:
+        result["username"] = unquote(parsed.username)
+    if parsed.password:
+        result["password"] = unquote(parsed.password)
+    return result

utils/cookie_handler.py

@@ -0,0 +1,144 @@
+def convert_cookie_editor_to_playwright(cookies_from_editor, logger=None):
+    """
+    将从 Cookie-Editor 插件导出的 Cookie 列表转换为 Playwright 兼容的格式。
+    """
+    playwright_cookies = []
+
+    for cookie in cookies_from_editor:
+        pw_cookie = {}
+        for key in ['name', 'value', 'domain', 'path', 'httpOnly', 'secure']:
+            if key in cookie:
+                pw_cookie[key] = cookie[key]
+        if cookie.get('session', False):
+            pw_cookie['expires'] = -1
+        elif 'expirationDate' in cookie:
+            if cookie['expirationDate'] is not None:
+                pw_cookie['expires'] = int(cookie['expirationDate'])
+            else:
+                pw_cookie['expires'] = -1
+
+        if 'sameSite' in cookie:
+            same_site_value = str(cookie['sameSite']).lower()
+            if same_site_value == 'no_restriction':
+                pw_cookie['sameSite'] = 'None'
+            elif same_site_value in ['lax', 'strict']:
+                pw_cookie['sameSite'] = same_site_value.capitalize()
+            elif same_site_value == 'unspecified':
+                pw_cookie['sameSite'] = 'Lax'
+
+        if all(key in pw_cookie for key in ['name', 'value', 'domain', 'path']):
+            playwright_cookies.append(pw_cookie)
+        else:
+            if logger:
+                logger.warning(f"跳过一个格式不完整的 Cookie: {cookie}")
+
+    return playwright_cookies
+
+
+def convert_kv_to_playwright(kv_string, default_domain=".google.com", logger=None):
+    """
+    将键值对格式的 Cookie 字符串转换为 Playwright 兼容的格式。
+
+    Args:
+        kv_string (str): 包含 Cookie 的键值对字符串，格式为 "name1=value1; name2=value2; ..."
+        default_domain (str): 默认域名，默认为".google.com"
+        logger: 日志记录器
+
+    Returns:
+        list: Playwright 兼容的 Cookie 列表
+    """
+    playwright_cookies = []
+
+    # 按分号分割 Cookie
+    cookie_pairs = kv_string.split(';')
+
+    for pair in cookie_pairs:
+        pair = pair.strip()  # 去除首尾空白字符
+
+        if not pair:  # 跳过空字符串
+            continue
+
+        # 跳过无效的 Cookie（不包含等号）
+        if '=' not in pair:
+            if logger:
+                logger.warning(f"跳过无效的 Cookie 格式: '{pair}'")
+            continue
+
+        # 分割name和value
+        name, value = pair.split('=', 1)  # 只分割第一个等号
+        name = name.strip()
+        value = value.strip()
+
+        if not name:  # 跳过空名称
+            if logger:
+                logger.warning(f"跳过空名称的 Cookie: '{pair}'")
+            continue
+
+        # 构造 Playwright 格式的 Cookie
+        pw_cookie = {
+            'name': name,
+            'value': value,
+            'domain': default_domain,
+            'path': '/',
+            'expires': -1,  # 默认为会话 Cookie
+            'httpOnly': False,  # KV 格式无法确定 httpOnly 状态，默认为 False
+            'secure': True,     # 假设为安全 Cookie
+            'sameSite': 'Lax'   # 默认 SameSite 策略
+        }
+
+        playwright_cookies.append(pw_cookie)
+
+        if logger:
+            logger.debug(f"成功转换 Cookie: {name} -> domain={default_domain}")
+
+    return playwright_cookies
+
+
+def auto_convert_to_playwright(cookie_data, default_domain=".google.com", logger=None):
+    """
+    自动识别 Cookie 数据格式并转换为 Playwright 兼容格式。
+    支持两种输入格式:
+    1. JSON 数组 (Cookie-Editor 导出格式)
+    2. KV 字符串 (键值对格式: "name1=value1; name2=value2; ...")
+
+    Args:
+        cookie_data: Cookie 数据，可以是 list (JSON格式) 或 str (KV格式)
+        default_domain (str): KV格式使用的默认域名，默认为".google.com"
+        logger: 日志记录器
+
+    Returns:
+        list: Playwright 兼容的 Cookie 列表
+
+    Raises:
+        ValueError: 当格式无法识别时抛出异常
+    """
+    # 格式1: JSON 数组格式 (Cookie-Editor 导出格式)
+    if isinstance(cookie_data, list):
+        if logger:
+            logger.debug(f"检测到 JSON 数组格式的 Cookie 数据，共 {len(cookie_data)} 个条目")
+        return convert_cookie_editor_to_playwright(cookie_data, logger=logger)
+
+    # 格式2: KV 字符串格式
+    if isinstance(cookie_data, str):
+        # 去除首尾空白字符
+        cookie_str = cookie_data.strip()
+
+        if not cookie_str:
+            if logger:
+                logger.warning("收到空的 Cookie 字符串")
+            return []
+
+        if logger:
+            logger.debug(f"检测到 KV 字符串格式的 Cookie 数据")
+
+        return convert_kv_to_playwright(
+            cookie_str,
+            default_domain=default_domain,
+            logger=logger
+        )
+
+    # 无法识别的格式
+    error_msg = f"无法识别的 Cookie 数据格式: {type(cookie_data).__name__}"
+    if logger:
+        logger.error(error_msg)
+    raise ValueError(error_msg)

utils/cookie_manager.py

@@ -0,0 +1,198 @@
+"""
+统一的Cookie管理器
+整合JSON文件和环境变量Cookie的检测、加载和管理功能
+"""
+
+import os
+import json
+from dataclasses import dataclass
+from typing import List, Dict, Optional
+from utils.paths import cookies_dir
+from utils.cookie_handler import auto_convert_to_playwright
+from utils.common import clean_env_value
+
+@dataclass
+class CookieSource:
+    """Cookie来源的统一表示"""
+    type: str  # "file" | "env_var"
+    identifier: str  # filename or "USER_COOKIE_1"
+    display_name: str  # 显示名称
+
+    def __str__(self):
+        return f"{self.type}:{self.identifier}"
+
+
+class CookieManager:
+    """
+    统一的Cookie管理器
+    负责检测、加载和缓存所有来源的Cookie数据
+    """
+
+    def __init__(self, logger=None):
+        self.logger = logger
+        self._detected_sources: Optional[List[CookieSource]] = None
+        self._cookie_cache: Dict[str, List[Dict]] = {}
+
+    def detect_all_sources(self) -> List[CookieSource]:
+        """
+        检测所有可用的Cookie来源（JSON文件 + 环境变量）
+        结果会被缓存，避免重复扫描
+        """
+        if self._detected_sources is not None:
+            return self._detected_sources
+
+        sources = []
+
+        # 1. 扫描Cookies目录中的JSON文件
+        try:
+            cookie_path = cookies_dir()
+            if os.path.isdir(cookie_path):
+                cookie_files = [f for f in os.listdir(cookie_path) if f.lower().endswith('.json')]
+
+                for cookie_file in cookie_files:
+                    source = CookieSource(
+                        type="file",
+                        identifier=cookie_file,
+                        display_name=cookie_file
+                    )
+                    sources.append(source)
+
+                if cookie_files and self.logger:
+                    self.logger.info(f"发现 {len(cookie_files)} 个 Cookie 文件")
+                elif self.logger:
+                    self.logger.info(f"在 {cookie_path} 目录下未找到任何格式的 Cookie 文件")
+            else:
+                if self.logger:
+                    self.logger.error(f"Cookie 目录不存在: {cookie_path}")
+
+        except Exception as e:
+            if self.logger:
+                self.logger.error(f"扫描 Cookie 目录时出错: {e}")
+
+        # 2. 扫描USER_COOKIE环境变量
+        cookie_index = 1
+        env_cookie_count = 0
+
+        while True:
+            env_var_name = f"USER_COOKIE_{cookie_index}"
+            env_value = clean_env_value(os.getenv(env_var_name))
+
+            if not env_value:
+                if cookie_index == 1 and self.logger:
+                    self.logger.info(f"未检测到任何 USER_COOKIE 环境变量")
+                break
+
+            source = CookieSource(
+                type="env_var",
+                identifier=env_var_name,
+                display_name=env_var_name
+            )
+            sources.append(source)
+
+            env_cookie_count += 1
+            cookie_index += 1
+
+        if env_cookie_count > 0 and self.logger:
+            self.logger.info(f"发现 {env_cookie_count} 个 Cookie 环境变量")
+
+        # 缓存结果
+        self._detected_sources = sources
+        return sources
+
+    def load_cookies(self, source: CookieSource) -> List[Dict]:
+        """
+        从指定来源加载Cookie数据
+
+        Args:
+            source: Cookie来源对象
+
+        Returns:
+            Playwright兼容的cookie列表
+        """
+        cache_key = str(source)
+
+        # 检查缓存
+        if cache_key in self._cookie_cache:
+            if self.logger:
+                self.logger.debug(f"从缓存加载 Cookie: {source.display_name}")
+            return self._cookie_cache[cache_key]
+
+        cookies = []
+
+        try:
+            if source.type == "file":
+                cookies = self._load_from_file(source.identifier)
+            elif source.type == "env_var":
+                cookies = self._load_from_env(source.identifier)
+            else:
+                if self.logger:
+                    self.logger.error(f"未知的 Cookie 来源类型: {source.type}")
+                return []
+
+            # 缓存结果
+            self._cookie_cache[cache_key] = cookies
+
+            if self.logger:
+                self.logger.info(f"从 {source.display_name} 加载了 {len(cookies)} 个 Cookie 数据")
+
+        except Exception as e:
+            if self.logger:
+                self.logger.error(f"从 {source.display_name} 加载 Cookie 时出错: {e}")
+            return []
+
+        return cookies
+
+    def _load_from_file(self, filename: str) -> List[Dict]:
+        """从文件加载 Cookie，自动识别 JSON 或 KV 格式"""
+        cookie_path = cookies_dir() / filename
+
+        if not os.path.exists(cookie_path):
+            raise FileNotFoundError(f"Cookie 文件不存在: {cookie_path}")
+
+        with open(cookie_path, 'r', encoding='utf-8') as f:
+            file_content = f.read().strip()
+
+        # 尝试解析为 JSON
+        try:
+            cookies_from_file = json.loads(file_content)
+            # JSON 解析成功，使用自动转换函数
+            return auto_convert_to_playwright(
+                cookies_from_file,
+                default_domain=".google.com",
+                logger=self.logger
+            )
+        except json.JSONDecodeError:
+            # JSON 解析失败，当作 KV 格式处理
+            if self.logger:
+                self.logger.info(f"文件 {filename} 不是有效的 JSON 格式，尝试作为 KV 格式解析")
+            return auto_convert_to_playwright(
+                file_content,
+                default_domain=".google.com",
+                logger=self.logger
+            )
+
+    def _load_from_env(self, env_var_name: str) -> List[Dict]:
+        """从环境变量加载 Cookie，自动识别 JSON 或 KV 格式"""
+        env_value = clean_env_value(os.getenv(env_var_name))
+
+        if not env_value:
+            raise ValueError(f"环境变量 {env_var_name} 不存在或为空")
+
+        # 尝试解析为 JSON
+        try:
+            cookies_from_env = json.loads(env_value)
+            # JSON 解析成功，使用自动转换函数
+            return auto_convert_to_playwright(
+                cookies_from_env,
+                default_domain=".google.com",
+                logger=self.logger
+            )
+        except json.JSONDecodeError:
+            # JSON 解析失败，当作 KV 格式处理
+            if self.logger:
+                self.logger.debug(f"环境变量 {env_var_name} 不是有效的 JSON 格式，作为 KV 格式解析")
+            return auto_convert_to_playwright(
+                env_value,
+                default_domain=".google.com",
+                logger=self.logger
+            )

utils/logger.py

@@ -0,0 +1,75 @@
+import logging
+import datetime
+import os
+
+def custom_timezone_converter(timestamp):
+    """
+    将时间戳转换为指定时区 (默认 UTC+8/Asia/Shanghai) 的 struct_time。
+    时区通过环境变量 TZ_OFFSET (小时数) 配置。
+    """
+    
+    # 尝试从环境变量获取偏移量，默认为 8 (北京时间)
+    try:
+        offset_hours = float(os.getenv('TZ_OFFSET', 8))
+    except (ValueError, TypeError):
+        offset_hours = 8
+
+    # 创建时区对象
+    target_timezone = datetime.timezone(datetime.timedelta(hours=offset_hours))
+    
+    # 转换时间
+    dt_time = datetime.datetime.fromtimestamp(timestamp, target_timezone)
+    return dt_time.timetuple()
+
+def setup_logging(log_file, prefix=None, level=logging.INFO):
+    """
+    配置日志记录器，使其输出到文件和控制台。
+    支持一个可选的前缀，用于标识日志来源。
+
+    每个 (进程ID, prefix) 组合对应一个独立的 logger，首次调用时初始化，
+    后续调用直接返回已有 logger，避免重复创建 handler 导致内存泄漏。
+    
+    时间显示默认为 UTC+8 (北京时间)，可通过环境变量 TZ_OFFSET 修改。
+
+    :param log_file: 日志文件的路径（仅首次调用生效）。
+    :param prefix: (可选) 要添加到每条日志消息开头的字符串前缀。
+    :param level: 日志级别（仅首次调用生效）。
+    """
+    # 使用进程ID + 前缀作为 logger 名称，避免不同进程/实例的 logger 互相干扰
+    logger_name = f'camoufox.{os.getpid()}'
+    if prefix:
+        logger_name += f'.{prefix}'
+    
+    logger = logging.getLogger(logger_name) 
+    logger.setLevel(level)
+
+    # 如果该 logger 已有 handlers，说明已初始化过，直接返回
+    if logger.hasHandlers():
+        return logger
+
+    base_format = '%(asctime)s - %(process)d - %(levelname)s - %(message)s'
+
+    if prefix:
+        log_format = f'%(asctime)s - %(process)d - %(levelname)s - {prefix} - %(message)s'
+    else:
+        log_format = base_format
+
+    fh = logging.FileHandler(log_file)
+    fh.setLevel(level)
+
+    ch = logging.StreamHandler()
+    ch.setLevel(level)
+
+    formatter = logging.Formatter(log_format)
+    # 设置自定义的时间转换器
+    formatter.converter = custom_timezone_converter
+
+    fh.setFormatter(formatter)
+    ch.setFormatter(formatter)
+
+    logger.addHandler(fh)
+    logger.addHandler(ch)
+    
+    logger.propagate = False
+    
+    return logger

utils/paths.py

@@ -0,0 +1,31 @@
+import os
+from functools import lru_cache
+from pathlib import Path
+
+
+@lru_cache(maxsize=1)
+def project_root() -> Path:
+    """
+    返回代码仓库根目录，使调用者能够构建不依赖当前工作目录的绝对路径。
+    """
+    env_root = os.getenv("CAMOUFOX_PROJECT_ROOT")
+    if env_root:
+        return Path(env_root).expanduser().resolve()
+
+    current = Path(__file__).resolve()
+    for parent in current.parents:
+        if (parent / "cookies").exists():
+            return parent
+
+    # 如果标记目录缺失，则回退到原始行为
+    return current.parents[min(2, len(current.parents) - 1)]
+
+
+def logs_dir() -> Path:
+    """存储日志文件和截图的根级目录。"""
+    return project_root() / "logs"
+
+
+def cookies_dir() -> Path:
+    """存储持久化Cookie JSON文件的根级目录。"""
+    return project_root() / "cookies"

utils/url_helper.py

@@ -0,0 +1,152 @@
+"""
+URL处理辅助函数
+
+提供URL解析和路径提取功能，用于导航验证中的域名无关匹配。
+"""
+
+from urllib.parse import urlparse
+
+
+def extract_url_path(url: str) -> str:
+    """
+    提取URL的路径和查询参数部分，忽略协议和域名差异
+
+    用于验证导航是否到达正确页面，允许域名重定向。
+
+    Args:
+        url: 完整URL字符串
+
+    Returns:
+        路径+查询参数+片段（例如："/apps/drive/123?param=value#section"）
+        如果URL为空或无效，返回空字符串
+
+    Examples:
+        >>> extract_url_path("https://ai.studio/apps/drive/123?param=value")
+        '/apps/drive/123?param=value'
+
+        >>> extract_url_path("https://aistudio.google.com/apps/drive/123")
+        '/apps/drive/123'
+
+        >>> extract_url_path("https://example.com/path")
+        '/path'
+    """
+    if not url:
+        return ""
+
+    try:
+        parsed = urlparse(url)
+        result = parsed.path
+        if parsed.query:
+            result += '?' + parsed.query
+        if parsed.fragment:
+            result += '#' + parsed.fragment
+        return result
+    except Exception:
+        # 如果URL格式无效，返回空字符串
+        return ""
+
+
+def mask_path_for_logging(path: str) -> str:
+    """
+    对路径进行脱敏处理，用于日志输出
+
+    脱敏规则：
+    1. 对于 /apps/drive/XXXXXXXXXX 路径，保留头4位和尾4位，中间用***代替
+    2. 如果不是 /apps/drive/XXXXXXXXXX 路径，返回完整路径
+
+    Args:
+        path: URL路径字符串
+
+    Returns:
+        脱敏后的路径字符串
+
+    Examples:
+        >>> mask_path_for_logging("/apps/drive/abcdef123456")
+        '/apps/drive/abcd***3456'
+
+        >>> mask_path_for_logging("/apps/drive/xyz789")
+        '/apps/drive/xyz789'
+
+        >>> mask_path_for_logging("/other/path")
+        '/other/path'
+    """
+    if not path:
+        return ""
+
+    # 检查是否为 /apps/drive/ 路径
+    if path.startswith('/apps/drive/'):
+        # 提取路径中的ID部分
+        path_parts = path.split('/')
+        if len(path_parts) >= 4:  # ['', 'apps', 'drive', 'ID']
+            drive_id = path_parts[3]
+
+            # 如果ID长度大于8，则进行脱敏处理
+            if len(drive_id) > 8:
+                # 使用与URL脱敏相同的格式
+                masked_id = f"{drive_id[:4]}***{drive_id[-4:]}"
+                # 重新构建路径
+                masked_parts = path_parts[:3] + [masked_id] + path_parts[4:]
+                return '/'.join(masked_parts)
+
+    # 如果不符合脱敏条件，返回原始路径
+    return path
+
+
+def mask_url_for_logging(url: str) -> str:
+    """
+    对URL进行脱敏处理，用于日志输出
+
+    脱敏规则：
+    1. 对于 /apps/drive/XXXXXXXXXX 路径，保留头4位和尾4位，中间用***代替
+    2. 如果不是 /apps/drive/XXXXXXXXXX 路径，返回完整URL
+
+    Args:
+        url: 完整URL字符串
+
+    Returns:
+        脱敏后的URL字符串
+
+    Examples:
+        >>> mask_url_for_logging("https://ai.studio/apps/drive/abcdef123456")
+        'https://ai.studio/apps/drive/abcd***3456'
+
+        >>> mask_url_for_logging("https://aistudio.google.com/apps/drive/xyz789")
+        'https://aistudio.google.com/apps/drive/xyz789'
+
+        >>> mask_url_for_logging("https://example.com/other/path")
+        'https://example.com/other/path'
+    """
+    if not url:
+        return ""
+
+    try:
+        parsed = urlparse(url)
+
+        # 检查是否为 /apps/drive/ 路径
+        if parsed.path.startswith('/apps/drive/'):
+            # 提取路径中的ID部分
+            path_parts = parsed.path.split('/')
+            if len(path_parts) >= 4:  # ['', 'apps', 'drive', 'ID']
+                drive_id = path_parts[3]
+
+                # 如果ID长度大于8，则进行脱敏处理
+                if len(drive_id) > 8:
+                    masked_id = f"{drive_id[:4]}***{drive_id[-4:]}"
+                    # 重新构建路径
+                    masked_parts = path_parts[:3] + [masked_id] + path_parts[4:]
+                    masked_path = '/'.join(masked_parts)
+
+                    # 重新构建URL
+                    result = f"{parsed.scheme}://{parsed.netloc}{masked_path}"
+                    if parsed.query:
+                        result += '?' + parsed.query
+                    if parsed.fragment:
+                        result += '#' + parsed.fragment
+                    return result
+
+        # 如果不符合脱敏条件，返回原始URL
+        return url
+
+    except Exception:
+        # 如果URL解析失败，返回原始URL
+        return url