pvemanager/WIKI.ru.md

📖 PVEmanager — Документация

Полное руководство по установке, настройке и использованию PVEmanager v1.16.0

---

📑 Содержание

1. Быстрый старт
2. Установка и развёртывание
3. Основные возможности
4. Система уведомлений
5. Управление ВМ и контейнерами
6. Массовые операции
7. Шаблоны ОС
8. Images — каталог облачных образов
9. Развёртывание LXC из CT-шаблонов
10. App Store
11. Кластеры Proxmox
12. Снимки (Snapshots)
13. Резервные копии
14. IPAM
15. Удалённое выполнение команд
16. Мониторинг
17. Безопасность (RBAC v2)
18. Локализация
19. Настройки
20. Управление SSH-ключами
21. Сети (SDN и интерфейсы узлов)
22. Инструмент pve CLI
23. Справочник API
24. Рабочие области (Workspaces)
25. Назначение серверов пользователю
26. Владелец ВМ / LXC
27. Квоты
28. Логи и аудит
29. Устранение неполадок
30. FAQ

---

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

Требования

• Docker и Docker Compose
• Минимум 2 ГБ RAM
• Сервер Proxmox VE с доступом к API

Запуск за 1 минуту

# Клонировать репозиторий
git clone https://github.com/your-repo/pvemanager.git
cd pvemanager

# Скопировать и настроить переменные окружения
cp .env.example .env
cp backend/.env.example backend/.env

# Запуск
docker compose up -d

# Открыть в браузере
open http://localhost:3001

Учётные данные по умолчанию:

• Логин: admin
• Пароль: admin123

⚠️ Обязательно смените пароль после первого входа!

---

📦 Установка и развёртывание

Варианты развёртывания

1. Standalone (разработка)

docker compose up -d

• Порт UI: 3001 (frontend), порт API: 8000 (backend)
• Без обратного прокси NGINX
• Подходит для локальной разработки

2. С NGINX (HTTP)

./deploy.sh
# Выбрать вариант 2

3. С NGINX + SSL (продакшн)

./deploy.sh
# Выбрать вариант 3
# Указать домен и email для Let's Encrypt

4. Установка одной командой (bootstrap.sh)

Один скрипт, который устанавливает панель как на обычном хосте Debian/Ubuntu, так и напрямую на хосте Proxmox VE — среда определяется по наличию /etc/pve:

git clone https://git.tzim.uz/markmorado/pvemanager.git
cd pvemanager
bash bootstrap.sh

• Обычный хост Debian/Ubuntu — при необходимости ставит Docker и git/curl/openssl/jq, клонирует репозиторий в PVEMANAGER_DIR (по умолчанию /opt/pvemanager) и передаёт управление deploy.sh --standalone.
• Хост Proxmox VE — создаёт LXC на Debian 12 (DHCP на vmbr0, nesting=1,keyctl=1 для Docker внутри), устанавливает панель внутри по тому же сценарию, а после того как панель ответит на GET /health, создаёт на самом хосте PVE локальный API-токен root@pam!pvemanager (pvesh create ... --privsep 0) и регистрирует этот хост как первую ноду панели. Пароль от Proxmox никуда не передаётся.
• Настраивается через переменные окружения (PVEMANAGER_REPO, PVEMANAGER_VERSION, PVEMANAGER_DIR, а также PVEMANAGER_LXC_* — vmid, хранилище, мост и ресурсы контейнера) — полный список и значения по умолчанию см. в заголовке bootstrap.sh.
• Скрипт переживает сбой apt-get update из-за недоступного enterprise-репозитория на неподписанном хосте PVE, не прерывая bootstrap до установки git/curl.

Переменные окружения

Основные (.env)

# База данных
POSTGRES_PASSWORD=your_secure_password

# Часовой пояс
TZ=Your/Timezone

# Отключить проверку обновлений (для приватных репо без токена)
DISABLE_UPDATE_CHECK=false

# Токен GitHub для доступа к приватному репозиторию (опционально)
GITHUB_TOKEN=

Backend (backend/.env)

# Секретный ключ (сгенерируйте уникальный! минимум 32 символа)
SECRET_KEY=your-very-long-secret-key-change-me

# Пароль администратора по умолчанию — ОБЯЗАТЕЛЬНО смените перед первым развёртыванием!
ADMIN_PASSWORD=admin123

# Ключ шифрования Fernet для чувствительных полей БД (пароли Proxmox/cloud-init).
# Сгенерировать: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
# ВНИМАНИЕ: храните этот ключ в безопасности — его потеря означает потерю доступа к зашифрованным паролям.
# Если не задан, пароли хранятся в открытом виде (небезопасно).
FERNET_KEY=

# Время жизни JWT-токена (в минутах). По умолчанию: 480 (8 часов)
ACCESS_TOKEN_EXPIRE_MINUTES=480

# CORS-источники (через запятую). В продакшне используйте реальный домен(ы).
CORS_ORIGINS=*

Уведомления Email и Telegram

Настройки SMTP и Telegram-бота теперь управляются через веб-интерфейс:

1. Перейдите в Настройки → Уведомления
2. В разделе «Настройка каналов уведомлений» заполните:
   • SMTP — параметры вашего почтового сервера
   • Telegram — токен бота от @BotFather
3. Нажмите кнопку Тест для проверки настроек

---

📚 Справочник API

В этом разделе перечислены ключевые эндпоинты API. Все они требуют JWT-аутентификации.

Аутентификация

• POST /api/auth/login — возвращает access_token

Обновления системы

• GET /settings/api/version — текущая версия
• GET /settings/api/updates/repository — получить URL git-репозитория
• PUT /settings/api/updates/repository — задать URL git-репозитория
• GET /settings/api/updates/check — проверить наличие обновлений
• POST /settings/api/updates/perform — запустить обновление

Серверы Proxmox

• GET /api/servers — список серверов
• POST /api/servers — добавить сервер (auto_create_token создаёт API-токен по логину/паролю)
• PUT /api/servers/{id} — обновить сервер
• DELETE /api/servers/{id} — удалить сервер
• POST /api/servers/{id}/test — проверить подключение
• POST /api/servers/{id}/provision-token — перевести сервер с пароля на автосозданный API-токен

Виртуальные машины

• GET /api/servers/{id}/resources — список ВМ
• POST /api/servers/{id}/vm/{vmid}/start?node={node} — запустить ВМ
• POST /api/servers/{id}/vm/{vmid}/stop?node={node} — остановить ВМ
• POST /api/servers/{id}/vm/{vmid}/restart?node={node} — перезагрузить ВМ
• GET /api/servers/{id}/vm/{vmid}/status?node={node} — статус ВМ

Контейнеры

• GET /api/servers/{id}/resources — список контейнеров
• POST /api/servers/{id}/container/{vmid}/start?node={node} — запустить контейнер
• POST /api/servers/{id}/container/{vmid}/stop?node={node} — остановить контейнер
• POST /api/servers/{id}/container/{vmid}/restart?node={node} — перезагрузить контейнер
• GET /api/servers/{id}/container/{vmid}/status?node={node} — статус контейнера

Шаблоны ОС

• GET /templates/api/groups — список групп шаблонов
• POST /templates/api/groups — создать группу шаблонов
• GET /templates/api/templates — список шаблонов
• POST /templates/api/templates — создать шаблон
• DELETE /templates/api/templates/{id} — удалить шаблон

IPAM

• GET /ipam/api/networks — список сетей
• POST /ipam/api/networks — создать сеть
• DELETE /ipam/api/networks/{id} — удалить сеть
• GET /ipam/api/allocations — список выделенных IP
• POST /ipam/api/allocations — создать выделение IP
• DELETE /ipam/api/allocations/{id} — освободить IP

Уведомления

• GET /api/notifications — список уведомлений
• PATCH /api/notifications/{id}/read — отметить прочитанным
• DELETE /api/notifications/{id} — удалить уведомление

Пользователи и роли

• GET /api/users — список пользователей (админ)
• POST /api/users — создать пользователя (админ)
• PUT /api/users/{id} — обновить пользователя (админ)
• DELETE /api/users/{id} — удалить пользователя (админ)
• GET /api/roles — список ролей (админ)
• POST /api/roles — создать роль (админ)
• PUT /api/roles/{id} — обновить роль (админ)
• DELETE /api/roles/{id} — удалить роль (админ)

Квоты

• GET /api/users/{id}/quota — квота пользователя и текущее использование (требует quota:view)
• PUT /api/users/{id}/quota — задать квоту пользователя; null для метрики = без ограничений (требует quota:manage)
• GET /api/quota — собственная квота и использование текущего пользователя (self-service)

Настройки

• GET /settings/api/panel — получить настройки панели
• PUT /settings/api/panel — обновить настройки панели
• GET /settings/api/security — получить настройки безопасности
• PUT /settings/api/security — обновить настройки безопасности
• GET /settings/api/notifications — получить настройки уведомлений
• PUT /settings/api/notifications — обновить настройки уведомлений

Резервные копии и хранилища

• GET /api/backups/storages/{server_id} — список хранилищ
• GET /api/backups/scan-nfs/{server_id}?server=<ip> — сканировать NFS-сервер на доступные экспорты
• POST /api/backups/storages/{server_id} — добавить хранилище
• PUT /api/backups/storages/{server_id}/{storage_id} — обновить хранилище
• DELETE /api/backups/storages/{server_id}/{storage_id} — удалить хранилище
• GET /api/backups/list/{server_id}?node=&storage= — список файлов резервных копий
• DELETE /api/backups/{server_id}/backup — удалить файл резервной копии
• POST /api/backups/create — создать резервную копию VM/LXC (vzdump)
• POST /api/backups/restore — восстановить VM/LXC из резервной копии
• GET /api/backups/task/{server_id}/{node}/{upid} — статус/лог задачи
• GET /api/backups/jobs — список запланированных заданий резервного копирования
• POST /api/backups/jobs — создать запланированное задание
• PUT /api/backups/jobs/{id} — обновить задание
• DELETE /api/backups/jobs/{id} — удалить задание

Высокая доступность (HA)

• GET /api/{server_id}/ha/status — статус HA для всех ВМ
• GET /api/{server_id}/ha/{vm_type}/{vmid} — статус HA для ВМ
• POST /api/{server_id}/ha/{vm_type}/{vmid}/add — добавить ВМ в HA
• DELETE /api/{server_id}/ha/{vm_type}/{vmid}/remove — убрать ВМ из HA

SDN (Software Defined Networking)

• GET /api/servers/{server_id}/sdn/status — проверить доступность SDN
• GET /api/servers/{server_id}/sdn/zones — список зон
• POST /api/servers/{server_id}/sdn/zones — создать зону
• PUT /api/servers/{server_id}/sdn/zones/{zone} — обновить зону
• GET /api/servers/{server_id}/sdn/vnets — список VNet
• POST /api/servers/{server_id}/sdn/vnets — создать VNet
• PUT /api/servers/{server_id}/sdn/vnets/{vnet} — обновить VNet
• POST /api/servers/{server_id}/sdn/vnets/{vnet}/subnets — создать подсеть (поддерживает create_ipam_network)
• DELETE /api/servers/{server_id}/sdn/vnets/{vnet}/subnets/{cidr} — удалить подсеть
• POST /api/servers/{server_id}/sdn/apply — применить ожидающие изменения SDN

Сети узлов

• GET /api/servers/{server_id}/nodes — список узлов сервера

Прочее

• POST /api/sync-vms — принудительная немедленная синхронизация ВМ со всех серверов Proxmox
• DELETE /proxmox/api/all-tasks/completed — удалить все завершённые/проваленные/отменённые задачи текущего пользователя (и ProxmoxTask, и TaskQueue)

---

🏠 Основные возможности

Дашборд

• 5 карточек статистики — узлы, ВМ, контейнеры, кластеры, оповещения (в реальном времени)
• Карточки ресурсов — CPU, RAM, хранилище с мини-графиками (sparkline)
• Чип статуса в шапке — All systems operational / предупреждения / критические оповещения
• Живые часы в шапке
• Количество кластеров вычисляется автоматически из базы данных
• Счётчик оповещений из AuditLog (ошибки + критические за последние 24 ч)
• Недавние события аудита (последние 5) на дашборде
• Селектор кластера в боковой панели — показывает активный кластер или имя standalone
• Бейдж версии в шапке

Серверы Proxmox

• Добавление нескольких серверов
• Аутентификация через API Token или пароль
• Автоматическое создание API-токена с переводом уже подключённых по паролю серверов без переподключения
• Мониторинг статуса серверов с различением недоступной ноды и отклонённых/протухших учётных данных
• Доступность storage по нодам

