Настройка входа и регистрации

Настройка входа по email с кодом подтверждения, Google OAuth, списков разрешенных адресов для регистрации и локальных тестовых кодов.

Предиктор Икс поддерживает два метода входа: email + код подтверждения (по умолчанию) и Google OAuth (опционально). При успешном входе сервер выдает JWT-куки со сроком действия 30 дней. На этой странице описано, как настроить каждый из методов, как ограничить доступ к регистрации и главная ловушка для self-hosted развертываний.

Список используемых ниже переменных окружения см. в разделе Переменные окружения; подробности о жизненном цикле токенов см. в разделе Аутентификация и токены.

Как работает вход по email и коду подтверждения

Пользователь вводит email на странице входа → сервер отправляет 6-значный код → пользователь вводит его → сервер проверяет код → выдается JWT-кука. Стандартный процесс. Поддерживаются два бэкенда для доставки почты — выберите тот, который подходит для вашего развертывания:

Вариант А: Resend (рекомендуется для облачных развертываний)

Создайте аккаунт в Resend и подтвердите свой домен
Создайте API-ключ

Установите переменные окружения:

RESEND_API_KEY=re_xxxxxxxxxxxxxxxx
RESEND_FROM_EMAIL=noreply@yourdomain.com  # домен должен быть подтвержден в Resend

Перезапустите сервер

Вариант Б: SMTP-релей (для self-hosted / локальных развертываний)

Используйте этот вариант, если развертывание не имеет доступа к api.resend.com или у вас уже есть внутренний почтовый релей (Microsoft Exchange, Postfix, локальный SendGrid и т.д.). SMTP_HOST имеет приоритет над RESEND_API_KEY, если установлены оба — сервер всегда будет использовать SMTP, поэтому письма с кодами подтверждения и приглашениями не покинут внутреннюю сеть.

SMTP-путь поддерживает три режима релея, которые используют большинство корпоративных почтовых серверов (в частности, коннекторы приема Microsoft Exchange):

Режим	Порт	Аутентификация	TLS
Анонимный внутренний релей	`25`	нет — доверие по IP / подсети	нет (только внутри сегмента)
Аутентифицированная отправка	`587`	`SMTP_USERNAME` + `SMTP_PASSWORD`	STARTTLS, обновляется автоматически
Неявный TLS (SMTPS)	`465`	опционально (`SMTP_USERNAME` + `SMTP_PASSWORD`)	TLS-рукопожатие при соединении — включено на 465 порту, или принудительно через `SMTP_TLS=implicit`

Анонимный релей Exchange на порту 25 — типичный "внутренний SMTP-релей", который принимает почту из доверенной подсети без учетных данных:

SMTP_HOST=exchange.internal.example.com
SMTP_PORT=25
SMTP_USERNAME=
SMTP_PASSWORD=
SMTP_TLS_INSECURE=false
RESEND_FROM_EMAIL=noreply@yourdomain.com  # используется в заголовке From:

Аутентифицированная отправка на порту 587 — для релеев, требующих сервисную учетную запись; STARTTLS обновляется автоматически, если сервер его поддерживает:

SMTP_HOST=smtp.internal.example.com
SMTP_PORT=587
SMTP_USERNAME=predictorx
SMTP_PASSWORD=...
SMTP_TLS_INSECURE=false        # ставить true только для самоподписанных сертификатов / частных CA
RESEND_FROM_EMAIL=noreply@yourdomain.com

Неявный TLS (SMTPS) на порту 465 — для провайдеров, поддерживающих только SMTPS (например, корпоративная почта Aliyun / Tencent). Порт 465 автоматически включает неявный TLS; SMTP_TLS=implicit принудительно включает его на нестандартном порту:

SMTP_HOST=smtp.qiye.aliyun.com
SMTP_PORT=465                  # неявный TLS включен на 465 автоматически
SMTP_USERNAME=predictorx@yourdomain.com
SMTP_PASSWORD=...
SMTP_TLS=implicit              # опционально на 465; обязательно на нестандартном порту
RESEND_FROM_EMAIL=noreply@yourdomain.com

Строгие публичные релеи (например, Google Workspace smtp-relay.gmail.com) дополнительно требуют валидное имя EHLO. Они отклоняют приветствие localhost с публичного IP, из-за чего релей сбрасывает соединение (ошибка smtp auth: EOF). Установите SMTP_EHLO_NAME в значение FQDN, которое ожидает релей; по умолчанию используется имя хоста контейнера, которое обычно не является валидным FQDN:

SMTP_HOST=smtp-relay.gmail.com
SMTP_PORT=587
SMTP_EHLO_NAME=mail.yourdomain.com   # FQDN, принимаемый релеем
RESEND_FROM_EMAIL=noreply@yourdomain.com

При запуске сервер выводит выбранный провайдер и режим TLS. Если после перезапуска вы не видите строку с SMTP, значит SMTP_HOST не был прочитан процессом — проверьте переменные контейнера (docker compose -f docker-compose.selfhost.yml exec backend env | grep SMTP).

