Proxmox-VPS-Panel/backend/MANAGE_USERS.md

Управление пользователями панели

Публичная регистрация в панели закрыта — это сделано из соображений безопасности, чтобы никто посторонний не мог зайти и создавать себе VPS через ваш Proxmox.

Все учётные записи создаёт администратор одним из способов:

1. Через CLI внутри контейнера backend (рекомендуемый способ).
2. Через эндпоинт /admin/users POST (уже залогинившись как админ).
3. Через UI → Admin → Users → «Создать» (если добавите такую кнопку в frontend/src/pages/AdminUsers.jsx).

Документ описывает первый способ — CLI.

---

1. Базовый вызов

docker compose exec backend python -m app.manage_users <команда> [аргументы]

app.manage_users уже лежит в репозитории (backend/app/manage_users.py) и автоматически попадает в образ backend — отдельно класть его в Dockerfile не нужно.

Все команды

list                                          — список всех пользователей
create <email> <password> [admin|client]      — создать пользователя
activate <email>                              — включить (is_active=True)
deactivate <email>                            — выключить (is_active=False)
set-role <email> <admin|client>               — сменить роль
reset-password <email> <new_password>         — сменить пароль
delete <email>                                — удалить пользователя

Если пароль не указан в аргументах — CLI безопасно спросит его интерактивно через getpass (символы не отображаются в терминале).

---

2. Типовые сценарии

2.1. Первый запуск панели — создать админа

Самый первый пользователь создаётся не через CLI, а через bootstrap: при пустой БД endpoint POST /auth/register остаётся открытым и создаёт админа. Если вы только что подняли панель — зайдите на страницу /register, заполните форму один раз и получите admin-аккаунт. Сразу после этого вход через /register закрывается навсегда.

# Способ через CLI (если вы предпочитаете не использовать /register):
docker compose exec backend python -m app.manage_users \
    create admin@example.com 'StrongP@ssw0rd!' admin

2.2. Создать обычного клиента

docker compose exec backend python -m app.manage_users \
    create ivan@example.com 'TempP@ss123' client

Клиент сразу сможет войти (is_active=True по умолчанию) и видеть доступные шаблоны VPS.

2.3. Временно отключить пользователя

docker compose exec backend python -m app.manage_users deactivate ivan@example.com
# Пользователь не сможет войти, его VPS остаются.

docker compose exec backend python -m app.manage_users activate ivan@example.com
# Вернуть доступ.

2.4. Сделать пользователя админом (или наоборот)

docker compose exec backend python -m app.manage_users set-role ivan@example.com admin

⚠️ CLI не даст понизить единственного активного администратора — сначала создайте/назначьте другого admin.

2.5. Сбросить пароль

docker compose exec backend python -m app.manage_users \
    reset-password ivan@example.com 'NewP@ssw0rd'
# или интерактивно (пароль не светится в истории):
docker compose exec backend python -m app.manage_users reset-password ivan@example.com

2.6. Удалить пользователя

docker compose exec backend python -m app.manage_users delete ivan@example.com

Это удалит запись пользователя из БД. Его VPS в Proxmox останутся — панель их создаёт через API, и они живут независимо. Если хотите удалить и VPS — сделайте это через UI Proxmox или дашборд панели до удаления пользователя.

2.7. Посмотреть всех пользователей

docker compose exec backend python -m app.manage_users list

Вывод:

  ID  EMAIL                             ROLE    ACTIVE  CREATED_AT
------------------------------------------------------------------------------
   3  ivan@example.com                  client  да      2026-08-10 12:34
   2  petr@example.com                  client  нет     2026-08-10 11:02
   1  admin@example.com                 admin   да      2026-08-09 22:11

---

3. Защитные ограничения CLI

Скрипт намеренно блокирует опасные операции:

• Нельзя удалить или понизить единственного активного admin — защита от случайной потери единственного администратора. Если вам кажется, что это окей — сделайте это через прямой SQL-запрос к БД (docker compose exec db psql ...), приняв на себя ответственность.
• Пароль должен быть не короче 6 символов (как и в UI).
• Email нормализуется (lowercase + trim), чтобы User@Example.com и user@example.com не оказались разными пользователями.

---

4. Локальный запуск без Docker

Если вы разрабатываете панель вне Docker и используете SQLite из config.py:

cd backend
python -m app.manage_users create admin@example.com password admin

Скрипт читает DATABASE_URL из окружения или .env (backend/.env), так что работает и в dev-режиме, и в проде.

---

5. Если что-то пошло не так

Симптом	Причина	Решение
ModuleNotFoundError: No module named 'app'	запускаете не из backend/	добавьте cd backend либо укажите PYTHONPATH=/app:$PYTHONPATH
OperationalError: connection refused	БД ещё не стартовала	подождите, пока docker compose ps покажет db healthy
❌ Пользователь уже существует	дубль email	проверьте list — возможно, регистрировались раньше
❌ Нельзя понизить единственного администратора	защита CLI	создайте второго admin, затем понизьте первого