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

`.env` нужен прежде всего для bootstrap: токен бота, доступ к базе, публичный URL вебхуков и стабильные секреты. После первого входа большая часть продуктовых настроек меняется в Web App админке и сохраняется в БД как переопределения поверх `.env`.

Рекомендуемый порядок:

1. Заполнить минимальный `.env` по `.env.example`.
2. Запустить стек и войти в Web App под Telegram ID из `ADMIN_IDS`.
3. Настроить Remnawave, платежи, внешний вид, поддержку, уведомления и тарифы через админку.

## Минимальный bootstrap

| Переменная | Где менять | Назначение |
| --- | --- | --- |
| `BOT_TOKEN` | Только `.env` | Токен Telegram-бота. |
| `ADMIN_IDS` | Только `.env` | Telegram ID администраторов через запятую. Нужен для первого входа в админку. |
| `WEBHOOK_BASE_URL` | `.env` | Публичный URL backend/webhook-домена. Используется для URL вебхуков Telegram, платежных провайдеров и Remnawave. |
| `POSTGRES_USER` | `.env` / Compose | Пользователь PostgreSQL. |
| `POSTGRES_PASSWORD` | `.env` / Compose | Пароль PostgreSQL. |
| `POSTGRES_DB` | `.env` / Compose | Имя базы PostgreSQL. |
| `WEBAPP_ENABLED` | `.env` / админка | Включает Web App и админку. Держите `True` для первого запуска; если выключить, вернуть доступ можно только через `.env` и рестарт. |
| `WEBAPP_SESSION_SECRET` | `.env` | Стабильный HMAC-секрет сессий Web App. Если пустой, генерируется на процесс, но сессии сбросятся после рестарта. |
| `WEBHOOK_SECRET_TOKEN` | `.env` | Секрет вебхука Telegram. Если пустой, генерируется на процесс. |

## Инфраструктура и Compose

| Переменная | Где менять | Назначение |
| --- | --- | --- |
| `APP_ENV_FILE` | CLI/Compose | Путь к env-файлу вместо `.env`. |
| `IMAGE_TAG` | CLI/Compose | Тег Docker-образов. |
| `FRONTEND_PORT` | `.env` / Compose | Хостовый порт frontend nginx. По умолчанию `8082`. |
| `WEB_SERVER_HOST` | `.env` | Внутренний хост backend-сервера вебхуков. Обычно `0.0.0.0`. |
| `WEB_SERVER_PORT` | `.env` / Compose | Хостовый порт backend-сервера вебхуков. По умолчанию `8080`. |
| `WEBAPP_SERVER_HOST` | `.env` | Внутренний хост Web App API-сервера. Обычно `0.0.0.0`. |
| `WEBAPP_SERVER_PORT` | `.env` | Внутренний порт Web App API-сервера. По умолчанию `8081`. |
| `POSTGRES_HOST` | Compose | Host PostgreSQL. В штатном Compose задается как `postgres`. |
| `POSTGRES_PORT` | `.env` | Порт PostgreSQL. |
| `DB_POOL_SIZE` | `.env` | Размер async SQLAlchemy pool. |
| `DB_MAX_OVERFLOW` | `.env` | Дополнительные transient DB-соединения сверх pool. |
| `DB_POOL_TIMEOUT_SECONDS` | `.env` | Таймаут ожидания соединения из pool. |
| `DB_POOL_RECYCLE_SECONDS` | `.env` | Период recycling DB-соединений. |
| `REDIS_URL` | Compose | Redis для FSM, кеша, rate-limit, очередей и locks. В Compose задается автоматически. |
| `REDIS_KEY_PREFIX` | `.env` | Префикс Redis-ключей. |
| `TRUSTED_PROXIES` | `.env` | IP/CIDR обратных прокси, которым доверяется `X-Forwarded-For`. |
| `HTTP_BIND` / `HTTPS_BIND` | Caddy Compose | Адреса публикации Caddy-варианта. |
| `NEWT_ID` / `NEWT_SECRET` | Dev Compose | Доступы Newt в dev-compose. |

## Кеши, rate limits и worker

Обычно эти значения не требуют правки.

