Notific 1.0.0

Notific — автономная система для планирования и доставки уведомлений через Telegram, MAX, Matrix и SMS через Huawei HiLink-модем. Одно уведомление можно отправлять сразу в несколько чатов, каналов, комнат и на несколько телефонных номеров, поэтому Notific подходит для личных, семейных, командных и служебных сценариев.

Приложение устанавливается на обычный сервер с PHP, хранит данные в SQLite и не требует отдельного сервера базы данных или облачного сервиса.

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

• разовые и повторяющиеся уведомления;
• личные напоминания;
• сообщения в семейные или групповые чаты;
• уведомления небольшой команды;
• сообщения о регламентных работах, событиях и сроках;
• одновременная доставка одного сообщения в несколько разных мессенджеров;
• резервная доставка по нескольким каналам.

Notific не является системой массового маркетинга: в нём нет базы подписчиков, сегментации аудитории и рассылок по спискам получателей. Получателем служит настроенный чат, канал, комната Matrix или отдельный телефонный номер.

Возможности

• расписания once, interval, daily, weekly и monthly;
• отдельный часовой пояс для каждого уведомления;
• политика обработки пропущенного времени запуска;
• несколько каналов доставки на одно уведомление;
• Telegram Bot API;
• MAX Bot API;
• Matrix Client-Server API;
• SMS через Huawei HiLink API, с отдельным адресом модема для каждого канала;
• проверка сохранённой конфигурации канала;
• история срабатываний и фактических результатов доставки;
• состояние uncertain, если результат внешней отправки нельзя определить однозначно;
• повторные попытки для ошибок, при которых отправку можно безопасно выполнить ещё раз;
• имя пользователя и пароль;
• двухфакторная аутентификация TOTP (2FA) и одноразовые коды восстановления;
• изменение учётных данных и двухфакторной аутентификации из веб-интерфейса;
• встроенное ограничение частоты запросов;
• доверенные клиентские сети и обратные прокси-серверы;
• шифрование токенов каналов и TOTP-секрета;
• локальные CSS, JavaScript и SVG без внешних CDN.

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

Требования

• PHP 8.3 или новее;
• Composer 2;
• расширения PHP: curl, iconv, json, mbstring, openssl, pdo, pdo_sqlite, sodium, xmlwriter;
• HTTPS;
• возможность периодически запускать bin/worker.php --once и bin/maintenance.php.

Рекомендуется PHP 8.4. Полный список требований находится в composer.json.

Быстрый старт

Пример установки в /var/www/notific:

cd /var/www/notific
composer install --no-dev --prefer-dist --no-interaction --no-plugins --no-scripts --optimize-autoloader --classmap-authoritative
chown -R www-data:www-data data
chmod 0700 data
php bin/bootstrap-token.php

Корневой каталог сайта в настройках веб-сервера должен указывать только на:

/var/www/notific/public

После настройки HTTPS откройте:

https://notific.example.com/install.php

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

Пример конфигурации Nginx: deploy/nginx/notific.conf.example.

Фоновые задачи

Один проход очереди доставки:

php bin/worker.php --once

Обычно его запускают каждые 5–15 секунд внешним планировщиком.

Служебная очистка:

php bin/maintenance.php

Примеры служб и таймеров systemd находятся в deploy/systemd/.

SMS через Huawei HiLink

Каждый SMS-канал хранит собственный HTTP/HTTPS-адрес Huawei HiLink-модема. Поэтому разные SMS-каналы могут отправлять через разные физические модемы. В форме канала указываются адрес модема и номер получателя в международном формате E.164.

Для новой установки типичный адрес физического модема:

http://192.168.8.1

NOTIFIC_HUAWEI_MODEM_URL задаёт адрес модема по умолчанию. Для конкретного SMS-канала можно указать отдельный modem_url; если он задан, используется именно он:

NOTIFIC_HUAWEI_MODEM_URL=http://192.168.8.1
NOTIFIC_HUAWEI_SMS_GAP_MS=1000
NOTIFIC_HUAWEI_MODEM_LOCK_WAIT_MS=20000

Если NOTIFIC_HUAWEI_MODEM_LOCK_FILE не задан, для адреса модема по умолчанию используется файл блокировки huawei-modem-api.lock, а для дополнительных адресов модемов создаются отдельные файлы блокировки, имена которых зависят от хэша адреса. Если NOTIFIC_HUAWEI_MODEM_LOCK_FILE задан явно, один общий файл блокировки используется для всех SMS-модемов этой установки.

После подтверждённой отправки Notific выдерживает паузу NOTIFIC_HUAWEI_SMS_GAP_MS, чтобы запись успела появиться в Sent, а затем пытается безопасно удалить техническую копию сообщения. Ответ sms-list принимается только при строгой структуре response/Count/Messages/Message; XML-комментарии, CDATA, DTD/PI, неожиданная иерархия, дубли обязательных полей и некорректный XML не могут стать основанием для delete-sms. До отправки и после неё читается только BoxType=2. Удаление разрешается лишь при доказанно полном снимке первой страницы: возвращено меньше ReadCount=50, Count точно совпадает с числом записей, найден ровно один новый Index, а номер получателя и нормализованный текст совпадают. Полная страница, неполный или сомнительный снимок, неоднозначность либо ошибка чтения/удаления приводят к пропуску очистки; уже подтверждённая SMS остаётся в состоянии sent. Доступ к входящим сообщениям для этой логики не нужен.

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

Поддерживается классический XML API Huawei HiLink с SesTokInfo, sms-list, send-sms и delete-sms. Прошивки, требующие отдельной авторизации через веб-интерфейс модема или использующие шифрованный вариант HiLink API, в версии 1.0.0 не поддерживаются.

Рабочие данные

По умолчанию Notific использует каталог data/. Его можно вынести из дерева приложения:

NOTIFIC_DATA_DIR=/var/lib/notific

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

data/database/notific.sqlite3
data/secrets/master.key
data/runtime/installed.lock

База, master.key и installed.lock относятся к одной установке и должны резервироваться вместе. Для обычного резервного копирования проще сохранять весь каталог рабочих данных.

Документация

• DEPLOYMENT.md — установка, PHP-FPM, systemd, резервное копирование, восстановление и обновление;
• SECURITY.md — модель безопасности и важные настройки;
• ARCHITECTURE.md — устройство приложения и жизненный цикл доставки;
• CHANGELOG.md — изменения по версиям.

Лицензия

Код распространяется по PolyForm Noncommercial License 1.0.0.

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

Юридически действует полный текст LICENSE.

Сторонние зависимости перечислены в THIRD-PARTY.md.

Автор

Разработка: Виталий Егоров
E-mail: egorowitaliy@gmail.com