Ntfy¶

Overview¶

Ntfy（一般寫作 ntfy）係一套開源、輕量、可自架嘅推送通知服務，主要用 HTTP API 以 pub-sub 模式運作。發佈者只要向指定主題（topic）發送 HTTP POST 或 PUT 請求，訂閱者就可以透過 Android、iOS、Web、CLI 或 SSE/WebSocket 即時收到通知。Ntfy 嘅設計哲學係簡單、低資源、容易整合，因此常用於系統告警、備份完成通知、CI/CD 狀態、智能家居事件，以及同 litellm、Uptime Kuma 等服務串接。

在本 wiki 嘅基建語境中，Ntfy 部署喺 oracle-cloud 嘅執行個體上，以 docker 同 docker-compose 管理。容器名稱為 ntfy，使用 binwiederhier/ntfy:latest 映像，接入外部網絡 cf_network，並固定內網 IP 172.21.0.39。呢個安排令其他容器或反向代理可以穩定咁指向 Ntfy，避免因 DNS 或容器重啟而改 IP。

Architecture¶

Ntfy 容器以 serve 模式啟動，預設會喺容器內監聽 HTTP 連接埠（通常係 80）。Compose 檔案冇將連接埠映射到主機，而係只將容器加入 cf_network。因此 Ntfy 唔會直接暴露喺 Oracle Cloud 主機嘅公網介面，而係經 cloudflare-tunnel、proxy 或同網絡內嘅其他容器存取。

資料流大致如下：

[系統告警 / LiteLLM / 備份腳本]
             |
             | HTTP POST / PUT
             v
      [ntfy:80] 172.21.0.39
             |
             | SSE / WebSocket / HTTP stream
             v
[手機 App / Web / CLI / 其他服務]

容器掛載三個主要路徑：

/usr/share/zoneinfo：唯讀掛載，配合 TZ: Asia/Hong_Kong 提供正確時區。
/opt/docker/ntfy/cache：對應容器內 /var/cache/ntfy，用嚟存放快取、訊息資料庫、附件等。
/opt/docker/ntfy/config：對應容器內 /etc/ntfy，用嚟存放 server.yml 等設定檔。

cf_network 係外部網絡，代表佢必須事先存在。呢個設計常見於由 Cloudflare Tunnel 容器建立嘅共享網絡，令 Ntfy 可以畀隧道容器以 http://ntfy:80 或 http://172.21.0.39:80 存取。

Deployment¶

部署前需要具備：Oracle Cloud 執行個體、已安裝 Docker Engine 同 Docker Compose、已存在嘅 cf_network，以及 /opt/docker/ntfy 目錄權限。Compose 內容如下：

services:

  ntfy:
    image: binwiederhier/ntfy:latest
    container_name: ntfy
    restart: unless-stopped

    command:
      - serve

    environment:
      TZ: Asia/Hong_Kong

    volumes:
      - /usr/share/zoneinfo:/usr/share/zoneinfo:ro
      - /opt/docker/ntfy/cache:/var/cache/ntfy
      - /opt/docker/ntfy/config:/etc/ntfy

    networks:
      cf_network:
        ipv4_address: 172.21.0.39


networks:
  cf_network:
    external: true

部署步驟：

以 SSH 登入 Oracle Cloud 執行個體。
建立目錄：mkdir -p /opt/docker/ntfy/cache /opt/docker/ntfy/config。
檢查 cf_network 是否存在：docker network inspect cf_network。如果未存在，須按現有架構建立，並確保子網包含 172.21.0.39。
將上述 Compose 儲存為 /opt/docker/ntfy/docker-compose.yml。
執行 docker compose up -d。
用 docker compose logs -f ntfy 檢查啟動日誌。
喺 Cloudflare Tunnel 或反向代理設定 hostname，例如 ntfy.example.com，origin 指向 http://ntfy:80 或 http://172.21.0.39:80。
測試：curl -d "測試通知" https://ntfy.example.com/mytopic。

