Посібник розробника NectarinePanel

English · Українська · Русский · Polski

Це основна документація для розробників і операторів, які встановлюють, змінюють, тестують, випускають або діагностують NectarinePanel. Роботу з вебінтерфейсом описано в посібнику користувача. Інші файли docs/ залишаються поглибленим технічним довідником.

1. Призначення проєкту

NectarinePanel — модульний монорепозиторій для розгортання та експлуатації застосунків на одному Ubuntu VPS, а не багатосерверний планувальник. FastAPI відповідає за валідацію, авторизацію та стан, Celery — за довгі задачі, а привілейовані зміни сервера проходять через локальний агент з обмеженим набором операцій.

Стек: FastAPI, асинхронний SQLAlchemy, Alembic, PostgreSQL, Valkey, Celery, Nuxt 4, Vue 3, TypeScript, Pinia, системний агент та необов'язковий Telegram-бот на aiogram. Цільова робоча система — Ubuntu 24.04 LTS. Для розробки потрібні Python 3.12+, підтримуваний у frontend/package.json Node.js LTS, npm 10+ і Docker Engine з Compose v2.

2. Структура репозиторію

backend/        API FastAPI, моделі, схеми, сервіси й міграції Alembic
worker/         задачі Celery та обробник фонових завдань
agent/          перевірені системні операції й локальна HTTP-межа
frontend/       Nuxt, компоненти, composable-функції, переклади й тести
telegram-bot/   необов'язковий бот власника
installer/      встановлення, оновлення, видалення, модулі systemd і Nginx
docs/           основні посібники й технічні довідники
tests/          тести репозиторію, встановлення й контейнерних файлів
scripts/        сценарії обслуговування та перевірки

Зберігайте наявну прагматичну структуру. Не додавайте шари domain/application/infrastructure без конкретної потреби. Маршрути обробляють HTTP, сервіси містять повторно використовувану бізнес- та інфраструктурну логіку, схеми визначають контракти API, а моделі — структуру зберігання даних.

3. Архітектура та потік операції

Browser -> Nginx -> Nuxt
                 -> FastAPI -> PostgreSQL
                            -> Valkey -> Celery worker / scheduler
                            -> local agent -> root-owned helper -> host
Telegram -> authenticated internal FastAPI endpoints

Типова асинхронна операція:

FastAPI автентифікує користувача, перевіряє RBAC, валідує вхідні дані й створює записи задачі та аудиту.
Celery отримує ідентифікатори й несекретні параметри.
Обробник завантажує актуальний стан і зашифровані облікові дані зі сховища.
Привілейована операція надсилається до типізованої кінцевої точки агента.
Агент і допоміжна програма повторно перевіряють запит та перетворюють його на фіксований список аргументів або обмежену файлову операцію.
Обробник зберігає перебіг і результат; інтерфейс використовує WebSocket із резервним опитуванням API.

Ніколи не додавайте універсальний запуск команд до агента й не монтуйте сокет Docker у публічну серверну частину. Докладніше: архітектура, безпека, проєкти.

4. Локальне середовище

Усі команди Python виконуються лише через віртуальне середовище репозиторію.

python3 -m venv .venv
.venv/bin/pip install -r backend/requirements-dev.txt
cd frontend && npm ci
cd ..
cp .env.example .env

Замініть секрети для розробки в .env до передачі середовища іншим людям:

openssl rand -hex 32
.venv/bin/python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Повне Docker-середовище

docker compose up --build
docker compose exec backend python -m app.cli create-admin --username admin

Панель: http://localhost:3000, OpenAPI: http://localhost:8000/api/v1/docs. Порти розробки прив'язані до локального інтерфейсу. Цей Compose не призначений для робочого середовища.

Опціональні профілі:

docker compose --profile telegram up --build
docker compose --profile adminer up --build

Запуск компонентів на хості

Запустіть PostgreSQL/Valkey або задайте сумісні URL у .env, далі в окремих терміналах:

make migrate
make backend
make worker
make scheduler
make agent
make frontend

Серверна частина під час прямого запуску за замовчуванням використовує SQLite, але обробник, фонові задачі, обмеження частоти запитів і планувальник потребують Valkey. Для тестів середовища виконання й сервера використовуйте заглушки або одноразове середовище; не спрямовуйте розробку до робочого сховища.

