vps-control/README_RU.md

VPS Control

Ориентированная на production-среду система мониторинга и ограниченного управления VPS-хостами на Debian и Ubuntu.

Небольшой демон на Rust предоставляет семантические системные API через приватную сеть WireGuard или TLS. Отдельно размещаемая управляющая часть на Go + React предоставляет инвентаризацию серверов, историю, RBAC и неизменяемый журнал аудита.

Браузер ──HTTPS──> React/nginx ──> Go API ──приватная сеть──> Rust agent
                                         │
                                     PostgreSQL
                                         ▲
                            Grafana (Prometheus/Loki APIs)

В проекте намеренно отсутствует удалённый shell-доступ.

По умолчанию агент слушает 127.0.0.1:9105, считывает учётные данные из файлов, управляемых root, запускается от имени непривилегированного системного пользователя и ограничивается средствами управления ресурсами systemd.

Быстрый старт

Управляющая часть:

cp control-plane/.env.example control-plane/.env
# Заполните все значения CHANGE_ME и создайте файлы с секретами, описанные ниже.
docker compose -f control-plane/docker-compose.yml up -d --build

Сборка агента для разработки:

cargo build --manifest-path agent/Cargo.toml --release
sudo install -m 0755 agent/target/release/vps-agent /usr/local/bin/vps-agent
sudo install -m 0640 examples/agent-config.toml /etc/vps-agent/config.toml

Для установки релизной версии скачайте скрипт управления жизненным циклом и файл контрольной суммы как отдельные файлы, проверьте их с помощью sha256sum -c, после чего выполните:

sudo ./scripts/vps-agentctl.sh install --version v0.1.0

См. документацию по развёртыванию, безопасности, а также руководства по агенту и управляющей части.

Структура репозитория

agent/                 VPS-демон на Rust и файлы для упаковки systemd-службы
control-plane/backend/ Go API, хранение данных в PostgreSQL, аутентификация/RBAC/аудит
control-plane/frontend Панель управления на React/Vite
docs/                  архитектура, модель угроз, эксплуатация, разработка
scripts/               безопасная утилита управления жизненным циклом агента
examples/              примеры конфигураций, готовых к развёртыванию

Безопасность и совместимость

Поддерживаемые системы:

• Debian 12+
• Ubuntu 22.04
• Ubuntu 24.04

Требуется systemd.

Держите агент за WireGuard либо привязывайте его только к localhost/reverse tunnel.

Никогда не привязывайте агент к публичному сетевому интерфейсу без:

• TLS;
• настроенной политики firewall на хосте;
• явной оценки связанных с этим рисков.

Перед включением операций, изменяющих состояние системы, прочитайте docs/security.md.

Текущий объём функциональности v1 поддерживает операции только для чтения для:

• системной информации;
• сетевой конфигурации;
• сетевых сокетов;
• firewall;
• Fail2Ban;
• WireGuard;
• сервисов из явно разрешённого списка.

Также поддерживаются ручные операции Fail2Ban ban/unban и перезапуск разрешённых сервисов. Все такие действия записываются в журнал аудита.

Управляемое изменение правил firewall и настройка L7 rate limit намеренно отложены до появления отдельного привилегированного helper-процесса, который сможет гарантировать безопасный откат изменений даже при сбое или аварийном завершении.

Дополнительные observability-endpoint'ы позволяют backend-компоненту выступать в роли ограниченного источника метрик, совместимого с Prometheus, и источника логов, совместимого с Loki, для Grafana.

Grafana никогда не получает адрес агента или его учётные данные.

Разработка

См. docs/development.md.

Команды, совместимые с CI, также перечислены в AGENTS.md.

Репозиторий распространяется по лицензии Apache-2.0.