Добавлена подробная инструкция 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
 ```
 Если все галочки стоят — панель готова к работе.