austnv/remnawave-minishop
1
0
Fork 0
Code Issues 1 Pull Requests Activity

docs: refactor docs structure

Browse Source
This commit is contained in:
3252a8
2026-05-26 21:45:44 +03:00
parent 0c167c8f09
commit 0df52d0235
41 changed files with 455 additions and 669 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+9 -9
View File
@@ -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:
deploy/examples/README.md
+6 -6
View File
@@ -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#без-обратного-прокси) |
deploy/examples/caddy/README.md
+1 -1
View File
@@ -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`.
deploy/examples/newt/README.md
+1 -1
View File
@@ -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`.
deploy/examples/nginx/README.md
+1 -1
View File
@@ -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/` для сертификатов.
deploy/examples/nginx/ssl/README.md
+1 -1
View File
@@ -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`:
deploy/examples/no-proxy/README.md
+2 -2
View File
@@ -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`.
docs-site/astro.config.mjs
+4 -32
View File
@@ -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' },
],
},
],
}),
],
docs-site/scripts/sync-docs.mjs
+7 -20
View File
@@ -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',
];
docs/administration/users.md
+1 -1
View File
@@ -14,6 +14,6 @@
## Связанные разделы
- [Админ-панель](../features/admin-panel.md)
- [Поддержка](../features/support.md)
- [Поддержка пользователей / тикеты](../features/support.md)
- [Тарифы](../features/tariffs.md)
- [Mini App](../features/web-app.md)
docs/architecture.md
+26 -32
View File
@@ -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
docs/configuration.md
+9 -9
View File
@@ -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 и обновления.
docs/configuration/env-vars.md
+39 -39
View File
@@ -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/<token>`. По умолчанию `True`; если выключить, бот ведет на финальную Remnawave Subscription Page. |
| `SUBSCRIPTION_PAGE_CONFIG_PANEL_ENABLED` | `.env` / админка | Читать Remnawave Subscription Page config из панели для встроенных инструкций. По умолчанию `True`, чтобы не дублировать настройку страницы подписки в приложении. |
| `SUBSCRIPTION_PAGE_CONFIG_JSON_OVERRIDE_ENABLED` | `.env` / админка | Включает использование JSON из поля `SUBSCRIPTION_PAGE_CONFIG_JSON` вместо конфига панели. По умолчанию `False`. |
| `SUBSCRIPTION_PAGE_CONFIG_PATH` | `.env` / админка | 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-уведомлениями. |
## Логирование
docs/configuration/security.md
+4 -4
View File
@@ -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).
docs/deploy-examples/caddy.md
-39
View File
@@ -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
```
docs/deploy-examples/index.md
-39
View File
@@ -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
```
docs/deploy-examples/newt.md
-38
View File
@@ -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: <https://docs.pangolin.net/manage/sites/install-site>.
## Проверка
```bash
docker compose ps
docker compose logs -f newt backend worker frontend
```
docs/deploy-examples/nginx.md
-44
View File
@@ -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
```
docs/deploy-examples/no-proxy.md
-35
View File
@@ -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
```
docs/deployment.md
+129 -36
View File
@@ -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-тестов или отдельного окружения можно подставить
docs/features/admin-panel.md
+5 -5
View File
@@ -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_<METHOD>_WEBAPP_LABEL_RU`, `PAYMENT_<METHOD>_WEBAPP_LABEL_EN`, `PAYMENT_<METHOD>_WEBAPP_ICON`, `PAYMENT_<METHOD>_TELEGRAM_LABEL_RU`, `PAYMENT_<METHOD>_TELEGRAM_LABEL_EN` и `PAYMENT_<METHOD>_TELEGRAM_EMOJI`. Пустое значение возвращает мультиязычный дефолт из модуля платежного провайдера. Иконка Web App выбирается из уже подключённых lucide-иконок (`frontend/src/lib/components/ui/icons.js`) через модалку в админке.
Для каждого платежного метода в разделе провайдера доступны настройки отображения `PAYMENT_<METHOD>_WEBAPP_LABEL_RU`, `PAYMENT_<METHOD>_WEBAPP_LABEL_EN`, `PAYMENT_<METHOD>_WEBAPP_ICON`, `PAYMENT_<METHOD>_TELEGRAM_LABEL_RU`, `PAYMENT_<METHOD>_TELEGRAM_LABEL_EN` и `PAYMENT_<METHOD>_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).
## Внешний вид
docs/features/core.md
+1 -1
View File
@@ -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).
docs/features/payments.md
+142 -18
View File
@@ -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).
docs/features/support.md
+1 -1
View File
@@ -1,4 +1,4 @@
# Поддержка
# Поддержка пользователей / тикеты
В проекте есть два канала поддержки:
docs/features/tariffs.md
+4 -4
View File
@@ -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` продает объем трафика без пользовательского срока действия.
docs/features/web-app.md
+20 -20
View File
@@ -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/<token>`: она открывает тот же интерфейс инструкций без авторизации и нижней навигации, но без QR-блока. Публичный payload отдается через `/api/subscription-guides/public/{share_token}` только для активной локальной подписки с валидным share token.
`SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED=True` включает такое же поведение в Telegram-боте: кнопки подключения открывают Mini App `/install`, а после успешной оплаты, trial или промокода пользователь получает публичную ссылку `/s/<token>`. Если настройку выключить, бот снова отправляет пользователя на финальную Remnawave Subscription Page.
`SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED=True` включает такое же поведение в Telegram-боте: кнопки подключения открывают Mini App `/install`, а после успешной оплаты, пробного периода или промокода пользователь получает публичную ссылку `/s/<token>`. Если настройку выключить, бот снова отправляет пользователя на финальную 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/<bot>?start=ref_u<code>`;
- Web App ссылка: `https://app.domain.com/?ref=u<code>`.
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_<referral_code>`. Email добавляется в описание пользователя панели и, если API панели принимает поле `email`, передается отдельным полем. Для Telegram-регистраций используется username `tg_<telegram_id>`.
docs/getting-started/overview.md
+3 -3
View File
@@ -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 и инструкции установки.
docs/getting-started/setup.md
+15 -5
View File
@@ -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-терминатора.
## После первого входа
docs/index.md
+3 -3
View File
@@ -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`.
## Справочник
docs/migrations/index.md
+2 -2
View File
@@ -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.
## Что пока не описано
docs/migrations/remnawave-tg-shop.md
+6 -7
View File
@@ -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
пример, который уже знает правильную маршрутизацию.
docs/payments/cryptopay.md
-28
View File
@@ -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)
docs/payments/freekassa.md
-16
View File
@@ -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)
docs/payments/heleket.md
-31
View File
@@ -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)
docs/payments/platega.md
-30
View File
@@ -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)
docs/payments/severpay.md
-28
View File
@@ -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)
docs/payments/telegram-stars.md
-19
View File
@@ -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).
docs/payments/wata.md
-30
View File
@@ -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)
docs/payments/yookassa.md
-16
View File
@@ -1,16 +0,0 @@
# YooKassa
YooKassa используется для рублевых оплат и может участвовать в сценариях автопродления period-подписок.
## Что настроить
- Включение провайдера: `YOOKASSA_ENABLED`.
- Идентификаторы и секреты магазина.
- Webhook URL на backend-домен.
- Отображение кнопки оплаты и порядок платежных методов.
## Где подробнее
- [Переменные YooKassa](../configuration/env-vars.md#yookassa)
- [Платежи](../features/payments.md)
- [Тарифы и автопродление](../features/tariffs.md#автопродление-пробный-период-и-бонусы)
docs/troubleshooting/issues.md
+2 -2
View File
@@ -9,7 +9,7 @@
- Убедитесь, что PostgreSQL и Redis здоровы.
- Проверьте обязательные переменные в `.env`.
## Telegram webhook не работает
## Вебхук Telegram не работает
- Проверьте `WEBHOOK_BASE_URL`.
- Убедитесь, что домен доступен по HTTPS.
@@ -26,7 +26,7 @@
## Платеж не засчитался
- Проверьте включение провайдера.
- Проверьте webhook URL и секреты.
- Проверьте URL вебхука и секреты.
- Посмотрите backend-логи.
- Сверьте статус платежа в админке и кабинете провайдера.
docs/troubleshooting/logs.md
+11 -11
View File
@@ -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).
## После изменения конфигурации