Перейти к содержимому
Поиск
Разработка

ntfy: уведомления из PHP, Node.js и скриптов — мастерская и 9 опытов

Подключаем уведомления к приложениям: публикация, права, SSE, восстановление, вложения и задержка. Девять реальных опытов, локальный конструктор JSON, Windows/Linux и исходники.

Александр Некрасов
ntfy: уведомления из PHP, Node.js и скриптов — мастерская и 9 опытов — обложка

ntfy: уведомления из приложений, скриптов и серверов

Резервная копия завершилась, большой отчёт готов, импорт нашёл ошибки, а свободное место на диске подошло к заданной границе. Приложение знает об этом сразу, но человеку приходится открывать кабинет или читать журнал. ntfy помогает превратить такое событие в короткое уведомление: ваш код отправляет HTTP-запрос, а подписчик получает сообщение по выбранной теме.

Инструмент подходит для собственных сервисов, домашних автоматизаций, фоновых задач и командных уведомлений. Можно использовать клиентское приложение либо подключить своего получателя через API. Для контролируемой среды ntfy разворачивается на собственном сервере: адрес, правила доступа, хранение сообщений и вложений остаются частью вашей инфраструктуры.

Ниже — девять практических опытов: публикация, JSON с кириллицей, разделение прав, поток SSE, восстановление после обрыва, вложение, отложенное сообщение, ограничения и обработка повторов. Мастерская показывает записи настоящего выполнения Windows/Linux и позволяет собрать JSON запроса. В ZIP находится исполняемый стенд, клиенты Node.js и PHP, тесты и настройки для VPS.

Где полезно: сообщать о результате, требующем внимания

В сервисе отчётности хорошее уведомление содержит название отчёта, период и ссылку на защищённый результат. В резервном копировании важно сообщать не только «завершено», но и что именно сохранено и где проверить восстановление. После импорта полезны количество обработанных строк, число ошибок и ссылка на подробный журнал. Человек должен понимать, стоит ли прерывать текущую работу.

Для команды можно разделить темы по назначению: результаты сборок, операции обслуживания, ошибки интеграций. При этом не стоит отправлять каждую строку application log отдельным сообщением. Группируйте повторяющиеся события, подавляйте известный шум и выбирайте частоту, соответствующую реакции человека. Постоянный поток одинаковых предупреждений быстро перестают читать.

Начните с одного сценария, например уведомления о готовности большого PDF. Зафиксируйте условие отправки, ответственного получателя и ожидаемое действие. После успешного опыта добавляйте новые темы. Подход полезен именно как связь между событием системы и понятным следующим шагом, а не как ещё один экран со всеми техническими сообщениями подряд.

Отправитель, тема, сервер и подписчик: четыре части системы

Отправитель — ваш PHP-код, Node.js-процесс или консольный скрипт. Он передаёт сообщение серверу ntfy. Тема, или topic, определяет канал сообщений: например, aen-lab в учебном стенде. Подписчик читает этот канал через поддерживаемый клиент либо HTTP API. У одной темы может быть несколько получателей с разными задачами.

Сервер принимает запрос, проверяет авторизацию и ограничения, сохраняет сообщение согласно конфигурации и передаёт его подключённым подписчикам. Успешный HTTP-ответ означает принятие сервером. Доступность сообщения через API, доставка на устройство, отображение системой уведомлений и прочтение человеком — последующие отдельные этапы. Их нельзя объединять в одно слово «доставлено» без проверки.

В мастерской первая публикация сразу проверяется отдельным чтением по точному ID. Это подтверждает работу сервера и API-подписчика. Проверка на реальном телефоне требует самого устройства, приложения, разрешений и фоновых настроек. Внешний вид мобильной страницы и реальная доставка push-уведомления проверяются разными способами.

Чем ntfy отличается от очереди задач и журнала ошибок

Уведомление помогает обратить внимание на событие. Очередь задач нужна, когда работу обязательно должен выполнить worker: сформировать документ, обработать файл, изменить запись. Для такой обработки важны подтверждения, повторы, порядок и состояние задания. Наличие кэша сообщений в ntfy не делает его заменой любой системе очередей.

Если задача должна продолжиться независимо от человека, рассмотрите BullMQ, NATS JetStream или Symfony Messenger. После завершения такой задачи ntfy может сообщить человеку результат. Эти инструменты дополняют друг друга на разных этапах процесса.

Подробную диагностику оставляйте в журнале приложения. Например, Monolog сохраняет контекст ошибок PHP, а уведомление может содержать краткое описание и идентификатор события. Не отправляйте в сообщение весь стек исключения вместе с персональными данными: для расследования удобнее защищённая страница с полным контекстом.

Версия, состав проекта и границы демонстрации

На 18 ноября 2026 года стенд закреплён на ntfy 2.38.1. В compose.yaml указан точный образ и digest. Клиенты и инструменты используют Node.js 24, а PHP-пример требует расширение curl. Версия сервера одинакова для записей Windows и Linux: на Windows он работает в Linux-контейнере Docker Desktop, а клиент Node.js запускается в самой Windows.

