Устранение неполадок

В этом руководстве рассмотрены распространенные проблемы и их решения. Для получения диагностической информации всегда начинайте с:

docplatform doctor

Запуск сервера

Сервер не запускается: “address already in use”

Причина: Другой процесс использует настроенный порт.

Решение:

# Find what's using port 3000
lsof -i :3000  # macOS/Linux
ss -tlnp | grep 3000  # Linux

# Option 1: Stop the other process
# Option 2: Use a different port
docplatform serve --port 8080

Сервер не запускается: “permission denied”

Причина: Процесс не имеет прав чтения/записи к директории данных.

Решение:

# Check ownership
ls -la .docplatform/

# Fix ownership (if running as docplatform user)
sudo chown -R docplatform:docplatform .docplatform/

# Fix permissions
chmod 700 .docplatform/

Сервер не запускается: “database is locked”

Причина: Запущен другой процесс DocPlatform, или предыдущий процесс не завершился корректно.

Решение:

# Check for other docplatform processes
ps aux | grep docplatform

# If a process is stuck, kill it
kill -SIGTERM <pid>

# If the lock file persists after no processes are running
# SQLite WAL mode handles this automatically on restart
docplatform serve

Синхронизация git

“Permission denied (publickey)” при синхронизации git

Причина: SSH-ключ не настроен или не имеет доступа к репозиторию.

Решение:

  1. Проверьте наличие ключа:

    ls -la $GIT_SSH_KEY_PATH

  2. Проверьте, что ключ добавлен в deploy keys репозитория:

    ssh -T -i $GIT_SSH_KEY_PATH [email protected]

  3. Убедитесь, что для deploy key включен доступ на запись (необходим для push)

Синхронизация git показывает “no changes”, хотя файлы были обновлены

Причина: Изменения были внесены в файлы вне директории docs/, которую DocPlatform не индексирует.

Решение: Убедитесь, что ваши Markdown-файлы находятся в директории docs/ workspace. Файлы в других директориях сохраняются в git, но не отслеживаются DocPlatform.

Конфликт: HTTP 409 при сохранении

Причина: Страница была изменена другим пользователем или через git push между загрузкой и сохранением.

Решение:

  1. Веб-интерфейс показывает баннер конфликта с обеими версиями
  2. Нажмите Download both, чтобы получить оба файла
  3. Вручную объедините изменения
  4. Сохраните объединенную версию

Предотвращение:

  • Включите webhooks для более быстрой синхронизации (уменьшает окно конфликта)
  • Используйте индикаторы присутствия, чтобы видеть, кто что редактирует
  • Назначайте владельцев страниц для предотвращения одновременного редактирования

Git push не проходит: “remote rejected”

Причина: Deploy key не имеет доступа на запись, или правила защиты ветки запрещают прямые push.

Решение:

  1. Проверьте, что deploy key имеет доступ на запись в настройках репозитория
  2. Проверьте правила защиты ветки — DocPlatform пушит напрямую в настроенную ветку
  3. Если защита ветки необходима, настройте DocPlatform на push в незащищенную ветку

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

“401 Unauthorized” на каждый запрос

Причина: JWT access token истек (по умолчанию срок жизни 15 минут).

Решение: Веб-редактор обрабатывает обновление токена автоматически. При прямом использовании API вызовите endpoint обновления:

curl -X POST http://localhost:3000/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your-refresh-token"}'

Невозможно войти после ротации JWT-ключа

Причина: Все токены были инвалидированы при удалении и регенерации JWT-ключа.

Решение: Это ожидаемое поведение. Все пользователи должны войти заново после ротации ключа. Очистите cookies/хранилище браузера и войдите с паролем.

OIDC-вход перенаправляет на страницу ошибки

Причина: URL обратного вызова OAuth не совпадает с настроенным в Google/GitHub.

Решение:

  1. Проверьте URL обратного вызова в настройках провайдера OAuth
  2. Он должен быть: https://your-domain.com/api/v1/auth/callback/google (или /github)
  3. Убедитесь, что переменные окружения OIDC_*_CLIENT_ID и OIDC_*_CLIENT_SECRET установлены правильно
  4. Перезапустите сервер после изменения переменных окружения OIDC

Первый пользователь не является Super Admin

Причина: База данных уже содержала записи пользователей от предыдущей установки.

Решение:

# WARNING: This deletes all data
docplatform serve  # stop first
rm .docplatform/data.db
docplatform serve
# Register your admin account

Делайте это только на новой установке. Для существующих установок используйте базу данных для прямого обновления ролей пользователей (продвинутый уровень).

Поиск

Поиск не возвращает результатов

Причина: Поисковый индекс может быть пустым или рассинхронизирован.

Решение:

# Check search health
docplatform doctor

# If the index is out of sync, rebuild
docplatform rebuild

Результаты поиска устарели (не отражают недавние правки)

Причина: Асинхронная задача индексации еще не обработана (обычно задержка < 1 секунды).

Решение: Подождите момент и повторите попытку. Если проблема сохраняется:

  1. Проверьте логи сервера на ошибки индексации
  2. Выполните docplatform rebuild для принудительной полной переиндексации

Поиск работает медленно

Причина: Очень большие workspaces (1 000+ страниц) со сложными запросами.

