ntfy

Обзор

ntfy — сервер уведомлений по модели publish/subscribe. Задание резервного копирования, проверка доступности или домашний скрипт отправляет HTTP-запрос в тему; подписанные клиенты получают сообщение в браузере или мобильном приложении. Приоритет, заголовок, теги и вложение добавляют контекст, нужный для действия.

Для чего подходит

Для личного мониторинга и автоматизаций, если вы готовы поддерживать сервер уведомлений самостоятельно. Он закрывает обычные сценарии отправки и подписки в духе Pushover. HTTPS, учётные записи, доступность, хранение и путь доставки на телефон или в браузер становятся вашей задачей; кэш уведомлений не заменяет постоянный архив.

Рецепт запускает закреплённый официальный образ с UID/GID 1000 и корневой файловой системой только для чтения. Инициализатор готовит один именованный том. SQLite-базы сообщений и доступа хранятся вместе с вложениями; вход обязателен, регистрация отключена, чтение и отправка в темы без явного разрешения запрещены. Администратор создаётся из закрытой декларативной bcrypt-записи до обслуживания запросов.

Данные и пределы доставки

Сообщения и вложения кэшируются семь дней. Учётные записи, токены, ACL тем, подписки и настройки аккаунтов сохраняются в том же томе; веб-клиент дополнительно хранит локальный кэш IndexedDB. Серверный backup не копирует профиль браузера. Восстановленное вложение сохраняет исходный срок истечения.

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

Smoke проверяет живого HTTP-подписчика, настоящую отправку, чтение кэша, аккаунты, ACL токена, байты вложения и восстановление после удаления тома. Отдельно подтверждает скачивание вложения без входа по известному URL. Физический телефон и фоновая браузерная доставка не проверялись.

Клиенты и дополнительные сервисы

Upstream предлагает браузерный клиент и официальные приложения Android/iOS. Открытый браузер получает сообщения напрямую. Android может подключаться к серверу напрямую; Firebase — отдельный путь доставки. Для мгновенных уведомлений iOS со своего сервера нужен upstream-polling, обычно через ntfy.sh; Web Push при закрытом браузере требует VAPID-ключей и push-сервисов браузера. Рецепт не настраивает эти ретрансляторы, SMTP, звонки и внешнее хранилище. Перед включением изучите сетевые требования и приватность; серверный smoke не подтверждает фоновую мобильную доставку.

Безопасность и сопровождение

Оставляйте веб-порт на loopback или за доверенной VPN/прокси. Для публикации используйте HTTPS, защищайте .env, разрешайте автоматизациям только нужные темы и шифруйте внешние копии. В этой версии нет встроенных OIDC, SAML, MFA и входа по заголовку пользователя прокси. Доверие forwarded-IP выключено, поэтому запросы через прокси делят его лимит.

Декларативный хэш администратора применяется при каждом запуске. Меняйте его явно и сохраняйте соответствующее окружение для восстановления. Обычные аккаунты и токены, созданные штатными CLI/API, хранятся в SQLite и входят в backup.

Upstream использует двойную лицензию Apache-2.0/GPLv2, рецепт — MIT. Иконка каталога взята из исходного mask-ресурса по варианту Apache-2.0; лицензия сохранена в ASSET-LICENSES.md.

Источники: v2.34.0, настройки и доступ, отправка, подписки, лицензия.

Пошаговая инструкция

Требования и доступ

Используйте Ubuntu 22.04+ или Debian 12+ на amd64/arm64 с Docker Engine и Compose v2.24+. Минимум — 1 CPU, 128 МБ RAM (рекомендуется 256 МБ), 2 ГБ диска плюс рост кэша и внешние копии. Проверена только amd64.

Скопируйте рецепт целиком со скриптами и proxy/. Создайте .env с правами 600, выберите уникальный сильный пароль администратора и получите его хэш закреплённым образом:

cp .env.example .env
chmod 600 .env
docker run --rm -it binwiederhier/ntfy:v2.34.0 user hash

Запишите выведенный хэш в .env: NTFY_AUTH_USERS='ntfyadmin:<bcrypt-хэш>:admin'. Одинарные кавычки сохраняют буквальные $; в .env не удваивайте их. Сам открытый пароль сохраните в менеджере паролей. Не вставляйте хэш непосредственно в Compose: там правила экранирования отличаются.

