docs: обновить README, описать возможности и настройку, переснять скриншоты

- README: главные возможности, галерея, быстрый старт, ссылки на документы - docs/features.md: гид по всем разделам с новыми скриншотами - docs/configuration.md: переменные окружения, права, роли, планировщик - 26 скриншотов нового дизайна на демо-данных (в т.ч. мобильные) - scripts/seed-demo.ts и scripts/docs-screenshots.mjs для пересъёмки Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-07 02:42:04 +07:00
1 parent a26647a52d
commit 06d767fde7
@@ -0,0 +1,128 @@
+# Настройка VPS Tracker
+
+Всё, что настраивается переменными окружения, плюс как устроены авторизация, планировщик и хранение данных. Настройки, которые меняются в интерфейсе (валюта, Telegram, интервалы синка), описаны в [features.md](features.md).
+
+- [Переменные окружения](#переменные-окружения)
+- [Авторизация и права](#авторизация-и-права)
+- [Пространства](#пространства)
+- [Планировщик](#планировщик)
+- [Блокировки и GeoIP](#блокировки-и-geoip)
+- [Хранение данных и миграции](#хранение-данных-и-миграции)
+- [Безопасность](#безопасность)
+
+---
+
+## Переменные окружения
+
+### Основные
+
+| Переменная | По умолчанию | Назначение |
+|---|---|---|
+| `PORT` | `3001` | Порт HTTP-сервера |
+| `DB_PATH` | `<cwd>/data/vps-tracker.db` (в Docker — `/app/data/vps-tracker.db`) | Путь к файлу SQLite |
+| `LOG_LEVEL` | `info` | Уровень логов Fastify (`debug`, `warn`…) |
+| `NODE_ENV` | — | `production` включает доверие к прокси и требует явных секретов |
+| `TRUST_PROXY` | `1` в production | Доверять `X-Forwarded-For` (нужно за Traefik/nginx для реального IP клиента) |
+| `BACKUP_BODY_LIMIT_BYTES` | `104857600` (100 МБ) | Максимальный размер загружаемого бэкапа |
+
+### Авторизация (auth-portal)
+
+| Переменная | По умолчанию | Назначение |
+|---|---|---|
+| `AUTH_REQUIRED` | `false` | `true` — все `/api/*` требуют JWT портала |
+| `AUTH_JWT_SECRET` (или `JWT_SECRET`) | dev-секрет вне production | Секрет подписи JWT (обязателен при `AUTH_REQUIRED=true`, ≥ 8 символов) |
+| `AUTH_ISSUER` | `https://auth.shnt.top` | Ожидаемый `iss` в токене |
+| `AUTH_PORTAL_URL` | `http://localhost:5175` | URL портала: вход, каталог пользователей, аудит |
+| `AUTH_AUDIT_INGEST_SECRET` | — | Секрет для отправки событий журнала изменений в аудит портала |
+| `VPS_MAIN_SPACE_OWNER_USER_ID` | — | Пользователь портала, которого назначить владельцем «Основного» пространства |
+
+### Блокировки и GeoIP
+
+| Переменная | По умолчанию | Назначение |
+|---|---|---|
+| `CENSORCHECK_INGEST_SECRET` | — | Секрет HMAC-токенов, которыми скрипты отправляют результаты (общий для блокировок и GeoIP) |
+| `CENSORCHECK_PUBLIC_URL` | — | Публичный URL, который подставляется в команды `curl …/cc`, `…/ic` |
+| `CENSORCHECK_RATE_LIMIT` | включён | `0` — отключить rate limit на приёме результатов |
+| `VPS_LAUNCHER_DOMAIN` | — | (Traefik-compose) короткий домен для launcher-скриптов |
+
+---
+
+## Авторизация и права
+
+По умолчанию (`AUTH_REQUIRED=false`) авторизации нет — удобно для домашней установки за VPN. Для команды включите SSO через auth-portal: пользователь входит на портале, приложение проверяет JWT и права.
+
+Токен должен содержать приложение `vps` в `apps`, иначе — 403. Права имеют вид `vps:<раздел>:<read|write|admin>`; `write` включает `read`, `admin` включает оба.
+
+| Раздел | Чтение | Запись |
+|---|---|---|
+| Дашборд и всё прочее | `vps:dashboard:read` | — |
+| VPS, проекты, схема, данные, блокировки, GeoIP | `vps:vps:read` | `vps:vps:write` |
+| Хостеры и аккаунты | `vps:accounts:read` | `vps:accounts:write` |
+| Платежи, баланс, курсы | `vps:payments:read` | `vps:payments:write` |
+| Синхронизация | `vps:sync:write` | `vps:sync:write` |
+| Настройки, журнал изменений, уведомления, бэкап | `vps:settings:admin` | `vps:settings:admin` |
+
+**Глобальный администратор** — пользователь с `is_admin` в токене или правом `vps:spaces:admin`. Только он может скачивать и восстанавливать бэкап и файл БД и запускать legacy-миграцию: эти операции затрагивают все пространства и содержат учётные данные API.
+
+Публичные (без JWT) эндпоинты: `/health`, `/ready`, `/api/auth/config`, launcher-скрипты `/cc*`, `/ic*` и приём результатов `/api/integrations/{censorcheck,ipregion}` (защищены своим HMAC-токеном), `/api/integrations/cfdm/*` (токен интеграции).
+
+---
+
+## Пространства
+
+Каждая запись (VPS, хостер, платёж, настройки…) принадлежит пространству. Клиент выбирает пространство заголовком `X-Space-Id`; без него — «Основное».
+
+| Роль | Может |
+|---|---|
+| **viewer** | смотреть |
+| **member** | менять VPS, проекты, схемы, платежи, баланс, хостеров и аккаунты, запускать синк |
+| **admin** | + настройки пространства, участники, шаринг VPS |
+| **owner** | + передача владения, удаление пространства |
+
+Права портала и роль в пространстве проверяются **обе**: для записи платежа нужны и `vps:payments:write`, и роль не ниже member.
+
+Синхронизация, уведомления (свой Telegram/webhook), uptime-проверки и CFDM работают отдельно для каждого пространства.
+
+---
+
+## Планировщик
+
+Запускается вместе с сервером и перезапускается при сохранении настроек.
+
+| Задача | Интервал | Условие |
+|---|---|---|
+| Синк VPS, платежей и баланса | настройка, ≥ 15 мин (по умолчанию 60) | включён автосинк |
+| Синк тарифов | настройка, ≥ 60 мин (по умолчанию 1440) | включён автосинк |
+| Напоминания об оплате | настройка, ≥ 15 мин (по умолчанию 60) | всегда |
+| Uptime-проверки | настройка, ≥ 1 мин (по умолчанию 5) | у VPS включён мониторинг |
+| Pull доменов из CFDM | 15 мин | интеграция включена, есть URL и токен |
+| Очистка журналов | раз в сутки и при старте | всегда |
+
+Таймеры тикают с самым частым интервалом среди пространств, но каждое пространство выполняется по своему. Если предыдущий прогон задачи ещё идёт, тик пропускается. Ручной и плановый синк одного аккаунта не выполняются одновременно (второй получает `409`).
+
+---
+
+## Блокировки и GeoIP
+
+1. Задайте `CENSORCHECK_INGEST_SECRET` (длинная случайная строка) и `CENSORCHECK_PUBLIC_URL` (например `https://vt.example.com`).
+2. За Traefik используйте отдельный короткий хост `VPS_LAUNCHER_DOMAIN` — см. [deploy-traefik.md](deploy-traefik.md).
+3. На сервере: `curl -fsSL https://vt.example.com/cc | bash` (блокировки) или `…/ic | bash` (GeoIP). Каждый запуск получает свежий токен на 20 минут.
+
+Скрипты — закреплённые версии [vernette/censorcheck](https://github.com/vernette/censorcheck) и [vernette/ipregion](https://github.com/vernette/ipregion) (MIT) в `apps/api/scripts/`.
+
+---
+
+## Хранение данных и миграции
+
+- Одна база SQLite (WAL, внешние ключи включены). Бэкап — копия файла `vps-tracker.db` или выгрузка из интерфейса.
+- При старте схема **доводится автоматически**: создаются недостающие таблицы и колонки, данные старых версий (например, URL BILLmanager из аккаунтов) переносятся на новое место. Отдельно запускать миграции не нужно.
+- Ретеншн: `notification_log` и `sync_log` — 90 дней, `vps_health_checks` — 30 дней; синки в статусе `running` старше часа помечаются ошибкой.
+
+---
+
+## Безопасность
+
+- Включайте `AUTH_REQUIRED=true`, если приложение доступно не только вам; иначе любой с доступом к порту видит и меняет данные.
+- Учётные данные API хранятся в БД открытым текстом (их нужно отправлять хостеру) и **не отдаются** в API/интерфейс — только признак «задано» и логин. Храните файл БД и бэкапы как секрет.
+- `/api/rates-proxy` запрашивает только URL курсов, сохранённый в настройках, — произвольные адреса не проксируются.
+- Запросы к Telegram и webhook ограничены таймаутом 10 секунд.