From 11048a6ed83315e381b18d115c0fd4271e2e7446 Mon Sep 17 00:00:00 2001
From: 3252a8 <3252a8@proton.me>
Date: Tue, 26 May 2026 23:31:04 +0300
Subject: [PATCH] docs: refactor docs structure
---
README.md | 7 +-
deploy/examples/README.md | 10 +-
deploy/examples/caddy/README.md | 2 +-
deploy/examples/newt/README.md | 2 +-
deploy/examples/nginx/README.md | 2 +-
deploy/examples/nginx/ssl/README.md | 2 +-
deploy/examples/no-proxy/README.md | 2 +-
docs-site/astro.config.mjs | 25 ++---
docs-site/scripts/sync-docs.mjs | 15 ++-
docs-site/src/components/Header.astro | 104 ++++++++++++++++++++
docs-site/src/styles/custom.css | 8 ++
docs/administration/maintenance.md | 59 -----------
docs/administration/users.md | 19 ----
docs/configuration/security.md | 2 +-
docs/features/admin-panel.md | 9 +-
docs/features/web-app.md | 12 +--
docs/{ => getting-started}/configuration.md | 12 +--
docs/{ => getting-started}/deployment.md | 2 +-
docs/getting-started/overview.md | 10 +-
docs/getting-started/setup.md | 12 +--
docs/index.md | 22 +----
docs/migrations/index.md | 24 +----
docs/migrations/remnawave-tg-shop.md | 4 +-
docs/troubleshooting/issues.md | 2 +-
docs/troubleshooting/logs.md | 2 +-
docs/troubleshooting/maintenance.md | 25 +++++
26 files changed, 203 insertions(+), 192 deletions(-)
create mode 100644 docs-site/src/components/Header.astro
delete mode 100644 docs/administration/maintenance.md
delete mode 100644 docs/administration/users.md
rename docs/{ => getting-started}/configuration.md (92%)
rename docs/{ => getting-started}/deployment.md (98%)
create mode 100644 docs/troubleshooting/maintenance.md
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: \'\'',
' 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 и админку
+- тестовый платеж или тестовая активация
\'',
' 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