Что будет, если не настроить ни один вариант: сервер не выдаст ошибку, но все письма будут записываться только в stdout сервера. Полезно для локальной разработки (код можно скопировать из логов); в продакшене это "черная дыра".

Фиксированные коды для локального тестирования

Не включайте фиксированный код подтверждения на публично доступном инстансе.

Прежнее поведение, когда не-production инстансы по умолчанию принимали 000999, было удалено. Теперь, если вы не настроите это явно, ввод 000999 будет считаться неверным кодом.

Для локальной разработки без почтового бэкенда используйте код, который генерируется и выводится в логи сервера. Если вам нужна детерминированная локальная автоматизация, установите PREDICTORX_DEV_VERIFICATION_CODE в 6-значное значение (например, 000999) и оставьте APP_ENV в значении development:

APP_ENV=development
Предиктор Икс_DEV_VERIFICATION_CODE=888888

Этот способ игнорируется, если APP_ENV=production.

В production-развертываниях PREDICTORX_DEV_VERIFICATION_CODE должен быть пустым, а APP_ENV — production. Если вы разворачиваете через make selfhost / docker-compose.selfhost.yml, APP_ENV по умолчанию имеет значение production.

Настройка Google OAuth

Опционально. Без этого доступен только вход по email. С ним на странице входа появится кнопка "Войти через Google".

Создайте OAuth 2.0 клиент в Google Cloud Console
Установите Authorized redirect URIs на адрес фронтенда Предиктор Икс + /auth/callback, например:
```
https://predictorx.yourdomain.com/auth/callback
```

После получения ID и секрета клиента, установите три переменные окружения:

GOOGLE_CLIENT_ID=xxxxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-xxxxxxxxxxxxxxx
GOOGLE_REDIRECT_URI=https://predictorx.yourdomain.com/auth/callback

Перезапустите сервер.

Вступает в силу во время выполнения: фронтенд считывает эти настройки через /api/config — после изменений достаточно перезапустить сервер, чтобы фронтенд увидел обновления без пересборки.

Redirect URI должен в точности совпадать в консоли Google и в GOOGLE_REDIRECT_URI — включая протокол (http / https), завершающий слэш и порт. При любом несоответствии Google отклонит запрос с ошибкой redirect_uri_mismatch.

Ограничение регистрации пользователей

Три переменные окружения работают по принципу приоритета:

Rendering diagram…

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

ALLOWED_EMAILS (высший приоритет) — явный список email-адресов через запятую. Если не пуст, регистрироваться могут только указанные адреса.
ALLOWED_EMAIL_DOMAINS — список разрешенных доменов через запятую (например, company.io,partner.com).
ALLOW_SIGNUP — главный переключатель, по умолчанию true. Установите false, чтобы полностью отключить саморегистрацию.

Три слоя работают по логике И, а не ИЛИ. Распространенное заблуждение: ALLOWED_EMAIL_DOMAINS=company.io + ALLOW_SIGNUP=true означает "разрешить company.io и всех остальных". Это не так. Если хоть один список не пуст, все несовпадающие адреса будут отклонены — ALLOW_SIGNUP=true не отменяет это ограничение.

Чтобы "разрешить всем", оставьте все три переменные пустыми (или сохраните ALLOW_SIGNUP=true).

Типичные конфигурации:

Цель	Конфигурация
Только для сотрудников `company.io`	`ALLOWED_EMAIL_DOMAINS=company.io`
Внутренние + несколько внешних коллабораторов	`ALLOWED_EMAIL_DOMAINS=company.io` + добавление адресов в `ALLOWED_EMAILS`
Отключить саморегистрацию, только по приглашениям	`ALLOW_SIGNUP=false`
Открытая регистрация (не рекомендуется для продакшена)	Все три пусты

Можно ли приглашать людей, если регистрация отключена?

Только тех, у кого уже есть аккаунт Предиктор Икс. Принятие приглашения не проверяет список разрешенных для регистрации — если пользователь уже регистрировался (например, в другом рабочем пространстве), вход по ссылке-приглашению сработает.

Но люди, которые никогда не регистрировались, не смогут воспользоваться приглашением. Перед принятием они должны войти, а первый шаг входа проверяется по спискам разрешенных. Если ALLOW_SIGNUP=false или их адрес не указан в разрешенных, они не смогут завершить регистрацию и принять приглашение.

Чтобы пригласить внешнего коллегу, который еще не регистрировался: временно добавьте его email в ALLOWED_EMAILS, подождите, пока он зарегистрируется и примет приглашение, затем удалите его из списка.

Информацию о том, как создавать и использовать приглашения, см. в разделе Участники и роли.

Переменные окружения — полные определения всех переменных, используемых на этой странице
Аутентификация и токены — JWT / PAT / типы токенов и их использование
Устранение неполадок — код не пришел, ошибка redirect_uri_mismatch, отклонение регистрации