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 секунд.
@@ -0,0 +1,244 @@
+# Возможности VPS Tracker
+
+Гид по всем разделам интерфейса. Скриншоты — на демо-данных (вымышленные хостеры, IP из RFC 5737).
+
+**Содержание**
+
+1. [Дашборд](#дашборд)
+2. [VPS и карточка сервера](#vps-и-карточка-сервера)
+3. [Проекты](#проекты)
+4. [Схема инфраструктуры](#схема-инфраструктуры)
+5. [Хостеры, аккаунты и синхронизация](#хостеры-аккаунты-и-синхронизация)
+6. [Активные тарифы](#активные-тарифы)
+7. [Платежи, баланс и продления](#платежи-баланс-и-продления)
+8. [Отчёты и ресурсы](#отчёты-и-ресурсы)
+9. [Статус блокировок](#статус-блокировок)
+10. [GeoIP](#geoip)
+11. [Уведомления](#уведомления)
+12. [Пространства, пользователи и роли](#пространства-пользователи-и-роли)
+13. [Журналы](#журналы)
+14. [Настройки, интеграции и бэкапы](#настройки-интеграции-и-бэкапы)
+
+---
+
+## Дашборд
+
+![Дашборд](screenshots/dashboard.png)
+
+Одна страница, чтобы понять, всё ли в порядке:
+
+- **KPI**: активные VPS, расход в месяц (в базовой валюте), суммарный баланс у хостеров по API, **запас дней** — на сколько хватит денег при текущем расходе, сколько VPS истекает в ближайшие 7 дней, число проблем.
+- **Баннер «Требуется внимание»** и кнопка «Внимание» в шапке собирают проблемы инвентаря: истекающая оплата, низкий баланс, давно не синхронизированные аккаунты, расхождение баланса API и журнала.
+- **Быстрые действия** — переходы в частые разделы (можно скрыть в настройках).
+- **Графики** платежей и расходов по месяцам и таблица «Здоровье инвентаря» с CSV-экспортом.
+
+![Графики и здоровье инвентаря](screenshots/dashboard-charts.png)
+
+Все суммы в разных валютах пересчитываются в базовую: по курсу хостера (если задан в карточке хостера) или по курсам из URL в настройках (формат ЦБ РФ `cbr-xml-daily` или `{ base, rates }`).
+
+---
+
+## VPS и карточка сервера
+
+![Список VPS](screenshots/vps.png)
+
+- Таблица с поиском по IP, DNS, проекту, назначению и ОС; фильтры, настраиваемые колонки (вид), сортировка.
+- Для каждого сервера: IP/IPv6 и доп. адреса, домены (из CFDM), аккаунт и хостер, страна/город/ДЦ с флагом, CPU/RAM/диск, проект, статус, тариф (дневной/месячный), оплачено до.
+- **Массовые действия**: выделите несколько VPS — сменить статус или проект, удалить.
+- **Произвольные поля** (настраиваются в *Настройки → Общие*) появляются в таблице и форме.
+- Поля, изменённые вручную, запоминаются как «пользовательские» — синхронизация с хостером их не перезаписывает.
+
+Карточка сервера разбита на вкладки: **Обзор** (сеть и ресурсы), **Финансы** (тариф, дата оплаты и связанные платежи), **Заметки**, **Синк** (что пришло от хостера).
+
+| | |
+|---|---|
+| ![Карточка VPS — обзор](screenshots/vps-detail.png) | ![Карточка VPS — финансы](screenshots/vps-detail-finance.png) |
+
+**Дата «оплачено до»** считается автоматически: из поля хостера, а для дневного тарифа — из баланса аккаунта и суточного списания; прямые платежи за VPS продлевают дату.
+
+**Uptime-мониторинг**: для VPS с включённым мониторингом раз в N минут (по умолчанию 5) проверяется TCP-доступность SSH-порта. Переходы «упал/поднялся» попадают в уведомления и историю проверок.
+
+---
+
+## Проекты
+
+![Проекты](screenshots/projects.png)
+
+Группировка серверов по проектам (цвет, заметки). Для каждого — количество VPS, расход в месяц и суммарные ресурсы. Карточка проекта показывает его VPS и быстрые переходы в отчёты.
+
+![Карточка проекта](screenshots/project-detail.png)
+
+Проект можно указать прямо в форме VPS: существующий находится без учёта регистра (в том числе кириллица), новый создаётся автоматически.
+
+---
+
+## Схема инфраструктуры
+
+![Схема инфраструктуры](screenshots/topology.png)
+
+Редактор топологии на React Flow:
+
+- узлы **VPS** (с флагом, IP, ресурсами, ценой и статусом uptime), фигуры, заметки, группы;
+- **связи** с типом (сеть, зависимость, туннель, VPN, синхронизация, произвольная), направлением, стилем линии, подписью, протоколом и IP концов туннеля;
+- **сервисы CFDM** — отдельные узлы с членством VPS (для балансировки/HA);
+- несколько схем во вкладках, блокировка от случайных правок, экспорт в PNG, автосохранение.
+
+---
+
+## Хостеры, аккаунты и синхронизация
+
+| | |
+|---|---|
+| ![Хостеры](screenshots/providers.png) | ![Аккаунты хостеров](screenshots/accounts.png) |
+
+**Хостер** — компания (сайт, базовая валюта, курсы USD/EUR для пересчёта) и **тип API** с URL биллинга — один на хостера.
+**Аккаунт** — ваш логин у хостера: учётные данные API, режим оплаты (ежедневно/ежемесячно), порог низкого баланса. Пароли API в интерфейс не возвращаются — видно только, что они заданы, и логин.
+
+Поддерживаемые API:
+
+| Тип | Что нужно в аккаунте | Что синхронизируется |
+|---|---|---|
+| **BILLmanager 6** | логин и пароль API | VPS, платежи, баланс, тарифы `vds.order` по всем ДЦ |
+| **4VPS** | Panel ID и API Key | VPS, баланс, тарифы |
+| **Маклауд / VDSina** (userapi) | API Token | VPS, операции, баланс, тарифы |
+| **Veesp** | email и пароль client area | VPS, счета, баланс, тарифы |
+| **RuVDS** | API-токен из ЛК | VPS, платежи, баланс, тарифы |
+
+Для разных BILLmanager-хостеров есть **профили** с особенностями их API (FirstByte, IHOR, DataCheap, Serv.host, WaiCore, LandVPS, Cloudrix…) — новый добавляется одним файлом, см. [profiles/README.md](../apps/api/src/services/billmanager/profiles/README.md).
+
+Синхронизация запускается кнопкой на аккаунте («Синхронизировать» / «Синхронизировать все») или по расписанию (*Настройки → Синхронизация*: интервал синка VPS и платежей — от 15 минут, тарифов — от 60 минут). Повторный запуск во время идущего синка того же аккаунта отклоняется. Каждый запуск пишется в [журнал синка](#журналы).
+
+---
+
+## Активные тарифы
+
+![Активные тарифы](screenshots/tariffs.png)
+
+Прайс-листы хостеров, загруженные через API: ресурсы, цена, ДЦ, доступность к заказу. Удобно сравнивать хостеров и замечать новые тарифы — о них приходит уведомление. Если загрузка прайс-листа не удалась, сохранённый список не стирается.
+
+---
+
+## Платежи, баланс и продления
+
+![Платежи](screenshots/payments.png)
+
+- **Платежи** — пополнения баланса хостера и прямые оплаты VPS (привязка к аккаунту и/или серверу необязательна), итоги по валютам, импорт из синка без дублей.
+- **Баланс и списания** — журнал движений по балансу (приход/расход), сводка и чистый остаток.
+- **Продления** — календарь ближайших оплат на 7/30/90 дней и стоимость продлений.
+
+| | |
+|---|---|
+| ![Баланс и списания](screenshots/balance.png) | ![Продления](screenshots/renewals.png) |
+
+---
+
+## Отчёты и ресурсы
+
+![Отчёты](screenshots/reports.png)
+
+- **Отчёты**: расход в месяц по проектам и хостерам, платежи по типам, фильтр по проекту и периоду, экспорт в CSV.
+- **Ресурсы**: суммарные vCPU/RAM/диск активных VPS и распределение по хостерам.
+
+![Ресурсы](screenshots/resources.png)
+
+---
+
+## Статус блокировок
+
+![Статус блокировок](screenshots/blocking.png)
+
+Проверка доступности популярных сервисов **с самого VPS** (через [censorcheck](https://github.com/vernette/censorcheck)): доступен, заблокирован, отказ (403), редирект, таймаут. Результат автоматически привязывается к VPS по IP; есть история прогонов и группировка по VPS или по сервису.
+
+Запуск на сервере — одна команда (скрипт ставит недостающие `jq`/`dig`, показывает прогресс и отправляет результат с одноразовым токеном):
+
+```bash
+curl -fsSL https://vt.example.com/cc | bash                     # разовая проверка
+curl -fsSL https://vt.example.com/cc | bash -s -- --daily       # раз в сутки (cron)
+curl -fsSL https://vt.example.com/cc | bash -s -- --remove-daily
+```
+
+**MikroTik (RouterOS 7.22+)** — пробы идут через указанный исходящий IP:
+
+```
+:global "vt-srcIp" "1.2.3.4"; /tool fetch url="https://vt.example.com/cc.rsc" dst-path=vt-cc.rsc; /import file-name=vt-cc.rsc
+```
+
+(`?daily=1` — ежедневный scheduler, `?remove=daily` — удалить.) Кнопки «Скопировать команду», «Раз в день», «MikroTik» на странице подставляют ваш домен. Нужны `CENSORCHECK_INGEST_SECRET` и `CENSORCHECK_PUBLIC_URL` — см. [configuration.md](configuration.md#блокировки-и-geoip).
+
+---
+
+## GeoIP
+
+![GeoIP](screenshots/geo.png)
+
+Какую страну видят у вашего IP GeoIP-базы (MaxMind, RIPE, ipinfo, Cloudflare…) и сервисы (Google, YouTube, Netflix, ChatGPT…), включая CDN, — через [ipregion](https://github.com/vernette/ipregion). Матрица VPS × сервис, переключение «по VPS / по сервису», подсветка расхождений, история.
+
+Запуск так же, как у блокировок: `curl -fsSL https://vt.example.com/ic | bash` (`--daily`, `--remove-daily`), для MikroTik — `ic.rsc`.
+
+---
+
+## Уведомления
+
+![Настройки уведомлений](screenshots/settings-notifications.png)
+
+Каналы: **Telegram** (Chat ID, несколько чатов через запятую, топики форума через Thread ID, свой Bot API URL для прокси) и **webhook** (POST JSON). Кнопка «Тест» проверяет настройки и подсказывает типичные ошибки (бот не в чате, неверный токен, нет топика).
+
+| Событие | Когда | Повтор |
+|---|---|---|
+| Истекает оплата | VPS с оплатой в ближайшие 7 дней | не чаще раза в сутки для того же набора |
+| Низкий баланс | баланс аккаунта по API ниже порога | раз в сутки |
+| Дайджест синка | после планового синка, если что-то изменилось | при новых изменениях |
+| Новые тарифы | у хостера появились тарифы | при новом наборе |
+| VPS недоступен / восстановлен | переход статуса uptime-проверки | каждый переход |
+
+Каждое событие включается отдельно. Все отправки (и пропуски-дубли) видны в журнале уведомлений. Длинные сообщения обрезаются по строкам под лимит Telegram, имена из API экранируются.
+
+---
+
+## Пространства, пользователи и роли
+
+При включённой авторизации (`AUTH_REQUIRED=true`) вход идёт через **auth-portal** (JWT), а данные разделены на **пространства**:
+
+- у каждого пользователя есть личное пространство; есть общее «Основное» и можно создавать командные;
+- роли в пространстве: **owner → admin → member → viewer**. Viewer только смотрит; member меняет VPS, платежи, хостеров, аккаунты и запускает синк; admin управляет настройками и участниками;
+- **шаринг VPS**: сервер можно показать в другом пространстве (чтение/запись) или передать целиком;
+- удалённые пространства попадают в корзину и восстанавливаются;
+- права портала (`vps:<раздел>:read|write|admin`) ограничивают разделы поверх ролей — см. [configuration.md](configuration.md#авторизация-и-права).
+
+Синхронизация, уведомления, uptime и интеграции работают отдельно для каждого пространства.
+
+---
+
+## Журналы
+
+| | |
+|---|---|
+| ![Журнал синка](screenshots/sync-journal.png) | ![Журнал изменений](screenshots/audit.png) |
+
+- **Журнал синка** — каждый запуск по аккаунтам: время, длительность, статус, что изменилось или текст ошибки.
+- **Журнал изменений** — кто, когда и что поменял (создание/изменение/удаление) с diff полей; лента или таблица. При настроенном портале события дублируются в его аудит.
+
+Старые записи журналов удаляются автоматически (уведомления и синк — 90 дней, uptime-проверки — 30 дней).
+
+---
+
+## Настройки, интеграции и бэкапы
+
+| | |
+|---|---|
+| ![Общие настройки](screenshots/settings.png) | ![Синхронизация](screenshots/settings-sync.png) |
+
+- **Общие** — быстрые действия на дашборде, базовая валюта, URL курсов и автоконвертация, произвольные поля VPS, **бэкап/восстановление** (JSON или файл БД).
+- **Синхронизация** — автосинк и интервалы.
+- **Уведомления** — Telegram, webhook и выбор событий.
+- **Интеграции** — **App Switcher** (переключатель приложений в шапке) и **CF Domain Manager (CFDM)**: домены и балансировщики из CFDM подтягиваются каждые 15 минут и показываются у VPS и на схеме.
+
+![Интеграции](screenshots/settings-integrations.png)
+
+Работает и на телефоне — меню сворачивается, таблицы прокручиваются:
+
+<p align="center">
+  <img src="screenshots/mobile-dashboard.png" width="260" alt="Дашборд на телефоне">
+  &nbsp;
+  <img src="screenshots/mobile-vps.png" width="260" alt="VPS на телефоне">
+</p>
@@ -0,0 +1,33 @@
+# Скриншоты
+
+Скриншоты в README и `docs/` сняты на **демо-данных**: хостеры вымышленные (Nordhost, Aurora Cloud, Baltic VDS, Pixel Hosting), IP — из документационных диапазонов RFC 5737 (`203.0.113.0/24`, `198.51.100.0/24`, `192.0.2.0/24`), домены — `*.example.net`.
+
+## Как пересоздать
+
+Нужны собранный фронтенд и Chrome/Chromium/Edge.
+
+```bash
+pnpm install
+pnpm --filter web build
+pnpm --filter @cfdm/shared build && pnpm --filter @cfdm/db build
+```
+
+1. Поднять демо на пустой базе (порт 3101, без планировщика):
+
+   ```bash
+   cd apps/api
+   rm -f ../../data/demo.db*
+   DB_PATH=../../data/demo.db VITEST=1 LOG_LEVEL=warn npx tsx scripts/seed-demo.ts --serve
+   ```
+
+2. В другом терминале из корня репозитория снять все экраны:
+
+   ```bash
+   node apps/api/scripts/docs-screenshots.mjs docs/screenshots
+   ```
+
+   Путь к браузеру — переменная `CHROME`, адрес демо — `BASE`.
+
+Список экранов и их параметры (размер окна, клик по вкладке, прокрутка, мобильный режим) — в начале [`docs-screenshots.mjs`](../../apps/api/scripts/docs-screenshots.mjs). Демо-данные — [`seed-demo.ts`](../../apps/api/scripts/seed-demo.ts).
+
+Файлы в репозитории дополнительно ужаты до 256-цветной палитры (тёмная тема переносит это без видимых потерь), чтобы README грузился быстрее.