用 GitHub Release Monitor 自动追踪开源项目更新：从零到部署的完整指南

“

你是否也常常在浏览器里反复刷新某个 GitHub 仓库，只为等那条「Release v2.3.0」？
本文手把手带你用 GitHub Release Monitor 把这件重复、耗时、还容易遗漏的小事自动化。全文 9000+ 字，含 Docker 一行启动、手动部署、常见坑排查与 FAQ，照着做 30 分钟就能上线。

一、这东西到底能帮我做什么？

一句话：把「追踪开源项目的新版本」这件事变成「收到一封邮件通知」。

使用场景举例 过去怎么做 现在怎么做
每天早八检查十几个常用库的 release 打开浏览器 × N → 点进每个仓库 → 看 tag 早上 8:05 打开邮箱，邮件标题告诉你谁发布了什么
发现依赖库出了 RC 版本，想提前测试 手动订阅 release → 收到所有 pre-release 的噪音 在 UI 里只勾选 rc 标签，其他 beta/alpha 不打扰
团队内部共享关注列表 把仓库链接甩进群里，大家各自收藏 导出一份 JSON，同事 5 秒导入，同步完成

二、核心能力速览

功能 一句话解释
自动监控 背景任务每 N 分钟轮询一次 GitHub API，发现新版本即发邮件
邮件通知 支持任何 SMTP 服务器，主题、正文可自定义
过滤规则 全局开关（稳定版 / 预发布 / 草稿），还能给每个仓库单独改规则
国际化 界面英文、德文随浏览器语言切换
数据可移植 一键导出 JSON，换机器也能 10 秒复原
内置诊断 测试页告诉你「GitHub 通不通」「SMTP 发不发得出」

三、30 秒看懂技术栈

  • 前端：Next.js 14 + TypeScript + Tailwind CSS + ShadCN UI
  • 后端：同一套 Next.js 的 App Router，无需额外服务器
  • 邮件：Nodemailer，支持 STARTTLS / SSL
  • 认证：iron-session 加密 cookie，无需数据库
  • 打包：Docker 镜像 ghcr.io/iamspido/github-release-monitor:latest

“

如果你只关心“跑起来”，直接跳到「Docker Compose 部署」即可；想深入源码再看「手动部署」。

四、Docker Compose 部署（官方推荐，含自动 HTTPS）

1. 准备条件

  • 一台能装 Docker 和 Docker Compose 的 Linux 服务器（Ubuntu 22.04 演示）
  • 一个域名，例如 releases.example.com 解析到服务器 IP
  • 80/443 端口未被占用（Traefik 会自动申请 Let’s Encrypt 证书）

2. 下载示例配置

git clone https://github.com/iamspido/github-release-monitor.git
cd github-release-monitor/example

目录结构：

example
├── traefik/          # 反向代理 + 自动 HTTPS
├── smtp/             # 本地 SMTP relay（可选）
└── github-release-monitor/   # 主程序

3. 配置主程序

进入主程序目录，编辑 .env：

cd github-release-monitor
cp env.example .env
nano .env

最少需要改 4 处：

变量 示例值 说明
AUTH_SECRET openssl rand -base64 32 生成的 44 位随机串 加密 cookie 用
AUTH_USERNAME admin 登录用户名
AUTH_PASSWORD Sup3rSecure! 登录密码
GITHUB_ACCESS_TOKEN ghp_xxx… 去 GitHub → Settings → Tokens 创建，不要勾选任何 scope 即可公开库访问
MAIL_FROM_ADDRESS notify@example.com 发件人
MAIL_TO_ADDRESS you@example.com 收件人

“

如果你用自带的 SMTP relay，MAIL_HOST / MAIL_PORT 保持默认即可。

4. 配置 Traefik

进入 example/traefik/compose.yaml：

command:
  - "--certificatesresolvers.letsencrypt.acme.email=you@example.com"

把邮箱换成自己的，证书到期自动续期。

5. 配置 SMTP Relay（可选但推荐）

进入 example/smtp/compose.yaml：

environment:
  - POSTFIX_myhostname=example.com
  - OPENDKIM_DOMAINS=example.com=mail

域名与 MAIL_FROM_ADDRESS 对应，减少进垃圾箱概率。

6. 启动服务

按顺序启动：

# 1. 反向代理网络
docker compose -f traefik/compose.yaml up -d

# 2. SMTP
docker compose -f smtp/compose.yaml up -d

# 3. 主程序
docker compose -f github-release-monitor/compose.yaml up -d

浏览器打开 https://releases.example.com，输入用户名密码即可。

五、Docker 单行启动（无 HTTPS，本地测试）

如果你只是本地尝鲜，一条命令：

mkdir -p data && sudo chown -R 1001:1001 data
docker run -d \
  -p 8080:3000 \
  -v "$PWD/data:/app/data" \
  --env-file .env \
  --name github-release-monitor \
  ghcr.io/iamspido/github-release-monitor:latest

