pvemanager/docs/appstore-engine.md

App Store — M2 App Engine (установка)

Установка приложения из каталога: клон золотого шаблона → pct push compose/.env → docker compose up -d → health-check, с журналом шагов, статусами и WS-прогрессом. Ядро переиспользует пайплайн M0 (app/appstore/pipeline.py).

Компоненты

• Модели: InstalledApp, AppOperation (backend/app/models/appstore.py).
• Миграция: migrate_appstore_installed() (таблицы installed_apps, app_operations).
• Движок: backend/app/services/appstore_engine.py — install, retry_install, delete_app, build_env (платформенные переменные ТЗ 5.3 + форма + генерация random-секретов).
• API: backend/app/api/appstore/apps.py.
• Прогресс: WebSocket /ws/tasks, события appstore_operation_update / appstore_app_deleted.

Обязательная настройка

APPSTORE_GOLDEN_TEMPLATE — volid золотого vztmpl с предустановленным Docker, напр. local:vztmpl/golden-docker_12_amd64.tar.zst (готовится вручную, M0). Без него установка отклоняется с понятной ошибкой.

API

POST   /api/appstore/apps/install          (app:install)  → {installed_app_id, operation_id, vmid, secrets}
GET    /api/appstore/apps                   (app:view)
GET    /api/appstore/apps/{id}              (app:view)     → + catalog, update_available
GET    /api/appstore/apps/{id}/operations   (app:view)     → журнал шагов
GET    /api/appstore/apps/{id}/credentials  (app:view)     → секреты формы (показать один раз)
POST   /api/appstore/apps/{id}/retry        (app:manage)   → повтор без пересоздания LXC
DELETE /api/appstore/apps/{id}              (app:manage)   → stop + destroy LXC + удалить запись

install тело запроса: app_id, name, server_id, node?, form_answers{}, cores, memory, disk, storage, bridge, ostemplate?.

Поведение (ТЗ 6.1)

• Пайплайн асинхронный (ThreadPoolExecutor), статус и журнал шагов пишутся в БД, прогресс транслируется по WS.
• secrets (пароли/сгенерированные random) возвращаются один раз в ответе install; в БД хранятся зашифрованно (Fernet, env_encrypted).
• Сбой любого шага → installed_apps.status='error', app_operations.status='failed' с текстом ошибки; доступны «Повторить» (/retry) и «Удалить» (DELETE).
• Идемпотентность повтора: vmid сохраняется в записи; при повторе контейнер не пересоздаётся (проверка существования по vmid), пайплайн продолжает с доставки/запуска.
• pct exec/pct push — через SSH на ноду; значения .env очищаются от переводов строк, файлы доставляются base64 → pct push (без shell-инъекций, S-4).

Verification (DoD M2 — backend)

Предпосылки: настроен APPSTORE_GOLDEN_TEMPLATE, каталог синхронизирован (M1), SSH-доступ панели к ноде.

1. POST /api/appstore/apps/install {app_id:"uptime-kuma", name:"uk1", server_id:1} → 202-подобный ответ с operation_id; по WS приходят шаги; статус → running.
2. GET /api/appstore/apps/{id} → status:running, url:http://IP:port.
3. Открыть url — приложение отвечает.
4. Приложение с формой (напр. wordpress): random-пароли БД генерируются, GET /apps/{id}/credentials их возвращает.
5. Сбой (напр. неверный шаблон) → status:error, журнал с текстом; POST /retry не создаёт второй LXC; DELETE сносит контейнер и запись.

UI (сетка, мастер установки, My Apps) — под-этап M2 (готов).

M3 — Lifecycle + реконсиляция

Добавлено в appstore_engine.py / api/appstore/apps.py:

POST /api/appstore/apps/{id}/action/{start|stop|restart}   (app:manage)
GET  /api/appstore/apps/{id}/logs?tail=200                 (app:view)  — docker compose logs через pct exec
POST /api/appstore/apps/reconcile                          (app:view)  — сверка LXC↔БД

• lifecycle_action — start/stop/restart LXC через ProxmoxClient, обновление статуса + WS.
• get_logs — pct exec … docker compose logs --tail N по SSH (ТЗ 6.5, по запросу).
• reconcile (ТЗ 6.6) — фон каждые 60с (start_reconcile_scheduler) + при открытии «My Apps»: пропавший контейнер → orphaned; статус синхронизируется с Proxmox (running/stopped).
• UI: кнопки Start/Stop/Restart/Logs/Delete в My Apps, диалог логов, бейдж orphaned.

DoD M3: все операции работают, orphan-детект работает.

M4 — Update + Rollback (снапшоты Proxmox)

POST /api/appstore/apps/{id}/update    (app:manage)  body: {form_answers?}
POST /api/appstore/apps/{id}/rollback  (app:manage)

• update (ТЗ 6.3): снапшот preupd_<version>_<timestamp> → pct push свежего compose из каталога (poc_update) → docker compose pull && up -d → health-check. Успех → новая версия в БД, хранится последний 1 pre-update снапшот (старые удаляются). Провал health → статус update_failed, доступен откат. .env сохраняется, новые поля формы дозапрашиваются (form_answers). Версия/tipi снапшота фиксируются в installed_apps.snapshot_version/snapshot_tipi_version (миграция добавляет колонки).
• rollback (ТЗ 6.4): stop → rollback_container_snapshot(start=1) → start → health-check → возврат прежней версии в БД. UI обязательно предупреждает, что откат возвращает и ДАННЫЕ приложения на момент снапшота.
• UI: кнопки Update (если update_available) и Rollback (если есть last_snapshot) в My Apps, с подтверждением-предупреждением.

DoD M4: обновление и откат Nextcloud проходят без потери данных (данные — в томах контейнера, снапшот покрывает весь CT).