Переменные окружения

Полный список переменных окружения для запуска self-hosted сервера Предиктор Икс.

Self-hosted сервер Предиктор Икс server считывает свою конфигурацию из переменных окружения при запуске — база данных, вход в систему, электронная почта, хранилище и списки разрешений для регистрации настраиваются именно здесь. Эта страница группирует все переменные по назначению: каждый раздел поясняет, что произойдет, если оставить переменную незаданной, и какие из них необходимо задать в production. О том, как настроить переменные для аутентификации, см. Настройка входа и регистрации.

Основные переменные сервера

Это основные переменные, о которых необходимо подумать перед развертыванием — у некоторых есть значения по умолчанию, позволяющие запустить сервер, но в production вам следует задать обязательные переменные явно.

Переменная	По умолчанию	Требуется в production?
`DATABASE_URL`	`postgres://predictorx:predictorx@localhost:5432/predictorx?sslmode=disable`	Да
`PORT`	`8080`	Нет (если не меняете порт)
`JWT_SECRET`	`predictorx-dev-secret-change-in-production`	Да (значение по умолчанию небезопасно)
`APP_ENV`	пусто	Да (должно быть `production`)
`FRONTEND_ORIGIN`	пусто	Да (self-hosted должен задать свой домен)
`PREDICTORX_DEV_VERIFICATION_CODE`	пусто	Нет (должно оставаться пустым в production)

Не задавайте PREDICTORX_DEV_VERIFICATION_CODE в production. Фиксированный код для локального тестирования отключен по умолчанию, но если вы включите его с помощью PREDICTORX_DEV_VERIFICATION_CODE=888888, любой, кто может запросить код, сможет войти в систему с этим фиксированным значением, пока APP_ENV не равен production. Этот ярлык игнорируется, когда APP_ENV=production.

Пул подключений к базе данных

Переменная	По умолчанию	Описание
`DATABASE_MAX_CONNS`	`25`	Максимальное количество соединений pgxpool. Демон часто опрашивает базу (каждые 3 с) и использует соединения; для крупных развертываний может потребоваться большее значение
`DATABASE_MIN_CONNS`	`5`	Минимальное количество простаивающих соединений

Если не задано, используются значения выше — не встроенные в pgx значения 4/NumCPU, которые ранее вызывали исчерпание пула в production.

Конфигурация электронной почты

Предиктор Икс поддерживает два бэкенда доставки — Resend для облачных развертываний или SMTP-релей для внутренних/локальных сетей. SMTP_HOST имеет приоритет над RESEND_API_KEY, если заданы оба.

Resend

Переменная	По умолчанию	Описание
`RESEND_API_KEY`	пусто	API-ключ Resend
`RESEND_FROM_EMAIL`	`noreply@predictorx.ru`	Адрес отправителя (должен быть домен, подтвержденный в вашей учетной записи Resend; также используется как заголовок `From:` при работе через SMTP)

SMTP-релей

Переменная	По умолчанию	Описание
`SMTP_HOST`	пусто	Имя хоста SMTP-релея. Задание этого параметра активирует режим SMTP и отменяет использование Resend
`SMTP_PORT`	`25`	SMTP-порт. Используйте `587` для STARTTLS или `465` для SMTPS (implicit TLS, включается автоматически)
`SMTP_USERNAME`	пусто	Имя пользователя SMTP. Оставьте пустым для релея без аутентификации
`SMTP_PASSWORD`	пусто	Пароль SMTP
`SMTP_TLS`	`starttls`	Режим TLS. `implicit` (псевдоним `smtps`, `ssl`) принудительно устанавливает TLS-рукопожатие сразу при подключении (SMTPS); порт `465` включает его автоматически. Если не задано или установлено в `starttls`, обновление до TLS происходит после подключения
`SMTP_TLS_INSECURE`	`false`	Установите `true` для пропуска проверки TLS-сертификата (только для частных CA / самоподписанных сертификатов)
`SMTP_EHLO_NAME`	имя хоста машины	Имя EHLO/HELO, передаваемое релею. Установите реальный FQDN, если строгий релей (например, Google Workspace `smtp-relay.gmail.com`) отклоняет стандартное приветствие с публичного IP — иначе релей разорвет соединение, что проявится как неясная ошибка `EOF` на более поздней команде

Обновление до STARTTLS происходит автоматически, когда сервер объявляет о поддержке. Тайм-аут на установку соединения составляет 10 секунд, а на всю SMTP-сессию — 30 секунд.

Поведение, если ничего не задано: сервер не выдает ошибку, но все письма (коды верификации, ссылки приглашений) записываются только в stdout сервера. Это удобно для локальной разработки — просто скопируйте код из логов. В production отсутствие настройки создает "черную дыру", пользователи не получают письма, и ошибки не возникают.

Конфигурация Google OAuth

Необязательно. Оставьте незаполненным, если используете только email + код подтверждения. Настройте для добавления кнопки "Войти через Google" на странице входа.

