ntfy 保姆级部署教程：一行 curl 把消息推到你手机的开源通知服务

ntfy（仓库 binwiederhier/ntfy，Go 编写，Star 数约 3.5 万，读作 "notify"）是一个基于 HTTP 的发布-订阅（pub-sub）通知服务：任何电脑、任何脚本，用一行 curl -d "消息内容" ntfy.sh/我的主题 就能把通知推送到你的手机或桌面，无需注册、无需付费。官方提供免费的公共实例 ntfy.sh，同时整个服务开源，完全可以自托管到自己的服务器。它和邮件通知、钉钉/企微机器人等"通道绑定"的方案不同——ntfy 只有"主题"一个概念，天然适合脚本告警、任务完成提醒、服务器监控通知等场景。

一、项目介绍与适用场景

ntfy 官方定位："send notifications to your phone or desktop via PUT/POST"。架构极简：发布者向某个主题（topic）发消息，订阅者（手机 App、Web 页面、CLI）监听同一主题即可收到。官方提供开源 Android App（Google Play / F-Droid）与 iOS App（App Store）。

适用场景：cron 备份/任务完成通知、服务器与网站监控告警、CI/CD 构建结果推送、脚本报错提醒、家居自动化通知、给自己或团队的临时消息广播等。

二、核心功能逐条拆解

1. HTTP 发布/订阅：curl -d（POST）即可发消息，手机/桌面/Web 实时收到，无需注册账号。
2. 富文本消息：支持标题（X-Title）、标签（X-Tags）、优先级（X-Priority，1-5）、表情符号 emoji。
3. 访问控制：自托管可用 Token 做读写权限分离（write/read），公共实例也可对主题加 token 防打扰。
4. 附件与图片：可随消息发送图片/文件附件，配合 Web 界面直接预览。
5. 消息缓存：--cache-file 持久化最近消息，新订阅者能补收离线消息。
6. 多端订阅：Android/iOS App、Web App、CLI（ntfy subscribe）、API 轮询全支持。
7. Web Push / 邮件桥接：浏览器 Web Push 通知，还可邮件、Matrix、Signal 等通道集成。
8. 低资源占用：Go 单二进制，官方 Docker 镜像 amd64/armv6/armv7/arm64 全架构可用。

三、全套官方链接

四、硬件与环境前置要求

官方文档指出服务器以静态链接二进制发布，以 tarball、deb/rpm 包与 Docker 镜像形式分发。单实例占用很低（内存约几十 MB），普通 VPS 即可；官方支持 Linux（systemd/OpenRC）、macOS（Homebrew）、Windows、FreeBSD、Arch/NixOS，以及 Docker/Kubernetes/Helm。公共实例免费使用（单条消息约 10KB 限制），自托管则完全自主。

五、多平台部署步骤

5.1 Docker 部署（推荐）

第 1 步：官方镜像一条命令启动（默认监听 80 端口）：

docker run -p 80:80 -it binwiederhier/ntfy serve

第 2 步：加持久化消息缓存（官方原文命令）：

docker run \
  -v /var/cache/ntfy:/var/cache/ntfy \
  -p 80:80 \
  -it \
  binwiederhier/ntfy \
    serve \
    --cache-file /var/cache/ntfy/cache.db

第 3 步：用配置文件管理更多参数（官方提示：镜像内不含 /etc/ntfy/server.yml，需自行建文件并挂载）：

docker run \
  -v /etc/ntfy:/etc/ntfy \
  -e TZ=UTC \
  -p 80:80 \
  -it \
  binwiederhier/ntfy \
  serve

可用仓库的 server.yml 模板 起步；非 root 运行时记得把 server.yml、user.db、cache.db 与附件目录 chown 到对应 UID:GID（官方原文提醒）。

5.2 预编译二进制部署（Linux）

第 1 步：从 Releases 页 下载 amd64/arm64 等对应 tarball（官方原文 x86_64 示例，以 v2.35.0 为例）：

