From 0df52d0235581e2461eb7d02f4c3d874fe6e59a1 Mon Sep 17 00:00:00 2001 From: 3252a8 <3252a8@proton.me> Date: Tue, 26 May 2026 21:45:44 +0300 Subject: [PATCH] docs: refactor docs structure --- README.md | 18 +-- deploy/examples/README.md | 12 +- deploy/examples/caddy/README.md | 2 +- deploy/examples/newt/README.md | 2 +- deploy/examples/nginx/README.md | 2 +- deploy/examples/nginx/ssl/README.md | 2 +- deploy/examples/no-proxy/README.md | 4 +- docs-site/astro.config.mjs | 36 +----- docs-site/scripts/sync-docs.mjs | 27 ++--- docs/administration/users.md | 2 +- docs/architecture.md | 58 +++++----- docs/configuration.md | 18 +-- docs/configuration/env-vars.md | 78 ++++++------- docs/configuration/security.md | 8 +- docs/deploy-examples/caddy.md | 39 ------- docs/deploy-examples/index.md | 39 ------- docs/deploy-examples/newt.md | 38 ------ docs/deploy-examples/nginx.md | 44 ------- docs/deploy-examples/no-proxy.md | 35 ------ docs/deployment.md | 165 +++++++++++++++++++++------ docs/features/admin-panel.md | 10 +- docs/features/core.md | 2 +- docs/features/payments.md | 160 +++++++++++++++++++++++--- docs/features/support.md | 2 +- docs/features/tariffs.md | 8 +- docs/features/web-app.md | 40 +++---- docs/getting-started/overview.md | 6 +- docs/getting-started/setup.md | 20 +++- docs/index.md | 6 +- docs/migrations/index.md | 4 +- docs/migrations/remnawave-tg-shop.md | 13 +-- docs/payments/cryptopay.md | 28 ----- docs/payments/freekassa.md | 16 --- docs/payments/heleket.md | 31 ----- docs/payments/platega.md | 30 ----- docs/payments/severpay.md | 28 ----- docs/payments/telegram-stars.md | 19 --- docs/payments/wata.md | 30 ----- docs/payments/yookassa.md | 16 --- docs/troubleshooting/issues.md | 4 +- docs/troubleshooting/logs.md | 22 ++-- 41 files changed, 455 insertions(+), 669 deletions(-) delete mode 100644 docs/deploy-examples/caddy.md delete mode 100644 docs/deploy-examples/index.md delete mode 100644 docs/deploy-examples/newt.md delete mode 100644 docs/deploy-examples/nginx.md delete mode 100644 docs/deploy-examples/no-proxy.md delete mode 100644 docs/payments/cryptopay.md delete mode 100644 docs/payments/freekassa.md delete mode 100644 docs/payments/heleket.md delete mode 100644 docs/payments/platega.md delete mode 100644 docs/payments/severpay.md delete mode 100644 docs/payments/telegram-stars.md delete mode 100644 docs/payments/wata.md delete mode 100644 docs/payments/yookassa.md diff --git a/README.md b/README.md index 1dfb662..8123f2b 100644 --- a/README.md +++ b/README.md @@ -26,22 +26,22 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи - статистика пользователей, подписок, платежей и синхронизации с Remnawave; - список пользователей с поиском, фильтрами и колонкой premium-трафика; - блокировка пользователей, поддержка через тикеты, рассылки, промокоды, логи действий и настройка разрешенных параметров приложения поверх `.env`; -- редактор JSON-каталога тарифов с period/traffic-моделями, Internal Squads, premium-сквадами и HWID-пакетами; -- настройки инструкций подключения: чтение конфига Subscription Page из Remnawave Panel, опциональный JSON-override и переключатель поведения кнопок бота; +- редактор JSON-каталога тарифов с моделями на срок/по трафику, Internal Squads, premium-сквадами и HWID-пакетами; +- настройки инструкций подключения: чтение конфига Subscription Page из Remnawave Panel, опциональное JSON-переопределение и переключатель поведения кнопок бота; - ручная синхронизация пользователей и подписок с панелью. ## Документация - [Входная страница документации](docs/index.md) - маршрут по установке, настройке, платежам, админке и диагностике. -- [Deploy examples](docs/deploy-examples/index.md) - готовые варианты запуска: Caddy, Nginx, Pangolin/Newt и no-proxy. +- [Развертывание](docs/deployment.md) - Docker Compose, Caddy, Nginx, Pangolin/Newt и запуск без обратного прокси. - [Настройка окружения](docs/configuration.md) - bootstrap `.env` и рекомендуемая настройка через Web App админку. - [Переменные `.env`](docs/configuration/env-vars.md) - полный справочник всех env-ключей по разделам. -- [Тарифы](docs/features/tariffs.md) - каталог тарифов, period- и traffic-модели, обычные и premium-докупки, premium-сквады, смена тарифа, HWID-лимиты и обработка трафика. +- [Тарифы](docs/features/tariffs.md) - каталог тарифов, модели на срок и по трафику, обычные и premium-докупки, premium-сквады, смена тарифа, HWID-лимиты и обработка трафика. - [Админ-панель](docs/features/admin-panel.md) - права доступа, настройки, редактор тарифов, premium-сквады и сохранение JSON-каталога. -- [Web App / Mini App](docs/features/web-app.md) - отдельный порт, домен, Telegram OAuth, email-вход, инструкции установки и реферальные ссылки. -- [Поддержка](docs/features/support.md) - тикеты в Mini App, входящий список админки, уведомления, лимиты и внешняя ссылка поддержки. +- [Веб-приложение / Mini App](docs/features/web-app.md) - отдельный порт, домен, Telegram OAuth, вход по email, инструкции установки и реферальные ссылки. +- [Поддержка пользователей / тикеты](docs/features/support.md) - тикеты в Mini App, входящий список админки, уведомления, лимиты и внешняя ссылка поддержки. - [Темы Web App](docs/features/webapp-themes.md) - кастомные темы, настройка внешнего вида, логотипы, CSS/ассеты и пайплайн создания новой темы. -- [Развертывание](docs/deployment.md) - Docker Compose, reverse proxy, Nginx, Caddy, вебхуки, запуск из образа и обновление версии (`IMAGE_TAG`). +- [Развертывание](docs/deployment.md) - Docker Compose, обратный прокси, Nginx, Caddy, вебхуки, запуск из образа и обновление версии (`IMAGE_TAG`). - [Миграции](docs/migrations/index.md) - готовые сценарии переноса с других ботов; сейчас описан `remnawave-tg-shop`. - [Миграция с remnawave-tg-shop](docs/migrations/remnawave-tg-shop.md) - готовый сценарий для legacy-стека. @@ -113,7 +113,7 @@ docker compose up -d --build # Логи приложения docker compose logs -f backend worker frontend -# Готовые production-примеры +# Рекомендуемый продакшен-вариант с Caddy cd deploy/examples/caddy # или nginx, newt, no-proxy cp .env.example .env nano .env @@ -123,7 +123,7 @@ docker compose up -d IMAGE_TAG=3.1.0 docker compose up -d ``` -Для production-запуска удобнее брать готовые папки из [`deploy/examples`](deploy/examples), а читать каноничные инструкции в [docs/deploy-examples/index.md](docs/deploy-examples/index.md): там отдельно описаны варианты для Caddy, Nginx, Newt/Pangolin и прямой публикации портов без reverse proxy. В папках рядом с compose лежат только конфиги и короткие ссылки на документацию. +Для продакшен-запуска удобнее брать готовые папки из [`deploy/examples`](deploy/examples), а читать каноничные инструкции в [docs/deployment.md](docs/deployment.md). Предпочтительный вариант для обычного публичного сервера - Caddy: он сам выпускает и продлевает HTTPS-сертификаты. В папках рядом с compose лежат только конфиги и короткие ссылки на документацию. GHCR image names for releases: diff --git a/deploy/examples/README.md b/deploy/examples/README.md index 67870a6..b0ab572 100644 --- a/deploy/examples/README.md +++ b/deploy/examples/README.md @@ -1,12 +1,12 @@ -# Deploy examples +# Примеры Docker Compose -Каноничная документация по вариантам запуска живет в [docs/deploy-examples/index.md](../../docs/deploy-examples/index.md). +Каноничная документация по вариантам запуска живет в [docs/deployment.md](../../docs/deployment.md). Эта папка хранит только рабочие compose-примеры и конфиги. Подробное описание не дублируется здесь, чтобы сайт документации и навигация из README использовали один источник. | Папка | Документация | | --- | --- | -| `caddy` | [Caddy](../../docs/deploy-examples/caddy.md) | -| `nginx` | [Nginx](../../docs/deploy-examples/nginx.md) | -| `newt` | [Pangolin / Newt](../../docs/deploy-examples/newt.md) | -| `no-proxy` | [No proxy](../../docs/deploy-examples/no-proxy.md) | +| `caddy` | [Развертывание с Caddy](../../docs/deployment.md#caddy-рекомендуемый-вариант) | +| `nginx` | [Развертывание с Nginx](../../docs/deployment.md#nginx) | +| `newt` | [Развертывание через Pangolin / Newt](../../docs/deployment.md#pangolin--newt) | +| `no-proxy` | [Запуск без обратного прокси](../../docs/deployment.md#без-обратного-прокси) | diff --git a/deploy/examples/caddy/README.md b/deploy/examples/caddy/README.md index 20686f2..f8d75ed 100644 --- a/deploy/examples/caddy/README.md +++ b/deploy/examples/caddy/README.md @@ -1,5 +1,5 @@ # Caddy -Каноничная инструкция: [docs/deploy-examples/caddy.md](../../../docs/deploy-examples/caddy.md). +Каноничная инструкция: [docs/deployment.md](../../../docs/deployment.md#caddy-рекомендуемый-вариант). Файлы этого примера остаются рядом: `docker-compose.yml`, `.env.example` и `Caddyfile`. diff --git a/deploy/examples/newt/README.md b/deploy/examples/newt/README.md index ef3cd4e..5db50a9 100644 --- a/deploy/examples/newt/README.md +++ b/deploy/examples/newt/README.md @@ -1,5 +1,5 @@ # Pangolin / Newt -Каноничная инструкция: [docs/deploy-examples/newt.md](../../../docs/deploy-examples/newt.md). +Каноничная инструкция: [docs/deployment.md](../../../docs/deployment.md#pangolin--newt). Файлы этого примера остаются рядом: `docker-compose.yml` и `.env.example`. diff --git a/deploy/examples/nginx/README.md b/deploy/examples/nginx/README.md index 675b9de..37d6241 100644 --- a/deploy/examples/nginx/README.md +++ b/deploy/examples/nginx/README.md @@ -1,5 +1,5 @@ # Nginx -Каноничная инструкция: [docs/deploy-examples/nginx.md](../../../docs/deploy-examples/nginx.md). +Каноничная инструкция: [docs/deployment.md](../../../docs/deployment.md#nginx). Файлы этого примера остаются рядом: `docker-compose.yml`, `.env.example`, `nginx.conf.template` и папка `ssl/` для сертификатов. diff --git a/deploy/examples/nginx/ssl/README.md b/deploy/examples/nginx/ssl/README.md index f1c4eeb..854f533 100644 --- a/deploy/examples/nginx/ssl/README.md +++ b/deploy/examples/nginx/ssl/README.md @@ -1,6 +1,6 @@ # TLS certificates -Каноничная инструкция по Nginx: [docs/deploy-examples/nginx.md](../../../../docs/deploy-examples/nginx.md). +Каноничная инструкция по Nginx: [docs/deployment.md](../../../../docs/deployment.md#nginx). Кладите сертификаты в подпапки, совпадающие с `WEBHOOK_HOST` и `MINIAPP_HOST`: diff --git a/deploy/examples/no-proxy/README.md b/deploy/examples/no-proxy/README.md index 2e2a6b1..931278d 100644 --- a/deploy/examples/no-proxy/README.md +++ b/deploy/examples/no-proxy/README.md @@ -1,5 +1,5 @@ -# No proxy +# Без обратного прокси -Каноничная инструкция: [docs/deploy-examples/no-proxy.md](../../../docs/deploy-examples/no-proxy.md). +Каноничная инструкция: [docs/deployment.md](../../../docs/deployment.md#без-обратного-прокси). Файлы этого примера остаются рядом: `docker-compose.yml` и `.env.example`. diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs index 0dd3ddc..14f6239 100644 --- a/docs-site/astro.config.mjs +++ b/docs-site/astro.config.mjs @@ -59,16 +59,8 @@ export default defineConfig({ { label: 'Главная', link: '/' }, { label: 'Обзор', slug: 'getting-started/overview' }, { label: 'Установка', slug: 'getting-started/setup' }, - { label: 'Deploy examples', slug: 'deploy-examples' }, - ], - }, - { - label: 'Варианты деплоя', - items: [ - { label: 'Caddy', slug: 'deploy-examples/caddy' }, - { label: 'Nginx', slug: 'deploy-examples/nginx' }, - { label: 'Pangolin / Newt', slug: 'deploy-examples/newt' }, - { label: 'Без reverse proxy', slug: 'deploy-examples/no-proxy' }, + { label: 'Архитектура', slug: 'reference/architecture' }, + { label: 'Развертывание', slug: 'reference/deployment' }, ], }, { @@ -86,23 +78,10 @@ export default defineConfig({ { label: 'Платежи', slug: 'features/payments' }, { label: 'Подписки', slug: 'features/subscriptions' }, { label: 'Тарифы', slug: 'features/tariffs' }, - { label: 'Mini App', slug: 'features/web-app' }, + { label: 'Веб-приложение / Mini App', slug: 'features/web-app' }, { label: 'Темы Web App', slug: 'features/webapp-themes' }, { label: 'Админ-панель', slug: 'features/admin-panel' }, - { label: 'Поддержка', slug: 'features/support' }, - ], - }, - { - label: 'Платежные системы', - items: [ - { label: 'YooKassa', slug: 'payments/yookassa' }, - { label: 'FreeKassa', slug: 'payments/freekassa' }, - { label: 'Platega', slug: 'payments/platega' }, - { label: 'SeverPay', slug: 'payments/severpay' }, - { label: 'Wata', slug: 'payments/wata' }, - { label: 'CryptoPay', slug: 'payments/cryptopay' }, - { label: 'Heleket', slug: 'payments/heleket' }, - { label: 'Telegram Stars', slug: 'payments/telegram-stars' }, + { label: 'Поддержка пользователей / тикеты', slug: 'features/support' }, ], }, { @@ -126,13 +105,6 @@ export default defineConfig({ { label: 'Логи', slug: 'troubleshooting/logs' }, ], }, - { - label: 'Справочник', - items: [ - { label: 'Архитектура', slug: 'reference/architecture' }, - { label: 'Развертывание', slug: 'reference/deployment' }, - ], - }, ], }), ], diff --git a/docs-site/scripts/sync-docs.mjs b/docs-site/scripts/sync-docs.mjs index b91ae97..6d3c063 100644 --- a/docs-site/scripts/sync-docs.mjs +++ b/docs-site/scripts/sync-docs.mjs @@ -15,34 +15,21 @@ const descriptions = { 'configuration/env-vars.md': 'Полный справочник переменных окружения Remnawave Minishop.', 'features/core.md': 'Пользовательские и админские сценарии Remnawave Minishop.', 'features/payments.md': 'Платежные провайдеры, кнопки оплаты и webhook-обработка.', - 'features/subscriptions.md': 'Period- и traffic-тарифы, premium-сквады, HWID-устройства и жизненный цикл подписки.', - 'features/tariffs.md': 'Каталог тарифов, period/traffic-модели, premium-сквады и HWID-устройства.', + 'features/subscriptions.md': 'Тарифы на срок и по трафику, premium-сквады, HWID-устройства и жизненный цикл подписки.', + 'features/tariffs.md': 'Каталог тарифов, модели на срок/по трафику, premium-сквады и HWID-устройства.', 'features/web-app.md': 'Telegram Mini App, авторизация, публичные инструкции и проксирование.', 'features/webapp-themes.md': 'Кастомные темы, CSS-токены, ассеты и пайплайн создания темы.', 'features/admin-panel.md': 'Возможности админ-панели, управление пользователями, настройками, тарифами и поддержкой.', - 'features/support.md': 'Пользовательские тикеты, админский inbox, уведомления и лимиты поддержки.', - 'deploy-examples/index.md': 'Как выбрать готовый deploy example для production или проверки.', - 'deploy-examples/caddy.md': 'Запуск Remnawave Minishop с Caddy и автоматическим HTTPS.', - 'deploy-examples/nginx.md': 'Запуск Remnawave Minishop с Nginx и внешними TLS-сертификатами.', - 'deploy-examples/newt.md': 'Запуск через Pangolin/Newt без входящих портов на сервере приложения.', - 'deploy-examples/no-proxy.md': 'Прямой запуск backend и frontend портов без reverse proxy.', + 'features/support.md': 'Пользовательские тикеты, список обращений в админке, уведомления и лимиты поддержки.', 'migrations/index.md': 'Готовые сценарии миграции в Remnawave Minishop с других ботов.', 'migrations/remnawave-tg-shop.md': 'Перенос данных со старого remnawave-tg-shop на split-архитектуру Minishop.', - 'payments/yookassa.md': 'Быстрый вход в настройку YooKassa для Remnawave Minishop.', - 'payments/freekassa.md': 'Быстрый вход в настройку FreeKassa для Remnawave Minishop.', - 'payments/platega.md': 'Настройка Platega, отдельных СБП/карта и crypto-кнопок.', - 'payments/severpay.md': 'Настройка SeverPay, MID, token, return URL и срока жизни ссылки.', - 'payments/wata.md': 'Настройка Wata, API token, TTL ссылки, подписи webhook и trusted IP.', - 'payments/cryptopay.md': 'Настройка CryptoPay, токена, сети, currency type и asset.', - 'payments/heleket.md': 'Настройка Heleket, merchant ID, payment API key, invoice currency и webhook-проверок.', - 'payments/telegram-stars.md': 'Оплата подписок и докупок через Telegram Stars.', 'administration/users.md': 'Где управлять пользователями, подписками, блокировками и поддержкой.', - 'administration/maintenance.md': 'Обновления, миграции, резервные копии и проверки production-стека.', + 'administration/maintenance.md': 'Обновления, миграции, резервные копии и проверки продакшен-стека.', 'troubleshooting/issues.md': 'Короткие чеклисты для частых проблем запуска, вебхуков, Mini App и платежей.', 'troubleshooting/logs.md': 'Какие логи смотреть при диагностике backend, worker, frontend, миграций и вебхуков.', 'architecture.md': 'Краткая архитектура backend, frontend, worker и инфраструктурных сервисов.', 'configuration.md': 'Минимальный .env, bootstrap-секреты и настройка через Web App админку.', - 'deployment.md': 'Docker Compose, reverse proxy, TLS, образы, обновления и резервные копии.', + 'deployment.md': 'Docker Compose, обратный прокси, TLS, образы, обновления и резервные копии.', }; const imageExtensions = new Set(['.avif', '.gif', '.jpeg', '.jpg', '.png', '.svg', '.webp']); @@ -114,8 +101,8 @@ function extraFrontmatter(sourceRelativePath) { ' - text: "Быстрый старт"', ' link: /getting-started/setup/', ' icon: right-arrow', - ' - text: "Deploy examples"', - ' link: /deploy-examples/', + ' - text: "Развертывание"', + ' link: /reference/deployment/', ' icon: setting', ' variant: minimal', ]; diff --git a/docs/administration/users.md b/docs/administration/users.md index 7b322c2..7f6232d 100644 --- a/docs/administration/users.md +++ b/docs/administration/users.md @@ -14,6 +14,6 @@ ## Связанные разделы - [Админ-панель](../features/admin-panel.md) -- [Поддержка](../features/support.md) +- [Поддержка пользователей / тикеты](../features/support.md) - [Тарифы](../features/tariffs.md) - [Mini App](../features/web-app.md) diff --git a/docs/architecture.md b/docs/architecture.md index 53a3dc2..586f6e1 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -1,48 +1,42 @@ -# Project Architecture +# Архитектура проекта -The repository is split by runtime responsibility: +Репозиторий разделен по зонам ответственности рантайма: ```text -backend/ Python application code - bot/ Telegram bot, aiohttp APIs, webhooks, services - config/ Pydantic settings and tariff/theme config loaders - db/ SQLAlchemy models, DAL, migrations - main_backend.py aiohttp backend entrypoint - main_worker.py background worker entrypoint - main_migrate.py one-shot migration entrypoint - requirements.txt Python runtime dependencies +backend/ Python-код приложения + bot/ Telegram-бот, aiohttp API, вебхуки, сервисы + config/ Pydantic-настройки и загрузчики тарифов/тем + db/ SQLAlchemy-модели, DAL, миграции + main_backend.py точка входа aiohttp backend + main_worker.py точка входа фонового worker + main_migrate.py одноразовый запуск миграций + requirements.txt Python-зависимости рантайма -frontend/ Svelte/Vite Mini App and admin UI - src/ Svelte source code - scripts/ frontend build helpers - package.json Node scripts and dependencies +frontend/ Svelte/Vite Mini App и админка + src/ исходный код Svelte + scripts/ вспомогательные скрипты сборки frontend + package.json Node-скрипты и зависимости deploy/ - docker/ Dockerfile, nginx and caddy runtime config - compose/ legacy/alternate compose examples + docker/ Dockerfile, nginx- и caddy-конфиги рантайма + examples/ готовые Docker Compose примеры запуска -data/ runtime data mounted in containers -locales/ bot and Web App translations -tests/ Python test suite +data/ данные рантайма, монтируемые в контейнеры +locales/ переводы бота и Web App +tests/ Python-тесты ``` -The default `docker-compose.yml` stays in the repository root so `docker compose up` remains the -simple production path. It builds three application images from `deploy/docker/Dockerfile`: +Основной `docker-compose.yml` находится в корне репозитория, чтобы `docker compose up` оставался простым продакшен-путем. Он собирает три прикладных образа из `deploy/docker/Dockerfile`: -- `backend`: aiohttp APIs and webhooks only. -- `worker`: tariff traffic worker, panel sync, webhook queue consumers. -- `frontend`: static Svelte assets served by nginx. +- `backend`: aiohttp API и вебхуки. +- `worker`: worker тарифов, синхронизация с панелью, обработчики очередей вебхуков. +- `frontend`: статические Svelte-ассеты, которые отдает nginx. -The `migrate` service is a one-shot container based on the backend image. It is part of the -default Compose dependency graph: Postgres and Redis become healthy, `migrate` applies -`Base.metadata.create_all` and pending `schema_migrations`, then `backend` and `worker` start -only after `migrate` exits successfully. This keeps migrations automatic for `docker compose up` -without running them inside every backend replica. +Сервис `migrate` - одноразовый контейнер на базе backend-образа. Он входит в стандартный Compose-граф: Postgres и Redis переходят в healthy-состояние, `migrate` применяет `Base.metadata.create_all` и ожидающие `schema_migrations`, а затем `backend` и `worker` стартуют только после успешного завершения `migrate`. Так миграции остаются автоматическими для `docker compose up`, но не запускаются внутри каждой backend-реплики. -Python imports intentionally remain `bot.*`, `config.*`, and `db.*`. Runtime containers set -`PYTHONPATH=/app/backend`; local tests use the same layout through `pytest.ini`. +Python-импорты намеренно остаются в пространствах `bot.*`, `config.*` и `db.*`. Контейнеры рантайма выставляют `PYTHONPATH=/app/backend`; локальные тесты используют такую же раскладку через `pytest.ini`. -Common commands: +Основные команды: ```bash docker compose up -d --build diff --git a/docs/configuration.md b/docs/configuration.md index 1ecffe5..d7b0ec5 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -28,7 +28,7 @@ nano .env | `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. | +| `WEBHOOK_SECRET_TOKEN` | Стабильный секретный токен вебхука Telegram. | | `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`, но при необходимости их можно переопределить из админки. | @@ -39,7 +39,7 @@ nano .env openssl rand -hex 32 ``` -Если оставить эти секреты пустыми, приложение сгенерирует их на процесс, но после рестарта Web App-сессии станут невалидными, а Telegram webhook получит новый `secret_token`. +Если оставить эти секреты пустыми, приложение сгенерирует их на процесс, но после рестарта Web App-сессии станут невалидными, а вебхук Telegram получит новый `secret_token`. ## Если Web App выключен @@ -58,8 +58,8 @@ openssl rand -hex 32 Рекомендуемый порядок первичной настройки: 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 включайте только если нужно временно заменить конфиг панели. +2. **Система -> Тарифы**: создайте JSON-каталог тарифов, выберите Internal Squads, настройте модели на срок/по трафику, premium-сквады и HWID-пакеты. +3. **Система -> Настройки -> Инструкции подключения**: проверьте, что Remnawave Panel отдает нужный конфиг Subscription Page. JSON-переопределение включайте только если нужно временно заменить конфиг панели. 4. **Система -> Настройки -> Платежи**: включите нужные провайдеры и заполните их ключи. 5. **Внешний вид**: настройте название, тему, логотип, favicon и accent. 6. **Система -> Настройки -> Поддержка / Уведомления**: настройте тикеты, лог-чат, email-уведомления и напоминания. @@ -73,12 +73,12 @@ openssl rand -hex 32 - токен бота и `ADMIN_IDS`; - параметры PostgreSQL, Redis, портов и Compose; -- `WEBHOOK_BASE_URL`, потому что Telegram webhook устанавливается при старте; +- `WEBHOOK_BASE_URL`, потому что вебхук Telegram устанавливается при старте; - стабильные секреты `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 из админки. +Конфиг инструкций установки обычно не нужно хранить в локальном `data`-файле: по умолчанию приложение читает конфиг Subscription Page из Remnawave Panel. `SUBSCRIPTION_PAGE_CONFIG_PATH` и `SUBSCRIPTION_PAGE_CONFIG_JSON` нужны как резервный путь или явное переопределение из админки. ## Файловые данные @@ -105,6 +105,6 @@ docker compose exec backend sh -lc 'id; touch /app/data/themes/test && rm /app/d - [configuration/env-vars.md](configuration/env-vars.md) - полный справочник переменных `.env`. - [features/admin-panel.md](features/admin-panel.md) - как устроены overrides и allowlist настроек. - [features/tariffs.md](features/tariffs.md) - JSON-каталог тарифов и редактор тарифов. -- [features/web-app.md](features/web-app.md) - домен Mini App, Telegram OAuth и email-вход. -- [features/support.md](features/support.md) - тикеты поддержки и уведомления. -- [deployment.md](deployment.md) - Docker Compose, reverse proxy, Caddy/Nginx и обновления. +- [Веб-приложение / Mini App](features/web-app.md) - домен Mini App, Telegram OAuth и вход по email. +- [Поддержка пользователей / тикеты](features/support.md) - тикеты поддержки и уведомления. +- [Развертывание](deployment.md) - Docker Compose, обратный прокси, Caddy/Nginx и обновления. diff --git a/docs/configuration/env-vars.md b/docs/configuration/env-vars.md index 6c05bd7..800c350 100644 --- a/docs/configuration/env-vars.md +++ b/docs/configuration/env-vars.md @@ -1,6 +1,6 @@ # Переменные окружения -`.env` нужен прежде всего для bootstrap: токен бота, доступ к базе, публичный webhook URL и стабильные секреты. После первого входа большая часть продуктовых настроек меняется в Web App админке и сохраняется в БД как override поверх `.env`. +`.env` нужен прежде всего для bootstrap: токен бота, доступ к базе, публичный URL вебхуков и стабильные секреты. После первого входа большая часть продуктовых настроек меняется в Web App админке и сохраняется в БД как переопределения поверх `.env`. Рекомендуемый порядок: @@ -14,13 +14,13 @@ | --- | --- | --- | | `BOT_TOKEN` | Только `.env` | Токен Telegram-бота. | | `ADMIN_IDS` | Только `.env` | Telegram ID администраторов через запятую. Нужен для первого входа в админку. | -| `WEBHOOK_BASE_URL` | `.env` | Публичный URL backend/webhook-домена. Используется для Telegram, платежных и Remnawave webhook URL. | +| `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 webhook. Если пустой, генерируется на процесс. | +| `WEBHOOK_SECRET_TOKEN` | `.env` | Секрет вебхука Telegram. Если пустой, генерируется на процесс. | ## Инфраструктура и Compose @@ -29,10 +29,10 @@ | `APP_ENV_FILE` | CLI/Compose | Путь к env-файлу вместо `.env`. | | `IMAGE_TAG` | CLI/Compose | Тег Docker-образов. | | `FRONTEND_PORT` | `.env` / Compose | Хостовый порт frontend nginx. По умолчанию `8082`. | -| `WEB_SERVER_HOST` | `.env` | Внутренний host backend webhook server. Обычно `0.0.0.0`. | -| `WEB_SERVER_PORT` | `.env` / Compose | Хостовый порт backend webhook server. По умолчанию `8080`. | -| `WEBAPP_SERVER_HOST` | `.env` | Внутренний host Web App API server. Обычно `0.0.0.0`. | -| `WEBAPP_SERVER_PORT` | `.env` | Внутренний порт Web App API server. По умолчанию `8081`. | +| `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. | @@ -41,7 +41,7 @@ | `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 reverse proxy, которым доверяется `X-Forwarded-For`. | +| `TRUSTED_PROXIES` | `.env` | IP/CIDR обратных прокси, которым доверяется `X-Forwarded-For`. | | `HTTP_BIND` / `HTTPS_BIND` | Caddy Compose | Адреса публикации Caddy-варианта. | | `NEWT_ID` / `NEWT_SECRET` | Dev Compose | Доступы Newt в dev-compose. | @@ -105,29 +105,29 @@ | `USER_TRAFFIC_STRATEGY` | Legacy-стратегия лимита трафика. | | `USER_HWID_DEVICE_LIMIT` | Legacy-лимит HWID-устройств по умолчанию. | -## Web App, внешний вид и Telegram Login +## Веб-приложение, внешний вид и 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-кнопках, referral-ссылках, email-входе и BotFather Mini App settings. Не указывайте здесь `/api` или webhook-пути. | +| `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/`. По умолчанию `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` / админка | Fallback-путь к локальному Remnawave Subscription Page v1 JSON config, если конфиг панели выключен или недоступен. По умолчанию `data/subpage-config/multiapp.json`; файл не создается автоматически. | -| `SUBSCRIPTION_PAGE_CONFIG_JSON` | Админка | Опциональный JSON-override Remnawave Subscription Page v1. Применяется только при включенном `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED`; backend валидирует JSON при сохранении. | +| `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` | Client ID Telegram OAuth / OpenID Connect. Если пусто, берется bot ID из `BOT_TOKEN`. | -| `TELEGRAM_OAUTH_CLIENT_SECRET` | `.env` | Client Secret Telegram OAuth / OpenID Connect. | -| `TELEGRAM_OAUTH_REQUEST_ACCESS` | `.env` | Дополнительные permissions, например `write`. | +| `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-поле, игнорируется. | @@ -139,9 +139,9 @@ Инструкции установки совместимы с Remnawave Subscription Page v1 config: `version`, `locales`, `brandingSettings`, `uiConfig`, `baseSettings`, `baseTranslations`, `svgLibrary` и `platforms`. Текстовые поля рендерятся как текст, а SVG из `svgLibrary` проходит санитарную проверку перед отдачей в Web App. -## SMTP и email-вход +## SMTP и вход по email -Email-вход появляется только если заполнены `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD` и `SMTP_FROM_EMAIL`. +Вход по email появляется только если заполнены `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD` и `SMTP_FROM_EMAIL`. | Переменная | Назначение | | --- | --- | @@ -150,7 +150,7 @@ Email-вход появляется только если заполнены `SM | `SMTP_FALLBACK_PORTS` | Резервные порты через запятую. | | `SMTP_TIMEOUT_SECONDS` | Таймаут SMTP-попытки. | | `SMTP_USERNAME` | SMTP login. | -| `SMTP_PASSWORD` | SMTP password/API key. | +| `SMTP_PASSWORD` | SMTP-пароль или API-ключ. | | `SMTP_FROM_EMAIL` | Подтвержденный адрес отправителя. | | `SMTP_FROM_NAME` | Имя отправителя. | | `SMTP_STARTTLS` | Использовать STARTTLS. | @@ -164,7 +164,7 @@ Email-вход появляется только если заполнены `SM ## Платежи -Все включатели, секреты и presentation-настройки провайдеров доступны в админке: **Система -> Настройки -> Платежи**. +Все включатели, секреты и настройки отображения провайдеров доступны в админке: **Система -> Настройки -> Платежи**. | Переменная | Назначение | | --- | --- | @@ -185,7 +185,7 @@ Email-вход появляется только если заполнены `SM | `CRYPTOPAY_ENABLED` | Включает CryptoPay. | | `HELEKET_ENABLED` | Включает Heleket. | -Конкретные presentation-ключи: +Конкретные ключи отображения: ```text PAYMENT_YOOKASSA_WEBAPP_LABEL_RU @@ -249,7 +249,7 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI | Переменная | Назначение | | --- | --- | | `YOOKASSA_SHOP_ID` | ID магазина. | -| `YOOKASSA_SECRET_KEY` | Secret key. | +| `YOOKASSA_SECRET_KEY` | Секретный ключ. | | `YOOKASSA_RETURN_URL` | URL возврата после оплаты. | | `YOOKASSA_DEFAULT_RECEIPT_EMAIL` | Email для чеков по умолчанию. | | `YOOKASSA_VAT_CODE` | Код НДС. | @@ -261,22 +261,22 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI | Переменная | Назначение | | --- | --- | | `FREEKASSA_MERCHANT_ID` | ID магазина. | -| `FREEKASSA_API_KEY` | API key. | +| `FREEKASSA_API_KEY` | API-ключ. | | `FREEKASSA_SECOND_SECRET` | Секрет уведомлений. | | `FREEKASSA_PAYMENT_IP` | Публичный IP сервера для запроса оплаты. | | `FREEKASSA_PAYMENT_METHOD_ID` | ID метода оплаты. | -| `FREEKASSA_TRUSTED_IPS` | IP-allowlist webhook-источников. | +| `FREEKASSA_TRUSTED_IPS` | Список доверенных IP webhook-источников. | ### Platega | Переменная | Назначение | | --- | --- | | `PLATEGA_BASE_URL` | Базовый URL API. | -| `PLATEGA_MERCHANT_ID` | Merchant ID. | -| `PLATEGA_SECRET` | API secret. | -| `PLATEGA_PAYMENT_METHOD` | Legacy/fallback method ID. | -| `PLATEGA_SBP_METHOD` | Method ID для СБП. | -| `PLATEGA_CRYPTO_METHOD` | Method ID для крипто. | +| `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 неуспешного возврата. | @@ -286,7 +286,7 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI | --- | --- | | `SEVERPAY_BASE_URL` | Базовый URL API. | | `SEVERPAY_MID` | Merchant MID. | -| `SEVERPAY_TOKEN` | API token/secret. | +| `SEVERPAY_TOKEN` | API-токен или секрет. | | `SEVERPAY_RETURN_URL` | URL возврата. | | `SEVERPAY_LIFETIME_MINUTES` | Время жизни платежной ссылки. | @@ -295,19 +295,19 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI | Переменная | Назначение | | --- | --- | | `WATA_BASE_URL` | Базовый URL API. | -| `WATA_API_TOKEN` | Bearer token. | +| `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` | Cached public key; если пусто, загружается из API. | -| `WATA_TRUSTED_IPS` | IP-allowlist webhook-источников. | +| `WATA_PUBLIC_KEY` | Закешированный публичный ключ; если пусто, загружается из API. | +| `WATA_TRUSTED_IPS` | Список доверенных IP webhook-источников. | ### CryptoPay | Переменная | Назначение | | --- | --- | -| `CRYPTOPAY_TOKEN` | API token CryptoPay. | +| `CRYPTOPAY_TOKEN` | API-токен CryptoPay. | | `CRYPTOPAY_NETWORK` | `mainnet` или `testnet`. | | `CRYPTOPAY_CURRENCY_TYPE` | `fiat` или `crypto`. | | `CRYPTOPAY_ASSET` | Актив, например `RUB`, `USDT`, `BTC`. | @@ -318,7 +318,7 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI | --- | --- | | `HELEKET_BASE_URL` | Базовый URL API. | | `HELEKET_MERCHANT_ID` | UUID мерчанта. | -| `HELEKET_API_KEY` | Payment API key. | +| `HELEKET_API_KEY` | Ключ платежного API. | | `HELEKET_CURRENCY` | Валюта инвойса. | | `HELEKET_TO_CURRENCY` | Целевая криптовалюта для конвертации. | | `HELEKET_NETWORK` | Сеть, например `tron`, `bsc`, `eth`. | @@ -326,7 +326,7 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI | `HELEKET_SUCCESS_URL` | URL после успешной оплаты. | | `HELEKET_LIFETIME_SECONDS` | TTL инвойса: 300..43200. | | `HELEKET_VERIFY_WEBHOOK_SIGNATURE` | Проверять подпись webhook. | -| `HELEKET_TRUSTED_IPS` | IP-allowlist webhook-источников. | +| `HELEKET_TRUSTED_IPS` | Список доверенных IP webhook-источников. | ## Тарифы и legacy-цены @@ -345,7 +345,7 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI | `TRAFFIC_PACKAGES` | Legacy-пакеты трафика RUB, формат `10:199,50:799`. | | `STARS_TRAFFIC_PACKAGES` | Legacy-пакеты трафика Stars. | -## Trial, referral и уведомления +## Пробный период, рефералы и уведомления Эти настройки доступны в админке. @@ -368,7 +368,7 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI ## Поддержка -Подробный сценарий описан в [features/support.md](../features/support.md). +Подробный сценарий описан в разделе [поддержка пользователей / тикеты](../features/support.md). | Переменная | Назначение | | --- | --- | @@ -377,8 +377,8 @@ PAYMENT_HELEKET_TELEGRAM_EMOJI | `SUPPORT_TICKET_MAX_BODY_LENGTH` | Максимальная длина сообщения. | | `SUPPORT_TICKET_MAX_SUBJECT_LENGTH` | Максимальная длина темы. | | `SUPPORT_TICKET_RATE_LIMIT_PER_HOUR` | Лимит новых тикетов в час. | -| `SUPPORT_ADMIN_NOTIFICATION_COOLDOWN_SECONDS` | Cooldown Telegram/log уведомлений. | -| `SUPPORT_ADMIN_EMAIL_COOLDOWN_SECONDS` | Cooldown email-уведомлений. | +| `SUPPORT_ADMIN_NOTIFICATION_COOLDOWN_SECONDS` | Пауза между Telegram/log уведомлениями. | +| `SUPPORT_ADMIN_EMAIL_COOLDOWN_SECONDS` | Пауза между email-уведомлениями. | ## Логирование diff --git a/docs/configuration/security.md b/docs/configuration/security.md index f0efab5..55ee64c 100644 --- a/docs/configuration/security.md +++ b/docs/configuration/security.md @@ -5,7 +5,7 @@ ## Секреты - `WEBAPP_SESSION_SECRET` должен быть постоянным между рестартами, иначе Web App-сессии станут невалидными. -- `WEBHOOK_SECRET_TOKEN` защищает Telegram webhook. +- `WEBHOOK_SECRET_TOKEN` защищает вебхук Telegram. - `PANEL_WEBHOOK_SECRET` проверяет входящие события Remnawave Panel. - Платежные токены и webhook-секреты храните в `.env` или настройках админки с учетом доступа к серверу. @@ -23,15 +23,15 @@ openssl rand -hex 32 ## Публичные URL -- `WEBHOOK_BASE_URL` должен вести на backend webhook server. -- `SUBSCRIPTION_MINI_APP_URL` должен вести на frontend/Mini App. +- `WEBHOOK_BASE_URL` должен вести на backend-сервер вебхуков. +- `SUBSCRIPTION_MINI_APP_URL` должен вести на frontend/Mini App-домен. - Не добавляйте `/api`, `/auth` или webhook-пути в `SUBSCRIPTION_MINI_APP_URL`. ## Дополнительно - Используйте HTTPS на всех публичных доменах. - Ограничивайте доступ к серверу и `.env`. -- Следите за логами платежных вебхуков и panel webhooks. +- Следите за логами платежных вебхуков и вебхуков панели. - После ротации секретов перезапускайте соответствующие сервисы и проверяйте вебхуки. См. также [переменные окружения](env-vars.md) и [развертывание](../deployment.md). diff --git a/docs/deploy-examples/caddy.md b/docs/deploy-examples/caddy.md deleted file mode 100644 index 003da0c..0000000 --- a/docs/deploy-examples/caddy.md +++ /dev/null @@ -1,39 +0,0 @@ -# Caddy - -Вариант `deploy/examples/caddy` подходит, если нужен самый простой публичный HTTPS. Caddy сам выпускает и продлевает сертификаты Let's Encrypt. - -## Требования - -- На сервере открыты входящие `80/tcp` и `443/tcp`. -- DNS-записи `WEBHOOK_HOST` и `MINIAPP_HOST` смотрят на этот сервер. -- В `.env` заполнены домены, токены, секреты и доступы к Remnawave. - -## Запуск - -```bash -cd deploy/examples/caddy -cp .env.example .env -nano .env -docker compose up -d -``` - -Минимально поменяйте: - -- `WEBHOOK_HOST` и `MINIAPP_HOST`; -- `BOT_TOKEN`, `ADMIN_IDS`; -- `POSTGRES_PASSWORD`; -- `WEBAPP_SESSION_SECRET`, `WEBHOOK_SECRET_TOKEN`; -- `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET`. - -## Проверка - -```bash -docker compose ps -docker compose logs -f caddy backend worker frontend -``` - -Если нужна нестандартная логика Caddy, правьте `deploy/examples/caddy/Caddyfile` и перезапускайте: - -```bash -docker compose up -d --force-recreate caddy -``` diff --git a/docs/deploy-examples/index.md b/docs/deploy-examples/index.md deleted file mode 100644 index 94b9f17..0000000 --- a/docs/deploy-examples/index.md +++ /dev/null @@ -1,39 +0,0 @@ -# Deploy examples - -В `deploy/examples` лежат самодостаточные Compose-варианты для разных способов публикации Minishop. Каждый пример запускается из своей директории и содержит собственный `docker-compose.yml`, `.env.example` и README. - -```bash -cp .env.example .env -nano .env -docker compose up -d -``` - -После старта проверяйте: - -```bash -docker compose ps -docker compose logs -f backend worker frontend -``` - -## Какой вариант выбрать - -| Вариант | Когда использовать | Где лежит | -| --- | --- | --- | -| [Caddy](caddy.md) | Нужен самый простой публичный HTTPS с автоматическими сертификатами Let's Encrypt. | `deploy/examples/caddy` | -| [Nginx](nginx.md) | Уже используете Nginx и готовы положить TLS-сертификаты рядом с примером. | `deploy/examples/nginx` | -| [Pangolin/Newt](newt.md) | Публикуете сервисы через туннель без входящих портов на сервере приложения. | `deploy/examples/newt` | -| [No proxy](no-proxy.md) | Нужно напрямую открыть порты backend/frontend или проверить стек без reverse proxy. | `deploy/examples/no-proxy` | - -## Два публичных URL - -Для production обычно нужны два домена: - -- webhook/backend URL для Telegram, платежных систем и Remnawave webhooks; -- Mini App/frontend URL для Telegram Mini App, Web App и админки. - -Пример: - -```text -https://webhooks.example.com -> backend:8080 -https://app.example.com -> frontend:80 -``` diff --git a/docs/deploy-examples/newt.md b/docs/deploy-examples/newt.md deleted file mode 100644 index b7a69be..0000000 --- a/docs/deploy-examples/newt.md +++ /dev/null @@ -1,38 +0,0 @@ -# Pangolin / Newt - -Вариант `deploy/examples/newt` подходит, если сервер приложения не должен принимать входящие соединения. Newt подключается к Pangolin, а публичные домены настраиваются ресурсами в панели Pangolin. - -## Запуск - -```bash -cd deploy/examples/newt -cp .env.example .env -nano .env -docker compose up -d -``` - -В `.env` заполните: - -- `WEBHOOK_HOST` и `MINIAPP_HOST` - публичные домены ресурсов в Pangolin; -- `PANGOLIN_ENDPOINT`, `NEWT_ID`, `NEWT_SECRET` - значения из настроек site/client в Pangolin; -- обычные переменные приложения: `BOT_TOKEN`, `ADMIN_IDS`, `POSTGRES_PASSWORD`, секреты и доступ к Remnawave. - -## Ресурсы Pangolin - -Создайте два HTTP-ресурса для Newt site: - -| Публичный домен | Upstream | -| --- | --- | -| `https://webhooks.example.com` | `http://backend:8080` | -| `https://app.example.com` | `http://frontend:80` | - -Домены в Pangolin должны совпадать с `WEBHOOK_HOST` и `MINIAPP_HOST`. - -Официальная инструкция Pangolin по установке Newt site: . - -## Проверка - -```bash -docker compose ps -docker compose logs -f newt backend worker frontend -``` diff --git a/docs/deploy-examples/nginx.md b/docs/deploy-examples/nginx.md deleted file mode 100644 index 0555914..0000000 --- a/docs/deploy-examples/nginx.md +++ /dev/null @@ -1,44 +0,0 @@ -# Nginx - -Вариант `deploy/examples/nginx` поднимает Nginx в той же Docker-сети, что и приложение. Он подходит, если у вас уже есть TLS-сертификаты или нужен ручной контроль Nginx-конфига. - -## Маршрутизация - -- `WEBHOOK_HOST` проксируется в `backend:8080`. -- `MINIAPP_HOST` проксируется в `frontend:80`. -- `frontend` сам проксирует внутренние `/api`, `/auth` и ассеты тем в `backend:8081`. - -## Подготовка - -```bash -cd deploy/examples/nginx -cp .env.example .env -nano .env -``` - -Положите TLS-сертификаты в `ssl/`: - -```text -ssl/ - webhooks.example.com/ - fullchain.pem - privkey.pem - app.example.com/ - fullchain.pem - privkey.pem -``` - -Имена папок должны совпадать с `WEBHOOK_HOST` и `MINIAPP_HOST` в `.env`. - -## Запуск - -```bash -docker compose up -d -docker compose logs -f nginx backend worker frontend -``` - -Если нужно поменять заголовки, лимиты или TLS-настройки, правьте `deploy/examples/nginx/nginx.conf.template` и перезапускайте: - -```bash -docker compose up -d --force-recreate nginx -``` diff --git a/docs/deploy-examples/no-proxy.md b/docs/deploy-examples/no-proxy.md deleted file mode 100644 index 871b0b0..0000000 --- a/docs/deploy-examples/no-proxy.md +++ /dev/null @@ -1,35 +0,0 @@ -# Без reverse proxy - -Вариант `deploy/examples/no-proxy` напрямую публикует HTTP-порты backend и frontend. Он удобен для локальной проверки, внутренней сети или ситуации, когда HTTPS завершается внешней платформой. - -## Порты - -- backend/webhooks: `WEB_SERVER_BIND`, по умолчанию `0.0.0.0:8080`; -- frontend/Mini App: `FRONTEND_BIND`, по умолчанию `0.0.0.0:8082`. - -## Запуск - -```bash -cd deploy/examples/no-proxy -cp .env.example .env -nano .env -docker compose up -d -``` - -## Важно про HTTPS - -Контейнеры приложения сами не выпускают TLS-сертификаты. Для реального Telegram webhook и Mini App публичные URL должны быть HTTPS. - -Используйте этот вариант, если: - -- проверяете стек локально; -- публикуете сервисы только во внутренней сети; -- TLS уже завершается внешним reverse proxy, load balancer или платформой. - -## Проверка - -```bash -curl http://127.0.0.1:8080/healthz -curl http://127.0.0.1:8082/health -docker compose logs -f backend worker frontend -``` diff --git a/docs/deployment.md b/docs/deployment.md index e59af1a..98246bb 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -27,18 +27,20 @@ docker compose logs -f backend worker frontend ## Готовые папки запуска -Для production удобнее использовать не корневой compose, а отдельные примеры из -[Deploy examples](deploy-examples/index.md). В каждой папке лежат свой `docker-compose.yml`, -`.env.example` и нужный конфиг рядом, а подробные инструкции хранятся в `docs/`: +Для продакшена удобнее использовать не корневой compose, а отдельные Docker Compose-примеры из папки `deploy/examples`. В каждой папке лежат свой `docker-compose.yml`, `.env.example` и нужный конфиг прокси. -| Папка | Назначение | Запуск | -| --- | --- | --- | -| [Caddy](deploy-examples/caddy.md) | Caddy с автоматическим HTTPS. | `cp .env.example .env`, заполнить `.env`, `docker compose up -d`. | -| [Nginx](deploy-examples/nginx.md) | Nginx в Docker-сети приложения, TLS-сертификаты кладутся в `ssl/`. | `cp .env.example .env`, заполнить `.env`, положить сертификаты, `docker compose up -d`. | -| [Pangolin/Newt](deploy-examples/newt.md) | Pangolin/Newt без входящих портов на сервере приложения. | `cp .env.example .env`, заполнить Newt credentials, создать ресурсы в Pangolin, `docker compose up -d`. | -| [No proxy](deploy-examples/no-proxy.md) | Прямая публикация портов backend/frontend. | `cp .env.example .env`, заполнить публичные URL и порты, `docker compose up -d`. | +Предпочтительный вариант для обычного публичного сервера - **Caddy**: он сам выпускает и продлевает HTTPS-сертификаты, а конфигурация получается короче, чем с ручным Nginx. -Пример для Caddy: +| Папка | Когда использовать | +| --- | --- | +| [`deploy/examples/caddy`](https://gitlab.com/3252a8/remnawave-minshop/-/tree/main/deploy/examples/caddy) | Нужен простой публичный HTTPS с автоматическими сертификатами Let's Encrypt. | +| [`deploy/examples/nginx`](https://gitlab.com/3252a8/remnawave-minshop/-/tree/main/deploy/examples/nginx) | Уже используете Nginx и готовы положить TLS-сертификаты рядом с примером. | +| [`deploy/examples/newt`](https://gitlab.com/3252a8/remnawave-minshop/-/tree/main/deploy/examples/newt) | Публикуете сервисы через Pangolin/Newt без входящих портов на сервере приложения. | +| [`deploy/examples/no-proxy`](https://gitlab.com/3252a8/remnawave-minshop/-/tree/main/deploy/examples/no-proxy) | Нужно напрямую открыть HTTP-порты backend/frontend или проверить стек за внешним TLS-терминатором. | + +## Caddy (рекомендуемый вариант) + +Caddy подходит, если DNS-записи `WEBHOOK_HOST` и `MINIAPP_HOST` смотрят на сервер приложения, а входящие `80/tcp` и `443/tcp` открыты. ```bash cd deploy/examples/caddy @@ -48,8 +50,115 @@ docker compose up -d docker compose logs -f caddy backend worker frontend ``` -Корневой `docker-compose.yml` оставлен для локальной сборки из исходников. Примеры в -`deploy/examples` используют готовые GHCR-образы и не требуют указывать `-f`. +Минимально поменяйте в `.env`: + +- `WEBHOOK_HOST` и `MINIAPP_HOST`; +- `BOT_TOKEN`, `ADMIN_IDS`; +- `POSTGRES_PASSWORD`; +- `WEBAPP_SESSION_SECRET`, `WEBHOOK_SECRET_TOKEN`; +- `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET`. + +Если нужна нестандартная логика Caddy, правьте `Caddyfile` рядом с compose и перезапускайте: + +```bash +docker compose up -d --force-recreate caddy +``` + +## Nginx + +Nginx-вариант поднимает Nginx в той же Docker-сети, что и приложение: + +- `WEBHOOK_HOST` проксируется в `backend:8080`; +- `MINIAPP_HOST` проксируется в `frontend:80`; +- `frontend` сам проксирует внутренние `/api`, `/auth` и ассеты тем в `backend:8081`. + +```bash +cd deploy/examples/nginx +cp .env.example .env +nano .env +``` + +Положите TLS-сертификаты в `ssl/`: + +```text +ssl/ + webhooks.example.com/ + fullchain.pem + privkey.pem + app.example.com/ + fullchain.pem + privkey.pem +``` + +Имена папок должны совпадать с `WEBHOOK_HOST` и `MINIAPP_HOST` в `.env`. + +```bash +docker compose up -d +docker compose logs -f nginx backend worker frontend +``` + +Если нужно поменять заголовки, лимиты или TLS-настройки, правьте `nginx.conf.template` и перезапускайте Nginx: + +```bash +docker compose up -d --force-recreate nginx +``` + +## Pangolin / Newt + +Этот вариант не открывает входящие порты на сервере приложения. Newt подключается к Pangolin, а публичные домены настраиваются ресурсами в панели Pangolin. + +```bash +cd deploy/examples/newt +cp .env.example .env +nano .env +docker compose up -d +``` + +В `.env` заполните: + +- `WEBHOOK_HOST` и `MINIAPP_HOST` - публичные домены ресурсов в Pangolin; +- `PANGOLIN_ENDPOINT`, `NEWT_ID`, `NEWT_SECRET` - значения из настроек site/client в Pangolin; +- обычные переменные приложения: `BOT_TOKEN`, `ADMIN_IDS`, `POSTGRES_PASSWORD`, секреты и доступ к Remnawave. + +В Pangolin создайте два HTTP-ресурса для этого Newt site: + +| Публичный домен | Upstream | +| --- | --- | +| `https://webhooks.example.com` | `http://backend:8080` | +| `https://app.example.com` | `http://frontend:80` | + +Проверка: + +```bash +docker compose ps +docker compose logs -f newt backend worker frontend +``` + +## Без обратного прокси + +Этот вариант напрямую публикует два HTTP-порта: + +- backend/вебхуки: `WEB_SERVER_BIND`, по умолчанию `0.0.0.0:8080`; +- frontend/Mini App: `FRONTEND_BIND`, по умолчанию `0.0.0.0:8082`. + +```bash +cd deploy/examples/no-proxy +cp .env.example .env +nano .env +docker compose up -d +``` + +Важно: контейнеры приложения сами не выпускают TLS-сертификаты. Для реального вебхука Telegram и Mini App публичные URL должны быть HTTPS. Используйте этот вариант для локальной проверки, внутренней сети или ситуации, когда HTTPS завершается внешней платформой и дальше трафик приходит на эти порты. + +Проверка локально: + +```bash +curl http://127.0.0.1:8080/healthz +curl http://127.0.0.1:8082/health +docker compose logs -f backend worker frontend +``` + +Корневой `docker-compose.yml` оставлен для локальной сборки из исходников. Примеры в `deploy/examples` используют готовые GHCR-образы и не требуют указывать `-f`. ## Миграции @@ -77,14 +186,13 @@ docker compose logs migrate ## Сервисы -- `backend`: aiohttp API, Telegram webhook, платежные webhooks, panel webhooks, проверка здоровья `/healthz`. -- `worker`: TariffTrafficWorker, задачи синхронизации с панелью, обработка рассылок, потребители очереди webhooks. +- `backend`: aiohttp API, вебхук Telegram, платежные вебхуки, вебхуки панели, проверка здоровья `/healthz`. +- `worker`: TariffTrafficWorker, задачи синхронизации с панелью, обработка рассылок, потребители очереди вебхуков. - `frontend`: статические Svelte-ассеты через nginx. - `postgres`: PostgreSQL 17. - `redis`: Redis 7 для FSM, кеша, rate-limit, очередей и locks. -В production-примерах внешний доступ добавляют `caddy`, `nginx`, `newt` или прямые `ports` в -соответствующем варианте из [Deploy examples](deploy-examples/index.md). +В продакшен-примерах внешний доступ добавляют `caddy`, `nginx`, `newt` или прямые `ports` в соответствующем варианте из `deploy/examples`. ## Логи и проверка @@ -103,7 +211,7 @@ curl http://127.0.0.1:8080/health ``` В обычном compose backend публикуется на `127.0.0.1:${WEB_SERVER_PORT:-8080}`, frontend на -`127.0.0.1:${FRONTEND_PORT:-8082}`. В новых production-примерах проверяйте bind-переменные +`127.0.0.1:${FRONTEND_PORT:-8082}`. В новых продакшен-примерах проверяйте bind-переменные конкретной папки: `HTTP_BIND`, `HTTPS_BIND`, `WEB_SERVER_BIND` или `FRONTEND_BIND`. ## Обновление @@ -244,11 +352,11 @@ docker compose up -d backend worker ## Обратный прокси -Готовые reverse-proxy примеры лежат в: +Готовые reverse-proxy примеры описаны выше: -- [Caddy](deploy-examples/caddy.md) - автоматический HTTPS; -- [Nginx](deploy-examples/nginx.md) - сертификаты кладутся рядом в `ssl/`; -- [Newt/Pangolin](deploy-examples/newt.md) - без входящих портов на сервере приложения. +- [Caddy](#caddy-рекомендуемый-вариант) - автоматический HTTPS; +- [Nginx](#nginx) - сертификаты кладутся рядом в `ssl/`; +- [Newt/Pangolin](#pangolin--newt) - без входящих портов на сервере приложения. Во всех вариантах схема одинаковая: @@ -272,21 +380,6 @@ app.example.com { `app.example.com` - в `frontend:80`. В `deploy/examples/nginx/nginx.conf.template` уже есть заголовки `X-Forwarded-*`, редирект HTTP -> HTTPS и пути сертификатов. -## Newt - -Для Newt используйте [Pangolin / Newt](deploy-examples/newt.md). В compose уже есть сервис -`newt`, а в `.env.example` - поля `PANGOLIN_ENDPOINT`, `NEWT_ID` и `NEWT_SECRET`. - -В Pangolin создайте два HTTP-ресурса для этого Newt site: - -```text -Mini App / frontend: http://frontend:80 -Webhooks / backend: http://backend:8080 -``` - -`backend:8081` является внутренним WebApp API/auth-сервером для frontend nginx; обычно его не нужно -указывать в Newt напрямую. - ## Переменный env-файл По умолчанию compose читает `.env`. Для smoke-тестов или отдельного окружения можно подставить diff --git a/docs/features/admin-panel.md b/docs/features/admin-panel.md index 6679879..d073a00 100644 --- a/docs/features/admin-panel.md +++ b/docs/features/admin-panel.md @@ -42,14 +42,14 @@ - общие параметры: язык, валюта, ссылки поддержки, документы, обязательный канал, Remnawave-доступы и поведение `/start`; - внешний вид и доступность Web App: название, цвет, логотип, emoji-логотип и `WEBAPP_ENABLED`; -- инструкции подключения: `SUBSCRIPTION_GUIDES_ENABLED`, `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED`, чтение конфига из Remnawave Panel, JSON-override и fallback-путь к файлу; +- инструкции подключения: `SUBSCRIPTION_GUIDES_ENABLED`, `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED`, чтение конфига из Remnawave Panel, JSON-переопределение и резервный путь к файлу; - legacy-цены без JSON-каталога: периоды подписки, RUB/Stars цены и пакеты трафика; - платежные провайдеры: включение методов, порядок кнопок, публичные параметры и секреты YooKassa, FreeKassa, Platega, SeverPay, Wata, CryptoPay, Heleket и Stars, а также текст и иконки кнопок оплаты; - пробный период, реферальные бонусы, уведомления, логирование, поддержка, раздел устройств, лимит устройств и legacy-лимиты трафика. Секретные поля помечены как secret и не должны использоваться для произвольного просмотра старых значений. Настройки, которых нет в manifest, остаются только в `.env` или коде. -Для каждого платежного метода в разделе провайдера доступны presentation-настройки `PAYMENT__WEBAPP_LABEL_RU`, `PAYMENT__WEBAPP_LABEL_EN`, `PAYMENT__WEBAPP_ICON`, `PAYMENT__TELEGRAM_LABEL_RU`, `PAYMENT__TELEGRAM_LABEL_EN` и `PAYMENT__TELEGRAM_EMOJI`. Пустое значение возвращает мультиязычный дефолт из модуля платежного провайдера. Иконка Web App выбирается из уже подключённых lucide-иконок (`frontend/src/lib/components/ui/icons.js`) через модалку в админке. +Для каждого платежного метода в разделе провайдера доступны настройки отображения `PAYMENT__WEBAPP_LABEL_RU`, `PAYMENT__WEBAPP_LABEL_EN`, `PAYMENT__WEBAPP_ICON`, `PAYMENT__TELEGRAM_LABEL_RU`, `PAYMENT__TELEGRAM_LABEL_EN` и `PAYMENT__TELEGRAM_EMOJI`. Пустое значение возвращает мультиязычное значение по умолчанию из модуля платежного провайдера. Иконка Web App выбирается из уже подключенных lucide-иконок (`frontend/src/lib/components/ui/icons.js`) через модалку в админке. ## Переводы @@ -76,9 +76,9 @@ Секция **Система -> Настройки -> Инструкции подключения** управляет встроенным экраном установки. `SUBSCRIPTION_GUIDES_ENABLED` включает `/install` в личном кабинете, а `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED` заставляет кнопки подключения в Telegram-боте открывать Mini App вместо финальной Remnawave Subscription Page. Оба переключателя включены по умолчанию. -По умолчанию Minishop читает Remnawave Subscription Page config из панели (`SUBSCRIPTION_PAGE_CONFIG_PANEL_ENABLED=True`). Это основной режим, потому что один и тот же конфиг используется и в панели, и во встроенной инструкции. JSON-поле `SUBSCRIPTION_PAGE_CONFIG_JSON` применяется только когда явно включен `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED`; иначе оно может храниться в админке, но не влияет на пользователей. `SUBSCRIPTION_PAGE_CONFIG_PATH` остается fallback-путем к локальному v1 JSON-файлу, если конфиг панели отключен или недоступен. +По умолчанию Minishop читает конфиг Remnawave Subscription Page из панели (`SUBSCRIPTION_PAGE_CONFIG_PANEL_ENABLED=True`). Это основной режим, потому что один и тот же конфиг используется и в панели, и во встроенной инструкции. JSON-поле `SUBSCRIPTION_PAGE_CONFIG_JSON` применяется только когда явно включен `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED`; иначе оно может храниться в админке, но не влияет на пользователей. `SUBSCRIPTION_PAGE_CONFIG_PATH` остается резервным путем к локальному v1 JSON-файлу, если конфиг панели отключен или недоступен. -При сохранении backend валидирует JSON-override как Remnawave Subscription Page v1 config. Ошибки показываются как обычные validation errors настроек, а если рабочий конфиг недоступен, пользовательская кнопка подключения откатывается к старой финальной ссылке подписки. +При сохранении backend валидирует JSON-переопределение как конфиг Remnawave Subscription Page v1. Ошибки показываются как обычные ошибки валидации настроек, а если рабочий конфиг недоступен, пользовательская кнопка подключения откатывается к старой финальной ссылке подписки. ## Поддержка @@ -86,7 +86,7 @@ В карточке тикета администратор видит диалог, пользовательский контекст и действия: ответить пользователю, оставить внутреннюю заметку, изменить статус, приоритет, категорию или исполнителя, закрыть тикет и перейти в карточку пользователя. Внутренние заметки не показываются пользователю. -Счетчик непрочитанных обращений отображается в навигации админки. Уведомления о новых тикетах и ответах пользователя настраиваются через `LOG_SUPPORT`, `LOG_SUPPORT_THREAD_ID` и параметры `SUPPORT_*`. Подробности: [support.md](support.md). +Счетчик непрочитанных обращений отображается в навигации админки. Уведомления о новых тикетах и ответах пользователя настраиваются через `LOG_SUPPORT`, `LOG_SUPPORT_THREAD_ID` и параметры `SUPPORT_*`. Подробности: [поддержка пользователей / тикеты](support.md). ## Внешний вид diff --git a/docs/features/core.md b/docs/features/core.md index a9ea65f..d3430a4 100644 --- a/docs/features/core.md +++ b/docs/features/core.md @@ -19,4 +19,4 @@ Minishop закрывает путь от регистрации пользов - Ручная синхронизация с Remnawave Panel. - Редактор JSON-каталога тарифов. -Подробности: [админ-панель](admin-panel.md), [Mini App](web-app.md) и [поддержка](support.md). +Подробности: [админ-панель](admin-panel.md), [Mini App](web-app.md) и [поддержка пользователей / тикеты](support.md). diff --git a/docs/features/payments.md b/docs/features/payments.md index 09f922a..e8d07b1 100644 --- a/docs/features/payments.md +++ b/docs/features/payments.md @@ -1,28 +1,152 @@ # Платежи -Платежные методы включаются настройками и отображаются пользователю как кнопки оплаты в Mini App и Telegram-сценариях. - -## Поддерживаемые провайдеры - -- [YooKassa](../payments/yookassa.md) -- [FreeKassa](../payments/freekassa.md) -- [Platega](../payments/platega.md) -- [SeverPay](../payments/severpay.md) -- [Wata](../payments/wata.md) -- [CryptoPay](../payments/cryptopay.md) -- [Heleket](../payments/heleket.md) -- [Telegram Stars](../payments/telegram-stars.md) +Платежные методы включаются настройками и отображаются пользователю как кнопки оплаты в Mini App и Telegram-сценариях. Настройки можно задавать через `.env` или через админку, если параметр есть в allowlist настроек. ## Типовой порядок настройки 1. Включите нужный провайдер в админке или через `.env`. -2. Заполните публичные параметры и секреты. -3. Настройте webhook URL у провайдера, если это требуется. -4. Проверьте порядок и подписи кнопок оплаты. -5. Выполните тестовый платеж и проверьте логи backend. +2. Заполните публичные параметры, секреты и URL возврата. +3. Настройте URL вебхука у провайдера, если это требуется. +4. Проверьте порядок методов в `PAYMENT_METHODS_ORDER`. +5. Проверьте подписи и иконки кнопок оплаты. +6. Выполните тестовый платеж и проверьте логи `backend`. -## Где смотреть параметры +Общие ссылки: - [Справочник `.env`](../configuration/env-vars.md) содержит все ключи провайдеров. - [Админ-панель](admin-panel.md) описывает UI-настройки платежей. -- [Тарифы](tariffs.md) описывают цены, Stars и сценарии покупки. +- [Тарифы](tariffs.md) описывают цены, Telegram Stars и сценарии покупки. +- [Логи](../troubleshooting/logs.md) помогают проверить webhook и создание платежных ссылок. + +## YooKassa + +YooKassa используется для рублевых оплат и может участвовать в сценариях автопродления period-подписок. + +Что настроить: + +- включение провайдера: `YOOKASSA_ENABLED`; +- идентификаторы и секреты магазина; +- URL вебхука на backend-домен; +- отображение кнопки оплаты и порядок платежных методов. + +Справочник переменных: [YooKassa](../configuration/env-vars.md#yookassa). + +## FreeKassa + +FreeKassa подключается как отдельный платежный метод и обрабатывает входящие webhook-события через `backend`. + +Что настроить: + +- включение провайдера: `FREEKASSA_ENABLED`; +- ID магазина, API/secret-ключи и настройки подписи; +- список доверенных IP, если используется; +- публичный URL вебхука на `WEBHOOK_BASE_URL`. + +Справочник переменных: [FreeKassa](../configuration/env-vars.md#freekassa). + +## Platega + +Platega подключается как отдельный платежный провайдер, но внутри Minishop может дать несколько кнопок: основную устаревшую кнопку, СБП/карту и крипто-кнопку. Общие параметры мерчанта задаются один раз, а ID методов оплаты и подписи кнопок настраиваются отдельно. + +Что включить: + +- `PLATEGA_ENABLED` - общий флаг провайдера; +- `PLATEGA_SBP_ENABLED` - отдельная кнопка СБП/карта; +- `PLATEGA_CRYPTO_ENABLED` - отдельная crypto-кнопка Platega; +- `PLATEGA_PAYMENT_METHOD` - устаревший/резервный ID метода оплаты для старых callback-запросов и старых установок. + +Что настроить: + +1. Укажите `PLATEGA_BASE_URL`, `PLATEGA_MERCHANT_ID` и `PLATEGA_SECRET`. +2. Заполните `PLATEGA_SBP_METHOD` и/или `PLATEGA_CRYPTO_METHOD`, если используете отдельные кнопки. +3. Проверьте `PLATEGA_RETURN_URL` и `PLATEGA_FAILED_URL`. +4. Настройте тексты и иконки кнопок через `PAYMENT_PLATEGA_SBP_*` и `PAYMENT_PLATEGA_CRYPTO_*`. +5. Добавьте нужные методы в `PAYMENT_METHODS_ORDER`. + +Справочник переменных: [Platega](../configuration/env-vars.md#platega). + +## SeverPay + +SeverPay подключается как отдельный платежный метод с собственным MID, token и сроком жизни платежной ссылки. + +Что настроить: + +1. Включите `SEVERPAY_ENABLED`. +2. Укажите `SEVERPAY_BASE_URL`. +3. Заполните `SEVERPAY_MID` и `SEVERPAY_TOKEN`. +4. Настройте `SEVERPAY_RETURN_URL`. +5. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`. +6. Добавьте `severpay` в `PAYMENT_METHODS_ORDER`. + +Справочник переменных: [SeverPay](../configuration/env-vars.md#severpay). + +## Wata + +Wata подключается как отдельный провайдер с bearer token, платежными ссылками и опциональной проверкой подписи webhook. + +Что настроить: + +1. Включите `WATA_ENABLED`. +2. Укажите `WATA_BASE_URL` и `WATA_API_TOKEN`. +3. Проверьте `WATA_RETURN_URL` и `WATA_FAILED_URL`. +4. Настройте `WATA_LINK_TTL_MINUTES`: минимум 15 минут, максимум 43200. +5. Если включаете проверку подписи, задайте `WATA_WEBHOOK_VERIFY_SIGNATURE` и при необходимости `WATA_PUBLIC_KEY`. +6. Для дополнительной защиты заполните `WATA_TRUSTED_IPS`. +7. Добавьте `wata` в `PAYMENT_METHODS_ORDER`. + +Справочник переменных: [Wata](../configuration/env-vars.md#wata). + +## CryptoPay + +CryptoPay используется для криптовалютных платежей через отдельный токен и сеть Crypto Bot API. + +Что настроить: + +1. Включите `CRYPTOPAY_ENABLED`. +2. Укажите `CRYPTOPAY_TOKEN`. +3. Выберите `CRYPTOPAY_NETWORK`: `mainnet` или `testnet`. +4. Задайте `CRYPTOPAY_CURRENCY_TYPE`: `fiat` или `crypto`. +5. Проверьте `CRYPTOPAY_ASSET`, например `RUB`, `USDT` или `BTC`. +6. Добавьте `cryptopay` в `PAYMENT_METHODS_ORDER`. + +Для тестов используйте соответствующую сеть: testnet-токен не должен попадать в mainnet-настройки. Если сумма или asset выглядят неверно, проверьте сочетание `CRYPTOPAY_CURRENCY_TYPE` и `CRYPTOPAY_ASSET`. + +Справочник переменных: [CryptoPay](../configuration/env-vars.md#cryptopay). + +## Heleket + +Heleket используется для крипто-инвойсов с отдельными merchant ID, ключом платежного API, валютой инвойса и настройками проверки webhook. + +Что настроить: + +1. Включите `HELEKET_ENABLED`. +2. Укажите `HELEKET_BASE_URL`, `HELEKET_MERCHANT_ID` и `HELEKET_API_KEY`. +3. Настройте `HELEKET_CURRENCY`. +4. При необходимости задайте `HELEKET_TO_CURRENCY` и `HELEKET_NETWORK`. +5. Проверьте `HELEKET_RETURN_URL` и `HELEKET_SUCCESS_URL`. +6. Настройте `HELEKET_LIFETIME_SECONDS`: допустимый диапазон 300..43200. +7. Если включаете проверку webhook, задайте `HELEKET_VERIFY_WEBHOOK_SIGNATURE`. +8. Для IP-фильтрации заполните `HELEKET_TRUSTED_IPS`. +9. Добавьте `heleket` в `PAYMENT_METHODS_ORDER`. + +Справочник переменных: [Heleket](../configuration/env-vars.md#heleket). + +## Telegram Stars + +Telegram Stars используются напрямую и поддерживаются в legacy-ценах и JSON-каталоге тарифов. + +Где применяются Stars: + +- цены периодов подписки; +- пакеты трафика; +- premium-докупки; +- HWID-докупки, если они включены в каталоге тарифов. + +Что проверить: + +- `STARS_ENABLED`; +- Stars-цены в legacy-настройках или JSON-каталоге; +- корректное округление цены до целого количества Stars; +- сценарии смены тарифа: XTR/Stars-докупки не конвертируются без явного курса. + +См. также [переменные платежей](../configuration/env-vars.md#платежи) и [тарифы](tariffs.md). diff --git a/docs/features/support.md b/docs/features/support.md index 94b8e91..006a36a 100644 --- a/docs/features/support.md +++ b/docs/features/support.md @@ -1,4 +1,4 @@ -# Поддержка +# Поддержка пользователей / тикеты В проекте есть два канала поддержки: diff --git a/docs/features/tariffs.md b/docs/features/tariffs.md index 0930ce3..79c23fa 100644 --- a/docs/features/tariffs.md +++ b/docs/features/tariffs.md @@ -22,8 +22,8 @@ JSON-каталог может содержать несколько тариф - добавление, редактирование и удаление тарифов; - включение и выключение тарифа на витрине; - выбор тарифа по умолчанию; -- настройка `period`-тарифов: месячный лимит, периоды, RUB/Stars цены, пакеты докупки трафика; -- настройка `traffic`-тарифов: пакеты GB, RUB/Stars цены, курс конвертации; +- настройка тарифов на срок (`period`): месячный лимит, периоды, RUB/Stars цены, пакеты докупки трафика; +- настройка тарифов по трафику (`traffic`): пакеты GB, RUB/Stars цены, курс конвертации; - настройка базовых Internal Squads из списка Remnawave; - настройка premium-раздела: названия RU/EN, premium Internal Squads, месячный premium-лимит и RUB/Stars пакеты докупки premium-трафика; - настройка базового HWID-лимита и пакетов докупки устройств. @@ -120,7 +120,7 @@ JSON-каталог может содержать несколько тариф Если у traffic-тарифа нет RUB-пакетов, `conversion_rate_rub_per_gb` обязателен. -## Period-тарифы +## Тарифы на срок (`period`) `period` продает доступ на срок с месячным лимитом трафика. @@ -187,7 +187,7 @@ JSON-каталог может содержать несколько тариф В Web App админке premium-сквады можно выбрать из выпадающего списка на вкладке **Premium** в редакторе тарифа. Список берется из API Remnawave (`/api/admin/panel/internal-squads`), поэтому UUID обычно не нужно копировать вручную. -## Traffic-тарифы +## Тарифы по трафику (`traffic`) `traffic` продает объем трафика без пользовательского срока действия. diff --git a/docs/features/web-app.md b/docs/features/web-app.md index a97a4c7..16c1e26 100644 --- a/docs/features/web-app.md +++ b/docs/features/web-app.md @@ -1,8 +1,8 @@ -# Web App / Mini App +# Веб-приложение / Mini App -Web App собирается в отдельный `frontend` image и отдается через nginx. Static/Mini App запросы идут в `frontend:80`; frontend nginx проксирует `/api/*`, `/auth/*` и theme/logo assets в backend WebApp server на `backend:8081`. Telegram, payment и panel webhook routes остаются на backend webhook server `backend:8080`. +Веб-приложение собирается в отдельный образ `frontend` и отдается через nginx. Статические запросы Mini App идут в `frontend:80`; frontend nginx проксирует `/api/*`, `/auth/*` и ассеты тем/логотипов во внутренний WebApp-сервер backend на `backend:8081`. Telegram, платежные и панельные webhook-маршруты остаются на backend-сервере вебхуков `backend:8080`. -## Что показывает Web App +## Что показывает веб-приложение - текущую ссылку подключения; - статус и дату окончания подписки; @@ -16,7 +16,7 @@ Web App собирается в отдельный `frontend` image и отда - реферальную ссылку и статистику приглашений; - привязку email и Telegram к одному аккаунту. -Для администраторов из `ADMIN_IDS` Web App также показывает админ-панель: статистику, **пользователей** (поиск, фильтры, premium-трафик), поддержку, рассылки, промокоды, логи, настройки и редактор тарифов. Подробности: [админ-панель](admin-panel.md). +Для администраторов из `ADMIN_IDS` веб-приложение также показывает админ-панель: статистику, **пользователей** (поиск, фильтры, premium-трафик), поддержку, рассылки, промокоды, логи, настройки и редактор тарифов. Подробности: [админ-панель](admin-panel.md). ## Настройки `.env` @@ -57,7 +57,7 @@ SUPPORT_TICKETS_ENABLED=True SUPPORT_TICKET_RATE_LIMIT_PER_HOUR=5 ``` -`SUBSCRIPTION_MINI_APP_URL` - это публичный HTTPS URL именно frontend/Mini App, обычно отдельный домен вроде `https://app.domain.com/`. Его указывают в BotFather в Mini Apps, а бот использует его для кнопок личного кабинета, referral-ссылок и email-входа. Не добавляйте в него `/api`, `/webhook` или путь конкретной страницы. +`SUBSCRIPTION_MINI_APP_URL` - это публичный HTTPS URL именно frontend/Mini App, обычно отдельный домен вроде `https://app.domain.com/`. Его указывают в BotFather в Mini Apps, а бот использует его для кнопок личного кабинета, реферальных ссылок и входа по email. Не добавляйте в него `/api`, `/webhook` или путь конкретной страницы. ## Инструкции установки @@ -75,17 +75,17 @@ SUPPORT_TICKET_RATE_LIMIT_PER_HOUR=5 Личный экран показывает QR-код финальной ссылки подписки, кнопку копирования и кнопку **Поделиться**. Для передачи инструкции генерируется публичная ссылка `/s/`: она открывает тот же интерфейс инструкций без авторизации и нижней навигации, но без QR-блока. Публичный payload отдается через `/api/subscription-guides/public/{share_token}` только для активной локальной подписки с валидным share token. -`SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED=True` включает такое же поведение в Telegram-боте: кнопки подключения открывают Mini App `/install`, а после успешной оплаты, trial или промокода пользователь получает публичную ссылку `/s/`. Если настройку выключить, бот снова отправляет пользователя на финальную Remnawave Subscription Page. +`SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED=True` включает такое же поведение в Telegram-боте: кнопки подключения открывают Mini App `/install`, а после успешной оплаты, пробного периода или промокода пользователь получает публичную ссылку `/s/`. Если настройку выключить, бот снова отправляет пользователя на финальную Remnawave Subscription Page. Конфиг совместим с Remnawave Subscription Page v1 (`version`, `locales`, `brandingSettings`, `uiConfig`, `baseSettings`, `baseTranslations`, `svgLibrary`, `platforms`). Backend проверяет обязательные locale-строки, допустимые платформы и типы кнопок, ссылки на `svgIconKey`, а SVG из `svgLibrary` санитизирует перед отдачей в UI. -Если `WEBAPP_ENABLED=False`, пользовательский Web App и админ-панель не регистрируются. Чтобы снова попасть в админку, включите `WEBAPP_ENABLED=True` в `.env` и перезапустите backend/frontend контейнеры. +Если `WEBAPP_ENABLED=False`, пользовательское веб-приложение и админ-панель не регистрируются. Чтобы снова попасть в админку, включите `WEBAPP_ENABLED=True` в `.env` и перезапустите backend/frontend контейнеры. Внешний вид настраивается в админке: раздел **Внешний вид** управляет логотипом, emoji-логотипом, accent-цветом, выбранной темой и масштабом логотипа. Кастомные темы читаются из `WEBAPP_THEMES_DIR`, а `WEBAPP_DEFAULT_THEME` может принудительно выбрать тему по ключу. Подробный контракт `theme.json`, CSS/asset-роуты и пайплайн создания темы описаны в [webapp-themes.md](webapp-themes.md). Если SMTP-настройки не заполнены, вход по email скрывается. -Тикеты поддержки включаются через `SUPPORT_TICKETS_ENABLED`; внешний резервный контакт задается `SUPPORT_LINK`. Полный сценарий пользователя, админа и уведомлений описан в [support.md](support.md). +Тикеты поддержки включаются через `SUPPORT_TICKETS_ENABLED`; внешний резервный контакт задается `SUPPORT_LINK`. Полный сценарий пользователя, админа и уведомлений описан в разделе [поддержка пользователей / тикеты](support.md). ## Telegram-авторизация @@ -97,7 +97,7 @@ SUPPORT_TICKET_RATE_LIMIT_PER_HOUR=5 2. В `Bot Settings` -> `Domain` укажите домен Web App без протокола и пути, например `app.domain.com`. 3. В `Bot Settings` -> `Mini Apps` укажите URL, например `https://app.domain.com/`. 4. В `Bot Settings` -> `Web Login` включите OpenID Connect Login, если BotFather предлагает переключение. -5. Скопируйте Client ID и Client Secret в `TELEGRAM_OAUTH_CLIENT_ID` и `TELEGRAM_OAUTH_CLIENT_SECRET`. +5. Скопируйте идентификатор клиента и секрет клиента в `TELEGRAM_OAUTH_CLIENT_ID` и `TELEGRAM_OAUTH_CLIENT_SECRET`. 6. В `Web Login` -> `Allowed URLs` добавьте: ```text @@ -107,9 +107,9 @@ https://app.domain.com/auth/telegram/callback `TELEGRAM_OAUTH_REQUEST_ACCESS=write` разрешает боту написать пользователю после логина. Если дополнительные разрешения не нужны, оставьте переменную пустой. -## Email-вход +## Вход по email -Email-вход работает через одноразовый код: +Вход по email работает через одноразовый код: 1. Пользователь вводит email. 2. Бот отправляет код через SMTP. @@ -118,25 +118,25 @@ Email-вход работает через одноразовый код: Для Brevo обычно подходит порт `587` с STARTTLS. Если основной порт недоступен, приложение пробует порты из `SMTP_FALLBACK_PORTS`; порт `465` используется через SSL. -Полный список переменных, обязательные поля для включения email-входа и типичные ошибки подключения описаны в разделе **SMTP и вход по email** в [configuration.md](../configuration.md). +Полный список переменных, обязательные поля для включения входа по email и типичные ошибки подключения описаны в разделе **SMTP и вход по email** в [configuration.md](../configuration.md). ## Проксирование -Рекомендуемая production-схема - два публичных домена: +Рекомендуемая продакшен-схема - два публичных домена: - `WEBHOOK_BASE_URL`, например `https://webhooks.domain.com`, целиком проксируется в `backend:8080`; - `SUBSCRIPTION_MINI_APP_URL`, например `https://app.domain.com/`, целиком проксируется в `frontend:80`. `frontend` уже сам проксирует `/api/*`, `/auth/*`, `/webapp-logo` и ассеты тем/логотипов во внутренний -WebApp API на `backend:8081`, поэтому внешний reverse proxy обычно не должен отправлять эти пути в +WebApp API на `backend:8081`, поэтому внешний обратный прокси обычно не должен отправлять эти пути в `backend:8081` напрямую. -Готовые варианты описаны в [Deploy examples](../deploy-examples/index.md): +Готовые варианты описаны в разделе [Развертывание](../deployment.md#готовые-папки-запуска): -- [Caddy](../deploy-examples/caddy.md) - автоматический HTTPS; -- [Nginx](../deploy-examples/nginx.md) - сертификаты в соседней папке `ssl/`; -- [Pangolin/Newt](../deploy-examples/newt.md) - публикация без входящих портов на сервере приложения; -- [No proxy](../deploy-examples/no-proxy.md) - прямая публикация портов для проверки или внешней TLS-платформы. +- [Caddy](../deployment.md#caddy-рекомендуемый-вариант) - автоматический HTTPS; +- [Nginx](../deployment.md#nginx) - сертификаты в соседней папке `ssl/`; +- [Pangolin/Newt](../deployment.md#pangolin--newt) - публикация без входящих портов на сервере приложения; +- [без обратного прокси](../deployment.md#без-обратного-прокси) - прямая публикация портов для проверки или внешней TLS-платформы. В default `docker-compose.yml` наружу публикуются `frontend` и webhook/backend port, а внутри Docker network сервисы доступны друг другу по service DNS names: @@ -158,6 +158,6 @@ services: - Telegram deep-link: `https://t.me/?start=ref_u`; - Web App ссылка: `https://app.domain.com/?ref=u`. -Web App учитывает `ref`, `start`, `start_param` и Telegram Mini Apps `start_param`, сохраняет найденный параметр до авторизации и передает его в Telegram OAuth или email-вход. +Веб-приложение учитывает `ref`, `start`, `start_param` и Telegram Mini Apps `start_param`, сохраняет найденный параметр до авторизации и передает его в Telegram OAuth или вход по email. Для email-регистраций пользователь в Remnawave создается с username вида `em_`. Email добавляется в описание пользователя панели и, если API панели принимает поле `email`, передается отдельным полем. Для Telegram-регистраций используется username `tg_`. diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index 6470c14..091009a 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -1,10 +1,10 @@ # Обзор -Remnawave Minishop состоит из Telegram-бота, backend API, worker-процессов, frontend/Mini App и инфраструктурных сервисов PostgreSQL и Redis. В production эти части запускаются через Docker Compose и общаются с Remnawave Panel по API и вебхукам. +Remnawave Minishop состоит из Telegram-бота, backend API, worker-процессов, frontend/Mini App и инфраструктурных сервисов PostgreSQL и Redis. В продакшене эти части запускаются через Docker Compose и общаются с Remnawave Panel по API и вебхукам. ## Основные компоненты -- **Backend** - Telegram webhook, платежные вебхуки, panel webhooks, API для Mini App и админки. +- **Backend** - вебхук Telegram, платежные вебхуки, вебхуки панели, API для Mini App и админки. - **Worker** - фоновые задачи, синхронизация подписок, обработка очереди вебхуков и тарифных событий. - **Frontend** - отдельный nginx-образ с Mini App и админкой. - **PostgreSQL** - пользователи, платежи, настройки, поддержка, промокоды и служебные данные. @@ -21,6 +21,6 @@ Remnawave Minishop состоит из Telegram-бота, backend API, worker-п ## Куда идти дальше - [Установка](setup.md) - базовый запуск через Compose. -- [Deploy examples](../deploy-examples/index.md) - готовые варианты публикации. +- [Развертывание](../deployment.md) - Docker Compose, Caddy, Nginx, Pangolin/Newt и запуск без обратного прокси. - [Архитектура](../architecture.md) - структура каталогов и сервисов. - [Mini App](../features/web-app.md) - публичный frontend, Telegram OAuth и инструкции установки. diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index ee034d0..8c92264 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -15,17 +15,27 @@ docker compose logs -f backend worker frontend ## Что заполнить в первую очередь - `BOT_TOKEN` и `ADMIN_IDS` для доступа к боту и админке. -- `WEBHOOK_BASE_URL` для Telegram, платежных и panel webhook URL. +- `WEBHOOK_BASE_URL` для Telegram, платежных вебхуков и вебхуков панели. - `SUBSCRIPTION_MINI_APP_URL` для Mini App и кнопок в Telegram. - `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`. - `WEBAPP_SESSION_SECRET`, `WEBHOOK_SECRET_TOKEN`, `PANEL_API_URL`, `PANEL_API_KEY`, `PANEL_WEBHOOK_SECRET`. ## Как выбрать Compose-вариант -- Для быстрого публичного HTTPS берите [Caddy](../deploy-examples/caddy.md). -- Если у вас уже есть TLS-сертификаты и нужен Nginx в Docker-сети, берите [Nginx](../deploy-examples/nginx.md). -- Если нельзя открывать входящие порты на сервере приложения, берите [Pangolin/Newt](../deploy-examples/newt.md). -- Для локальной проверки или внешнего TLS-терминатора берите [no-proxy](../deploy-examples/no-proxy.md). +Для продакшена по умолчанию берите [Caddy](../deployment.md#caddy-рекомендуемый-вариант): это самый короткий путь к публичному HTTPS без ручной раскладки сертификатов. + +```bash +cd deploy/examples/caddy +cp .env.example .env +nano .env +docker compose up -d +``` + +Остальные варианты описаны в [разделе развертывания](../deployment.md#готовые-папки-запуска): + +- [Nginx](../deployment.md#nginx) - если у вас уже есть TLS-сертификаты и нужен Nginx в Docker-сети; +- [Pangolin/Newt](../deployment.md#pangolin--newt) - если нельзя открывать входящие порты на сервере приложения; +- [без обратного прокси](../deployment.md#без-обратного-прокси) - для локальной проверки или внешнего TLS-терминатора. ## После первого входа diff --git a/docs/index.md b/docs/index.md index b852c2c..f91f3b6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ Remnawave Minishop - Telegram-бот и Mini App для продажи и упр - [Обзор](getting-started/overview.md) - архитектура, сервисы и основные сценарии. - [Установка](getting-started/setup.md) - путь от `.env` до первого запуска. -- [Deploy examples](deploy-examples/index.md) - Caddy, Nginx, Pangolin/Newt и no-proxy варианты. +- [Развертывание](deployment.md) - Docker Compose, Caddy, Nginx, Pangolin/Newt и запуск без обратного прокси. - [Настройка платежей](features/payments.md) - включение провайдеров и проверка вебхуков. - [Безопасность](configuration/security.md) - секреты, доступы и публичные URL. - [Админ-панель](features/admin-panel.md) - пользователи, настройки, рассылки, поддержка и тарифы. @@ -17,9 +17,9 @@ Remnawave Minishop - Telegram-бот и Mini App для продажи и упр ## Ключевые возможности -- **Продажа подписок** - period- и traffic-тарифы, докупки трафика, HWID-устройства, premium-сквады и Telegram Stars. +- **Продажа подписок** - тарифы на срок и по трафику, докупки трафика, HWID-устройства, premium-сквады и Telegram Stars. - **Жизненный цикл пользователей** - регистрация, пробный период, продление, синхронизация с панелью и предупреждения по трафику. -- **Mini App** - личный кабинет, инструкции установки, Telegram OAuth, email-вход и публичные referral-ссылки. +- **Mini App** - личный кабинет, инструкции установки, Telegram OAuth, вход по email и публичные реферальные ссылки. - **Операционные инструменты** - админка, тикеты поддержки, промокоды, рассылки, логи и настройки поверх `.env`. ## Справочник diff --git a/docs/migrations/index.md b/docs/migrations/index.md index 36e2add..8463a4e 100644 --- a/docs/migrations/index.md +++ b/docs/migrations/index.md @@ -6,7 +6,7 @@ | Источник | Поддерживаемый случай | Инструкция | | --- | --- | --- | -| `remnawave-tg-shop` `v2.7.0` и близкие версии | Переезд старого stack/volume PostgreSQL на split-архитектуру Minishop `v3.4+`, обновление `.env`, запуск `migrate`, проверка reverse proxy | [Миграция с remnawave-tg-shop](remnawave-tg-shop.md) | +| `remnawave-tg-shop` `v2.7.0` и близкие версии | Переезд старого stack/volume PostgreSQL на split-архитектуру Minishop `v3.4+`, обновление `.env`, запуск `migrate`, проверка обратного прокси | [Миграция с remnawave-tg-shop](remnawave-tg-shop.md) | ## Что покрывает текущая миграция @@ -18,7 +18,7 @@ - обновление переменных окружения, которые изменились после `v2.7.0`; - запуск one-shot сервиса `migrate`; - переход с одного upstream `remnawave-tg-shop:8000` на `backend:8080` и `frontend:80`; -- запуск через корневой compose или готовые deploy examples. +- запуск через корневой compose или готовые примеры Docker Compose. ## Что пока не описано diff --git a/docs/migrations/remnawave-tg-shop.md b/docs/migrations/remnawave-tg-shop.md index f2b54ed..b9c483d 100644 --- a/docs/migrations/remnawave-tg-shop.md +++ b/docs/migrations/remnawave-tg-shop.md @@ -9,7 +9,7 @@ Если вы используете только готовые Docker-образы и не собираете проект локально, git-команды из ручного способа не нужны. Достаточно обновить compose-файл до одного из готовых примеров в `deploy/examples` и -перенести/обновить БД. Самый прямой вариант без встроенного reverse proxy - +перенести/обновить БД. Самый прямой вариант без встроенного обратного прокси - `deploy/examples/no-proxy/docker-compose.yml`; для Caddy, Nginx и Newt есть такие же самостоятельные папки. @@ -105,7 +105,7 @@ docker compose \ | Volume | v2.7.0 | v3.4+ | Что внутри | | --- | --- | --- | --- | | `remnawave-minishop-db-data` | переименовать из `remnawave-tg-shop-db-data` | переносится скриптом | PostgreSQL | -| `remnawave-minishop-redis-data` | — | создаётся пустым | Redis (FSM, rate-limit, cache, очередь webhooks, distributed locks) | +| `remnawave-minishop-redis-data` | — | создаётся пустым | Redis (FSM, rate-limit, cache, очередь вебхуков, distributed locks) | | `remnawave-minishop-shop-data` | — | создаётся пустым | `/app/data`: `tariffs.json`, темы Web App, кэш логотипа/emoji | | `remnawave-minishop-caddy-data` / `remnawave-minishop-caddy-config` | переименовать из `remnawave-tg-shop-caddy-*` | переносится скриптом | только при Caddy-варианте | @@ -170,7 +170,7 @@ bash scripts/migrate_to_minishop.sh Примеры: ```bash -# Caddy-вариант из raw. +# Caddy-вариант из raw-файла. # Перед запуском скопируйте старый .env в deploy/examples/caddy/.env # и заполните WEBHOOK_HOST / MINIAPP_HOST. COMPOSE_FILE=deploy/examples/caddy/docker-compose.yml \ @@ -336,7 +336,7 @@ docker volume rm remnawave-tg-shop-caddy-data remnawave-tg-shop-caddy-config 2>/ | Назначение | DNS-имя сервиса | Порт | | --- | --- | --- | -| Telegram / платёжные / panel webhooks | `backend` | `8080` | +| Telegram / платежные / вебхуки панели | `backend` | `8080` | | Health-чек | `backend` | `8080` (`/healthz`) | | Web App API (`/api/*`, `/auth/*`, ассеты тем и логотипов) | `backend` | `8081` (доступен только из Docker-сети) | | Статический фронт Web App | `frontend` | `80` (внутри `frontend` уже проксирует `/api/*` и `/auth/*` на `backend:8081`) | @@ -360,9 +360,8 @@ server { } ``` -Полные примеры (Caddy, Nginx, Newt/Pangolin и запуск без reverse proxy) — в -[docs/deployment.md](../deployment.md), [docs/features/web-app.md](../features/web-app.md) и -[Deploy examples](../deploy-examples/index.md). Если раньше прокси указывал на +Полные примеры (Caddy, Nginx, Newt/Pangolin и запуск без обратного прокси) — в +[docs/deployment.md](../deployment.md) и [docs/features/web-app.md](../features/web-app.md). Если раньше прокси указывал на `remnawave-tg-shop:8000` напрямую, после миграции нужно либо переключиться на `backend:8080` / `frontend:80`, либо использовать готовый Caddy/Nginx/Newt пример, который уже знает правильную маршрутизацию. diff --git a/docs/payments/cryptopay.md b/docs/payments/cryptopay.md deleted file mode 100644 index 2cb2235..0000000 --- a/docs/payments/cryptopay.md +++ /dev/null @@ -1,28 +0,0 @@ -# CryptoPay - -CryptoPay используется для криптовалютных платежей через отдельный токен и сеть Crypto Bot API. - -## Что включить - -- `CRYPTOPAY_ENABLED` - включает CryptoPay среди доступных методов. -- Presentation-ключи `PAYMENT_CRYPTOPAY_*` - подписи и иконки кнопки в Mini App и Telegram. - -## Что настроить - -1. Укажите `CRYPTOPAY_TOKEN`. -2. Выберите `CRYPTOPAY_NETWORK`: `mainnet` или `testnet`. -3. Задайте `CRYPTOPAY_CURRENCY_TYPE`: `fiat` или `crypto`. -4. Проверьте `CRYPTOPAY_ASSET`, например `RUB`, `USDT` или `BTC`. -5. Добавьте `cryptopay` в `PAYMENT_METHODS_ORDER`. - -## Проверка - -- Для тестов используйте соответствующую сеть: testnet-токен не должен попадать в mainnet-настройки. -- Выполните тестовый платеж и проверьте, что статус закрывается после callback от провайдера. -- Если сумма или asset выглядят неверно, проверьте сочетание `CRYPTOPAY_CURRENCY_TYPE` и `CRYPTOPAY_ASSET`. - -## Где подробнее - -- [Переменные CryptoPay](../configuration/env-vars.md#cryptopay) -- [Настройка платежей](../features/payments.md) -- [Логи и диагностика](../troubleshooting/logs.md) diff --git a/docs/payments/freekassa.md b/docs/payments/freekassa.md deleted file mode 100644 index 9c8d020..0000000 --- a/docs/payments/freekassa.md +++ /dev/null @@ -1,16 +0,0 @@ -# FreeKassa - -FreeKassa подключается как отдельный платежный метод и обрабатывает входящие webhook-события через backend. - -## Что настроить - -- Включение провайдера: `FREEKASSA_ENABLED`. -- ID магазина, API/secret-ключи и настройки подписи. -- Trusted IP allowlist, если используется. -- Публичный webhook URL на `WEBHOOK_BASE_URL`. - -## Где подробнее - -- [Переменные FreeKassa](../configuration/env-vars.md#freekassa) -- [Платежи](../features/payments.md) -- [Логи и проверка](../troubleshooting/logs.md) diff --git a/docs/payments/heleket.md b/docs/payments/heleket.md deleted file mode 100644 index 3fc183f..0000000 --- a/docs/payments/heleket.md +++ /dev/null @@ -1,31 +0,0 @@ -# Heleket - -Heleket используется для crypto-инвойсов с отдельными merchant ID, payment API key, валютой инвойса и настройками webhook-проверки. - -## Что включить - -- `HELEKET_ENABLED` - включает Heleket среди доступных методов. -- Presentation-ключи `PAYMENT_HELEKET_*` - подписи и иконки кнопки. - -## Что настроить - -1. Укажите `HELEKET_BASE_URL`, `HELEKET_MERCHANT_ID` и `HELEKET_API_KEY`. -2. Настройте `HELEKET_CURRENCY`. -3. При необходимости задайте `HELEKET_TO_CURRENCY` и `HELEKET_NETWORK`. -4. Проверьте `HELEKET_RETURN_URL` и `HELEKET_SUCCESS_URL`. -5. Настройте `HELEKET_LIFETIME_SECONDS`: допустимый диапазон 300..43200. -6. Если включаете проверку webhook, задайте `HELEKET_VERIFY_WEBHOOK_SIGNATURE`. -7. Для IP-фильтрации заполните `HELEKET_TRUSTED_IPS`. -8. Добавьте `heleket` в `PAYMENT_METHODS_ORDER`. - -## Проверка - -- Создайте тестовый инвойс и убедитесь, что пользователь получает корректную ссылку. -- Проверьте, что сеть и валюта соответствуют настройкам в кабинете Heleket. -- Если webhook отклоняется, проверьте подпись, allowlist и фактический payload в backend-логах. - -## Где подробнее - -- [Переменные Heleket](../configuration/env-vars.md#heleket) -- [Настройка платежей](../features/payments.md) -- [Логи и диагностика](../troubleshooting/logs.md) diff --git a/docs/payments/platega.md b/docs/payments/platega.md deleted file mode 100644 index faab142..0000000 --- a/docs/payments/platega.md +++ /dev/null @@ -1,30 +0,0 @@ -# Platega - -Platega подключается как отдельный платежный провайдер, но внутри Minishop может дать несколько кнопок: основную legacy-кнопку, СБП/карту и крипто-кнопку. Общие merchant-параметры задаются один раз, а method ID и подписи кнопок настраиваются отдельно. - -## Что включить - -- `PLATEGA_ENABLED` - общий флаг провайдера. -- `PLATEGA_SBP_ENABLED` - отдельная кнопка СБП/карта. -- `PLATEGA_CRYPTO_ENABLED` - отдельная crypto-кнопка Platega. -- `PLATEGA_PAYMENT_METHOD` - legacy/fallback method ID для старых callback и старых установок. - -## Что настроить - -1. Укажите `PLATEGA_BASE_URL`, `PLATEGA_MERCHANT_ID` и `PLATEGA_SECRET`. -2. Заполните `PLATEGA_SBP_METHOD` и/или `PLATEGA_CRYPTO_METHOD`, если используете отдельные кнопки. -3. Проверьте `PLATEGA_RETURN_URL` и `PLATEGA_FAILED_URL`. -4. Настройте тексты и иконки кнопок через `PAYMENT_PLATEGA_SBP_*` и `PAYMENT_PLATEGA_CRYPTO_*`. -5. Добавьте нужные методы в `PAYMENT_METHODS_ORDER`. - -## Проверка - -- После сохранения настроек откройте Mini App и убедитесь, что видны только включенные Platega-кнопки. -- Выполните тестовую оплату для каждой включенной кнопки: СБП/карта и crypto используют разные method ID. -- При ошибках проверьте backend-логи и ответ провайдера при создании платежной ссылки. - -## Где подробнее - -- [Переменные Platega](../configuration/env-vars.md#platega) -- [Настройка платежей](../features/payments.md) -- [Логи и диагностика](../troubleshooting/logs.md) diff --git a/docs/payments/severpay.md b/docs/payments/severpay.md deleted file mode 100644 index cd716fd..0000000 --- a/docs/payments/severpay.md +++ /dev/null @@ -1,28 +0,0 @@ -# SeverPay - -SeverPay подключается как отдельный платежный метод с собственным MID, token и сроком жизни платежной ссылки. - -## Что включить - -- `SEVERPAY_ENABLED` - показывает SeverPay среди доступных методов оплаты. -- Presentation-ключи `PAYMENT_SEVERPAY_*` - подписи и иконки кнопки в Mini App и Telegram. - -## Что настроить - -1. Укажите `SEVERPAY_BASE_URL`. -2. Заполните `SEVERPAY_MID` и `SEVERPAY_TOKEN`. -3. Настройте `SEVERPAY_RETURN_URL`. -4. При необходимости задайте `SEVERPAY_LIFETIME_MINUTES`. -5. Добавьте `severpay` в `PAYMENT_METHODS_ORDER`. - -## Проверка - -- Создайте тестовый платеж и проверьте, что пользователь получает платежную ссылку. -- Убедитесь, что ссылка живет ожидаемое время, если задан `SEVERPAY_LIFETIME_MINUTES`. -- После оплаты проверьте статус платежа в backend-логах и в админке. - -## Где подробнее - -- [Переменные SeverPay](../configuration/env-vars.md#severpay) -- [Настройка платежей](../features/payments.md) -- [Логи и диагностика](../troubleshooting/logs.md) diff --git a/docs/payments/telegram-stars.md b/docs/payments/telegram-stars.md deleted file mode 100644 index a14907e..0000000 --- a/docs/payments/telegram-stars.md +++ /dev/null @@ -1,19 +0,0 @@ -# Telegram Stars - -Telegram Stars используются напрямую и поддерживаются в legacy-ценах и JSON-каталоге тарифов. - -## Где применяются Stars - -- Цены периодов подписки. -- Пакеты трафика. -- Premium-докупки. -- HWID-докупки, если они включены в каталоге тарифов. - -## Что проверить - -- `STARS_ENABLED`. -- Stars-цены в legacy-настройках или JSON-каталоге. -- Корректное округление цены до целого количества Stars. -- Сценарии смены тарифа: XTR/Stars-докупки не конвертируются без явного курса. - -Подробности: [переменные платежей](../configuration/env-vars.md#платежи) и [тарифы](../features/tariffs.md). diff --git a/docs/payments/wata.md b/docs/payments/wata.md deleted file mode 100644 index 777849e..0000000 --- a/docs/payments/wata.md +++ /dev/null @@ -1,30 +0,0 @@ -# Wata - -Wata подключается как отдельный провайдер с bearer token, платежными ссылками и опциональной проверкой подписи webhook. - -## Что включить - -- `WATA_ENABLED` - включает Wata для пользователей. -- `WATA_ADMIN_ONLY_ENABLED` - оставляет метод доступным только для админских сценариев, если используется вместо публичного включения. -- Presentation-ключи `PAYMENT_WATA_*` - подписи и иконки кнопки. - -## Что настроить - -1. Укажите `WATA_BASE_URL` и `WATA_API_TOKEN`. -2. Проверьте `WATA_RETURN_URL` и `WATA_FAILED_URL`. -3. Настройте `WATA_LINK_TTL_MINUTES`: минимум 15 минут, максимум 43200. -4. Если включаете проверку подписи, задайте `WATA_WEBHOOK_VERIFY_SIGNATURE` и при необходимости `WATA_PUBLIC_KEY`. -5. Для дополнительной защиты заполните `WATA_TRUSTED_IPS`. -6. Добавьте `wata` в `PAYMENT_METHODS_ORDER`. - -## Проверка - -- Создайте тестовый платеж и убедитесь, что ссылка открывается у пользователя. -- Проверьте входящий webhook: подпись и IP-allowlist должны соответствовать фактическому запросу Wata. -- Если платеж остается в pending, проверьте backend-логи вокруг webhook и статуса ссылки. - -## Где подробнее - -- [Переменные Wata](../configuration/env-vars.md#wata) -- [Настройка платежей](../features/payments.md) -- [Логи и диагностика](../troubleshooting/logs.md) diff --git a/docs/payments/yookassa.md b/docs/payments/yookassa.md deleted file mode 100644 index ef94066..0000000 --- a/docs/payments/yookassa.md +++ /dev/null @@ -1,16 +0,0 @@ -# YooKassa - -YooKassa используется для рублевых оплат и может участвовать в сценариях автопродления period-подписок. - -## Что настроить - -- Включение провайдера: `YOOKASSA_ENABLED`. -- Идентификаторы и секреты магазина. -- Webhook URL на backend-домен. -- Отображение кнопки оплаты и порядок платежных методов. - -## Где подробнее - -- [Переменные YooKassa](../configuration/env-vars.md#yookassa) -- [Платежи](../features/payments.md) -- [Тарифы и автопродление](../features/tariffs.md#автопродление-пробный-период-и-бонусы) diff --git a/docs/troubleshooting/issues.md b/docs/troubleshooting/issues.md index de3aae9..a055b9b 100644 --- a/docs/troubleshooting/issues.md +++ b/docs/troubleshooting/issues.md @@ -9,7 +9,7 @@ - Убедитесь, что PostgreSQL и Redis здоровы. - Проверьте обязательные переменные в `.env`. -## Telegram webhook не работает +## Вебхук Telegram не работает - Проверьте `WEBHOOK_BASE_URL`. - Убедитесь, что домен доступен по HTTPS. @@ -26,7 +26,7 @@ ## Платеж не засчитался - Проверьте включение провайдера. -- Проверьте webhook URL и секреты. +- Проверьте URL вебхука и секреты. - Посмотрите backend-логи. - Сверьте статус платежа в админке и кабинете провайдера. diff --git a/docs/troubleshooting/logs.md b/docs/troubleshooting/logs.md index 70f253e..7abfe25 100644 --- a/docs/troubleshooting/logs.md +++ b/docs/troubleshooting/logs.md @@ -14,14 +14,14 @@ docker compose logs migrate ## Что искать - ошибки миграций в `migrate`; -- ошибки Telegram webhook и payment webhook в `backend`; +- ошибки вебхука Telegram и платежных вебхуков в `backend`; - проблемы очереди вебхуков и фоновых задач в `worker`; -- ошибки проксирования `/api`, `/auth` и theme assets во `frontend`; +- ошибки проксирования `/api`, `/auth` и ассетов тем во `frontend`; - ошибки авторизации Mini App и Telegram OAuth. -## Frontend proxy, `/api`, `/auth` и theme assets +## Проксирование frontend, `/api`, `/auth` и ассеты тем -`frontend` - это nginx-контейнер Mini App. Он отдает статику и проксирует Web App маршруты во внутренний backend WebApp server на `backend:8081`. +`frontend` - это nginx-контейнер Mini App. Он отдает статику и проксирует маршруты Web App во внутренний WebApp-сервер backend на `backend:8081`. Сначала смотрите nginx-логи: @@ -33,7 +33,7 @@ docker compose logs -f frontend - `/api/*` и `/auth/*` должны попадать в `frontend:80`, а уже frontend проксирует их в `backend:8081`; - `/webapp-logo`, `/webapp-uploaded-logo/*`, `/webapp-favicon/*`, `/webapp-theme-css/*` и `/webapp-theme-assets/*` тоже проксируются через frontend; -- внешний reverse proxy не должен отдельно уводить `/api` или `/auth` на webhook-сервер `backend:8080`. +- внешний обратный прокси не должен отдельно уводить `/api` или `/auth` на webhook-сервер `backend:8080`. Быстрые проверки снаружи: @@ -44,7 +44,7 @@ curl -i https://app.domain.com/auth/telegram/start curl -i https://app.domain.com/webapp-theme-css/dark/style.css ``` -Если `/health` отвечает, а `/api/bootstrap` или theme assets падают, смотрите одновременно frontend и backend: +Если `/health` отвечает, а `/api/bootstrap` или ассеты тем падают, смотрите одновременно frontend и backend: ```bash docker compose logs -f frontend backend @@ -54,12 +54,12 @@ docker compose logs -f frontend backend - frontend nginx: `deploy/docker/frontend/nginx.conf`; - внешний Caddy/Nginx: `deploy/examples/caddy/Caddyfile` или `deploy/examples/nginx/nginx.conf.template`; -- Web App домен: `SUBSCRIPTION_MINI_APP_URL`, он должен быть публичным HTTPS URL frontend, без `/api`, `/auth` или webhook-пути; -- WebApp server backend: `WEBAPP_ENABLED=True`, `WEBAPP_SERVER_HOST=0.0.0.0`, `WEBAPP_SERVER_PORT=8081`. +- домен Web App: `SUBSCRIPTION_MINI_APP_URL`, он должен быть публичным HTTPS URL frontend, без `/api`, `/auth` или webhook-пути; +- WebApp-сервер backend: `WEBAPP_ENABLED=True`, `WEBAPP_SERVER_HOST=0.0.0.0`, `WEBAPP_SERVER_PORT=8081`. -## Mini App auth и Telegram OAuth +## Авторизация Mini App и Telegram OAuth -Ошибки авторизации почти всегда видны в `backend`, потому что проверка Telegram Mini Apps `initData`, Telegram OAuth `id_token`, nonce/state и сессий выполняется на backend WebApp server. +Ошибки авторизации почти всегда видны в `backend`, потому что проверка Telegram Mini Apps `initData`, Telegram OAuth `id_token`, nonce/state и сессий выполняется на WebApp-сервере backend. ```bash docker compose logs -f backend @@ -92,7 +92,7 @@ docker compose logs -f backend - `/auth/telegram/start` и `/auth/telegram/callback` проходят через frontend nginx в `backend:8081`; - в браузере после callback нет статуса `telegram_auth=invalid_state`, `invalid_token`, `not_configured`, `unauthorized` или `failed`. -Подробности по маршрутам и настройке OAuth: [Web App / Mini App](../features/web-app.md). +Подробности по маршрутам и настройке OAuth: [веб-приложение / Mini App](../features/web-app.md). ## После изменения конфигурации