这是什么？

MagicPush 是一个轻量级的消息推送服务管理平台。它的核心思路很直接：把不同通知渠道统一收进一个 Web 管理后台，再通过标准化 REST API 对外提供推送入口。

换句话说，它不是“又注册一个第三方推送服务”，而是把自己的服务器变成一个消息网关。脚本、定时任务、NAS、CI/CD、监控系统只需要调用同一个 API，后面到底走 Telegram、企业微信、钉钉、飞书、邮件还是 Bark，可以交给 MagicPush 管。

为什么需要它？

消息推送这件事看起来简单，实际很容易越用越乱。

比如 Telegram Bot 很好用，但对网络环境有要求；企业微信、钉钉、飞书适合企业内部通知，但个人场景未必顺手；微信公众号、服务号、第三方推送服务又会遇到模板、频率、账号规则或服务停更的问题。

最麻烦的是：如果每个脚本都单独维护一套推送逻辑，后面换渠道就会变成“全项目考古”。

MagicPush 解决的是这个中间层问题：

自动化脚本 / 监控 / NAS / CI/CD / 业务系统
  ↓
统一 REST API
  ↓
MagicPush
  ↓
Telegram / 企业微信 / 钉钉 / 飞书 / 邮件 / Bark / Gotify / Webhook ...

这样一来，调用方只关心“我要发一条通知”，渠道的增删改放在后台处理。推送逻辑终于不用像散落各处的充电线一样，越理越打结。

支持的渠道

MagicPush 支持的渠道相当丰富，覆盖个人、企业、自托管和通用 Webhook 场景：

这里最有价值的不是“渠道多”本身，而是它们可以被统一管理。比如同一条服务器告警，可以同时发到企业微信群、Telegram 和邮件；某些生活类提醒，则只发到 Bark 或 WxPusher。

核心功能

MagicPush 的功能重点集中在“推送平台化”：

• 多渠道消息同时推送。
• 标准化 REST API 调用。
• 用户注册、登录和渠道绑定。
• 双令牌 JWT 认证机制，包含 access token 和 refresh token。
• 推送接口管理，支持多接口、多令牌。
• 关键词过滤，支持黑名单和白名单模式。
• 消息免打扰，可按接口配置多个免打扰时段。
• 推送历史记录和状态追踪。
• 响应式 Web 管理界面，支持深色/浅色主题。

对个人用户来说，最实用的是“多接口、多令牌”。不同脚本可以用不同接口，权限和记录更清楚；某个 token 泄露或废弃时，也不用把所有服务一起重配。

安全与限流

推送服务如果暴露到公网，安全和限流就不是装饰品，而是保命符。

MagicPush 的 README 里提到它支持多层限流，包括 Express 全局限流、接口级限流，以及推送接口按来源 IP 和推送 Token 的双重限流。管理员也可以在前端安全设置中调整限流规则，并查看限流日志。

需要注意一个边界：预构建 Docker 镜像 magiccode1412/magicpush:latest 是 All-in-One 模式，由 Express 直接提供静态文件，不包含 Nginx 层兜底限流。因此它只有 Express 层的限流。如果你需要 Nginx 层的 IP 频率限制和并发连接控制，需要使用项目里的 docker-compose up -d 自行构建前后端分离镜像。

另外，各渠道平台本身也有频率限制。比如企业微信群机器人、钉钉、飞书、Telegram、PushPlus、WxPusher 等都可能按机器人、群、token 或账号限制请求频率。MagicPush 可以帮你统一入口，但不能绕过平台规则。高频告警场景建议优先考虑自托管渠道，例如 Gotify、Bark 自建服务、ntfy 自建服务或自己的 Webhook。

Docker 部署

项目提供了预构建 Docker 镜像，支持 amd64 和 arm64 架构。最简单的启动方式是：

docker run -d -p 3000:3000 \
  -v ./data:/app/server/data \
  -v ./logs:/app/server/logs \
  --name magicpush \
  --restart always \
  magiccode1412/magicpush:latest

启动后访问：

http://<服务器ip>:3000

如果偏好 docker compose，可以这样写：

services:
  app:
    image: magiccode1412/magicpush:latest
    ports:
      - "3000:3000"
    volumes:
      - ./data:/app/server/data
      - ./logs:/app/server/logs
    network_mode: bridge
    restart: always
    container_name: magicpush

国内环境也可以参考项目 README 中的 CNB 镜像地址。需要 Nginx 层限流时，不要直接使用预构建 All-in-One 镜像，而是拉取项目后按文档执行：

docker-compose up -d

API 使用示例

MagicPush 的意义在于让调用方变简单。一个典型调用形态大概是这样：

curl -X POST "http://你的服务器:3000/api/push/你的接口令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "服务器告警",
    "content": "CPU 使用率超过 90%，请检查。"
  }'

这个示例只表达调用方式：POST 到某个推送接口，提交标题和内容。实际路径、字段和鉴权方式请以 MagicPush 后台生成的接口配置以及项目文档为准。

一旦入口固定，后面脚本就可以写得很干净：

任务成功 → 调 MagicPush → 发到 WxPusher
任务失败 → 调 MagicPush → 同时发 Telegram + 邮件
NAS 异常 → 调 MagicPush → 发到企业微信 + Bark

这就是消息网关的价值：业务脚本不再关心渠道细节。

适合谁？

MagicPush 特别适合这些场景：

• 服务器告警：磁盘、内存、CPU、证书到期、服务离线。
• NAS 通知：下载完成、备份完成、同步失败、硬盘异常。
• 自动化脚本：签到、定时任务、爬虫结果、数据同步状态。
• CI/CD 通知：构建失败、部署成功、版本发布提醒。
• 个人服务监控：家庭服务器、旁路由、Docker 容器、网站状态。
• 小团队消息聚合：把分散通知统一转到团队常用渠道。

如果你只有一个脚本、只发一个 Bark，那 MagicPush 可能有点杀鸡用牛刀。可一旦你有三五个服务、两三个渠道、十几个 token，它就很像一个“推送配线架”：线还是那些线，但终于有地方收纳了。

优缺点

它更像基础设施，不像一次性小工具。部署后可能不会每天打开后台，但每次脚本要发通知时，它都在背后干活。

技术栈与开源信息

MagicPush 后端基于 Node.js 18+、Express、SQLite、JWT、bcryptjs 等技术；前端使用 Vue 3、Vite、Tailwind CSS、Element Plus、Pinia。项目使用 MIT 协议开源。

这套技术栈比较适合轻量自托管：SQLite 降低了数据库维护成本，Docker 降低了部署门槛，Vue 管理后台也足够直观。对个人服务器、NAS 或小团队内网环境来说，负担不大。

总结

MagicPush 的价值不是“多一个推送服务”，而是把分散的通知渠道变成自己的消息网关。

它适合那些已经有不少自动化脚本、服务器告警、NAS 任务、CI/CD 通知的人。你不必在每个项目里重复写 Telegram、企业微信、邮件、Webhook 的适配代码，只要统一打到 MagicPush，再由它分发到不同渠道。

当通知系统开始变复杂时，最重要的不是再找一个渠道，而是先拥有一个稳定的中转层。MagicPush 做的就是这件事：让消息各回各家，但入口只有一个。