| Переменная | Назначение |
| --- | --- |
| `WEBAPP_ME_CACHE_TTL_SECONDS` | TTL кеша `/api/me`. |
| `WEBAPP_DEVICES_CACHE_TTL_SECONDS` | TTL кеша устройств Web App. |
| `PANEL_USER_CACHE_TTL_SECONDS` | TTL кеша Remnawave `/users/{uuid}`. |
| `PANEL_DEVICES_CACHE_TTL_SECONDS` | TTL кеша устройств пользователя Remnawave. |
| `PANEL_ALL_USERS_CACHE_TTL_SECONDS` | TTL кеша полных сканов пользователей Remnawave. |
| `PANEL_ALL_USERS_PAGE_SIZE` | Размер страницы Remnawave `/users`. |
| `ADMIN_PANEL_STATS_CACHE_TTL_SECONDS` | TTL статистики Remnawave в админке. |
| `ADMIN_DB_STATS_CACHE_TTL_SECONDS` | TTL дорогих DB-агрегатов админки. |
| `ADMIN_USERS_LIST_CACHE_TTL_SECONDS` | TTL списка пользователей админки. |
| `PROFILE_SYNC_CACHE_TTL_SECONDS` | Минимальная пауза между sync Telegram-профиля пользователя. |
| `PANEL_SYNC_LIFETIME_TRAFFIC_MIN_INTERVAL_SECONDS` | Минимальная пауза записи lifetime-трафика. |
| `PANEL_SYNC_LIFETIME_TRAFFIC_MIN_DELTA_BYTES` | Дельта lifetime-трафика для более ранней записи. |
| `WEBAPP_RATE_LIMIT_TTL_SECONDS` | Окно Web App rate limit. |
| `WEBAPP_RATE_LIMIT_MAX_REQUESTS` | Количество запросов в окне rate limit. |
| `WEBHOOK_QUEUE_NAME` | Redis queue для тяжелой обработки webhook. |
| `WEBHOOK_QUEUE_CONCURRENCY` | Количество worker consumers для webhook queue. |
| `WORKER_PANEL_SYNC_INTERVAL_SECONDS` | Интервал фоновой синхронизации с панелью. |
| `TARIFF_WORKER_LOCK_TTL_SECONDS` | TTL Redis lock для tariff worker. |
| `TARIFF_WORKER_TICK_SECONDS` | Интервал tariff worker. |
| `TARIFF_WORKER_BULK_PANEL_FETCH_THRESHOLD` | Порог активных подписок для bulk fetch пользователей панели. |

## Общие настройки

Эти поля доступны в админке: **Система -> Настройки**.

| Переменная | Назначение |
| --- | --- |
| `DEFAULT_LANGUAGE` | Язык по умолчанию: `ru` или `en`. |
| `DEFAULT_CURRENCY_SYMBOL` | Символ/код валюты в интерфейсе. |
| `SUPPORT_LINK` | Внешняя ссылка поддержки. |
| `SERVER_STATUS_URL` | Страница статуса сервиса. |
| `TERMS_OF_SERVICE_URL` | Условия использования. |
| `PRIVACY_POLICY_URL` | Политика конфиденциальности. |
| `USER_AGREEMENT_URL` | Пользовательское соглашение. |
| `REQUIRED_CHANNEL_ID` | ID обязательного Telegram-канала. |
| `REQUIRED_CHANNEL_LINK` | Ссылка на обязательный канал. |
| `START_COMMAND_DESCRIPTION` | Описание `/start` для меню Telegram. |
| `DISABLE_WELCOME_MESSAGE` | Отключить приветствие на `/start`. |

## Remnawave

Эти поля стоит держать в `.env` как базовую конфигурацию интеграции с панелью. Они также доступны в админке, чтобы можно было быстро поправить доступы или временно переопределить их без ручного редактирования файла и перезапуска.