Управление ВМ и LXC

• Просмотр всех виртуальных машин
• Запуск / Остановка / Перезагрузка / Выключение
• Изменение конфигурации (CPU, RAM, диск)
• VNC-консоль в браузере
• Удалённое выполнение команд

Массовые операции

• Массовый запуск/остановка/перезагрузка/удаление ВМ и контейнеров
• Система очереди задач с отслеживанием прогресса
• Фоновая обработка

Шаблоны ОС

• Быстрое развёртывание ВМ из шаблонов
• Кросс-узловое развёртывание шаблонов для кластеров
• Группы шаблонов и иконки
• Переустановка ВМ из шаблона

Снимки (Snapshots)

• Создание, удаление, откат снимков VM/LXC
• Система очереди операций со снимками
• Архивирование снимков при удалении ВМ

Резервные копии

• Ручное создание резервных копий (vzdump) для ВМ и контейнеров
• Просмотр и удаление копий по хранилищу/узлу
• Восстановление VM/LXC из копии с опциональным новым VMID
• Запланированные задания с cron-выражениями
• Политики хранения копий (keep_last, keep_daily, keep_weekly, keep_monthly)
• Управление пулами хранилищ (добавить, изменить, удалить)
• Отслеживание прогресса задач через UPID

Высокая доступность (HA)

• Просмотр статуса HA для всех ВМ на сервере
• Добавление/удаление ВМ из групп Proxmox HA
• Статус HA и информация о группе для каждой ВМ

IPAM (управление IP-адресами)

• Управление сетями и подсетями
• Привязка к серверу и узлу — сети привязываются к конкретному серверу и узлу Proxmox, чтобы исключить назначение IP между серверами
• Ручной выбор сервера + сети в модальном окне при привязке IP к VM/LXC
• Динамические селекторы сервера и узла в формах создания сети
• Автоматическое выделение IP
• Резервирование и освобождение IP
• История выделений

Уведомления

• Оповещения о событиях ВМ в реальном времени
• Email-уведомления через SMTP
• Telegram-уведомления через Bot API
• In-App уведомления с иконкой колокольчика

Безопасность

• RBAC v2 с атомарными правами (resource:action)
• Изоляция пользователей в стиле VPS (пользователи видят только свои инстансы)
• Блокировка IP (автоматическая и ручная)
• Управление сессиями
• Защита входа (блокировка, ограничение частоты)
• Журналы аудита

Квоты

Ограничения ресурсов на пользователя, применяемые при развёртывании VM/LXC:

• Ограничиваемые метрики — количество инстансов, суммарные vCPU (ядра), суммарная RAM (МБ) и суммарный диск (ГБ), просуммированные по неудалённым, не-шаблонным инстансам пользователя
• Без ограничений по умолчанию — пользователь без строки квоты или с пустой метрикой (NULL) не ограничен по этой метрике; администраторы никогда не блокируются
• Применение — развёртывание инстанса, превышающего любой лимит, отклоняется с HTTP 429 и двуязычным сообщением с прогнозируемым значением и лимитом
• Управление админом — задание лимитов на пользователя на странице Пользователи (диалог квот с живыми полосами использования); требует право quota:manage (quota:view для чтения)
• Self-service — каждый пользователь видит свои лимиты и текущее использование на странице Настройки, а остаток квоты показывается подсказкой в мастере создания инстанса
• Текущее использование берётся из кэша vm_instances (owner_id), где RAM хранится в МБ, а диск — в ГБ

Мониторинг

• Метрики CPU, RAM, диска, сети в реальном времени
• Исторические графики (час, день, неделя, месяц) как для инстансов, так и для нод (вкладка «Графики» у ноды: CPU, IO delay, память, load average, сеть, swap, корневая ФС)
• Пороги оповещений по ресурсам

---

🔔 Система уведомлений

Обзор

Система уведомлений обеспечивает:

• Оповещения в реальном времени о событиях ВМ
• Email-уведомления через SMTP
• Telegram-уведомления через Bot API
• In-App уведомления с иконкой колокольчика

Типы уведомлений

Тип	Описание	Пример
vm_status	Изменения состояния ВМ	ВМ запущена/остановлена
resource_alert	Оповещения по ресурсам	CPU > 80%, RAM > 85%
system	Системные события	Ошибки подключения

Уровни важности

Уровень	Цвет	Описание
critical	🔴 Красный	Критические проблемы
warning	🟠 Оранжевый	Предупреждения
info	🔵 Синий	Информационные
success	🟢 Зелёный	Успешные операции

Настройка Email

1. Перейдите в Настройки → Уведомления
2. В «Настройке каналов уведомлений» заполните данные SMTP:
   • SMTP-сервер — адрес почтового сервера
   • Порт — 465 для SSL, 587 для STARTTLS
   • Пользователь — ваш email
   • Пароль — пароль приложения
   • Email отправителя — адрес отправителя
3. В «Настройках уведомлений» отметьте Email-уведомления
4. Нажмите Тест для проверки

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

Сервер	Хост	Порт	TLS
Yandex	smtp.yandex.ru	465	SSL
Gmail	smtp.gmail.com	587	STARTTLS
Mail.ru	smtp.mail.ru	465	SSL

⚠️ Для Yandex и Gmail используйте «пароль приложения», а не основной пароль!

Настройка Telegram

1. Создайте бота через @BotFather
2. В Настройки → Уведомления введите токен бота
3. Отправьте боту /start
4. Получите Chat ID через @userinfobot
5. В «Настройках уведомлений» включите Telegram и введите Chat ID
6. Нажмите Проверить для подтверждения

Параметры уведомлений

Параметр	Описание
Включено	Активировать канал
Только критические	Отправлять только критический уровень
Тихие часы	Период без уведомлений (напр., 23:00 – 07:00)

Фоновый мониторинг

Автоматически отслеживает:

• Статус ВМ каждые 30 секунд
• Ресурсы каждые 60 секунд
• Пороги: CPU > 80%, RAM > 85%, диск > 90%

---

🖥️ Управление ВМ и контейнерами

Палитра команд (Ctrl+K)

Нажмите Ctrl+K (⌘K на macOS) в любом месте приложения, чтобы открыть палитру команд — поисковый список всех пунктов навигации. Начните печатать для фильтрации, затем Enter для перехода. Палитра и боковое меню используют один унифицированный реестр навигации, поэтому всегда синхронизированы.

Действия с ВМ

Меню строки инстанса (⋯) содержит Опции, Миграцию, Изменение ресурсов, Создание резервной копии и Удаление наряду с действиями питания ниже. Меню остаётся открытым при живых обновлениях списка.

Действие	Описание	Хоткей
Start	Запустить ВМ	-
Stop	Остановить (ACPI-выключение)	-
Restart	Перезагрузить	-
Force Stop	Принудительная остановка	-
Delete	Удалить ВМ	-

Вкладки инстанса: для ВМ карточки Compute resources, CPU options, Disk management и Disk resize находятся на вкладке Hardware; LXC-контейнеры (у которых нет вкладки Hardware) держат эти карточки на вкладке Settings.

Массовые операции

Выберите несколько ВМ/контейнеров и выполните массовые действия:

1. Отметьте чекбокс рядом с каждой нужной ВМ
2. Используйте «Выбрать все» для выбора всех видимых ВМ
3. Нажмите кнопку действия в панели массовых операций:
   • Start All — запустить все выбранные
   • Stop All — остановить все выбранные
   • Restart All — перезагрузить все выбранные
   • Delete All — удалить все выбранные (с подтверждением)

Подробнее см. Массовые операции.

Консоль (VNC / терминал)

• QEMU-ВМ — VNC-консоль через noVNC (графический вывод в браузере).
  1. Откройте детали ВМ → нажмите Console, либо ПКМ по ВМ в списке → VNC Console
  2. Полный проброс клавиатуры и мыши; поддержка полноэкранного режима
• LXC-контейнеры — интерактивный shell через терминал xterm.js.
  1. Откройте детали контейнера → нажмите Terminal, либо ПКМ по контейнеру в списке → Terminal
  2. Полный PTY: автодополнение, цвета, Unicode, изменение размера терминала при ресайзе окна
  3. Использует WebSocket-протокол Proxmox termproxy (рукопожатие аутентификации + keepalive-пинги каждые 2 мин)

Изменение конфигурации

CPU: 1–32 ядра
RAM: 512 МБ – 128 ГБ
Диск: увеличение размера (уменьшение невозможно)

Примечание (v1.2.0+): изменение размера диска полностью асинхронно. Панель ждёт завершения задачи ресайза в Proxmox перед запуском ВМ, что предотвращает ошибки lock file timeout, возникавшие при немедленном запуске ВМ после запроса ресайза.

Высокая доступность (HA)

Требуется кластер Proxmox с настроенным менеджером HA.

1. Откройте детали ВМ или контейнера
2. Перейдите на вкладку HA
3. Нажмите Add to HA и выберите HA-группу (опционально)
4. Для удаления — нажмите Remove from HA

Операции панели сейчас отражают статус HA, но не заменяют конфигурацию менеджера Proxmox HA.

---

⚡ Массовые операции

Обзор

Массовые операции позволяют выполнить одно и то же действие над несколькими ВМ или контейнерами одновременно. Это удобно, когда нужно запустить, остановить или перезагрузить много виртуальных машин сразу.

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

Действие	Описание	Требуется подтверждение
Bulk Start	Запустить все выбранные VM/контейнеры	Нет
Bulk Stop	Остановить все выбранные (ACPI-выключение)	Нет
Bulk Restart	Перезагрузить все выбранные	Нет
Bulk Shutdown	Корректное выключение	Нет
Bulk Delete	Удалить все выбранные	Да (двойное подтверждение)

Как использовать

1. Перейдите на страницу «Виртуальные машины»
2. Выберите ВМ чекбоксами:
   • Кликайте отдельные чекбоксы
   • Или используйте «Выбрать все» для всех видимых ВМ
3. Панель массовых действий появляется внизу при выборе ВМ
4. Нажмите нужное действие
5. Подтвердите при запросе (для операций удаления)

Панель задач (Task Drawer)

При запуске массовой операции Task Drawer автоматически открывается в боковой панели. Он показывает прогресс каждой задачи в реальном времени:

• Выполняющиеся задачи показывают спиннер и текущий прогресс (completed / total)
• Завершённые задачи зелёные; проваленные — красные
• Задачи старше 24 часов автоматически скрываются из панели (остаются доступны на странице /tasks)
• Кнопка корзины (🗑) в шапке панели удаляет все завершённые/проваленные/отменённые задачи одним кликом

Отслеживание UPID Proxmox

Начиная с v1.1.5, отдельные действия управления VM/LXC (start / stop / restart) связаны с реальным UPID задачи Proxmox. UPID регистрируется как запись ProxmoxTask и опрашивается в реальном времени, поэтому Task Drawer отражает фактическое состояние задачи на стороне Proxmox.

Ограничения

• Одновременно выполняется только одна массовая задача
• Задачи обрабатываются последовательно
• Максимум элементов на задачу: не ограничено (но учитывайте нагрузку на сервер)
• Задачи нельзя приостановить (только отменить, если ожидают)

---

📋 Шаблоны ОС

Концепция

Шаблоны ОС позволяют быстро развёртывать ВМ из предварительно настроенных шаблонов.

Создание группы шаблонов

1. Шаблоны ОС → Groups → Add Group
2. Введите имя (напр., «Linux Servers»)
3. Добавьте описание

Добавление шаблона

1. Шаблоны ОС → Templates → Add Template
2. Или: Scan → выбрать из Proxmox

Развёртывание ВМ

1. Выберите шаблон
2. Укажите:
   • Имя ВМ
   • Целевой узел (для кластеров — выбрать, куда развернуть)
   • CPU/RAM/диск
   • IP-адрес (или авто из IPAM)
   • SSH-ключ (опционально)
3. Нажмите Deploy

Кросс-узловое развёртывание шаблонов (кластеры)

При использовании кластеров Proxmox шаблоны можно развернуть на любой узел кластера:

Как это работает

1. Создание шаблона на любом узле — шаблон изначально создаётся на одном узле кластера
2. Выбор целевого узла — при развёртывании ВМ выберите любой онлайн-узел кластера
3. Автоматическая репликация — если шаблона нет на целевом узле:
   • Система клонирует шаблон на целевой узел
   • Конвертирует клон в шаблон
   • Отслеживает реплицированные шаблоны в базе данных
4. Последующие развёртывания — используют уже реплицированный шаблон (быстро)

Требования

