Назад в блог

Надёжные push-уведомления на iPhone из self-hosted стека

Надёжные push-уведомления на iPhone из self-hosted стека

В 3 часа ночи срабатывает алерт Grafana. В логах сервера видно, что вызов вебхука прошёл успешно. iPhone молчит. Self-hosted мониторинг хорошо находит сбои. Самое слабое место большинства домашних лабораторий — доставка сообщения на телефон.

Этот гайд объясняет, почему push-уведомления на iPhone из self-hosted стека доставлять так сложно, как выглядит надёжная схема и как подключить Grafana, Uptime Kuma, n8n, cron-задачи и shell-скрипты. Первый рабочий алерт занимает около пяти минут.

Почему push-уведомления на iOS ломаются в self-hosted системах

Достучаться до iPhone может только APNs

Любой push на iPhone проходит через Apple Push Notification service (APNs). Ваш сервер не может открыть соединение с телефоном и отправить данные напрямую. Телефон держит одно долгоживущее соединение с Apple. Ваш сервер отправляет каждое сообщение в APNs по HTTP/2, аутентифицируясь ключом из вашего аккаунта разработчика Apple. APNs доставляет его по уже существующему соединению телефона.

Значит, в вашей схеме нужен посредник, который умеет работать с APNs. Телефон не опрашивает ваш сервер, поэтому обычный эндпоинт вебхука в локальной сети доставить ничего не может. Подробнее о пути доставки читайте в статье как push-уведомления доходят до iPhone.

Собственный отправитель требует больше работы, чем кажется

С APNs можно работать напрямую. Понадобятся ключ подписи (файл .p8 для токен-аутентификации, который не истекает раз в год, либо TLS-сертификат клиента для каждого приложения, который истекает), зарегистрированное приложение, хранилище токенов устройств и код, который обрабатывает ошибки APNs и повторные отправки. Нужно также iOS-приложение, которое регистрирует устройство и показывает уведомление. Каждую часть по отдельности поддерживать несложно. Настоящая цена в том, чтобы всё это продолжало работать при ротации ключей и изменениях политики Apple.

Большинству self-hosted пользователей нужен результат, а не инфраструктура. Размещённый сервис, который уже берёт на себя сторону APNs, позволяет оставить ваш стек простым: один HTTP-запрос на один алерт.

Фокусирование, беззвучный режим и уровни прерывания

iOS решает, насколько громко доставить каждое уведомление, исходя из его уровня прерывания, ваших режимов Фокусирования и настроек приложения. Для алертов важны три вещи:

  1. Уведомления должны быть разрешены для приложения. Проверьте это в первую очередь в настройках iOS. Приложение с отключёнными уведомлениями никогда не покажет ваш алерт, как бы ни вёл себя сервер.
  2. Срочные уведомления могут пробиться через Фокусирование. В Pocket Alert сообщения с high приходят как срочные. Более низкие уровни ждут окончания Фокусирования.
  3. Критические алерты игнорируют переключатель беззвучного режима и режим «Не беспокоить». Для них нужно специальное право, которое Apple выдаёт после проверки. В Pocket Alert оно есть: сообщения с critical на платных тарифах проигрывают звук, даже когда телефон в беззвучном режиме, при условии что вы разрешили для приложения критические уведомления. Если вы отключили это разрешение, такие сообщения придут как срочные.

Как задать уровень, описано в разделе о приоритетах ниже.

Как выглядит надёжная схема

Ваш стек обнаруживает проблему и отправляет один HTTP-запрос. Дальше работу берёт размещённый сервис:

Grafana / Uptime Kuma / n8n / cron + CLI
        │  HTTPS (API call or webhook)
        ▼
Pocket Alert  ──►  APNs  ──►  iPhone (Pocket Alert app)

Распределение работы выглядит так:

Ваш стек делаетPocket Alert делает
Обнаруживает сбой и решает, что важноПринимает запрос и проверяет ваш API-ключ или URL вебхука
Формирует текст или отправляет собственный JSONСопоставляет поля, задаёт уровень приоритета и доставляет в APNs
Отправляет событие один раз, когда оно происходитОтправляет push на все устройства аккаунта или на указанное вами устройство
Ведёт собственные логиХранит историю сообщений и журнал запросов для каждого вебхука, чтобы вы видели, что пришло и что не сработало