| Переменная | Назначение |
| --- | --- |
| `PANEL_API_URL` | URL API панели, например `https://panel.example.com/api`. |
| `PANEL_API_KEY` | API-ключ панели. |
| `PANEL_WEBHOOK_SECRET` | Секрет проверки Remnawave webhook. |
| `USER_SQUAD_UUIDS` | Internal Squads по умолчанию для legacy-режима без JSON-каталога. |
| `USER_EXTERNAL_SQUAD_UUID` | Необязательный External Squad. |
| `USER_TRAFFIC_LIMIT_GB` | Legacy-лимит трафика пользователя. |
| `USER_TRAFFIC_STRATEGY` | Legacy-стратегия лимита трафика. |
| `USER_HWID_DEVICE_LIMIT` | Legacy-лимит HWID-устройств по умолчанию. |

## Веб-приложение, внешний вид и Telegram Login

Часть внешнего вида (`WEBAPP_PRIMARY_COLOR`, `WEBAPP_LOGO_*`, `WEBAPP_FAVICON_*`) сохранена для совместимости, но env-значения этих полей игнорируются при загрузке. Настраивайте их в **Админка -> Внешний вид**.

| Переменная | Где менять | Назначение |
| --- | --- | --- |
| `WEBAPP_ENABLED` | `.env` / админка | Включает Web App. Если `False`, пользовательский Web App и админка недоступны до включения через `.env` и рестарта. |
| `SUBSCRIPTION_MINI_APP_URL` | `.env` / админка | Публичный HTTPS URL Mini App/frontend, например `https://app.domain.com/`. Используется в Telegram-кнопках, реферальных ссылках, входе по email и настройках BotFather Mini App. Не указывайте здесь `/api` или webhook-пути. |
| `SUBSCRIPTION_GUIDES_ENABLED` | `.env` / админка | Включает встроенные инструкции установки в Web App. По умолчанию `True`; если конфиг недоступен или невалиден, кнопка подключения открывает обычную финальную ссылку подписки. |
| `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED` | `.env` / админка | Включает открытие Mini App `/install` из кнопок бота и показ публичной ссылки инструкции `/s/<token>`. По умолчанию `True`; если выключить, бот ведет на финальную Remnawave Subscription Page. |
| `SUBSCRIPTION_PAGE_CONFIG_PANEL_ENABLED` | `.env` / админка | Читать Remnawave Subscription Page config из панели для встроенных инструкций. По умолчанию `True`, чтобы не дублировать настройку страницы подписки в приложении. |
| `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED` | `.env` / админка | Включает использование JSON из поля `SUBSCRIPTION_PAGE_CONFIG_JSON` вместо конфига панели. По умолчанию `False`. |
| `SUBSCRIPTION_PAGE_CONFIG_PATH` | `.env` / админка | Резервный путь к локальному JSON-конфигу Remnawave Subscription Page v1, если конфиг панели выключен или недоступен. По умолчанию `data/subpage-config/multiapp.json`; файл не создается автоматически. |
| `SUBSCRIPTION_PAGE_CONFIG_JSON` | Админка | Опциональное JSON-переопределение Remnawave Subscription Page v1. Применяется только при включенном `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED`; backend валидирует JSON при сохранении. |
| `WEBAPP_TITLE` | Админка | Заголовок Web App. |
| `WEBAPP_THEMES_DIR` | `.env` | Каталог кастомных тем. |
| `WEBAPP_DEFAULT_THEME` | `.env` / админка | Ключ темы по умолчанию. |
| `WEBAPP_SESSION_TTL_SECONDS` | `.env` | Время жизни Web App-сессии. |
| `WEBAPP_AUTH_MAX_AGE_SECONDS` | `.env` | Максимальный возраст Telegram Mini Apps `initData`. |
| `WEBAPP_LOGIN_TOKEN_TTL_SECONDS` | `.env` | TTL ссылки внешнего логина. |
| `TELEGRAM_OAUTH_CLIENT_ID` | `.env` | Идентификатор клиента Telegram OAuth / OpenID Connect. Если пусто, берется bot ID из `BOT_TOKEN`. |
| `TELEGRAM_OAUTH_CLIENT_SECRET` | `.env` | Секрет клиента Telegram OAuth / OpenID Connect. |
| `TELEGRAM_OAUTH_REQUEST_ACCESS` | `.env` | Дополнительные разрешения, например `write`. |
| `WEBAPP_PRIMARY_COLOR` | Админка | Устаревшее env-поле, игнорируется. |
| `WEBAPP_LOGO_URL` | Админка | Устаревшее env-поле, игнорируется. |
| `WEBAPP_LOGO_USE_EMOJI` | Админка | Устаревшее env-поле, игнорируется. |
| `WEBAPP_LOGO_EMOJI` | Админка | Устаревшее env-поле, игнорируется. |
| `WEBAPP_LOGO_EMOJI_FONT` | Админка | Устаревшее env-поле, игнорируется. |
| `WEBAPP_FAVICON_USE_CUSTOM` | Админка | Устаревшее env-поле, игнорируется. |
| `WEBAPP_FAVICON_URL` | Админка | Устаревшее env-поле, игнорируется. |
| `WEBAPP_LOGO_FAVICON_URL` | Админка | Устаревшее env-поле, игнорируется. |

