OPDS и читалки

Читать в браузере удобно на планшете и ноутбуке, но у телефона и электронной читалки свои приложения с своими шрифтами, словарями и синхронизацией. Для них у Flibusta-at-home есть OPDS — стандартный протокол каталогов электронных книг, который поддерживает большинство читалок. Приложение видит библиотеку как каталог: листает разделы, ищет, скачивает книгу к себе.

Адрес и вход

Адрес каталога — адрес библиотеки плюс /opds:

https://flibusta.example.org/opds
https://example.org/flibusta/opds      # subfolder-схема

Точный адрес для вашей установки показан в разделе «Справка» самой библиотеки.

Аутентификация — HTTP Basic, те же имя и пароль, что для входа через браузер. Из доверенной сети (FLIBUSTA_TRUSTED_NET) пароль не требуется, но тогда персональных разделов у каталога нет. Неудачные попытки входа по OPDS считаются так же, как через форму (15-минутная блокировка после серии ошибок, запись в лог попыток входа с кодом 6, срабатывание fail2ban), так что опечатка в пароле в настройках приложения может временно заблокировать аккаунт — приложения имеют привычку молча повторять запрос.

Читалка присылает пароль в каждом запросе, а его проверка намеренно медленная, поэтому в конфигурации с Redis удачная проверка запоминается на пять минут. Ошибочные пароли не запоминаются никогда — на блокировки это не влияет. Заметить эту деталь можно в одном случае: после смены пароля читалка со старым паролем может ещё несколько минут получать доступ, пока запись не истечёт. Если нужно отрезать устройство немедленно, удалите или пересоздайте учётную запись в разделе «Пользователи» — это сбрасывает запись сразу.

Часть приложений умеет принимать логин и пароль прямо в адресе:

https://имя:пароль@flibusta.example.org/opds

Специальные символы в имени и пароле нужно percent-кодировать: @ → %40, # → %23, / → %2F, : → %3A, ? → %3F, & → %26, + → %2B, % → %25, пробел → %20. Если приложение с таким адресом не справляется, укажите адрес без учётных данных и введите их в диалоге, который появится при первом обращении.

Что есть в каталоге

Корень каталога:

Раздел	Что внутри
Новинки	последние добавленные книги, постранично
Книжные полки	общие списки избранного (см. настройки читателя)
По жанрам	дерево жанров Флибусты, внутри — книги жанра
По авторам	алфавитный указатель: буква → следующая буква → авторы; у автора — книги по сериям и по алфавиту
По сериям	такой же указатель по названиям серий

Плюс поиск: каталог объявляет OpenSearch, так что кнопка «поиск» в приложении ищет по названиям книг (/opds/search?q=…), а из указателя авторов — по авторам.

Каждая книга в ленте несёт обложку (миниатюру и полноразмерную), аннотацию, авторов, серию со ссылкой «все книги серии» и ссылку на скачивание. Скрытые жанры и фильтры сеанса из веб-интерфейса на OPDS не действуют: каталог показывает всё.

Форматы: что скачает читалка

Ссылка на скачивание в ленте OPDS ведёт на файл в том формате, в котором книга хранится: для fb2 — fb2.php?id=<id> (fb2, упакованный в zip), для остальных — usr.php?id=<id> с исходным pdf, epub, djvu и т.д.

Конвертация fb2 → epub/kfx/azw8 через OPDS не предлагается: лента отдаёт fb2, и дальше всё зависит от приложения. Большинство мобильных читалок (KOReader, FBReader, Moon+ Reader, PocketBook Reader, Cool Reader) читают fb2 и fb2.zip напрямую — проблемы нет. Два исключения:

• Kobo: встроенная читалка fb2 не понимает, а OPDS-клиент в прошивке отсутствует. Путь — скачать в браузере со страницы книги в формате kepub (пункт в выпадающем меню кнопки скачивания) и передать на устройство по USB или через Calibre.
• Kindle: аналогично, OPDS нет; со страницы книги скачивается kfx или azw8 и отправляется на устройство через Send to Kindle или USB.

Если очень нужно, прямая ссылка на конвертированный файл конструируется руками: fb2.php?id=<id>&final_format=<epub2|epub3|kepub|kfx|azw8|pdf|txt|md> — с той же HTTP Basic аутентификацией, что и OPDS. Так можно, например, сохранить в закладках телефона ссылку «эта книга в epub».

Подключение в приложениях

Везде принцип один: найти «каталоги» / «сетевую библиотеку» / «OPDS», добавить каталог, указать адрес и учётные данные. Ориентиры:

• KOReader (Android, читалки Kobo/Kindle/PocketBook с KOReader): меню «Файловый менеджер» → «OPDS-каталог» → «+», адрес, имя, пароль. Умеет поиск, качает fb2 и читает его сам. Самый беспроблемный вариант для электронных чернил.
• FBReader (Android, iOS, десктоп): «Сетевая библиотека» → «Добавить каталог» → адрес. При первом обращении спросит логин и пароль.
• Moon+ Reader (Android): «Сетевая библиотека» → «Добавить», адрес, учётные данные в отдельных полях.
• PocketBook Reader (Android, iOS) и Cool Reader: аналогично, раздел сетевых библиотек / OPDS.
• Foliate (Linux) и Thorium Reader (Windows/macOS/Linux): раздел каталогов, вставить адрес.
• Calibre: сам по себе OPDS-клиентом не является, но книгу, скачанную любым способом, удобно конвертировать и отправлять на устройство через него.

Названия пунктов меню меняются от версии к версии; ищите слова OPDS, «каталог», «сетевая библиотека».

Типичные проблемы

«Не удаётся подключиться» при рабочем адресе в браузере. Три причины по частоте: приложение не принимает сертификат (самоподписанный или внутренний CA — установите корневой сертификат на устройство или используйте Let’s Encrypt); адрес указан без https://; в адресе subfolder-схемы потерян префикс (/flibusta/opds, а не /opds).

Спрашивает пароль снова и снова. Либо пароль неверный и аккаунт уже заблокирован на 15 минут (см. «Пользователи → Активность пользователей»), либо reverse proxy не передаёт заголовок Authorization в php-fpm. В шаблонах для SWAG он передаётся явно (fastcgi_param HTTP_AUTHORIZATION); для других прокси — см. статью о reverse proxy.

Каталог открывается, но обложки не показываются. Обложки отдаёт extract_cover.php, который тоже требует аутентификации; некоторые приложения не передают учётные данные при запросе картинок. Это косметика; книги при этом скачиваются нормально.

Пустые «Книжные полки». Раздел показывает общие списки, унаследованные от старых версий библиотеки, а не личное избранное читателя. Если таких списков нет, раздел пуст — это нормально.

Книга скачивается как .zip. Так и задумано: fb2 отдаётся упакованным. Все нормальные читалки открывают fb2.zip напрямую; если ваша не умеет, распакуйте или используйте ссылку с final_format=epub3.

Доступ снаружи. OPDS — это обычные HTTPS-запросы, поэтому работает через любой из способов из статьи о доступе из интернета. С VPN-вариантами (Tailscale и т.п.) есть нюанс: VPN на телефоне должен быть включён в момент, когда приложение обращается к каталогу, а фоновая синхронизация некоторых читалок этого не проверяет и молча получает ошибку.