Переменная	По умолчанию	Описание
`GOOGLE_CLIENT_ID`	пусто	Google Cloud OAuth client ID
`GOOGLE_CLIENT_SECRET`	пусто	Google Cloud OAuth secret
`GOOGLE_REDIRECT_URI`	`http://localhost:3000/auth/callback`	Callback URL для OAuth (self-host: замените на ваш домен фронтенда)

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

Полная инструкция по настройке (включая шаги в Google Cloud Console) находится в Настройка входа и регистрации.

Конфигурация файлового хранилища

Предиктор Икс хранит загружаемые пользователями вложения (изображения и файлы в комментариях). Предпочтительно использовать S3; если S3 не настроен, используется локальный диск.

S3 / S3-совместимое хранилище

Переменная	По умолчанию	Описание
`S3_BUCKET`	пусто	Только имя бакета (например `my-bucket`). Не добавляйте суффикс `.s3.<region>.amazonaws.com` — сервер сам конструирует адрес из `S3_BUCKET` + `S3_REGION`. Задание этого параметра включает хранение в S3
`S3_REGION`	`us-west-2`	AWS-регион. Должен соответствовать реальному региону бакета — используется для подписи SDK и формирования публичного URL
`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`	пусто	Статические учетные данные. Если оба не заданы, используется цепочка учетных данных AWS SDK по умолчанию (IAM-роль / переменные окружения)
`AWS_ENDPOINT_URL`	пусто	Пользовательский S3-совместимый эндпоинт (например MinIO). Переключает на path-style URL
`ATTACHMENT_DOWNLOAD_MODE`	`auto`	Путь загрузки вложений: `auto`, `cloudfront`, `presign`, или `proxy`. В режиме `auto` предпочтителен CloudFront; внутренние/частные эндпоинты используют прокси сервера; публичные S3-совместимые используют предписанные (presigned) GET-ссылки
`ATTACHMENT_DOWNLOAD_URL_TTL`	`30m`	Время жизни (TTL) для подписанных ссылок CloudFront и S3 presigned URL. Принимает строки длительности Go

Если S3_BUCKET не задан: при запуске сервер пишет в лог "S3_BUCKET not set, cloud upload disabled", и все загрузки сохраняются на локальный диск.

URL объектов формируются в следующем порядке приоритета:

https://<CLOUDFRONT_DOMAIN>/<key> если задан CLOUDFRONT_DOMAIN.
<AWS_ENDPOINT_URL>/<S3_BUCKET>/<key> (path-style) если задан AWS_ENDPOINT_URL.
https://<S3_BUCKET>.s3.<S3_REGION>.amazonaws.com/<key> (virtual-hosted-style). Если S3_BUCKET содержит точки, сервер переключается на https://s3.<S3_REGION>.amazonaws.com/<S3_BUCKET>/<key> (path-style), так как TLS-сертификат AWS с подстановочными знаками не проверяет бакеты с точками.