Инструкции установки совместимы с Remnawave Subscription Page v1 config: `version`, `locales`, `brandingSettings`, `uiConfig`, `baseSettings`, `baseTranslations`, `svgLibrary` и `platforms`. Текстовые поля рендерятся как текст, а SVG из `svgLibrary` проходит санитарную проверку перед отдачей в Web App.

## SMTP и вход по email

Вход по email появляется только если заполнены `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD` и `SMTP_FROM_EMAIL`.

| Переменная | Назначение |
| --- | --- |
| `SMTP_HOST` | SMTP host. |
| `SMTP_PORT` | Основной SMTP port. |
| `SMTP_FALLBACK_PORTS` | Резервные порты через запятую. |
| `SMTP_TIMEOUT_SECONDS` | Таймаут SMTP-попытки. |
| `SMTP_USERNAME` | SMTP login. |
| `SMTP_PASSWORD` | SMTP-пароль или API-ключ. |
| `SMTP_FROM_EMAIL` | Подтвержденный адрес отправителя. |
| `SMTP_FROM_NAME` | Имя отправителя. |
| `SMTP_STARTTLS` | Использовать STARTTLS. |
| `SMTP_USE_SSL` | Использовать SSL-wrapper. |
| `EMAIL_CODE_TTL_SECONDS` | TTL email-кода. |
| `EMAIL_CODE_RESEND_SECONDS` | Пауза перед повторной отправкой. |
| `EMAIL_CODE_MAX_ATTEMPTS` | Максимум попыток ввода кода. |
| `BRUTE_FORCE_MAX_FAILURES` | Количество ошибок до временной блокировки. |
| `BRUTE_FORCE_WINDOW_SECONDS` | Окно учета ошибок. |
| `BRUTE_FORCE_LOCK_SECONDS` | Длительность блокировки. |

## Платежи

Все включатели, секреты и настройки отображения провайдеров доступны в админке: **Система -> Настройки -> Платежи**.

| Переменная | Назначение |
| --- | --- |
| `PAYMENT_METHODS_ORDER` | Порядок кнопок оплаты: `severpay,wata,freekassa,platega,yookassa,stars,cryptopay,heleket`. |
| `SUBSCRIPTION_PURCHASE_DESCRIPTION_ENABLED` | Показывать описание подписки перед выбором срока. |
| `SUBSCRIPTION_PURCHASE_DESCRIPTION_RU` / `SUBSCRIPTION_PURCHASE_DESCRIPTION_EN` | Локализованное описание подписки. |
| `PAYMENT_<METHOD>_WEBAPP_LABEL_RU` / `PAYMENT_<METHOD>_WEBAPP_LABEL_EN` | Текст кнопки провайдера в Web App. |
| `PAYMENT_<METHOD>_WEBAPP_ICON` | Lucide-иконка кнопки в Web App. |
| `PAYMENT_<METHOD>_TELEGRAM_LABEL_RU` / `PAYMENT_<METHOD>_TELEGRAM_LABEL_EN` | Текст кнопки в Telegram. |
| `PAYMENT_<METHOD>_TELEGRAM_EMOJI` | Emoji кнопки в Telegram. |
| `STARS_ENABLED` | Включает Telegram Stars. |
| `YOOKASSA_ENABLED` | Включает YooKassa. |
| `FREEKASSA_ENABLED` | Включает FreeKassa. |
| `PLATEGA_ENABLED` | Включает Platega. |
| `PLATEGA_SBP_ENABLED` / `PLATEGA_CRYPTO_ENABLED` | Отдельные кнопки СБП/крипто Platega. |
| `SEVERPAY_ENABLED` | Включает SeverPay. |
| `WATA_ENABLED` | Включает Wata. |
| `CRYPTOPAY_ENABLED` | Включает CryptoPay. |
| `HELEKET_ENABLED` | Включает Heleket. |