Отправьте первый алерт через curl

Зарегистрируйтесь на pocketalert.app/signup, откройте API-ключи и нажмите Create New Key. Ключ показывается один раз, поэтому скопируйте его в надёжное место.

Сохраните его в переменную окружения и отправьте сообщение:

export PA_KEY="YOUR_API_KEY"

curl -X POST "https://api.pocketalert.app/v1/messages" \
  -H "Token: $PA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Backup finished",
    "message": "nightly-backup on nas01 completed in 14m",
    "level": "high"
  }'

Успешный вызов возвращает JSON с полями tid, title, message, application, device и created_at. Сохраните tid, если потом захотите сопоставить push со строкой в логе.

Три вещи чаще всего вызывают проблемы:

  • Укажите Content-Type. API принимает JSON или multipart/form-data. Он отклоняет application/x-www-form-urlencoded, который отправляет curl -d, если не задать заголовок. Используйте -H "Content-Type: application/json" с JSON-телом или -F для полей формы.
  • title и message обязательны. Всё остальное необязательно.
  • Не указывайте device_id, чтобы дойти до всех устройств аккаунта. Добавьте его, если у вас несколько телефонов и нужен конкретный.

Отправка алертов из командной строки

CLI Pocket Alert — самый быстрый способ подключить алерты к существующим скриптам. Установите его через shell-скрипт, Homebrew или Go:

curl -fsSL https://raw.githubusercontent.com/PocketAlert/cli/main/install.sh | sh
# or
brew install pocketalert/tap/pocketalert
# or
go install github.com/PocketAlert/cli/cmd/pocketalert@latest

Выполните pocketalert auth один раз и вставьте ключ. Ключ сохраняется в ~/.pocketalert/config.json, читать его может только ваш пользователь. На серверах, в контейнерах и CI вместо этого задайте POCKETALERT_API_KEY.

Отправка сообщения:

pocketalert send "Deploy finished" "v2.4.0 is live" --level high

Можно передать вывод команды прямо в алерт:

df -h | pocketalert send "Disk report" --level default

Или обернуть команду через exec. Она запускается как обычно, затем отправляет один push с кодом завершения, длительностью и последними строками вывода и возвращает тот же код выхода:

pocketalert exec -t "Database dump" -- ./dump.sh

Флаг -q выводит только ID сообщения, что удобно для скриптов. Добавьте --json к любой команде, чтобы получить вывод в машиночитаемом формате.

Вебхуки с сопоставлением полей

Если источник уже отправляет JSON, как Grafana, Uptime Kuma или ваш собственный сервис, писать отправитель не нужно. Создайте вебхук в панели на странице Webhooks, и Pocket Alert выдаст URL для приёма вида https://p4a.me/wh/1234abcd. Часть адреса непредсказуема, а каждый URL привязан к одному вебхуку и одному приложению. Направьте источник на этот URL методом POST.

Push придёт с заголовком «Webhook» и именем вебхука, поэтому назовите его по источнику, например Grafana. Шаблон сообщения берёт значения из входящего JSON по путям GJSON:

  • %object.field% для вложенных полей
  • %items.0.name% для элементов массива
  • %users.#% для количества
  • * как весь шаблон отправляет всё тело запроса

Например, для такого входящего payload:

{
  "service": "api-gateway",
  "check": "tls-expiry",
  "state": "warning",
  "detail": "certificate expires in 6 days"
}

шаблон может быть таким:

[%state%] %service%: %check%
%detail%

Плейсхолдер, путь которого отсутствует, превращается в пустую строку, поэтому опечатка проявится как пропуск в тексте, а не как ошибка.

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

Приоритет задаётся двумя способами. Можно указать уровень по умолчанию для вебхука или добавить в payload поле level верхнего уровня, которое переопределит значение по умолчанию. Допустимые значения: silent, low, default, high, critical или числа от -2 до 2. Некорректное level игнорируется, и применяется уровень вебхука по умолчанию.