Публичная страница не подключена к частному серверу уведомлений. Она показывает сохранённые результаты реальных опытов и создаёт JSON локально. Нажатие кнопки в мастерской не отправляет сообщения, не выдаёт токены и не запрашивает разрешение на уведомления браузера. Для самостоятельного выполнения предназначен скачиваемый проект.

Такой формат позволяет изучить ответы, отказы доступа, поток событий и параметры без создания чужих подписок. Проверенные наборы синтетические. Публичные записи не содержат рабочие токены; они находятся только в исключённом каталоге локального стенда. Текущие способы установки перечислены в официальном руководстве ntfy.

Фрагмент package.json

{
  "name": "aen-ntfy-workshop",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "license": "MIT",
  "scripts": {
    "lab:up": "node tools/lab.mjs up",
    "lab:down": "node tools/lab.mjs down",
    "test": "node tests/integration.mjs",
    "start": "node tools/server.mjs",
    "build": "node tools/build.mjs"
  },
  "dependencies": {
    "bootstrap": "5.3.9"
  }
}

Мини-мастерская: исследовать ответы и собрать свой запрос

Выберите практическую задачу, платформу записи и вариант опыта, затем нажмите «Показать результат». Под кратким выводом можно раскрыть полный ответ, входные параметры и время выполнения. JSON результата скачивается отдельно: удобно сравнить идентификаторы, статусы HTTP и подтверждение получения. После смены параметров прежний результат сбрасывается.

Ниже расположен локальный конструктор. Измените заголовок, сообщение и приоритет, соберите JSON и скачайте notification.json. Он пригодится в запросе к вашему собственному стенду. Конструктор не проверяет существование сервера, права пользователя или факт доставки: он помогает подготовить тело запроса и увидеть связь между полями и назначением уведомления.

Начните с обычной публикации, затем сравните её с отказами ACL и восстановлением через since. На телефоне удобно открыть мастерскую отдельно. Исходники доступны прямо на странице: выберите файл, раскройте код, скопируйте его либо скачайте. Весь проект содержит также команды запуска, тесты и конфигурации обратного прокси.

Windows: поднять собственный локальный стенд

Распакуйте проект и откройте PowerShell в его каталоге. Нужны работающий Docker Desktop с Linux engine и Node.js 24. Скрипт lab:up запускает только Compose-проект aen-b24-ntfy, ждёт ответ сервера и при первом старте создаёт учебных пользователей. Порт 8581 привязан к 127.0.0.1, поэтому сервер доступен только с этой машины.

После запуска выполните тесты. Они публикуют синтетические сообщения в aen-lab и проверяют реальные ответы, в том числе отложенное сообщение. Для просмотра статической мастерской выполните build и start. Длительно работающую команду start оставьте в отдельном терминале, а упражнения с клиентами запускайте в другом окне.

Не завершайте стенд до окончания опытов. В конце npm run lab:down остановит только этот Compose-проект и сохранит данные. Если Docker не работает, публичную мастерскую всё равно можно изучать, но это не является выполнением серверных тестов. Сначала устраните причину запуска Docker, затем повторите лабораторию.

node --version
docker version
npm.cmd ci
npm.cmd run lab:up
npm.cmd test
npm.cmd run build
npm.cmd start

Linux: тот же набор опытов на серверной платформе

На Linux нужны Docker Engine, Compose plugin и Node.js 24. PHP CLI с расширением curl потребуется только для соответствующего клиента. Выполните установку по lock-файлу и запуск лаборатории из каталога проекта. node_modules с Windows переносить не нужно: зависимости устанавливаются заново на целевой платформе.

Проект использует тот же topic, те же правила доступа и те же тесты. Разница в оболочке: Bash работает с export и unset, PowerShell — с переменными Env. В Bash команда curl обычно является отдельным HTTP-клиентом; в Windows явно используйте curl.exe, чтобы не попасть на старый псевдоним Invoke-WebRequest.

Для первого опыта на VPS оставляйте порт на loopback и запускайте клиента по SSH на самом сервере. Так можно проверить публикацию, чтение и права до настройки внешнего домена. Затем добавляйте HTTPS и клиентское подключение. Поэтапный запуск облегчает поиск причины: проблема Docker, ACL и обратного прокси не смешивается в один неясный отказ.

node --version
docker compose version
npm ci
npm run lab:up
npm test
npm run build
npm start

Compose: постоянные данные и закрытый доступ по умолчанию

В compose.yaml задано постоянное хранилище для базы пользователей, кэша сообщений и вложений. Данные находятся в .runtime/data и переживают обычный перезапуск контейнера. auth-default-access установлен в deny-all: неизвестный пользователь не получает доступ к теме только потому, что знает её название. Это важная отправная точка для частного сервера.

В учебной конфигурации кэш сообщений хранится час, вложение ограничено 64k, суммарное пространство — 2M, срок вложений — час. Эти небольшие величины позволяют воспроизвести ошибки размера без загрузки больших файлов. Повышенный burst запросов нужен серии тестов; переносить все значения в production без оценки нагрузки не стоит.

base-url определяет адрес сервера, который может попадать в ссылки ответа, включая вложения. Для локальной лаборатории это localhost, а на VPS нужен настоящий внешний HTTPS-адрес. Как связать несколько сервисов и тома в одном окружении, разобрано в практике Docker Compose.

