Усунення несправностей

Цей посібник охоплює поширені проблеми та їх рішення. Для отримання діагностичної інформації завжди починайте з:

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 увімкнено доступ на запис (необхідний для відправки)

Синхронізація git показує “no changes”, але файли оновлювалися

Причина: Зміни зроблені у файлах поза директорією docs/, яку DocPlatform не індексує.

Рішення: Переконайтесь, що ваші Markdown файли знаходяться в директорії docs/ робочого простору. Файли в інших директоріях зберігаються в git, але не відстежуються DocPlatform.

Конфлікт: HTTP 409 при збереженні

Причина: Сторінку було змінено іншим користувачем або через git push між вашим завантаженням та збереженням.

Рішення:

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

Запобігання:

  • Увімкніть webhook для швидшої синхронізації (зменшення вікна конфлікту)
  • Використовуйте індикатори присутності, щоб бачити, хто що редагує
  • Призначте відповідальність за сторінки для уникнення одночасного редагування

Git push не вдається: “remote rejected”

Причина: Deploy key не має доступу на запис, або правила захисту гілки запобігають прямим push.

Рішення:

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

Автентифікація

“401 Unauthorized” на кожному запиті

Причина: Токен доступу JWT закінчився (15-хвилинний час життя за замовчуванням).

Рішення: Веб-редактор автоматично обробляє оновлення токенів. При прямому використанні API викликайте ендпоінт оновлення:

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 для примусової повної переіндексації

Пошук працює повільно

Причина: Дуже великі робочі простори (1000+ сторінок) із складними запитами.

Рішення:

  • Використовуйте більш конкретні пошукові терміни
  • Використовуйте фільтри за тегами для звуження області пошуку
  • Майбутні релізи підтримуватимуть 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.

Симптоми:

  • Сторінка зникає з результатів пошуку
  • Сторінка виключена з опублікованої документації
  • Користувачі без ролі адміністратора отримують 403 Forbidden
  • Адміністратор бачить банер попередження на сторінці

Рішення:

  1. Увійдіть як Admin або Super Admin
  2. Відкрийте зачеплену сторінку у веб-редакторі
  3. Перемкніться в режим необробленого 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, виключена з пошуку та опублікованої документації Виробництво — запобігає випадковому розкриттю
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, збільшіть розмір тому

Продуктивність

Високе використання пам’яті

Очікувано: < 80 МБ у стані спокою, < 200 МБ під навантаженням.

Якщо використання пам’яті перевищує 200 МБ:

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

Повільний рендеринг сторінок

Очікувано: < 50 мс p99.

Якщо рендеринг сторінок повільний:

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

Отримання допомоги

Якщо ви не можете вирішити проблему:

  1. Запустіть docplatform doctor --bundle для генерації діагностичного bundle
  2. Перевірте логи сервера на предмет повідомлень про помилки
  3. Відкрийте issue на GitHub із діагностичним bundle та відповідними записами логів

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