Конкретные ключи отображения:

```text
PAYMENT_YOOKASSA_WEBAPP_LABEL_RU
PAYMENT_YOOKASSA_WEBAPP_LABEL_EN
PAYMENT_YOOKASSA_WEBAPP_ICON
PAYMENT_YOOKASSA_TELEGRAM_LABEL_RU
PAYMENT_YOOKASSA_TELEGRAM_LABEL_EN
PAYMENT_YOOKASSA_TELEGRAM_EMOJI
PAYMENT_FREEKASSA_WEBAPP_LABEL_RU
PAYMENT_FREEKASSA_WEBAPP_LABEL_EN
PAYMENT_FREEKASSA_WEBAPP_ICON
PAYMENT_FREEKASSA_TELEGRAM_LABEL_RU
PAYMENT_FREEKASSA_TELEGRAM_LABEL_EN
PAYMENT_FREEKASSA_TELEGRAM_EMOJI
PAYMENT_PLATEGA_SBP_WEBAPP_LABEL_RU
PAYMENT_PLATEGA_SBP_WEBAPP_LABEL_EN
PAYMENT_PLATEGA_SBP_WEBAPP_ICON
PAYMENT_PLATEGA_SBP_TELEGRAM_LABEL_RU
PAYMENT_PLATEGA_SBP_TELEGRAM_LABEL_EN
PAYMENT_PLATEGA_SBP_TELEGRAM_EMOJI
PAYMENT_PLATEGA_CRYPTO_WEBAPP_LABEL_RU
PAYMENT_PLATEGA_CRYPTO_WEBAPP_LABEL_EN
PAYMENT_PLATEGA_CRYPTO_WEBAPP_ICON
PAYMENT_PLATEGA_CRYPTO_TELEGRAM_LABEL_RU
PAYMENT_PLATEGA_CRYPTO_TELEGRAM_LABEL_EN
PAYMENT_PLATEGA_CRYPTO_TELEGRAM_EMOJI
PAYMENT_SEVERPAY_WEBAPP_LABEL_RU
PAYMENT_SEVERPAY_WEBAPP_LABEL_EN
PAYMENT_SEVERPAY_WEBAPP_ICON
PAYMENT_SEVERPAY_TELEGRAM_LABEL_RU
PAYMENT_SEVERPAY_TELEGRAM_LABEL_EN
PAYMENT_SEVERPAY_TELEGRAM_EMOJI
PAYMENT_WATA_WEBAPP_LABEL_RU
PAYMENT_WATA_WEBAPP_LABEL_EN
PAYMENT_WATA_WEBAPP_ICON
PAYMENT_WATA_TELEGRAM_LABEL_RU
PAYMENT_WATA_TELEGRAM_LABEL_EN
PAYMENT_WATA_TELEGRAM_EMOJI
PAYMENT_STARS_WEBAPP_LABEL_RU
PAYMENT_STARS_WEBAPP_LABEL_EN
PAYMENT_STARS_WEBAPP_ICON
PAYMENT_STARS_TELEGRAM_LABEL_RU
PAYMENT_STARS_TELEGRAM_LABEL_EN
PAYMENT_STARS_TELEGRAM_EMOJI
PAYMENT_CRYPTOPAY_WEBAPP_LABEL_RU
PAYMENT_CRYPTOPAY_WEBAPP_LABEL_EN
PAYMENT_CRYPTOPAY_WEBAPP_ICON
PAYMENT_CRYPTOPAY_TELEGRAM_LABEL_RU
PAYMENT_CRYPTOPAY_TELEGRAM_LABEL_EN
PAYMENT_CRYPTOPAY_TELEGRAM_EMOJI
PAYMENT_HELEKET_WEBAPP_LABEL_RU
PAYMENT_HELEKET_WEBAPP_LABEL_EN
PAYMENT_HELEKET_WEBAPP_ICON
PAYMENT_HELEKET_TELEGRAM_LABEL_RU
PAYMENT_HELEKET_TELEGRAM_LABEL_EN
PAYMENT_HELEKET_TELEGRAM_EMOJI
```