访问 http://localhost:8080。

六、手动部署（源码跑起来）

适用场景：

  • 想改 UI 或加功能
  • 公司内网无法拉镜像
  • 想跑在 ARM、OpenWrt 等特殊环境

步骤 1：克隆代码

git clone https://github.com/iamspido/github-release-monitor.git
cd github-release-monitor

步骤 2：安装依赖

npm install

步骤 3：准备数据目录

mkdir data
sudo chown $(whoami) data

步骤 4：写 .env

复制示例并填写：

cp .env.example .env
nano .env

必填项与 Docker 部分相同，不再赘述。

步骤 5：启动

开发模式（热更新）：

npm run dev

生产模式：

npm run build
npm run start

默认监听 :3000。

七、界面速通：第一次登录后做什么？

  1. 添加仓库
    主页右上角「Add Repository」→ 输入 facebook/react 这类格式 → 保存。
    系统立刻查询一次，如有最新 release 会立即发邮件（可关闭）。

  2. 全局过滤器
    Settings → Global Filters：

    • Stable：稳定版
    • Pre-release：预发布
    • Draft：草稿
      按你的口味开关。

  3. 仓库级过滤
    对单个仓库点「Edit」→ Override Global → 只勾 rc，于是只有 v2.0.0-rc.1 会提醒你。

  4. 测试邮件
    Settings → Diagnostics → Send Test Email，确认 SMTP 通不通。

  5. 导入导出
    Settings → Data → Export JSON，换机器时直接拖进去即可。

八、FAQ：你可能遇到的 12 个问题

问题 一句话答案
没有域名能用吗？ 可以，单行 Docker 跑本地 localhost:8080，只是没有 HTTPS。
GitHub Token 必须吗？ 不填也能跑，但每小时只能调 60 次 API，多几个仓库就超。
邮件发不出去？ 先看 Diagnostics → Test Email；再检查 25/587/465 端口是否被封。
能同时通知多人吗？ 目前一封邮件只能填一个 MAIL_TO_ADDRESS，可自建邮件组解决。
能钉钉/飞书通知吗？ 官方只支持 SMTP；社区有人用 Webhook-to-Email 转发实现。
如何更新版本？ Docker：docker pull … 然后 docker compose up -d；源码：git pull && npm run build。
数据存在哪？ Docker：./data/settings.json；源码：./data/，定期备份即可。
忘记密码？ 停容器 → 改 .env 里 AUTH_PASSWORD → 重启。
能监控私有仓库吗？ 需要给 Token 加 repo scope，并把仓库地址写完整。
ARM 服务器能用吗？ 镜像支持 linux/arm64，手动部署亦可。
日志在哪看？ Docker：docker logs github-release-monitor；源码：./data/logs/。
会重复发邮件吗？ 不会，系统记录已发 release id，除非删库重建。

九、常见场景配置示例

场景 1：只关注稳定版

  • Global Filters：仅勾选 Stable
  • 所有仓库用 Global 即可
  • 好处：邮箱安静，不被 alpha/beta 打扰

场景 2：前端团队关注 Next.js Canary

  • 添加 vercel/next.js
  • Override → Pre-release 打勾 → Tags 填 canary
  • 于是 v14.0.5-canary.6 会提醒，而 v14.0.4 不会

场景 3：运维组内部共享列表

  1. 管理员 A 把常用 30 个库添加完
  2. Settings → Export JSON → 存成 team-repos.json
  3. 新同事入职：Import JSON → 10 秒完成同步

十、故障排查清单（收藏备用）

现象 检查项
页面打不开 docker ps 看容器是否 Exited；docker logs 查报错
SSL 证书无效 Traefik 日志里找 acme 关键字；域名是否解析正确
邮件进垃圾箱 给 POSTFIX_myhostname 与 DNS A 记录对齐；加 SPF、DKIM
API 报错 403 Token 是否过期；私有库是否忘加 repo scope
界面显示德语 浏览器语言优先级导致，手动在 URL 加 ?locale=en

十一、扩展阅读：如何自己魔改

  • 换主题色：改 tailwind.config.js → 重新编译
  • 加 Webhook 通知：在 src/lib/notifications.ts 里新增 provider
  • 接入企业微信：把 SMTP 换成企业微信的「邮件机器人」地址即可
  • 跑在 NAS：群晖 DSM 7 直接装 Docker Compose，网络选 host 模式

十二、小结

GitHub Release Monitor 把「盯版本」这件事做到了极简：

  • 对开发者：再也不用写脚本轮询 GitHub API
  • 对团队：共享列表、零配置迁移
  • 对运维：一条 Docker Compose 搞定 HTTPS、SMTP、备份

照着本文 30 分钟搭好，把节省下来的时间留给写代码吧。