• Кластер Proxmox (узлы должны быть в одном кластере)
• Рекомендуется общее хранилище (но не обязательно)
• Шаблон должен быть доступен с исходного узла

Пример

Кластер: pve1, pve2, pve3
Шаблон: Ubuntu-22.04 на pve1

Развёртывание на pve1: используется оригинальный шаблон (быстро)
Развёртывание на pve2: репликация шаблона → развёртывание (первый раз медленнее)
Развёртывание на pve3: репликация шаблона → развёртывание (первый раз медленнее)

Следующее развёртывание на pve2: используется реплицированный шаблон (быстро)

Переустановка ВМ

1. Откройте детали ВМ
2. Нажмите Reinstall
3. Выберите шаблон
4. VMID сохраняется

---

📥 Images — каталог облачных образов

Обзор

Модуль Images позволяет просматривать, скачивать и управлять образами ОС из облачных репозиториев. Образы можно скачивать напрямую в хранилище Proxmox и опционально автоматически конвертировать в шаблоны ВМ.

Возможности

• Просмотр облачных образов — обнаружение образов ОС из стандартного репозитория Proxmox и кастомных зеркал
• Скачивание образов — загрузка образов .qcow2 в любое хранилище Proxmox с отслеживанием прогресса
• Автоконвертация в шаблон — опциональная автоматическая конвертация скачанных образов в шаблоны ВМ Proxmox
• Фильтрация по архитектуре — образы фильтруются по платформе узла (x86-64, aarch64); архитектура по умолчанию соответствует выбранному узлу
• Кастомные зеркала — администраторы могут добавлять, редактировать и управлять кастомными источниками зеркал
• Загрузка ISO — установочный ISO можно скачать по URL, из сохранённого зеркала (kind=iso) или прямо на шаге ISO в мастере создания инстанса. Встроенный каталог намеренно ограничен .qcow2 — у установочных ISO нет стабильной ссылки на «последнюю версию», поэтому жёстко прописанные ссылки протухали бы при каждом релизе
• Загрузка локального файла — ISO или шаблон LXC (vztmpl) можно загрузить со своего компьютера прямо в storage ноды — для образов, которые нигде публично не доступны панели

Доступ к Images

1. Перейдите в Infrastructure → Images (боковое меню)
2. Выберите сервер и узел Proxmox
3. Просматривайте доступные образы, отфильтрованные по архитектуре

Скачивание образа

1. Нажмите Download рядом с нужным образом
2. Выберите целевое хранилище
3. Опционально включите Convert to Template (создаёт шаблон ВМ по завершении)
4. Нажмите Download — прогресс отслеживается в реальном времени
5. По завершении образ доступен в хранилище для развёртывания ВМ

Загрузка локального файла

1. Перейдите в Infrastructure → Images и выберите Upload
2. Укажите файл ISO или vztmpl и целевое хранилище
3. Панель передаёт файл на ноду в фоне; прогресс отслеживается так же, как при загрузке по URL
4. По завершении файл доступен в хранилище для развёртывания ВМ/CT

Установка ОС с ISO

Мастер создания инстанса предлагает тип «пустая ВМ» для установки с ISO: создаётся ВМ с пустым диском и смонтированным на ide2 образом, который ставится первым в порядке загрузки, — гость сразу попадает в установщик через встроенную консоль noVNC. Выбор гостя Windows автоматически задаёт прошивку OVMF, SATA-диск и сетевую карту e1000, так как у установщика ещё нет драйверов virtio.

Извлечение и монтирование ISO

На странице ВМ диалог ISO показывает все образы, уже лежащие в хранилище ноды — включая те, что появились там до подключения ноды к панели, — и текущий смонтированный образ, если он есть:

• Монтировать — выберите ISO из хранилища; опционально отметьте «загрузка с этого ISO», чтобы поставить CD-ROM первым в порядке загрузки.
• Извлечь (переименовано из «Отсоединить») — снимает смонтированный ISO; опционально отметьте «загрузка с диска», чтобы поставить основной диск первым в порядке загрузки.

Любое действие, меняющее порядок загрузки, применяется через гибридную перезагрузку: штатное ACPI-выключение с откатом на принудительную остановку, затем запуск. Это убирает таймаут ping гостя, с которым сталкивается обычный рестарт на свежеустановленной ОС, где ещё не запущен QEMU Guest Agent.

GitHub-зеркало с QEMU Guest Agent

Встроенный каталог образов amd64 ссылается на GitHub-зеркало, содержащее облачные образы с предустановленным qemu-guest-agent. Это даёт:

• Живые метрики на ВМ (CPU, память, заполнение диска, скорости I/O) сразу после деплоя — дополнительная установка агента не нужна
• Образы включают контрольную сумму sha256; если закешированный файл не совпадает с опубликованной суммой, панель скачает его повторно автоматически

Чтобы собрать или обновить зеркало самостоятельно, запустите вспомогательный скрипт на Linux-хосте с установленным QEMU:

bash patch-cloud-images.sh

Скрипт скачивает исходный .qcow2, устанавливает qemu-guest-agent через virt-customize и публикует патченный образ как GitHub Release.

Кастомные зеркала (только админ)

Администраторы могут настроить кастомные репозитории образов:

1. Перейдите в Настройки → Images → Custom Mirrors
2. Нажмите Add Mirror
3. Введите URL зеркала (должен быть валидным репозиторием Proxmox)
4. Сохраните — зеркало сразу появится в браузере образов

Формат URL зеркала:

Валидное зеркало должно предоставлять стандартную структуру репозитория Proxmox с файлом index.json, содержащим метаданные образов.

Эндпоинты API

Метод	Эндпоинт	Описание
GET	/api/images	Список доступных образов
GET	/api/images/node-arch/{server_id}/{node}	Архитектура узла
POST	/api/images/download	Запустить скачивание (возвращает UPID задачи)
GET	/api/images/mirrors	Список кастомных зеркал (админ)
POST	/api/images/mirrors	Добавить кастомное зеркало (админ)
PUT	/api/images/mirrors/{id}	Обновить зеркало (админ)
DELETE	/api/images/mirrors/{id}	Удалить зеркало (админ)

Отслеживание задачи скачивания

Скачивание образов отслеживается как задачи Proxmox (UPID). Используйте стандартный эндпоинт задач для мониторинга прогресса:

GET /api/backups/task/{server_id}/{node}/{upid}

---

📦 Развёртывание LXC из CT-шаблонов

Обзор

Начиная с v1.5.0, LXC-контейнеры можно создавать напрямую из файлов CT-шаблонов Proxmox (.tar.zst, .tar.gz) без необходимости заранее настраивать запись «Шаблон ОС». Это стандартный способ развернуть Debian, Ubuntu, Alpine и другие дистрибутивы из списка загрузок Proxmox.

Просмотр доступных CT-шаблонов

CT-шаблоны берутся напрямую из хранилища сервера Proxmox:

1. Перейдите в Instances → Create Instance
2. Выберите целевой сервер Proxmox
3. Выберите тип LXC Container
4. Мастер получает доступные файлы .tar.zst / .tar.gz со всех хранилищ выбранного сервера

Развёртывание LXC-контейнера

1. Шаг Server — выберите сервер Proxmox
2. Шаг Type — выберите LXC Container
3. Шаг Template — выберите CT-шаблон из списка
4. Шаг Config — заполните:
   • Имя контейнера (hostname)
   • Ядра CPU, RAM (МБ), Swap (МБ), диск (ГБ)
   • Хранилище, сетевой мост
   • IP-адрес / шлюз (вручную или из IPAM)
   • Root-пароль и/или SSH-ключи
   • Владелец (только админ)
   • Опции Start after create / On-boot
5. Шаг Confirm — проверьте и нажмите Deploy

Развёртывание выполняется асинхронно; прогресс отслеживается в Task Drawer.

SSH-ключи при развёртывании LXC

• Выберите один или несколько ключей из личной библиотеки SSH-ключей (см. Управление SSH-ключами)
• Админы, развёртывающие от имени другого пользователя, могут выбрать ключи из библиотеки этого пользователя
• Ключи внедряются в authorized_keys контейнера во время провижининга

Переустановка LXC-контейнера (CT-шаблон)

Контейнеры, созданные из CT-шаблонов, поддерживают переустановку:

1. Откройте меню действий контейнера → Reinstall
2. Опционально выберите другой CT-шаблон
3. Автоматически сохраняются:
   • Root-пароль
   • SSH-ключи
   • IP-адрес и шлюз
4. Старый контейнер уничтожается, создаётся новый с тем же VMID

Примечание: nesting=1 включается по умолчанию для всех новых LXC-контейнеров для совместимости с systemd 255+ (cgroup v2).

---

🛒 App Store

Каталог self-hosted приложений с установкой в один клик. Каждое приложение работает в собственном unprivileged LXC-контейнере с Docker Compose (1 приложение = 1 LXC). Каталог мультиисточниковый: runtipi/runtipi-appstore (~265 приложений) и опционально getumbrel/umbrel-apps (~380 приложений). Источники выбираются через APPSTORE_SOURCES; id приложений Umbrel имеют префикс (umbrel-<id>) во избежание коллизий.

Предварительные требования

• Золотой шаблон LXC (Debian 12 + Docker + Compose) на каждый сервер Proxmox. Соберите его из App Store → золотой шаблон (POST /api/appstore/golden-template, выбирает сервер/узел/хранилище) — это автоматизирует ручную процедуру из docs/golden-template.md. Хранилище шаблона и rootfs выбираются из выпадающих списков, заполненных реальными хранилищами выбранного сервера/ноды (по content vztmpl/rootdir), с автоподстановкой local/local-lvm, если они доступны. Полученный volid vztmpl хранится для каждого server_id (шаблон, собранный на сервере A, лежит только в хранилище A и никогда не используется для установки на сервере B); APPSTORE_GOLDEN_TEMPLATE — лишь последний запасной вариант для серверов без собственной сборки.
• SSH-доступ от панели к узлу Proxmox (используется для pct exec / pct push).
• Установлен FERNET_KEY (шифрует секреты приложений на диске).

Настройки окружения

Переменная	По умолчанию	Назначение
APPSTORE_GOLDEN_TEMPLATE	—	запасной volid золотого vztmpl, используется только если у сервера нет собственного сохранённого шаблона
APPSTORE_NAMESERVER	1.1.1.1 8.8.8.8	DNS, явно задаваемый на LXC App Store (и на CT сборки золотого шаблона) — без него контейнер наследует резолвер узла, который может быть недоступен из сети LXC (напр., DNS только для Tailscale на хосте) и ломает pull образов
APPSTORE_SOURCES	runtipi	активные источники каталога через запятую (runtipi, umbrel)
RUNTIPI_APPSTORE_REPO	runtipi/runtipi-appstore	источник каталога Runtipi
RUNTIPI_APPSTORE_REF	master	ветка/тег/коммит (рекомендуется зафиксировать)
UMBREL_APPSTORE_REPO	getumbrel/umbrel-apps	источник каталога Umbrel (когда включён umbrel)
UMBREL_APPSTORE_REF	master	ветка/тег/коммит Umbrel
UMBREL_APPSTORE_GALLERY_CDN	https://getumbrel.github.io/umbrel-apps-gallery	CDN иконок Umbrel (<app-id>/icon.svg, скачиваются пофайлово параллельно)
APPSTORE_DATA_DIR	/app/data/appstore	кэш логотипов (смонтированный volume)
CATALOG_SYNC_INTERVAL_HOURS	24	интервал авто-синхронизации каталога
APPSTORE_HOST_ARCH	amd64	целевая архитектура узла (помечает неподдерживаемые приложения)

Каталог

• Экран App Store: сетка карточек с поиском и фильтрами по категориям; кнопка Refresh catalog + метка времени последней синхронизации. Когда включено более одного источника, появляются фильтр источника и бейдж источника на карточке (Runtipi / Umbrel).
• Автоматическая синхронизация каждые 24 ч; повреждённая запись приложения пропускается без провала всей синхронизации. Каждый источник синхронизируется независимо, а проход исчез → недоступно ограничен рамками источника.
• Приложения Umbrel: метаданные из umbrel-app.yml, иконки из репозитория gallery; при установке runtime-сервисы Umbrel app_proxy/tor вырезаются, а порт контейнера (app_proxy → APP_PORT) публикуется на хосте LXC.
• Страница приложения: описание, версия, ссылка на источник, дисклеймер установки и предпросмотр compose.

Установка

Конвейер (каждый шаг журналируется и стримится по WebSocket):