如果 Oracle Cloud 只用 Tunnel 入站，VCN 安全清單同主機防火牆唔需要開放 80/443；若果直接由公網連入，就要額外開放連接埠並加強認證。

Configuration¶

Ntfy 預設會讀取 /etc/ntfy/server.yml。由於 /opt/docker/ntfy/config 已映射到該目錄，可以建立 server.yml 作進階設定。常見例子：

base-url: "https://ntfy.example.com"
listen-http: ":80"
cache-file: "/var/cache/ntfy/cache.db"
cache-duration: "12h"
auth-file: "/var/cache/ntfy/user.db"
auth-default-access: "deny-all"
behind-proxy: true

重點設定：

base-url：對外公開網址，用於產生連結同通知內容。
listen-http：容器內監聽位址，通常保持 :80。
cache-file：訊息快取資料庫位置。
auth-file：使用者同權杖資料庫位置。
auth-default-access：建議設為 deny-all，避免變成公開轉發站。
behind-proxy：如果前面有 Cloudflare Tunnel、Traefik 或 Caddy，應設為 true。

認證方面，可用容器內 CLI 管理：

docker exec -it ntfy ntfy user add --role=admin admin
docker exec -it ntfy ntfy access admin mytopic rw
docker exec -it ntfy ntfy token add admin

之後發佈通知時可以帶入權杖或基本認證。TZ: Asia/Hong_Kong 同 zoneinfo 掛載可令日誌同時間顯示符合香港時區。

Operations¶

日常運維命令：

cd /opt/docker/ntfy
docker compose ps
docker compose logs -f ntfy
docker compose restart ntfy
docker compose pull
docker compose up -d

備份方面，最重要係 /opt/docker/ntfy/config 同 /opt/docker/ntfy/cache。如果 cache 內有 SQLite 資料庫，建議先停容器再複製，或者用 SQLite 備份工具，以減少檔案鎖定問題。更新時建議先備份，再拉取新映像。若追求穩定，可將 latest 改為固定版本標籤。

健康檢查可以用 https://ntfy.example.com/v1/health，亦可交由 Uptime Kuma 監控。若出現 502，通常係 Tunnel 同 Ntfy 唔喺同一網絡、IP 衝突、或者 cf_network 子網設定唔一致。若手機收唔到，檢查訂閱 URL、認證、背景限制、WebSocket，以及 Android/iOS 推送設定。若容器啟動失敗，檢查 /opt/docker/ntfy 權限同 server.yml 語法。若磁碟爆滿，清理 cache 或縮短 cache-duration。

安全上，唔好將未設認證嘅 Ntfy 直接暴露公網；應使用強密碼、Token、ACL，並限制來源。Ntfy 只負責通知，唔應該取代 litellm 呢類 LLM gateway，而係同佢整合，例如將 LiteLLM 嘅預算告警發送到指定 topic。

FAQ¶

Q：點解 Compose 冇 ports？
A：因為 Ntfy 只接入 cf_network，由 Cloudflare Tunnel 或反向代理喺同一網絡內存取，唔直接暴露主機連接埠。

Q：點解要固定 IP 172.21.0.39？
A：固定 IP 方便其他容器、隧道或監控服務穩定指向 Ntfy，減少 DNS 依賴。

Q：Ntfy 可唔可以取代 litellm？
A：唔可以。Ntfy 係通知服務，LiteLLM 係 LLM API gateway；兩者角色唔同，但可以互相整合。

Q：要唔要開 Oracle Cloud 安全清單？
A：如果只經 Tunnel 入站，通常唔需要開公網 80/443。若直接對外，就要開，並必須加認證。

Q：點樣備份？
A：備份 /opt/docker/ntfy/config 同 /opt/docker/ntfy/cache。設定檔可版本控制，cache 則按需要備份。

Q：手機收唔到通知點算？
A：檢查 topic 權限、Token、App 背景限制、WebSocket，以及 Firebase/APNs 相關設定。

docker
docker-compose
oracle-cloud
cloudflare-tunnel
proxy
litellm
Uptime Kuma
Home Assistant
Traefik
Caddy

Source¶

Coverage auto (container scan)