企业官网建设流程全解析

ntfy 如何启用访问控制、限制匿名访问并创建用户与访问令牌

【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy

默认情况下，ntfy 服务器对所有人开放，任何人可以读写任意 topic。如果你在自己的服务器上部署了 ntfy，并希望只有指定用户能访问自己的 topic、匿名请求被拒绝，就需要启用 ntfy 自带的认证与访问控制（ACL）。本文基于仓库中的 配置文档 与 发布文档，给出一条可操作的完整路径：开启访问控制 → 限制匿名访问 → 创建用户 → 分配 topic 权限 → 创建访问令牌 → 验证认证请求是否生效。

前提：你已经在服务器上运行了 ntfy（例如通过包安装或 Docker），并且拥有在服务器上执行ntfyCLI 命令的权限。ntfy user、ntfy access、ntfy token这些命令直接编辑认证数据库，只能在服务器上执行，且操作者需要有相应权限。

第一步：启用访问控制

在/etc/ntfy/server.yml（或等价的配置来源）中配置以下两个选项，重启后认证即生效：

auth-file: "/var/lib/ntfy/user.db" auth-default-access: "deny-all"

• auth-file：用户/访问数据库（SQLite），文件不存在时会自动创建；文档建议放在/var/lib/ntfy/user.db（使用 deb/rpm 包时最省事）。设置该选项即启用认证。
• auth-default-access：找不到匹配 ACL 条目时的兜底权限，可选read-write（默认）、read-only、write-only、deny-all。默认值是read-write，意味着即使开了认证，匿名请求仍可以读写所有 topic；要限制匿名访问，必须显式设为deny-all。

另外，如果配置了database-url（PostgreSQL），认证会自动启用，此时不应再设置auth-file。

对应的环境变量形式为NTFY_AUTH_FILE和NTFY_AUTH_DEFAULT_ACCESS，适合 Docker Compose 场景：

services: ntfy: image: binwiederhier/ntfy restart: unless-stopped environment: NTFY_AUTH_FILE: /var/lib/ntfy/auth.db NTFY_AUTH_DEFAULT_ACCESS: deny-all

注意：Docker 部署时auth.db位于容器内，重启后用户数据会丢失；如需持久化，应将/var/lib/ntfy/auth.db挂载为 volume（即文档中给出的NTFY_AUTH_FILE: /var/lib/ntfy/auth.db配合卷挂载的用法）。

第二步：创建用户

有两种方式：CLI 手动创建，或在配置文件中声明式创建。

方式一：用ntfy user命令（手动）

ntfy user add phil # 添加普通用户 phil ntfy user add --role=admin phil # 添加管理员用户 phil ntfy user list # 查看用户列表 ntfy user change-pass phil # 修改密码 ntfy user change-role phil admin # 提升为管理员 ntfy user del phil # 删除用户

ntfy 只有两个角色：

• user（默认）：无特殊权限，需要用ntfy access逐条管理 topic 访问；
• admin：可以读写所有topic，无需再配置 ACL 条目。实际使用中通常创建一个 admin 用户就够了。

方式二：在配置文件中声明（auth-users）

适合 Docker/Ansible 等自动化部署场景。用户条目格式为<username>:<password-hash>:<role>，服务启动时自动创建/更新：

auth-file: "/var/lib/ntfy/user.db" auth-users: - "phil:$2a$10$YLiO8U21sX1uhZamTLJXHuxgVC0Z/GKISibrKCLohPgtG7yIxSk4C:admin" - "ben:$2a$10$NKbrNb7HPMjtQXWJ0f1pouw03LDLT/WzlO9VAv44x84bRCkh19h6m:user"

上面的 bcrypt 哈希值来自文档示例，必须替换为你自己生成的值：用ntfy user hash生成密码哈希后填入。

两个必须知道的限制：

• 通过配置声明的用户在数据库中被标记为 "provisioned users"，从配置中移除该用户后，下次重启 ntfy 会将其从数据库中删除；
• 原本手动创建的用户一旦加入配置，也会被"升级"为 provisioned user，之后再从配置中删除同样会导致用户被删。

环境变量形式为NTFY_AUTH_USERS，多个用户用逗号分隔（bcrypt 哈希含特殊字符，务必加引号）。

第三步：配置 topic 级访问权限（ACL）