1. Клонирование золотого шаблона LXC (по умолчанию 2 vCPU / 2048 МБ / 8 ГБ, DHCP или расширенные переопределения).
2. Запуск и ожидание IP.
3. pct push docker-compose.yml + .env (ответы формы + сгенерированные random-секреты) + любые вложенные data_files.
4. docker compose up -d.
5. HTTP health-check.
6. Показ URL приложения и одноразовых учётных данных.

Проваленный шаг ставит статус error с логом шага; Retry не пересоздаёт LXC (идемпотентно по VMID) и повторно использует исходные параметры установки (сохранены в installed_apps.install_params), Delete удаляет контейнер и запись.

Заметки о надёжности:

• Файлы, поставляемые с приложением каталога (data_files), доставляются в контейнер до docker compose up; учитываются Umbrel APP_PASSWORD / default_credentials.
• Каталоги bind-mount хоста (volumes: в compose приложения, и ${APP_DATA_DIR}/..., и относительные пути) предварительно создаются с разрешительными правами до up — иначе Docker создаёт их как root, и non-root пользователи контейнера (напр., mysql у mariadb) получают Permission denied.
• Поиск VMID пропускает уже занятые записи — nextid не резервирует номер, поэтому повтор мог бы иначе занять другой контейнер.
• pct create повторяет несколько раз при временной ошибке config-lock (частой сразу после удаления того же VMID, пока узел ещё стирает старый диск).
• Delete теперь ждёт, пока Proxmox фактически подтвердит завершение задачи destroy (до 30 мин, покрывает медленное стирание диска), прежде чем пометить приложение удалённым — иначе VMID мог бы быть переиспользован, пока узел ещё занят.
• Значения .env, содержащие #, берутся в кавычки (парсер dotenv иначе обрезал бы их как inline-комментарий); порт, явно выбранный в мастере (включая 80), публикуется как есть.

Трей свёрнутых операций

Долгие операции App Store — установка приложения и сборка золотого шаблона — можно свернуть вместо того, чтобы держать диалог открытым:

• Свёрнутые операции живут в глобальном хранилище (сохраняется в localStorage) и рендерятся как трей в макете приложения, поэтому плашка переживает навигацию по страницам и полную перезагрузку вкладки. Трей сам опрашивает прогресс каждой операции (REST, каждые 3 с), независимо от диалога.
• Клик по плашке возвращает на страницу операции и переоткрывает диалог — установка возобновляется в мастере, сборка шаблона переоткрывает диалог золотого шаблона с предвыбранным сервером.
• Свернуть добавляет операцию в трей и закрывает диалог; ✕ на плашке лишь удаляет плашку (операция продолжает работать на сервере). Плашки операций, которых больше нет (404 после перезагрузки), очищаются автоматически.

Мои приложения

Управление установленными приложениями: Start / Stop / Restart / Logs / Delete, живой статус и кликабельный IP:port.

• Реконсиляция запускается каждые 60 с и при открытии экрана: LXC, удалённый вне PVEmanager, помечается orphaned.
• Обновление: делает pre-update снапшот Proxmox → docker compose pull && up -d → health-check; хранит только последний pre-update снапшот.
• Откат: восстанавливает снапшот (⚠️ также откатывает данные приложения к моменту снапшота) и возвращает версию в базе данных.

Права

app:view (каталог + Мои приложения), app:install (установка), app:manage (синхронизация, жизненный цикл, обновление, откат, удаление). Админы обходят все проверки.

REST API

GET    /api/appstore/catalog                      # список (q, category, source)
GET    /api/appstore/catalog/{app_id}             # детали
GET    /api/appstore/catalog/{app_id}/logo        # логотип (публично)
POST   /api/appstore/catalog/sync                 # ручная синхронизация (админ)
POST   /api/appstore/apps/install                 # установка
GET    /api/appstore/apps                          # список установленных
POST   /api/appstore/apps/{id}/action/{start|stop|restart}
GET    /api/appstore/apps/{id}/logs
POST   /api/appstore/apps/{id}/update
POST   /api/appstore/apps/{id}/rollback
POST   /api/appstore/apps/reconcile
DELETE /api/appstore/apps/{id}
POST   /api/appstore/golden-template                    # собрать золотой vztmpl для сервера
GET    /api/appstore/golden-template/status?server_id=…  # шаблон сервера + последняя операция сборки

---

🔗 Кластеры Proxmox

Обзор

PVEmanager полностью поддерживает кластеры Proxmox, позволяя управлять несколькими узлами как единой сущностью.

Добавление кластера

1. Перейдите в Proxmox VE → Add Server
2. Введите IP-адрес любого узла (напр., pve1)
3. Панель автоматически обнаружит все узлы кластера
4. Все узлы появятся в селекторах узлов

Преимущества кластера

Возможность	Standalone	Кластер
Кол-во узлов	1	Несколько
Кросс-узловые шаблоны	❌	✅
Выбор целевого узла	❌	✅
Автоматический failover	❌	✅ (Proxmox HA)

Создание кластера Proxmox

Если ваши узлы ещё не в кластере:

# На первом узле (pve1)
pvecm create my-cluster

# На других узлах (pve2, pve3 и т.д.)
pvecm add 10.10.10.11  # IP pve1

Кросс-узловое развёртывание шаблонов

См. Шаблоны ОС — Кросс-узловое развёртывание

Импорт уже существующего кластера

Если узлы уже объединены в кластер в обход панели (через pvecm или веб-интерфейс Proxmox), сначала добавьте каждый узел в панель как обычный standalone-сервер, затем воспользуйтесь Кластер → Импорт:

1. Выберите любой из уже добавленных узлов — панель прочитает с него cluster/config/join и определит реальное имя кластера и список узлов
2. Совпавшие по IP или hostname серверы панели будут отмечены автоматически; узлы, ещё не добавленные в панель, будут показаны в списке, но привязать их нельзя, пока они не добавлены как серверы
3. Подтвердите — панель только привяжет совпавшие записи серверов к группе кластера в своей БД; никакая команда pvecm не выполняется, реальный кластер не затрагивается

Это чисто БД-аналог «Создать кластер»/«Присоединить ноду», которые выполняют настоящие операции pvecm create/pvecm add — используйте Импорт только когда узлы уже реально объединены в кластер.

---

📸 Снимки (Snapshots)

Обзор

Снимки позволяют сохранять и восстанавливать состояние ВМ и контейнеров в любой момент времени.

Создание снимка

1. Откройте детали ВМ или контейнера
2. Перейдите на вкладку Snapshots
3. Нажмите Create Snapshot
4. Введите имя и описание
5. Опционально включите состояние RAM (только QEMU-ВМ)

Управление снимками

Действие	Описание
Create	Сохранить текущее состояние ВМ
Rollback	Восстановить к предыдущему состоянию снимка
Delete	Удалить существующий снимок

⚠️ Откат отменит все изменения, сделанные после создания снимка!

Очередь снимков

Операции со снимками обрабатываются через систему очереди задач. Прогресс отслеживается, результаты сохраняются для каждого элемента.

Эндпоинты API

# Список снимков
GET /api/{server_id}/vm/{vmid}/snapshots?node={node}

# Создать снимок
POST /api/{server_id}/vm/{vmid}/snapshots?node={node}

# Удалить снимок
DELETE /api/{server_id}/vm/{vmid}/snapshots/{snapname}?node={node}

# Откатить к снимку
POST /api/{server_id}/vm/{vmid}/snapshots/{snapname}/rollback?node={node}

Для LXC-контейнеров используйте /container/ вместо /vm/ в эндпоинтах выше.

---

💾 Резервные копии

Обзор

PVEmanager предоставляет полный интерфейс управления резервными копиями на базе Proxmox vzdump. Можно создавать, просматривать, восстанавливать и удалять копии, а также настраивать автоматические запланированные задания.

Управление хранилищами

Перед созданием копий убедитесь, что целевое хранилище настроено в Proxmox.

Действие	Описание
List storages	Просмотр всех хранилищ сервера
Add storage	Добавить пул хранилища (directory, NFS, CIFS и т.д.)
Edit storage	Изменить конфигурацию хранилища
Delete storage	Удалить хранилище из Proxmox

Создание резервной копии

1. Перейдите на страницу Backups
2. Выберите сервер и узел
3. Выберите хранилище, куда сохранить копию
4. Выберите VM/контейнер (по VMID)
5. Настройте опции:
   • Режим: snapshot (по умолчанию), suspend или stop
   • Сжатие: zstd (по умолчанию), lzo, gzip, none
6. Нажмите Create Backup
7. Возвращается UPID — используйте его для отслеживания прогресса

Режимы резервного копирования

Режим	Описание	Простой
snapshot	Живой снимок (требует QEMU agent или LVM)	Нет
suspend	Приостановка ВМ на время копирования	Кратковременный
stop	Остановка ВМ, копирование, запуск	Полная остановка

Просмотр и удаление копий

• Просматривайте существующие копии по серверу, узлу и хранилищу
• Фильтруйте по VMID
• Удаляйте отдельные файлы копий

Восстановление

1. Выберите файл копии из списка
2. Нажмите Restore
3. Укажите:
   • Целевое хранилище для восстановления
   • Новый VMID (опционально, оставить оригинал или назначить новый)
   • Start after restore (опционально)
4. Восстановление выполняется как задача Proxmox (возвращается UPID для отслеживания)

⚠️ Восстановление в существующий VMID перезапишет его!

Запланированные задания резервного копирования

Автоматизируйте регулярные копии с помощью cron-планирования.

Создание задания

Server: выбрать сервер Proxmox
Node: целевой узел
VMIDs: список через запятую (напр., 100,101,102)
Storage: назначение копии
Mode: snapshot / suspend / stop
Compress: zstd / lzo / gzip / none
Cron: стандартное 5-полевое cron-выражение
Enabled: переключатель вкл/выкл

Примеры cron-выражений

Выражение	Значение
0 2 * * *	Каждый день в 02:00
0 3 * * 0	Каждое воскресенье в 03:00
0 1 * * 1-5	Будни в 01:00
30 4 1 * *	Первый день каждого месяца в 04:30

Политики хранения

Настройте, сколько копий хранить автоматически:

Параметр	Описание	По умолчанию
keep_last	Хранить N последних копий	3
keep_daily	Одну в день в течение N дней	7
keep_weekly	Одну в неделю в течение N недель	4
keep_monthly	Одну в месяц в течение N месяцев	6

Управление заданиями

• List jobs — все задания (админы видят все; пользователи — свои)
• Enable/disable — переключить без удаления
• Edit — изменить расписание, хранение, хранилище
• Delete — удалить задание и его запись в APScheduler

Отслеживание задач

Каждая операция копирования (создание / восстановление / удаление) возвращает UPID Proxmox. Используйте его для опроса статуса и логов:

# Статус задачи
GET /api/backups/task/{server_id}/{node}/{upid}

---

🌐 IPAM

Сети

Создавайте сети для организации IP-пространства:

Name: Production Network
CIDR: 192.168.1.0/24
VLAN: 100
Gateway: 192.168.1.1
DNS: 8.8.8.8, 8.8.4.4
Proxmox Server: выбрать сервер
Proxmox Node: выбрать узел (предотвращает назначение IP между серверами)

Пулы IP

Пулы задают диапазоны для автоматического выделения:

Pool: Web Servers
Start: 192.168.1.10
End: 192.168.1.50

Статус IP

Статус	Описание
🟢 Available	Свободен
🔵 Allocated	Назначен ВМ
🟠 Reserved	Зарезервирован

---

💻 Удалённое выполнение команд

Требования

• QEMU Guest Agent установлен и запущен в ВМ
• ВМ должна быть запущена

Установка Guest Agent

Debian/Ubuntu:

apt install qemu-guest-agent
systemctl enable --now qemu-guest-agent

CentOS/RHEL/AlmaLinux:

yum install qemu-guest-agent
systemctl enable --now qemu-guest-agent

Windows: Скачайте virtio-win drivers

Использование

1. Откройте детали ВМ
2. Перейдите на вкладку Commands
3. Введите команду или выберите из быстрых команд
4. Нажмите Execute

Быстрые команды

Команда	Описание
df -h	Использование диска
free -h	Использование памяти
uptime	Время работы
ps aux	Список процессов
systemctl status	Статус служб

Ограничения

• Таймаут: 30 секунд
• Интерактивные команды не поддерживаются
• Требуется Guest Agent

---

📊 Мониторинг

Метрики в реальном времени

• CPU: суммарная нагрузка + по ядрам
• RAM: использовано/всего
• Диск: использовано/всего + I/O (карточки по каждому диску на вкладке Overview)
• Сеть: входящий/исходящий трафик (скорости в байт/с)
• Disk IOPS: скорости чтения/записи по каждому диску через QEMU guest agent (get_vm_fsinfo)
• Скорости сетевого I/O: живые байт/с, вычисляемые из накопительных счётчиков в metrics_broadcaster

