# Настройка VPS Tracker Всё, что настраивается переменными окружения, плюс как устроены авторизация, планировщик и хранение данных. Настройки, которые меняются в интерфейсе (валюта, Telegram, интервалы синка), описаны в [features.md](features.md). - [Переменные окружения](#переменные-окружения) - [Авторизация и права](#авторизация-и-права) - [Пространства](#пространства) - [Планировщик](#планировщик) - [Блокировки и GeoIP](#блокировки-и-geoip) - [Хранение данных и миграции](#хранение-данных-и-миграции) - [Безопасность](#безопасность) --- ## Переменные окружения ### Основные | Переменная | По умолчанию | Назначение | |---|---|---| | `PORT` | `3001` | Порт HTTP-сервера | | `DB_PATH` | `/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:<раздел>:`; `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 секунд.