### YooKassa

| Переменная | Назначение |
| --- | --- |
| `YOOKASSA_SHOP_ID` | ID магазина. |
| `YOOKASSA_SECRET_KEY` | Секретный ключ. |
| `YOOKASSA_RETURN_URL` | URL возврата после оплаты. |
| `YOOKASSA_DEFAULT_RECEIPT_EMAIL` | Email для чеков по умолчанию. |
| `YOOKASSA_VAT_CODE` | Код НДС. |
| `YOOKASSA_AUTOPAYMENTS_ENABLED` | Автопродление через сохраненные способы оплаты. |
| `YOOKASSA_AUTOPAYMENTS_REQUIRE_CARD_BINDING` | Требовать привязку карты. |

### FreeKassa

| Переменная | Назначение |
| --- | --- |
| `FREEKASSA_MERCHANT_ID` | ID магазина. |
| `FREEKASSA_API_KEY` | API-ключ. |
| `FREEKASSA_SECOND_SECRET` | Секрет уведомлений. |
| `FREEKASSA_PAYMENT_IP` | Публичный IP сервера для запроса оплаты. |
| `FREEKASSA_PAYMENT_METHOD_ID` | ID метода оплаты. |
| `FREEKASSA_TRUSTED_IPS` | Список доверенных IP webhook-источников. |

### Platega

| Переменная | Назначение |
| --- | --- |
| `PLATEGA_BASE_URL` | Базовый URL API. |
| `PLATEGA_MERCHANT_ID` | ID мерчанта. |
| `PLATEGA_SECRET` | Секрет API. |
| `PLATEGA_PAYMENT_METHOD` | Устаревший/резервный ID метода оплаты. |
| `PLATEGA_SBP_METHOD` | ID метода оплаты для СБП. |
| `PLATEGA_CRYPTO_METHOD` | ID метода оплаты для крипто. |
| `PLATEGA_RETURN_URL` | URL успешного возврата. |
| `PLATEGA_FAILED_URL` | URL неуспешного возврата. |

### SeverPay

| Переменная | Назначение |
| --- | --- |
| `SEVERPAY_BASE_URL` | Базовый URL API. |
| `SEVERPAY_MID` | Merchant MID. |
| `SEVERPAY_TOKEN` | API-токен или секрет. |
| `SEVERPAY_RETURN_URL` | URL возврата. |
| `SEVERPAY_LIFETIME_MINUTES` | Время жизни платежной ссылки. |

### Wata

| Переменная | Назначение |
| --- | --- |
| `WATA_BASE_URL` | Базовый URL API. |
| `WATA_API_TOKEN` | Bearer-токен. |
| `WATA_RETURN_URL` | URL успешного возврата. |
| `WATA_FAILED_URL` | URL неуспешного возврата. |
| `WATA_LINK_TTL_MINUTES` | TTL платежной ссылки в минутах (по умолчанию 15, минимум 15, максимум 43200). |
| `WATA_WEBHOOK_VERIFY_SIGNATURE` | Проверять `X-Signature`. |
| `WATA_PUBLIC_KEY` | Закешированный публичный ключ; если пусто, загружается из API. |
| `WATA_TRUSTED_IPS` | Список доверенных IP webhook-источников. |

### CryptoPay

| Переменная | Назначение |
| --- | --- |
| `CRYPTOPAY_TOKEN` | API-токен CryptoPay. |
| `CRYPTOPAY_NETWORK` | `mainnet` или `testnet`. |
| `CRYPTOPAY_CURRENCY_TYPE` | `fiat` или `crypto`. |
| `CRYPTOPAY_ASSET` | Актив, например `RUB`, `USDT`, `BTC`. |