Фрагмент compose.yaml

services:
  ntfy:
    image: binwiederhier/ntfy:v2.38.1@sha256:038da2be5e668fee6d36a62884eea48975e1b71c29a56964e5298c1b9165a573
    command: [serve]
    ports: ["127.0.0.1:8581:80"]
    volumes: ["./.runtime/data:/var/lib/ntfy"]
    environment:
      NTFY_BASE_URL: http://127.0.0.1:8581
      NTFY_AUTH_FILE: /var/lib/ntfy/auth.db
      NTFY_AUTH_DEFAULT_ACCESS: deny-all
      NTFY_CACHE_FILE: /var/lib/ntfy/cache.db
      NTFY_CACHE_DURATION: 1h
      NTFY_ATTACHMENT_CACHE_DIR: /var/lib/ntfy/attachments
      NTFY_ATTACHMENT_FILE_SIZE_LIMIT: 64k
      NTFY_ATTACHMENT_TOTAL_SIZE_LIMIT: 2M
      NTFY_ATTACHMENT_EXPIRY_DURATION: 1h
      NTFY_VISITOR_REQUEST_LIMIT_BURST: 500
    restart: unless-stopped

Пользователи, ACL и токены: кто пишет, а кто читает

Лаборатория создаёт двух пользователей. aen-writer может публиковать только в aen-lab, aen-reader — читать эту тему. Токены сохраняются в .runtime/tokens.json и не попадают в public или архив с готовыми записями. Пароли создаются случайно. Повторный lab:up использует существующее состояние, а не очищает базу ради нового опыта.

Токен наследует права пользователя. Поэтому отдельный токен одного общего администратора не превращается в ограниченный токен только для отправки. Для интеграции создавайте пользователя с минимальными правами, затем выдавайте ему токен. Если несколько приложений выполняют разные задачи, раздельные учётные записи упрощают отзыв доступа и выяснение источника сообщения.

В стенде токены истекают через сутки. При повторном использовании спустя время обновите их командами ntfy token; скрипт не вращает их автоматически. Не удаляйте всю базу, чтобы исправить один истёкший токен. Модель пользователей, ACL и токенов описана в официальной конфигурации доступа.

docker compose -p aen-b24-ntfy exec ntfy ntfy access
docker compose -p aen-b24-ntfy exec ntfy ntfy token --help

Пример 1. Отправить сообщение и подтвердить чтение

Первый опыт выполняет POST в aen-lab и сохраняет выданный сервером ID. Затем отдельный читатель запрашивает накопленные сообщения и находит именно этот идентификатор. Такая проверка сильнее, чем просмотр HTTP 200: она подтверждает, что опубликованное событие доступно получателю с его отдельными правами.

Для ручного запуска загрузите токен писателя в переменную окружения и выполните CLI. Скрипт печатает только ID, тип события и время, без значения токена. В рабочем приложении сохраняйте этот ответ вместе с собственным идентификатором операции: так проще сопоставить действие системы и уведомление при расследовании ошибки.

Пустое сообщение лучше отклонить до сетевого запроса. Если ответ оказался не JSON, клиент сообщает статус, а не считает любой текст успешной доставкой. Прокси может вернуть HTML-страницу ошибки, поэтому корректная обработка ответа нужна даже при простом HTTP API. Получение ответа сервером и чтение человеком остаются разными проверками.

$env:NTFY_URL = 'http://127.0.0.1:8581'
$env:NTFY_TOKEN = (Get-Content .runtime/tokens.json | ConvertFrom-Json).'aen-writer'
node src/publish-cli.mjs 'Учебный отчёт готов'
Remove-Item Env:NTFY_TOKEN
export NTFY_URL=http://127.0.0.1:8581
export NTFY_TOKEN="$(node -p 'JSON.parse(require("fs").readFileSync(".runtime/tokens.json","utf8"))["aen-writer"]')"
node src/publish-cli.mjs 'Учебный отчёт готов'
unset NTFY_TOKEN

Пример 2. JSON: заголовок, кириллица, приоритет и теги

Расширенное уведомление содержит отдельный заголовок, текст, приоритет и теги. В опыте используется русская строка о готовом отчёте, высокий приоритет 4 и два тега. После публикации тест проверяет сохранённые значения в ответе. Такой контракт удобен для приложений: данные явно названы, а кириллица передаётся в UTF-8 JSON.

Соберите notification.json в мастерской и отправьте его на корень собственного сервера. Поле topic находится в самом JSON. Для короткого текстового POST тема задавалась в URL; эти два способа не следует смешивать случайным копированием параметров. В PowerShell файл с UTF-8 обычно надёжнее сложной вложенной строки с несколькими уровнями кавычек.

Приоритет должен отражать действие: обычный отчёт не требует постоянного срочного сигнала. Теги помогают распознавать тип события, но не заменяют ясный текст. Официальные варианты публикации, поля и настройки сообщения перечислены в руководстве отправки ntfy. Наш конструктор показывает небольшой набор для типичной интеграции.

