Перейти к содержимому
minishop

Настройка окружения

Проект поддерживает два слоя конфигурации:

  • .env - bootstrap, инфраструктура, стабильные секреты и базовые доступы к Remnawave;
  • Web App админка - основной рекомендуемый способ менять продуктовые настройки после первого запуска.

Админка сохраняет overrides в базе данных и применяет их поверх .env. Это удобно для платежей, внешнего вида, поддержки, уведомлений, legacy-цен и большинства пользовательских параметров. Тарифы редактируются отдельно в разделе Система -> Тарифы и сохраняются в JSON-файл TARIFFS_CONFIG_PATH.

Полный справочник всех переменных вынесен в configuration/env-vars.md.

Минимальный .env

Заголовок раздела «Минимальный .env»

Начните с короткого примера:

cp .env.example .env
nano .env

Минимально заполните:

ПеременнаяЗачем нужна
BOT_TOKENТокен Telegram-бота.
ADMIN_IDSTelegram ID администраторов через запятую; без этого не попасть в Web App админку.
WEBHOOK_BASE_URLПубличный URL webhook-домена backend.
POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DBДоступы PostgreSQL для Compose и backend.
WEBAPP_ENABLEDВключает Web App и админку. Для первого запуска держите True.
WEBAPP_SESSION_SECRETСтабильный секрет сессий Web App.
WEBHOOK_SECRET_TOKENСтабильный secret token Telegram webhook.
SUBSCRIPTION_MINI_APP_URLПубличный HTTPS URL Mini App/frontend, например https://app.domain.com/. Это URL, который открывают кнопки Telegram и который указывается в BotFather; не добавляйте сюда /api или webhook-пути.
SUBSCRIPTION_GUIDES_ENABLED, SUBSCRIPTION_GUIDES_BOT_MENU_ENABLEDВстроенные инструкции установки в Web App и кнопках бота. По умолчанию включены; обычно их достаточно менять в админке.
PANEL_API_URL, PANEL_API_KEY, PANEL_WEBHOOK_SECRETБазовая интеграция с Remnawave. Эти значения стоит хранить в .env, но при необходимости их можно переопределить из админки.

WEBAPP_SESSION_SECRET и WEBHOOK_SECRET_TOKEN можно сгенерировать так:

openssl rand -hex 32

Если оставить эти секреты пустыми, приложение сгенерирует их на процесс, но после рестарта Web App-сессии станут невалидными, а Telegram webhook получит новый secret_token.

Если Web App выключен

Заголовок раздела «Если Web App выключен»

WEBAPP_ENABLED=False отключает пользовательский Web App и вместе с ним админ-панель. В таком состоянии нельзя зайти в Система -> Настройки и включить Web App обратно через UI.

Чтобы восстановить доступ:

  1. В .env выставьте WEBAPP_ENABLED=True.
  2. Перезапустите backend/frontend контейнеры, например docker compose up -d --force-recreate backend frontend.
  3. Откройте SUBSCRIPTION_MINI_APP_URL под Telegram-аккаунтом из ADMIN_IDS и при необходимости проверьте настройку в админке.

Настройка через админку

Заголовок раздела «Настройка через админку»

После запуска откройте Mini App под аккаунтом, чей Telegram ID указан в ADMIN_IDS, и перейдите в админ-панель.

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

  1. Система -> Настройки -> Remnawave: проверьте PANEL_API_URL, PANEL_API_KEY, PANEL_WEBHOOK_SECRET, базовые squads.
  2. Система -> Тарифы: создайте JSON-каталог тарифов, выберите Internal Squads, настройте period/traffic-модели, premium-сквады и HWID-пакеты.
  3. Система -> Настройки -> Инструкции подключения: проверьте, что Remnawave Panel отдает нужный Subscription Page config. JSON-override включайте только если нужно временно заменить конфиг панели.
  4. Система -> Настройки -> Платежи: включите нужные провайдеры и заполните их ключи.
  5. Внешний вид: настройте название, тему, логотип, favicon и accent.
  6. Система -> Настройки -> Поддержка / Уведомления: настройте тикеты, лог-чат, email-уведомления и напоминания.
  7. Общие настройки: заполните ссылки на поддержку, документы, статус сервиса и обязательный канал, если он нужен.

Изменения из админки пишутся в таблицу app_setting_overrides. При сбросе override снова используется значение из .env или дефолт из кода.

Что оставить только в .env

Заголовок раздела «Что оставить только в .env»

Не все настройки стоит переносить в базу. В .env остаются:

  • токен бота и ADMIN_IDS;
  • параметры PostgreSQL, Redis, портов и Compose;
  • WEBHOOK_BASE_URL, потому что Telegram webhook устанавливается при старте;
  • стабильные секреты WEBAPP_SESSION_SECRET и WEBHOOK_SECRET_TOKEN;
  • WEBAPP_THEMES_DIR, TARIFFS_CONFIG_PATH и низкоуровневые TTL/pool/worker-параметры;
  • Remnawave-доступы как базовый источник правды, даже если для удобства они доступны в админке.

Конфиг инструкций установки обычно не нужно хранить в локальном data-файле: по умолчанию приложение читает Subscription Page config из Remnawave Panel. SUBSCRIPTION_PAGE_CONFIG_PATH и SUBSCRIPTION_PAGE_CONFIG_JSON нужны как fallback или явный override из админки.

Файловые данные

Заголовок раздела «Файловые данные»

В штатном docker-compose.yml данные хранятся в named volume shop-data. Внутри него лежат тарифы, темы, логотипы и прочие файловые данные приложения.

Если для локальной разработки включаете bind mount ./data:/app/data, заранее создайте каталоги и отдайте их пользователю контейнера:

mkdir -p data/themes data/webapp-logo data/webapp-emoji data/tariffs
touch data/locales-overrides.json
chown -R 10001:10001 data
chmod -R u+rwX data
docker compose up -d --force-recreate backend worker

Проверить права можно так:

docker compose exec backend sh -lc 'id; touch /app/data/themes/test && rm /app/data/themes/test'

Дополнительные разделы

Заголовок раздела «Дополнительные разделы»