5. Конфігурація

Авторитетна модель — backend/app/core/config.py, стандартні значення — у .env.example.

Змінна	Призначення
`ENVIRONMENT`	`development`, `test` або робоче значення; робоче середовище відхиляє стандартні небезпечні секрети.
`DATABASE_URL`	Рядок підключення асинхронного SQLAlchemy.
`REDIS_URL`	Valkey/Redis для обмеження запитів, Celery й оперативного стану.
`JWT_SECRET`	Щонайменше 32 символи поза локальним середовищем.
`FIELD_ENCRYPTION_KEY`	Ключ Fernet для збережених секретів; обов'язковий у робочому середовищі.
`AGENT_URL`, `AGENT_TOKEN`	Закрита кінцева точка агента й спільний секрет автентифікації.
`STORAGE_ROOT`	Корінь проєктів, резервних копій, завантажень і стану середовищ виконання.
`CONFIG_ROOT`, `NGINX_CONFIG_ROOT`	Конфігурація панелі й створених вузлів Nginx.
`CORS_ORIGINS`	Дозволені джерела браузера через кому.
`PUBLIC_BASE_URL`	Публічний URL панелі для посилань і зворотних викликів.
`TELEGRAM_*`	Необов'язкова конфігурація бота й внутрішньої автентифікації.

Не змінюйте FIELD_ENCRYPTION_KEY без міграції даних: наявні зашифровані поля стануть нечитабельними. Не записуйте до логів об'єкти налаштувань, токени, паролі, закриті ключі й розшифровані DSN.

6. Розробка серверної частини

Серверна частина асинхронна. Використовуйте AsyncSession, схеми Pydantic на межі API й стабільні HTTP-помилки замість внутрішніх винятків.

Під час додавання кінцевої точки:

створіть або оновіть схему у backend/app/schemas/;
винесіть повторно використовувану логіку до backend/app/services/, якщо маршрут змішує HTTP із бізнес- або інфраструктурною логікою;
до читання чутливих даних викличте require_global_role(...) або require_project_permission(project_id, permission);
записуйте змінювальні та пов'язані з безпекою дії до аудиту без відкритих секретів;
додайте тести успішного виконання, валідації, відсутності автентифікації, забороненої ролі, доступу до чужого проєкту й значущих помилок;
не ламайте наявний контракт відповіді без явно оголошеної несумісної зміни.

Ролі owner і admin мають глобальний доступ до проєктів. Доступ ролей maintainer і viewer задається призначенням на проєкт і картою дозволів у backend/app/services/permissions.py. Приховування дії в інтерфейсі не замінює авторизацію на сервері.

Для всіх модулів, функцій і класів Python обов'язкові короткі англійські рядки документації. Використовуйте безпечні параметри драйверів, перевірені ідентифікатори, фіксовані списки аргументів та обмежене введення-виведення. Не створюйте команди оболонки з користувацьких даних.

7. Міграції бази даних

Кожна зміна збережених даних потребує міграції Alembic від поточної вершини:

cd backend
../.venv/bin/alembic heads
../.venv/bin/alembic revision --autogenerate -m "describe change"
../.venv/bin/alembic upgrade head
cd ..

Перевірте DDL, назви, індекси, зовнішні ключі, стандартні значення, порядок оновлення й безпеку відкату. Протестуйте оновлення з попередньої схеми. Не змінюйте вже застосовану міграцію — додайте виправну. Програма оновлення створює аварійну резервну копію, але міграція все одно має бути транзакційною й сумісною з наявними даними, наскільки дозволяє СУБД.

8. Обробник і фонові задачі

Celery використовується для розгортання, резервного копіювання, операцій із базами даних і сертифікатами, моніторингу та інших тривалих задач. API має ставити задачу в чергу, а не утримувати HTTP-з'єднання.

Правила фонових задач:

параметри містять ідентифікатори й несекретні дані, але не облікові дані;
обробник заново читає поточний стан бази даних на старті;
перебіг та помилки обмежені за розміром і безпечні для інтерфейсу;
повторні спроби задаються явно й лише для ідемпотентних або відновлюваних операцій;
очищення виконується у finally;
метадані фіксуються після успіху зовнішньої операції;
повторне очищення або видалення за можливості ідемпотентні.