Гранулярность данных

Источник	Гранулярность	Используется для
cluster/resources (pvestatd)	10 с	Обзор узлов и хранилищ
status/current	1 с	Метрики запущенных ВМ в реальном времени

Все запущенные ВМ опрашиваются через status/current с частотой 1 с при ограниченной конкурентности. Результаты транслируются по WebSocket.

Где отображаются метрики

Расположение	Показываемые данные
Инстанс → вкладка Overview	Карточки заполнения по дискам, карточка Network I/O, карточка Disk I/O-rate
Список инстансов	Столбцы Net I/O и Disk I/O; Disk% для LXC
Список top-loaded на дашборде	Оверлей метрик CPU, RAM, Disk, Net

Периоды графиков

• Час
• День
• Неделя
• Месяц

Оповещения

Пороговые значения для уведомлений:

Метрика	Warning	Critical
CPU	80%	90%
RAM	85%	95%
Диск	90%	95%

---

🔒 Безопасность

Обзор

PVEmanager включает комплексные функции безопасности для защиты вашей инфраструктуры.

RBAC v2 — контроль доступа на основе ролей

Это тот раздел, который стоит прочитать, если RBAC кажется запутанным. Здесь модель разобрана от начала до конца: что такое право (permission), как реально проверяется запрос, что умеет каждая встроенная роль и — самое важное — как реализовано «пользователь видит только свои ВМ» (это отдельный механизм от RBAC, который легко настроить неправильно). Источники истины в бэкенде: backend/app/rbac/permissions.py (каталог прав), backend/app/rbac/engine.py (логика проверки), backend/app/rbac/migration.py (роли по умолчанию).

Ментальная модель в одном абзаце

У пользователя ровно одна роль. Роль — это просто именованная JSON-карта прав → true/false (напр., {"vm:view": true, "vm:delete": false}). Каждый защищённый эндпоинт API объявляет нужное ему право (напр., «нужно vm:create»). При каждом запросе Permission Engine смотрит на карту прав роли вызывающего и отвечает да/нет. Нет ни ACL для отдельных ресурсов, ни рабочих «scope» у прав — право либо выдано роли, либо нет. Единственное кажущееся исключение — «пользователи видят только свои инстансы» — вообще не является правом: это отдельный фильтр по владельцу, описанный в конце раздела.

Формат права

Каждое право — атомарная строка:

resource:action

• resource — над чем вы действуете (vm, backup, user, …).
• action — что вы делаете (view, create, delete, …).

Примеры: vm:view (видеть ВМ), server:create (добавить сервер Proxmox), log:export (скачать логи аудита), role:manage (полное администрирование ролей).

Про :scope. Технически dataclass права поддерживает третий сегмент :scope, но ни одно встроенное право его не использует — все реальные права глобальные (resource:action). Игнорируйте scope при проектировании ролей; изоляция арендаторов реализована через владельца, а не через scope :own. (В старых версиях этой вики документировались вымышленные коды вроде vms:view:own — их никогда не было в коде, и они удалены.)

Как на самом деле работает проверка права (движок)

Когда эндпоинт спрашивает «есть ли у пользователя X:Y?», PermissionEngine.has_permission применяет правила по порядку и возвращает true на первом совпадении:

1. Обход для админа. Если пользователь — администратор (is_admin или роль с именем admin), ответ всегда да — админы неявно держат все права и никогда не блокируются.
2. Прямая выдача. Точный код присутствует и равен true в карте роли (vm:create есть в роли → да).
3. Wildcard-выдача. Роль держит resource:* (напр., vm:* даёт все действия vm:). Wildcard не используется встроенными ролями, но вы можете добавить его в кастомные роли.
4. manage подразумевает частые действия. Если роль держит resource:manage, движок также выдаёт эти действия для ресурса: view, list, update, start, stop, restart. Так vm:manage в одиночку позволяет смотреть/редактировать/управлять питанием ВМ, не перечисляя эти действия отдельно. ⚠️ Учтите: manage не подразумевает create или delete — выдавайте их явно.

Если ни одно правило не совпало, доступ отклоняется с HTTP 403 Permission denied: X:Y.

Точки применения. Эндпоинты защищают доступ через FastAPI-зависимость PermissionChecker (Depends(PermissionChecker("vm:create"))) или inline-вызов require_permission(user, "vm:create"). Фронтенд независимо скрывает пункты меню, на которые у пользователя нет прав (см. таблицу соответствия ниже), но реальной границей безопасности является именно проверка на бэкенде.

requires — зависимости прав

Многие права объявляют предпосылки (поле requires в permissions.py). Они выражают логические зависимости — напр., vm:create requires vm:view + template:view; vm:execute requires vm:console.

Важно: requires — это документация / подсказка для UI, а не проверка в рантайме — движок не выдаёт предпосылки автоматически. Собирая кастомную роль, отмечайте предпосылки сами, иначе функция может работать наполовину (напр., пользователь, который может vm:create, но не имеет vm:view, не увидит только что созданную ВМ).

Полный каталог прав

Сгруппировано по ресурсам. «Подразумевается manage» означает, что движок выдаёт это бесплатно, когда роль держит <resource>:manage (правило 4 выше).

Дашборд

Право	Что открывает
dashboard:view	Доступ к странице Дашборда и обзорной статистике

Серверы Proxmox и кластер (server, cluster)

Право	Что открывает
server:view	Видеть список серверов/узлов и статус
server:create	Добавить новый сервер Proxmox
server:update	Редактировать параметры подключения сервера
server:delete	Удалить сервер Proxmox
server:manage	Полное управление сервером, включая кластерные операции (требует server:view)
cluster:manage	Создание кластеров, присоединение/исключение узлов (требует server:view)

Виртуальные машины (vm)

Право	Что открывает
vm:view	Видеть ВМ (с учётом фильтра владельца — см. ниже)
vm:create	Создавать ВМ (требует vm:view, template:view)
vm:update	Менять конфигурацию ВМ (CPU/RAM/диск)
vm:delete	Удалять ВМ
vm:start / vm:stop / vm:restart	Действия питания
vm:console	Консоль noVNC / xterm.js
vm:migrate	Миграция между узлами одного кластера
vm:remote_migrate	Миграция в другой зарегистрированный кластер (требует vm:migrate)
vm:execute	Выполнять команды через QEMU guest agent (требует vm:console)
vm:manage	Полное управление ВМ и глобальный флаг «видеть все инстансы» (см. раздел про изоляцию)

LXC-контейнеры (lxc) — та же структура, что у VM: view, create, update, delete, start, stop, restart, console, migrate, remote_migrate. (Отдельного lxc:manage нет; листинг/питание контейнеров управляется действиями lxc:* и тем же фильтром владельца, что и ВМ.)

Шаблоны и образы (template)

Право	Что открывает
template:view	Просматривать шаблоны ОС
template:create / template:update / template:delete	Управлять записями шаблонов
template:manage	Полное управление шаблонами, включая страницу Images (скачивание облачных образов)

Хранилище (storage): storage:view, storage:manage. Резервные копии (backup): backup:view, backup:create, backup:restore, backup:delete, backup:manage (хранилища + запланированные задания). IPAM (ipam): ipam:view, ipam:manage. Сети (network): network:view, network:manage (интерфейсы узла + зоны/vnet/подсети SDN). Firewall (firewall): firewall:view, firewall:manage (правила датацентра/узла/ВМ, группы, IP-наборы). Администрирование узла (node): node:view, node:manage (службы systemd, APT), node:upgrade (apt dist-upgrade), node:power (перезагрузка/выключение физического узла). Пулы ресурсов (pool): pool:view, pool:manage. PVE-доступ (access): access:view, access:manage (realm-ы аутентификации и API-токены Proxmox). App Store (app): app:view (каталог + Мои приложения), app:install, app:manage (синхронизация, обновление, откат, удаление). Скрипты (script): script:view, script:execute, script:manage (редактирование скриптов и git-источников).

Пользователи, квоты и роли (user, quota, role)

Право	Что открывает
user:view	Видеть список пользователей
user:create / user:update / user:delete	Управлять учётными записями
user:manage	Полное администрирование пользователей, включая управление SSH-ключами других пользователей
quota:view / quota:manage	Читать / задавать квоты ресурсов пользователей (требует user:view)
role:view	Видеть роли и их права
role:create / role:update / role:delete	Управлять ролями
role:manage	Полное администрирование ролей, включая назначение (требует role:view, user:view)

Логи (log): log:view, log:export, log:delete. Настройки (setting): setting:view, setting:update (настройки панели), setting:manage (безопасность и расширенные настройки). Эти права относятся только к настройкам панели — собственная учётная запись пользователя (профиль, пароль, 2FA, SSH-ключи, предпочтения уведомлений) живёт на /profile, ограничена самим пользователем и не требует никаких прав. Уведомления (notification): notification:view, notification:manage.

Делегированное редактирование ролей. Не-админ с role:manage может выдавать только те права, которыми владеет сам (can_assign_permission / validate_role_permissions). Это предотвращает эскалацию привилегий — нельзя раздать доступ, которого у вас нет. Админы освобождены от этого и могут выдавать что угодно.

Какое право открывает какую страницу в меню

Фронтенд (frontend/src/lib/nav-items.ts) скрывает пункт меню, если пользователь не админ и не держит указанное право. Пункты без права — только для админа. То же право защищает и сам маршрут (RequirePermission в frontend/src/components/shared/route-guards.tsx), поэтому скрытую страницу нельзя открыть вводом URL — при отказе пользователя перебрасывает на первую доступную ему страницу.

Пункт меню	Требуемое право
Dashboard	dashboard:view
Instances	vm:view
Nodes	server:view
Cluster	cluster:manage
Templates	template:view
Images	template:manage
Backups	backup:view
Tasks	vm:view
App Store / My Apps	app:view
Scripts	script:view
IPAM	ipam:view
Networks	server:manage
Users	user:view
Workspaces	(только админ)
Logs	log:view
Settings (настройки панели)	setting:view
Профиль (меню пользователя, не сайдбар)	(без права — любой вошедший)

Роли по умолчанию (встроенные)

Четыре роли пересоздаются/обновляются при каждом старте функцией ensure_default_roles_new_format. Это системные (is_system) роли. Логика посева только добавляет отсутствующие ключи прав — она никогда не перезаписывает ключи, которые админ уже переключил в UI, — поэтому ваши правки этих ролей переживают обновления. Новые права, добавленные при обновлении версии, также добавляются (backfill) к кастомным ролям, которые уже держат соответствующее «зонтичное» право (backfill_granular_permissions), поэтому кастомная роль на базе server:manage автоматически получает новые ключи node:* / network:* вместо молчаливой потери доступа.

Роль	Назначение	Что может делать
admin	Администратор платформы	Всё. Держит каждое право и обход is_admin — видит все серверы, все инстансы (независимо от владельца), всех пользователей, настройки, безопасность.
moderator	Оператор без прав админа	Смотреть дашборд/серверы; создавать + управлять питанием + консоль ВМ и LXC; смотреть шаблоны/хранилище/firewall/сеть/узел/пулы/копии/IPAM/пользователей/логи; создавать копии; экспортировать логи; управлять уведомлениями. Нет удаления, изменения настроек, управления пользователями/ролями. Заметьте: без vm:manage модератор всё равно подчиняется фильтру владельца (см. ниже).
user	Стандартный арендатор (стиль VPS)	Смотреть + start/stop/restart/console для своих ВМ и LXC; смотреть шаблоны/хранилище/firewall/сеть/узел/пулы/IPAM; управлять своими уведомлениями. Собственный профиль, SSH-ключи и квота живут на /profile и не требуют прав, поэтому у роли намеренно нет setting:view (он открыл бы страницу настроек панели). Нет create/delete по умолчанию, нет дашборда. Ограничен своими инстансами, так как не имеет vm:manage.
demo	Read-only витрина	Только просмотр: дашборд, серверы, ВМ, LXC, шаблоны, хранилище, firewall, сеть, узел, пулы, IPAM. Ни действий питания, ни записи.

Точный JSON каждой роли лежит в NEW_DEFAULT_ROLES в backend/app/rbac/migration.py — сверяйтесь с ним, если нужен побайтовый набор прав.

Управление ролями в UI

