Добавить документацию по управлению пользователями (MANAGE_USERS.md)
This commit is contained in:
@@ -0,0 +1,163 @@
|
||||
# Управление пользователями панели
|
||||
|
||||
Публичная регистрация в панели **закрыта** — это сделано из соображений
|
||||
безопасности, чтобы никто посторонний не мог зайти и создавать себе VPS
|
||||
через ваш Proxmox.
|
||||
|
||||
Все учётные записи создаёт администратор одним из способов:
|
||||
|
||||
1. **Через CLI внутри контейнера backend** (рекомендуемый способ).
|
||||
2. **Через эндпоинт `/admin/users` POST** (уже залогинившись как админ).
|
||||
3. **Через UI → Admin → Users → «Создать»** (если добавите такую кнопку
|
||||
в `frontend/src/pages/AdminUsers.jsx`).
|
||||
|
||||
Документ описывает первый способ — CLI.
|
||||
|
||||
---
|
||||
|
||||
## 1. Базовый вызов
|
||||
|
||||
```bash
|
||||
docker compose exec backend python -m app.manage_users <команда> [аргументы]
|
||||
```
|
||||
|
||||
> `app.manage_users` уже лежит в репозитории (`backend/app/manage_users.py`)
|
||||
> и автоматически попадает в образ backend — отдельно класть его в Dockerfile
|
||||
> не нужно.
|
||||
|
||||
### Все команды
|
||||
|
||||
```text
|
||||
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` закрывается навсегда.
|
||||
|
||||
```bash
|
||||
# Способ через CLI (если вы предпочитаете не использовать /register):
|
||||
docker compose exec backend python -m app.manage_users \
|
||||
create admin@example.com 'StrongP@ssw0rd!' admin
|
||||
```
|
||||
|
||||
### 2.2. Создать обычного клиента
|
||||
|
||||
```bash
|
||||
docker compose exec backend python -m app.manage_users \
|
||||
create ivan@example.com 'TempP@ss123' client
|
||||
```
|
||||
|
||||
Клиент сразу сможет войти (`is_active=True` по умолчанию) и видеть
|
||||
доступные шаблоны VPS.
|
||||
|
||||
### 2.3. Временно отключить пользователя
|
||||
|
||||
```bash
|
||||
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. Сделать пользователя админом (или наоборот)
|
||||
|
||||
```bash
|
||||
docker compose exec backend python -m app.manage_users set-role ivan@example.com admin
|
||||
```
|
||||
|
||||
> ⚠️ CLI не даст понизить **единственного** активного администратора —
|
||||
> сначала создайте/назначьте другого admin.
|
||||
|
||||
### 2.5. Сбросить пароль
|
||||
|
||||
```bash
|
||||
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. Удалить пользователя
|
||||
|
||||
```bash
|
||||
docker compose exec backend python -m app.manage_users delete ivan@example.com
|
||||
```
|
||||
|
||||
> Это удалит запись пользователя из БД. **Его VPS в Proxmox останутся** —
|
||||
> панель их создаёт через API, и они живут независимо. Если хотите удалить
|
||||
> и VPS — сделайте это через UI Proxmox или дашборд панели до удаления
|
||||
> пользователя.
|
||||
|
||||
### 2.7. Посмотреть всех пользователей
|
||||
|
||||
```bash
|
||||
docker compose exec backend python -m app.manage_users list
|
||||
```
|
||||
|
||||
Вывод:
|
||||
|
||||
```text
|
||||
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`:
|
||||
|
||||
```bash
|
||||
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, затем понизьте первого |
|
||||
Reference in New Issue
Block a user