DenozordecandClaude Opus 5.5
06d767fde7
- README: главные возможности, галерея, быстрый старт, ссылки на документы - docs/features.md: гид по всем разделам с новыми скриншотами - docs/configuration.md: переменные окружения, права, роли, планировщик - 26 скриншотов нового дизайна на демо-данных (в т.ч. мобильные) - scripts/seed-demo.ts и scripts/docs-screenshots.mjs для пересъёмки Co-Authored-By: Claude Opus 5.5 <[email protected]>
129 lines
10 KiB
Markdown
129 lines
10 KiB
Markdown
# Настройка 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 секунд.
|