Уведомитель

Уведомитель (Nexora Notif) — официальное дополнение, которое сообщает пользователям вашей панели об их учётных записях: о приближении даты окончания, заканчивающемся трафике, продлении, добавленном трафике, а также рассылает ваши собственные сообщения одному пользователю или группе. Он отправляет через Telegram, Bale, Soroush Plus, Rubika, SMS, почту, ntfy или любой HTTP API. Эта страница описывает установку, каналы, что и когда отправляется и ваши собственные сообщения.

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

Уведомление пишется один раз и передаётся каналам пользователя в заданном вами порядке. Следующий канал пробуется, только если предыдущий не смог доставить: у пользователя там нет адреса, канал отказал (заблокированный бот, несуществующий номер) или три попытки не удались. Платное SMS уходит, только когда бесплатные каналы не дошли до пользователя, и никто не получает одно уведомление дважды.

Уведомитель читает панель с ограниченным токеном и получает подписанные события панели. Привязки мессенджеров каждого пользователя он хранит в контактной карточке учётной записи в панели (telegram_id, bale_id, soroush_id, rubika_id), где их видят и другие дополнения, и страница пользователей.

Установка

В панели: Дополнения → Каталог → Nexora Notif → Установить. Панель задаёт его вопросы и устанавливает его на свой сервер или на другой по SSH либо даёт команду для запуска. Все способы установки описаны в Каталог дополнений.

Вопрос	Что задаёт
Порт	По умолчанию 8097. С включённым HTTPS — единственный порт уведомителя.
База данных	SQLite или PostgreSQL со строкой подключения.
Первый администратор	Имя и пароль от 10 символов до 72 байт.
Путь админки	Всё, что отдаёт уведомитель, находится под ним. Выбирается случайно; пусто — в корне.
Публичный адрес	Где вы открываете уведомитель: схема, хост и порт.
HTTPS	panel (по умолчанию в форме панели), acme, acme-http, self-signed или off, как у любого дополнения (Каталог дополнений).

Вручную, на Linux-сервере от root:

sh install.sh --method docker --opt port=8097 --opt admin_password=… \
  --panel-url https://panel.example.com --claim-code …

--method script запускает бинарный файл под systemd вместо Docker. Повторный запуск той же команды обновляет на месте; --uninstall удаляет, а --purge удаляет ещё и данные.

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

Настройка

Войдите по публичному адресу с путём админки, https://<host>:<port>/<path>/. Корень адреса ничего не отвечает. Настройка — это список дел самого уведомителя: двухфакторный вход, первый канал, резервные копии. Он также отмечает то, что установка из панели оставила неверным: отсутствующий адрес или адрес на простом HTTP, регистрацию или пароль, оставшийся от установки, — он лежит в .env открытым текстом. Смените этот пароль первым делом.

Потерянный пароль сбрасывается на сервере:

notif admin reset-password -user admin -pass …

Каналы

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

Telegram, Bale и Soroush Plus

Все три используют один и тот же вид ботов. Создайте бота через BotFather каждого мессенджера и вставьте его токен.

Дайте уведомителю собственных ботов

Обновления бота может читать только одна программа. Токен, который уже использует Shop или другой инструмент, делить нельзя; если это так, канал сообщит об этом.

