企业官网建设流程全解析

PanWatch 从源码构建 Docker 镜像：make build 与 GitHub Actions 发布流程

【免费下载链接】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 盯盘工具，提供持仓分析、实时提醒与自动报告。本文将从源码出发，讲解如何用make build一键构建 PanWatch Docker 镜像，以及它背后的 GitHub Actions 多平台发布流程。

一、为什么值得自己构建镜像？

官方镜像发布在 Docker Hub，但自己动手构建能带来三个好处：

• 验证代码：本地构建即本地测试，构建通过说明依赖和前端打包都没问题；
• 定制版本：可以在自己的分支上打私有版本标签，只推送到自己的仓库；
• 理解架构：PanWatch 采用「Node 前端构建 + Python 后端运行」的多阶段 Dockerfile，是学习生产级镜像瘦身的好样本。

构建完成后，你得到的就是一个可直接docker run的 PanWatch 容器，启动后访问http://localhost:8000即可使用 AI 盯盘、实时提醒等功能。

二、一键构建步骤：make build 详解

2.1 准备工作

先克隆仓库（只读使用即可）：

git clone https://gitcode.com/GitHub_Trending/pa/PanWatch cd PanWatch

本地构建需要三个工具：Node.js（前端）、pnpm（包管理）、Docker。Makefile 中的build目标会自动检测操作系统并选择对应脚本：

• Linux/macOS：执行 build.sh
• Windows：执行 scripts/build.ps1（PowerShell 版）

2.2 执行构建

make build VERSION=0.1.0

版本号是必填参数，不传会提示Usage: make build VERSION=<version>。build.sh 会依次完成四步：

1. 构建前端：在frontend/目录执行pnpm install --frozen-lockfile && pnpm build；
2. 复制静态产物：把frontend/dist/拷到临时static/目录供 Dockerfile 使用；
3. 构建镜像：docker build --platform linux/amd64 --build-arg VERSION=0.1.0 -t sunxiao0721/panwatch:0.1.0 .，固定 amd64 架构以适配大多数服务器和 NAS；
4. 追加 latest 标签：非 latest 版本会额外打一个latest标签，方便快速部署。

构建完成后脚本会直接打印后续命令：

# 运行容器 docker run -d -p 8000:8000 -v panwatch_data:/app/data sunxiao0721/panwatch:0.1.0 # 推送镜像（需先 docker login） docker push sunxiao0721/panwatch:0.1.0

三、Dockerfile 多阶段构建解读

Dockerfile 是整个构建的核心，采用两阶段设计来控制镜像体积：

几个值得注意的工程细节：

• 版本号注入：构建时通过ARG VERSION写入 VERSION 文件（当前仓库中为dev），运行时版本即可追溯；
• 前端产物挂载：COPY --from=frontend-builder把 dist 直接拷入./static/，最终镜像里不含 Node 环境；
• 健康检查：内置HEALTHCHECK，每 30 秒请求/api/health探活；
• 可覆盖时区：默认TZ=Asia/Shanghai，可用-e TZ=...覆盖；
• Playwright 延迟安装：浏览器在首次启动时自动装到数据卷data目录，进一步减小镜像体积。

数据统一存放于/app/data，通过-v panwatch_data:/app/data持久化，升级镜像时持仓、提醒配置等数据不会丢失。

四、GitHub Actions 自动发布流程

正式版本不依赖本地构建，而是由.github/workflows/release.yml全自动完成，流程如下：

推送 tag (x.y.z) 或 手动触发 ↓ 跑后端单测（pytest tests/ -x -q） ↓ 跑 marketdata 包测试 ↓ QEMU + buildx 多平台构建（amd64 + arm64） ↓ 登录 Docker Hub，推送 version / latest 标签 ↓ 生成 release-notes.md → 创建 Release → Telegram 通知

4.1 两种触发方式

1. Tag 推送：推送形如0.2.3的 tag（注意：不带 v 前缀，匹配规则为*.*.*）自动触发；
2. 手动触发：通过workflow_dispatch指定version、是否推送latest、目标平台（默认linux/amd64,linux/arm64）。

4.2 版本解析的兼容性处理

workflow 中的 "Resolve version" 步骤（release.yml）会把带v前缀的 tag 自动去掉前缀，因此v0.2.3和0.2.3都能正确发布，并生成对应 Docker 标签（版本号标签 + 可选 latest）。

4.3 质量门禁

• 构建前必须跑通全部后端单测和 marketdata 包测试，测试不过则发布中止；
• 仓库还提供了 scripts/pre_release_check.sh，可在发布前手动执行：单测 + Python 编译检查 + 前端构建，加--with-agent-smoke参数还会触发 4 个 AI Agent（日报、盘前展望、图表分析师、盘中监控）做真实冒烟验证；
• 通过 make install-hooks 安装 scripts/pre-push 钩子后，每次git push前都会自动跑单测，把问题拦在推送之前。

五、本地构建 vs 自动发布怎么选？

总结

PanWatch 的构建发布链路非常清晰：make build负责本地一键构建，build.sh 串起前端打包与 Docker 多阶段构建；GitHub Actions 的 release.yml 则在测试门禁通过后，自动构建 amd64/arm64 双架构镜像并推送到 Docker Hub，附带 Release 说明与即时通知。无论你是想尝鲜新特性还是自部署 AI 盯盘，都能在这条流水线上找到适合自己的方式。

【免费下载链接】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