From 015c8fdec79a9f3a0b90a34661fa797c5a4b3efc Mon Sep 17 00:00:00 2001 From: mirivlad Date: Tue, 2 Jun 2026 00:00:53 +0800 Subject: [PATCH] docs: update sync server guide with user registration flow and full API --- docs/10_Sync_Server_Guide.md | 101 +++++++++++++++++++++++++++-------- 1 file changed, 80 insertions(+), 21 deletions(-) diff --git a/docs/10_Sync_Server_Guide.md b/docs/10_Sync_Server_Guide.md index 7f8efbf..1643c5c 100644 --- a/docs/10_Sync_Server_Guide.md +++ b/docs/10_Sync_Server_Guide.md @@ -60,8 +60,9 @@ sudo ./verstak-server/install.sh \ ### Что там есть -- **Дашборд** — статистика: количество устройств, количество операций, список API-ключей. +- **Дашборд** — статистика: количество устройств, количество операций, список API-ключей, форма настройки SMTP. - **Управление API-ключами** — просмотр, создание и удаление ключей устройств. +- **Настройка SMTP** — сервер, порт, логин, пароль, email отправителя, URL сервера (для ссылок в письмах). SMTP нужен для отправки писем подтверждения email и сброса пароля. Сессия живёт 24 часа. После перезапуска сервера все сессии сбрасываются (хранятся в памяти). @@ -69,7 +70,28 @@ sudo ./verstak-server/install.sh \ Можно запустить сервер с другими `--admin-user`/`--admin-pass` — добавится второй администратор. Повторный запуск с тем же именем меняет пароль. -## 4. API-ключи (устройства) +## 4. Регистрация пользователей + +### Как зарегистрироваться + +Откройте в браузере: `http://<сервер>:47732/register` + +Форма принимает: +- **Логин** — латинские буквы и цифры +- **Email** — для подтверждения и сброса пароля +- **Пароль** — минимум 8 символов, латинские буквы и цифры + +После отправки формы на email приходит письмо с ссылкой подтверждения (если SMTP настроен). Если SMTP не настроен, подтверждение происходит автоматически, и можно сразу логиниться. + +### Как войти + +`http://<сервер>:47732/login` — форма логина принимает логин или email. + +### Личный кабинет + +После входа — `/dashboard` — список устройств пользователя с полными API-ключами, кнопками копирования и удаления, форма добавления нового устройства. + +## 5. API-ключи (устройства) ### Что такое API-ключ @@ -77,21 +99,27 @@ API-ключ — это токен, который клиент (Верстак ### Как создать -Через админ-панель: -1. Зайти в `/admin/dashboard`. +#### Через веб-интерфейс пользователя + +1. Зайти в `/login`, войти. +2. В `/dashboard` ввести имя устройства и нажать "Connect". +3. Скопировать сгенерированный ключ. + +#### Через админ-панель + +1. Зайти в `/admin/login`. 2. В разделе "API Keys" ввести имя устройства и нажать "Create". 3. Скопировать сгенерированный ключ. -Через API (требует логин и пароль администратора): +#### Через API (требует логин+пароль пользователя) + ```bash curl -X POST http://localhost:47732/api/v1/device/register \ -H "Content-Type: application/json" \ - -d '{"name":"мой-ноутбук","username":"admin","password":"пароль-админа"}' + -d '{"name":"мой-ноутбук","username":"ivan","password":"пароль-пользователя"}' ``` Ответ: `{"device_id":"...","api_key":"..."}` -**Важно:** не выставляйте сервер в интернет без HTTPS (через reverse proxy). До создания полноценной системы пользователей регистрация устройств требует учётных данных администратора. - ### Как использовать Ключ передаётся в заголовке `Authorization: Bearer <ключ>`: @@ -102,11 +130,11 @@ curl -X POST http://localhost:47732/api/v1/sync/push \ -d '{"device_id":"b10c5d8e3f2a","ops":[...]}' ``` -В клиенте Верстак достаточно вбить URL сервера и API-ключ в настройках (GUI Settings или `config.yml`). +В GUI Верстак достаточно указать URL сервера, логин и пароль — устройство зарегистрируется автоматически. ### Один ключ на все устройства или отдельный на каждое? -**На каждое устройство — отдельный ключ.** Так вы сможете отозвать доступ конкретному устройству (удалить ключ в админ-панели), не затронув остальные. +**На каждое устройство — отдельный ключ.** Так вы сможете отозвать доступ конкретному устройству (удалить ключ в личном кабинете), не затронув остальные. Технически один и тот же ключ можно использовать на нескольких устройствах, но: - его нельзя будет удалить, не отключив все устройства разом; @@ -115,7 +143,7 @@ curl -X POST http://localhost:47732/api/v1/sync/push \ **Рекомендация:** создавайте отдельный ключ для каждого клиента (ПК, ноутбук, телефон). -## 5. Настройка клиента +## 6. Настройка клиента ### CLI ```bash @@ -133,25 +161,35 @@ sync: auto_sync: false ``` -### GUI -В графическом интерфейсе нажмите на иконку шестерёнки в левом нижнем углу → откроется окно настроек синхронизации. Укажите URL сервера и API-ключ, нажмите "Сохранить". Кнопка "Синхронизировать" запускает push + pull. +API-ключ и device_id можно получить, зарегистрировав устройство через API: +```bash +curl -s http://сервер:47732/api/v1/device/register \ + -H "Content-Type: application/json" \ + -d '{"name":"мой-пк","username":"ivan","password":"мой-пароль"}' | jq . +``` -## 6. Безопасность +### GUI +В графическом интерфейсе нажмите на иконку шестерёнки в левом нижнем углу → откроется окно настроек синхронизации. Укажите URL сервера, логин и пароль, нажмите "Test Connection" для проверки, затем "Сохранить". Кнопка "Синхронизировать" (или пункт меню в сайдбаре) запускает push + pull. + +## 7. Безопасность Сервер **не поддерживает HTTPS**. В production используйте reverse proxy (nginx, Caddy) для терминирования TLS. Что стоит учесть: -- Регистрация устройств открыта — любой, кто достучался до сервера, может создать ключ. -- Нет logout'а — сессия живёт 24 часа или до перезапуска сервера. +- Регистрация устройств требует аутентификации пользователя. +- Подтверждение email обязательно, если настроен SMTP (иначе подтверждение автоматическое). +- Нет logout'а для админа — сессия живёт 24 часа или до перезапуска сервера. - Нет rate limiting'а — возможен перебор пароля. -- Пароль хранится в bcrypt — база данных не должна быть общедоступной. +- Пароли хранятся в bcrypt — база данных не должна быть общедоступной. +- SMTP-пароль хранится в открытом виде в конфиге сервера. Рекомендации для production: - Закрыть порт сервера фаерволом (только доверенные IP). - Использовать VPN (WireGuard/OpenVPN) для доступа между устройствами. -- Или поставить nginx/Caddy перед сервером с HTTPS и базовой аутентификацией на `/api/v1/device/register`. +- Поставить nginx/Caddy перед сервером с HTTPS. +- Настроить SMTP для полноценного подтверждения email и сброса пароля. -## 7. Полный API +## 8. Полный API ### Открытые endpoint'ы @@ -168,11 +206,22 @@ sync: | POST | `/api/v1/blobs/` | Загрузить blob (multipart) | | GET | `/api/v1/blobs/{sha256}` | Скачать blob | -### Требуют логин+пароль администратора +### Требуют логин+пароль (body JSON) | Метод | Путь | Описание | |---|---|---| -| POST | `/api/v1/device/register` | Регистрация устройства (body: name + username + password) | +| POST | `/api/v1/auth/register` | Регистрация (username, email, password) | +| GET | `/api/v1/auth/confirm?token=` | Подтверждение email | +| POST | `/api/v1/auth/login` | Вход, возвращает Bearer-токен | +| POST | `/api/v1/auth/forgot` | Запрос сброса пароля (email) | +| POST | `/api/v1/auth/reset` | Сброс пароля (token, password) | +| POST | `/api/v1/device/register` | Регистрация устройства (name, username, password) | + +### Требуют сессию пользователя (Bearer token или cookie) + +| Метод | Путь | Описание | +|---|---|---| +| GET | `/api/v1/user/devices` | Список устройств пользователя | ### Требуют сессию админа (cookie) @@ -183,3 +232,13 @@ sync: | GET | `/admin/api/keys` | Список API-ключей (JSON) | | POST | `/admin/api/keys` | Создать ключ | | DELETE | `/admin/api/keys/{id}` | Удалить ключ | +| POST | `/admin/api/smtp` | Сохранить SMTP-конфигурацию | + +### Пользовательский веб-интерфейс (cookie) + +| Метод | Путь | Описание | +|---|---|---| +| GET/POST | `/register` | Форма регистрации | +| GET/POST | `/login` | Форма входа | +| GET | `/dashboard` | Личный кабинет (устройства) | +| GET | `/logout` | Выход |