• Telegram: если ваш сервер не может достучаться до API Telegram, задайте Прокси (socks5://host:port) или зеркало Bot API как адрес API. Прокси на этом сервере, на хосте Docker или в вашей локальной сети нужно указать при установке в поле Разрешённые прокси ботов.
• Bale: Bale замедляет бота, который пишет пользователям вне диалога. Для уведомлений предназначен его платный бизнес-API; включите его в канале, когда пополните бизнес-аккаунт Bale.
• Soroush Plus: работает как Telegram, по собственному адресу API.

Rubika

У Rubika свой API ботов, и уведомитель его поддерживает. Её API может отклонять серверы за пределами Ирана: дайте каналу прокси внутри Ирана или адрес посредника там.

Привязка пользователей к боту

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

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

SMS

Kavenegar и Faraz SMS встроены. Оба отправляют по одобренному шаблону через сервисную линию, которая доходит и до номеров, блокирующих рекламные SMS. Напишите шаблон в панели провайдера и получите одобрение, затем укажите уведомителю, какая переменная шаблона что несёт, по одной в строке, например token={name}. Для Faraz SMS также укажите длину каждой переменной в шаблоне (name=20); уведомитель обрезает каждое значение до этой длины, потому что более длинное сообщение Faraz отправляет на ручную проверку, хотя и отвечает «отправлено».

Номер телефона берётся из поля phone контактной карточки, записанного так, как его ввёл оператор. Другие SMS-провайдеры работают через общий HTTP-канал, описанный ниже.

Почта

Любой SMTP-сервер: хост, порт (587 со STARTTLS, 465 с TLS), пользователь, пароль и отправитель. Письма — простой текст. Адрес берётся из поля email карточки.

Отправляйте со своего домена

Настройте SPF, DKIM и DMARC для домена отправителя. QQ Mail, 163, Mail.ru, Yandex и Gmail отклоняют или прячут письма, которые не могут проверить.

ntfy

ntfy — push-приложение, которое пользователи ставят сами. Включите ntfy для пользователя на его странице в разделе Аккаунты: уведомитель выберет тему, которую никто не угадает, сохранит её в карточке как ntfy и покажет адрес, который нужно передать пользователю. Кто знает адрес, тот может его читать, поэтому передавайте его только этому пользователю. На Android-телефонах без сервисов Google пользователи включают в приложении instant delivery.

Общий HTTP-канал

Любой провайдер с HTTP API: адрес, метод, заголовки и тело, каждое — шаблон над уведомлением, и поле контакта, где хранится адрес пользователя у этого провайдера (phone или ваш собственный ключ, например vk_id). Ключ провайдера указывается в поле Секрет и никогда не попадает в журнал. Тело — JSON, форма или ничего; есть HTTP Basic-аутентификация, Признак успеха для провайдеров, которые отвечают 200 на ошибку, и сертификат CA для частного провайдера.

Шаблоны могут использовать текст и заголовок уведомления, адрес и имя пользователя, секрет, идентификатор уведомления и переменные уведомления, а также функции, которые форматируют номер телефона в международном или местном виде.

Готовые настройки в поле Начать с заполняют всё для SMS.ru, SMSC, SMS Aero, MTS Exolve, VK, LINE, Matrix и Pushover; замените написанное заглавными буквами. WhatsApp доступен через посредника по вашему выбору на этом канале.

Адреса, которые уведомитель отклоняет

Адрес каждого канала (и прокси бота) должен быть в публичном интернете. Для посредника или собственного сервера в частной сети (локальная сеть, WireGuard, Tailscale, контейнер рядом с уведомителем) включите в канале Адрес в моей сети. Собственный сервер уведомителя и служба метаданных облака отклоняются даже тогда; вместо этого запустите локальный посредник на другой машине своей сети. В Docker при включённом переключателе хост доступен как host.docker.internal.

Уведомления

Уведомления содержит ваше Расписание — за сколько дней до окончания (например, 5, 1) и при какой доле трафика (например, 80, 95) пользователь получает уведомление — и все виды уведомлений, каждое можно включить или выключить:

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

Текст открывает текст уведомления для каждого языка и, когда одному каналу нужны другие слова, например короткое SMS, для каждого вида канала. Пустое поле оставляет текст по умолчанию. Нажмите на переменную, чтобы её добавить: {name}, {expiry}, {days}, {traffic_total}, {traffic_used}, {traffic_left}, {percent}, {added}, {sub_url}, {group}. Предпросмотр показывает текст для учётной записи-образца.

Язык пользователя — поле lang его карточки (fa, en, ru или zh), иначе язык из Настройки. Для персидского языка даты по умолчанию идут по персидскому календарю; один календарь для всех выбирается в Даты. Тихие часы в Настройки задерживают уведомление до их окончания; ничего не теряется, а уведомление с пометкой срочно проходит и в тихие часы.

Сообщения

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

1. Подсчитать показывает, сколько учётных записей подходит, какой канал доставит каждой, сколько из них SMS и до скольких не дойдёт ни один канал, вместе с сообщением в том виде, в каком его прочтёт первая учётная запись.
2. Отправить переспрашивает ещё раз и называет число SMS.
3. Сообщение уходит в фоне со скоростью каналов. Ещё не ушедшее можно отменить. Отчёт показывает, что отправлено, каким каналом и что не удалось.

На странице учётной записи видно, что ей отправлялось.

Выбор порядка каналов

Страна	Доходит до пользователя с включённым VPN	Доходит до пользователя с выключенным VPN
Иран	Telegram, все остальные каналы	Bale, Soroush Plus, Rubika, SMS, почта
Россия	Telegram, почта, ntfy	Почта (Mail.ru и Yandex остаются доступны в режиме мобильных белых списков); SMS для оператора с российским юрлицом
Китай	Telegram, ntfy, почта	Почта (QQ Mail, 163)

Хороший порядок ставит первым бесплатный канал, который пользователи читают, а SMS или почту — последними: в Иране Telegram, затем Bale, затем SMS; в России и Китае Telegram, затем ntfy, затем почта. Пишите в уведомлениях только об учётной записи: тексты по умолчанию не содержат цен, предложений и слова VPN, что важно там, где за рекламу способов обхода блокировок штрафуют и где SMS-провайдеры это запрещают.

Журнал, приватность и резервные копии

Журнал перечисляет все доставки с попыткой каждого канала и его ответом. Завершённые доставки вместе с текстом удаляются через число дней, заданное в Настройки (по умолчанию 90). Уведомитель хранит копию имени, контактной карточки, даты окончания и трафика каждой учётной записи, чтобы решать, когда и что писать; секретная часть ссылки подписки хранится только в виде хеша.

На SQLite уведомитель раз в день копирует свою базу в <data>/backups, храня семь копий. Вручную — notif backup -o notif.db, а при остановленном уведомителе — notif restore -i notif.db. На PostgreSQL резервируйте базу через pg_dump.

Если что-то не так

Что вы видите	Что это значит
Канал бота сообщает, что его обновления читает другая программа	Токен используется в другом месте (Shop, вебхук). Дайте уведомителю собственного бота.
Нет адреса в журнале	В карточке пользователя ничего нет для этого канала; уведомление переходит к следующему каналу.
No channel reached the user	Перепробованы все каналы; попытки в журнале объясняют, почему не удался каждый.
Для учётной записи ничего не поставлено в очередь	Ни у одного включённого канала нет для неё адреса. Привяжите бота или добавьте в карточку телефон или почту.
Not public у канала	Его адрес на этом сервере или в частной сети. См. Адреса, которые уведомитель отклоняет.
Неизвестно в журнале	Провайдер принял запрос, а его ответ потерялся. Возможно, сообщение отправлено, поэтому повторно оно не отправляется.

Если у вас работает и Shop, выключите в Shop собственные напоминания об учётных записях, чтобы клиенты не получали одно и то же уведомление дважды.