1. Откройте Пользователи (нужно role:view; для редактирования — role:manage или админ).
2. Перейдите на вкладку Roles → New Role или отредактируйте существующую.
3. Права сгруппированы по категориям (Virtual Machines, Backups, User Management, …). Отметьте нужные чекбоксы.
4. Не забудьте отметить и предпосылки (requires) — движок не включает их автоматически.
5. Назначьте роль пользователю в диалоге редактирования пользователя.

Системные роли (admin/moderator/user/demo) удалить нельзя, но их наборы прав можно настраивать (ваши изменения сохраняются при обновлениях).

Legacy-формат прав

Старые релизы использовали точечный формат (vms.view, proxmox.manage). Он отображается на новый двоеточный формат через LEGACY_PERMISSION_MAP и конвертируется один раз в базе данных при старте, поэтому трансляция в рантайме не нужна. Вы всё ещё можете вписать legacy-код в кастомную роль — он разрешается прозрачно, — но новые роли должны использовать форму resource:action.

---

Изоляция пользователей — «каждый видит только свои инстансы»

Это функция, которую чаще всего путают с RBAC. Это не право. Это отдельный фильтр по владельцу, наложенный поверх прав vm:*/lxc:*. Понимание этого разделения — ключ к правильной настройке арендаторов.

Правило

Вызывающий	Видит / управляет
Админ или роль с именем admin	Всеми инстансами
Любая роль, держащая vm:manage	Всеми инстансами
Все остальные (включая стоковую роль user)	Только инстансами, которыми владеет (owner_id == user.id)

Решение принимает can_view_all_instances в backend/app/api/proxmox/_helpers.py. Обратите внимание: ключ «видеть всё» — это vm:manage, а не vm:view. Стоковая роль user намеренно несёт только vm:view, чтобы страница Instances вообще работала — vm:view сам по себе никогда не раскрывает ВМ других арендаторов.

⚠️ Самая частая ошибка конфигурации: выдать vm:manage роли user (или кастомной «арендаторской» роли), чтобы «дать им управлять своими ВМ». Это включает глобальный обзор, и каждый пользователь внезапно видит все ВМ в панели. Для арендаторов выдавайте гранулярные действия (vm:update, vm:delete, vm:start, …) вместо vm:manage. Резервируйте vm:manage для операторов/админов, которые должны видеть всё.

Как владение применяется везде

Владение проверяется не только в списке инстансов, но и на каждой поверхности, доступной непривилегированному пользователю:

• Список инстансов и действия над одним инстансом — check_vm_access / require_vm_access проверяют owner_id перед любой операцией view/питание/консоль/снимок/копия/удаление.
• Эндпоинты живых ресурсов — дашборд (/api/resources/all) и страница узла/сервера (/api/{server_id}/resources) вызывают get_owned_vmids и фильтруют живой листинг Proxmox до принадлежащих VMID, поэтому пользователь только с server:view не может перечислить ВМ других владельцев через страницу узла.

Назначение владельца

1. Автоматически — когда пользователь развёртывает VM/LXC, он становится её owner_id.
2. Вручную (админ) — откройте инстанс → кнопка Owner → выберите пользователя → Save. REST API см. в Владелец ВМ / LXC.

Инстансы, синхронизированные из Proxmox до появления владения, имеют owner_id = NULL (видны только привилегированным пользователям). Массово назначить им владельца:

docker compose exec app python assign_instances_owner.py

RBAC vs Workspaces vs назначение серверов vs владение

Эти четыре механизма складываются — не-админ должен пройти все применимые фильтры:

Слой	На какой вопрос отвечает	Где настраивается
Роль RBAC	Какие действия пользователь вообще может выполнять?	Пользователи → Roles
Workspaces	Какие серверы пользователю разрешено видеть?	Рабочие области
Назначение серверов	Какие конкретные серверы внутри этих областей?	Назначение серверов пользователю
Владение	Какие отдельные ВМ/LXC (если нет vm:manage/админа)?	Владелец ВМ / LXC

---

Снимки (в контексте безопасности)

Снимки позволяют сохранять и восстанавливать состояние ВМ и контейнеров.

Снимки ВМ

# Список снимков
GET /api/{server_id}/vm/{vmid}/snapshots?node={node}

# Создать снимок
POST /api/{server_id}/vm/{vmid}/snapshots?node={node}
{
  "snapname": "before-update",
  "description": "Before system update",
  "vmstate": false  # Включить состояние RAM (опционально)
}

# Удалить снимок
DELETE /api/{server_id}/vm/{vmid}/snapshots/{snapname}?node={node}

# Откатить к снимку
POST /api/{server_id}/vm/{vmid}/snapshots/{snapname}/rollback?node={node}&start=false

Снимки контейнеров

Те же эндпоинты, но используйте /container/ вместо /vm/.

SDN (Software Defined Networking)

Управление зонами SDN и виртуальными сетями Proxmox.

Проверка доступности SDN

GET /api/servers/{server_id}/sdn/status

Возвращает:

{
  "server_id": 1,
  "sdn_available": true,
  "pending_changes": false
}

Типы зон

Тип	Описание
simple	Базовая изолированная сеть
vlan	Разделение на основе VLAN
vxlan	Overlay-сеть VXLAN
evpn	EVPN/VXLAN с BGP

Эндпоинты SDN API

# Список зон
GET /api/servers/{server_id}/sdn/zones

# Создать зону
POST /api/servers/{server_id}/sdn/zones
{
  "zone": "myzone",
  "type": "simple"
}

# Обновить зону
PUT /api/servers/{server_id}/sdn/zones/{zone}
{
  "mtu": 1500,
  "dns": "8.8.8.8"
}

# Список VNet
GET /api/servers/{server_id}/sdn/vnets

# Создать VNet
POST /api/servers/{server_id}/sdn/vnets
{
  "vnet": "vnet1",
  "zone": "myzone",
  "alias": "Production Network"
}

# Обновить VNet
PUT /api/servers/{server_id}/sdn/vnets/{vnet}
{
  "alias": "Updated Alias",
  "tag": 100
}

# Создать подсеть (с опциональным авто-созданием IPAM)
POST /api/servers/{server_id}/sdn/vnets/{vnet}/subnets
{
  "subnet": "10.0.0.0/24",
  "gateway": "10.0.0.1",
  "snat": true,
  "create_ipam_network": true
}

# Удалить подсеть (опционально удалить связанную сеть IPAM)
DELETE /api/servers/{server_id}/sdn/vnets/{vnet}/subnets/{subnet_cidr}?delete_ipam_network=true

# Применить изменения (обязательно после модификаций)
POST /api/servers/{server_id}/sdn/apply

Сетевые интерфейсы узлов

Управление сетевыми интерфейсами (мосты, bond-ы, VLAN) напрямую на узлах Proxmox.

Доступ к странице «Сети»

1. Откройте Networks из бокового меню (требует право server:manage; записи в SDN/интерфейсы требуют network:manage)
2. Выберите сервер из выпадающего списка
3. Страница показывает две вкладки: SDN и Node Interfaces

Управление интерфейсами узла

Действие	Описание
List interfaces	Просмотр всех интерфейсов на выбранном узле
Create interface	Создать мост, bond, VLAN или alias
Edit interface	Изменить IP, маску, шлюз, порты и т.д.
Delete interface	Удалить конфигурацию интерфейса
Apply config	Активировать ожидающие изменения
Revert config	Откатить к рабочей конфигурации

⚠️ Всегда применяйте изменения после создания или редактирования интерфейсов. Изменения находятся в staging до применения.

Эндпоинты Node Network API

# Список узлов сервера
GET /api/servers/{server_id}/nodes

# Список интерфейсов узла
GET /proxmox/api/servers/{server_id}/nodes/{node}/networks

# Детали интерфейса
GET /proxmox/api/servers/{server_id}/nodes/{node}/networks/{iface}

# Создать интерфейс
POST /proxmox/api/servers/{server_id}/nodes/{node}/networks
{
  "iface": "vmbr1",
  "type": "bridge",
  "address": "10.0.0.1",
  "netmask": "255.255.255.0",
  "bridge_ports": "ens4",
  "autostart": true
}

# Обновить интерфейс
PUT /proxmox/api/servers/{server_id}/nodes/{node}/networks/{iface}
{
  "address": "10.0.0.2"
}

# Удалить интерфейс
DELETE /proxmox/api/servers/{server_id}/nodes/{node}/networks/{iface}

# Применить ожидающую конфигурацию сети
PUT /proxmox/api/servers/{server_id}/nodes/{node}/networks/apply

# Откатить ожидающие изменения
DELETE /proxmox/api/servers/{server_id}/nodes/{node}/networks/revert

Совместимость со старым форматом

Старый формат прав (vms.view, proxmox.manage) по-прежнему поддерживается и автоматически конвертируется в новый формат.

Блокировка IP

Автоматическая и ручная блокировка IP защищает от brute-force атак.

Автоматическая блокировка

Когда пользователь несколько раз не может войти с одного IP:

1. После порога (по умолчанию: 10) неудачных попыток
2. IP блокируется на настроенное время (по умолчанию: 60 минут)
3. Блокировка может быть временной или постоянной

Ручная блокировка

Администраторы могут вручную блокировать IP:

• Блокировка с указанием причины
• Задать длительность или сделать постоянной
• Просмотр списка заблокированных IP
• Разблокировка по мере необходимости

Управление сессиями

Отслеживание и контроль активных пользовательских сессий.

Функция	Описание
Active Sessions	Просмотр всех вошедших пользователей
Device Info	Определение браузера и устройства
IP Tracking	Логирование IP-адреса сессии
Single Session	Опция разрешить только одну сессию на пользователя
Force Logout	Завершить любую сессию

Защита входа

Настройка	По умолчанию	Описание
Max Login Attempts	5	Попыток до блокировки аккаунта
Lockout Duration	30 мин	Как долго аккаунт заблокирован
IP Block Threshold	10	Неудачных попыток до блокировки IP
IP Block Duration	60 мин	Как долго IP заблокирован

Настройки безопасности

Доступ через Настройки → Безопасность:

Настройка	По умолчанию	Описание
Session Timeout	60 мин	Авто-выход после бездействия
Single Session	Выкл	Разрешить только одну сессию на пользователя
Password Min Length	8	Минимум символов пароля
Require Uppercase	Да	Пароль должен содержать заглавные
Require Lowercase	Да	Пароль должен содержать строчные
Require Numbers	Да	Пароль должен содержать цифры
Require Special	Нет	Пароль должен содержать спецсимволы
Password Expiry	0 (никогда)	Дней до истечения пароля
API Rate Limit	60/мин	Запросов API в минуту

Лучшие практики

1. Смените пароли по умолчанию сразу после установки
2. Включите SSL/HTTPS в продакшне
3. Используйте надёжные пароли с требованиями к сложности
4. Мониторьте попытки входа на предмет подозрительной активности
5. Настройте файрвол для ограничения доступа к панели
6. Регулярно обновляйтесь для получения патчей безопасности

---

📝 Логи и аудит

Обзор

Страница Логи (/logs в боковом меню) даёт админам полный поисковый обзор таблицы audit_logs панели. Она дополняет ленту активности дашборда более глубокой фильтрацией, пагинацией и агрегированной статистикой за 24 часа.

Макет страницы

1. Карточки статистики (окно 24ч) — всего событий, число ошибок, неудачные входы, число строк на текущей странице
2. Фильтры — свободный поиск (по сообщению и имени пользователя) и выпадающий список уровней из GET /logs/api/levels
3. Таблица логов — время, бейдж уровня, категория, имя пользователя, сообщение
4. Пагинация — управляется API (page, limit)

Уровни логов

Уровень	Цвет	Описание
INFO	🔵 Синий	Информационные события
SUCCESS	🟢 Зелёный	Успешные операции
WARNING	🟡 Жёлтый	Некритические предупреждения
ERROR	🔴 Красный	Сбои
CRITICAL	🟣 Фиолетовый	Критические события безопасности / системы

Справочник API

Метод	Эндпоинт	Описание
GET	/logs/api/logs	Список записей аудита (с пагинацией)
GET	/logs/api/stats	Агрегированная статистика (по умолчанию 24ч)
GET	/logs/api/levels	Различные уровни для выпадающего фильтра
GET	/logs/api/categories	Различные категории

Параметры запроса для GET /logs/api/logs

Имя	Тип	Описание
search	string	Свободный поиск по сообщению/имени пользователя
level	string	Фильтр по уровню (INFO, ERROR, …)
category	string	Фильтр по категории
username	string	Фильтр по имени пользователя
page	int	Номер страницы (с 1)
limit	int	Размер страницы (по умолчанию 50)
date_from	ISO date	Нижняя граница (включительно)
date_to	ISO date	Верхняя граница (включительно)

Форма ответа