У модульних тестах підміняйте межі агента й клієнтів, перевіряйте успіх і часткову відмову. Не вимагайте робочий Docker або зовнішні сервіси.

9. Системний агент

Агент — привілейована межа безпеки. HTTP-процес працює як vps-panel-agent і передає одну перевірену операцію через стандартне введення точній допоміжній програмі, що належить суперкористувачу й дозволена в sudoers.

Нова операція потребує:

строгої типізованої моделі запиту й обмежень;
автентифікації за токеном агента;
розв'язання шляху всередині дозволеного кореня після обробки символічних посилань;
фіксованої програми й аргументів без shell=True;
обмеження часу й виводу та передбачуваних помилок;
повторної валідації в допоміжній програмі для операцій суперкористувача;
тестів безпеки на вихід за межі шляху, ін'єкції, посилання, некоректні дані й відсутність авторизації;
мінімально необхідних власників і системних дозволів.

Якщо дію не можна безпечно виразити як фіксовану дозволену операцію, її не має бути в API агента.

10. Інтерфейс і локалізація

Nuxt відповідає за подання й стан клієнта. Авторизація, секрети й системна логіка залишаються у серверній частині. Використовуйте наявні компоненти, змінні CSS, значки Tabler, composable-функції й адаптивні шаблони; не додавайте залежність заради невеликої тестованої допоміжної функції.

frontend/pages/        сторінки маршрутів
frontend/components/   повторно використовувані компоненти інтерфейсу
frontend/composables/  API, локалізація, дозволи й спільна логіка
frontend/stores/       стан Pinia
frontend/locales/      каталоги EN, UK, RU і PL
frontend/types/        типи інтерфейсу
frontend/tests/        тести Vitest

Кожен видимий рядок має використовувати функцію локалізації та існувати в усіх чотирьох каталогах. Ключі перекладу мають бути змістовними й стабільними, а дати та числа — форматуватися з урахуванням мови. Для сторінок потрібні явні стани завантаження, помилки, порожнього результату, заборони доступу й успіху. Незворотні дії потребують діалогу підтвердження та, де підтримується, підтвердження на сервері.

cd frontend
npm run lint
npm run typecheck
npm run test
npm run build
cd ..

11. Тести та перевірка якості

Під час розробки запускайте цільові тести:

.venv/bin/python -m pytest backend/tests/test_projects.py
.venv/bin/python -m pytest agent/tests/test_security.py
cd frontend && npm run test -- projects-utils && cd ..

Перед комітом виконайте повну перевірку:

make check

Вона охоплює перевірку й форматування Ruff, mypy, ESLint, перевірку типів Nuxt, тести Python та інтерфейсу, робочу збірку, аудит npm, синтаксис сценаріїв оболонки й конфігурацію Compose. Для змін встановлювача або образів додатково:

docker compose --profile telegram build backend frontend worker agent telegram-bot
sudo ./installer/install.sh --domain panel.example.com --email admin@example.com --dry-run

Нова логіка потребує тестів, зокрема граничних випадків. За замовчуванням віддавайте перевагу модульним тестам; інтеграційні додавайте там, де заглушки не доводять поведінку на межі бази даних, черги, агента або файлової системи.

12. Інваріанти зберігання й розгортання

/opt/nectarine-panel/              встановлений застосунок
/etc/nectarine-panel/              конфігурація сервісів і секрети
/etc/nginx/vps-panel/              створені вузли проєктів
/srv/vps-panel/projects/{id}/      релізи, поточне посилання, спільні дані, завантаження й логи
/srv/vps-panel/backups/            копії проєктів, баз даних і всієї панелі
/srv/vps-panel/minecraft/{id}/     дані середовища Minecraft

Релізи незмінні, а активація атомарно замінює current. Постійні дані розміщуються у shared/, а не в релізі чи незмонтованому шарі контейнера. Розпакування відхиляє вихід за межі каталогу, зовнішні посилання, спеціальні файли, надмірну кількість елементів та архівні бомби. Відновлення перевіряє контрольну суму, тип, сумісність і ціль до заміни даних.

13. Встановлення й життєвий цикл робочої системи

Встановлюйте перевірений реліз із тегом від імені суперкористувача:

