Chuyển tới nội dung chính

ntfy`ntfy là dịch vụ thông báo pub-sub dựa trên HTTP đơn giản. Nó hoạt động với máy chủ công cộng miễn phí tại

ntfy.sh hoặc bất kỳ phiên bản tự lưu trữ nào và hỗ trợ mọi ứng dụng khách có thể thực hiện yêu cầu HTTP - điện thoại, trình duyệt, tập lệnh, đồng hồ.

ntfy tạo một kênh đẩy nhẹ tuyệt vời cho Hermes: đăng ký một chủ đề từ ntfy mobile app, gửi tin nhắn đến chủ đề đó để nói chuyện với đại lý, nhận phản hồi về điện thoại của bạn.

Điều kiện tiên quyết​

  • Tên chủ đề (bất kỳ chuỗi duy nhất nào - Hermes-myname-2026 đều hoạt động tốt)
  • ntfy mobile app đã cài đặt và đăng ký theo chủ đề đó
  • Tùy chọn: máy chủ ntfy tự lưu trữ hoặc mã thông báo tài khoản ntfy.sh cho các chủ đề riêng tư/dành riêng

Thế thôi. Không SDK, không daemon, không Node.js. Bộ điều hợp sử dụng httpx vốn đã là phụ thuộc của Hermes.

Định cấu hình Hermes​

Thông qua trình hướng dẫn thiết lập​

Hermes setup gateway

`
``Chọn **ntfy** và làm theo lời nhắc.

### Thông qua biến môi trường

Thêm những thứ này vào 

~/.Hermes/.env

:

`
NTFY_TOPIC=Hermes-myname-2026
NTFY_ALLOWED_USERS=Hermes-myname-2026
NTFY_HOME_CHANNEL=Hermes-myname-2026

`

