H繁中版
文件訊息平台ntfy
<!-- Source: https://hermesbible.com/docs/user-guide/messaging/ntfy -->

Section: Messaging Platforms · URL: https://hermesbible.com/docs/user-guide/messaging/ntfy

ntfy

ntfy 是一個簡單的 HTTP 訂閱制通知服務。它可搭配免費的公共伺服器 ntfy.sh 使用，也支援任何自架實例，並且相容所有能發送 HTTP 請求的客戶端——手機、瀏覽器、腳本、智慧手錶都行。

ntfy 非常適合作為 Hermes 的輕量級推播管道：在 ntfy 手機應用程式 訂閱一個主題，向該主題發送訊息即可與智慧體互動，回覆會直接推播到你的手機上。

執行 hermes gateway setup 並選擇 ntfy，即可透過引導式設定快速完成。

前置需求

  • 一個主題名稱（任意唯一字串即可，例如 hermes-myname-2026）
  • 已安裝 ntfy 手機應用程式 並訂閱該主題
  • 選用：自架 ntfy 伺服器，或 ntfy.sh 的帳號令牌（token），用於私密/保留主題

就這樣。不需要 SDK、不需要常駐程式、不需要 Node.js。適配器使用的是 httpx，它已經是 Hermes 的依賴項。

設定 Hermes

透過設定精靈

hermes gateway setup

選擇 ntfy 並依照提示操作。

透過環境變數

將以下內容加入 ~/.hermes/.env：

NTFY_TOPIC=hermes-myname-2026
NTFY_ALLOWED_USERS=hermes-myname-2026
NTFY_HOME_CHANNEL=hermes-myname-2026
變數必要說明
NTFY_TOPIC是要訂閱的主題（接收訊息）
NTFY_SERVER_URL選用伺服器網址（預設：https://ntfy.sh）——可指向自架的 ntfy 以確保隱私
NTFY_TOKEN選用Bearer 令牌（例如 tk_xyz）或 user:pass 格式的 Basic 認證
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 欄位由發布者自行控制，可以填入任意內容。Hmes 適配器不會使用 title 進行授權——否則任何知道主題名稱的發布者都能偽裝成已授權的使用者。

因此，主題名稱本身就是身分識別。所有發布到該主題的訊息都會被視為來自同一個邏輯使用者（即該主題）。所以 NTFY_ALLOWED_USERS 通常只需填入主題名稱本身——這是一個單一條目的允許清單，用來控管整條管道的存取權限。

這代表任何知道主題名稱的人都能與智慧體對話。若要建立真正的信任邊界：

  • 自架 ntfy 並透過 存取控制 鎖定主題。只有持有讀取/寫入令牌的已授權客戶端才能發布。
  • 或在 ntfy.sh 上使用私密主題（保留主題 需要帳號），並以 NTFY_TOKEN 加以保護。
  • 或選用一個長且無法猜測的主题名稱（例如 hermes-7d4f9c8b-2026），將其視為共享密鑰。這是最簡便的設定方式，但主題名稱可能透過任何日誌或截圖洩漏。

不論採用何種方式，除非底層主題有存取控制，否則請勿透過 ntfy 傳送敏感資料。

快速開始——從手機與你的智慧體對話

  1. 選擇一個主題名稱：hermes-myname-2026
  2. 在手機上：安裝 ntfy 應用程式，點選 +，輸入 hermes-myname-2026
  3. 在主機上： 
    echo 'NTFY_TOPIC=hermes-myname-2026' >> ~/.hermes/.env
echo 'NTFY_ALLOWED_USERS=hermes-myname-2026' >> ~/.hermes/.env
hermes gateway restart
  4. 在 ntfy 應用程式中向該主題發送訊息。智慧體的回覆會以推播通知的形式送達。

搭配 cron 排程任務使用

設定 NTFY_HOME_CHANNEL 後，cron 排程任務即可將結果傳送至 ntfy：

cronjob(
    action="create",
    schedule="every 1h",
    deliver="ntfy",          # uses NTFY_HOME_CHANNEL
    prompt="Check for alerts and summarise."
)

或明確指定特定主題：

send_message(target="ntfy:alerts-channel", message="Done!")

即使 cron 與網關在不同行程中運作，此功能依然有效——外掛會註冊一個 standalone_sender_fn 來建立獨立的 HTTP 連線。

自架 ntfy

若你需要完全掌控：

# Docker
docker run -p 80:80 -it binwiederhier/ntfy serve

# Native
go install heckel.io/ntfy/v2@latest
ntfy serve

接著將 Hermes 指向該伺服器：

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 中設定：

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 秒重連一次 —— 資料流的 Keepalive 預設值為 55 秒；ntfy 可能有間歇性的網路問題。適配器會套用指數退避策略（2 → 5 → 10 → 30 → 60 秒），一旦資料流維持連線 ≥60 秒即重置為 0。

Open WebUI

msgraph webhookopen webui