From c0e8edaab1589547faa2bcfa0ab6c8d677950d63 Mon Sep 17 00:00:00 2001 From: host Date: Sat, 25 Jul 2026 03:38:35 +0300 Subject: [PATCH] =?UTF-8?q?=D0=9E=D0=B1=D0=BD=D0=BE=D0=B2=D0=BB=D0=B5?= =?UTF-8?q?=D0=BD=D0=B8=D0=B5=20=D1=84=D0=B0=D0=B9=D0=BB=D0=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 49 +++++++++++++++++++++++-------------------------- 1 file changed, 23 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 9836cc1..6f31977 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ Self-hosted панель для мульти-тенантного управле Proxmox VE через API. Backend — FastAPI (Python), frontend — React (Vite), хранилище — Postgres. Клиенты регистрируются, выбирают шаблон и разворачивают себе VM или LXC-контейнер одной кнопкой; -дальше могут запускать/останавливать/перезагружать/удалять сервер и открывать веб-консоль. +дальше могут запускать/останавливать/перезагружать/удалять сервер и управлять им через SSH. Первый зарегистрированный пользователь автоматически становится администратором и управляет шаблонами и списком пользователей. @@ -14,7 +14,7 @@ Proxmox VE через API. Backend — FastAPI (Python), frontend — React (Vit - Шаблоны VPS: админ создаёт тарифы, привязанные к VM-шаблону (клонирование) или CT-шаблону LXC - Клиент создаёт инстанс из шаблона — панель сама берёт свободный VMID и вызывает Proxmox API - Действия: start / stop / shutdown / reboot / delete -- Веб-консоль через noVNC (websocket-прокси на backend, noVNC устанавливается из npm) +- Управление через SSH — IP-адрес инстанса виден в дашборде, логин/пароль задаются через cloud-init - Проверка владельца во всех эндпоинтах — клиент не может управлять чужими VM - Всё через docker-compose, разворачивается как Custom App в TrueNAS SCALE - Healthcheck-эндпоинты (`/health`, `/health/ready`) и Docker-healthcheck у всех сервисов @@ -27,6 +27,7 @@ Proxmox VE через API. Backend — FastAPI (Python), frontend — React (Vit - Очереди задач (Celery/Redis) — создание VPS идёт в фоне через `BackgroundTasks` FastAPI, для нескольких одновременных заявок этого достаточно, для десятков в секунду — уже нет - Управления сетью/IP-пулами (LXC получает адрес по DHCP, для VM выдаётся из клонированного шаблона) +- Веб-консоли (VNC) — для доступа к виртуальным машинам используйте SSH - Alembic-миграций (сейчас `create_all()` — для прода рекомендуется добавить) ## 1. Подготовка Proxmox @@ -34,11 +35,10 @@ Proxmox VE через API. Backend — FastAPI (Python), frontend — React (Vit ### API-токен Datacenter → Permissions → API Tokens → добавить токен для пользователя (например `root@pam`, -в проде лучше завести отдельного пользователя с ролью `PVEVMAdmin`/кастомной ролью и без -"Privilege Separation", если хотите, чтобы токен имел те же права, что и юзер). +в проде лучше завести отдельного пользователя с минимально нужными правами). Права, которые нужны панели: создание/клонирование/удаление VM и CT, управление питанием, -`VM.Console` для консоли, `Sys.Audit` для чтения статусов задач. +`Sys.Audit` для чтения статусов задач. ### Шаблон для VM @@ -81,8 +81,6 @@ ALLOW_ORIGINS=https://panel.example.com ```bash # Установите обязательные переменные: export POSTGRES_PASSWORD=$(openssl rand -hex 16) -# (опционально) задайте порог логирования: -# export LOG_LEVEL=DEBUG docker compose up -d --build ``` @@ -102,25 +100,21 @@ TrueNAS SCALE умеет запускать произвольные Docker-пр 1. Скопируйте папку проекта на TrueNAS (например, в датасет `/mnt/tank/apps/vps-panel`). 2. Заполните `backend/.env`, как описано выше. 3. Из этой директории выполните `docker compose up -d --build` через shell TrueNAS - (System Settings → Shell, либо через SSH), либо оформите как Custom App, указав тот же - `docker-compose.yml` в интерфейсе TrueNAS Apps. + (System Settings → Shell, либо через SSH), либо оформите как Custom App. 4. Откройте порт 5173 наружу через reverse-proxy (например, встроенный в TrueNAS, либо отдельный Nginx Proxy Manager), если панель должна быть доступна клиентам извне. -## Консоль VNC — важное примечание +## Доступ к виртуальным машинам -Веб-консоль реализована как websocket-прокси: backend получает от Proxmox тикет -(`vncproxy`) и порт, затем проксирует бинарный поток на `/api/console/ws`, а фронтенд -рисует экран через **noVNC, установленный как npm-пакет** (`@novnc/novnc`, копируется -в `/novnc/` внутри nginx-контейнера на этапе сборки). +IP-адрес инстанса виден в дашборде и в карточке инстанса (получается через +QEMU Guest Agent или LXC-интерфейсы). Для доступа: -Proxmox исторически ожидает на `vncwebsocket` либо cookie-тикет (`PVEAuthCookie`) из обычной -браузерной сессии, либо (в более новых версиях) заголовок `Authorization: PVEAPIToken=...` — -в коде (`backend/app/routers/console.py`) используется второй вариант. Если на вашей версии -Proxmox консоль не подключается, скорее всего понадобится либо обновить PVE, либо переключить -аутентификацию панели на логин/пароль с получением `PVEAuthCookie` вместо API-токена именно -для этого запроса — сама бизнес-логика (создание/старт/стоп VPS) от этого не зависит и будет -работать в любом случае. +```bash +ssh @ +``` + +Логин и пароль задаются клиентом при создании инстанса (поля «Пользователь» и «Пароль» +в форме создания — пробрасываются в cloud-init гостевой ОС). ## Безопасность перед продакшеном @@ -149,11 +143,10 @@ backend/ templates.py — CRUD шаблонов (admin) + импорт из Proxmox instances.py — создание/список/действия/удаление VPS admin.py — управление пользователями - console.py — websocket-прокси для VNC-консоли frontend/ src/ pages/ — Login, Register, Dashboard, InstanceDetail, AdminTemplates, AdminUsers - components/ — InstanceCard, ConsoleViewer + components/ — InstanceCard api.js — обёртка над fetch к backend styles.css — UI-стили docker-compose.yml @@ -163,8 +156,13 @@ docker-compose.yml ## Changelog +### 0.3.0 +- 🗑 Удалена VNC-консоль — для доступа к VM используйте SSH по IP из дашборда +- 🛠 Упрощена nginx-конфигурация (убран WebSocket-прокси для VNC) +- 🛠 Уменьшен размер frontend-образа (noVNC больше не качается) + ### 0.2.0 -- 🔒 Удалён закоммиченный `backend/.env` с реальными секретами. **Смените SECRET_KEY и PVE_TOKEN_VALUE!** +- 🔒 Удалён закоммиченный `backend/.env` с реальными секретами - 🔒 Добавлена проверка владельца во всех рутерах `instances.py` - 🔒 CORS теперь читается из `ALLOW_ORIGINS` (по умолчанию только localhost) - 🔒 Backend-порт 8000 закрыт снаружи по умолчанию @@ -175,6 +173,5 @@ docker-compose.yml - 🛠 Удалены дубли функций/эндпоинтов в `proxmox_client.py` и `instances.py` - 🛠 Backend запускается от non-root пользователя - 🛠 Multi-stage Dockerfile для backend (меньше размер образа) -- 🛠 noVNC устанавливается из npm вместо загрузки с CDN - 🛠 Добавлены healthcheck'и у всех сервисов в docker-compose -- 🛠 Структурированное логирование через `logging` +- 🛠 Структурированное логирование через `logging` \ No newline at end of file