Files

T

austnv c733d830f6 docs: add to deploy/emaples

2026-06-04 13:07:26 +03:00

8.9 KiB

Raw Blame History

Вход по email

Email-вход позволяет пользователю зарегистрироваться или войти в Mini App без Telegram. Пользователь вводит email, получает одноразовый код и может подтвердить вход кодом или magic link из письма. После входа email можно связать с Telegram-аккаунтом в настройках профиля.

Аккаунты только с email не получают права администратора: админка проверяет Telegram ID из ADMIN_IDS.

Когда форма появляется

Кнопка входа по email показывается только если заполнены все обязательные SMTP-настройки:

SMTP_HOST=smtp-relay.brevo.com
SMTP_PORT=587
SMTP_USERNAME=<smtp-login>
SMTP_PASSWORD=<smtp-password-or-api-key>
SMTP_FROM_EMAIL=no-reply@domain.com

Если хотя бы одно из этих полей пустое, backend вернет email_auth_enabled=false в bootstrap, а frontend скроет email-login.

Для magic link также нужен корректный SUBSCRIPTION_MINI_APP_URL, потому что ссылка в письме строится на его основе.

SMTP-настройка

Типовой пример:

SMTP_HOST=smtp-relay.brevo.com
SMTP_PORT=587
SMTP_FALLBACK_PORTS=2525,465
SMTP_TIMEOUT_SECONDS=30
SMTP_STARTTLS=True
SMTP_USE_SSL=False
SMTP_USERNAME=<smtp-login>
SMTP_PASSWORD=<smtp-password-or-api-key>
SMTP_FROM_EMAIL=no-reply@domain.com
SMTP_FROM_NAME=Remnawave Minishop

EMAIL_CODE_TTL_SECONDS=600
EMAIL_CODE_RESEND_SECONDS=60
EMAIL_CODE_MAX_ATTEMPTS=5
BRUTE_FORCE_MAX_FAILURES=5
BRUTE_FORCE_WINDOW_SECONDS=900
BRUTE_FORCE_LOCK_SECONDS=900

Для Brevo обычно подходит порт 587 с STARTTLS. Если основной порт недоступен, приложение пробует порты из SMTP_FALLBACK_PORTS; порт 465 используется через SSL wrapper автоматически.

SMTP_FROM_EMAIL должен быть подтвержден у SMTP-провайдера, иначе письмо часто отклоняется или попадает в спам. SMTP_FROM_NAME можно оставить пустым, тогда используется название Web App.

Полный справочник переменных: SMTP и вход по email.

Как работает вход

Пользователь вводит email в форме входа.
Backend проверяет rate limit и создает одноразовый код.
Письмо отправляется через SMTP. Если SUBSCRIPTION_MINI_APP_URL валиден, в письме также есть magic link.
Пользователь вводит код в Mini App или открывает magic link.
Backend создает нового email-пользователя или находит существующего по email.
Если в URL был referral-параметр, он применяется к новой или существующей записи.
Пользователь получает Web App-сессию.

Коды хранятся в базе в хешированном виде, устаревают по EMAIL_CODE_TTL_SECONDS, повторная отправка ограничена EMAIL_CODE_RESEND_SECONDS, а количество попыток ввода ограничено EMAIL_CODE_MAX_ATTEMPTS и общими brute-force настройками.

Парольный вход

После подтверждения email пользователь может задать пароль в настройках профиля. Пароль хранится как PBKDF2-SHA256 hash с солью.

После установки пароля доступен путь:

https://app.domain.com/login/password

Если парольный вход не удался, frontend предлагает fallback на обычный email-код. Установка или изменение пароля тоже подтверждается email-кодом.

Привязка аккаунтов

В настройках профиля пользователь может:

привязать email к Telegram-аккаунту через код;
привязать Telegram к email-аккаунту через Telegram Mini Apps initData или Telegram OAuth;
задать или сменить пароль для email-входа.

Если email уже принадлежит другой записи, backend выполняет безопасное объединение по существующим правилам аккаунтов и инвалидирует старые Web App-кеши.

Проверка после настройки

Перезапустите backend/frontend после изменения .env.
Откройте https://app.domain.com/ вне Telegram.
Убедитесь, что форма email-входа видна.
Запросите код на тестовый адрес.
Проверьте письмо, magic link и ручной ввод 6-значного кода.
Проверьте логи backend, если письмо не пришло:

docker compose logs -f backend

Частые ошибки

Форма email не видна: не заполнены SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD или SMTP_FROM_EMAIL.
Письмо не отправляется: проверьте порт, STARTTLS/SSL режим, SMTP login/API key и подтверждение отправителя.
Magic link ведет не туда: исправьте SUBSCRIPTION_MINI_APP_URL, он должен быть публичным HTTPS URL Mini App без /api и /auth.
Код сразу устаревает: проверьте EMAIL_CODE_TTL_SECONDS и время на сервере.
Пользователь получает rate_limited: подождите EMAIL_CODE_RESEND_SECONDS или проверьте brute-force настройки.

Email-уведомления поддержки, платежей и жизненного цикла подписки используют тот же SMTP-контур. Сценарий поддержки описан в разделе тикетов, сводка по каналам - в разделе уведомления.

Настройка локального SMTP-сервера

Требования

Перед запуском локального SMTP-сервера вам потребуется настроить DNS-записи вашего домена:

A — mail.example.com (указать IP вашего сервера)
MX — mail.example.com (приоритет 10)
PTR — mail.example.com (настраивается у вашего хостера VPS)
TXT — v=spf1 ip4:1.2.3.4 ~all (поддомен @, замените 1.2.3.4 на реальный ipv4 вашего сервера)

После изменения DNS-записей подождите некоторое время (иногда требуется от 3 часов до суток) для применения изменений.

Для использования STARTTLS необходимо получить TLS/SSL-сертификат для домена mail.example.com. Самый простой способ это сделать — прописать следующую директиву в Caddyfile (если вы используете Caddy):

https://mail.example.com {
    respond "Mail server"
}

Установка

Настройка docker-compose.yml:

mkdir -p /opt/mailserver
cd /opt/mailserver
curl -O https://raw.githubusercontent.com/3252a8/remnawave-minishop/refs/heads/main/deploy/examples/mail/docker-compose.yml
nano docker-compose.yml

Запуск:

docker compose up -d

Создание пользователя:

# Скрипт попросит придумать пароль и потвердить его
docker exec -it mailserver setup email add no-reply@example.com

# Проверка создания пользователя
docker exec -it mailserver setup email list

# Должны увидеть:
# no-reply@example.com

После всех настроек вы можете использовать свой почтовый клиент (Microsoft Outlook, Mozilla Thunderbird) для отправки и получения писем. В окне добавления нового аккаунта достаточно ввести созданную почту no-reply@example.com и пароль.

8.9 KiB Raw Blame History Unescape Escape