Решение:

  • Используйте более конкретные поисковые запросы
  • Используйте фильтры по тегам для сужения области
  • В будущих версиях будет поддержка Meilisearch для высокопроизводительного поиска

Восстановление данных

Случайно удалена страница

Вариант 1: История git (если включена синхронизация git)

cd .docplatform/workspaces/{id}/docs/
git log --all — path/to/deleted-page.md
git checkout <commit-hash> — path/to/deleted-page.md

Затем выполните docplatform rebuild для переиндексации.

Вариант 2: Резервная копия базы данных

# List backups
ls .docplatform/backups/

# Restore from backup (stops the server first)
cp .docplatform/backups/{latest}.db .docplatform/data.db
docplatform serve

База данных повреждена

Решение:

  1. Остановите сервер
  2. Проверьте наличие свежей резервной копии: 
    ls -la .docplatform/backups/
  3. Восстановите из резервной копии: 
    cp .docplatform/backups/{latest}.db .docplatform/data.db
  4. Если резервная копия недоступна, перестройте из файловой системы: 
    rm .docplatform/data.db
docplatform rebuild
  5. Запустите сервер

Файловая система (файлы .md) является источником истины. Даже при потере базы данных rebuild воссоздает ее из ваших файлов.

Потерян JWT-ключ

Причина: Файл jwt-key.pem был удален.

Последствия: Все пользовательские сессии инвалидированы. Пользователи должны войти заново.

Решение: Запустите сервер — новый ключ генерируется автоматически. Данные не теряются, но все пользователи должны пройти повторную аутентификацию.

Ошибки frontmatter

Страница стала недоступна после редактирования frontmatter

Причина: Невалидный YAML в блоке frontmatter. DocPlatform по умолчанию использует строгий режим — при ошибке парсинга frontmatter доступ к странице ограничивается только ролью Admin, чтобы опечатка в YAML не привела к случайному раскрытию приватной страницы.

Симптомы:

  • Страница исчезает из результатов поиска
  • Страница исключена из опубликованной документации
  • Пользователи без роли admin получают 403 Forbidden
  • Администратор видит предупреждающий баннер на странице

Решение:

  1. Войдите как Admin или Super Admin
  2. Откройте затронутую страницу в веб-редакторе
  3. Переключитесь в режим raw Markdown (переключатель </>)
  4. Исправьте YAML frontmatter (частые проблемы: отсутствующие кавычки вокруг значений с двоеточиями, неправильный отступ, незакрытые скобки)
  5. Сохраните — страница будет переиндексирована и доступ восстановлен

Если нет доступа к веб-редактору, исправьте файл напрямую на диске:

# Edit the Markdown file
nano .docplatform/workspaces/{id}/docs/{path-to-page}.md

# Rebuild to re-index
docplatform rebuild

Режимы обработки ошибок frontmatter

Режим Поведение при невалидном YAML Когда использовать
Strict (по умолчанию) Страница ограничена до Admin, исключена из поиска и публикации Production — предотвращает случайное раскрытие
Lenient Сохраняет последний корректный frontmatter из базы данных, показывает предупреждение Разработка — меньше прерываний при редактировании

Строгий режим гарантирует, что опечатка в YAML никогда случайно не сделает ограниченную страницу публичной. Это намеренное решение по безопасности.

Дисковое пространство

Предупреждение “Low disk space” от doctor

Причина: DocPlatform предупреждает, когда свободное дисковое пространство падает ниже 1 ГБ.

Последствия: SQLite требует свободное дисковое пространство для операций WAL (write-ahead log). Если диск заполнится полностью, запись не удается, и данные могут быть повреждены.

Решение:

  1. Проверьте использование диска: df -h
  2. Очистите старые резервные копии: уменьшите BACKUP_RETENTION_DAYS или вручную удалите старые файлы в {DATA_DIR}/backups/
  3. Переместите директорию данных на более емкий диск: обновите DATA_DIR и переместите директорию
  4. При использовании Docker увеличьте размер volume

Производительность

Высокое потребление памяти

Ожидаемое: < 80 МБ в простое, < 200 МБ под нагрузкой.

Если потребление памяти превышает 200 МБ:

  1. Проверьте количество активных WebSocket-соединений
  2. Проверьте количество workspaces и общее количество страниц
  3. Большие git-репозитории (>5 000 файлов) используют больше памяти — гибридный движок автоматически переключается на native git CLI, когда RSS go-git превышает 512 МБ

Медленный рендеринг страниц

Ожидаемое: < 50 мс p99.

Если рендеринг страниц медленный:

  1. Проверьте дисковый I/O — производительность SQLite зависит от скорости диска
  2. Используйте SSD для директории данных
  3. Проверьте, находится ли файл базы данных на сетевой файловой системе (NFS/CIFS) — переместите на локальный диск

Получение помощи

Если не удается решить проблему:

  1. Выполните docplatform doctor --bundle для создания диагностического bundle
  2. Проверьте логи сервера на сообщения об ошибках
  3. Откройте issue на GitHub с диагностическим bundle и соответствующими записями журнала

Диагностический bundle не содержит контент страниц, пароли или API-токены — только структурные метаданные и конфигурацию (с замаскированными секретами).