| Biến | Bắt buộc | Mô tả |
|---|---|---|
| 
`NTFY_TOPIC
` | Có | Chủ đề để đăng ký (tin nhắn đến) |
| 
`NTFY_SERVER_URL
` | Tùy chọn | URL máy chủ (mặc định: 
`https://ntfy.sh

) — trỏ tới ntfy tự lưu trữ để đảm bảo quyền riêng tư |
| 
`NTFY_TOKEN
` | Tùy chọn | Mã thông báo mang (ví dụ: 
`tk_xyz

) hoặc 
`user:pass
` cho xác thực cơ bản |
| 
`NTFY_PUBLISH_TOPIC
` | Tùy chọn | Chủ đề khác cho các câu trả lời gửi đi (mặc định là 
`NTFY_TOPIC

) |
| 
`NTFY_MARKDOWN
` | Tùy chọn | Đặt 
`true
` để gửi trả lời với tiêu đề 
`X-Markdown: true
` |
| 
`NTFY_ALLOWED_USERS
` | Được đề xuất | Cho phép tên chủ đề được phân tách bằng dấu phẩy (được coi là ID người dùng; xem bên dưới) |
| 
`NTFY_ALLOW_ALL_USERS
` | Tùy chọn | Đặt 
`true
` để cho phép mọi nhà xuất bản - chỉ an toàn cho các chủ đề riêng tư có mã thông báo đã đọc |
| 
`NTFY_HOME_CHANNEL
` | Tùy chọn | Chủ đề mặc định để gửi cron/thông báo |
| 
`NTFY_HOME_CHANNEL_NAME
` | Tùy chọn | Nhãn con người cho kênh chủ đề |

## Mô hình nhận dạng — đọc phần này trước khi triển khai`ntfy không có danh tính người dùng được xác thực gốc. Trường 
`title
` trên thư đã xuất bản **do nhà xuất bản kiểm soát** và có thể là bất cứ thứ gì người gửi muốn. Bộ điều hợp Hermes KHÔNG sử dụng 
`title
` để ủy quyền - nó sẽ cho phép bất kỳ nhà xuất bản nào biết chủ đề này giả mạo người dùng được phép.

Thay vào đó, **tên chủ đề chính là danh tính**. Mọi tin nhắn được xuất bản tới chủ đề đều được coi là đến từ cùng một người dùng logic (chủ đề). Do đó, 
`NTFY_ALLOWED_USERS
` thường chỉ là tên chủ đề - một danh sách cho phép một mục nhập kiểm soát toàn bộ kênh.

Điều này có nghĩa là **bất kỳ ai biết chủ đề đều có thể nói chuyện với nhân viên hỗ trợ**. Để biến đó thành ranh giới tin cậy thực sự:
- **Tự lưu trữ ntfy** và khóa chủ đề bằng [Access Control](https://docs.ntfy.sh/config/#access-control). Chỉ những khách hàng được ủy quyền có mã thông báo đọc/ghi mới có thể xuất bản.

- Hoặc **sử dụng chủ đề riêng tư trên ntfy.sh** ([reserved topics](https://docs.ntfy.sh/publish/#reserved-topics) yêu cầu tài khoản) và bảo vệ chủ đề đó bằng 
`NTFY_TOKEN

.
- Hoặc **chọn một tên chủ đề dài, khó đoán** (
`Hermes-7d4f9c8b-2026

) và coi đó là bí mật chung. Đây là thiết lập nhẹ nhất nhưng tên chủ đề bị rò rỉ qua bất kỳ nhật ký hoặc ảnh chụp màn hình nào.

Trong mọi trường hợp, không đưa dữ liệu nhạy cảm qua ntfy trừ khi chủ đề cơ bản được kiểm soát quyền truy cập.

## Bắt đầu nhanh — nói chuyện với đại lý của bạn từ điện thoại
1. Chọn tên chủ đề: 
`Hermes-myname-2026

2. Trên điện thoại: cài đặt [ntfy app](https://ntfy.sh/docs/subscribe/phone/), nhấn **++**, nhập 
`Hermes-myname-2026

3. Trên máy chủ:

``` bash
   echo 'NTFY_TOPIC=Hermes-myname-2026' >> ~/.Hermes/.env
   echo 'NTFY_ALLOWED_USERS=Hermes-myname-2026' >> ~/.Hermes/.env
   Hermes gateway restart

`

4. Từ ứng dụng ntfy, gửi tin nhắn đến chủ đề. Câu trả lời của nhân viên hỗ trợ sẽ xuất hiện dưới dạng thông báo đẩy.

## Sử dụng ntfy với cron jobs

Khi 
`NTFY_HOME_CHANNEL
` được đặt, các công việc định kỳ có thể gửi tới ntfy:

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

`
``Hoặc nhắm mục tiêu một chủ đề cụ thể một cách rõ ràng:

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

`
``Tính năng này hoạt động ngay cả khi cron chạy ngoài quy trình từ cổng — plugin đăng ký 
`standalone_sender_fn
` để mở kết nối HTTP của chính nó.

## Tự lưu trữ ntfy

Nếu bạn muốn kiểm soát hoàn toàn:

`bash

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

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

`
``Sau đó chỉ Hermes vào nó:

`
NTFY_SERVER_URL=https://ntfy.mydomain.com
NTFY_TOPIC=Hermes
NTFY_TOKEN=tk_abc123  # if you've set up access control

`
``Tính năng tự lưu trữ cung cấp cho bạn quyền kiểm soát quyền truy cập chủ đề, chính sách lưu trữ tin nhắn, tệp đính kèm và thẻ biểu tượng cảm xúc. Xem [ntfy server docs](https://docs.ntfy.sh/install/).

## Định dạng đánh dấu

Máy khách ntfy hiển thị đánh dấu khi nhà xuất bản đặt tiêu đề 
`X-Markdown: true

. Để bật tính năng trả lời gửi đi của Hermes:

`
NTFY_MARKDOWN=true

`
``Hoặc trong 
`config.yaml

:

``` yaml
platforms:
  ntfy:
    extra:
      markdown: true

`
`Ứng dụng dành cho thiết bị di động hỗ trợ một tập hợp con của CommonMark - in đậm, in nghiêng, danh sách, liên kết, khối mã có rào chắn. Xem [ntfy's markdown docs](https://docs.ntfy.sh/publish/#markdown-formatting) để biết bộ chính xác.

## Thiết lập chỉ gửi đi (thông báo không gửi đến)

Nếu bạn chỉ muốn Hermes *đẩy* thông báo tới ntfy (tóm tắt cron, cảnh báo) và không bao giờ chấp nhận lại tin nhắn, hãy đặt cả 
`NTFY_TOPIC
` và 
`NTFY_PUBLISH_TOPIC
` về cùng một giá trị và bỏ qua hoàn toàn 
`NTFY_ALLOWED_USERS

. Nếu không có danh sách cho phép, nhân viên hỗ trợ sẽ không bao giờ trả lời các tin nhắn gửi đến — điện thoại của bạn nhận được thông báo nhưng cuộc trò chuyện chỉ diễn ra một chiều.

## Giới hạn
- **Kích thước tin nhắn**: ntfy giới hạn nội dung tin nhắn ở mức 4096 ký tự. Hermes cắt ngắn với lời cảnh báo khi vượt quá mức này.

- **Không có chỉ báo gõ**: giao thức không hiển thị một chỉ báo nào; 
`send_typing
` là một sản phẩm không hoạt động.
- **Không có chủ đề hoặc tệp đính kèm**: ntfy là thông báo đẩy đơn giản. Những câu trả lời dài vẫn nằm trong nội dung thư, không có chuỗi bài đăng nào.
- **Không có danh tính người dùng gốc**: xem phần mô hình nhận dạng ở trên.

## Khắc phục sự cố`**Xác thực không thành công / 401** — 
`NTFY_TOKEN
` sai hoặc mã thông báo không có quyền xuất bản/đăng ký về chủ đề này. Bộ điều hợp tạm dừng vòng lặp kết nối lại trên 401 và trạng thái thời gian chạy của cổng sẽ hiển thị 
`fatal: ntfy_unauthoriZed

. Sửa mã thông báo và khởi động lại cổng.

**Không tìm thấy chủ đề / 404** — 
`NTFY_TOPIC
` không tồn tại trên máy chủ đã định cấu hình. Đối với ntfy.sh, các chủ đề được tạo tự động trong lần xuất bản đầu tiên, do đó, 404 có nghĩa là bạn được trỏ đến một máy chủ tự lưu trữ không cung cấp chủ đề. Bộ điều hợp tạm dừng vòng lặp kết nối lại với 
`fatal: ntfy_topic_not_found

.

**Đã kết nối nhưng không có tin nhắn** — Kiểm tra xem 
`NTFY_ALLOWED_USERS
` có bao gồm chính tên chủ đề hay không. Với mô hình nhận dạng của ntfy, chủ đề LÀ người dùng; để trống danh sách cho phép sẽ từ chối mọi thứ.

**Kết nối lại sau mỗi 60 giây** — Mặc định duy trì luồng là 55 giây; ntfy có thể gặp sự cố mạng không liên tục. Bộ điều hợp áp dụng thời gian chờ theo cấp số nhân (2 → 5 → 10 → 30 → 60 giây) và đặt lại về 0 sau khi luồng vẫn tồn tại ≥60 giây.