knyttan/puppeteer

无头 Chrome Docker 容器

镜像概述

本镜像提供了一个稳定、高效的无头 Google Chrome 浏览器运行环境。它专为依赖无头浏览器实例的后端服务而设计，通过暴露 Puppeteer 接口，使开发者能够轻松地在 Docker 容器中执行网页自动化、渲染和测试任务。

核心功能与特性

• 无头 Chrome 支持：内置配置好的 Google Chrome 浏览器，原生支持无头模式运行。
• Puppeteer 接口兼容：完美兼容 Puppeteer 及 Puppeteer-core 客户端，提供标准化的控制接口。
• 代理支持：内置代理配置方案，解决复杂网络环境下的请求与路由问题。
• 高可用与稳定性：经过严格的负载测试和长时间浸泡测试，确保在数据中心环境中长期稳定运行，避免内存泄漏或进程崩溃。

使用场景和适用范围

• 网页自动化与数据抓取：执行包含复杂 JavaScript 渲染的页面抓取与数据提取。
• 自动化测试：作为 CI/CD 流水线中的端到端 (E2E) 测试和 UI 自动化测试运行环境。
• 内容生成：自动化生成网页截图、导出 PDF 报告或进行页面快照。
• 微服务渲染：作为后端独立微服务，为其他业务系统提供统一的页面渲染与解析能力。

使用方法和配置说明

基础 Docker 运行示例

使用 docker run 快速启动无头 Chrome 容器：

bash
docker run -d \
  --name chrome-headless \
  -p 9222:9222 \
  --shm-size="2g" \
  your-registry/chrome-headless:latest

注：--shm-size="2g" 用于增加共享内存大小，防止 Chrome 在处理复杂页面时因内存不足而崩溃。

Docker Compose 部署示例

推荐使用 Docker Compose 进行服务编排与管理：

yaml
version: '3.8'
services:
  chrome-headless:
    image: your-registry/chrome-headless:latest
    container_name: chrome-headless
    ports:
      - "9222:9222"
    shm_size: '2gb'
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai

Apple M1/M2 芯片本地运行指南

由于架构限制，目前无法直接在基于 Apple Silicon (M1/M2) 芯片的设备上通过原生 Docker 运行该 Chrome 镜像。需使用 colima 作为替代方案：

1. 安装 colima：

bash
brew install colima

2. 以 x86_64 架构启动 colima 环境：

bash
colima start --arch x86_64

3. 环境启动后，正常执行 docker-compose 或 docker run 命令即可。

测试与验证

项目内置了多种测试脚本以验证容器的稳定性和性能。请在仓库根目录下使用 make 命令执行以下测试：

• 负载测试 (Load)：验证容器内置代理在高并发和负载均衡环境下的有效性。

  bash
  make load-noproxy  # 无代理负载测试
  make load-proxy    # 有代理负载测试
  

• 浸泡测试 (Soak)：验证容器长时间运行时的资源占用和稳定性，防止内存泄漏或过热。

  bash
  make soak-init     # 初始化监听器，记录 Chrome 进程数至 test/process-count
  make soak-run      # 发起持续无间断请求
  make soak-watch    # 实时监控容器内部状态
  

• 单元测试 (Unit)：使用 Puppeteer 客户端运行基础单元测试。

  bash
  make test
  

• 客户端测试 (Client)：运行针对客户端代码的集成测试。

  bash
  make test-client
  

调试与提示 (Tips)

• CI/CD 配置：在 Circle CI 等持续集成环境中使用的 SSH 密钥应统一托管于密码管理器（如 1Password）中，并确保所有相关项目使用同一密钥以简化配置。
• Puppeteer 调试：如需深入调试 Chrome 或 Puppeteer 行为，请参考 https://github.com/GoogleChrome/puppeteer#debugging-tips 获取更多排错技巧。