Запуск и проверка

Скрипты загружают .env как доверенную shell-конфигурацию; не используйте чужой непроверенный файл. Инициализатор готовит том, затем ntfy работает с UID/GID 1000 и корневой ФС только для чтения. Запустите сервер и войдите как ntfyadmin с паролем, для которого получали хэш:

docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 180
curl --fail http://127.0.0.1:8083/v1/health

Откройте NTFY_URL, войдите и подпишитесь на тему household. Отправьте пробное сообщение; curl запросит пароль без записи в команду:

curl --fail -u ntfyadmin -d 'Test notification' http://127.0.0.1:8083/household

VPS

Задайте внешний HTTPS origin в NTFY_URL и поставьте прокси хоста перед loopback-портом 8083. Оставьте открытыми только SSH/HTTP/HTTPS, проверьте вход и запрет анонимного доступа к темам, храните зашифрованную копию вне VPS. Страница интерфейса может загружаться до входа, но данные закрытых тем анонимно не читаются.

Доверенная локальная сеть

Используйте ssh -L 8083:127.0.0.1:8083 user@server с соответствующим локальным URL либо HTTPS-прокси для LAN/VPN. При явной привязке к приватному IP хоста ограничьте доступ firewall. Не отключайте авторизацию. Даже для приватной темы URL вложения остаётся ссылкой доступа.

Домен и HTTPS

Задайте NTFY_URL=https://notify.example.com и пересоздайте сервис. В proxy/ есть примеры Caddy, Nginx и Traefik на хосте для 127.0.0.1:8083. Caddy управляет сертификатами; Nginx требует пути к ним; Traefik — websecure и resolver letsencrypt. Контейнерному прокси нужны общая сеть и внутренний порт 8080 вместо собственного loopback. Сохраните websocket-upgrade и потоковую передачу; буферизация Nginx выключена, лимит запроса — 15 МБ. Доверие IP-заголовкам выключено, поэтому пользователи делят лимит IP прокси; включайте доверие только когда сервис доступен лишь настоящему прокси, а входные заголовки очищаются.

Аккаунты и хранение

Декларативная запись администратора применяется при каждом запуске. Для смены пароля получите новый хэш, обновите NTFY_AUTH_USERS в одинарных кавычках и пересоздайте ntfy. Автоматизациям создавайте обычные аккаунты с явными разрешениями тем; выполните интерактивные команды и создайте токен в UI этого аккаунта:

docker compose exec ntfy ntfy user add backupjob
docker compose exec ntfy ntfy access backupjob backups rw

Кэш сообщений и вложения хранятся семь дней; общий кэш файлов ограничен 1 ГБ, один файл — 15 МБ. Удаление браузерной истории не удаляет серверный кэш. URL вложений можно передавать другим, поэтому считайте их секретами и шифруйте чувствительные файлы до загрузки. Web Push, iOS upstream-polling, Firebase, SMTP и звонки не включены; фоновую доставку настройте и проверьте отдельно по официальной документации.

Резервное копирование

Запустите ./backup.sh. Скрипт останавливает запись и сохраняет весь том, .env и Compose в один backups/ntfy-.tar с правами 600. Внутри — cache.db, user.db, вложения, настройки аккаунтов, подписки, ACL, токены и хэш администратора. Прежнее состояние работы/остановки сохраняется. Зашифруйте архив и перенесите вне сервера; живая SQLite-база или только экспорт браузера не являются полной копией.

Восстановление

Восстановление заменяет текущий том. Используйте доверенную копию, соответствующий закреплённый тег и NTFY_AUTH_USERS из архивной configuration.env. До восстановления сравните сохранённое окружение вручную; оно не активируется автоматически. На новом хосте сначала инициализируйте соответствующий рецепт. Скрипт проверяет содержимое и имена обеих баз, делает страховочную копию, останавливает запись и заменяет данные. При ошибке замены ntfy остаётся остановленным.

docker compose up -d --wait --wait-timeout 180
./restore.sh ./backups/ntfy-TIMESTAMP.tar
curl --fail http://127.0.0.1:8083/v1/health

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

Обновление

