diff --git a/README.md b/README.md index 580be69..6e1adb5 100644 --- a/README.md +++ b/README.md @@ -33,15 +33,14 @@ Remnawave Minishop - Telegram-бот и Web App (Mini App) для продажи ## Документация - [Входная страница документации](docs/index.md) - маршрут по установке, настройке, платежам, админке и диагностике. -- [Развертывание](docs/deployment.md) - Docker Compose, Caddy, Nginx, Pangolin/Newt и запуск без обратного прокси. -- [Настройка окружения](docs/configuration.md) - bootstrap `.env` и рекомендуемая настройка через Web App админку. +- [Развертывание](docs/getting-started/deployment.md) - Docker Compose, Caddy, Nginx, Pangolin/Newt и запуск без обратного прокси. +- [Настройка окружения](docs/getting-started/configuration.md) - bootstrap `.env` и рекомендуемая настройка через Web App админку. - [Переменные `.env`](docs/configuration/env-vars.md) - полный справочник всех env-ключей по разделам. - [Тарифы](docs/features/tariffs.md) - каталог тарифов, модели на срок и по трафику, обычные и premium-докупки, premium-сквады, смена тарифа, HWID-лимиты и обработка трафика. - [Админ-панель](docs/features/admin-panel.md) - права доступа, настройки, редактор тарифов, premium-сквады и сохранение JSON-каталога. - [Веб-приложение / 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, обратный прокси, Nginx, Caddy, вебхуки, запуск из образа и обновление версии (`IMAGE_TAG`). - [Миграции](docs/migrations/index.md) - готовые сценарии переноса с других ботов; сейчас описан `remnawave-tg-shop`. - [Миграция с remnawave-tg-shop](docs/migrations/remnawave-tg-shop.md) - готовый сценарий для legacy-стека. @@ -123,7 +122,7 @@ docker compose up -d IMAGE_TAG=3.1.0 docker compose up -d ``` -Для продакшен-запуска удобнее брать готовые папки из [`deploy/examples`](deploy/examples), а читать каноничные инструкции в [docs/deployment.md](docs/deployment.md). Предпочтительный вариант для обычного публичного сервера - Caddy: он сам выпускает и продлевает HTTPS-сертификаты. В папках рядом с compose лежат только конфиги и короткие ссылки на документацию. +Для продакшен-запуска удобнее брать готовые папки из [`deploy/examples`](deploy/examples), а читать каноничные инструкции в [docs/getting-started/deployment.md](docs/getting-started/deployment.md). Предпочтительный вариант для обычного публичного сервера - Caddy: он сам выпускает и продлевает HTTPS-сертификаты. В папках рядом с compose лежат только конфиги и короткие ссылки на документацию. Имена образов для релизов: diff --git a/deploy/examples/README.md b/deploy/examples/README.md index b0ab572..0ad8ca8 100644 --- a/deploy/examples/README.md +++ b/deploy/examples/README.md @@ -1,12 +1,12 @@ # Примеры Docker Compose -Каноничная документация по вариантам запуска живет в [docs/deployment.md](../../docs/deployment.md). +Каноничная документация по вариантам запуска живет в [docs/getting-started/deployment.md](../../docs/getting-started/deployment.md). Эта папка хранит только рабочие compose-примеры и конфиги. Подробное описание не дублируется здесь, чтобы сайт документации и навигация из README использовали один источник. | Папка | Документация | | --- | --- | -| `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#без-обратного-прокси) | +| `caddy` | [Развертывание с Caddy](../../docs/getting-started/deployment.md#caddy-рекомендуемый-вариант) | +| `nginx` | [Развертывание с Nginx](../../docs/getting-started/deployment.md#nginx) | +| `newt` | [Развертывание через Pangolin / Newt](../../docs/getting-started/deployment.md#pangolin--newt) | +| `no-proxy` | [Запуск без обратного прокси](../../docs/getting-started/deployment.md#без-обратного-прокси) | diff --git a/deploy/examples/caddy/README.md b/deploy/examples/caddy/README.md index f8d75ed..54ea587 100644 --- a/deploy/examples/caddy/README.md +++ b/deploy/examples/caddy/README.md @@ -1,5 +1,5 @@ # Caddy -Каноничная инструкция: [docs/deployment.md](../../../docs/deployment.md#caddy-рекомендуемый-вариант). +Каноничная инструкция: [docs/getting-started/deployment.md](../../../docs/getting-started/deployment.md#caddy-рекомендуемый-вариант). Файлы этого примера остаются рядом: `docker-compose.yml`, `.env.example` и `Caddyfile`. diff --git a/deploy/examples/newt/README.md b/deploy/examples/newt/README.md index 5db50a9..caa41ed 100644 --- a/deploy/examples/newt/README.md +++ b/deploy/examples/newt/README.md @@ -1,5 +1,5 @@ # Pangolin / Newt -Каноничная инструкция: [docs/deployment.md](../../../docs/deployment.md#pangolin--newt). +Каноничная инструкция: [docs/getting-started/deployment.md](../../../docs/getting-started/deployment.md#pangolin--newt). Файлы этого примера остаются рядом: `docker-compose.yml` и `.env.example`. diff --git a/deploy/examples/nginx/README.md b/deploy/examples/nginx/README.md index 37d6241..19173c9 100644 --- a/deploy/examples/nginx/README.md +++ b/deploy/examples/nginx/README.md @@ -1,5 +1,5 @@ # Nginx -Каноничная инструкция: [docs/deployment.md](../../../docs/deployment.md#nginx). +Каноничная инструкция: [docs/getting-started/deployment.md](../../../docs/getting-started/deployment.md#nginx). Файлы этого примера остаются рядом: `docker-compose.yml`, `.env.example`, `nginx.conf.template` и папка `ssl/` для сертификатов. diff --git a/deploy/examples/nginx/ssl/README.md b/deploy/examples/nginx/ssl/README.md index 854f533..ce05203 100644 --- a/deploy/examples/nginx/ssl/README.md +++ b/deploy/examples/nginx/ssl/README.md @@ -1,6 +1,6 @@ # TLS certificates -Каноничная инструкция по Nginx: [docs/deployment.md](../../../../docs/deployment.md#nginx). +Каноничная инструкция по Nginx: [docs/getting-started/deployment.md](../../../../docs/getting-started/deployment.md#nginx). Кладите сертификаты в подпапки, совпадающие с `WEBHOOK_HOST` и `MINIAPP_HOST`: diff --git a/deploy/examples/no-proxy/README.md b/deploy/examples/no-proxy/README.md index 931278d..638d041 100644 --- a/deploy/examples/no-proxy/README.md +++ b/deploy/examples/no-proxy/README.md @@ -1,5 +1,5 @@ # Без обратного прокси -Каноничная инструкция: [docs/deployment.md](../../../docs/deployment.md#без-обратного-прокси). +Каноничная инструкция: [docs/getting-started/deployment.md](../../../docs/getting-started/deployment.md#без-обратного-прокси). Файлы этого примера остаются рядом: `docker-compose.yml` и `.env.example`. diff --git a/docs-site/astro.config.mjs b/docs-site/astro.config.mjs index c1dcde7..ff66b52 100644 --- a/docs-site/astro.config.mjs +++ b/docs-site/astro.config.mjs @@ -13,14 +13,16 @@ export default defineConfig({ plugins: [ starlightThemeNova({ nav: [ - { label: 'Главная', href: '/' }, { label: 'Установка', href: '/getting-started/setup/' }, - { label: 'Платежи', href: '/features/payments/' }, { label: 'GitHub', href: 'https://github.com/3252a8/remnawave-minishop' }, + { label: 'Telegram', href: 'https://t.me/remnawave_minishop' } ], }), ], customCss: ['./src/styles/custom.css'], + components: { + Header: './src/components/Header.astro', + }, lastUpdated: false, locales: { root: { @@ -56,18 +58,16 @@ export default defineConfig({ { label: 'Начало', items: [ - { label: 'Главная', link: '/' }, { label: 'Обзор', slug: 'getting-started/overview' }, { label: 'Установка', slug: 'getting-started/setup' }, - { label: 'Архитектура', slug: 'reference/architecture' }, - { label: 'Развертывание', slug: 'reference/deployment' }, + { label: 'Развертывание', slug: 'getting-started/deployment' }, + { label: 'Настройка окружения', slug: 'getting-started/configuration' }, ], }, { label: 'Конфигурация', items: [ - { label: 'Переменные', slug: 'configuration/env-vars' }, - { label: 'Настройка окружения', slug: 'reference/configuration' }, + { label: 'Переменные окружения', slug: 'configuration/env-vars' }, { label: 'Безопасность', slug: 'configuration/security' }, ], }, @@ -84,13 +84,6 @@ export default defineConfig({ { label: 'Поддержка пользователей / тикеты', slug: 'features/support' }, ], }, - { - label: 'Администрирование', - items: [ - { label: 'Пользователи', slug: 'administration/users' }, - { label: 'Обслуживание', slug: 'administration/maintenance' }, - ], - }, { label: 'Миграции', items: [ @@ -99,10 +92,12 @@ export default defineConfig({ ], }, { - label: 'Устранение неполадок', + label: 'Справка', items: [ { label: 'Проблемы', slug: 'troubleshooting/issues' }, { label: 'Логи', slug: 'troubleshooting/logs' }, + { label: 'Обслуживание', slug: 'troubleshooting/maintenance' }, + { label: 'Архитектура', slug: 'reference/architecture' }, ], }, ], diff --git a/docs-site/scripts/sync-docs.mjs b/docs-site/scripts/sync-docs.mjs index fde7072..600ee50 100644 --- a/docs-site/scripts/sync-docs.mjs +++ b/docs-site/scripts/sync-docs.mjs @@ -11,6 +11,8 @@ const descriptions = { 'index.md': 'Документация по запуску, настройке и сопровождению Telegram Mini App для Remnawave.', 'getting-started/overview.md': 'Что входит в Remnawave Minishop и как связаны бот, Mini App, backend, worker и Remnawave Panel.', 'getting-started/setup.md': 'Минимальный путь запуска Remnawave Minishop через Docker Compose.', + 'getting-started/configuration.md': 'Минимальный .env, bootstrap-секреты и настройка через Web App админку.', + 'getting-started/deployment.md': 'Docker Compose, обратный прокси, TLS, образы, обновления и резервные копии.', 'configuration/security.md': 'Секреты, публичные URL, доступ администраторов и базовые меры защиты Minishop.', 'configuration/env-vars.md': 'Полный справочник переменных окружения Remnawave Minishop.', 'features/core.md': 'Пользовательские и админские сценарии Remnawave Minishop.', @@ -23,13 +25,10 @@ const descriptions = { 'features/support.md': 'Пользовательские тикеты, список обращений в админке, уведомления и лимиты поддержки.', 'migrations/index.md': 'Готовые сценарии миграции в Remnawave Minishop с других ботов.', 'migrations/remnawave-tg-shop.md': 'Перенос данных со старого remnawave-tg-shop на split-архитектуру Minishop.', - 'administration/users.md': 'Где управлять пользователями, подписками, блокировками и поддержкой.', - 'administration/maintenance.md': 'Обновления, миграции, резервные копии и проверки продакшен-стека.', 'troubleshooting/issues.md': 'Короткие чеклисты для частых проблем запуска, вебхуков, Mini App и платежей.', 'troubleshooting/logs.md': 'Какие логи смотреть при диагностике backend, worker, frontend, миграций и вебхуков.', + 'troubleshooting/maintenance.md': 'Обновления, миграции, резервные копии и проверки продакшен-стека.', 'architecture.md': 'Краткая архитектура backend, frontend, worker и инфраструктурных сервисов.', - 'configuration.md': 'Минимальный .env, bootstrap-секреты и настройка через Web App админку.', - 'deployment.md': 'Docker Compose, обратный прокси, TLS, образы, обновления и резервные копии.', }; const imageExtensions = new Set(['.avif', '.gif', '.jpeg', '.jpg', '.png', '.svg', '.webp']); @@ -98,11 +97,11 @@ function extraFrontmatter(sourceRelativePath) { ' image:', ' html: \'Интерфейс Remnawave Minishop\'', ' actions:', - ' - text: "Быстрый старт"', - ' link: /getting-started/setup/', + ' - text: "Обзор"', + ' link: /getting-started/overview/', ' icon: right-arrow', - ' - text: "Развертывание"', - ' link: /reference/deployment/', + ' - text: "Установка"', + ' link: /getting-started/setup/', ' icon: setting', ' variant: minimal', ]; diff --git a/docs-site/src/components/Header.astro b/docs-site/src/components/Header.astro new file mode 100644 index 0000000..f9e69ec --- /dev/null +++ b/docs-site/src/components/Header.astro @@ -0,0 +1,104 @@ +--- +import type { StarlightRouteData } from '@astrojs/starlight/route-data' +import { Icon } from '@astrojs/starlight/components' +import LanguageSelect from 'virtual:starlight/components/LanguageSelect' +import Search from 'virtual:starlight/components/Search' +import SiteTitle from 'virtual:starlight/components/SiteTitle' +import SocialIcons from 'virtual:starlight/components/SocialIcons' +import ThemeSelect from 'virtual:starlight/components/ThemeSelect' +import config from 'virtual:starlight/user-config' + +import MobileMenuToggle from 'starlight-theme-nova/components/MobileMenuToggle.astro' +import options from 'virtual:starlight-theme-nova/user-config' + +const { hasSidebar } = Astro.locals.starlightRoute +const nav = options.nav ?? [] +const route = Astro.locals.starlightRoute + +function getI18nText( + value: string | Record, + route: StarlightRouteData, +): string { + if (typeof value === 'string') { + return value + } + + const { lang, locale } = route + + if (value[lang]) { + return value[lang] + } + + if (config.defaultLocale.lang === lang || config.defaultLocale.locale === locale) { + if (value.root) { + return value.root + } + } + + if (locale && value[locale]) { + return value[locale] + } + + throw new Error(`Unable to find the translation for language "${lang}".`) +} + +function navIcon(href: string) { + if (href.includes('github.com/3252a8/remnawave-minishop')) { + return 'github' + } + if (href.includes('t.me/remnawave_minishop')) { + return 'telegram' + } + return undefined +} +--- + +
+
+ +
+ +
+ +
+ + { + hasSidebar && ( +
+ +
+ ) + } +
diff --git a/docs-site/src/styles/custom.css b/docs-site/src/styles/custom.css index ce05293..4318b7f 100644 --- a/docs-site/src/styles/custom.css +++ b/docs-site/src/styles/custom.css @@ -12,6 +12,14 @@ color: #00fe7a; } + .minishop-header-link { + column-gap: 0.625rem; + } + + .minishop-header-link svg { + flex-shrink: 0; + } + .hero { gap: clamp(2rem, 6vw, 5rem); padding-block: clamp(3.5rem, 10vw, 6.5rem); diff --git a/docs/administration/maintenance.md b/docs/administration/maintenance.md deleted file mode 100644 index 6af4feb..0000000 --- a/docs/administration/maintenance.md +++ /dev/null @@ -1,59 +0,0 @@ -# Обслуживание - -Плановое обслуживание обычно сводится к обновлению образов, проверке миграций, логов и резервных копий PostgreSQL. - -## Обновление - -```bash -docker compose pull -docker compose up -d -docker compose logs -f migrate backend worker -``` - -## Резервная копия PostgreSQL - -```bash -docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB"' > backup.sql -``` - -## Проверки после работ - -- `docker compose ps` -- `docker compose logs -f backend worker frontend` -- `/healthz` на backend-домене -- вход в Mini App и админку -- тестовый платеж или тестовая активация - -## Синхронизация GitLab-зеркала - -Основное место работы - GitHub remote `origin`. GitLab remote `gitlab` используется как запасное зеркало. - -После пуша в GitHub синхронизируйте зеркало: - -```bash -bash scripts/sync-gitlab-mirror.sh -``` - -PowerShell-вариант: - -```powershell -powershell -ExecutionPolicy Bypass -File .\scripts\sync-gitlab-mirror.ps1 -``` - -По умолчанию скрипт делает `git fetch origin --prune --tags`, пушит все ветки из `origin/*` в `gitlab` и пушит теги. Он не удаляет ветки в GitLab и не делает force-push. Для строгого зеркалирования доступны флаги: - -```bash -bash scripts/sync-gitlab-mirror.sh --force --prune -``` - -```powershell -powershell -ExecutionPolicy Bypass -File .\scripts\sync-gitlab-mirror.ps1 -Force -Prune -``` - -Перед опасными режимами можно посмотреть команды без выполнения: - -```bash -bash scripts/sync-gitlab-mirror.sh --force --prune --dry-run -``` - -Подробности: [развертывание](../deployment.md) и [логи](../troubleshooting/logs.md). diff --git a/docs/administration/users.md b/docs/administration/users.md deleted file mode 100644 index 7f6232d..0000000 --- a/docs/administration/users.md +++ /dev/null @@ -1,19 +0,0 @@ -# Пользователи - -Пользовательские операции выполняются в Web App админке. Доступ получают только Telegram-пользователи из `ADMIN_IDS`. - -## Что доступно администратору - -- список пользователей с поиском и фильтрами; -- просмотр подписки, статуса, трафика и premium-лимитов; -- блокировка пользователя; -- ручная синхронизация с Remnawave Panel; -- тикеты поддержки и ответы пользователю; -- просмотр платежей и служебных событий. - -## Связанные разделы - -- [Админ-панель](../features/admin-panel.md) -- [Поддержка пользователей / тикеты](../features/support.md) -- [Тарифы](../features/tariffs.md) -- [Mini App](../features/web-app.md) diff --git a/docs/configuration/security.md b/docs/configuration/security.md index 55ee64c..77bb532 100644 --- a/docs/configuration/security.md +++ b/docs/configuration/security.md @@ -34,4 +34,4 @@ openssl rand -hex 32 - Следите за логами платежных вебхуков и вебхуков панели. - После ротации секретов перезапускайте соответствующие сервисы и проверяйте вебхуки. -См. также [переменные окружения](env-vars.md) и [развертывание](../deployment.md). +См. также [переменные окружения](env-vars.md) и [развертывание](../getting-started/deployment.md). diff --git a/docs/features/admin-panel.md b/docs/features/admin-panel.md index d073a00..b8f5cf6 100644 --- a/docs/features/admin-panel.md +++ b/docs/features/admin-panel.md @@ -18,6 +18,13 @@ Раздел **Пользователи** — таблица с **пагинацией по 25 записей**. Строка поиска ищет по внутреннему числовому ID, Telegram ID, фрагменту `@username`, имени или email; применение — кнопка «Найти» или клавиша Enter в поле поиска. +Из этого же раздела администратор управляет основными пользовательскими операциями: + +- просматривает подписку, статус, трафик, premium-лимиты, платежи и служебные события; +- блокирует пользователя; +- запускает ручную синхронизацию с Remnawave Panel; +- открывает тикеты поддержки и отвечает пользователю. + **Фильтры:** - состояние аккаунта: все / не забанены / забанены; @@ -72,7 +79,7 @@ } ``` -### Инструкции подключения +## Инструкции подключения Секция **Система -> Настройки -> Инструкции подключения** управляет встроенным экраном установки. `SUBSCRIPTION_GUIDES_ENABLED` включает `/install` в личном кабинете, а `SUBSCRIPTION_GUIDES_BOT_MENU_ENABLED` заставляет кнопки подключения в Telegram-боте открывать Mini App вместо финальной Remnawave Subscription Page. Оба переключателя включены по умолчанию. diff --git a/docs/features/web-app.md b/docs/features/web-app.md index 16c1e26..d4e163e 100644 --- a/docs/features/web-app.md +++ b/docs/features/web-app.md @@ -118,7 +118,7 @@ https://app.domain.com/auth/telegram/callback Для Brevo обычно подходит порт `587` с STARTTLS. Если основной порт недоступен, приложение пробует порты из `SMTP_FALLBACK_PORTS`; порт `465` используется через SSL. -Полный список переменных, обязательные поля для включения входа по email и типичные ошибки подключения описаны в разделе **SMTP и вход по email** в [configuration.md](../configuration.md). +Полный список переменных, обязательные поля для включения входа по email и типичные ошибки подключения описаны в разделе **SMTP и вход по email** в [configuration.md](../getting-started/configuration.md). ## Проксирование @@ -131,12 +131,12 @@ https://app.domain.com/auth/telegram/callback WebApp API на `backend:8081`, поэтому внешний обратный прокси обычно не должен отправлять эти пути в `backend:8081` напрямую. -Готовые варианты описаны в разделе [Развертывание](../deployment.md#готовые-папки-запуска): +Готовые варианты описаны в разделе [Развертывание](../getting-started/deployment.md#готовые-папки-запуска): -- [Caddy](../deployment.md#caddy-рекомендуемый-вариант) - автоматический HTTPS; -- [Nginx](../deployment.md#nginx) - сертификаты в соседней папке `ssl/`; -- [Pangolin/Newt](../deployment.md#pangolin--newt) - публикация без входящих портов на сервере приложения; -- [без обратного прокси](../deployment.md#без-обратного-прокси) - прямая публикация портов для проверки или внешней TLS-платформы. +- [Caddy](../getting-started/deployment.md#caddy-рекомендуемый-вариант) - автоматический HTTPS; +- [Nginx](../getting-started/deployment.md#nginx) - сертификаты в соседней папке `ssl/`; +- [Pangolin/Newt](../getting-started/deployment.md#pangolin--newt) - публикация без входящих портов на сервере приложения; +- [без обратного прокси](../getting-started/deployment.md#без-обратного-прокси) - прямая публикация портов для проверки или внешней TLS-платформы. В default `docker-compose.yml` наружу публикуются `frontend` и webhook/backend port, а внутри Docker network сервисы доступны друг другу по service DNS names: diff --git a/docs/configuration.md b/docs/getting-started/configuration.md similarity index 92% rename from docs/configuration.md rename to docs/getting-started/configuration.md index d7b0ec5..7b5ff90 100644 --- a/docs/configuration.md +++ b/docs/getting-started/configuration.md @@ -7,7 +7,7 @@ Админка сохраняет overrides в базе данных и применяет их поверх `.env`. Это удобно для платежей, внешнего вида, поддержки, уведомлений, legacy-цен и большинства пользовательских параметров. Тарифы редактируются отдельно в разделе **Система -> Тарифы** и сохраняются в JSON-файл `TARIFFS_CONFIG_PATH`. -Полный справочник всех переменных вынесен в [configuration/env-vars.md](configuration/env-vars.md). +Полный справочник всех переменных вынесен в [configuration/env-vars.md](../configuration/env-vars.md). ## Минимальный `.env` @@ -102,9 +102,9 @@ 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-каталог тарифов и редактор тарифов. -- [Веб-приложение / Mini App](features/web-app.md) - домен Mini App, Telegram OAuth и вход по email. -- [Поддержка пользователей / тикеты](features/support.md) - тикеты поддержки и уведомления. +- [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-каталог тарифов и редактор тарифов. +- [Веб-приложение / Mini App](../features/web-app.md) - домен Mini App, Telegram OAuth и вход по email. +- [Поддержка пользователей / тикеты](../features/support.md) - тикеты поддержки и уведомления. - [Развертывание](deployment.md) - Docker Compose, обратный прокси, Caddy/Nginx и обновления. diff --git a/docs/deployment.md b/docs/getting-started/deployment.md similarity index 98% rename from docs/deployment.md rename to docs/getting-started/deployment.md index 9491ddc..6fb8858 100644 --- a/docs/deployment.md +++ b/docs/getting-started/deployment.md @@ -1,7 +1,7 @@ # Развертывание Документ описывает продакшен-запуск после разделения проекта на `backend`, `frontend` и `worker`. -Перед стартом заполните минимальный `.env` по [configuration.md](configuration.md). Полный справочник переменных лежит в [configuration/env-vars.md](configuration/env-vars.md); после первого входа большинство продуктовых настроек удобнее менять через Web App админку. +Перед стартом заполните минимальный `.env` по [configuration.md](configuration.md). Полный справочник переменных лежит в [configuration/env-vars.md](../configuration/env-vars.md); после первого входа большинство продуктовых настроек удобнее менять через Web App админку. ## Быстрый старт diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md index 091009a..c38ae63 100644 --- a/docs/getting-started/overview.md +++ b/docs/getting-started/overview.md @@ -10,17 +10,9 @@ Remnawave Minishop состоит из Telegram-бота, backend API, worker-п - **PostgreSQL** - пользователи, платежи, настройки, поддержка, промокоды и служебные данные. - **Redis** - FSM, кеши, rate limit, очередь вебхуков и distributed locks. -## Сценарии - -- пользователь открывает Mini App, видит подписку и оплачивает тариф; -- платежный провайдер отправляет webhook в backend; -- worker применяет фоновые задачи и синхронизацию; -- Remnawave Panel хранит пользователя, подписку и ссылку подключения; -- администратор управляет тарифами, поддержкой, пользователями и настройками через админку. - ## Куда идти дальше - [Установка](setup.md) - базовый запуск через Compose. -- [Развертывание](../deployment.md) - Docker Compose, Caddy, Nginx, Pangolin/Newt и запуск без обратного прокси. +- [Развертывание](deployment.md) - Docker Compose, Caddy, Nginx, Pangolin/Newt и запуск без обратного прокси. - [Архитектура](../architecture.md) - структура каталогов и сервисов. - [Mini App](../features/web-app.md) - публичный frontend, Telegram OAuth и инструкции установки. diff --git a/docs/getting-started/setup.md b/docs/getting-started/setup.md index 8c92264..18ed6ba 100644 --- a/docs/getting-started/setup.md +++ b/docs/getting-started/setup.md @@ -22,7 +22,7 @@ docker compose logs -f backend worker frontend ## Как выбрать Compose-вариант -Для продакшена по умолчанию берите [Caddy](../deployment.md#caddy-рекомендуемый-вариант): это самый короткий путь к публичному HTTPS без ручной раскладки сертификатов. +Для продакшена по умолчанию берите [Caddy](deployment.md#caddy-рекомендуемый-вариант): это самый короткий путь к публичному HTTPS без ручной раскладки сертификатов. ```bash cd deploy/examples/caddy @@ -31,11 +31,11 @@ nano .env docker compose up -d ``` -Остальные варианты описаны в [разделе развертывания](../deployment.md#готовые-папки-запуска): +Остальные варианты описаны в [разделе развертывания](deployment.md#готовые-папки-запуска): -- [Nginx](../deployment.md#nginx) - если у вас уже есть TLS-сертификаты и нужен Nginx в Docker-сети; -- [Pangolin/Newt](../deployment.md#pangolin--newt) - если нельзя открывать входящие порты на сервере приложения; -- [без обратного прокси](../deployment.md#без-обратного-прокси) - для локальной проверки или внешнего TLS-терминатора. +- [Nginx](deployment.md#nginx) - если у вас уже есть TLS-сертификаты и нужен Nginx в Docker-сети; +- [Pangolin/Newt](deployment.md#pangolin--newt) - если нельзя открывать входящие порты на сервере приложения; +- [без обратного прокси](deployment.md#без-обратного-прокси) - для локальной проверки или внешнего TLS-терминатора. ## После первого входа @@ -45,4 +45,4 @@ docker compose up -d 4. Проверьте инструкции подключения. 5. Сделайте тестовую покупку или пробную активацию. -Подробности: [настройка окружения](../configuration.md) и [развертывание](../deployment.md). +Подробности: [настройка окружения](configuration.md) и [развертывание](deployment.md). diff --git a/docs/index.md b/docs/index.md index f91f3b6..ff2637c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,29 +4,9 @@ Remnawave Minishop - Telegram-бот и Mini App для продажи и упр > Проект работает вместе с Remnawave Panel: панель хранит пользователей и подписки, а Minishop отвечает за Telegram, платежи, Mini App, тарифы и операционную админку. -## Быстрый старт - -- [Обзор](getting-started/overview.md) - архитектура, сервисы и основные сценарии. -- [Установка](getting-started/setup.md) - путь от `.env` до первого запуска. -- [Развертывание](deployment.md) - Docker Compose, Caddy, Nginx, Pangolin/Newt и запуск без обратного прокси. -- [Настройка платежей](features/payments.md) - включение провайдеров и проверка вебхуков. -- [Безопасность](configuration/security.md) - секреты, доступы и публичные URL. -- [Админ-панель](features/admin-panel.md) - пользователи, настройки, рассылки, поддержка и тарифы. -- [Миграции](migrations/index.md) - готовые сценарии переноса с других ботов. -- [Устранение неполадок](troubleshooting/issues.md) - быстрые проверки для частых проблем. - ## Ключевые возможности -- **Продажа подписок** - тарифы на срок и по трафику, докупки трафика, HWID-устройства, premium-сквады и Telegram Stars. +- **Продажа подписок** - тарифы на срок и по трафику, докупки трафика, HWID-устройства, [premium-сквады](features/tariffs.md#premium-сквады-и-отдельный-лимит) - **Жизненный цикл пользователей** - регистрация, пробный период, продление, синхронизация с панелью и предупреждения по трафику. - **Mini App** - личный кабинет, инструкции установки, Telegram OAuth, вход по email и публичные реферальные ссылки. - **Операционные инструменты** - админка, тикеты поддержки, промокоды, рассылки, логи и настройки поверх `.env`. - -## Справочник - -- [Переменные окружения](configuration/env-vars.md) -- [Развертывание](deployment.md) -- [Тарифы](features/tariffs.md) -- [Темы Web App](features/webapp-themes.md) -- [Миграции](migrations/index.md) -- [Миграция с remnawave-tg-shop](migrations/remnawave-tg-shop.md) diff --git a/docs/migrations/index.md b/docs/migrations/index.md index 8463a4e..501a37a 100644 --- a/docs/migrations/index.md +++ b/docs/migrations/index.md @@ -2,26 +2,6 @@ Этот раздел содержит готовые инструкции миграции в Remnawave Minishop из уже описанных источников. Каждая поддерживаемая миграция должна быть отдельным Markdown-файлом с конкретными шагами, ограничениями, командами и проверками. -Сейчас в документации есть только один готовый сценарий: - -| Источник | Поддерживаемый случай | Инструкция | +| Источник | Поддерживаемый случай | Документы | | --- | --- | --- | -| `remnawave-tg-shop` `v2.7.0` и близкие версии | Переезд старого stack/volume PostgreSQL на split-архитектуру Minishop `v3.4+`, обновление `.env`, запуск `migrate`, проверка обратного прокси | [Миграция с remnawave-tg-shop](remnawave-tg-shop.md) | - -## Что покрывает текущая миграция - -Инструкция для `remnawave-tg-shop` рассчитана на родственный стек, где заранее известны Docker volumes, контейнеры, схема БД и путь обновления: - -- перенос PostgreSQL volume `remnawave-tg-shop-db-data` в новый volume Minishop; -- создание новых пустых volumes `redis-data` и `shop-data`; -- перенос Caddy volumes при использовании Caddy-варианта; -- обновление переменных окружения, которые изменились после `v2.7.0`; -- запуск one-shot сервиса `migrate`; -- переход с одного upstream `remnawave-tg-shop:8000` на `backend:8080` и `frontend:80`; -- запуск через корневой compose или готовые примеры Docker Compose. - -## Что пока не описано - -Для других Telegram-ботов, самописных панелей и ручных таблиц готовой инструкции пока нет. Такие источники нельзя переносить по инструкции `remnawave-tg-shop`: у них могут отличаться таблицы пользователей, модель тарифов, статусы платежей, связь с Remnawave Panel, формат промокодов, рефералы и правила отката. - -Когда для конкретного источника появится проверенный сценарий, он должен быть добавлен в этот раздел отдельным файлом и отдельной строкой в таблице выше. +| [remnawave-tg-shop](https://github.com/kavore/remnawave-tg-shop/) | Полный перенос всех данных | [Инструкция](remnawave-tg-shop.md) | diff --git a/docs/migrations/remnawave-tg-shop.md b/docs/migrations/remnawave-tg-shop.md index b9c483d..df06349 100644 --- a/docs/migrations/remnawave-tg-shop.md +++ b/docs/migrations/remnawave-tg-shop.md @@ -131,7 +131,7 @@ docker compose \ | — | `REDIS_URL=redis://redis:6379/0` | Обязательна для воркера, очередей и rate-limit. По умолчанию в compose-файлах уже задана. | | — | `WEBAPP_SESSION_SECRET`, `WEBAPP_ENABLED`, `WEBAPP_SERVER_PORT`, `WEBAPP_THEMES_DIR`, `TARIFFS_CONFIG_PATH` | Новые настройки Web App / тарифного каталога. Безопасные дефолты есть в `.env.example`. | -Полный референс — [docs/configuration.md](../configuration.md). Скрипт миграции +Полный референс — [docs/getting-started/configuration.md](../getting-started/configuration.md). Скрипт миграции эти переменные **не правит** автоматически (только `POSTGRES_HOST`), потому что у каждой инсталляции свой шаблон `.env` с кастомными значениями. Лучше сравнить свой `.env` с `.env.example` глазами один раз, чем получить @@ -361,7 +361,7 @@ server { ``` Полные примеры (Caddy, Nginx, Newt/Pangolin и запуск без обратного прокси) — в -[docs/deployment.md](../deployment.md) и [docs/features/web-app.md](../features/web-app.md). Если раньше прокси указывал на +[docs/getting-started/deployment.md](../getting-started/deployment.md) и [docs/features/web-app.md](../features/web-app.md). Если раньше прокси указывал на `remnawave-tg-shop:8000` напрямую, после миграции нужно либо переключиться на `backend:8080` / `frontend:80`, либо использовать готовый Caddy/Nginx/Newt пример, который уже знает правильную маршрутизацию. diff --git a/docs/troubleshooting/issues.md b/docs/troubleshooting/issues.md index a055b9b..04d9172 100644 --- a/docs/troubleshooting/issues.md +++ b/docs/troubleshooting/issues.md @@ -30,4 +30,4 @@ - Посмотрите backend-логи. - Сверьте статус платежа в админке и кабинете провайдера. -Подробности: [логи](logs.md) и [развертывание](../deployment.md). +Подробности: [логи](logs.md) и [развертывание](../getting-started/deployment.md). diff --git a/docs/troubleshooting/logs.md b/docs/troubleshooting/logs.md index 7abfe25..8ba838d 100644 --- a/docs/troubleshooting/logs.md +++ b/docs/troubleshooting/logs.md @@ -101,4 +101,4 @@ docker compose up -d docker compose logs -f backend worker frontend ``` -См. также [проблемы](issues.md) и [развертывание](../deployment.md). +См. также [проблемы](issues.md) и [развертывание](../getting-started/deployment.md). diff --git a/docs/troubleshooting/maintenance.md b/docs/troubleshooting/maintenance.md new file mode 100644 index 0000000..b4502c7 --- /dev/null +++ b/docs/troubleshooting/maintenance.md @@ -0,0 +1,25 @@ +# Обслуживание + +Плановое обслуживание обычно сводится к обновлению образов, проверке миграций, логов и резервных копий PostgreSQL. + +## Обновление + +```bash +docker compose pull +docker compose up -d +docker compose logs -f migrate backend worker +``` + +## Резервная копия PostgreSQL + +```bash +docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB"' > backup.sql +``` + +## Проверки после работ + +- `docker compose ps` +- `docker compose logs -f backend worker frontend` +- `/healthz` на backend-домене +- вход в Mini App и админку +- тестовый платеж или тестовая активация