Ntfy搭建与权限管理教程

ntfy 是一款开源的基于 HTTP 的发布/订阅（Pub-Sub）通知服务。本教程基于 Docker Compose 部署，并开启了严格的鉴权模式（默认拒绝所有访问），适合对安全性有较高要求的私有云环境。

1. 部署准备与配置文件

首先，创建一个空目录用于存放 ntfy 的数据和配置文件：

1	mkdir -p /opt/ntfy && cd /opt/ntfy

在该目录下创建 docker-compose.yaml 文件，内容如下：

services:
  ntfy:
    image: binwiederhier/ntfy
    container_name: ntfy-service
    command:
      - serve
    environment:
      - TZ=Asia/Shanghai
      # 1. 基础访问配置
      # 【注意】请将下面的 URL 替换为你自己的实际域名或 IP+端口
      - NTFY_BASE_URL=[http://ntfy.example.com:80](http://ntfy.example.com:80)
      - NTFY_BEHIND_PROXY=false # 如果使用了 Nginx/Traefik 等反向代理则设为 true

      # 2. 鉴权核心配置
      - NTFY_AUTH_FILE=/var/lib/ntfy/auth.db
      - NTFY_AUTH_DEFAULT_ACCESS=deny-all # 核心安全配置：默认拒绝所有未经授权的读写请求

      # 3. 性能与限制
      - NTFY_WEB_PUSH=true
      - NTFY_CACHE_FILE=/var/cache/ntfy/cache.db
      - NTFY_ATTACHMENT_CACHE_DIR=/var/cache/ntfy/attachments
      - NTFY_ATTACHMENT_TOTAL_SIZE_LIMIT=1G
    volumes:
      - ./etc:/etc/ntfy
      - ./cache:/var/cache/ntfy
      - ./lib:/var/lib/ntfy
    ports:
      - 80:80
    restart: always
    deploy:
      resources:
        limits:
          memory: 128M
        reservations:
          memory: 16M

启动服务：

1	docker compose up -d

注意：由于我们配置了 NTFY_AUTH_DEFAULT_ACCESS=deny-all，现在服务虽然启动了，但任何人都无法发送或接收消息。我们必须立刻进入下一步：创建管理员和分配权限。

2. 权限字典说明（Permission Dictionary）

在进行用户授权之前，必须了解 ntfy 的权限级别。授权命令通常以字典格式分配权限：

read-write (或 rw)：读写权限。该用户可以订阅接收消息，也可以向该 Topic 发送消息。（适合真人用户、手机客户端）
read-only (或 ro)：只读权限。该用户只能订阅接收消息，不能发送。（适合仅用于接收通知的终端）
write-only (或 wo)：只写权限。该用户只能向该 Topic 发送消息，无法查看该 Topic 上的其他消息。（非常适合自动化脚本、探针、服务器报警程序，防止 Token 泄露导致消息被窃听）
deny (或 -)：明确拒绝访问。用于在某些通配符规则下，排除特定 Topic 的访问权。

3. 用户与权限管理操作指南

由于服务运行在 Docker 容器中，所有的管理命令都需要通过 docker exec 进入容器执行。

3.1 创建账号

创建管理员账号（默认拥有所有 Topic 的读写权限）：

1	docker exec -it ntfy-service ntfy user add --role=admin myadmin

创建普通用户（默认没有任何权限）：

1	docker exec -it ntfy-service ntfy user add alice

3.2 授权访问特定 Topic

场景 A：授权用户读写特定 Topic

1	docker exec -it ntfy-service ntfy access alice home_alerts read-write

场景 B：授权只写权限（适合服务器监控脚本）

1
2
3

# 创建机器人账号并授予只写权限
docker exec -it ntfy-service ntfy user add server_bot
docker exec -it ntfy-service ntfy access server_bot server_status write-only

场景 C：使用通配符批量授权

1	docker exec -it ntfy-service ntfy access alice "alice_*" read-write

4. Access Token (访问令牌) 管理

在自动化脚本（如 NAS 报警、服务器探针）中直接使用账号密码是非常不安全的。推荐为这些脚本生成 Access Token，如果 Token 泄露，随时可以撤销，而不影响你的主账号密码。

4.1 创建 Token

为用户 alice 创建一个永不过期的 Token：

1	docker exec -it ntfy-service ntfy token add alice

为用户 alice 创建一个 72 小时后过期的 Token（适合临时授权给第三方脚本）：

1	docker exec -it ntfy-service ntfy token add --expires 72h alice

命令执行后，会返回一串以 tk_ 开头的字符串，这就是你的 Token。

4.2 查看与删除 Token

查看某用户的所有 Token：

1	docker exec -it ntfy-service ntfy token list alice

删除/吊销特定 Token（发现泄露时使用）：

1	docker exec -it ntfy-service ntfy token del tk_xxxxxxxxxxxxxxxxxxxx

💡 提示：除了命令行，你也可以使用管理员账号登录 ntfy 的网页端（你的 NTFY_BASE_URL），在左下角的 “Account” 设置中可视化生成和管理 Token。

5. 客户端接入指南

由于开启了严格鉴权，你在任何设备上订阅或发送消息前，都必须先配置登录凭证。

网页端 (Web UI)：打开 http://ntfy.example.com:80，点击左下角的 🔑 图标（或 Account），输入你创建的用户名和密码登录。登录后即可在线订阅 Topic 和接收消息。
iOS / Android 移动端：
1. 在 App Store / Google Play 下载 ntfy 客户端。
2. 进入 App，点击 设置 (Settings) -> 用户 (Users/Servers)。
3. 添加新的服务器：输入你的服务器地址 http://ntfy.example.com:80。
4. 输入用户名和密码（或选择使用 Token 登录）。
5. 保存后，返回主界面订阅你在第 3 步授权过的 Topic（例如 home_alerts）。

6. 进阶消息推送实战 (结合鉴权与附件)

以下列举了使用 curl 命令推送消息的最佳实践。

6.1 使用 Token 发送基础消息 (推荐)

使用 HTTP Header 传递 Token，比 -u 传密码更安全：

1
2
3

curl -H "Authorization: Bearer tk_xxxxxxxxxxxxxxxxxxxx" \
     -d "这是一条来自服务器的报警测试" \
     [http://ntfy.example.com:80/server_status](http://ntfy.example.com:80/server_status)

6.2 发送富文本与高优先级报警

给消息加上标题 (Title)、标签 (Tags/Emoji) 和高优先级 (Priority)，并在手机端触发强烈震动/声音：

curl -H "Authorization: Bearer tk_xxxxxxxxxxxxxxxxxxxx" \
     -H "Title: 数据库宕机告警！" \
     -H "Priority: urgent" \
     -H "Tags: warning,skull" \
     -d "生产环境 MySQL 节点连接失败，请立即处理！" \
     [http://ntfy.example.com:80/server_status](http://ntfy.example.com:80/server_status)

6.3 发送图片/附件

你的配置文件中开启了附件支持。你可以直接将本地的图片或日志文件推送到手机端：

# 推送本地的一张监控截图
curl -H "Authorization: Bearer tk_xxxxxxxxxxxxxxxxxxxx" \
     -H "Title: 门口监控捕捉到移动" \
     -H "Filename: snapshot.jpg" \
     -T "/path/to/local/snapshot.jpg" \
     [http://ntfy.example.com:80/home_alerts](http://ntfy.example.com:80/home_alerts)

7. 常用命令速查表 (Cheat Sheet)

操作目标	命令
列出所有用户	`docker exec -it ntfy-service ntfy user list`
修改用户密码	`docker exec -it ntfy-service ntfy user change-pass <user>`
删除用户	`docker exec -it ntfy-service ntfy user del <user>`
查看全局权限表	`docker exec -it ntfy-service ntfy access`
授予权限(读写/只读/只写)	`docker exec -it ntfy-service ntfy access <user> <topic> rw/ro/wo`
重置/撤销某主题权限	`docker exec -it ntfy-service ntfy access <user> <topic> reset`
创建 Access Token	`docker exec -it ntfy-service ntfy token add <user>`
吊销 Access Token	`docker exec -it ntfy-service ntfy token del <token>`

欢迎访问我的小窝