{
  "logs": [
    {
      "id": 1234,
      "timestamp": "2026-06-04T10:21:33Z",
      "level": "INFO",
      "category": "vm",
      "username": "admin",
      "message": "VM 100 started on node pve1"
    }
  ],
  "total": 532,
  "page": 1,
  "limit": 50,
  "pages": 11
}

Контроль доступа

Страница «Логи» защищена правом log:view в RBAC v2. Стоковая роль admin имеет его; moderator имеет доступ только на чтение; роли user и demo эту страницу не видят.

Хранение

Хранение логов управляется через Настройки → Панель → Дни хранения логов (добавлено в v1.5.2). Записи старше настроенного числа дней удаляются автоматически. По умолчанию — 30 дней.

---

🔑 Управление SSH-ключами

Обзор

У каждого пользователя есть личная библиотека SSH-ключей. Ключи из библиотеки можно выбирать при развёртывании ВМ или LXC-контейнеров, избавляя от необходимости каждый раз вставлять публичный ключ вручную.

Управление SSH-ключами

1. Перейдите в Настройки → SSH Keys
2. Нажмите Add Key
3. Заполните:
   • Name — читаемая метка (напр., Work laptop)
   • Public Key — вставьте полный публичный ключ (ssh-rsa ..., ssh-ed25519 ... и т.д.)
   • Private Key (опционально) — хранится в базе в зашифрованном виде
   • Comment (опционально) — свободная заметка
4. Нажмите Save

SHA-256 отпечаток вычисляется и отображается автоматически.

Использование ключей при развёртывании

• В мастере создания инстанса на шаге Config показан селектор ключей
• Обычные пользователи видят свои ключи
• Админы, выбирающие владельца, видят ключи владельца в дополнение к своим

Синхронизация SSH-ключей при смене владельца

Когда администратор переназначает ВМ или LXC другому пользователю (через диалог Владелец на странице инстанса), панель автоматически:

1. Удаляет публичный SSH-ключ предыдущего владельца из ciuser/authorized keys инстанса
2. Внедряет публичный SSH-ключ нового владельца

Учётные данные для доступа всегда соответствуют текущему владельцу — ручная ротация ключей не нужна.

Управление ключами админом

Админы (пользователи с правом user:manage) могут просматривать и управлять SSH-ключами любого пользователя:

GET  /api/ssh-keys/user/{user_id}   — список ключей конкретного пользователя

Справочник API

Метод	Эндпоинт	Описание
GET	/api/ssh-keys	Список своих SSH-ключей
POST	/api/ssh-keys	Добавить новый ключ
PUT	/api/ssh-keys/{id}	Обновить ключ
DELETE	/api/ssh-keys/{id}	Удалить ключ
GET	/api/ssh-keys/user/{user_id}	Список ключей любого пользователя (админ)

---

🌍 Локализация

Поддерживаемые языки

• 🇷🇺 Русский (полное покрытие начиная с v1.16.0)
• 🇺🇸 Английский (по умолчанию)
• 🇺🇿 Узбекский (частично)

v1.16.0 завершил полный проход по переводам: все ранее захардкоженные или непереведённые строки на дашборде, в инстансах, образах, App Store, нодах, ролях, хранилищах, скриптах, сертификатах, графиках, мастере, массовой миграции и реалмах доступа теперь корректно переведены на русский и английский.

Переключение языка

Начиная с v1.5.2, язык является пользовательской настройкой, хранящейся в базе данных.

1. Настройки → Profile
2. Выберите язык в выпадающем списке Language
3. Нажмите Save — интерфейс переключится немедленно без перезагрузки страницы

Добавление нового языка

Переводы хранятся плоскими JSON-файлами в backend/app/locales/. Чтобы добавить новый язык, просто создайте новый файл — изменения кода не требуются:

# Создать файл локали для узбекского
cp backend/app/locales/en.json backend/app/locales/uz.json
# Затем переведите значения в uz.json

Имя файла становится кодом языка (uz.json → "uz"). Панель подхватит его при следующем старте (или вызовите I18nService.reload() в рантайме).

Структура: каждый файл — плоский JSON-объект {"key": "переведённая строка"}. Ключи должны совпадать с существующими ключами в ru.json / en.json.

---

⚙️ Настройки

Профиль пользователя

• Полное имя
• Email (для уведомлений)
• Смена пароля
• Язык — язык UI пользователя (хранится в колонке БД users.language); применяется сразу при сохранении через i18n.changeLanguage(); у каждой учётной записи своя настройка
• Публичный SSH-ключ — хранится в профиле пользователя и автоматически внедряется в VM/LXC при развёртывании через cloud-init

Настройки панели

Параметр	Описание	По умолчанию
Refresh interval	Частота обновления данных	30 сек
Log retention	Сколько дней хранить логи	30 дней
Panel name	Отображаемое имя (read-only в UI, можно переопределить в БД)	env PANEL_NAME

Примечание: настройка языка перенесена с вкладки «Панель» на вкладку «Профиль» в v1.5.2 — теперь каждый пользователь управляет своим языком независимо.

Обновления системы и выбор репозитория

Панель поддерживает автоматические обновления из Git-репозитория. Можно выбрать, какой репозиторий использовать:

Доступные варианты:

1. git.tzim.uz/markmorado/pvemanager (по умолчанию) — основной репозиторий
2. github.com/markmorado/pvemanager — зеркало
3. Кастомный репозиторий — ваш форк или зеркало

Как сменить репозиторий:

