docs: add sync server installation and usage guide
This commit is contained in:
parent
84c0bcbcab
commit
e828ebd44e
|
|
@ -37,6 +37,7 @@
|
|||
7. [[07_AI_Coder_Prompts]] — промпты для ИИ-кодера.
|
||||
8. [[08_MVP_Checklist]] — чеклист первого MVP.
|
||||
9. [[09_Extensibility]] — архитектура плагинов (Lua + шаблоны дел).
|
||||
10. [[10_Sync_Server_Guide]] — установка и настройка сервера синхронизации.
|
||||
|
||||
## Главные принципы
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,180 @@
|
|||
# Сервер синхронизации Верстак — руководство
|
||||
|
||||
## 1. Зачем нужен сервер
|
||||
|
||||
Сервер позволяет синхронизировать данные между несколькими устройствами (например, рабочий ПК и ноутбук), а также хранить резервную копию vault'ов.
|
||||
|
||||
Он не обязателен — Верстак работает полностью локально и без сервера.
|
||||
|
||||
## 2. Установка
|
||||
|
||||
### Быстрая установка (systemd)
|
||||
|
||||
```bash
|
||||
# Сборка бинарника
|
||||
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`;
|
||||
- запускает и включает автозапуск.
|
||||
|
||||
### Ручной запуск (для тестирования)
|
||||
|
||||
```bash
|
||||
# Одной командой
|
||||
./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 не работают.
|
||||
|
||||
### Как создать
|
||||
|
||||
Через админ-панель:
|
||||
1. Зайти в `/admin/dashboard`.
|
||||
2. В разделе "API Keys" ввести имя устройства и нажать "Create".
|
||||
3. Скопировать сгенерированный ключ.
|
||||
|
||||
Через API (без авторизации):
|
||||
```bash
|
||||
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 <ключ>`:
|
||||
```bash
|
||||
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
|
||||
```bash
|
||||
verstak sync push --vault /путь/к/vault
|
||||
verstak sync pull --vault /путь/к/vault
|
||||
verstak sync status --vault /путь/к/vault
|
||||
```
|
||||
|
||||
Перед использованием нужно указать URL сервера и API-ключ в `.verstak/config.yml` внутри vault:
|
||||
```yaml
|
||||
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 |
|
||||
|
||||
### Требуют сессию админа (cookie)
|
||||
|
||||
| Метод | Путь | Описание |
|
||||
|---|---|---|
|
||||
| GET/POST | `/admin/login` | Страница входа / отправка формы |
|
||||
| GET | `/admin/dashboard` | Дашборд |
|
||||
| GET | `/admin/api/keys` | Список API-ключей (JSON) |
|
||||
| POST | `/admin/api/keys` | Создать ключ |
|
||||
| DELETE | `/admin/api/keys/{id}` | Удалить ключ |
|
||||
Loading…
Reference in New Issue