PanWatch 镜像拉不动？Playwright 浏览器自动安装问题彻底解决指南-平芜编程栈

PanWatch 镜像拉不动？Playwright 浏览器自动安装问题彻底解决指南

【免费下载链接】PanWatchPanWatch — AI stock monitoring for A-shares, HK & US markets, powered by TradingAgents. Portfolio insights, real-time alerts & automated reports.｜盯盘侠：覆盖 A股/港股/美股的 AI 盯盘、持仓分析、实时提醒与自动报告。项目地址: https://gitcode.com/GitHub_Trending/pa/PanWatch

PanWatch是一款覆盖 A股/港股/美股的 AI 盯盘工具：持仓分析、实时价格提醒、自动报告与 K线截图一应俱全。多数用户通过 Docker 镜像部署，但两类问题最常让新手卡住——镜像拉取失败和首次启动时 Playwright 浏览器安装不成功。本文给出完整排查路径，按图索骥即可快速解决。

PanWatch 是什么？为什么需要 Playwright？

PanWatch 的核心能力是把行情、K线、新闻与 AI 分析聚合在一块看板上。它的股票详情页会自动生成 K线图表截图（用于 AI 读图和分享卡片），这个功能由 screenshot_collector.py 中的截图采集器驱动，底层依赖 Playwright 无头浏览器抓取图表页面。

理解了这一点就明白：Playwright 装不好，不会导致服务起不来，但「K线截图」相关功能会缺失，日志里也会刷安装失败的报错。

问题一：镜像拉不动，先排查这 3 点

1. 网络与镜像源

docker pull卡住或报connection refused/i/o timeout，绝大多数情况是网络问题：

确认机器能正常访问外网，代理环境下记得给 Docker 配置 daemon 代理；
使用国内网络时，可为 Docker 配置可用的镜像加速地址；
拉取中断后重新执行docker pull即可断点续传，不必删库重来。

2. 镜像体积大，耐心等待

镜像采用多阶段构建（前端 Node 构建 + Python 运行环境），完整定义见 Dockerfile。首次拉取需要下载数 GB 数据，建议用docker pull sunxiao0721/panwatch:latest观察进度，或在带宽充足时再执行。

3. 磁盘空间不足

检查docker system df，确保剩余空间大于镜像大小 1.5 倍，避免解压阶段报错。

问题二：Playwright 浏览器自动安装失败

这是更隐蔽的一类问题。PanWatch 官方刻意不把 Chromium 打进镜像，而是让容器首次启动时自动下载浏览器到挂载卷：

/app/data/playwright （容器内默认路径）

安装逻辑在 server.py 的setup_playwright()中：启动时检查目录是否已有chromium文件夹，没有就执行playwright install chromium（10 分钟超时）。设计文档说明见 README 快速开始章节。

常见报错对照表

报错/现象	原因	解决办法
`Executable doesn't exist... chromium`	浏览器没装成功	手动进容器执行安装命令（见下文）
`Host system is missing dependencies`	缺少系统库	使用官方镜像（已内置全部依赖），见 Dockerfile
安装超时`Timed out`	容器无法访问浏览器下载源	为容器配置`HTTP_PROXY`/`HTTPS_PROXY`
每次重启都重装	没挂载`/app/data`卷	按官方命令挂载`panwatch_data`卷
日志刷`Playwright 命令不可用`	pip 依赖没装全	确认 requirements.txt 中`playwright==1.57.0`已安装

手动补装 Chromium（最快解法）

挂载卷正确的前提下，进容器手动执行一次即可，之后会持久化到卷里：

docker exec -it panwatch bash export PLAYWRIGHT_BROWSERS_PATH=/app/data/playwright playwright install chromium

看到chromium目录出现在/app/data/playwright下即成功，重启容器后setup_playwright()检测到已安装会直接跳过，日志提示「Playwright 浏览器已就绪」。

用挂载卷保证"装一次，永久生效"

浏览器装在镜像层的话，重建容器就会丢失，所以务必挂载数据卷：

docker run -d \ --name panwatch \ -p 8000:8000 \ -v panwatch_data:/app/data \ sunxiao0721/panwatch:latest

这样 Chromium 与数据库都落在panwatch_data卷中，升级镜像也不影响。

不需要截图功能？一行跳过

如果只关心盯盘提醒、持仓分析，不关心 K线截图，启动时加一个环境变量即可完全跳过浏览器下载，还能省掉首次启动的几分钟：

docker run -d --name panwatch -p 8000:8000 \ -v panwatch_data:/app/data \ -e PLAYWRIGHT_SKIP_BROWSER_INSTALL=1 \ sunxiao0721/panwatch:latest

关键环境变量速查

变量	作用
`PLAYWRIGHT_SKIP_BROWSER_INSTALL`	设为`1`跳过首次 Chromium 安装
`PLAYWRIGHT_BROWSERS_PATH`	显式指定浏览器安装路径（优先于默认规则）
`DATA_DIR`	数据目录，容器内默认`/app/data`
`HTTP_PROXY`/`HTTPS_PROXY`	容器出站代理，解决浏览器下载超时
`TZ`	时区，默认`Asia/Shanghai`

验证是否修复

访问http://localhost:8000，服务能正常打开即部署成功；
查看启动日志（docker logs panwatch），出现「Playwright 浏览器已就绪」或「跳过 Playwright 浏览器安装」都为正常状态；
打开任意股票详情页，K线图能正常渲染与截图，说明浏览器链路完全打通。

总结

镜像拉不动→ 先查网络与镜像加速，其次确认磁盘空间，大镜像耐心等；
Playwright 装不上→ 确认挂载了/app/data卷，容器内手动执行一次playwright install chromium，或用PLAYWRIGHT_SKIP_BROWSER_INSTALL=1跳过；
官方镜像已预装 Chromium 所需的全部系统依赖（见 Dockerfile），只要浏览器二进制文件落盘成功，K线截图、AI 读图等功能即可完整使用。

按这套流程操作后，PanWatch 的 Docker 部署基本不会再卡在浏览器安装这一步。祝你盯盘顺利！

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考