wget https://github.com/binwiederhier/ntfy/releases/download/v2.35.0/ntfy_2.35.0_linux_amd64.tar.gz
tar zxvf ntfy_2.35.0_linux_amd64.tar.gz
sudo cp -a ntfy_2.35.0_linux_amd64/ntfy /usr/local/bin/ntfy
sudo mkdir /etc/ntfy && sudo cp ntfy_2.35.0_linux_amd64/{client,server}/*.yml /etc/ntfy
sudo ntfy serve

第 2 步：安装 systemd 服务（tarball 自带 unit 文件，官方原文命令）：

sudo mv ntfy_2.35.0_linux_amd64/server/ntfy.service /etc/systemd/system/
sudo chmod 644 /etc/systemd/system/ntfy.service
sudo systemctl daemon-reload && sudo systemctl enable --now ntfy

5.3 Debian/Ubuntu apt 仓库

官方提供 apt 源（archive.ntfy.sh），添加 keyring 后 apt install ntfy 即可，之后由 systemd 管理，升级走 apt。

六、配置文件全部参数解释

配置文件在 /etc/ntfy/server.yml（Docker 挂载或二进制解压自带的 server/*.yml），常用项（官方 config 文档）：

命令行等价参数（如 --cache-file、--listen-http）也可直接传给 ntfy serve；镜像内不带配置文件时命令行参数是唯一入口。

认证相关命令也走 ntfy CLI：ntfy user add --role=admin 用户名 建用户、ntfy token add --role=admin 用户名 签发管理员 Token、ntfy token add 用户名 主题 给指定主题签发只读/只写 Token，全部记录在 auth-file 指定的数据库里（官方 config 文档）。

七、启动、后台常驻与开机自启

7.1 前台启动

ntfy serve

7.2 systemd 常驻（Debian/RPM 包或上述二进制第 2 步安装后）

sudo systemctl start ntfy
sudo systemctl enable ntfy   # 开机自启

7.3 Docker 常驻（docker-compose，官方示例含健康检查）

services:
  ntfy:
    image: binwiederhier/ntfy
    container_name: ntfy
    command: ["serve"]
    volumes:
      - /var/cache/ntfy:/var/cache/ntfy
      - /etc/ntfy:/etc/ntfy
    ports:
      - 80:80
    restart: unless-stopped

八、功能实操教程

第 1 步：部署完成后（无论 Docker 还是二进制），浏览器访问 http://服务器IP，能看到 ntfy Web 界面即成功。

第 2 步：命令行发一条通知（官方文档原文，公共实例可直接用）：

curl -d "Backup successful 😀" ntfy.sh/mytopic

自托管则把域名换成自己的：curl -d "备份完成" https://你的域名/mytopic。

第 3 步：带标题、优先级与标签：

curl -H "X-Title: 备份完成提醒" -H "X-Priority: high" \
  -H "X-Tags: warning,daily-backup" -d "mailsrv13 备份失败，请检查" ntfy.sh/mytopic

第 4 步：手机订阅。安装官方 Android App（Google Play / F-Droid）或 iOS App（App Store），添加服务器地址（公共 ntfy.sh 或你的自托管域名），订阅主题 mytopic，之后同一主题的消息即推送到手机。

第 5 步：Web 端订阅。在 ntfy Web 界面订阅主题即可在浏览器收到 Web Push 通知。

第 6 步：写进脚本。把 curl 命令放进 cron / systemd timer / CI 步骤，例如备份脚本末尾一行即可实现"跑完提醒"；配合 X-Tags 打上 backup 等标签便于过滤。

第 7 步：访问控制。自托管时启用认证（配置 auth-file），用 ntfy user add / ntfy token add 给每个主题分配 write/read Token，只有持 Token 者能发/收，防止主题被滥用。

第 8 步：命令行订阅。装好二进制后 ntfy subscribe mytopic 即可在终端实时收该主题消息；ntfy subscribe --poll mytopic 用轮询模式（适合不能长连接的脚本）。

第 9 步：发图片与附件。curl -F "file=@图片.jpg" ntfy.sh/mytopic 把文件作为附件随消息发送，Web/App 端直接预览；X-Attach 头也可指定远程文件地址（官方发布文档）。

九、全套报错故障排查

1. 公网无法推送 / App 收不到 原因：自托管未配置 base-url，或服务器 80 端口未开放。 解决：在 server.yml 设 base-url: https://你的域名 并重启服务；检查防火墙/安全组放行 80 端口。

2. App 订阅提示连接失败 原因：实例在反代后面但未开 behind-proxy: true，或 HTTPS 未配置。 解决：反代部署场景在配置里加 behind-proxy: true（官方文档明确要求）。

3. 重启后消息丢失 原因：未配置 cache-file，消息缓存是内存态。 解决：Docker 加 -v /var/cache/ntfy:/var/cache/ntfy 并指定 --cache-file /var/cache/ntfy/cache.db（官方命令示例）。

4. Docker 里配置文件不生效 原因：镜像默认不含 /etc/ntfy/server.yml（官方原文提示）。 解决：手动创建配置文件并 -v /etc/ntfy:/etc/ntfy 挂载，或用命令行参数。

5. 非 root 容器权限报错 原因：数据文件归属与容器用户不一致。 解决：按官方提醒把 server.yml、user.db、cache.db 与附件目录 chown 到容器运行 UID:GID。

6. 消息发出去但收不到，Web 端能看到 原因：手机 App 没连对实例，或只订阅了公共 ntfy.sh 而消息发到了自托管实例（反之亦然）。 解决：App 添加服务器地址时填对域名；主题名保持完全一致（大小写敏感）。

7. curl -d 报 404/401 原因：主题受 Token 保护，或路径前缀不对。 解决：给消息加 -H "Authorization: Bearer 你的writeToken"（官方发布文档的认证写法）。

十、升级、回滚与卸载

• 升级：apt 用户 apt upgrade；二进制用户下载新版本替换 /usr/local/bin/ntfy；Docker 用户 docker pull binwiederhier/ntfy && docker rm -f ntfy && docker run ...。
• 回滚：Releases 页有历史版本，替换旧二进制或固定 Docker 镜像 tag。
• 卸载：systemctl disable --now ntfy 后删 unit 文件与 /usr/local/bin/ntfy、/etc/ntfy（缓存/认证数据在 /var/cache/ntfy，删除前确认不再需要）。

十一、商用许可与合规风险提示

• License：Apache-2.0 与 GPLv2 双许可（官方 README 原文），可自由商用，注意 GPL 组件义务以分发方式为准。
• 自托管后消息内容由你负责：不要推送敏感明文到公共实例主题（公共主题任何人可订阅）。
• 给他人/团队提供通知服务时，建议强制 Token 认证并设置 auth-default-access 收紧默认权限。

参考链接

• 官方 README：binwiederhier/ntfy
• 安装文档：ntfy.sh/docs/install
• 发布文档：ntfy.sh/docs/publish
• 手机订阅文档：ntfy.sh/docs/subscribe/phone
• GitHub Releases：github.com/binwiederhier/ntfy/releases