阅读顺序：先选路径 → 再跑起来 → 最后做首次配置
PanWatch 怎么部署：三条官方路径、首次启动会做什么、装完先配哪几项
PanWatch 官方 README 给出 Docker 单容器、Docker Compose、本地开发三条路径，并把首次配置收敛成四步。本页把三条路径的选择依据、逐条命令、以及每条命令会看到的结果放在一起，并补上官方文档没有强调的一点：镜像首次启动会在数据卷里下载 Chromium，这一步失败会让你以为「服务没起来」。
PanWatch 的三条官方路径怎么选？先看这张对照表
官方 README 把三条路径并列，但没有给选择依据。下表按「你要解决的问题」来分。
| 路径 | 你要解决的问题 | 关键命令或文件 | 注意点 |
|---|---|---|---|
| Docker 单容器 | 最快看到界面，不碰 Python 与 Node | docker run -d --name panwatch --restart unless-stopped -p 8000:8000 -v panwatch_data:/app/data sunxiao0721/panwatch:latest | 首次启动会下载 Chromium 到卷里，需要网络与数分钟 |
| Docker Compose | 要把端口、卷、重启策略固定成文件，方便升级与迁移 | 官方给出的 docker-compose.yml 包含 image、container_name、ports、volumes、restart 与具名卷 panwatch_data；启动 docker compose up -d | 与单容器等价；升级用 docker compose up --build -d |
| 本地开发 | 要改代码、加数据源、写自己的 Agent | make dev-api（自动建 venv 装依赖，监听 :8000）与 make dev-web（自动 pnpm install，监听 :5183） | 需要 Python 3.10+ / Node.js 24.14.0 / pnpm 9.15.9；前端把 /api 代理到 127.0.0.1:8000 |
| Windows 用户 | 不想装 Python 与 Node，只想跑服务 | 走 Docker 单容器或 Compose 路径；Docker Desktop 即可 | 官方为 Windows 提供了 PowerShell 安装脚本，但主流程仍是容器；构建脚本 scripts/build.ps1 面向自行构建镜像的场景 |
| 需要截图类能力 | 详情页要自动出 K 线截图 | 保持 PLAYWRIGHT_SKIP_BROWSER_INSTALL 不设置，让首次启动完成 Chromium 安装 | 不需要截图时可设为 1 跳过下载，能显著缩短首次启动时间 |
| 对外访问 | 想让手机或外部访问 | uvicorn 默认监听 0.0.0.0:8000；官方仓库未附带反向代理或 HTTPS 配置 | 自己接 Nginx/Caddy 时必须自行加认证与 HTTPS，仓库里没有现成配置可抄 |
:5183 而不是 Vite 默认的 :5173，官方注释写明是为了与 BeeCount-Cloud 等本地常驻前端错开——如果你本地也常驻别的前端项目，这个改动会帮你省一次端口冲突排查。PanWatch 首次启动会发生什么？按顺序看这五步
PanWatch 把「容器起来了」和「能用了」分开看，每步都有可观察的结果；看不懂哪一步就查下一节的排查表。
首次跑通五步与每步的预期结果
docker run 或 docker compose up -d。可观察结果：docker ps 里 panwatch 状态为 Up。/app/data/playwright）。可观察结果：日志出现下载过程，耗时可达数分钟且需要外网可达。AUTH_USERNAME/AUTH_PASSWORD 预设）。可观察结果：能进入主界面，界面语言跟随浏览器语言。.env.example 示例是智谱 https://open.bigmodel.cn/api/paas/v4 + glm-4。可观察结果：设置页出现可用的模型列表。| 步骤 | 判断是否成功的依据 | 如果失败，先看哪里 |
|---|---|---|
| 容器启动 | docker ps 显示 Up；/ 返回登录页 | 端口被占用、数据卷权限；见本页排查表 |
| Chromium 安装 | 卷内出现 playwright 目录 | 网络不可达（国内常见）；可先用 PLAYWRIGHT_SKIP_BROWSER_INSTALL=1 跳过 |
| 账号设置 | 能进入主界面 | 若设了 AUTH_USERNAME/AUTH_PASSWORD 却忘记，需按官方说明重置 |
| 模型接入 | 设置页能列出模型并能对话 | Base URL 是否带 /v4 之类的路径、Key 是否有余额、是否需要代理 |
| 添加标的与启用 Agent | 自选页有标的；Agent 页对应开关为开 | Agent 默认不全开，需手动启用盘前与盘中 |
PanWatch 环境变量速查：哪些必须设、哪些先别动
官方 README 与 .env.example 共列出十余个变量。下表按「什么时候需要」分类，并标出默认值来源。
| 变量 | 作用 | 默认值 | 什么时候才需要设 |
|---|---|---|---|
TZ | 应用时区，影响 Agent 调度触发时间与时间展示 | Asia/Shanghai | 当你不在东八区，或想让调度按其他时区对齐时 |
AUTH_USERNAME / AUTH_PASSWORD | 预设登录用户名与密码 | 首次访问时设置 | 想跳过首次设置（例如脚本化部署）时 |
JWT_SECRET | JWT 签名密钥 | 自动生成 | 多副本或要固定会话时；自行设置需妥善保管 |
DATA_DIR | 数据存储目录 | ./data | 本地开发想换目录时；容器内对应 /app/data |
PLAYWRIGHT_SKIP_BROWSER_INSTALL | 跳过首次 Chromium 下载 | 未设置 | 不需要截图能力时设 1，可显著缩短首次启动 |
LOG_LEVEL | 控制台日志级别 | INFO | 排查问题时设 DEBUG（能看调度心跳与采集过程）；界面日志板始终保留完整记录 |
HTTP_PROXY / HTTPS_PROXY / http_proxy | 出站代理 | 未设置 | 国内访问 Telegram 或部分行情源时需要；优先级为外部环境变量 > 界面设置 > .env |
NO_PROXY | 代理例外名单 | 含 localhost,127.0.0.1 | 通常无需改 |
OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry 导出端点 | 未设置（完全关闭，零副作用） | 要把 trace 送到 Jaeger/Tempo/Langfuse 时；还需装 requirements-otel.txt |
DAILY_REPORT_CRON | .env.example 里的日报 cron 示例 | 30 15 * * 1-5 | 示例文件里的写法；实际调度以界面中的 Agent 配置为准 |
CA_CERT_FILE | 企业代理的根证书（Zscaler 等环境） | 留空不启用 | 公司网络做了 TLS 拦截时 |
TZ 与静默时段的时区不是同一个配置项：通知静默时段策略的默认时区是 UTC，两者对不上会出现「明明设了夜间静默却还在响」。② NO_PROXY 默认只放 localhost，如果代理把所有流量都接走，本地服务之间的调用可能被绕一圈。③ OTEL_* 留空时导出层全程 no-op，不装可选依赖也不会影响任何现有行为。PanWatch 首次配置四步：每一步要准备什么
官方把首次配置写成四步。下表把每一步的前置条件、可选项与验证方式补齐。
| 步骤 | 你要准备的东西 | 可选项与差异 | 怎么验证配好了 |
|---|---|---|---|
| ① 设置账号密码 | 一个可丢弃的强密码 | 也可用 AUTH_USERNAME/AUTH_PASSWORD 预设 | 退出后能重新登录 |
| ② 配置 AI 服务商 | OpenAI 兼容接口的 Base URL 与 API Key | OpenAI / 智谱 / DeepSeek / 本地 Ollama 都走同一入口；.env.example 示例为智谱 + glm-4 | 设置页能拉到模型列表，并能完成一次对话 |
| ③ 添加通知渠道 | Telegram Bot Token 与 Chat ID，或企微/钉钉/飞书/Bark/Webhook | 国内平台通常无需代理；Telegram 常需出站代理 | 渠道列表里该渠道为「已启用」，且能收到测试消息 |
| ④ 添加股票并启用 Agent | 标的代码（A 股用 6 位数字，港股 5 位，美股字母） | 三个 workflow Agent 默认只有收盘复盘是开启的 | Agent 页开关为开；到点后 agent_runs 里有成功记录 |
| 模型接入方式 | 适合什么情况 | 要准备什么 | 注意点 |
|---|---|---|---|
| 云端 OpenAI 兼容服务 | 想让分析质量与速度稳定 | Base URL、API Key、模型名 | 按量计费；官方把深度分析月度预算默认设为 10 美元并在超预算时拒绝执行 |
| 国内模型服务（如智谱） | 网络在国内、希望直连 | 对应平台的 Key 与模型名 | 官方示例就是这套组合；模型能力差异会影响分析文字质量 |
| 本地 Ollama | 想避免按量计费、数据不出本机 | 本机已装 Ollama 并拉好模型 | 更吃显存；上下文压缩与超时参数需要相应调整 |
| 两个模型分档 | 让贵模型只做决策、便宜模型做采集 | 在深度分析配置里分别填 deep_model 与 quick_model | 留空表示与默认一致；这是官方配置项，不是自定义技巧 |
PanWatch 的端口、数据卷与访问路径要注意什么？升级前必须知道的四件事
自托管项目最容易在「数据到底在哪」这件事上吃亏。下表把可操作的结论直接给出。
| 问题 | 结论 | 来源 |
|---|---|---|
| 数据存在哪 | 容器内 /app/data，由具名卷 panwatch_data 挂载；本地开发默认 ./data | README 快速开始 + DATA_DIR 默认值 |
| 备份什么 | 备份数据卷（而非容器）；data/ 与代码分离，容器重建不丢数据 | README 升级说明 |
| 服务监听在哪 | uvicorn 绑定 0.0.0.0:8000；同一局域网内其他设备可用主机 IP 访问 | server.py 启动段 |
| 对外暴露要注意什么 | 仓库内没有 Nginx/Caddy 配置，也没有 HTTPS 方案；对外必须先自己加反向代理与认证 | 仓库文件树中无相关配置文件 |
PanWatch 首次跑不通怎么办？六类卡点按现象查
下表只收录能从官方配置与源码直接推出成因的场景；每条都给出可执行的验证动作。
| 现象 | 最可能的成因 | 验证动作 |
|---|---|---|
| 容器起来了但页面打不开 | 端口被占用，或映射写成了容器内端口而非 8000 | 换宿主端口（如 -p 18000:8000）后重试；确认 docker ps 的 PORTS 列 |
| 首次启动很久没反应 | 正在下载 Chromium 到数据卷（需要外网与数分钟） | 看容器日志是否有下载进度；不需要截图时设 PLAYWRIGHT_SKIP_BROWSER_INSTALL=1 重启 |
| 能登录但 AI 功能全部失败 | 模型 Base URL 或 Key 不对，或网络需要代理 | 在设置页做一次对话测试；确认 Base URL 路径与 HTTP_PROXY 是否生效 |
| 界面能开、自选页空白 | 还没有启用任何 Agent，也没有添加标的；收盘复盘是默认开启的那一个 Agent | 先在持仓页添加一只标的，再到 Agent 页启用盘前/盘中 |
| 通知渠道测试失败 | Telegram 需要代理；或 Chat ID 与 Bot Token 不匹配 | 配置 HTTP_PROXY 后重试；或先用国内渠道（企微/钉钉/飞书）验证链路 |
| 重启后配置丢了 | 数据卷没挂上（漏写 -v 或卷名不一致） | docker inspect panwatch 检查 Mounts；确认卷名与启动命令一致 |
装 PanWatch 需要什么前置？
Docker 路径只需要一台能跑 Docker 的机器与可用的外网（首次要下载 Chromium）。本地开发路径需要 Python 3.10+、Node.js 24.14.0、pnpm 9.15.9——注意 Docker 运行时用的是 Python 3.11，两者不是同一个基线。以上均来自官方 README 与 CONTRIBUTING 原文。
Windows 能装吗？
能。最省事的路径是 Docker Desktop + 官方镜像，官方也给 Windows 用户提供了 PowerShell 安装脚本。本地开发路径在 Windows 上同样可行，但要把「前端监听 5183」这类约定一起照做。官方文档没有针对 Windows 的专门章节，遇到差异时以通用路径的说明为准。
首次启动为什么要等好几分钟？
因为镜像内的 Playwright 需要在首次启动时把 Chromium 下载到挂载卷（默认 /app/data/playwright）。官方 README 明确写了这一步需要网络且可能耗时数分钟。如果你不需要截图类能力，用 PLAYWRIGHT_SKIP_BROWSER_INSTALL=1 可以跳过整个下载。
不接模型能不能用？
能启动，但 AI 相关能力没有意义：公告、行情的采集与展示不依赖模型，而盘前/盘中/收盘三个 Agent 与 TradingAgents 深度分析都需要模型服务。官方把模型做成「设置 → AI 服务商」里的 OpenAI 兼容入口，因此本地 Ollama 也可以接。
要不要装 TradingAgents？
它是可选依赖。官方在 requirements.txt 里已经以 git+https://github.com/TauricResearch/TradingAgents.git@v0.5.0 的形式列出，安装时会拉约 115 个包、耗时数分钟；不启用深度分析 Agent 时零开销。启用后每次分析按模型用量计费，默认月度预算 10 美元、超预算拒绝执行。
数据放在哪？升级会丢吗？
数据在挂载卷里（容器内 /app/data，本地开发默认 ./data），代码与数据分离，容器重建不会清空数据。但升级前仍建议先备份数据卷——项目发布节奏较快（0.10.2 到 0.16.1 共 10 个版本），跨版本升级的注意事项以对应 Release Notes 为准。
能放到公网上用手机访问吗？
技术上可以（服务绑定 0.0.0.0:8000，且官方提供 PWA 支持），但仓库里没有现成的反向代理与 HTTPS 配置。对外暴露意味着登录凭据、模型 Key、通知 Token 与持仓数据都暴露在同一条链路上，需自行加固代理层；官方安全政策把自建代理排除在修复范围之外。