首个验收目标是 Android 手机。服务器检查失败后,可以让监控脚本把一条 HTTPS 消息交给自建 ntfy,再由值班手机订阅指定主题。关键是先把证书、账号权限和手机后台分别验收,最后才接入故障检测;网页出现一条消息,并不能证明锁屏手机已经收到通知。
本文采用 Ubuntu 24.04 LTS、Docker Engine 与 Compose 插件,在独立新虚拟机上部署 ntfy 2.37.2 和 Caddy 2.11.9。版本根据 2026 年 11 月 11 日官方发布页核对,以下配置与命令是操作示例,需替换示例域名并按你的网络验收。ntfy 发布记录 · Caddy 发布记录
一、先确定通知链路和适用范围
ntfy 是消息转交通道,不能替代监控软件发现故障。本文最后用一个 HTTP 探测脚本演示故障和恢复通知;磁盘、备份任务或交换机告警,可以在现有监控程序的通知动作里使用同样的发布接口。
| 角色 | 本文安排 | 需要确认 |
|---|---|---|
| 通知服务器 | 独立 Ubuntu 虚拟机 | 不与待监控业务处于同一故障点 |
| HTTPS 入口 | Caddy 对外提供服务 | 域名、证书、网络连通 |
| 发布账号 | 只向一个主题写入 | 不能读取或访问其他主题 |
| 手机账号 | 只读取同一主题 | 不能发布假告警 |
| 探测位置 | 位于业务之外的监控节点 | 能访问目标,也能访问通知服务器 |
不要从生产服务器上直接开始试装。准备一台已安装 Docker Engine 与 Compose 插件的新虚拟机,普通运维账号可使用 sudo。Docker 安装按官方 Ubuntu 步骤完成,先确认以下命令都能正常返回。
sudo docker version
sudo docker compose version
curl --version
另需一个你控制的域名;本文用 alerts.example.com 作为占位符,不能原样申请证书。公网 DNS 的 A 记录指向入口地址;只有确实配置 IPv6 转发时才添加 AAAA。本文使用公网可信证书,因此 TCP 80、443 必须能够到达这台新虚拟机,服务器也要能访问证书签发服务。手机在移动网络下必须能访问该地址;若只做内网部署,则另行安排受信任证书、VPN 和移动网络可达性,不能照搬公网验收结论。
80/443 已被其他网站使用、DNS 不归你管理、或手机不能访问入口时,先停止,选择专用主机或协调既有代理;不要停掉现有网站,也不要把管理界面暴露出去。Docker 发布端口与主机防火墙的关系见官方说明;本文只发布代理端口,后端不映射主机端口。
二、创建配置,先把匿名访问关掉
在新虚拟机创建工作目录;如果目录已存在,先查清其用途,不覆盖旧部署。
mkdir -p "$HOME/ntfy-ops/config"
cd "$HOME/ntfy-ops"
umask 077
创建 compose.yml,保存以下内容。命名卷用于保留身份数据库、消息缓存和证书;容器重建不应抹掉这些数据。ntfy Docker 安装说明
name: ntfy-ops
services:
ntfy:
image: binwiederhier/ntfy:v2.37.2
command: ["serve"]
restart: unless-stopped
volumes:
- ./config:/etc/ntfy:ro
- ntfy_data:/var/lib/ntfy
- ntfy_cache:/var/cache/ntfy
caddy:
image: caddy:2.11.9-alpine
restart: unless-stopped
depends_on:
- ntfy
ports:
- "80:80"
- "443:443"
volumes:
- ./Caddyfile:/etc/caddy/Caddyfile:ro
- caddy_data:/data
- caddy_config:/config
volumes:
ntfy_data:
ntfy_cache:
caddy_data:
caddy_config:
创建 config/server.yml。先把域名替换为真实入口;默认拒绝可防止“知道主题名就能读写”,身份文件放在持久卷中。缓存示例保留 12 小时,它只帮助短暂离线补取,不能充当告警审计库。配置参数
base-url: "https://alerts.example.com"
listen-http: ":80"
behind-proxy: true
auth-file: "/var/lib/ntfy/user.db"
auth-default-access: "deny-all"
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
upstream-base-url: ""
创建 Caddyfile;两个文件中的域名必须一致。反向代理按容器服务名访问后端,不能写成本容器的回环地址。Caddy 自动处理 HTTPS 和流式连接,本文不额外套一层 Basic Auth,以免与 ntfy 身份认证冲突。自动 HTTPS · 反向代理
alerts.example.com {
reverse_proxy ntfy:80
}
先检查 Compose 语法并拉取镜像,此时还不开放服务。
sudo docker compose config --quiet
sudo docker compose pull
三、建立发布和订阅两个账号
在同一工作目录运行下面命令。创建账号时按终端提示交互输入两组不同的强密码,不在命令行、截图或文章中写出密码。账号默认是普通用户,不要改为管理员。ops-alerts 是本例的主题名,若更名必须同步修改 ACL、手机订阅和脚本。账号实现 · ACL 命令定义
sudo docker compose run --rm --no-deps ntfy user add ops-publisher
sudo docker compose run --rm --no-deps ntfy user add ops-reader
sudo docker compose run --rm --no-deps ntfy access ops-publisher ops-alerts write-only
sudo docker compose run --rm --no-deps ntfy access ops-reader ops-alerts read-only
sudo docker compose run --rm --no-deps ntfy access
检查权限列表:发布账号仅有本主题写权限,手机账号仅有本主题读权限,其他访问默认拒绝。若已有同名用户,先核查旧状态,不盲目删除重建。确认正确后启动,并检查日志和 HTTPS 健康接口。
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=80 ntfy caddy
curl --fail-with-body --connect-timeout 5 --max-time 15 \
https://alerts.example.com/v1/health
健康接口应返回健康状态,但它不代表主题允许匿名访问。证书错误应先修正 DNS、时间或证书链;不能用跳过 TLS 校验继续验收。Caddy 报端口冲突或证书签发失败时,先停止接入业务。
四、订阅手机,再逐项验证权限
从官方入口安装 Android 或 iOS 应用。添加自定义服务器地址,填写完整 HTTPS 入口、主题 ops-alerts,并在应用对应服务器的账号设置中添加 ops-reader 凭据;具体菜单名可能随应用版本变化。不要把只写账号交给订阅端。
Android 允许通知,并确认自建服务器订阅使用的即时投递/订阅后台服务处于开启状态;同时检查系统对该应用的电池限制和后台联网许可。Android 的自建服务器通常依靠持续连接,不能把官方公共服务器的推送行为直接套用到私有服务器。
iPhone 的后台即时通知还需要上游唤醒服务。主配置将上游显式留空;若组织允许依赖公共推送链路,将该行改为以下设置后重启 ntfy。上游收到主题 URL 哈希和消息 ID 等唤醒元数据,正文由手机回到自建服务器读取;仍需评估第三方依赖及合规要求。手机必须能访问自建入口,VPN 断开或内网地址不可达时,上游唤醒也无法解决取消息问题。纯内网、无外部推送链路不能承诺 iOS 锁屏即时送达。iOS 官方说明
upstream-base-url: "https://ntfy.sh"
先由发布账号发送一条无敏感内容的测试消息。curl 只给出用户名,会交互询问密码;使用 HTTPS,且不要打开 shell 调试输出。
curl --fail-with-body --connect-timeout 5 --max-time 15 \
--user ops-publisher \
--header 'Title: ntfy smoke test' \
--header 'Priority: default' \
--data-binary 'SMOKE-001: verify the phone notification and timestamp' \
https://alerts.example.com/ops-alerts
记下手机实际到达时间与消息标识。再做四项拒绝检查:匿名发布、读账号发布、写账号读取,以及读账号读取另一个未授权主题,都必须被拒绝,预期出现 401/403 一类拒绝状态。最后由读账号查询本主题缓存,应找到本次测试标识。发布接口 · 订阅 API
curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \
--data-binary 'ANONYMOUS-DENY-TEST' \
https://alerts.example.com/ops-alerts
curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \
--user ops-reader --data-binary 'READER-DENY-TEST' \
https://alerts.example.com/ops-alerts
curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \
--user ops-publisher 'https://alerts.example.com/ops-alerts/json?poll=1'
curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' \
--user ops-reader 'https://alerts.example.com/another-topic/json?poll=1'
curl --fail-with-body --user ops-reader \
'https://alerts.example.com/ops-alerts/json?poll=1'
至少覆盖前台、锁屏静置后、移动网络,以及暂时离线再联网四种场景;分别记录发送与到达时间。缓存补取不等于实时投递。若接口发布成功而锁屏不响,先查系统通知权限、频道声音、勿扰模式和后台连接,不要先撤销鉴权。做过权限拒绝测试,才能证明账号隔离有效。
五、接入故障检测:只在状态变化时通知
以下示例在本文中未作真实部署或手机端实测,请先在测试环境演练。例子放在独立 Linux 监控节点;其任务是定时请求业务健康 URL,而不是在通知服务器上安装业务。该节点需要 curl、Python 3 和 systemd。示例 URL 必须换成你自己可控、无副作用的健康接口;HTTP 200 也需能代表业务真正健康。先以无敏感数据的测试目标演练。
自动任务不能等候输入密码。用受限配置文件保存本主题的只写账号,并交互输入密码;文件存在时命令拒绝覆盖。此文件属于凭据,应纳入你的密钥管理及轮换流程,不上传 Git 或文章附件。
sudo python3 - <<'PYSECRET'
import getpass, json, os
password = getpass.getpass('ntfy publisher password: ')
if not password or any(ord(ch) < 32 for ch in password):
raise SystemExit('Password must be nonempty and contain no control characters')
fd = os.open('/etc/ntfy-monitor.curl', os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
with os.fdopen(fd, 'w') as stream:
stream.write('user = ' + json.dumps('ops-publisher:' + password, ensure_ascii=False) + '\n')
PYSECRET
先在监控节点另一终端创建一个空的临时目录,在该目录运行只绑定本机的演练 HTTP 服务;18080 如被占用,先换空闲端口,不停止占用者。这个服务只用于制造故障与恢复,不承载真实业务。
mkdir -p "$HOME/ntfy-probe-demo"
cd "$HOME/ntfy-probe-demo"
python3 -m http.server 18080 --bind 127.0.0.1
创建 /usr/local/sbin/ntfy-http-check,先替换通知 URL,探测 URL 暂保留本机演练地址。首次发现故障会通知,持续故障不重复刷屏;恢复后发送恢复通知。探测仅把 HTTP 200 认作正常,重定向、其他状态及连接错误均视为故障;发布仅接受 2xx,不跟随重定向。状态只在通知确认成功后更新,失败在下一次检查重试,因此这仍不是保证仅投递一次的队列。
#!/usr/bin/env bash
set -eu
probe_url='http://127.0.0.1:18080/'
notify_url='https://alerts.example.com/ops-alerts'
state_dir='/var/lib/ntfy-http-check'
state_file="$state_dir/state"
install -d -m 700 "$state_dir"
old='unknown'
if [ -f "$state_file" ]; then
old=$(cat "$state_file")
fi
current='down'
if probe_code=$(curl --silent --show-error --output /dev/null \
--write-out '%{http_code}' --connect-timeout 5 --max-time 15 "$probe_url"); then
if [ "$probe_code" = '200' ]; then
current='up'
fi
fi
if [ "$current" = "$old" ]; then
exit 0
fi
if [ "$current" = 'down' ] || [ "$old" = 'down' ]; then
if ! notify_code=$(curl --config /etc/ntfy-monitor.curl --silent --show-error \
--output /dev/null --write-out '%{http_code}' \
--connect-timeout 5 --max-time 15 \
--header "Title: HTTP service $current" \
--data-binary "HTTP probe state: $current; check the monitoring console." \
"$notify_url"); then
exit 1
fi
case "$notify_code" in
2??) ;;
*) printf 'Notification rejected: HTTP %s\n' "$notify_code" >&2; exit 1 ;;
esac
fi
printf '%s\n' "$current" > "$state_file"
设置脚本归属为 root、权限为 0750,再创建 /etc/systemd/system/ntfy-http-check.service 和同名 .timer。这里每分钟检查一次;只发送状态变化通知。不要将“端口存活”写成完整业务验收。
# /etc/systemd/system/ntfy-http-check.service
[Unit]
Description=HTTP probe with ntfy state-change notification
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/ntfy-http-check
# /etc/systemd/system/ntfy-http-check.timer
[Unit]
Description=Run HTTP probe once a minute
[Timer]
OnBootSec=1min
OnUnitActiveSec=1min
AccuracySec=1s
Unit=ntfy-http-check.service
[Install]
WantedBy=timers.target
执行权限和启动检查:
sudo chown root:root /usr/local/sbin/ntfy-http-check
sudo chmod 750 /usr/local/sbin/ntfy-http-check
sudo systemctl daemon-reload
sudo systemctl start ntfy-http-check.service
sudo systemctl enable --now ntfy-http-check.timer
sudo systemctl list-timers ntfy-http-check.timer
sudo journalctl -u ntfy-http-check.service -n 30 --no-pager
保持演练 HTTP 服务运行时,首次执行仅建立正常基线,不发成功消息。在演练终端按 Ctrl+C 停止该临时服务,等待下一轮检查,应收到 down 通知;再用相同命令启动演练服务,下一轮应收到 up 恢复通知。持续故障不应每分钟重复提醒。演练通过后,停止 timer,把探测 URL 改成真实业务的健康接口,再手动执行服务并重新启用 timer。不要为验证告警停掉生产业务。然后检查错误密码、通知入口不可达时的任务失败记录。告警服务器与被监控业务同机、同电源或同出口时,故障可能连通知一起带走,应安排独立的外部存活检查和备用联络方式。
Raspberry Pi 4 Model B 设备实拍:Laserlicht / Wikimedia Commons,CC BY-SA 4.0;等比缩小并转为 WebP,衍生图沿用同一许可。第三方设备照片,非本文现场,只说明小型设备形态,不证明本教程已在该设备部署。
六、问题定位、维护与回退
| 现象 | 先检查 | 何时停止扩大接入 |
|---|---|---|
| HTTPS 不通或证书无效 | DNS/AAAA、入口端口、时间、Caddy 日志 | 未取得可信证书前不发凭据 |
| 发布被拒绝 | 账号密码、主题拼写、ACL 写权限 | 不为排障开放匿名读写 |
| 手机能查历史但锁屏不提醒 | 后台连接、通知频道、iOS 上游和网络 | 锁屏与移动网络未通过前不当值班主通道 |
| 监控显示成功但没有业务告警 | 探测是否真正失败、是否已是相同状态 | 不清空状态来掩盖逻辑问题 |
| 重建后账号或缓存消失 | 命名卷、工作目录、Compose 项目名 | 未恢复身份库前不重新开放服务 |
定期备份 Compose、配置和持久卷。SQLite 身份库与缓存应在停止本套容器后做一致性备份,恢复后重新跑匿名拒绝、账号隔离和手机测试;不要把运行中的数据库文件随手复制就当成恢复保障。配置含域名,身份数据库、证书卷及脚本凭据按敏感数据保护。
暂停演练时,只停止本例的 timer;需要下线新部署时,在本文目录执行本项目的 Compose 停止命令。不要加删除卷参数,保留数据以便核查及恢复。
sudo systemctl disable --now ntfy-http-check.timer
cd "$HOME/ntfy-ops"
sudo docker compose down
FAQ
返回成功响应,为什么不能认定手机已经收到? 服务端接受消息、手机获取消息、系统显示通知是不同环节。验收必须看本次标识在真实手机上的到达时间。
能否只用复杂主题名,不创建账号? 企业告警不应依赖名字保密。本文默认拒绝,分别给写入端和读取端最小权限。
能否在通知里放数据库密码和完整日志? 不要。通知保留故障对象代号、严重程度与排查入口;详细信息留在受控监控平台,避免锁屏、缓存和第三方链路扩散敏感内容。
iPhone 纯内网能保证即时提醒吗? 本文没有这种保证。官方应用的后台即时路径依赖上游唤醒和手机回连;不能满足网络和第三方要求时,应选择组织已验证的其他通知通道。
相关解决方案与相关阅读
已有监控平台时,可先评估煜企 IT 运维服务的告警分级、主备通道和恢复演练安排,再决定是否纳入值班主通道。
如需企业环境落地,可带上网络边界、手机系统、告警量和现有监控方式,与煜企确认适用方案。