Прочитайте release notes, сделайте внешнюю копию и задайте проверенный фиксированный тег NTFY_VERSION. Выполните docker compose pull и docker compose up -d --wait --wait-timeout 180, проверьте журналы, вход и отправку/подписку обычным аккаунтом. Миграции SQLite выполняются при запуске. Сохраните учётные данные и проверьте совместимость клиентов; не используйте latest.

Откат

Не запускайте старый сервер на базе после миграций новой версии. Остановите ntfy, задайте прежний фиксированный тег и соответствующую NTFY_AUTH_USERS в .env, загрузите и пересоздайте контейнер без запуска, затем восстановите полную копию до обновления. Страховочная копия читает остановленный том до замены. Сохраните архив неудачной установки до подтверждения восстановления.

docker compose stop ntfy
# Set the old pinned version and matching NTFY_AUTH_USERS in .env.
docker compose pull ntfy
docker compose create ntfy
./restore.sh ./backups/ntfy-BEFORE-UPDATE.tar

Остановка и удаление

docker compose down сохраняет именованный том. После проверки зашифрованной внешней копии docker compose down --volumes навсегда удаляет сообщения, вложения, аккаунты, токены, ACL и настройки. Удаление каталога рецепта также удаляет .env и локальные копии.

Источники: configuration, Docker installation, publishing, subscription clients, v2.34.0.

Сообщить о проблеме с рецептом

Рассказать, как прошло на вашем сервере

Откроется предзаполненный issue на GitHub. Нужен аккаунт GitHub; после отправки сообщение будет публичным.

Диагностика

Ошибка запуска или healthcheck

Выполните docker compose config --quiet, docker compose ps и docker compose logs --tail=100 ntfy permissions. Проверьте успешное завершение инициализатора и запись в том для UID/GID 1000. /v1/health должен вернуть healthy true. Неверная bcrypt-запись блокирует запуск: получите её через user hash закреплённого образа и заключите в одинарные кавычки в .env. Не вставляйте открытый пароль или хэш с неэкранированными долларами.

Ошибка входа, токена или доступа к теме

Входите с именем до первого двоеточия в NTFY_AUTH_USERS. Хэш декларативный и применяется при каждом запуске; правка заметки с открытым паролем или CLI-смена пароля предопределённого пользователя его не меняет. Автоматизациям создавайте обычные аккаунты, проверяйте docker compose exec ntfy ntfy user list и разрешайте только нужные темы через ntfy access. Токен получает ACL владельца. Имя темы не является учётными данными.

В открытой странице сообщения есть, в фоне — нет

Серверный smoke подтверждает HTTP-доставку, не системный push. Проверьте URL сервера в клиенте, вход, сеть и разрешения уведомлений. Browser Web Push требует HTTPS/VAPID и push-сервисов браузера; мгновенный push собственного сервера на iOS — upstream-polling; у прямого подключения Android есть требования к фоновому режиму и батарее. Рецепт эти интеграции не настраивает. Используйте официальную настройку клиента, не отключайте авторизацию.

Неверная ссылка вложения или скачивание без входа

Задайте в NTFY_URL точный внешний origin, пересоздайте ntfy и проверьте новое пробное вложение. URL намеренно работает как ссылка доступа без входа; ACL темы не защищает утёкшую ссылку. Шифруйте чувствительные файлы до загрузки. Сообщения и вложения истекают через семь дней, восстановление сохраняет исходные сроки. Проверьте диск и лимиты: 1 ГБ суммарно и 15 МБ на файл.

Обрывы прокси или rate limit

Сохраните websocket-upgrade и потоковый HTTP, выключите буферизацию прокси и задайте большой read timeout. Пока доверие forwarded-IP выключено, запросы делят лимит IP прокси. Держите порт 8083 закрытым; контейнерный прокси не достигает сервиса хоста через собственный 127.0.0.1. Не доверяйте произвольному X-Forwarded-For ради обхода лимитов.

Пропавшие данные после восстановления

Проверьте, что полный архив содержит обе SQLite-базы и вложения; сравните configuration.env вручную до восстановления. Несоответствующая NTFY_AUTH_USERS перекроет восстановленные учётные данные администратора. На время проверки сохраните текущий том и страховочную копию; истёкший кэш после восстановления не становится свежим. Повторите чтение сообщения и вложения, вход обычного пользователя и проверку ограниченного токена.

Источники: настройки, отправка, подписки.