verstak/docs/10_Sync_Server_Guide.md

Сервер синхронизации Верстак — руководство

1. Зачем нужен сервер

Сервер позволяет синхронизировать данные между несколькими устройствами (например, рабочий ПК и ноутбук), а также хранить резервную копию vault'ов.

Он не обязателен — Верстак работает полностью локально и без сервера.

2. Установка

Быстрая установка (systemd)

# Сборка бинарника
go build -o verstak-server ./cmd/verstak-server/

# Установка (от root)
sudo ./verstak-server/install.sh \
  --port 47732 \
  --admin-user admin \
  --admin-pass 'мой-надёжный-пароль'

Скрипт:

• создаёт системного пользователя verstak;
• копирует бинарник в /usr/local/bin/verstak-server;
• создаёт /var/lib/verstak-server для данных;
• записывает админа в конфиг;
• устанавливает systemd-сервис verstak-server.service;
• запускает и включает автозапуск.

Ручной запуск (для тестирования)

# Одной командой
./verstak-server \
  --port 47732 \
  --data ./server-data \
  --admin-user admin \
  --admin-pass 'мой-надёжный-пароль'

Флаги:

Флаг	По умолчанию	Описание
--port	47732	Порт сервера
--data	./data	Директория для данных (SQLite + blobs)
--admin-user	—	Имя администратора (создаётся при первом запуске)
--admin-pass	—	Пароль администратора

Если не указать --admin-user и --admin-pass, сервер запустится, но админ-панель будет недоступна (некому будет логиниться).

3. Админ-панель

Как открыть

Откройте в браузере: http://<сервер>:47732/admin/login

Войдите с логином и паролем, указанными при установке.

Что там есть

• Дашборд — статистика: количество устройств, количество операций, список API-ключей, форма настройки SMTP.
• Управление API-ключами — просмотр, создание и удаление ключей устройств.
• Настройка SMTP — сервер, порт, логин, пароль, email отправителя, URL сервера (для ссылок в письмах). SMTP нужен для отправки писем подтверждения email и сброса пароля.

Сессия живёт 24 часа. После перезапуска сервера все сессии сбрасываются (хранятся в памяти).

Несколько админов

Можно запустить сервер с другими --admin-user/--admin-pass — добавится второй администратор. Повторный запуск с тем же именем меняет пароль.

4. Регистрация пользователей

Как зарегистрироваться

Откройте в браузере: http://<сервер>:47732/register

Форма принимает:

• Логин — латинские буквы и цифры
• Email — для подтверждения и сброса пароля
• Пароль — минимум 8 символов, латинские буквы и цифры

После отправки формы на email приходит письмо с ссылкой подтверждения (если SMTP настроен). Если SMTP не настроен, подтверждение происходит автоматически, и можно сразу логиниться.

Как войти

http://<сервер>:47732/login — форма логина принимает логин или email.

Личный кабинет

После входа — /dashboard — список устройств пользователя с полными API-ключами, кнопками копирования и удаления, форма добавления нового устройства.

5. API-ключи (устройства)

Что такое API-ключ

API-ключ — это токен, который клиент (Верстак на вашем ноутбуке или ПК) использует для доступа к серверу. Без ключа push/pull/blobs не работают.

Как создать

Через веб-интерфейс пользователя

1. Зайти в /login, войти.
2. В /dashboard ввести имя устройства и нажать "Connect".
3. Скопировать сгенерированный ключ.

Через админ-панель

1. Зайти в /admin/login.
2. В разделе "API Keys" ввести имя устройства и нажать "Create".
3. Скопировать сгенерированный ключ.

Через API (требует логин+пароль пользователя)

curl -X POST http://localhost:47732/api/v1/device/register \
  -H "Content-Type: application/json" \
  -d '{"name":"мой-ноутбук","username":"ivan","password":"пароль-пользователя"}'

Ответ: {"device_id":"...","api_key":"..."}

Как использовать

Ключ передаётся в заголовке Authorization: Bearer <ключ>:

curl -X POST http://localhost:47732/api/v1/sync/push \
  -H "Authorization: Bearer b10c5d8e3f2a..." \
  -H "Content-Type: application/json" \
  -d '{"device_id":"b10c5d8e3f2a","ops":[...]}'

В GUI Верстак достаточно указать URL сервера, логин и пароль — устройство зарегистрируется автоматически.

Один ключ на все устройства или отдельный на каждое?

На каждое устройство — отдельный ключ. Так вы сможете отозвать доступ конкретному устройству (удалить ключ в личном кабинете), не затронув остальные.

Технически один и тот же ключ можно использовать на нескольких устройствах, но:

• его нельзя будет удалить, не отключив все устройства разом;
• в логах сервера все операции будут выглядеть как от одного устройства;
• это не поддерживаемый сценарий.

Рекомендация: создавайте отдельный ключ для каждого клиента (ПК, ноутбук, телефон).

6. Настройка клиента

CLI

verstak sync push --vault /путь/к/vault
verstak sync pull --vault /путь/к/vault
verstak sync status --vault /путь/к/vault

Перед использованием нужно указать URL сервера и API-ключ в .verstak/config.yml внутри vault:

sync:
  server_url: http://мой-сервер:47732
  api_key: мой-ключ
  device_id: id-устройства   # опционально
  auto_sync: false

API-ключ и device_id можно получить, зарегистрировав устройство через API:

curl -s http://сервер:47732/api/v1/device/register \
  -H "Content-Type: application/json" \
  -d '{"name":"мой-пк","username":"ivan","password":"мой-пароль"}' | jq .

GUI

В графическом интерфейсе нажмите на иконку шестерёнки в левом нижнем углу → откроется окно настроек синхронизации. Укажите URL сервера, логин и пароль, нажмите "Test Connection" для проверки, затем "Сохранить". Кнопка "Синхронизировать" (или пункт меню в сайдбаре) запускает push + pull.

7. Безопасность

Сервер не поддерживает HTTPS. В production используйте reverse proxy (nginx, Caddy) для терминирования TLS.

Что стоит учесть:

• Регистрация устройств требует аутентификации пользователя.
• Подтверждение email обязательно, если настроен SMTP (иначе подтверждение автоматическое).
• Нет logout'а для админа — сессия живёт 24 часа или до перезапуска сервера.
• Нет rate limiting'а — возможен перебор пароля.
• Пароли хранятся в bcrypt — база данных не должна быть общедоступной.
• SMTP-пароль хранится в открытом виде в конфиге сервера.

Рекомендации для production:

• Закрыть порт сервера фаерволом (только доверенные IP).
• Использовать VPN (WireGuard/OpenVPN) для доступа между устройствами.
• Поставить nginx/Caddy перед сервером с HTTPS.
• Настроить SMTP для полноценного подтверждения email и сброса пароля.

8. Полный API

Открытые endpoint'ы

Метод	Путь	Описание
GET	/api/v1/health	Проверка здоровья сервера

Требуют API-ключ (Authorization: Bearer)

Метод	Путь	Описание
POST	/api/v1/sync/push	Отправить операции на сервер
POST	/api/v1/sync/pull	Получить операции с сервера
POST	/api/v1/blobs/	Загрузить blob (multipart)
GET	/api/v1/blobs/{sha256}	Скачать blob

Требуют логин+пароль (body JSON)

Метод	Путь	Описание
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)

Метод	Путь	Описание
GET/POST	/admin/login	Страница входа / отправка формы
GET	/admin/dashboard	Дашборд
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	Выход