$env:NTFY_TOKEN = (Get-Content .runtime/tokens.json | ConvertFrom-Json).'aen-writer'
curl.exe --fail-with-body -H "Authorization: Bearer $env:NTFY_TOKEN" -H "Content-Type: application/json" --data-binary "@notification.json" http://127.0.0.1:8581
Remove-Item Env:NTFY_TOKEN
export NTFY_TOKEN="$(node -p 'JSON.parse(require("fs").readFileSync(".runtime/tokens.json","utf8"))["aen-writer"]')"
curl --fail-with-body -H "Authorization: Bearer $NTFY_TOKEN" -H 'Content-Type: application/json' --data-binary @notification.json http://127.0.0.1:8581
unset NTFY_TOKEN

Пример 3. Четыре отказа: проверить права до внедрения

Проверка ACL включает четыре отрицательных сценария: анонимная публикация, чтение токеном писателя, запись токеном читателя и публикация писателем в чужую тему. Ожидаемый результат — отказ. Если каждый запрос успешен, красивый интерфейс подписки ещё не означает правильно настроенную частную систему.

В мастерской можно увидеть реальные статусы и ответы сервера. Отказы важно проверять вместе с разрешёнными действиями: иначе легко получить конфигурацию, которая либо открыта всем, либо блокирует вообще всё. Сохраняйте такую проверку при изменении пользователей, прокси и версии сервера. Она помогает заметить случайное расширение доступа.

Название темы — маршрутизация, а не пароль. Даже длинный случайный topic не заменяет авторизацию в частной системе. Для рабочей интеграции выберите понятные имена и ограничьте их ACL. Токены не кладите в query-параметры: URL часто оказывается в истории, журналах и скопированных ссылках. Передавайте доступ через предусмотренный заголовок Authorization.

Фрагмент tests/integration.mjs

const unauth=await req('/aen-lab',{method:'POST',body:'no auth'}),wrongRead=await req('/aen-lab/json?poll=1',{headers:h(writer)}),wrongWrite=await req('/aen-lab',{method:'POST',headers:h(reader),body:'reader cannot write'}),other=await req('/private-topic',{method:'POST',headers:h(writer),body:'forbidden'});
check([401,403].includes(unauth.status),'anonymous denied');check(wrongRead.status===403&&wrongWrite.status===403&&other.status===403,'ACL read/write/topic separation');

Пример 4. SSE: новое сообщение в открытом соединении

Поток SSE позволяет получать события через долго живущее HTTP-соединение. В тесте сначала открывается подписка читателя, затем писатель публикует новое сообщение. Проверка ждёт его точный ID в потоке и закрывает соединение. Это настоящий сетевой обмен с локальным сервером, а не нарисованная анимация уведомления.

У потокового ответа есть служебные события открытия и поддержания соединения. Обработчик должен отличать их от сообщения приложения. Фрагменты сети не обязаны совпадать с границами JSON или строки: полноценный клиент хранит незавершённый хвост и разбирает события по протоколу. Короткий лабораторный поиск ID подтверждает транспорт, но не объявляется универсальным парсером SSE.

Для ручной диагностики curl с ключом -N показывает поток без собственного буферизования. За reverse proxy тоже нужно учитывать buffering и тайм-ауты. Форматы JSON stream, SSE и raw описаны в API подписок ntfy. Выбирайте формат по потребностям клиента, а не только по короткому примеру подключения.

export NTFY_TOKEN="$(node -p 'JSON.parse(require("fs").readFileSync(".runtime/tokens.json","utf8"))["aen-reader"]')"
curl -N -H "Authorization: Bearer $NTFY_TOKEN" http://127.0.0.1:8581/aen-lab/sse
# Для чтения нужен токен aen-reader, не aen-writer.
unset NTFY_TOKEN

Пример 5. since: продолжить чтение после обрыва

Получатель может потерять соединение или временно отключиться. В опыте создаются два последовательных сообщения, а ID первого используется как контрольная точка. Запрос since возвращает следующее событие и не повторяет саму точку. Проверка работает по идентификаторам, поэтому старые учебные сообщения в кэше не мешают результату.

Сохраняйте последнюю успешно обработанную позицию после завершения обработки, а не сразу после получения сетевого фрагмента. При перезапуске получатель сможет запросить продолжение. Если отправить checkpoint вперёд раньше результата, ошибка обработки приведёт к пропуску; если сохранять слишком поздно, возможно повторное получение. Для этого нужна идемпотентность на стороне приложения.

since ограничен доступной историей сервера. Удалённое по сроку сообщение не восстановится от нового запроса. Также не следует бесконечно запрашивать весь кэш через since=all при каждом обновлении экрана. Для длительно отключённых потребителей определите, как они сверяют пропущенные события с основным источником данных.

export NTFY_TOKEN="$(node -p 'JSON.parse(require("fs").readFileSync(".runtime/tokens.json","utf8"))["aen-reader"]')"
curl --fail-with-body -H "Authorization: Bearer $NTFY_TOKEN" 'http://127.0.0.1:8581/aen-lab/json?poll=1&since=LAST_MESSAGE_ID'
# Замените LAST_MESSAGE_ID сохранённым ID; используйте токен читателя.
unset NTFY_TOKEN

Пример 6. Вложение: загрузить и проверить байты