Интеграции

Алерты Grafana

В панели создайте вебхук с именем Grafana и таким шаблоном сообщения:

[%status%] %commonLabels.alertname% (%commonLabels.severity%)
%alerts.0.annotations.summary%

Скопируйте его URL для приёма. В Grafana перейдите в Alerting → Contact points → Add contact point, выберите интеграцию Webhook и задайте:

Integration: Webhook
URL:         https://p4a.me/wh/1234abcd
Method:      POST

Привяжите contact point к политике уведомлений, чтобы подходящие алерты попадали в него, затем нажмите кнопку Test у contact point. Срабатывающий алерт HighCPU с меткой severity="critical" появится как [firing] HighCPU (critical). Когда он сбросится, тот же push придёт со словом resolved в скобках.

Три замечания. Часть severity пустая, если правила не задают эту метку. Шаблон читает только первый алерт группы (alerts.0), поэтому если одно уведомление объединяет несколько алертов, вы увидите только первое описание. И период ожидания (pending period) у каждого правила, например 5 минут, — самый дешёвый способ не дать «мигающей» метрике будить телефон каждую минуту. Подробнее о полях — в гайде по Grafana.

Uptime Kuma

Uptime Kuma отправляет вебхук при каждом изменении статуса. Добавьте уведомление типа Webhook, укажите в Post URL ваш URL для приёма и оставьте пресет JSON как тело запроса.

В Pocket Alert используйте %msg% в качестве шаблона. Поле msg есть в каждом запросе Uptime Kuma, включая предупреждения о сертификатах и тестовые сообщения, и уже читается как «[Website] [🔴 Down] timeout of 4000ms exceeded». Уровень по умолчанию для вебхука задайте high.

При пресетном теле восстановления приходят так же громко, как и падения, потому что Uptime Kuma сам по себе не добавляет поле level. В гайде по Uptime Kuma показано пользовательское тело, которое отправляет high при падении и low при восстановлении.

n8n

В workflow n8n добавьте узел HTTP Request после шага, который обнаруживает проблему:

  • Method: POST
  • URL: https://api.pocketalert.app/v1/messages
  • Authentication: Generic Credential Type, затем Header Auth. Имя Token, значение — ваш API-ключ.
  • Send Body: включить, Body Content Type — JSON, Specify Body — Using JSON, с выражением, которое собирает весь объект:
{{ JSON.stringify({
  title: 'Disk almost full on ' + $json.host,
  message: $json.detail,
  level: 'high'
}) }}

JSON.stringify экранирует кавычки и переносы строк в значениях, чего не делает простая подстановка "{{ $json.detail }}" внутри строки JSON. Для сбоев во всех workflow настройте error workflow, который начинается с узла Error Trigger: имя упавшего workflow находится в $json.workflow.name, а текст ошибки — в $json.execution.error.message. В гайде по n8n есть готовый workflow для импорта.

Запланированные и регулярные проверки

Cron-задачи падают молча, а пропущенный алерт в этот момент обходится дороже всего. Поместите алерт в саму задачу:

POCKETALERT_API_KEY=YOUR_API_KEY
PATH=/usr/local/bin:/usr/bin:/bin
0 3 * * * pocketalert exec -t "Nightly backup" -- /opt/scripts/backup.sh

Cron не загружает профиль вашей оболочки, поэтому две строки в начале дают задаче ключ и PATH, в котором есть CLI. Успешный запуск придёт как «✓ Nightly backup» с уровнем по умолчанию. Неудачный придёт как «✗ Nightly backup (exit 1)» с уровнем high и последними строками вывода в сообщении. Добавьте --on failure, если хотите получать уведомления только о сбоях.

exec сообщает, когда задача падает, но не когда она не запускается. Для этого используйте dead man's switch, как в гайде по мониторингу cron-задач.

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

Уровни приоритета и критические алерты

Доступно пять уровней, от тихого до громкого:

