Добавлена подробная инструкция INSTALL.md (Docker + VPS Panel)

2026-08-09 12:56:03 +03:00
parent e588bf0c20
commit 70b6603bbe
1 changed files with 487 additions and 0 deletions
@@ -0,0 +1,487 @@
+# Установка Docker и развёртывание Proxmox VPS Panel
+
+Полная пошаговая инструкция: от чистого Linux-сервера до работающей панели
+управления VPS на базе Proxmox VE.
+
+Документ рассчитан на Debian 12 / Ubuntu 22.04+ (это самый частый вариант
+для Proxmox-хоста и для отдельной VM/LXC под панель). Для других дистрибутивов
+есть отдельный раздел ниже.
+
+---
+
+## 1. Требования
+
+### Аппаратные (для VM/LXC, где будет крутиться панель)
+
+| Ресурс | Минимум | Рекомендуется |
+|---|---|---|
+| CPU | 1 vCPU | 2 vCPU |
+| RAM | 1 ГБ | 2 ГБ |
+| Диск | 8 ГБ | 20 ГБ (с запасом под бэкапы Postgres) |
+| Сеть | Доступ до API Proxmox по TCP 8006 | то же |
+
+### Программные
+
+- Linux с ядром ≥ 3.10 (для Docker Engine)
+- Права `root` или пользователь из группы `sudo`
+- Открытый порт `5173` (frontend, nginx) — если панель должна быть доступна извне
+- Доступ до Proxmox VE по HTTPS (порт 8006)
+
+### Сетевые
+
+- Сервер панели должен «видеть» Proxmox API (`https://<pve-ip>:8006/api2/json`)
+- Proxmox в свою очередь должен «видеть» сеть, в которой будут создаваться VM/CT
+  (обычно это один и тот же `vmbr0` / bridge)
+
+---
+
+## 2. Установка Docker Engine + Compose
+
+> Docker Engine — это сервер контейнеров (демон `dockerd`).
+> Docker Compose — это инструмент для описания multi-container приложений в YAML
+> (формат `compose.yaml`/`docker-compose.yml`).
+
+### 2.1. Debian / Ubuntu (рекомендуемый путь)
+
+```bash
+# 1. Обновляем индекс пакетов и ставим prerequisites
+sudo apt-get update
+sudo apt-get install -y \
+    ca-certificates \
+    curl \
+    gnupg \
+    lsb-release
+
+# 2. Добавляем официальный GPG-ключ Docker
+sudo install -m 0755 -d /etc/apt/keyrings
+curl -fsSL https://download.docker.com/linux/debian/gpg \
+    | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+sudo chmod a+r /etc/apt/keyrings/docker.gpg
+
+# 3. Добавляем репозиторий Docker
+echo \
+  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
+  https://download.docker.com/linux/debian \
+  $(lsb_release -cs) stable" \
+  | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+# 4. Ставим Docker Engine + CLI + Compose plugin
+sudo apt-get update
+sudo apt-get install -y \
+    docker-ce \
+    docker-ce-cli \
+    containerd.io \
+    docker-buildx-plugin \
+    docker-compose-plugin
+```
+
+> Для Ubuntu замените `debian` на `ubuntu` в строке с URL репозитория, остальное
+> идентично.
+
+### 2.2. Альтернатива: официальный `install.sh`
+
+Если не хочется возиться с репозиторием — Docker предоставляет скрипт, который
+сделает всё сам:
+
+```bash
+curl -fsSL https://get.docker.com -o get-docker.sh
+sudo sh get-docker.sh
+```
+
+Этот же скрипт работает на Debian, Ubuntu, RHEL, Fedora, CentOS, AlmaLinux,
+Rocky и т. д. — внутри он сам определяет дистрибутив.
+
+### 2.3. Другие дистрибутивы (краткая сводка)
+
+| Дистрибутив | Что делать |
+|---|---|
+| Fedora / RHEL / Alma / Rocky | `sudo dnf -y install dnf-plugins-core && sudo dnf config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo && sudo dnf install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin` |
+| Arch / Manjaro | `sudo pacman -S docker docker-compose` |
+| openSUSE | `sudo zypper install docker docker-compose` |
+| TrueNAS SCALE | см. раздел 8 — там Docker уже встроен |
+
+---
+
+## 3. Постустановочная настройка Docker
+
+### 3.1. Включаем автозапуск демона
+
+```bash
+sudo systemctl enable --now docker
+sudo systemctl status docker   # должно быть active (running)
+```
+
+### 3.2. Разрешаем пользователю работать без `sudo`
+
+По умолчанию `docker` требует root. Чтобы не набирать `sudo` каждый раз:
+
+```bash
+sudo usermod -aG docker $USER
+# После этого нужно ПЕРЕЛОГИНИТЬСЯ (или выполнить newgrp docker):
+newgrp docker
+```
+
+Проверка:
+
+```bash
+docker version
+docker compose version
+docker run --rm hello-world
+```
+
+Если `hello-world` скачался и напечатал приветствие — Docker готов.
+
+### 3.3. Ограничение логов (опционально, но полезно)
+
+Чтобы контейнеры не съедали диск логами, создайте `/etc/docker/daemon.json`:
+
+```json
+{
+  "log-driver": "json-file",
+  "log-opts": {
+    "max-size": "10m",
+    "max-file": "3"
+  }
+}
+```
+
+И перезапустите демон:
+
+```bash
+sudo systemctl restart docker
+```
+
+---
+
+## 4. Подготовка Proxmox
+
+Эти шаги делаются в **веб-интерфейсе Proxmox**.
+
+### 4.1. API-токен
+
+1. **Datacenter → Permissions → API Tokens → Add**
+2. User: `root@pam` (для теста; в проде лучше завести отдельного пользователя —
+   см. раздел «Безопасность» ниже)
+3. Token ID: например `panel`
+4. Privilege Separation: **выключить** (чтобы токен наследовал все права владельца)
+5. Скопируйте **Secret** — он показывается один раз.
+
+В итоге получите пару:
+
+```
+PVE_TOKEN_NAME=root@pam!panel
+PVE_TOKEN_VALUE=<тот самый секрет>
+```
+
+Права, которые нужны панели:
+
+- `VM.Allocate`, `VM.PowerMgmt`, `VM.Config.Disk`, `VM.Config.Network`,
+  `VM.Config.CPU`, `VM.Config.Memory`, `VM.Config.Cloudinit`,
+  `VM.Clone`, `VM.Audit`, `VM.Snapshot`, `VM.Backup`
+- `Sys.Audit` (для чтения статусов задач Proxmox)
+- Аналогичные права для `PVEAdmin` / `PVEAuditor` на ветке `/`
+
+В тестовой среде проще всего выдать роль `PVEAdmin` на корень `/`.
+
+### 4.2. Шаблон VM (для VM-инстансов)
+
+1. Скачайте cloud-образ, например Ubuntu 22.04:
+   ```bash
+   wget https://cloud-images.ubuntu.com/jammy/current/jammy-server-cloudimg-amd64.img
+   ```
+2. В Proxmox создайте VM, в **Hardware → CD/DVD** укажите этот образ.
+3. В **Cloud-Init → User**, **Password**, **SSH key** — заполните значения по умолчанию
+   (панель их перезапишет своими).
+4. Запустите VM, убедитесь, что cloud-init отработал и сеть поднялась.
+5. Выключите VM и превратите её в шаблон:
+   ```bash
+   qm template <vmid>
+   ```
+   VMID запомните — он пойдёт в поле `source_vmid` шаблона в панели.
+
+### 4.3. Шаблон LXC (для CT-инстансов)
+
+1. Узел → **local (storage)** → **CT Templates → Template** → вкладка **Download**
+2. Скачайте, например, `debian-12-standard_12.7-1_amd64.tar.zst`
+3. Готово. В панели поле `source_template` будет иметь вид:
+   ```
+   local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst
+   ```
+
+---
+
+## 5. Клонирование и настройка репозитория
+
+### 5.1. Клонируем
+
+```bash
+git clone https://gitea.nasweb.ru/host/Proxmox-VPS-Panel.git
+cd Proxmox-VPS-Panel
+```
+
+Структура должна выглядеть так:
+
+```
+Proxmox-VPS-Panel/
+├── backend/
+├── frontend/
+├── docker-compose.yml
+└── .gitignore
+```
+
+### 5.2. Готовим `.env` для backend
+
+```bash
+cd backend
+cp .env.example .env
+nano .env       # или vim / любой редактор
+```
+
+Заполните:
+
+```env
+# Обязательно смените! Сгенерировать: openssl rand -hex 32
+SECRET_KEY=<случайная_строка_минимум_32_символа>
+
+# Proxmox API
+PVE_HOST=https://192.168.31.2:8006
+PVE_NODE=pve
+PVE_TOKEN_NAME=root@pam!panel
+PVE_TOKEN_VALUE=<ваш_секрет_токена>
+
+# CORS — домен фронтенда через запятую (без пробелов)
+ALLOW_ORIGINS=http://localhost:5173,http://127.0.0.1:5173
+
+# Пароль БД — ОБЯЗАТЕЛЬНО должен совпадать с POSTGRES_PASSWORD
+# из .env рядом с docker-compose.yml
+DATABASE_URL=postgresql://panel:<тот_же_пароль_что_и_POSTGRES_PASSWORD>@db:5432/panel
+```
+
+> ⚠️ `DATABASE_URL` обычно собирается автоматически внутри `docker-compose.yml`
+> через `${POSTGRES_USER}` и `${POSTGRES_PASSWORD}`. Если вы переопределяете
+> его здесь — убедитесь, что хост = `db` (имя сервиса в compose), а не
+> `localhost`, иначе backend не достучится до Postgres.
+
+### 5.3. Генерируем секреты
+
+```bash
+# SECRET_KEY для подписи JWT
+openssl rand -hex 32
+
+# POSTGRES_PASSWORD для базы данных
+openssl rand -hex 16
+```
+
+### 5.4. Создаём `.env` рядом с `docker-compose.yml`
+
+Вернитесь в корень проекта:
+
+```bash
+cd ..
+cat > .env <<'EOF'
+POSTGRES_USER=panel
+POSTGRES_PASSWORD=<тот_самый_пароль_из_openssl_rand_hex_16>
+POSTGRES_DB=panel
+FRONTEND_PORT=5173
+EOF
+chmod 600 .env   # только владелец может читать — там секрет
+```
+
+> Этот файл уже в `.gitignore`, но на всякий случай не пушьте его.
+
+---
+
+## 6. Запуск панели
+
+### 6.1. Поднимаем стек
+
+```bash
+docker compose pull        # подтянуть базовые образы (postgres, alpine)
+docker compose up -d --build
+```
+
+- `--build` нужен, потому что backend и frontend собираются из исходников
+  (multi-stage Dockerfile внутри `backend/` и `frontend/`)
+- `-d` запускает в фоне
+
+### 6.2. Проверяем, что всё поднялось
+
+```bash
+docker compose ps
+```
+
+Все три сервиса (`db`, `backend`, `frontend`) должны быть в статусе `running`
+или `healthy`. Healthcheck у backend проверяет `http://localhost:8000/health`,
+у frontend — `http://localhost:5173/`, у БД — `pg_isready`.
+
+Логи в реальном времени:
+
+```bash
+docker compose logs -f
+# или только backend:
+docker compose logs -f backend
+```
+
+### 6.3. Проверка API вручную
+
+```bash
+curl http://localhost:5173/api/health
+# {"status":"ok"}
+
+curl http://localhost:5173/api/health/ready
+# {"status":"ready","db":"ok"}
+```
+
+> `/api/*` проксируется nginx-фронтенда на backend, поэтому порт 8000 наружу
+> не торчит.
+
+### 6.4. Открываем UI
+
+В браузере:
+
+```
+http://<ip-сервера-панели>:5173
+```
+
+1. Нажмите **Register** — зарегистрируйтесь.
+2. **Первый зарегистрированный пользователь автоматически становится админом.**
+   Это важно — зайдите первым сами.
+3. Войдите как админ, откройте **Admin → Templates**, создайте шаблон:
+
+   - **Type**: `vm` или `lxc`
+   - **Name**: что увидит клиент (например, `Ubuntu 22.04 / 1 vCPU / 1 GB`)
+   - **Cores / Memory / Disk**: сколько ресурсов получит инстанс
+   - **Source VMID** (для `vm`): VMID вашего VM-шаблона из шага 4.2
+   - **Source template** (для `lxc`): путь вида
+     `local:vztmpl/debian-12-standard_12.7-1_amd64.tar.zst`
+
+4. Выйдите из админа, зарегистрируйте второго пользователя (или попросите
+   клиента) — он уже будет `client` и увидит шаблон в дашборде.
+
+---
+
+## 7. Типовые ошибки и что с ними делать
+
+| Симптом | Причина | Решение |
+|---|---|---|
+| `POSTGRES_PASSWORD is required` при `up` | не задан `POSTGRES_PASSWORD` в `.env` рядом с compose | см. шаг 5.4 |
+| Backend падает с `connection refused` на `db:5432` | compose стартует backend раньше, чем БД приняла соединения | уже лечится через `depends_on: condition: service_healthy`; подождите минуту |
+| `pve authentication failed` при создании VPS | неверный `PVE_TOKEN_VALUE` или истёк токен | пересоздайте токен в Proxmox и обновите `.env`, затем `docker compose restart backend` |
+| CORS-ошибка в браузере: «blocked by CORS policy» | в `ALLOW_ORIGINS` нет домена, с которого открываете панель | добавьте свой домен/IP в `backend/.env` → `ALLOW_ORIGINS`, затем `docker compose restart backend` |
+| `permission denied` при `qm template` | вы выполняете не от root | `sudo qm template <vmid>` |
+| Не приходит IP созданной VM | в VM-шаблоне не установлен `qemu-guest-agent` и не включён в Proxmox | установите `qemu-guest-agent` в шаблоне, в опциях VM включите `Run guest agent on boot` |
+| Долго создаётся VM/CT | это нормально — `qmclone`/`pct clone` могут занимать минуты на больших дисках | следите за прогрессом через `docker compose logs -f backend` или UI Proxmox |
+
+---
+
+## 8. Установка на TrueNAS SCALE
+
+TrueNAS SCALE (Cobia / Dragonfish / Electric Eel / Fangtooth) уже содержит
+Docker Engine и Compose из коробки. Дополнительно ставить ничего не нужно.
+
+### 8.1. Вариант A: «Custom App» через UI
+
+1. **Apps → Discover Apps → Custom App**
+2. **Application Name**: `vps-panel`
+3. В секции **Container Images / Compose** переключитесь на режим
+   «Custom Compose`» и вставьте содержимое нашего `docker-compose.yml`
+   (или положите файлы в датасет и смонтируйте их как `/docker-compose.yml`).
+4. Переменные окружения задайте через UI:
+   - `POSTGRES_USER` = `panel`
+   - `POSTGRES_PASSWORD` = `<openssl rand -hex 16>`
+   - `POSTGRES_DB` = `panel`
+   - `FRONTEND_PORT` = `5173`
+   - На отдельной вкладке для сервиса `backend` добавьте все `PVE_*` и
+     `SECRET_KEY`, `ALLOW_ORIGINS`, плюс `env_file: ./backend/.env`
+5. **Storage**:
+   - Для сервиса `db` смонтируйте `panel_db` (named volume) или
+     путь на датасете типа `/mnt/tank/apps/vps-panel/db`
+6. Нажмите **Install**. Статус появится в **Installed Applications**.
+
+### 8.2. Вариант B: shell + `docker compose`
+
+```bash
+# Заходим на TrueNAS по SSH или открываем System Settings → Shell
+cd /mnt/tank/apps/vps-panel       # путь, куда положили репозиторий
+cp backend/.env.example backend/.env
+nano backend/.env                # заполняем
+cat > .env <<'EOF'
+POSTGRES_USER=panel
+POSTGRES_PASSWORD=<openssl rand -hex 16>
+POSTGRES_DB=panel
+FRONTEND_PORT=5173
+EOF
+
+docker compose up -d --build
+```
+
+### 8.3. Reverse-proxy
+
+TrueNAS Apps умеет автоматически прокидывать порты. Если нужен внешний доступ:
+
+- Встроенный reverse-proxy TrueNAS (например, через приложение
+  `nginx-proxy-manager` или `traefik`)
+- Или собственный reverse-proxy (Caddy, Nginx) с TLS через Let's Encrypt
+
+Обязательно укажите итоговый внешний домен в `backend/.env → ALLOW_ORIGINS`,
+иначе CORS заблокирует запросы.
+
+---
+
+## 9. Обновление панели
+
+```bash
+cd Proxmox-VPS-Panel
+git pull
+docker compose pull
+docker compose up -d --build
+docker compose restart
+```
+
+Миграций БД нет (используется `Base.metadata.create_all()`), так что апгрейд
+проходит без ручных шагов. Перед большими апгрейдами рекомендуется
+сделать бэкап volume `panel_db`:
+
+```bash
+docker compose stop db
+docker run --rm \
+    -v panel_db:/from \
+    -v $(pwd)/backups:/to \
+    alpine sh -c "tar czf /to/panel_db_$(date +%F).tgz -C /from ."
+docker compose start db
+```
+
+---
+
+## 10. Удаление
+
+```bash
+cd Proxmox-VPS-Panel
+docker compose down            # остановить и удалить контейнеры
+docker compose down -v         # + удалить volume panel_db (ВСЕ ДАННЫЕ БД)
+docker image prune -a          # удалить неиспользуемые образы
+```
+
+Удаление **не трогает** VM и LXC на Proxmox — их панель создаёт через API,
+и они продолжат жить независимо.
+
+---
+
+## Краткий чек-лист «поставил и работает»
+
+```
+[  ] Docker Engine + Compose установлены
+[  ] docker compose version показывает v2+
+[  ] В Proxmox создан API-токен
+[  ] В Proxmox есть VM-шаблон (если планируются VM)
+[  ] В Proxmox есть CT-шаблон (если планируются LXC)
+[  ] git clone репозитория выполнен
+[  ] backend/.env заполнен, SECRET_KEY сменён
+[  ] POSTGRES_PASSWORD сгенерирован и записан в .env рядом с compose
+[  ] docker compose up -d --build — все 3 сервиса running/healthy
+[  ] curl /api/health → {"status":"ok"}
+[  ] В браузере открыт http://<host>:5173, зарегистрирован админ
+[  ] Создан хотя бы один шаблон в Admin → Templates
+```
+
+Если все галочки стоят — панель готова к работе.