Ferrum项目与Browserless v2的集成实践

背景介绍

Ferrum是一个基于Ruby的轻量级浏览器自动化工具，它通过Chrome DevTools Protocol(CDP)与浏览器进行交互。在实际应用中，开发者常常需要将Ferrum与Browserless这样的无头浏览器服务进行集成，以实现远程浏览器控制能力。

Browserless版本升级带来的挑战

Browserless从v1升级到v2版本后，许多开发者遇到了集成问题。主要症状表现为连接被拒绝的错误信息："Connection refused - connect(2) for "0.0.0.0" port 3000"。

问题根源分析

经过技术社区的研究，发现问题的核心在于Ferrum v0.15版本中的连接处理逻辑。当Ferrum尝试与Browserless v2建立连接时，会执行以下步骤：

1. 首先向指定的主机/端口发起HTTP请求，获取元数据
2. 从响应中解析webSocketDebuggerUrl字段
3. 使用该URL建立WebSocket连接

问题出在Browserless v2返回的webSocketDebuggerUrl中，主机地址被错误地设置为"0.0.0.0"，而不是最初请求时使用的主机名。这导致后续的WebSocket连接尝试失败。

解决方案

方法一：升级Ferrum版本

Ferrum的HEAD版本(即最新的开发版本)已经修复了这个问题。开发者可以通过以下方式解决：

1. 直接从Git仓库安装最新版本
2. 等待Ferrum发布v0.15之后的正式版本

方法二：显式指定WebSocket URL

对于暂时无法升级的用户，可以通过显式指定WebSocket URL的方式解决：

Capybara.register_driver(:cuprite) do |app|
  Capybara::Cuprite::Driver.new(
    app,
    **{
      ws_url: "ws://chrome:3333/chrome",  # 关键配置
      headless: ENV['HEADLESS'],
      process_timeout: 10,
      timeout: 30,
      window_size: [1920, 1080],
      browser_options: { 'no-sandbox': nil, 'disable-gpu': nil },
      save_path: DownloadHelper::PATH
    }
  )
end

注意URL中的"/chrome"路径部分，这是Browserless v2特定的端点路径。

配置建议

1. 容器配置：确保Browserless容器正确配置了端口和环境变量
2. 超时设置：Browserless v2默认30秒后会自动关闭会话，建议适当延长TIMEOUT值
3. HEADLESS模式：在生产环境中建议保持HEADLESS为true，除非有特殊调试需求

最佳实践

对于使用Docker Compose的部署场景，可以参考以下配置：

services:
  chrome:
    image: ghcr.io/browserless/chrome:latest
    ports:
      - 3333:3333
    environment:
      PORT: 3333
      TIMEOUT: 600000  # 10分钟超时
    shm_size: 512m

常见问题排查

1. DeadBrowserError：检查会话超时设置，确保TIMEOUT值足够大
2. 连接失败：确认ws_url中的主机名和端口与容器配置一致
3. 路径问题：Browserless v2可能需要特定端点路径(如/chrome)

通过以上方法，开发者可以顺利实现Ferrum与Browserless v2的集成，享受新版Browserless带来的性能改进和功能增强。