Уведомление может содержать небольшой файл, например учебный текстовый отчёт. В опыте выполняется PUT с Filename, сервер возвращает сведения о вложении, а читатель скачивает его. Проверка сравнивает фактические байты и SHA-256. Один успешный ответ загрузки не доказывает, что ссылка ведёт к тому же содержимому.

В лаборатории вложение специально небольшое, а его срок ограничен часом. Ссылка из ответа строится с base-url сервера. Если после переноса на VPS остался localhost, телефон или внешний клиент получит непригодный адрес. Проверяйте скачивание именно с той стороны, где документ должен использоваться.

Вложение не является резервной копией. Для приватных документов практичнее хранить файл в основном приложении и отправлять ссылку, при открытии которой проверяется доступ. Не предполагайте, что знание topic ACL автоматически доказывает нужную политику каждого URL вложения. Проверьте фактическое поведение выбранной версии и рассматривайте прямую ссылку как потенциально передаваемую вместе с файлом.

export NTFY_TOKEN="$(node -p 'JSON.parse(require("fs").readFileSync(".runtime/tokens.json","utf8"))["aen-writer"]')"
curl --fail-with-body -X PUT -H "Authorization: Bearer $NTFY_TOKEN" -H 'Filename: report.txt' -H 'Content-Type: application/octet-stream' --data-binary @report.txt http://127.0.0.1:8581/aen-lab
unset NTFY_TOKEN

Пример 7. Delay: отправить не раньше заданного времени

Отложенное сообщение подходит для короткого напоминания: вернуться к операции через небольшой интервал или сообщить о проверке позже. В опыте сервер принимает Delay: 10s, затем тест убеждается, что сообщение ещё не доступно до срока и появляется после него. Это означает «не раньше чем через десять секунд», а не гарантию отображения ровно на десятой секунде.

Серверный обработчик отложенных сообщений проверяет очередь периодически; стандартный интервал проверки составляет десять секунд. Поэтому фактическое появление может быть позже заданной границы. В лаборатории ожидание ограничено 35 секундами, чтобы учитывать этот цикл. Более короткий дедлайн способен ошибочно объявить исправную доставку неработающей.

Сервер должен продолжать работать и сохранять нужное состояние. Для сложного расписания, бизнес-повторов и зависимостей лучше использовать отдельный планировщик либо очередь, а ntfy оставить отправителем результата. Например, Croner помогает описывать расписания Node.js и учитывать временные зоны.

export NTFY_TOKEN="$(node -p 'JSON.parse(require("fs").readFileSync(".runtime/tokens.json","utf8"))["aen-writer"]')"
curl --fail-with-body -H "Authorization: Bearer $NTFY_TOKEN" -H 'Delay: 10s' --data-binary 'Check report later' http://127.0.0.1:8581/aen-lab
unset NTFY_TOKEN

Пример 8. Ограничения: пустой текст и слишком большой файл

Клиент отклоняет пустое сообщение до сети. Отдельный запрос загружает 70 000 байт при серверном ограничении вложения 64k и получает отказ. Эти проверки показывают два уровня ответственности: интерфейс помогает исправить ввод, а сервер самостоятельно защищает ресурсы. Удаление клиентской проверки не должно превращать сервер в бесконтрольное хранилище.

Размеры UTF-8 текста измеряются байтами, а не только количеством символов JavaScript. Русская строка часто занимает больше байт, чем число видимых букв. Наш Node-клиент ограничивает сообщение 4000 байт. У библиотечного API и сервера есть собственные пределы; контракт приложения стоит делать явным и проверять до отправки.

Не повторяйте автоматически любой 4xx. Неверные права, формат и размер требуют исправления параметров. Для временной перегрузки нужен отдельный подход с паузой и пределом попыток. Сообщение об ошибке должно помогать оператору понять категорию отказа, а лог — содержать идентификатор операции и статус без раскрытия токена.

Фрагмент src/client.mjs

const url=new URL(base);if(!['http:','https:'].includes(url.protocol))throw Error('HTTP(S) required');
 if(!/^[a-zA-Z0-9_-]{1,64}$/.test(topic))throw Error('Invalid topic');
 if(typeof message!=='string'||!message.trim()||new TextEncoder().encode(message).length>4000)throw Error('Message: 1..4000 UTF-8 bytes');

Пример 9. Получатель: пропустить повтор одного ID

После восстановления соединения одно событие может снова попасть в обработку. В учебном опыте получатель видит три элемента: первое сообщение дважды и второе один раз. Set обработанных ID приводит к двум применениям. Это простой способ показать идемпотентность при повторной доставке уже известного серверного события.

Такой Set в памяти исчезнет после перезапуска процесса. Для важной обработки нужна сохранённая контрольная точка либо таблица выполненных операций. Также два отдельных POST обычно создают два разных ID. Если отправитель после тайм-аута повторил запрос, проверка только серверного ID не распознает, что бизнес-событие было тем же.

Добавьте собственный operationId в контракт и храните связь между событием, уведомлением и результатом обработки. Не путайте дедупликацию доставки с запретом всех похожих текстов: два одинаково сформулированных отчёта за разные периоды могут быть разными событиями. Ключ должен отражать смысл операции, а не случайное совпадение строки сообщения.

