diff --git a/docs/00_README.md b/docs/00_README.md index 9d60a5c..de07656 100644 --- a/docs/00_README.md +++ b/docs/00_README.md @@ -37,6 +37,7 @@ 7. [[07_AI_Coder_Prompts]] — промпты для ИИ-кодера. 8. [[08_MVP_Checklist]] — чеклист первого MVP. 9. [[09_Extensibility]] — архитектура плагинов (Lua + шаблоны дел). +10. [[10_Sync_Server_Guide]] — установка и настройка сервера синхронизации. ## Главные принципы diff --git a/docs/10_Sync_Server_Guide.md b/docs/10_Sync_Server_Guide.md new file mode 100644 index 0000000..46f26b7 --- /dev/null +++ b/docs/10_Sync_Server_Guide.md @@ -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}` | Удалить ключ |