8.7 KiB

Raw Blame History

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

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-ключей.
Управление API-ключами — просмотр, создание и удаление ключей устройств.

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

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

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

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

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

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

Как создать

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

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

Через API (без авторизации):

curl -X POST http://localhost:47732/api/v1/device/register \
  -H "Content-Type: application/json" \
  -d '{"name":"мой-ноутбук"}'

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

Важно: endpoint регистрации открыт без аутентификации. Не выставляйте сервер в интернет без дополнительной защиты (фаервол, VPN, reverse proxy с базовой аутентификацией).

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

Ключ передаётся в заголовке 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":[...]}'

В клиенте Верстак достаточно вбить URL сервера и API-ключ в настройках (GUI Settings или config.yml).

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

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

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

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

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

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

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

GUI

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

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

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

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

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

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

Закрыть порт сервера фаерволом (только доверенные IP).
Использовать VPN (WireGuard/OpenVPN) для доступа между устройствами.
Или поставить nginx/Caddy перед сервером с HTTPS и базовой аутентификацией на /api/v1/device/register.

7. Полный API

Открытые endpoint'ы

Метод	Путь	Описание
GET	`/api/v1/health`	Проверка здоровья сервера
POST	`/api/v1/device/register`	Регистрация устройства (без аутентификации)

Требуют 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

Метод	Путь	Описание
GET/POST	`/admin/login`	Страница входа / отправка формы
GET	`/admin/dashboard`	Дашборд
GET	`/admin/api/keys`	Список API-ключей (JSON)
POST	`/admin/api/keys`	Создать ключ
DELETE	`/admin/api/keys/{id}`	Удалить ключ

8.7 KiB Raw Blame History Unescape Escape