vps-tracker/docs/configuration.md

Настройка VPS Tracker

Всё, что настраивается переменными окружения, плюс как устроены авторизация, планировщик и хранение данных. Настройки, которые меняются в интерфейсе (валюта, Telegram, интервалы синка), описаны в features.md.

• Переменные окружения
• Авторизация и права
• Пространства
• Планировщик
• Блокировки и 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.
3. На сервере: curl -fsSL https://vt.example.com/cc | bash (блокировки) или …/ic | bash (GeoIP). Каждый запуск получает свежий токен на 20 минут.

Скрипты — закреплённые версии vernette/censorcheck и 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 секунд.