Calibre-Web на сервере: частые ошибки и решения

MAATRIX

Calibre-Web ставится за десять минут и в первый же час начинает капризничать: библиотека не находится, обложки не грузятся, при загрузке новой книги сервис падает в 500-ю ошибку, а с телефона через приложение книги не синхронизируются вовсе. Проблема почти всегда одна и та же — права доступа, формат library-файла или неправильно прокинутый том в Docker. Разберём по порядку, что чаще всего ломается и как это чинить, без переустановки с нуля.

"Библиотека не найдена" при первом запуске

Самая частая ошибка новичков: Calibre-Web — это не Calibre-сервер, а веб-интерфейс поверх уже существующей библиотеки Calibre. Ему нужен путь к папке, где лежит файл metadata.db — тот самый, который создаёт десктопный Calibre или утилита calibredb. Если вы просто указали пустую директорию, сервис честно скажет, что библиотеки там нет, и предложит создать новую (пустую) базу.

Если вы переносите существующую библиотеку с ПК, убедитесь, что в целевой папке на сервере реально лежит metadata.db, а не только файлы книг:

ls -la /srv/calibre-library/ | grep metadata.db

Если файла нет, а книги есть — библиотеку придётся собрать заново. Проще всего сделать это через calibredb прямо на сервере:

pip install calibre
calibredb list --library-path /srv/calibre-library

Если команда calibredb создаёт новую пустую базу поверх старых файлов книг — это ещё не катастрофа: metadata.db можно восстановить импортом файлов заново (calibredb add), но метаданные (теги, серии, рейтинги) при этом потеряются, если у вас нет резервной копии базы. Отсюда практический вывод: metadata.db — самый ценный файл во всей системе, и бэкапить нужно именно его, а не только сами fb2/epub.

Docker-контейнер видит библиотеку, но не может в неё писать

Второй частый сценарий — в веб-интерфейсе всё открывается, книги читаются, но при попытке загрузить новую книгу или отредактировать метаданные сервис выдаёт PermissionError или молча ничего не сохраняет. Причина в 99% случаев — несовпадение UID/GID между процессом внутри контейнера и владельцем файлов на хосте.

Официальный образ linuxserver/calibre-web запускается от пользователя с UID/GID, заданным переменными PUID/PGID. Если вы примонтировали папку библиотеки, принадлежащую root или другому пользователю, контейнер физически не может в неё писать. Проверка:

ls -la /srv/calibre-library
id calibre-web    # если создавали отдельного пользователя на хосте

Рабочий docker-compose.yml, который снимает 90% таких проблем:

services:
  calibre-web:
    image: lscr.io/linuxserver/calibre-web:latest
    container_name: calibre-web
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Europe/Moscow
      - DOCKER_MODS=linuxserver/mods:universal-calibre
    volumes:
      - ./config:/config
      - /srv/calibre-library:/books
    ports:
      - "8083:8083"
    restart: unless-stopped

Ключевое: PUID/PGID должны совпадать с владельцем /srv/calibre-library на хосте. Узнать их:

stat -c '%u %g' /srv/calibre-library

и подставить эти значения в PUID/PGID, либо наоборот — сделать chown папки под нужного пользователя:

sudo chown -R 1000:1000 /srv/calibre-library

Отдельно про DOCKER_MODS=linuxserver/mods:universal-calibre — этот мод добавляет в контейнер полноценный Calibre-бинарник, который нужен для конвертации форматов (epub → mobi и обратно) и для генерации обложек из EPUB без встроенной картинки. Без него функция конвертации в интерфейсе просто не появится, а часть обложек будет показываться серыми заглушками.

Обложки не грузятся или показывают заглушку

Если сама библиотека работает, а вот обложки книг — сплошные серые прямоугольники, причин обычно две.

Первая — не установлен мод universal-calibre (см. выше), и Calibre-Web физически нечем извлечь обложку из EPUB-контейнера для старых книг без закешированной миниатюры.

Вторая — файлы кеша обложек не пишутся из-за прав доступа, аналогично проблеме выше, только применительно к папке /config контейнера, где Calibre-Web хранит свою внутреннюю SQLite-базу и thumbnail-кеш:

docker exec -it calibre-web ls -la /config

Если владелец записей внутри /config не совпадает с PUID/PGID, пересоздайте том с правильными правами:

docker compose down
sudo chown -R 1000:1000 ./config
docker compose up -d

Полезно понимать разницу между bind-mount (./config:/config, как в примере выше) и именованным Docker-томом — у них разная логика владения файлами и разное поведение при бэкапе. Если сомневаетесь, какой вариант выбрать для конкретного сервиса, у нас есть отдельный разбор типов Docker-томов и когда какой использовать.

Ошибка 500 при загрузке книги через веб-интерфейс

Если загрузка отдельных книг падает с 500-й ошибкой (а остальной интерфейс работает нормально), первым делом смотрите логи контейнера — там почти всегда есть трейсбек с конкретной причиной:

docker logs -f --tail 100 calibre-web

Частые находки в логах:

• Нет места на диске. SQLite не может дописать транзакцию, и Calibre-Web падает с невнятной 500-й вместо явного сообщения о переполненном диске. Проверяется одной командой: df -h. Если диск действительно забит, у нас есть разбор что делать, когда на VPS закончилось место.
• Файл книги в неподдерживаемом или битом формате. Calibre-Web (без мода universal-calibre) умеет напрямую работать не со всеми форматами — попробуйте загрузить тот же файл вручную через calibredb add и посмотрите, ругается ли сам Calibre.
• Превышен лимит размера загружаемого файла, если Calibre-Web стоит за nginx как обратный прокси, — по умолчанию у nginx ограничение client_max_body_size в 1 МБ, а книги (особенно PDF-сканы) легко превышают это в разы.

Для последнего случая в конфиге сайта nginx нужно явно поднять лимит:

server {
    listen 443 ssl;
    server_name library.example.com;

    client_max_body_size 200M;

    location / {
        proxy_pass http://127.0.0.1:8083;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Если вы ещё не настраивали обратный прокси для Calibre-Web, у нас есть пошаговая инструкция по nginx как reverse proxy на VPS, а если прокси уже стоит, но капризничает — отдельная статья про частые ошибки nginx как reverse proxy.

Отправка на Kindle и почтовая рассылка не работают

Функция "Send to Kindle" в Calibre-Web использует обычную отправку email через SMTP, и её настройка — источник почти столько же ошибок, сколько сама библиотека. В Admin → Edit Basic Configuration → Configure Email Server нужно указать реальный SMTP-сервер, порт, логин и пароль. Для Gmail это не обычный пароль от аккаунта, а пароль приложения (App Password), который создаётся отдельно в настройках безопасности Google — обычный пароль Gmail отклонит с ошибкой авторизации.

Типичные грабли:

Последний пункт актуален не для всех VPS — часть недорогих провайдеров режет исходящий SMTP-трафик по умолчанию для борьбы со спамом. Стоит уточнять это до аренды, если рассылка на Kindle для вас критична.

OPDS-каталог и мобильные читалки не синхронизируются

Calibre-Web отдаёт библиотеку по протоколу OPDS (/opds) — это то, что использует большинство мобильных читалок вроде KOReader, Moon+ Reader или FBReader для просмотра каталога и скачивания книг напрямую с телефона. Если приложение не видит книги или просит пароль по кругу, проверьте по порядку:

1. URL OPDS-каталога. Он не совпадает с адресом обычного веб-интерфейса — это https://library.example.com/opds, а не корень сайта. В настройках приложения-читалки OPDS-каталог добавляется отдельным пунктом, не как обычная закладка браузера.
2. HTTPS обязателен для большинства читалок. Многие приложения на Android и iOS отказываются работать с OPDS по обычному HTTP из соображений безопасности. Если у вас ещё нет сертификата на поддомен, инструкция по установке Let's Encrypt на VPS закрывает это за один заход.
3. Basic Auth vs встроенная авторизация Calibre-Web. Если OPDS защищён и через nginx Basic Auth, и через встроенную авторизацию Calibre-Web одновременно, часть читалок не умеет пройти двойной логин подряд. Проще оставить один уровень авторизации — либо на nginx, либо на самом сервисе.

Если после проверки всех трёх пунктов синхронизация всё равно не идёт, временно откройте /opds в обычном браузере в режиме инкогнито — если каталог отдаётся корректным XML, проблема на стороне конкретного мобильного приложения, а не сервера.

Медленный отклик при большой библиотеке

На библиотеках от 5–10 тысяч книг Calibre-Web на слабом VPS (1 vCPU, 1–2 ГБ RAM) начинает заметно тормозить: страница со списком книг грузится по несколько секунд, полнотекстовый поиск может подвисать. Это упирается в две вещи одновременно — SQLite не рассчитан на параллельные тяжёлые запросы, а сам движок Calibre-Web делает не самые оптимальные SQL-запросы на больших выборках.

Практические меры, которые реально помогают:

• Отключить генерацию обложек "на лету" для форматов без встроенной миниатюры и один раз прогнать пересборку кеша обложек через calibredb, а не полагаться на автогенерацию при каждом обращении.
• Вынести /config на более быстрый диск (NVMe вместо сетевого/HDD-хранилища) — SQLite крайне чувствителен к latency диска на операциях записи.
• Дать сервису больше RAM, если сервер делит ресурсы с другими контейнерами — Calibre-Web сам по себе лёгкий (десятки МБ), но операции конвертации и индексации могут кратковременно требовать заметно больше.

Если библиотека растёт быстрее, чем ресурсы текущего тарифа, для домашней медиатеки на 10+ тысяч книг разумнее сразу брать сервер с NVMe-диском и запасом по RAM, чем потом мигрировать библиотеку на новый хост под нагрузкой.

Частые вопросы