BookStack

Подключение вики BookStack к Charo — API-токен, индексация полок, книг, глав и страниц, синхронизация прав.

Что индексируется

Коннектор обходит четыре раздела API BookStack и делает из каждой записи отдельный документ:

Раздел	Что попадает в индекс
Полки	название и описание
Книги	название и описание
Главы	название и описание
Страницы	название и содержимое (HTML преобразуется в текст)

Индексируется всё, что доступно учётной записи токена. Вложения к страницам не индексируются.

Предварительные требования

Инсталляция BookStack, доступная с сервера Charo по сети.
Учётная запись BookStack, у роли которой включено право Access system API и есть доступ на чтение к нужным полкам и книгам.
Для синхронизации прав — роль этой учётной записи должна дополнительно уметь управлять ролями и пользователями: коннектор читает списки ролей и людей вики.

Получение учётных данных

В BookStack откройте профиль пользователя → API Tokens и создайте токен.
BookStack покажет Token ID и Token Secret.
В Charo заполните три поля: «Базовый URL BookStack» (адрес инсталляции), «ID API-токена BookStack» и «Секрет API-токена BookStack».

Настройка в Charo

Полей настройки у этого коннектора нет: индексируется всё, что видит учётная запись токена. Задайте название коннектора и, при необходимости, расписание в расширенной конфигурации.

Синхронизация прав

Поддерживается: Charo наследует права BookStack — страницу найдёт только тот, кому она доступна в самой вики. Роли BookStack переносятся как группы, поэтому доступ, выданный роли, работает без перечисления людей.

Права пересинхронизируются примерно раз в пять минут — изменения в BookStack подхватываются с этой задержкой, а не мгновенно.

Три особенности, о которых стоит знать заранее:

Токену нужны права на управление ролями и пользователями. Без них коннектор откажется синхронизировать права сразу, а не посреди обхода.
Полка не передаёт права книгам, которые на ней стоят. В BookStack права полки решают судьбу самой полки; книге они передаются отдельным действием внутри вики. Charo повторяет это поведение — проверяйте права на книге, а не на полке.
Явный запрет роли сильнее разрешения по умолчанию. Если страница отказывает роли напрямую, человек с этой ролью не получит доступ, даже когда вторая его роль страницу открывает.

Роль гостя (visitors) группой в Charo не становится: её участник — не человек.

Требуется активная лицензия; подробнее — «Права доступа».

Ограничения и частота обновления

Обновления забираются инкрементально: коннектор запрашивает записи, изменённые за период с прошлой синхронизации. Фильтр по дате в API BookStack работает с точностью до суток, поэтому в выборку могут попадать записи чуть шире интервала.
Между страницами выдачи коннектор выдерживает паузу, чтобы не упереться в лимит запросов вашей инсталляции BookStack.

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

Ошибка авторизации (HTTP 401)

Неверная пара Token ID / Token Secret либо токен удалён — перевыпустите его.

Отказ в доступе (HTTP 403)

У роли пользователя не включено право Access system API. Если ошибка возникает только при включённой синхронизации прав — роли не хватает прав на управление ролями и пользователями.

Пустая индексация

У учётной записи токена нет доступа к книгам — выдайте роли доступ на чтение нужных полок и книг.

Ошибка соединения

«Базовый URL BookStack» должен быть доступен именно с сервера Charo — проверьте адрес командой curl с этого сервера.