const seen = new Set();
for (const message of messages) {
  if (seen.has(message.id)) continue;
  await handle(message);
  seen.add(message.id);
}
// Для перезапуска процесса храните состояние надёжнее оперативной памяти.

Node.js: небольшой клиент с тайм-аутом и разбором ошибки

Клиент в архиве принимает адрес, токен, тему, текст, заголовок, приоритет и теги. Он проверяет протокол URL, допустимое имя темы и размер сообщения. Запрос выполняется через встроенный fetch с ограничением времени. Дополнительная HTTP-библиотека для этого простого сценария не требуется.

Ответ сначала читается как текст, затем разбирается JSON. Это позволяет отличить нормальный API-ответ от HTML, пришедшего вместо него через ошибочный прокси. При неуспешном статусе вызывающая сторона получает исключение с кодом HTTP. Успешный объект содержит ID, который можно сохранить рядом с задачей приложения.

Сетевой тайм-аут не доказывает, что сервер не принял сообщение. Повторять запрос нужно с пониманием возможного дубля и своей моделью operationId. Адрес сервера задавайте доверенной конфигурацией, а не свободным полем посетителя. Для производственной интеграции дополните клиент проверкой требуемых полей ответа и ограничением числа повторов по категориям ошибок.

Фрагмент src/client.mjs

export async function publish({base,token,topic='aen-lab',message,title='Готово',priority=3,tags=[]}){
 const url=new URL(base);if(!['http:','https:'].includes(url.protocol))throw Error('HTTP(S) required');
 if(!/^[a-zA-Z0-9_-]{1,64}$/.test(topic))throw Error('Invalid topic');
 if(typeof message!=='string'||!message.trim()||new TextEncoder().encode(message).length>4000)throw Error('Message: 1..4000 UTF-8 bytes');
 const response=await fetch(url,{method:'POST',headers:{Authorization:`Bearer ${token}`,'Content-Type':'application/json'},body:JSON.stringify({topic,message,title,priority,tags}),signal:AbortSignal.timeout(5000)});
 const raw=await response.text();let payload;try{payload=JSON.parse(raw);}catch{throw Error('Non-JSON response: HTTP '+response.status);}
 if(!response.ok)throw Error(`ntfy HTTP ${response.status}: ${payload.error||'request rejected'}`);
 return payload;
}

PHP: уведомление после готовности отчёта или импорта

PHP-пример использует ext-curl, JSON_THROW_ON_ERROR, тайм-аут соединения и общий тайм-аут запроса. URL и токен читаются из окружения. Скрипт отправляет сообщение о готовности отчёта и выводит только короткое подтверждение. Он пригодится в CLI-задаче, обработчике очереди либо серверной интеграции после успешного сохранения результата.

Отправляйте уведомление после фиксации основных данных. Если транзакция затем откатилась, человеку не должно уйти сообщение об успешной операции. При большом потоке событий лучше сохранить намерение уведомить вместе с бизнес-данными и обработать его отдельно. Так временная недоступность ntfy не ломает пользовательское действие и не теряет событие молча.

В Windows и Linux сначала проверьте php -m и наличие curl. Ошибки доступа либо сети должен увидеть управляющий процесс, поэтому исключения нельзя просто скрывать. Токен берётся из конфигурации запуска, не из формы пользователя. Пример не требует Composer-зависимостей: это прямой HTTP-запрос стандартными средствами PHP.

Фрагмент src/publish.php

<?php
declare(strict_types=1);
$base = getenv('NTFY_URL') ?: 'http://127.0.0.1:8581';
$token = getenv('NTFY_TOKEN') ?: throw new RuntimeException('NTFY_TOKEN required');
$payload = json_encode(['topic'=>'aen-lab','title'=>'PHP: отчёт готов','message'=>$argv[1] ?? 'Учебный отчёт','priority'=>3],JSON_UNESCAPED_UNICODE|JSON_THROW_ON_ERROR);
$ch = curl_init($base);
curl_setopt_array($ch,[CURLOPT_POST=>true,CURLOPT_POSTFIELDS=>$payload,CURLOPT_RETURNTRANSFER=>true,CURLOPT_TIMEOUT=>5,CURLOPT_CONNECTTIMEOUT=>2,CURLOPT_FOLLOWLOCATION=>false,CURLOPT_HTTPHEADER=>['Content-Type: application/json','Authorization: Bearer '.$token]]);
$raw = curl_exec($ch);$status = curl_getinfo($ch,CURLINFO_RESPONSE_CODE);
if($raw===false)throw new RuntimeException('Network error: '.curl_error($ch));
curl_close($ch);
$data=json_decode($raw,true,512,JSON_THROW_ON_ERROR);
if($status<200||$status>=300)throw new RuntimeException('ntfy HTTP '.$status.': '.($data['error']??'error'));
echo json_encode(['id'=>$data['id'],'event'=>$data['event'],'time'=>$data['time']],JSON_PRETTY_PRINT).PHP_EOL;

Браузерная подписка, EventSource и заголовок Authorization

Для открытого либо подходящим образом авторизованного SSE-подключения удобно использовать EventSource. Однако его стандартный конструктор не принимает произвольный Authorization-заголовок. Нельзя просто перенести пример fetch с Bearer в EventSource и ожидать тот же результат. Это частая причина, почему консольный клиент работает, а браузерный — нет.