sudo ./installer/install.sh \
  --domain panel.example.com \
  --email admin@example.com

Встановлювач створює окремих користувачів, PostgreSQL/Redis, сховище, середовище Python, збірку інтерфейсу, міграції, модулі systemd, Nginx, допоміжну програму агента, першого власника й TLS. Невказаний пароль адміністратора генерується та показується один раз.

Параметр	Призначення
`--domain`, `--email`	Ім'я хоста панелі й адреса пошти для Let's Encrypt.
`--admin-user`, `--admin-password`	Перший власник; пароль щонайменше 12 символів.
`--storage-root`	Абсолютний корінь постійних даних.
`--telegram-token`, `--telegram-owner-id`	Необов'язкова конфігурація бота.
`--public-ip`	Явно задана публічна адреса.
`--source`	Встановлення з довіреного локального дерева вихідного коду.
`--repository`, `--ref`	Репозиторій і закріплена ревізія Git.
`--max-upload-mb`	Обмеження завантаження від 1 до 4096 МіБ.
`--backend-port`, `--frontend-port`, `--agent-port`, `--adminer-port`	Унікальні локальні порти 1024–65535.
`--non-interactive`	Помилка замість запиту відсутніх значень.
`--skip-ssl`	HTTP без випуску сертифіката.
`--dry-run`	Валідація без встановлення.

sudo /opt/nectarine-panel/installer/update.sh --ref vX.Y.Z
sudo /opt/nectarine-panel/installer/uninstall.sh

update.sh підтримує --source, --repository, --ref, --dry-run, створює аварійні резервні копії, застосовує міграції й перевіряє стан. uninstall.sh зберігає постійні дані без явно підтвердженого --purge; також доступні --yes та --dry-run.

Не передавайте неперевірену змінювану гілку безпосередньо до оболонки суперкористувача. Докладніше: встановлення, випуск релізу.

14. Діагностика робочої системи

Починайте зі стану сервісів та обмежених свіжих логів:

sudo systemctl status \
  vps-panel-backend vps-panel-frontend vps-panel-worker \
  vps-panel-scheduler vps-panel-agent vps-panel-telegram-bot
sudo journalctl -u vps-panel-backend -n 200 --no-pager
sudo journalctl -u vps-panel-worker -n 200 --no-pager
sudo journalctl -u vps-panel-agent -n 200 --no-pager
sudo nginx -t
curl -fsS http://127.0.0.1:8000/api/v1/health

Використовуйте фактичний порт серверної частини. Перевірте PostgreSQL, Redis, Docker, місце й індексні дескриптори диска, DNS, порти 80/443 та власників файлів у корені сховища. Відповідь 502 від операції проєкту зазвичай означає, що серверна частина не завершила перевірену дію агента; зіставте логи серверної частини, обробника й агента за часом та ідентифікатором задачі.

Не публікуйте повні файли оточення й логи без вилучення чутливих даних. Видаляйте токени, cookie, паролі, закриті URL і ключі SSH, рядки підключення до бази та користувацькі дані. Перед ручним виправленням створіть резервну копію й визначте власника стану. Не обходьте агент разовими змінами від суперкористувача, які панель не зможе узгодити.

15. Запити на злиття й релізи

Робіть коміти сфокусованими, документуйте міграції, безпеку, сумісність резервних копій і вплив на експлуатацію. Перед запитом на злиття:

перевірте git diff і git status;
виконайте make check і потрібні збірки контейнерів;
переконайтеся, що новий текст інтерфейсу є в чотирьох мовних каталогах;
переконайтеся, що не додано .env, бази даних, архіви, токени, закриті ключі, внутрішні імена хостів або створені файли збірки;
оновіть посібник користувача після зміни робочого процесу, а посібник розробника чи довідник — після зміни внутрішньої логіки.

Для релізу оновіть журнал змін і версію, перевірте міграції, створіть підписаний тег vX.Y.Z, опублікуйте контрольні суми та інструкції з оновлення й відкату, перевірте встановлення на чистій Ubuntu 24.04 і відновлення на тимчасовому сервері. Дотримуйтеся CONTRIBUTING.md, SECURITY.md і releasing.md.

FilesExpand file tree

developer-guide.md

Latest commit

History