1. PanWatch 到底想解决什么问题第一次看到 PanWatch 这个名字加上 TradingAgents、Docker、Agent、PWA 这几个关键词我脑子里第一反应是又一个盯盘工具市面上盯盘软件一抓一大把从券商自带到各种第三方客户端为什么还要自己折腾一个但把关键词拆开看事情没那么简单——TradingAgents 说明它背后有智能体协作的逻辑Docker 说明它是要自部署的PWA 说明它想同时覆盖桌面和移动端的使用场景。这三个词凑在一起指向的其实是一个很具体的需求把交易决策过程中的信息采集、分析、提醒这几件事用可编排的智能体串起来并且部署在自己能控制的机器上。我接触过不少做量化或者半自动交易的朋友大家的痛点出奇地一致。行情软件能给你数据但不会帮你做判断各种资讯 App 能给你新闻但和你持仓的关系要你自己去连好不容易写了个脚本跑策略换台机器就得重新配环境手机上看不到结果出门在外心里没底。PanWatch 这类项目要处理的就是这条链路上的断点。它不是要替代你的交易终端而是做一个信息中转和决策辅助层把分散的数据源、分析逻辑和通知渠道捏在一起。从技术形态上看PanWatch 是一个典型的自托管 Web 应用。Docker 负责把它和它的依赖打包成可移植的单元PWA 负责让这个 Web 应用在手机上表现得接近原生 AppTradingAgents 则负责核心的分析逻辑。这三者不是随便选的后面我会详细拆解每个选择背后的理由。适合读这篇内容的人大概分三类一是想自己搭一套盯盘辅助系统、但不知道从哪下手的开发者二是对 Agent 编排感兴趣、想找个真实项目练手的人三是已经在用类似工具、想对比一下架构思路的从业者。不管你是哪一类接下来的内容都会围绕怎么把它跑起来、为什么这么设计、实际用起来会遇到什么来展开。2. 用 Docker 把 PanWatch 跑起来环境准备的真实门槛2.1 为什么这个项目必须用 Docker 部署先说结论PanWatch 这类项目如果不用容器化部署体验会差到让人放弃。原因很直接——它要同时跑 Web 服务、Agent 调度、可能还有数据库和缓存这些组件对运行环境的要求各不相同。你在自己电脑上手动装一遍可能花两小时换一台服务器又得重来一遍而且中间任何一步版本对不上就是一堆报错。Docker 在这里的价值不是时髦而是把环境配置这件事从每次部署都要做变成一次做好、到处运行。镜像里已经把 Python 版本、依赖库、系统工具都固定下来了你拉下来直接跑就行。这也是为什么热词里 docker 安装、docker compose、docker 镜像这些词出现频率这么高——大家卡住的地方往往不是项目本身而是容器环境没弄对。提示如果你之前完全没碰过 Docker建议先花半小时把基础概念过一遍镜像image是模板容器container是模板跑起来的实例compose 是用来编排多个容器的配置文件。这三个概念搞清楚后面就不会晕。2.2 Windows 和 Linux 下的安装差异Windows 用户走的是 Docker Desktop 这条路Linux 用户走的是原生 Docker Engine。这两条路的坑完全不一样我分开说。Windows 上最常见的问题就是热词里那条 virtualization support not detected 和 docker desktop failed to start。这不是 Docker 的锅是底层虚拟化没开。你需要进 BIOS 把虚拟化支持打开Intel 平台叫 VT-xAMD 平台叫 SVM然后在 Windows 功能里确认虚拟机平台和适用于 Linux 的 Windows 子系统这两个组件是勾上的。少任何一个Docker Desktop 都起不来。装完之后如果遇到 failed to connect to the docker api at npipe 这类报错八成是 Docker Desktop 的服务没启动完等托盘图标变成稳定状态再操作。Linux 下相对干净但要注意权限问题。默认情况下普通用户不能直接操作 Docker每次都要 sudo 很烦。标准做法是把自己加进 docker 用户组sudo usermod -aG docker $USER执行完要重新登录才生效。这一步很多人漏掉然后一直用 sudo 跑后面挂载目录的时候就会出现权限混乱容器里写的文件宿主机读不了排查起来很费劲。2.3 拉取镜像与启动的完整流程假设你已经有了 Docker 环境PanWatch 的启动流程大致是这样。先确认 compose 文件里的镜像地址和端口映射然后docker compose pull docker compose up -d docker compose logs -fpull是拉最新镜像up -d是后台启动logs -f是实时看日志。第三步特别重要第一次启动一定要盯着日志看因为配置错误、端口占用、依赖服务没起来这些问题都会在日志里第一时间暴露。我见过太多人up -d之后就不管了然后发现访问不了再回头翻日志白白浪费时间。启动之后用docker compose ps看容器状态正常应该是 running 或者 healthy。如果状态是 restarting 或者 exited那就是启动过程中崩了回到日志里找原因。2.4 端口、数据卷和网络这三个配置项这三个是 compose 文件里最需要你手动确认的部分也是最容易出问题的地方。端口映射的格式是宿主机端口:容器端口。比如8080:8000意思是把容器里的 8000 端口映射到宿主机的 8080。如果你宿主机上 8080 已经被别的服务占了启动会报端口冲突换个数字就行。这里有个经验别用 80 和 443 这种常用端口除非你确定没有别的 Web 服务在跑否则冲突概率很高。数据卷决定了你的配置和数据库存在哪。如果不挂载容器一删数据就没了。标准写法是把宿主机的某个目录映射到容器里的数据目录这样升级镜像的时候数据还在。我一般会在宿主机建一个专门的数据目录比如/opt/panwatch/data权限设成容器内运行用户能读写。网络这块如果 PanWatch 需要连数据库或者缓存用 compose 自定义网络最省事。同一个 compose 文件里的服务默认就在一个网络里直接用服务名当主机名互相访问不用管 IP。热词里 docker 网络不通 是高频问题绝大多数情况是容器之间用了 localhost 去连对方——在容器里 localhost 指的是容器自己不是宿主机这个一定要记住。3. TradingAgents 的编排逻辑Agent 到底在干什么3.1 从一个脚本到多个 Agent 分工传统的盯盘脚本是什么样一个 while 循环拉数据算指标超过阈值就发通知。逻辑全写在一起改一处动全身。TradingAgents 这个思路不一样它把整个分析流程拆成几个角色每个角色负责一件事然后编排起来。打个比方这就像一个小型研究团队。有人负责收集情报数据采集 Agent有人负责分析基本面基本面分析 Agent有人负责看技术面技术分析 Agent最后有人汇总给出结论决策 Agent。每个 Agent 只关心自己的输入和输出彼此之间通过约定的数据格式传递信息。这样做的好处是你想换掉技术分析那部分逻辑不用动其他 Agent你想加一个新的分析维度加一个 Agent 挂上去就行。这也是为什么热词里 agent 框架、agent 架构、agent 框架与编排这些词这么热。大家真正关心的不是什么是 Agent这种概念问题而是多个 Agent 怎么协作、怎么传递数据、怎么处理某个 Agent 失败这些工程问题。3.2 Agent 之间的数据流与状态管理Agent 协作最核心的问题是数据怎么传。常见的有两种模式一种是共享一个状态对象每个 Agent 读写里面的字段另一种是链式传递前一个的输出直接作为后一个的输入。PanWatch 这类场景更适合共享状态模式。因为分析过程中多个 Agent 可能需要读同一份原始数据比如当前价格、持仓信息如果每个都自己去拉一遍既浪费又可能拿到不一致的数据。共享状态的做法是数据采集 Agent 拉一次写进状态里后面的 Agent 都从这个状态读。状态管理还有个绕不开的问题Agent 执行到一半失败了怎么办。热词里 agent execution terminated due to error 就是这类问题。我的经验是每个 Agent 的执行都要有超时和重试并且失败信息要写进状态里让后续 Agent 知道某一步没成功而不是拿着残缺的数据继续往下算。宁可整个流程标记为分析不完整也不要给出一个看起来正常、实际基于错误数据的结论。3.3 Agent 记忆为什么它比你想的更重要热词里出现了 agent 记忆和 a-memguard 这类词说明记忆机制是大家关注的重点。在盯盘场景里记忆的作用是什么举个具体例子今天某个 Agent 判断这只票处于震荡区间如果它记得过去三天都在震荡那这个判断的可信度就高如果它记得昨天还是单边上涨今天突然说震荡那就值得警惕。记忆分短期和长期。短期记忆就是当前这次分析流程里的上下文通常放在状态对象里。长期记忆是跨多次分析保留的信息需要持久化到数据库。PanWatch 用 Docker 部署长期记忆自然就落在挂载的数据卷里。这里有个实操上的坑记忆不能无限增长。你不可能把历史上每一次分析结果都塞进上下文那样 token 消耗会爆炸而且噪声太大。合理的做法是定期做摘要把一段时间内的分析结论压缩成几条关键信息存起来原始明细归档。这个摘要的粒度需要根据你的交易频率调日内交易和波段交易的粒度完全不一样。3.4 编排中的并发与限流多个 Agent 如果串行执行一次完整分析可能要等很久。能并行的部分要并行比如基本面分析和技术分析互不依赖可以同时跑。但并行带来两个新问题一是对外部数据源的请求会变多可能触发限流二是结果汇总时要处理时序问题。限流的处理办法是给每个数据源配一个请求队列控制并发数。比如某个行情接口限制每秒 5 次那你的采集 Agent 就不能同时发 20 个请求。这个在代码里通常用一个信号量或者令牌桶来实现。别小看这一步很多自建系统跑着跑着被封 IP就是因为没做限流。结果汇总的时序问题解决办法是给每个 Agent 的输出打上时间戳汇总的时候按时间对齐。如果某个 Agent 的结果明显滞后要么等它要么在结论里标注该维度数据延迟。4. PWA 这一层为什么不做原生 App4.1 PWA 在盯盘场景下的实际优势先说 PWA 是什么。简单讲它是一个普通网页但通过一些配置可以让你添加到主屏幕打开后没有浏览器地址栏看起来和原生 App 差不多还能接收推送通知、离线缓存部分内容。盯盘场景为什么适合 PWA因为这类应用的核心诉求是随时随地能看一眼而不是重度交互。你不需要在手机上做复杂的图表拖拽和参数调整那些在电脑上做更合适。手机上你要的是打开快、能看到关键信息、有异动能收到通知。这三点 PWA 都能满足而且省掉了开发两套原生 App 的成本。还有个现实原因自部署项目做原生 App分发是个大麻烦。上架应用商店要审核自己打包分发又要处理签名和安装信任问题。PWA 直接一个网址搞定你部署在服务器上手机浏览器打开就能用更新也是即时的不用等用户去应用商店下载新版本。4.2 添加到主屏幕与通知权限的实操PWA 的添加到主屏幕在不同系统上操作不一样。Android 的 Chrome 一般会自动弹出提示或者在菜单里找添加到主屏幕。iOS 的 Safari 是在分享菜单里找添加到主屏幕。注意 iOS 对 PWA 的支持一直比 Android 保守某些能力比如后台推送在不同系统版本上表现不一致这个要有心理预期。通知权限是另一个关键点。PWA 的推送需要用户明确授权而且必须是通过 HTTPS 访问才能触发权限请求。如果你在内网用 HTTP 访问通知功能基本用不了。解决办法是配一个域名加证书或者用反向代理套一层 HTTPS。这一步很多人会忽略然后纳闷为什么通知一直不弹。注意iOS 上 PWA 的推送支持是后来才加上的而且要求用户先把网页添加到主屏幕从主屏幕图标打开才可能收到推送。直接在 Safari 标签页里访问是收不到的。这个细节不搞清楚会以为是代码问题。4.3 离线缓存策略与数据新鲜度PWA 的 Service Worker 可以缓存资源让应用在弱网甚至离线时也能打开。但盯盘应用有个矛盾你希望打开快靠缓存又希望看到的是最新数据不能靠缓存。合理的策略是分层缓存。应用的壳HTML、CSS、JS、图标可以强缓存这些不常变。数据接口的响应绝对不能缓存或者只能缓存极短时间。Service Worker 里要明确区分这两类请求静态资源走 cache-firstAPI 请求走 network-first 或者直接 network-only。我踩过的一个坑是调试的时候改了前端代码刷新页面死活不生效最后发现是 Service Worker 缓存了旧版本。解决办法是在开发阶段禁用 Service Worker或者每次改完在开发者工具里手动清除缓存并注销 Service Worker。上线前再确认缓存策略是对的。5. 部署之后才会暴露的那些问题5.1 容器时区与时间戳错乱这个问题极其常见但排查起来很绕。容器默认用 UTC 时间如果你的分析逻辑里涉及今天昨天这种判断而宿主机是东八区就会出现数据对不上的情况。表现是明明应该是今天的数据系统却认为是昨天的。解决办法是在 compose 文件里设置时区环境变量environment: - TZAsia/Shanghai或者在 Dockerfile 里装好 tzdata 并设置好。这个坑的隐蔽之处在于它不会报错只是结果悄悄错了。等你发现的时候可能已经基于错误数据做了好几天的判断。5.2 数据持久化的验证方法挂载数据卷之后一定要验证数据真的落到了宿主机上。方法很简单在容器里写一个文件然后去宿主机的挂载目录看有没有。或者反过来在宿主机改一个配置文件重启容器看生效没有。我见过的情况是compose 文件里路径写错了容器实际上用的是内部目录数据卷挂了个寂寞。表面上看一切正常直到某次升级镜像容器重建所有配置和数据全没了才发现问题。所以部署完第一件事就是验证持久化别等出事。5.3 日志膨胀与磁盘占满Docker 容器的日志默认是往宿主机磁盘写的而且不限制大小。一个跑得久的服务日志能把磁盘撑满。表现是某天突然所有服务都异常一看磁盘 100%。解决办法是在 compose 里给每个服务配日志轮转logging: driver: json-file options: max-size: 10m max-file: 3意思是单个日志文件最大 10MB最多保留 3 个。这样日志总量可控。另外定期清理不用的镜像和停止的容器docker system prune可以一键清理但注意它会删掉没在用的东西执行前确认一下。5.4 Agent 执行超时与重试的边界Agent 调用外部接口超时是常态。关键是要区分可重试和不可重试的错误。网络抖动、接口临时 5xx这些可以重试参数错误、认证失败重试多少次都没用只会浪费资源。重试还要有退避策略不能失败后立刻重试那样会把对方打垮。常见做法是指数退避第一次等 1 秒第二次 2 秒第三次 4 秒最多重试 3 次。超过就放弃把这次分析标记为不完整。这里有个经验重试次数不是越多越好。在盯盘场景里时效性很重要一个数据等了 30 秒才拿到可能已经错过最佳判断时机。与其死等不如快速失败用上一次的数据或者标注缺失让决策 Agent 自己权衡。6. 从能跑到好用几个值得做的优化6.1 把配置从代码里抽出来项目刚跑起来的时候配置往往散落在各处。数据库地址写死在代码里通知渠道的密钥硬编码改一个参数要重新构建镜像。这在调试阶段还能忍一旦要长期用必须把配置抽成环境变量或者配置文件。标准做法是用.env文件配合 compose 的变量替换。敏感信息比如通知服务的密钥放.env.env加进.gitignore不提交。这样镜像可以复用不同环境用不同的.env就行。6.2 健康检查与自动重启容器跑着跑着卡死进程还在但服务不响应这种情况 Docker 默认是发现不了的。加健康检查能让 Docker 知道服务是不是真的可用healthcheck: test: [CMD, curl, -f, http://localhost:8000/health] interval: 30s timeout: 10s retries: 3配合restart: unless-stopped服务挂了会自动拉起来。这两个配置加起来能省掉很多半夜起来重启服务的麻烦。6.3 备份策略数据比镜像重要镜像随时能重新拉数据丢了就真没了。定期备份数据卷是必须的。最简单的办法是写个脚本把数据目录打包压缩存到另一个地方。频率看你的数据变化速度配置类的一天一次够了分析结果类的看重要性。备份还要验证能恢复。我见过备份文件攒了一堆真出事的时候发现压缩包是坏的或者恢复步骤根本跑不通。定期做一次恢复演练比备份本身还重要。6.4 监控告警让系统自己告诉你出问题了系统跑起来之后你需要知道它是不是正常。最基础的监控是看容器状态和资源占用进阶一点是监控业务指标比如最近一次分析是什么时候完成的Agent 失败率是多少。告警渠道可以复用 PanWatch 自己的通知能力也可以单独接一个。关键是告警要分级磁盘快满了这种可以提前预警服务挂了这种要立即通知。别把所有事情都设成最高优先级那样会麻木真正重要的问题反而被淹没。7. 我在实际搭建中总结的几条经验折腾这类自部署项目技术细节固然重要但真正决定成败的往往是那些不起眼的习惯。我把自己踩过的坑和总结的经验列几条都是实打实换来的。第一条先把最小可用版本跑通再加功能。很多人一上来就想把所有 Agent 都配上、所有通知渠道都接上结果一个环节出问题根本不知道是哪里的错。正确做法是先让最核心的流程跑起来确认数据能采集、分析能出结果、通知能收到然后再逐个加维度。第二条日志要打得足够细但别打敏感信息。排查问题全靠日志但密钥、账号这些绝对不能进日志。我一般会在日志里记录调用了哪个接口、耗时多少、返回状态码但不记录请求体和响应体的完整内容尤其是涉及认证的部分。第三条版本要锁死。镜像别用 latest 标签用具体的版本号。latest 意味着你每次拉都可能拿到不一样的代码今天能跑明天崩了排查起来毫无头绪。锁版本虽然少了自动更新的便利但换来了可复现性这在自部署场景里更重要。第四条文档写给自己看。部署过程中做的每一个非标准操作都记下来。过三个月你自己都忘了当时为什么那么配。一份简单的部署笔记能省掉未来大量的重复排查。第五条别在主力机器上做实验。Docker 虽然隔离但端口冲突、磁盘占满这些问题还是会影响到宿主机。有条件的话用一台单独的机器或者虚拟机来跑这类服务出问题不影响你日常干活。这套东西搭起来之后你会发现它的价值不在于某个 Agent 有多聪明而在于整条链路是通的、可控的、能持续跑的。数据在自己手里逻辑自己能改通知自己能配这种掌控感是现成软件给不了的。至于后面要不要加更多分析维度、要不要接更多数据源那都是在这个稳定底座上的自然延伸。