Интеграция с Git

Двунаправленная синхронизация git в DocPlatform позволяет вашей команде работать так, как удобно каждому. Технические писатели используют веб-редактор. Разработчики пушат из IDE. Все видят один и тот же контент.

Как это работает

        ┌─────────────┐
        │ Web Editor   │
        │ (browser)    │
        └──────┬───────┘
               │ save
               ▼
        ┌─────────────┐          ┌──────────────┐
        │ Content     │  commit  │ Local Git    │  push    ┌──────────────┐
        │ Ledger      │ ───────► │ Repository   │ ───────► │ Remote Repo  │
        │             │          │ (.git)       │          │ (GitHub etc) │
        └─────────────┘          └──────┬───────┘          └──────┬───────┘
               ▲                        │                         │
               │ reconcile              │ pull                    │
               │                 ┌──────▼───────┐                 │
               └──────────────── │ Sync Engine  │ ◄───────────────┘
                                 │ (polling /   │   webhook / poll
                                 │  webhook)    │
                                 └──────────────┘

Web -> Git (исходящая синхронизация)

  1. Вы сохраняете страницу в веб-редакторе
  2. Content Ledger записывает файл .md на диск
  3. Git-движок автоматически коммитит: docs: update {page-title}
  4. Коммиты пушатся в удаленный репозиторий

Git -> Web (входящая синхронизация)

  1. Кто-то пушит commit в удаленный репозиторий (из IDE, CI и т.д.)
  2. Sync Engine обнаруживает изменение (polling или webhook)
  3. Изменения подтягиваются в локальный репозиторий
  4. Content Ledger выполняет реконсиляцию: файловая система -> база данных -> поисковый индекс
  5. WebSocket транслирует обновление подключенным браузерам

Настройка

Подключение удаленного репозитория

При инициализации:

docplatform init \
  --workspace-name "Docs" \
  --slug docs \
  --git-url [email protected]:your-org/docs.git \
  --branch main

После инициализации — отредактируйте конфигурацию workspace:

# .docplatform/workspaces/{id}/.docplatform/config.yaml
git_remote: [email protected]:your-org/docs.git
git_branch: main
git_auto_commit: true
sync_interval: 300

Перезапустите сервер или запустите ручную синхронизацию.

Аутентификация

SSH (рекомендуется)

Сгенерируйте deploy key и добавьте его в репозиторий:

ssh-keygen -t ed25519 -f ~/.ssh/docplatform_deploy_key -N ""

Установите переменную окружения:

export GIT_SSH_KEY_PATH=~/.ssh/docplatform_deploy_key

Добавьте публичный ключ (~/.ssh/docplatform_deploy_key.pub) в deploy keys вашего репозитория. Включите доступ на запись, если хотите, чтобы DocPlatform пушил коммиты.

HTTPS с token

Для HTTPS-репозиториев встройте token в URL:

git_remote: https://x-access-token:[email protected]/your-org/docs.git

Или используйте Git credential helper, настроенный на хосте.

Поведение синхронизации

Auto-commit

Когда git_auto_commit: true (по умолчанию), каждое сохранение в веб-редакторе создает git commit. Быстрые правки в коротком интервале группируются в один commit.

Формат сообщения commit:

docs: update Getting Started

Edited via DocPlatform web editor
Author: [email protected]

Установите git_auto_commit: false, чтобы отключить auto-commit. В этом режиме веб-редактор записывает файлы на диск, но не создает git-коммиты — полезно, если вы хотите коммитить вручную или по расписанию.

Polling

DocPlatform опрашивает удаленный репозиторий с настроенным интервалом (по умолчанию: 300 секунд / 5 минут). Настройте с помощью:

sync_interval: 60  # check every minute

Более короткие интервалы означают более быструю синхронизацию, но больше сетевого трафика.

Webhooks

Для мгновенной синхронизации настройте webhook в вашем репозитории:

GitHub:

  1. Перейдите в Settings -> Webhooks -> Add webhook
  2. Payload URL: https://your-domain.com/api/v1/webhooks/github
  3. Content type: application/json
  4. Secret: установите переменную окружения GIT_WEBHOOK_SECRET с тем же значением
  5. Events: выберите Push events

GitLab:

  1. Перейдите в Settings -> Webhooks
  2. URL: https://your-domain.com/api/v1/webhooks/gitlab
  3. Secret token: совпадает с GIT_WEBHOOK_SECRET
  4. Trigger: Push events

Bitbucket:

  1. Перейдите в Repository settings -> Webhooks -> Add webhook
  2. URL: https://your-domain.com/api/v1/webhooks/bitbucket
  3. Triggers: Repository push

Ручная синхронизация

Запустите синхронизацию через веб-интерфейс (Settings -> Git -> Sync Now) или через API:

curl -X POST http://localhost:3000/api/v1/workspaces/{id}/sync \
  -H "Authorization: Bearer {token}"

Разрешение конфликтов