Для Bearer-подписки возможен fetch с чтением потока либо собственный backend, который проверяет сессию пользователя и обслуживает интерфейс. Выбор зависит от архитектуры приложения. При fetch-stream нужно корректно разбирать границы событий, восстанавливать соединение и освобождать ресурсы при уходе со страницы. Длинный токен в query ради краткого примера создаёт лишние места утечки.

Обычное сообщение внутри страницы и системное уведомление браузера тоже различаются. Сначала можно показать событие в интерфейсе без отдельного разрешения. Для фонового уведомления нужны соответствующие возможности браузера и настройка Web Push. В нашей публичной мастерской эти разрешения не запрашиваются, потому что она не является подключённым клиентом ntfy.

Телефоны и Web Push: что проверять на настоящем устройстве

Для телефона доступны клиентские приложения ntfy, но реальная доставка зависит от платформы, сетевого режима и фоновых ограничений. После настройки собственного сервера проверьте вход, подписку, обычное сообщение и сообщение при выключенном экране. Затем повторите опыт после переключения Wi-Fi и мобильной сети. Одной успешной проверки открытого приложения недостаточно.

Web Push требует HTTPS, корректной настройки сервера, service worker и разрешения пользователя. В зависимости от платформы могут участвовать внешние push-службы. Сам факт self-hosted ntfy не описывает автоматически весь маршрут фонового уведомления. Ознакомьтесь с руководством для телефонов и возможностями веб-приложения для выбранного клиента.

В этой публикации проверяются сервер, API, клиенты и мобильная адаптивность мастерской. Доставка push на физические Android/iOS-устройства не заявляется. При внедрении определите список поддерживаемых устройств и критерий успеха: принято сервером, показано системой или подтверждено человеком. Для критических сигналов продумайте запасной канал и правила эскалации.

VPS с Caddy: домен, HTTPS и правильный base-url

На выделенном или облачном сервере удобно оставить ntfy на loopback и поставить Caddy перед ним. Создайте DNS-запись для своего домена, обеспечьте доступ к портам HTTPS и настройте reverse_proxy. Домен notify.example.com в файле является образцом: сертификат и рабочий маршрут появятся только для реально принадлежащего вам адреса с корректной сетью.

В конфигурации ntfy замените base-url на внешний HTTPS-адрес и включите behind-proxy для этой доверенной схемы. Порт 8581 остаётся привязанным к 127.0.0.1. После изменения перезапустите только свой сервис и проверьте публикацию, подписку и URL вложения через внешний адрес. Локальный успешный POST не проверяет DNS и TLS.

Настройки прокси не должны открывать частный сервер всем желающим. Сохраните deny-all и пользователей с минимальными правами. Практика сертификатов, reverse proxy и развёртывания подробнее разобрана в материале Caddy. Начинайте с проверенной локальной лаборатории и меняйте по одному уровню подключения.

Фрагмент deploy/Caddyfile

# Replace with your real DNS name; 80/443 must reach this Caddy server.
notify.example.com {
    reverse_proxy 127.0.0.1:8581
}
# ntfy: base-url=https://notify.example.com, behind-proxy=true.
# Trust only the proxy route; keep 8581 bound to loopback.

VPS с Nginx: поток без буферизации и достаточный тайм-аут

Для Nginx используется существующий HTTPS virtual host с действующим сертификатом. В location проксируется ntfy, передаются сведения о внешнем запросе и отключается buffering. У SSE соединение живёт долго, поэтому стандартный короткий тайм-аут может приводить к периодическим обрывам, даже если публикация обычным POST выглядит исправной.

После правок выполните nginx -t и только затем reload по правилам своего сервера. Проверьте не только стартовую страницу, но и поток с новым сообщением. Если события появляются пачкой спустя время, ищите буферизацию по всей цепочке: reverse proxy, промежуточный CDN и клиент. На время диагностики сравните прямой loopback-запрос и внешний HTTPS-маршрут.

behind-proxy имеет смысл лишь за контролируемым прокси. Не доверяйте переданным клиентом адресам, если путь к backend открыт в обход него. Параметры вашей сети и ограничения запросов должны согласовываться между слоями. Ежедневные настройки и диагностика приведены в статье про Nginx.

Фрагмент deploy/nginx.conf

# Include in an existing HTTPS virtual host with a valid certificate.
location / {
    proxy_pass http://127.0.0.1:8581;
    proxy_http_version 1.1;
    proxy_buffering off;
    proxy_read_timeout 1h;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}
# Set ntfy base-url to the public HTTPS URL and behind-proxy=true.
# Do not publish port 8581 directly to the Internet.

Секреты и содержимое: что не должно попасть в уведомление

Токен даёт доступ от имени пользователя. Храните его в настройках сервиса или менеджере секретов, а не в публичном JavaScript и скачиваемом примере. В лаборатории .runtime исключён из публикации. Проверяйте не только исходный код, но и сохранённые HTTP-записи: полный дамп запроса способен содержать Authorization, даже если код выглядит аккуратно.

