168 lines
9.8 KiB
Markdown
168 lines
9.8 KiB
Markdown
# Вход по email
|
||
|
||
Email-вход позволяет пользователю зарегистрироваться или войти в Mini App без Telegram. Пользователь вводит email, получает одноразовый код и может подтвердить вход кодом или magic link из письма. После входа email можно связать с Telegram-аккаунтом в настройках профиля.
|
||
|
||
Аккаунты только с email не получают права администратора: админка проверяет Telegram ID из `ADMIN_IDS`.
|
||
|
||
## Когда форма появляется
|
||
|
||
Кнопка входа по email показывается только если заполнены все обязательные SMTP-настройки:
|
||
|
||
```ini
|
||
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-настройка
|
||
|
||
Типовой пример:
|
||
|
||
```ini
|
||
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
|
||
```
|
||
|
||
## Брендинг писем
|
||
|
||
HTML-письма используют тот же бренд, что и Mini App: название из `WEBAPP_TITLE`, accent из внешнего вида и логотип из раздела **Внешний вид**. Если логотип загружен через админку файлом, backend прикладывает его к письму как inline image (`cid:webapp-logo`), поэтому получателю не нужен доступ к внутреннему `/webapp-uploaded-logo/...`.
|
||
|
||
Если в качестве логотипа задан публичный `https://` URL, письмо использует его как обычный внешний `<img>`. В этом режиме некоторые почтовые клиенты могут скрыть картинку, пока получатель не разрешит загрузку внешних изображений.
|
||
|
||
Для Brevo обычно подходит порт `587` с STARTTLS. Если основной порт недоступен, приложение пробует порты из `SMTP_FALLBACK_PORTS`; порт `465` используется через SSL wrapper автоматически.
|
||
|
||
`SMTP_FROM_EMAIL` должен быть подтвержден у SMTP-провайдера, иначе письмо часто отклоняется или попадает в спам. `SMTP_FROM_NAME` можно оставить пустым, тогда используется название Web App.
|
||
|
||
Полный справочник переменных: [SMTP и вход по email](../configuration/env-vars.md#smtp-и-вход-по-email).
|
||
|
||
## Как работает вход
|
||
|
||
1. Пользователь вводит email в форме входа.
|
||
2. Backend проверяет rate limit и создает одноразовый код.
|
||
3. Письмо отправляется через SMTP. Если `SUBSCRIPTION_MINI_APP_URL` валиден, в письме также есть magic link.
|
||
4. Пользователь вводит код в Mini App или открывает magic link.
|
||
5. Backend создает нового email-пользователя или находит существующего по email.
|
||
6. Если в URL был referral-параметр, он применяется к новой или существующей записи.
|
||
7. Пользователь получает Web App-сессию.
|
||
|
||
Коды хранятся в базе в хешированном виде, устаревают по `EMAIL_CODE_TTL_SECONDS`, повторная отправка ограничена `EMAIL_CODE_RESEND_SECONDS`, а количество попыток ввода ограничено `EMAIL_CODE_MAX_ATTEMPTS` и общими brute-force настройками.
|
||
|
||
## Парольный вход
|
||
|
||
После подтверждения email пользователь может задать пароль в настройках профиля. Пароль хранится как PBKDF2-SHA256 hash с солью.
|
||
|
||
После установки пароля доступен путь:
|
||
|
||
```text
|
||
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-кеши.
|
||
|
||
## Проверка после настройки
|
||
|
||
1. Перезапустите backend/frontend после изменения `.env`.
|
||
2. Откройте `https://app.domain.com/` вне Telegram.
|
||
3. Убедитесь, что форма email-входа видна.
|
||
4. Запросите код на тестовый адрес.
|
||
5. Проверьте письмо, magic link и ручной ввод 6-значного кода.
|
||
6. Проверьте логи backend, если письмо не пришло:
|
||
|
||
```bash
|
||
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-контур. Сценарий поддержки описан в [разделе тикетов](support.md), сводка по каналам - в разделе [уведомления](notifications.md).
|
||
|
||
## Настройка локального 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):
|
||
|
||
```Caddyfile
|
||
https://mail.example.com {
|
||
respond "Mail server"
|
||
}
|
||
```
|
||
|
||
### Установка
|
||
|
||
1. Настройка docker-compose.yml:
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
2. Запуск:
|
||
|
||
```bash
|
||
docker compose up -d
|
||
```
|
||
|
||
3. Создание пользователя:
|
||
|
||
```bash
|
||
# Скрипт попросит придумать пароль и потвердить его
|
||
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 и пароль.
|