ACL 管理非 admin 用户以及**匿名访问（everyone/*）**对各个 topic 的权限。权限值有四种：

topic 支持通配符*（匹配零到任意多个字符），例如alerts_*、ben-*。

CLI 方式：ntfy access命令

ntfy access # 显示完整 ACL ntfy access phil # 查看 phil 的访问条目 ntfy access phil mytopic rw # 允许 phil 读写 mytopic ntfy access everyone mytopic rw # 允许匿名读写 mytopic ntfy access everyone "up*" write # 允许匿名对 up 开头的 topic 只写 ntfy access --reset # 重置整个 ACL

USERNAME可以是ntfy user add创建的用户，也可以是everyone或*（代表不带用户名/密码访问 API 的客户端）。

配置方式：auth-access条目

条目格式<username>:<topic-pattern>:<access>，启动时自动创建/更新，移除条目会从数据库删除：

auth-access: - "phil:mytopic:rw" - "ben:alerts-*:rw" - "ben:system-logs:ro" - "*:announcements:ro" # 匿名只读 announcements

用ntfy access命令查看结果，输出形如（文档示例）：

user phil (admin) - read-write access to all topics (admin role) user ben (user) - read-write access to topic garagedoor - read-write access to topic alerts* - read-only access to topic furnace user * (anonymous) - read-only access to topic announcements - no access to any (other) topics (server config)

注意最后一行的(server config)：当auth-default-access为deny-all时，匿名客户端对所有未显式允许的 topic 一律拒绝。

第四步：创建访问令牌

访问令牌（access token）用于 API 认证，适合不想把账户密码配到每个发布/订阅应用里的场景——例如给备份主机发一个专用 token，给家庭自动化系统发另一个。文档提示：目前 token 等同于对应用户的完全访问权限（除改密码和删账号外，所有操作都能用 token 执行），细粒度 token 尚未实现。

CLI 命令：

ntfy token list # 列出所有用户的 token ntfy token list phil # 列出 phil 的 token ntfy token add phil # 创建永不过期的 token ntfy token add --expires=2d phil # 创建 2 天后过期的 token ntfy token remove phil tk_th2sxr... # 删除 token ntfy token generate # 生成随机 token（用于 auth-tokens 配置项）

每个用户最多 60 个 token（硬编码限制）。文档示例的创建输出（文档示例）：

$ ntfy token add --expires=30d --label="backups" phil $ ntfy token list user phil - tk_7eevizlsiwf9yi4uxsrs83r4352o0 (backups), expires 15 Mar 23 14:33 EDT, accessed from 0.0.0.0 at 13 Feb 23 13:33 EST

也可以用配置文件预置 token（auth-tokens，格式<username>:<token>[:<label>]，token 必须以tk_开头且总长 32 字符，可用ntfy token generate生成）。或者登录网页端后，在Account页面的 "Access tokens" 区域点CREATE ACCESS TOKEN创建，填写 Label 并选择过期时间。下图为文档中的界面示例：

第五步：验证认证是否生效

配置完成后，文档给出两类验证请求，均假设使用示例用户phil（密码mypass），请替换为你自己的用户名、密码和服务器地址。

用户名/密码（Basic Auth）发布：

curl \ -u phil:mypass \ -d "Look ma, with auth" \ https://ntfy.example.com/mysecrets

或者 ntfy CLI：

ntfy publish \ -u phil:mypass \ ntfy.example.com/mysecrets \ "Look ma, with auth"

访问令牌（Bearer Auth）发布：

curl \ -H "Authorization: Bearer tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2" \ -d "Look ma, with auth" \ https://ntfy.example.com/mysecrets

或者：

ntfy publish \ --token tk_AgQdq7mVBoFD37zQVN29RhuMzNIz2 \ ntfy.example.com/mysecrets \ "Look ma, with auth"

curl 也可以走 Basic Auth 的简化写法：发送空用户名时，密码字段会被服务器当作 access token 处理，即curl -u:tk_xxx ...。

验证逻辑是：

• 带凭据的请求应成功发布（HTTP 返回中包含 id/time）；
• 不带凭据的匿名请求，对auth-default-access: deny-all且未被 ACL 显式放行的 topic 应被拒绝（订阅端表现为Not authorized (401/403)，手机应用文档 给出的解释是"用户名/密码不正确，或访问凭据已过期"）；
• 被 ACL 显式放行的匿名 topic（如上面的*:announcements:ro）仍可匿名只读。

由于认证时密码以明文传输，文档明确建议务必使用 HTTPS，避免被窃听。

一个完整的私有实例配置

把上面各步合起来的server.yml示例（文档"Example: Private instance"，密码哈希为文档示例值）：

auth-file: "/var/lib/ntfy/user.db" auth-default-access: "deny-all" auth-users: - "phil:$2a$10$YLiO8U21sX1uhZamTLJXHuxgVC0Z/GKISibrKCLohPgtG7yIxSk4C:admin" - "backup-script:$2a$10$/ehiQt.w7lhTmHXq.RNsOOkIwiPPeWFIzWYO3DRxNixnWKLX8.uj.:user" auth-access: - "backup-script:backups:rw" auth-tokens: - "phil:tk_3gd7d2yftt4b8ixyfe9mnmro88o76:My personal token"

效果：admin 用户phil可读写全部 topic；普通用户backup-script只能读写backupstopic；其余用户和匿名访问全部被deny-all拒绝。

限制与注意事项

• 访问 token 拥有该用户账户的完全访问权限（除改密码和删账号外），不要按 topic 隔离敏感场景；细粒度 token 在文档中仅标记为 roadmap。
• 声明式用户/ACL/token（auth-users、auth-access、auth-tokens）都是"配置即事实"：从配置中删掉条目，重启后对应数据库条目会被删除。修改配置前先确认。
• ntfy access --reset会重置整个 ACL 或指定用户的 ACL，执行前建议先用ntfy access查看当前条目。
• 若你的服务器启用了 UnifiedPush，文档指出在auth-default-access: "deny-all"的私有服务器上，需要额外配置才能使用 UnifiedPush，详见 配置文档。
• 完整的配置项说明（含auth-access-cache等）见 docs/config.md 的 "Access control" 章节与配置项表；发布/订阅时的认证细节（Basic Auth 的 base64 构造、authURL 参数等）见 docs/publish.md。

【免费下载链接】ntfySend push notifications to your phone or desktop using PUT/POST项目地址: https://gitcode.com/GitHub_Trending/nt/ntfy