### Heleket

| Переменная | Назначение |
| --- | --- |
| `HELEKET_BASE_URL` | Базовый URL API. |
| `HELEKET_MERCHANT_ID` | UUID мерчанта. |
| `HELEKET_API_KEY` | Ключ платежного API. |
| `HELEKET_CURRENCY` | Валюта инвойса. |
| `HELEKET_TO_CURRENCY` | Целевая криптовалюта для конвертации. |
| `HELEKET_NETWORK` | Сеть, например `tron`, `bsc`, `eth`. |
| `HELEKET_RETURN_URL` | URL после отмены/истечения. |
| `HELEKET_SUCCESS_URL` | URL после успешной оплаты. |
| `HELEKET_LIFETIME_SECONDS` | TTL инвойса: 300..43200. |
| `HELEKET_VERIFY_WEBHOOK_SIGNATURE` | Проверять подпись webhook. |
| `HELEKET_TRUSTED_IPS` | Список доверенных IP webhook-источников. |

## Тарифы и legacy-цены

Рекомендуемый способ настройки тарифов - раздел **Система -> Тарифы** в админке. Он сохраняет JSON в `TARIFFS_CONFIG_PATH`.

| Переменная | Назначение |
| --- | --- |
| `TARIFFS_CONFIG_PATH` | Путь к JSON-каталогу тарифов. |
| `TARIFF_TRAFFIC_WARNING_LEVELS` | Уровни предупреждений по трафику в процентах. |
| `1_MONTH_ENABLED` | Legacy-доступность периода 1 месяц без JSON-каталога. |
| `3_MONTHS_ENABLED` | Legacy-доступность периода 3 месяца без JSON-каталога. |
| `6_MONTHS_ENABLED` | Legacy-доступность периода 6 месяцев без JSON-каталога. |
| `12_MONTHS_ENABLED` | Legacy-доступность периода 12 месяцев без JSON-каталога. |
| `RUB_PRICE_1_MONTH`, `RUB_PRICE_3_MONTHS`, `RUB_PRICE_6_MONTHS`, `RUB_PRICE_12_MONTHS` | Legacy-цены RUB. |
| `STARS_PRICE_1_MONTH`, `STARS_PRICE_3_MONTHS`, `STARS_PRICE_6_MONTHS`, `STARS_PRICE_12_MONTHS` | Legacy-цены Stars. |
| `TRAFFIC_PACKAGES` | Legacy-пакеты трафика RUB, формат `10:199,50:799`. |
| `STARS_TRAFFIC_PACKAGES` | Legacy-пакеты трафика Stars. |

## Пробный период, рефералы и уведомления

Эти настройки доступны в админке.

| Переменная | Назначение |
| --- | --- |
| `TRIAL_ENABLED` | Включает пробный период. |
| `TRIAL_DURATION_DAYS` | Длительность пробного периода. |
| `TRIAL_TRAFFIC_LIMIT_GB` | Лимит трафика пробного периода. |
| `TRIAL_TRAFFIC_STRATEGY` | Стратегия лимита пробного периода. |
| `TRIAL_SQUAD_UUIDS` | Internal Squads для trial через запятую. Если пусто, используется `USER_SQUAD_UUIDS`. |
| `REFERRAL_ONE_BONUS_PER_REFEREE` | Ограничить бонусы одним успешным платежом приглашенного. |
| `REFERRAL_WELCOME_BONUS_DAYS` | Приветственный бонус пришедшему по реферальной ссылке. |
| `LEGACY_REFS` | Разрешить ссылки `ref_<telegram_id>`. |
| `REFERRAL_BONUS_DAYS_1_MONTH`, `REFERRAL_BONUS_DAYS_3_MONTHS`, `REFERRAL_BONUS_DAYS_6_MONTHS`, `REFERRAL_BONUS_DAYS_12_MONTHS` | Legacy-бонусы пригласившему. |
| `REFEREE_BONUS_DAYS_1_MONTH`, `REFEREE_BONUS_DAYS_3_MONTHS`, `REFEREE_BONUS_DAYS_6_MONTHS`, `REFEREE_BONUS_DAYS_12_MONTHS` | Legacy-бонусы приглашенному. |
| `SUBSCRIPTION_NOTIFICATIONS_ENABLED` | Включает напоминания о подписке. |
| `SUBSCRIPTION_NOTIFY_ON_EXPIRE` | Уведомлять в день окончания. |
| `SUBSCRIPTION_NOTIFY_AFTER_EXPIRE` | Уведомлять после окончания. |
| `SUBSCRIPTION_NOTIFY_DAYS_BEFORE` | За сколько дней предупреждать. |

