hermes教程-ntfy - 字节笔记本

ntfy

ntfy 是一个基于 HTTP 的简单发布-订阅通知服务。它可以使用 ntfy.sh 上的免费公共服务器，也可以使用任何自托管实例，并支持任何能够发出 HTTP 请求的客户端——手机、浏览器、脚本、手表。

ntfy 是 Hermes 的一个很好的轻量级推送通道：从 ntfy 移动应用订阅一个主题，向该主题发送消息与代理对话，然后在手机上收到回复。

运行 hermes gateway setup 并选择 ntfy 以获得引导式操作指南。

先决条件

一个主题名称（任何唯一字符串——例如 hermes-myname-2026）
已安装 ntfy 移动应用并订阅了该主题
可选：自托管的 ntfy 服务器，或用于私有/保留主题的 ntfy.sh 账户令牌

仅此而已。无需 SDK、守护进程或 Node.js。该适配器使用 httpx，它已经是 Hermes 的依赖项。

配置 Hermes

通过设置向导

bash

hermes gateway setup

选择 ntfy 并按照提示操作。

通过环境变量

将这些添加到 ~/.hermes/.env：

text

NTFY_TOPIC=hermes-myname-2026
NTFY_ALLOWED_USERS=hermes-myname-2026
NTFY_HOME_CHANNEL=hermes-myname-2026

变量	必需	描述
`NTFY_TOPIC`	是	要订阅的主题（传入消息）
`NTFY_SERVER_URL`	可选	服务器 URL（默认：`https://ntfy.sh`）——指向自托管的 ntfy 以保护隐私
`NTFY_TOKEN`	可选	Bearer 令牌（例如 `tk_xyz`）或用于 Basic 认证的 `user:pass`
`NTFY_PUBLISH_TOPIC`	可选	用于传出回复的不同主题（默认为 `NTFY_TOPIC`）
`NTFY_MARKDOWN`	可选	设置为 `true` 以发送带有 `X-Markdown: true` 头的回复
`NTFY_ALLOWED_USERS`	推荐	允许的主题名称列表（逗号分隔，视为用户 ID；见下文）
`NTFY_ALLOW_ALL_USERS`	可选	设置为 `true` 以允许所有发布者——仅对使用读取令牌的私有主题安全
`NTFY_HOME_CHANNEL`	可选	用于 cron / 通知投递的默认主题
`NTFY_HOME_CHANNEL_NAME`	可选	主频道的人类可读标签

身份模型——部署前请阅读

ntfy 没有原生的经过身份验证的用户身份。已发布消息的 title 字段是发布者控制的，可以是发送者想要的任何内容。Hermes 适配器不使用 title 进行授权——否则任何知道该主题的发布者都可以冒充允许的用户。

相反，主题名称本身就是身份。发布到该主题的每条消息都被视为来自同一个逻辑用户（即该主题）。因此，NTFY_ALLOWED_USERS 通常只是主题名称本身——一个单条目的允许列表，用于控制整个通道的访问。

这意味着任何知道该主题的人都可以与代理对话。要使其成为真正的信任边界：

自托管 ntfy 并使用访问控制锁定主题。只有拥有读/写令牌的授权客户端才能发布。
或者在 ntfy.sh 上使用私有主题（保留主题需要账户）并用 NTFY_TOKEN 保护它。
或者选择一个长且不可猜测的主题名称（例如 hermes-7d4f9c8b-2026）并将其视为共享密钥。这是最轻量的设置，但主题名称会通过任何日志或截图泄露。

在所有情况下，除非底层主题受访问控制，否则不要通过 ntfy 发送敏感数据。

快速开始——从手机与代理对话

选择一个主题名称：hermes-myname-2026
在手机上：安装 ntfy 应用，点击 +，输入 hermes-myname-2026

在主机上：

bash

echo 'NTFY_TOPIC=hermes-myname-2026' >> ~/.hermes/.env
echo 'NTFY_ALLOWED_USERS=hermes-myname-2026' >> ~/.hermes/.env
hermes gateway restart

从 ntfy 应用向该主题发送一条消息。代理的回复将以推送通知的形式送达。

将 ntfy 与 cron 作业一起使用

一旦设置了 NTFY_HOME_CHANNEL，cron 作业就可以投递到 ntfy：

python

cronjob(
    action="create",
    schedule="every 1h",
    deliver="ntfy",          # 使用 NTFY_HOME_CHANNEL
    prompt="检查警报并总结。"
)

或者显式指定特定主题：

python

send_message(target="ntfy:alerts-channel", message="完成！")

即使 cron 在网关进程外运行，这也有效——插件注册了一个 standalone_sender_fn，它会打开自己的 HTTP 连接。

自托管 ntfy

如果你想要完全控制：

bash

## Docker
docker run -p 80:80 -it binwiederhier/ntfy serve
## 原生安装
go install heckel.io/ntfy/v2@latest
ntfy serve

然后将 Hermes 指向它：

text

NTFY_SERVER_URL=https://ntfy.mydomain.com
NTFY_TOPIC=hermes
NTFY_TOKEN=tk_abc123  # 如果你设置了访问控制

自托管为你提供主题访问控制、消息持久化策略、附件和表情符号标签。请参阅 ntfy 服务器文档。

Markdown 格式化

当发布者设置 X-Markdown: true 头时，ntfy 客户端会渲染 Markdown。要为 Hermes 的传出回复启用此功能：

NTFY_MARKDOWN=true

或者在 config.yaml 中：

yaml

platforms:
  ntfy:
    extra:
      markdown: true

移动应用支持 CommonMark 的子集——粗体、斜体、列表、链接、围栏代码块。请参阅 ntfy 的 Markdown 文档了解确切支持集。

仅传出设置（无入站的通知）

如果你只希望 Hermes 推送通知到 ntfy（cron 摘要、警报），并且从不接受返回的消息，请将 NTFY_TOPIC 和 NTFY_PUBLISH_TOPIC 设置为相同的值，并完全跳过 NTFY_ALLOWED_USERS。没有允许列表，代理永远不会响应入站消息——你的手机会收到推送，但对话是单向的。

限制

消息大小：ntfy 将消息正文限制为 4096 个字符。Hermes 在超出时会截断并发出警告。
无输入指示器：协议不提供此功能；send_typing 是空操作。
无线程或附件：ntfy 是纯推送通知。长回复保留在消息正文中，没有线程展开。
无原生用户身份：请参阅上面的身份模型部分。

故障排除

认证失败 / 401——NTFY_TOKEN 错误，或者该令牌没有此主题的发布/订阅权限。适配器在收到 401 时会停止其重连循环，网关运行时状态将显示 fatal: ntfy_unauthorized。修复令牌并重启网关。

主题未找到 / 404——NTFY_TOPIC 在配置的服务器上不存在。对于 ntfy.sh，主题在首次发布时自动创建，因此 404 意味着你指向了一个没有预配该主题的自托管服务器。适配器会停止其重连循环，并显示 fatal: ntfy_topic_not_found。

已连接但无消息——检查 NTFY_ALLOWED_USERS 是否包含主题名称本身。根据 ntfy 的身份模型，主题就是用户；将允许列表留空会拒绝所有内容。

每 60 秒重新连接——流保活默认值为 55 秒；ntfy 可能存在间歇性网络问题。适配器应用指数退避（2 → 5 → 10 → 30 → 60 秒），并在流保持存活 ≥60 秒后重置为 0。