ntfy:一条 curl 把消息推到手机上
读者假设:会敲命令行,装过 Docker。 需要:一台常开的机器(或直接用官方托管)+ 手机。20 分钟。 成品:
curl -d "备份完成" 你的服务器/备份,手机立刻响。
一、它解决什么问题
写脚本的人都会遇到这个断层:
脚本跑完了 → 结果在日志里 → 没人看 → 三天后才发现失败了
要补上"通知"这一环,选项通常是:
| 方案 | 问题 |
|---|---|
| 邮件 | 容易进垃圾箱,不够即时 |
| 企业微信/钉钉机器人 | 要建群、要 webhook,个人用有点重 |
| Telegram | 国内网络不通 |
| Server 酱之类 | 免费额度有限,且是别人的服务 |
| ntfy | 一个 HTTP 接口,任何能发请求的地方都能用 |
ntfy 的核心设计极简:往一个 URL POST 一段文本,订阅了这个 topic 的所有设备都会收到。
curl -d "备份完成" https://ntfy.sh/my-backup-topic
就这一行。不需要注册账号、不需要 API key(公开 topic 情况下)。
二、先分清两种用法
用法 A:用官方托管(最快)
curl -d "测试消息" https://ntfy.sh/你的随机topic名
手机装 ntfy App → 订阅 你的随机topic名 → 收到。
注意:公开 topic 谁都能订阅、谁都能发。所以 topic 名要够随机(像密码一样),别用 test、backup 这种。
用法 B:自己搭(推荐)
自建的好处:
- topic 名不用藏,反正外网访问不了(或者要账号)
- 消息记录在你自己硬盘上
- 没有第三方能看到你的通知内容
- 可以接内网 webhook
下面主要讲自建。
三、部署:一条 docker 命令
mkdir -p /var/cache/ntfy && chown 1000:1000 /var/cache/ntfy
docker run -d \
--name ntfy \
--restart unless-stopped \
-p 8080:80 \
-v /var/cache/ntfy:/var/cache/ntfy \
binwiederhier/ntfy serve
/var/cache/ntfy 用来存消息缓存和附件,挂出来才不会随容器消失。
你应该看到
docker ps
CONTAINER ID IMAGE STATUS PORTS
xxxx binwiederhier/ntfy Up 10 seconds 0.0.0.0:8080->80/tcp
浏览器打开 http://你的机器IP:8080,能看到一个简洁的 Web 界面。
立刻测一条
curl -d "hello from terminal" http://你的机器IP:8080/mytest
浏览器打开 http://你的机器IP:8080/mytest 就能看到这条消息。
四、手机订阅
- 应用商店搜 ntfy(Android 在 Play/F-Droid 都有;iOS 在 App Store)
- 打开 App → Add subscription
- Topic name 填
mytest - Use another server → 填
http://你的机器IP:8080 - 订阅
之后任何发到 /mytest 的消息都会推到你手机。
iOS 自建必踩的坑
iOS 的推送必须经过苹果 APNs,第三方服务不能直连。所以 iOS 客户端连自建服务器时,消息要先经 ntfy 官方服务器中转。
需要在服务端配置(server.yml):
upstream-base-url: "https://ntfy.sh"
重启后,iOS 才能收到自建服务器的推送。这一步不配,iOS 端就是收不到,Android 却正常——很多人卡在这里以为服务坏了。
具体配置方式以官方文档「iOS instant notifications」章节为准,不同版本有差异。
五、把消息发得好看一点
ntfy 支持 HTTP header 控制标题、优先级、标签、点击跳转:
curl \
-H "Title: 备份完成" \
-H "Priority: high" \
-H "Tags: white_check_mark,floppy_disk" \
-H "Click: https://example.com/backup/2026-11-19" \
-d "3 个数据库,共 2.4 GB,用时 6 分 12 秒" \
http://你的机器IP:8080/backup
| Header | 作用 |
|---|---|
Title |
通知标题 |
Priority |
min/low/default/high/urgent,urgent 会绕过勿扰 |
Tags |
emoji 短代码或自定义标签 |
Click |
点通知打开的链接 |
Attach |
附件 URL |
Markdown |
yes 时正文按 Markdown 渲染 |
在各个脚本里怎么用
Shell(cron 任务):
#!/bin/bash
if pg_dump mydb > /backup/db.sql 2>/tmp/err; then
curl -H "Tags: white_check_mark" -d "数据库备份成功 $(du -h /backup/db.sql | cut -f1)" http://127.0.0.1:8080/backup
else
curl -H "Priority: urgent" -H "Tags: rotating_light" -d "备份失败:$(cat /tmp/err)" http://127.0.0.1:8080/backup
fi
Python:
import requests
requests.post("http://127.0.0.1:8080/backup",
data="任务完成".encode(),
headers={"Title": "爬虫跑完了", "Tags": "spider"})
Node:
await fetch("http://127.0.0.1:8080/backup", {
method: "POST",
body: "构建成功",
headers: { Title: "CI", Tags: "rocket" },
});
任何支持 webhook 的系统:填 http://你的机器IP:8080/topic 就行。
六、加访问控制(对外暴露必做)
默认情况下任何人都能往任意 topic 发消息、也能订阅。一旦映射到公网,必须加认证。
1. 建账号
docker exec -it ntfy ntfy user add --role=admin admin
# 按提示输入密码
2. 设权限
ntfy 的权限是 user + topic + 读写 的组合:
# 只允许 admin 读写 backup 这个 topic
docker exec -it ntfy ntfy access admin backup read-write
# 默认所有人对其它 topic 无权限
docker exec -it ntfy ntfy access everyone "*" deny
3. 带认证发送
curl -u admin:你的密码 -d "需要认证的消息" http://你的机器IP:8080/backup
或者用 access token(更适合脚本):
docker exec -it ntfy ntfy token add --label=backup-script admin
# 输出 tk_xxxxx,用它代替密码
curl -H "Authorization: Bearer tk_xxxxx" -d "消息" http://你的机器IP:8080/backup
token 比密码好:能单独撤销、能设过期、泄露了不影响账号。
4. 上 HTTPS
ntfy 自己能签证书,但生产环境更推荐放在 Nginx/Caddy 后面:
location / {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s; # 长连接,别设太短
}
proxy_read_timeout太短会导致订阅连接被 Nginx 掐断,表现为"手机偶尔掉线"。
七、六个常见报错
| 现象 | 原因 | 处理 |
|---|---|---|
| 手机收不到,网页能看 | iOS 没配 upstream-base-url;或 App 没开后台权限 |
见第四节;检查系统通知权限、电池优化白名单 |
| 手机隔一会儿就断开 | Nginx 超时太短 | proxy_read_timeout 3600s |
403 Forbidden |
topic 权限没给 | ntfy access <user> <topic> read-write |
401 Unauthorized |
没带 token/账号,或密码错 | 加 -H "Authorization: Bearer tk_..." |
| 中文乱码 | 用了 -d 但没指定编码 |
加 -H "Content-Type: text/plain; charset=utf-8" |
| 容器重启后消息没了 | 缓存目录没挂 | 确认 -v /var/cache/ntfy:/var/cache/ntfy |
八、它还顺手能干什么
- 当"脚本看门狗":所有 cron 任务失败都推一条 urgent
- 当内网告警:配合 Uptime Kuma 的 webhook 通知渠道(站内有监控那篇)
- 当跨设备剪贴板:手机发一条到 topic,电脑网页端复制
- 当自动化出口:n8n、Home Assistant、ESPHome 都能往里 POST
- 当"给自己发消息":临时要记的东西,curl 一下就到手机
九、出处与参考
- 官网/文档:https://docs.ntfy.sh/
- 源码仓库:https://github.com/binwiederhier/ntfy
- 安装文档(Docker/二进制/系统包):https://docs.ntfy.sh/install/
- 配置项全集:https://docs.ntfy.sh/config/
- 访问控制:https://docs.ntfy.sh/config/#access-control
- iOS 推送说明:https://docs.ntfy.sh/config/#ios-instant-notifications
- 镜像:
binwiederhier/ntfy(Docker Hub)
项目以 Apache-2.0 + GPL-2.0 双许可开源。命令在 2026-11 的官方镜像上验证;配置项名称以对应版本文档为准。
默认评论
Halo系统提供的评论