УровеньЗначениеНа iPhoneТипичное применение
silent-2Без звука, сразу в Центр уведомленийСобытия «Resolved», логи, которые можно посмотреть позже
low-1Пассивное, не включает экранИнформационные
default0Обычное уведомление со звукомРутинные результаты, например завершённый бэкап
high1Срочное, пробивает ФокусированиеТребует внимания в ближайшее время
critical2Критический алерт, звучит даже в беззвучном режимеТребует внимания сейчас. Только платные тарифы

На бесплатном тарифе сообщение critical доставляется как high. Оно по-прежнему приходит сразу как срочное, но уважает переключатель беззвучного режима.

Разумное соответствие для срабатывания алерта и его разрешения:

  • срабатывание: high, или critical для немногих событий, ради которых стоит проснуться
  • разрешение (resolved): silent

Задайте это уровнем по умолчанию для вебхука или полем level в payload, если источник может его отправлять.

Чек-лист: убедитесь, что алерт доходит

  1. Разрешите уведомления для приложения Pocket Alert в настройках iOS, включая «Срочные уведомления» и, на платном тарифе, «Критические уведомления».
  2. Проверьте с включённым Фокусированием. Включите режим Фокусирования, который вы используете, отправьте тестовое сообщение high командой curl из этого гайда и убедитесь, что оно проходит. Если нет, проверьте настройки уведомлений приложения для этого Фокусирования.
  3. Убедитесь, что вызов дошёл до Pocket Alert. API-сообщения отображаются в истории сообщений в приложении и веб-панели. Вызовы вебхука, в том числе отклонённые, видны в журнале запросов этого вебхука. Если вызов там есть, проблема на телефоне. Если нет, проблема в источнике.
  4. Проверьте логи источника на исходящий запрос: URL, код статуса и тело ответа.
  5. Следите за дневным лимитом. На бесплатном тарифе доступно 50 уведомлений в день. «мигающая» проверка может израсходовать их за час, поэтому настройте пороги и периоды ожидания до масштабирования. Команда pocketalert usage показывает, сколько осталось на сегодня.

Если алерт всё равно не приходит, проверяйте шаги по порядку: лог источника, затем история Pocket Alert, затем уровень и настройки устройства. Такой порядок быстро locates сбойное звено.

FAQ

Можно ли отправлять push-уведомления на iPhone без собственной настройки Apple Developer?
Да. Размещённый сервис, который уже подключён к APNs, берёт на себя сторону Apple. Вы отправляете HTTP-запрос со своим API-ключом, а сервис доставляет его в приложение на iPhone. Собственный отправитель требует ключей подписи, регистрации приложения и собственного iOS-приложения.

Почему мои self-hosted алерты приходят с задержкой или не приходят вовсе?
Обычно причин три: уведомления для приложения не разрешены, активное Фокусирование задерживает алерт по его уровню или запрос вообще не дошёл до сервиса. Сначала проверьте историю сообщений или журнал вебхука, чтобы понять, какая из них актуальна.

Пройдут ли алерты, когда включено Фокусирование?
Сообщения high приходят как срочные, которые могут пробиться через Фокусирование, если уведомления разрешены. Сообщения critical на платных тарифах идут дальше и звучат, даже когда телефон в беззвучном режиме. Более низкие уровни ждут. Проверьте собственную настройку Фокусирования, прежде чем полагаться на неё.

Есть ли бесплатный тариф?
Да. Бесплатный тариф включает 50 уведомлений в день, 1 устройство, 1 приложение и 1 вебхук. Критические сообщения на бесплатном тарифе доставляются с высоким приоритетом.

Что дальше

Первый алерт на iPhone можно получить примерно за пять минут:

  1. Зарегистрируйтесь и установите приложение на iPhone.
  2. Создайте API-ключ в разделе API-ключи.
  3. Выполните команду curl из этого гайда.

Когда это заработает, подключите один реальный источник: контактную точку Grafana, уведомление Uptime Kuma или cron-задачу. Другие источники для домашней лаборатории описаны в разделе алерты для homelab и в гайде по Proxmox. Остальные интеграции — в разделах вебхук-уведомления и алерты Grafana. Если сравниваете варианты, на странице альтернатив перечислены различия.

Поделиться статьёй