## Поддержка

Подробный сценарий описан в разделе [поддержка пользователей / тикеты](../features/support.md).

| Переменная | Назначение |
| --- | --- |
| `SUPPORT_TICKETS_ENABLED` | Включает тикеты в Mini App. |
| `SUPPORT_ADMIN_EMAIL_NOTIFICATIONS_ENABLED` | Email-уведомления администраторам. |
| `SUPPORT_TICKET_MAX_BODY_LENGTH` | Максимальная длина сообщения. |
| `SUPPORT_TICKET_MAX_SUBJECT_LENGTH` | Максимальная длина темы. |
| `SUPPORT_TICKET_RATE_LIMIT_PER_HOUR` | Лимит новых тикетов в час. |
| `SUPPORT_ADMIN_NOTIFICATION_COOLDOWN_SECONDS` | Пауза между Telegram/log уведомлениями. |
| `SUPPORT_ADMIN_EMAIL_COOLDOWN_SECONDS` | Пауза между email-уведомлениями. |

## Логирование

Часть настроек доступна в админке.

| Переменная | Назначение |
| --- | --- |
| `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. |
| `LOGS_PAGE_SIZE` | Размер страницы логов в админке. |
| `LOG_CHAT_ID` | Telegram chat/group ID для служебных уведомлений. |
| `LOG_THREAD_ID` | Topic/thread ID общего лог-чата. |
| `LOG_SUPPORT_THREAD_ID` | Topic/thread ID поддержки. |
| `LOG_NEW_USERS` | Логировать новые регистрации. |
| `LOG_PAYMENTS` | Логировать платежи. |
| `LOG_SUPPORT` | Логировать тикеты поддержки. |
| `LOG_PROMO_ACTIVATIONS` | Логировать активации промокодов. |
| `LOG_TRIAL_ACTIVATIONS` | Логировать активации trial. |
| `LOG_SUSPICIOUS_ACTIVITY` | Логировать подозрительную активность. |
| `LOG_ADMIN_ACTIONS` | Логировать действия администраторов. |

## Чеки, ссылки подключения и inline

| Переменная | Назначение |
| --- | --- |
| `NALOGO_INN` | ИНН самозанятого для LKNPD. |
| `NALOGO_PASSWORD` | Пароль LKNPD / «Мой налог». |
| `NALOGO_API_URL` | Базовый URL LKNPD API. |
| `NALOGO_RECEIPT_NAME_SUBSCRIPTION` | Название позиции чека подписки. |
| `NALOGO_RECEIPT_NAME_TRAFFIC` | Название позиции чека пакета трафика. |
| `CRYPT4_ENABLED` | Включает happ crypt4 для ссылок подключения. |
| `CRYPT4_REDIRECT_URL` | URL-обертка для кнопки подключения. |
| `CRYPT4_LINK_CACHE_TTL_SECONDS` | TTL кеша crypt4-ссылок. |
| `MY_DEVICES_SECTION_ENABLED` | Показывать раздел «Мои устройства». |
| `INLINE_REFERRAL_THUMBNAIL_URL` | Превью inline-результата рефералов. |
| `INLINE_USER_STATS_THUMBNAIL_URL` | Превью inline-результата пользовательской статистики. |
| `INLINE_FINANCIAL_STATS_THUMBNAIL_URL` | Превью inline-результата финансовой статистики. |
| `INLINE_SYSTEM_STATS_THUMBNAIL_URL` | Превью inline-результата системной статистики. |