API download_url использует GET /api/attachments/{id}/download, если не настроена подпись CloudFront. Эндпоинт перенаправляет на CloudFront/S3 или стримит через сервер для приватных/внутренних эндпоинтов (например, http://rustfs:9000). Для объектных хранилищ внутри Docker/VPC используйте ATTACHMENT_DOWNLOAD_MODE=proxy, если автоопределение недостаточно консервативно для вашей сети.

Локальный диск (если S3 не настроен)

Переменная	По умолчанию	Описание
`LOCAL_UPLOAD_DIR`	`./data/uploads`	Директория локального хранилища
`LOCAL_UPLOAD_BASE_URL`	пусто (возвращает относительные пути)	Публичный базовый URL — если оставить пустым, фронтенд не сможет разрешить полный URL для вложений

CloudFront (опционально)

Если вы используете CloudFront перед S3, применяются три переменные: CLOUDFRONT_DOMAIN, CLOUDFRONT_KEY_PAIR_ID, CLOUDFRONT_PRIVATE_KEY (или CLOUDFRONT_PRIVATE_KEY_SECRET для чтения из Secrets Manager). Пропустите их, если не используете CloudFront.

Переменная	По умолчанию	Описание
`COOKIE_DOMAIN`	пусто	Область действия сессионного cookie

Пусто: cookie валиден только для конкретного хоста (правильно для однохостовых развертываний)
Установлено в .example.com: cookie доступен для всех поддоменов
Предупреждение: не может быть IP-адресом (браузеры игнорируют его)

Ограничение регистрации

Три уровня списков разрешений объединяются по приоритету. Если хотя бы один уровень задан, письма, не соответствующие списку, будут отклонены — даже ALLOW_SIGNUP=true не перекроет это.

Переменная	По умолчанию	Описание
`ALLOWED_EMAILS`	пусто	Список разрешенных адресов (через запятую). Если задан, только они могут зарегистрироваться
`ALLOWED_EMAIL_DOMAINS`	пусто	Список разрешенных доменов (через запятую). Если задан, только пользователи с этих доменов могут зарегистрироваться
`ALLOW_SIGNUP`	`true`	Главный выключатель регистрации. Установите `false`, чтобы полностью отключить регистрацию

Важный момент: ALLOWED_EMAIL_DOMAINS=company.io + ALLOW_SIGNUP=true не означает "разрешить company.io или всех" — это означает только разрешить company.io. Списки работают по принципу логического И.

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

Блокировка создания рабочих пространств

ALLOW_SIGNUP=false блокирует новые аккаунты, но не блокирует уже вошедшим пользователям создание других пространств через POST /api/workspaces. Чтобы закрыть эту возможность, установите DISABLE_WORKSPACE_CREATION=true.

Переменная	По умолчанию	Описание
`DISABLE_WORKSPACE_CREATION`	`false`	Если `true`, любой запрос `POST /api/workspaces` вернет `403`. Веб-интерфейс скроет возможность создания пространства

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

Запустите инстанс с DISABLE_WORKSPACE_CREATION по умолчанию.
Войдите как администратор и создайте общее рабочее пространство.
Установите DISABLE_WORKSPACE_CREATION=true и перезапустите бэкенд. С этого момента пользователи могут присоединяться только через приглашения.

Ограничение скорости (опционально Redis)

Публичные эндпоинты аутентификации имеют ограничение скорости (rate limiting) по IP. Ограничитель работает через Redis. Если REDIS_URL не задан, middleware отключается (fail-open).

Переменная	По умолчанию	Описание
`REDIS_URL`	пусто	URL для подключения к Redis. Также используется для очереди событий в реальном времени и кешей
`RATE_LIMIT_AUTH`	`5`	Макс. запросов в минуту к `/auth/send-code` и `/auth/google`
`RATE_LIMIT_AUTH_VERIFY`	`20`	Макс. запросов в минуту к `/auth/verify-code`
`RATE_LIMIT_TRUSTED_PROXIES`	пусто	CIDR прокси-серверов, чьим заголовкам `X-Forwarded-For` можно доверять

За обратным прокси обязательно установите RATE_LIMIT_TRUSTED_PROXIES. Иначе все пользователи будут учитываться как один IP. Обычно это 127.0.0.1/32,::1/128 для Caddy/Nginx или диапазоны вашего CDN (Cloudflare, AWS ALB и т.д.).

Параметры настройки демона

Демон запускается локально у пользователя.

Переменная	По умолчанию	Описание
`PREDICTORX_SERVER_URL`	`ws://localhost:8080/ws`	Адрес сервера
`PREDICTORX_DAEMON_HEARTBEAT_INTERVAL`	`15s`	Интервал сердцебиения
`PREDICTORX_DAEMON_POLL_INTERVAL`	`3s`	Интервал опроса задач
`PREDICTORX_DAEMON_MAX_CONCURRENT_TASKS`	`20`	Макс. одновременных задач

Контроль доступа к фронтенду

Переменная	По умолчанию	Описание
`FRONTEND_ORIGIN`	пусто	Адрес фронтенда. От него зависят ссылки в письмах, CORS и домен cookie. Должен быть задан для self-host
`PREDICTORX_APP_URL`	пусто	URL фронтенда для CLI-авторизации
`PREDICTORX_PUBLIC_URL`	пусто	Публичный API URL для вебхуков автопилота
`CORS_ALLOWED_ORIGINS`	пусто	Дополнительные разрешенные CORS-источники

Если FRONTEND_ORIGIN не задан, возникают два сбоя: (1) ссылки в письмах ведут на https://app.predictorx.ru, а не на ваш инстанс; (2) WebSocket-соединения в production будут отклонены из-за проверки Origin.

Интеграция с GitHub

Для работы интеграции GitHub PR ↔ issue.

Переменная	По умолчанию	Описание
`GITHUB_APP_SLUG`	пусто	Слаг вашего приложения GitHub
`GITHUB_WEBHOOK_SECRET`	пусто	Секрет вебхука, заданный в приложении GitHub
`GITHUB_APP_ID`	пусто	Numeric App ID (опционально)
`GITHUB_APP_PRIVATE_KEY`	пусто	PEM-блок закрытого ключа (опционально)

Если обязательные переменные не заданы, кнопка Connect GitHub в настройках будет отключена.

Аналитика использования

По умолчанию сервер отправляет данные в официальный инстанс PostHog. Чтобы отключить, установите ANALYTICS_DISABLED=true.

Переменная	По умолчанию	Описание
`ANALYTICS_DISABLED`	`false`	Установите `true` для полного отключения аналитики
`POSTHOG_API_KEY`	ключ по умолчанию	Ваш API-ключ, если используете свой PostHog
`POSTHOG_HOST`	`https://us.i.posthog.com`	Хост вашего PostHog