Сам текст уведомления тоже может оказаться на экране блокировки и в истории устройства. Вместо подробных персональных данных отправляйте короткий статус и ссылку на защищённый кабинет. Не добавляйте в ссылку пароль, постоянный токен или полный приватный отчёт. Человек должен перейти в приложение и получить данные в соответствии со своими правами.

Для конфигурации нескольких серверов пригодится SOPS + age. Шифрование файла не заменяет правильные права уже запущенного процесса: секрет всё равно понадобится клиенту в момент обращения. Продумайте выдачу, срок действия, отзыв и замену токена вместе с жизненным циклом интеграции.

Хранение, резервная копия и обновление сервера

Кэш сообщений, база авторизации и вложения связаны с состоянием сервера. В учебном проекте они находятся в .runtime/data и сохраняются при lab:down и обычном restart. Не путайте перезапуск процесса с созданием новой пустой лаборатории. Удаление каталога данных может потерять пользователей, токены и доступную историю.

Для простой согласованной резервной копии можно остановить только свой Compose-проект, скопировать каталог данных и запустить обратно. В круглосуточной системе используйте подходящий механизм резервирования SQLite, а не слепое копирование изменяемой базы. Обязательно проверьте восстановление на отдельном стенде: наличие архива ещё не подтверждает, что сервер с ним запускается.

Перед обновлением закрепите новую версию отдельно, сохраните предыдущий образ и резервную копию. Повторите разрешённые и запрещённые операции, поток, since, вложение и сохранность после перезапуска. Не выполняйте глобальную очистку Docker ради обновления одного сервиса. Команды проекта ограничены его собственным именем aen-b24-ntfy и не удаляют данные автоматически.

docker compose -p aen-b24-ntfy -f compose.yaml ps
docker compose -p aen-b24-ntfy -f compose.yaml logs --tail=50 ntfy
# По завершении учебных опытов:
npm run lab:down

Диагностика: отделить сеть, права, кэш и устройство

Если POST не проходит, сначала проверьте адрес, health endpoint и соединение с локальным сервером. Затем проверьте токен, срок действия, пользователя и ACL. Ошибка 403 при чтении токеном писателя ожидаема в нашем стенде. Попытка исправить её выдачей административных прав скрывает причину и ломает разделение ролей.

Если публикация принята, но сообщение не найдено, сравните topic и точный ID. Проверьте Delay, доступную историю и параметры since. Для потоковой подписки отдельно проверьте буферизацию и обрывы. Если API-получатель видит сообщение, а телефон не показывает уведомление, переходите к настройкам клиента и ОС, не меняя вслепую серверную авторизацию.

В журнале полезны собственный operationId, серверный ID, статус, категория ошибки и длительность. Секреты туда не нужны. Для частого сбоя фиксируйте несколько измерений и воспроизводимый запрос с учебными данными. Такая последовательность быстро показывает, какой именно этап работает, вместо общего вывода «уведомления иногда не приходят».

curl --fail-with-body http://127.0.0.1:8581/v1/health
docker compose -p aen-b24-ntfy -f compose.yaml logs --tail=50 ntfy

Что проверяет стенд и как повторить проверку

Интеграционный сценарий действительно публикует сообщения, читает их отдельным пользователем, проверяет кириллицу, приоритет, отказы ACL, SSE и восстановление с checkpoint. Вложение скачивается и сравнивается побайтово. Отложенное сообщение проверяется до срока и после появления. Отдельно проверяются большой файл, пустой текст, обработка повторного ID и health endpoint.

Одинаковый набор запускается клиентом Windows и клиентом Linux против закреплённого сервера ntfy. PHP-клиент также проверяется в обеих средах; сохранность сообщений после перезапуска проверяется отдельно. Результаты попадают в публичные записи без токенов. Не считайте смену платформы в мастерской новым запуском: она выбирает соответствующую сохранённую проверку.

Повторите тесты после изменения конфигурации и библиотек. Время Delay не должно проверяться слишком коротким жёстким ожиданием: планировщик работает периодически. Записи этой публикации подтверждают учебные сценарии, а не все комбинации ваших устройств, провайдеров и нагрузок. Production VPS и реальные мобильные push требуют собственной приёмки.

npm test
# После успешной записи результатов и подготовки публичных данных:
npm run build
npm start

Исходники и внедрение первого полезного уведомления

В архиве находятся Compose-конфигурация, инструменты запуска, Node.js-клиент, PHP-клиент, интеграционные тесты, статическая мастерская, исходные записи и примеры Caddy/Nginx. Рабочие токены и базы лаборатории не включены: при запуске создаётся ваше собственное состояние. Авторский код распространяется по MIT, зависимости сохраняют свои лицензии.

Выберите одну длительную операцию в своём сервисе. Сформулируйте короткое сообщение о результате, определите адрес защищённой страницы и выдайте интеграции только право публикации в нужную тему. Проверьте успешный случай, отказ доступа, временную недоступность сервера и повтор отправки. Затем подключите реального получателя и проверьте, помогает ли уведомление его работе.

Для продолжения используйте документацию ntfy, репозиторий проекта и справочник конфигурации. Уведомление должно оставаться понятной частью процесса: сообщение сообщает о факте, приложение хранит достоверные данные, а получатель понимает следующее действие.