1. Перейдите в Настройки → System Updates
2. В выпадающем списке «Git Repository» выберите предпочтительный репозиторий
3. Для кастомного репозитория:
   • Выберите «Custom Repository...» из списка
   • Введите полный URL (напр., https://git.example.com/user/repo)
   • Нажмите Save

Настройка репозитория влияет на:

• Проверку обновлений (сравнение версий)
• Получение changelog
• Процесс обновления панели

Примечание: убедитесь, что выбранный репозиторий содержит валидные файлы VERSION и CHANGELOG.md.

Как работает процесс обновления

Начиная с v1.1.1, обновления выполняются сторожевым процессом на хосте (pvemanager-update.service), а не внутри контейнера. Это решает фундаментальную проблему, когда docker compose down убивал бы внутриконтейнерный скрипт до завершения пересборки.

[UI: "Update Panel"] → perform_update() → пишет .update_trigger
                                                   ↓ (опрос каждые 3 сек)
                                [pvemanager-update.service на ХОСТЕ]
                                обнаруживает триггер → удаляет его → выполняет:
                                  git pull
                                  docker compose down
                                  docker compose build --no-cache app
                                  docker compose up -d

Логи: ./logs/update_host.log (видны из панели)

Установка сторожа обновлений

Сторож нужно установить один раз на хост-машине. Он автоматически настраивается при запуске deploy.sh, либо его можно установить/переустановить отдельно:

# Установка или переустановка (требует root для systemd)
sudo ./deploy.sh --watchdog

# Проверить, что запущен
systemctl status pvemanager-update

# Смотреть живой лог обновления
tail -f logs/update_host.log

Требования:

• systemd на хосте
• Пользователь, запускающий deploy.sh --watchdog (или $SUDO_USER), должен быть в группе docker (root разрешён всегда)
• Volume .:/project:rw в compose.yml должен присутствовать (он есть по умолчанию)

Примечание для non-root: если вы запустите ./deploy.sh --watchdog без sudo, он сгенерирует готовые файлы в ./systemd/ и напечатает точные sudo-команды для их установки.

Настройки уведомлений

• In-App: всегда включены
• Email: требует настройки SMTP
• Telegram: требует токен бота

---

🛠️ Инструмент pve CLI

Начиная с v1.1.2, PVEmanager поставляется со скриптом pve — удобным CLI-ярлыком для частых задач управления.

Установка

# Требует root (копирует скрипт в /usr/local/bin/pve и правит путь проекта)
sudo ./deploy.sh --install-cli

После установки команда pve доступна системно.

Использование

pve help           # Показать все доступные команды
pve logs           # Смотреть живые логи app
pve restart        # Перезапустить все контейнеры
pve update         # Запустить обновление панели (через сторож)
pve exec <cmd>     # Выполнить команду внутри контейнера app
pve status         # Показать статус docker compose
pve dev            # Запустить frontend в dev-режиме (Vite HMR)
pve dev stop       # Остановить dev-режим, вернуться к production frontend

Как это работает

• deploy.sh --install-cli читает файл pve из корня проекта
• Заменяет плейсхолдер PVE_DIR фактическим путём проекта
• Записывает результат в /usr/local/bin/pve и делает исполняемым
• Перезапустите sudo ./deploy.sh --install-cli после перемещения каталога проекта

Примечание: бинарник pve отражает каталог проекта на момент установки. Если вы перемещаете проект — переустановите CLI.

---

🔌 Справочник API

Аутентификация

# Получить токен
POST /api/auth/login
Content-Type: application/json

{
    "username": "admin",
    "password": "admin123"
}

# Ответ
{
    "access_token": "eyJ...",
    "token_type": "bearer"
}

Использование токена

curl -H "Authorization: Bearer eyJ..." \
     http://localhost:8000/api/notifications

Основные эндпоинты

Метод	Эндпоинт	Описание
GET	/api/servers	Список серверов Proxmox
GET	/api/servers/{id}	Получить конкретный сервер
POST	/api/servers	Добавить сервер
PUT	/api/servers/{id}	Обновить сервер
DELETE	/api/servers/{id}	Удалить сервер
POST	/api/servers/{id}/test	Проверить подключение
GET	/api/servers/{id}/resources	ВМ и контейнеры сервера
POST	/api/servers/{id}/vm/{vmid}/{action}	Управление ВМ (start/stop/restart)
POST	/api/servers/{id}/container/{vmid}/{action}	Управление контейнером (start/stop/restart)
GET	/api/servers/{id}/vm/{vmid}/status	Статус ВМ
GET	/api/servers/{id}/container/{vmid}/status	Статус контейнера
GET	/ipam/api/networks	Список сетей IPAM
POST	/ipam/api/networks	Создать сеть IPAM
GET	/ipam/api/allocations	Список выделений IP
POST	/ipam/api/allocations	Создать выделение IP
GET	/templates/api/groups	Список групп шаблонов
GET	/templates/api/templates	Список шаблонов ОС
POST	/templates/api/templates	Создать шаблон ОС
GET	/api/notifications	Список уведомлений
PATCH	/api/notifications/{id}/read	Отметить прочитанным
DELETE	/api/notifications/{id}	Удалить уведомление
GET	/api/users	Список пользователей (только админ)
POST	/api/users	Создать пользователя (только админ)
GET	/settings/api/panel	Получить настройки панели
PUT	/settings/api/panel	Обновить настройки панели
GET	/logs/api/logs	Получить логи аудита
GET	/logs/api/stats	Статистика логов
GET	/api/backups/storages/{server_id}	Список хранилищ Proxmox
GET	/api/backups/scan-nfs/{server_id}	Сканировать NFS-сервер на экспорты
POST	/api/backups/create	Создать копию VM/LXC
POST	/api/backups/restore	Восстановить VM/LXC из копии
GET	/api/backups/list/{server_id}	Список файлов копий
DELETE	/api/backups/{server_id}/backup	Удалить файл копии
GET	/api/backups/jobs	Список запланированных заданий
POST	/api/backups/jobs	Создать запланированное задание
GET	/api/{server_id}/ha/status	Статус HA для всех ВМ
POST	/api/{server_id}/ha/{vm_type}/{vmid}/add	Добавить ВМ в HA-группу
DELETE	/api/{server_id}/ha/{vm_type}/{vmid}/remove	Убрать ВМ из HA
POST	/api/sync-vms	Принудительная синхронизация ВМ из Proxmox
GET	/api/servers/{id}/nodes	Список узлов сервера
PUT	/api/servers/{id}/sdn/zones/{zone}	Обновить зону SDN
PUT	/api/servers/{id}/sdn/vnets/{vnet}	Обновить VNet SDN
DELETE	/api/servers/{id}/sdn/vnets/{vnet}/subnets/{cidr}	Удалить подсеть SDN

Документация Swagger

Доступна по адресу: http://localhost:8000/docs

---

🗂️ Рабочие области (Workspaces)

Рабочие области — это именованные группы серверов Proxmox с ограниченным доступом пользователей. Они позволяют администраторам разделять инфраструктуру и давать пользователям доступ только к их серверам.

Ключевые понятия

Понятие	Описание
Workspace	Именованная группа с опциональным цветом и описанием
Default Workspace	Создаётся автоматически; все серверы по умолчанию в ней
Назначение сервера	Один сервер может принадлежать нескольким рабочим областям
Назначение пользователя	Пользователи видят только назначенные им области

Управление рабочими областями (админ)

1. Откройте Настройки → Workspaces (пункт бокового меню) или перейдите на /workspaces
2. Нажмите New Workspace для создания
3. Назначьте серверы на вкладке Servers внутри детали области
4. Назначьте пользователей на вкладке Users

Переключение рабочих областей (боковая панель)

• Активная область показана в боковой панели под логотипом
• Кликните имя области, чтобы открыть переключатель
• Выберите область — все списки ВМ/серверов сразу фильтруются
• Выберите All Workspaces (только админ), чтобы снять фильтр

API

Метод	Эндпоинт	Описание
GET	/api/workspaces	Список областей (фильтруется для не-админов)
POST	/api/workspaces	Создать область (админ)
GET	/api/workspaces/{id}	Деталь области с серверами/пользователями
PUT	/api/workspaces/{id}	Обновить область (админ)
DELETE	/api/workspaces/{id}	Удалить область (админ)
POST	/api/workspaces/{id}/servers	Добавить сервер в область
DELETE	/api/workspaces/{id}/servers/{server_id}	Убрать сервер из области
POST	/api/workspaces/{id}/users	Добавить пользователя в область
DELETE	/api/workspaces/{id}/users/{user_id}	Убрать пользователя из области

Передавайте заголовок X-Active-Workspace: {id} в запросах API для фильтрации ответов по области.

---

👤 Назначение серверов пользователю

Назначение серверов позволяет админам напрямую связывать конкретные серверы Proxmox с отдельными пользователями. В сочетании с рабочими областями это даёт тонкий контроль: пользователь видит только серверы, которые одновременно и в его рабочей области, и явно назначены ему.

Как это работает

1. Пользователь принадлежит одной или нескольким рабочим областям
2. Админ назначает пользователю конкретные серверы (из серверов, разделяющих хотя бы одну область с пользователем)
3. Пользователь видит только пересечение: серверы-области ∩ назначенные-серверы

Управление назначениями (UI)

1. Откройте страницу Пользователи
2. Нажмите Edit для пользователя
3. На вкладке Servers — отметьте/снимите серверы; несовместимые серверы (другая область) подсвечены
4. Save — назначения применяются немедленно

REST API

Метод	Эндпоинт	Описание
GET	/api/users/{id}/servers	Назначенные серверы пользователя
GET	/api/users/{id}/server-assignments	Все серверы с флагами assigned и compatible
PUT	/api/users/{id}/servers	Задать серверы (заменяет текущий список); тело: {"server_ids": [1,2]}

Возвращает 409 workspace_conflict, если какой-либо сервер не разделяет ни одной области с пользователем.

---

🖥️ Владелец ВМ / LXC

У любой ВМ или LXC-контейнера может быть владелец — обычный пользователь, ответственный за этот инстанс. Владелец отображается в списке ВМ.

Изоляция

Владение применяется везде, где непривилегированный пользователь видит инстансы, а не только в списке инстансов. Эндпоинты живых ресурсов — /api/resources/all (дашборд) и /api/{server_id}/resources (страница узла/сервера) — фильтруют ВМ/LXC по владельцу (сопоставляя каждый vmid с кэшем vm_instances), поэтому пользователь только с proxmox.view не может видеть инстансы других владельцев через страницу узла. Админы и роли с vm:manage освобождены от этого и видят всё.

Владелец теперь проставляется автоматически при создании (vm_create/ct_create), в том числе когда ВМ создаёт админ от имени другого пользователя — деплой инжектирует SSH-ключ именно этого владельца (объединённый с любыми вставленными вручную или взятыми из библиотеки ключами), а не ключ создавшего.

Инстансы, синхронизированные из Proxmox до появления владения, или созданные до исправления выше, имеют owner_id = NULL. Разовая миграция бэкфиллит их автоматически из deploy_tasks и audit_logs (записи vm_create/ct_create/lxc_create), но только когда все доступные данные указывают на одного и того же существующего пользователя — неоднозначные случаи (например, переиспользованный VMID) намеренно остаются без владельца. Чтобы назначить владельца тому, что осталось, запустите вспомогательный скрипт из образа бэкенда:

docker compose exec app python assign_instances_owner.py

Назначение владельца (админ)

Откройте страницу деталей ВМ → кнопка Owner → выберите пользователя → Save.

REST API

Метод	Эндпоинт	Описание
GET	/api/{server_id}/vm/{vmid}/owner	Текущий владелец + список пользователей
PUT	/api/{server_id}/vm/{vmid}/owner	Задать или очистить владельца ({"user_id": null} для очистки)

---

🎯 Квоты

Квоты ресурсов на пользователя ограничивают, сколько пользователь может выделить. Ограничиваются четыре метрики, каждая суммируется по неудалённым, не-шаблонным инстансам пользователя:

Метрика	Единица	Поле квоты
Инстансы	количество	max_instances
vCPU	ядра	max_cores
RAM	МБ	max_memory_mb
Диск	ГБ	max_disk_gb

• Без ограничений по умолчанию — пользователь без строки квоты или с пустой метрикой (NULL) не ограничен по этой метрике. Админы и ненастроенные пользователи никогда не блокируются.
• Применение — развёртывание VM/LXC, которое превысит любую метрику, отклоняется с HTTP 429 и двуязычным сообщением (Превышена квота … / Quota exceeded …) с прогнозируемым значением и лимитом.
• Источник использования — текущее использование вычисляется из кэша vm_instances (owner_id), где RAM хранится в МБ, а диск — в ГБ (без конвертации).

Два уровня блокировки на клиенте

Реально применяет ограничение только backend'ный HTTP 429, но интерфейс теперь предупреждает заранее, используя в обоих местах одну и ту же функцию exhaustedMetrics() (features/instances/quota.ts), чтобы они не могли разойтись:

• Свободного места совсем не осталось (использовано ≥ лимита хотя бы по одной метрике) — сама точка входа «Создать инстанс» отключается, а подсказка называет, какие именно лимиты исчерпаны. Ни одна конфигурация не влезет, поэтому мастер даже не открывается.
• Место есть, но выбранная конфигурация его превысит — мастер открывается как обычно; начиная с шага конфигурации называется метрика, которая была бы превышена, а «Далее»/«Развернуть» заблокированы, пока запрос не уменьшат.

Ни одна из блокировок не применяется к админам — их личная квота не имеет отношения к инстансу, который они создают для кого-то другого, а показанные им цифры носят чисто информационный характер.

Управление квотами (админ)

Страница Пользователи → диалог квот. Живые полосы использования показывают текущее потребление против каждого лимита. Оставьте поле пустым для без ограничений. Требует право quota:manage (quota:view для чтения).

Self-service

Каждый пользователь видит свои лимиты и текущее использование на странице Профиль. Мастер создания инстанса показывает остаток квоты подсказкой на шаге конфигурации.

REST API

Метод	Эндпоинт	Описание
GET	/api/users/{id}/quota	Лимиты пользователя + текущее использование (требует quota:view)
PUT	/api/users/{id}/quota	Задать лимиты; null для метрики = без ограничений (требует quota:manage)
GET	/api/quota	Собственные лимиты + использование текущего пользователя (self-service)

---

🔧 Устранение неполадок

Проблемы запуска

Контейнер не запускается

# Проверить логи
docker compose logs app

# Проверить статус
docker compose ps

Ошибка подключения к базе данных

# Проверить, запущена ли БД
docker compose logs db

# Перезапустить
docker compose restart db
docker compose restart app

Проблемы Proxmox

«Connection refused»

• Проверьте IP-адрес сервера
• Проверьте, что порт 8006 открыт
• Проверьте файрвол на Proxmox

«Authentication failed»

• Проверьте логин/пароль
• Используйте формат user@pam или user@pve
• Попробуйте создать API Token

Проблемы уведомлений

Email не отправляется

1. Проверьте настройки SMTP в backend/.env
2. Для порта 465 требуется SSL
3. Для порта 587 требуется STARTTLS
4. Проверьте «пароль приложения» для Yandex/Gmail

# Проверить переменные в контейнере
docker compose exec app env | grep SMTP

Telegram не работает

1. Проверьте токен бота
2. Отправьте боту /start
3. Проверьте Chat ID
4. Убедитесь, что бот не заблокирован

Кнопка «Тест» зависает

• Проверьте логи: docker compose logs app --tail 50
• SMTP-сервер может быть недоступен
• Таймаут — 10 секунд

Проблемы VNC / терминала

«VNC connection failed» (QEMU)

• Проверьте, что ВМ запущена
• Убедитесь, что VNC включён в настройках узла Proxmox
• Попробуйте перезапустить ВМ
• Проверьте, что у API-пользователя Proxmox есть привилегия VM.Console

«Connection closed» сразу при открытии VNC

• Это была известная ошибка, исправленная в v1.3.0 (noVNC получал уже открытый WebSocket вместо URL)
• Обновитесь до v1.3.0 или новее

Терминал не подключается (LXC)

• Проверьте, что контейнер запущен (не остановлен и не приостановлен)
• Проверьте, что у API-пользователя Proxmox есть привилегия VM.Console на узле
• Проверьте логи: docker compose logs app --tail 50

Проблемы команд

«Guest Agent not running»

# В ВМ выполнить:
systemctl status qemu-guest-agent
systemctl start qemu-guest-agent

Команда зависает

• Таймаут — 30 секунд
• Не используйте интерактивные команды
• Проверьте, что ВМ отвечает

Проблемы производительности

Высокое использование памяти

# Перезапустить контейнеры
docker compose restart

# Очистить логи
docker system prune -f

Медленная загрузка страниц

• Увеличьте интервал обновления в настройках
• Проверьте сеть до сервера Proxmox

Проблемы с учётной записью

Админ забыл пароль

Если админ забыл пароль, его можно сбросить через командную строку:

Вариант 1: Сброс к паролю по умолчанию

# Выполнить внутри контейнера app
docker compose exec app python -c "
from app.db import get_db
from app.models import User
from app.auth import get_password_hash

db = next(get_db())
admin = db.query(User).filter(User.username == 'admin').first()
if admin:
    admin.hashed_password = get_password_hash('admin123')
    db.commit()
    print('Admin password reset to: admin123')
else:
    print('Admin user not found')
db.close()
"

Вариант 2: Задать свой пароль

# Замените YOUR_NEW_PASSWORD на нужный пароль
docker compose exec app python -c "
from app.db import get_db
from app.models import User
from app.auth import get_password_hash

db = next(get_db())
admin = db.query(User).filter(User.username == 'admin').first()
if admin:
    admin.hashed_password = get_password_hash('YOUR_NEW_PASSWORD')
    db.commit()
    print('Admin password has been reset')
else:
    print('Admin user not found')
db.close()
"

Вариант 3: Сброс пароля любого пользователя

# Замените USERNAME на нужное имя пользователя
docker compose exec app python -c "
from app.db import get_db
from app.models import User
from app.auth import get_password_hash

db = next(get_db())
user = db.query(User).filter(User.username == 'USERNAME').first()
if user:
    user.hashed_password = get_password_hash('newpassword123')
    db.commit()
    print('Password reset for user: USERNAME')
else:
    print('User not found')
db.close()
"

⚠️ Заметка о безопасности: после сброса пароля немедленно войдите и смените его на надёжный через веб-интерфейс.

---

❓ FAQ

Общие вопросы

В: Можно ли использовать без Proxmox? О: Нет, панель специально разработана для управления Proxmox.

В: Сколько серверов можно добавить? О: Не ограничено.

В: Поддерживается ли кластер Proxmox? О: Да, добавьте любой узел кластера.

Безопасность

В: Пароли хранятся в открытом виде? О: Нет, используется bcrypt-хэширование.

В: Как сменить SECRET_KEY? О: Измените в .env и перезапустите. Все сессии будут инвалидированы.

Уведомления

В: Почему не приходят письма? О: Проверьте настройки SMTP, особенно порт и TLS.

В: Можно ли отключить уведомления? О: Да, в настройках уведомлений.

В: Как задать тихие часы? О: В настройках уведомлений укажите период (напр., 23:00 – 07:00).

Интеграции

В: Есть ли API для интеграции? О: Да, REST API с документацией по адресу /docs.

В: Можно ли добавить webhooks? О: Пока нет, но запланировано в будущих версиях.

---

📞 Поддержка

• GitHub Issues: Создать issue
• Документация: этот файл (WIKI.ru.md)
• Changelog: CHANGELOG.ru.md

---

Последнее обновление: 24 июля 2026 Версия: 1.13.0