HolyClaude无头浏览器配置原理Chromium Xvfb Playwright在Docker中不崩的完整方案【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaudeHolyClaude 是一款开箱即用的 AI 编程工作站 Docker 镜像内置 Claude Code、Web UI、8 个 AI CLI 和无头浏览器。其中最容易踩坑的就是无头浏览器配置——Chromium 在容器里崩溃、共享内存不足、沙箱权限报错是每个自托管开发者的老朋友。本文拆解 HolyClaude 的无头浏览器配置原理Chromium Xvfb Playwright 如何在 Docker 中稳定运行而不崩。为什么无头浏览器在 Docker 里总是崩手动搭建一套「AI 编程 浏览器自动化」环境通常要按顺序解决这些问题崩溃原因典型报错/dev/shm 只有 64MBout of memory/ 页面加载中断容器用户与宿主不匹配permission deniedChromium 沙箱与 seccomp 冲突Sandbox linux must be of rootX 显示未配置Missing X server or $DISPLAYHolyClaude 的思路是把每一步都固化进镜像用进程守护保证崩溃后自动拉起。下面逐层拆解。第一层Xvfb 虚拟显示器——让容器拥有屏幕Chromium 的某些模式需要一个 X 显示端。HolyClaude 通过 s6-overlay 将 Xvfb 注册为常驻服务容器内只有一个命令行一行启动Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp:99虚拟显示器编号对应镜像内写死的环境变量DISPLAY:99任何进程都能直接连上1920x1080x24标准 1080P、24 位色深截图和渲染尺寸符合直觉-nolisten tcp禁用远程 X 连接这是安全细节防止容器被当作跳板该服务的定义见 s6-overlay/s6-rc.d/xvfb/run。由于它由 s6-overlay 监督Xvfb 崩溃会自动重启不需要人工干预——这正是不崩的第一道保障。第二层Docker 运行时参数——内存、权限、seccomp 三件套浏览器在容器里崩八成不是镜像的问题而是运行时参数没给够。HolyClaude 的 docker-compose.yaml 里给出了完整参考配置shm_size: 2g # 共享内存从默认 64MB 提到 2GB cap_add: - SYS_ADMIN # 浏览器沙箱所需能力 - SYS_PTRACE # 调试能力 security_opt: - seccompunconfined # 解除 seccomp 对浏览器的拦截三项参数对应三类经典崩溃shm_size: 2g—— Chromium 渲染进程间通过/dev/shm传递大帧缓冲默认 64MB 极易撑爆这是容器里浏览器无预警崩溃的头号元凶SYS_ADMINseccompunconfined—— Chromium 沙箱依赖clone/unshare等系统调用Docker 默认 seccomp 策略会拦截它们两者配合后沙箱可正常初始化镜像内部还通过环境变量CHROMIUM_FLAGS--no-sandbox --disable-gpu --disable-dev-shm-usage提供了双保险即使 shm 再次吃紧--disable-dev-shm-usage会让 Chromium 退回/tmp临时目录这些参数在 Dockerfile 的环境变量段与两个 compose 模板docker-compose.yaml、docker-compose.full.yaml中保持一致。第三层Chromium 版本锁定——每次拉到的浏览器都是同一个无头浏览器配置的另一大坑是版本漂移今天能跑的 Playwright 脚本明天系统升级 Chromium 后就崩。HolyClaude 的解法极其硬核使用 Debian Bookworm 安全仓库的Chromium 153.0.8010.47三个 deb 包chromium / chromium-common / chromium-sandbox逐一校验 SHA256 后再安装安装后立即执行--version断言版本不符则构建直接失败运行时零下载不依赖 Playwright/Puppeteer 的浏览器自动下载机制Node 与 Python 两侧的 Playwright1.63.0全部指向同一个系统 Chromium统一入口是一个轻量包装脚本 scripts/holyclaude-chromium它展开CHROMIUM_FLAGS后执行真正的浏览器二进制再软链为/usr/bin/chromium。环境变量CHROME_PATH与PUPPETEER_EXECUTABLE_PATH都指向它意味着Puppeteer、Playwright、Lighthouse、CloudCLI 的浏览器插件用的是同一个浏览器行为完全一致。第四层s6-overlay 进程守护——崩了也不怕前几层解决为什么不崩这一层解决崩了怎么办。HolyClaude 用 s6-overlay 替代裸docker run的 PID 1 模型详见 docs/architecture.mdXvfb、CloudCLIWeb UI均为longrun服务崩溃后自动按策略重启僵尸进程被正确回收优雅停机docker stop时信号被 s6 转发给所有子服务浏览器会话不会留下孤儿进程入口脚本只跑一次UID/GID 重映射、Claude 会话恢复等初始化逻辑在 scripts/entrypoint.sh 完成后才exec /init移交给 s6这套设计下即使 Chromium 某个渲染进程 OOM受影响的只是该进程本身虚拟显示器和 Web 服务始终存活整个工作站不会死掉。一键安装步骤30 秒跑起来理解原理后实际使用只需要三步完整参数见 docs/configuration.md创建目录并放入 docker-compose.yaml 中的 Quick Start 模板执行docker compose up -d打开http://localhost:3001创建 CloudCLI 账号、用 Anthropic 账号登录之后在 Web UI 里发起任何需要浏览器的任务——截图、测试、页面巡检——后台的 Xvfb Chromium Playwright 组合已经在DISPLAY:99上待命全程无需手工配置。如何验证无头浏览器工作正常项目自带测试可以帮你确认这套配置健康tests/browser_runtime_smoke.sh冒烟测试验证 Chromium 真能启动并完成一次真实浏览器动作tests/browser_packaging_invariants.test.mjs校验包装脚本、环境变量指向与版本锁定的完整性tests/browser_snapshot_retry.sh快照重试路径验证若你自行部署后遇到白屏或崩溃优先检查三件事shm_size是否 ≥ 2g、seccomp是否 unconfined、容器内echo $DISPLAY是否为:99。总结不崩的完整方案由四道防线组成防线机制解决的问题虚拟显示器Xvfb :99 s6 守护Missing X server显示器进程崩溃运行时参数shm_size 2g / SYS_ADMIN / seccomp内存溢出、沙箱与系统调用拦截版本锁定SHA256 校验的 Bookworm Chromium 统一 wrapper版本漂移、多套浏览器行为不一致进程监督s6-overlay longrun 自动重启单点崩溃拖垮整个工作站这就是 HolyClaude 无头浏览器配置的全貌不是某一个参数救活了 Chromium而是镜像内的版本锁定、compose 层的资源授权、s6 层的进程守护三层协同才让 Chromium Xvfb Playwright 在 Docker 里真正做到不崩。【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HolyClaude无头浏览器配置原理：Chromium + Xvfb + Playwright在Docker中不崩的完整方案
HolyClaude无头浏览器配置原理Chromium Xvfb Playwright在Docker中不崩的完整方案【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaudeHolyClaude 是一款开箱即用的 AI 编程工作站 Docker 镜像内置 Claude Code、Web UI、8 个 AI CLI 和无头浏览器。其中最容易踩坑的就是无头浏览器配置——Chromium 在容器里崩溃、共享内存不足、沙箱权限报错是每个自托管开发者的老朋友。本文拆解 HolyClaude 的无头浏览器配置原理Chromium Xvfb Playwright 如何在 Docker 中稳定运行而不崩。为什么无头浏览器在 Docker 里总是崩手动搭建一套「AI 编程 浏览器自动化」环境通常要按顺序解决这些问题崩溃原因典型报错/dev/shm 只有 64MBout of memory/ 页面加载中断容器用户与宿主不匹配permission deniedChromium 沙箱与 seccomp 冲突Sandbox linux must be of rootX 显示未配置Missing X server or $DISPLAYHolyClaude 的思路是把每一步都固化进镜像用进程守护保证崩溃后自动拉起。下面逐层拆解。第一层Xvfb 虚拟显示器——让容器拥有屏幕Chromium 的某些模式需要一个 X 显示端。HolyClaude 通过 s6-overlay 将 Xvfb 注册为常驻服务容器内只有一个命令行一行启动Xvfb :99 -screen 0 1920x1080x24 -nolisten tcp:99虚拟显示器编号对应镜像内写死的环境变量DISPLAY:99任何进程都能直接连上1920x1080x24标准 1080P、24 位色深截图和渲染尺寸符合直觉-nolisten tcp禁用远程 X 连接这是安全细节防止容器被当作跳板该服务的定义见 s6-overlay/s6-rc.d/xvfb/run。由于它由 s6-overlay 监督Xvfb 崩溃会自动重启不需要人工干预——这正是不崩的第一道保障。第二层Docker 运行时参数——内存、权限、seccomp 三件套浏览器在容器里崩八成不是镜像的问题而是运行时参数没给够。HolyClaude 的 docker-compose.yaml 里给出了完整参考配置shm_size: 2g # 共享内存从默认 64MB 提到 2GB cap_add: - SYS_ADMIN # 浏览器沙箱所需能力 - SYS_PTRACE # 调试能力 security_opt: - seccompunconfined # 解除 seccomp 对浏览器的拦截三项参数对应三类经典崩溃shm_size: 2g—— Chromium 渲染进程间通过/dev/shm传递大帧缓冲默认 64MB 极易撑爆这是容器里浏览器无预警崩溃的头号元凶SYS_ADMINseccompunconfined—— Chromium 沙箱依赖clone/unshare等系统调用Docker 默认 seccomp 策略会拦截它们两者配合后沙箱可正常初始化镜像内部还通过环境变量CHROMIUM_FLAGS--no-sandbox --disable-gpu --disable-dev-shm-usage提供了双保险即使 shm 再次吃紧--disable-dev-shm-usage会让 Chromium 退回/tmp临时目录这些参数在 Dockerfile 的环境变量段与两个 compose 模板docker-compose.yaml、docker-compose.full.yaml中保持一致。第三层Chromium 版本锁定——每次拉到的浏览器都是同一个无头浏览器配置的另一大坑是版本漂移今天能跑的 Playwright 脚本明天系统升级 Chromium 后就崩。HolyClaude 的解法极其硬核使用 Debian Bookworm 安全仓库的Chromium 153.0.8010.47三个 deb 包chromium / chromium-common / chromium-sandbox逐一校验 SHA256 后再安装安装后立即执行--version断言版本不符则构建直接失败运行时零下载不依赖 Playwright/Puppeteer 的浏览器自动下载机制Node 与 Python 两侧的 Playwright1.63.0全部指向同一个系统 Chromium统一入口是一个轻量包装脚本 scripts/holyclaude-chromium它展开CHROMIUM_FLAGS后执行真正的浏览器二进制再软链为/usr/bin/chromium。环境变量CHROME_PATH与PUPPETEER_EXECUTABLE_PATH都指向它意味着Puppeteer、Playwright、Lighthouse、CloudCLI 的浏览器插件用的是同一个浏览器行为完全一致。第四层s6-overlay 进程守护——崩了也不怕前几层解决为什么不崩这一层解决崩了怎么办。HolyClaude 用 s6-overlay 替代裸docker run的 PID 1 模型详见 docs/architecture.mdXvfb、CloudCLIWeb UI均为longrun服务崩溃后自动按策略重启僵尸进程被正确回收优雅停机docker stop时信号被 s6 转发给所有子服务浏览器会话不会留下孤儿进程入口脚本只跑一次UID/GID 重映射、Claude 会话恢复等初始化逻辑在 scripts/entrypoint.sh 完成后才exec /init移交给 s6这套设计下即使 Chromium 某个渲染进程 OOM受影响的只是该进程本身虚拟显示器和 Web 服务始终存活整个工作站不会死掉。一键安装步骤30 秒跑起来理解原理后实际使用只需要三步完整参数见 docs/configuration.md创建目录并放入 docker-compose.yaml 中的 Quick Start 模板执行docker compose up -d打开http://localhost:3001创建 CloudCLI 账号、用 Anthropic 账号登录之后在 Web UI 里发起任何需要浏览器的任务——截图、测试、页面巡检——后台的 Xvfb Chromium Playwright 组合已经在DISPLAY:99上待命全程无需手工配置。如何验证无头浏览器工作正常项目自带测试可以帮你确认这套配置健康tests/browser_runtime_smoke.sh冒烟测试验证 Chromium 真能启动并完成一次真实浏览器动作tests/browser_packaging_invariants.test.mjs校验包装脚本、环境变量指向与版本锁定的完整性tests/browser_snapshot_retry.sh快照重试路径验证若你自行部署后遇到白屏或崩溃优先检查三件事shm_size是否 ≥ 2g、seccomp是否 unconfined、容器内echo $DISPLAY是否为:99。总结不崩的完整方案由四道防线组成防线机制解决的问题虚拟显示器Xvfb :99 s6 守护Missing X server显示器进程崩溃运行时参数shm_size 2g / SYS_ADMIN / seccomp内存溢出、沙箱与系统调用拦截版本锁定SHA256 校验的 Bookworm Chromium 统一 wrapper版本漂移、多套浏览器行为不一致进程监督s6-overlay longrun 自动重启单点崩溃拖垮整个工作站这就是 HolyClaude 无头浏览器配置的全貌不是某一个参数救活了 Chromium而是镜像内的版本锁定、compose 层的资源授权、s6 层的进程守护三层协同才让 Chromium Xvfb Playwright 在 Docker 里真正做到不崩。【免费下载链接】HolyClaudeAI coding workstation: Claude Code web UI 8 AI CLIs headless browser 50 tools项目地址: https://gitcode.com/gh_mirrors/ho/HolyClaude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考