Конфликты возникают, когда один и тот же файл изменен и в веб-редакторе, и через git push между интервалами синхронизации.

Как обнаруживаются конфликты

DocPlatform отслеживает хеши контента (SHA-256) для каждой страницы. При подтягивании удаленных изменений входящий хеш сравнивается с локальным. Если оба отличаются от общего предка, объявляется конфликт.

Что происходит при конфликте

  1. Операция сохранения или синхронизации возвращает HTTP 409 Conflict
  2. Обе версии (локальная и удаленная) сохраняются
  3. Веб-интерфейс показывает баннер конфликта с вариантами:
    • Keep local — отбросить удаленную версию
    • Keep remote — отбросить локальную версию
    • Download both — получить оба файла для ручного слияния
  4. Создается ветка конфликта (conflict/{page-slug}-{timestamp}) с локальной версией

Предотвращение конфликтов

  • Используйте webhooks вместо polling — более быстрая синхронизация означает меньшее окно для конфликтов
  • Назначайте владельца страницы — один автор на страницу снижает риск коллизий
  • Используйте веб-редактор для контента, IDE для кода — естественное разделение
  • Короткие интервалы синхронизации — sync_interval: 30 в средах с активной совместной работой

Пакетная синхронизация

Когда удаленный push содержит более 20 измененных файлов, DocPlatform переключается в пакетный режим:

  1. Получает все измененные файлы одним diff
  2. Захватывает mutex по каждому пути для всех затронутых путей (отсортированных для предотвращения deadlock)
  3. Обрабатывает все файлы в одной транзакции базы данных
  4. Инвалидирует кэш прав один раз (а не для каждого файла)
  5. Отправляет одно WebSocket-сообщение bulk-sync с общим количеством изменений

Это предотвращает шторм уведомлений и нагрузку на базу данных при push больших изменений (например, начальный импорт репозитория или массовая реструктуризация).

Хранение конфликтов

При обнаружении конфликта обе версии сохраняются на диске:

.docplatform/conflicts/
└── {page-id}/
    └── 20250115T103045Z/
        ├── ours.md      # Local version (web editor)
        └── theirs.md    # Remote version (git push)

Конфликты сохраняются до явного разрешения через веб-интерфейс или API. Команда docplatform doctor сообщает о неразрешенных конфликтах.

Детали git-движка

DocPlatform использует гибридный git-движок, который автоматически выбирает лучший backend:

Условие Движок Причина
Менее 5 000 файлов go-git (in-process) Быстрый, без внешних зависимостей, чистый Go
Более 5 000 файлов Native git CLI (subprocess) Лучшая обработка больших репозиториев, shallow clones
RSS go-git > 512 МБ Native git CLI (fallback) Безопасность памяти — предотвращает OOM на больших репозиториях

Пул из 4 конкурентных воркеров обрабатывает git-операции для всех workspaces. Каждый workspace имеет собственный mutex — операции над разными workspaces выполняются параллельно, а операции над одним workspace сериализуются.

Сообщения auto-commit используют следующий формат:

docs: update {page-title}

Edited via DocPlatform web editor
Author: [email protected]
Committer: DocPlatform <docplatform@local>

Работа с существующими репозиториями

DocPlatform работает с существующими репозиториями документации. При подключении репозитория:

  1. Репозиторий клонируется (или подтягивается, если уже существует локально)
  2. Все файлы .md в директории docs/ индексируются
  3. Frontmatter парсится, и метаданные страниц сохраняются в SQLite
  4. Поисковый индекс строится инкрементально

Файлы вне docs/ не индексируются и не отображаются в редакторе, но остаются в git-репозитории нетронутыми.

Импорт с других платформ

DocPlatform работает с любым Markdown-контентом. Вот как мигрировать с распространенных платформ:

Источник Способ экспорта Примечания
Docusaurus Прямое копирование Уже на основе .md — скопируйте директорию docs/ как есть, добавьте frontmatter при необходимости
GitBook JSON-экспорт -> конвертация Экспорт через GitBook API, конвертация в Markdown
Notion Markdown-экспорт Экспортируйте workspace как Markdown, реструктурируйте в иерархию docs/
Confluence HTML-экспорт -> конвертация Экспортируйте пространства как HTML, конвертируйте в Markdown с помощью pandoc или аналогичного инструмента
Wiki.js Экспорт из базы данных Экспортируйте страницы как Markdown из панели администрирования

Общие шаги миграции:

  1. Экспортируйте контент как Markdown-файлы
  2. Поместите их в git-репозиторий в директорию docs/
  3. Добавьте YAML frontmatter (как минимум title) к каждому файлу
  4. Подключите репозиторий к DocPlatform
  5. Выполните docplatform rebuild для принудительной полной реконсиляции

Реконсилятор DocPlatform автоматически обнаруживает все файлы .md, парсит их frontmatter, назначает ULID страницам без поля id и строит поисковый индекс.