Как установить Chaptarr на VPS для аудиокниг

Что такое Chaptarr и зачем он пользователям Readarr

Chaptarr — это форк Readarr, который управляет аудиокнигами и электронными книгами из одного экземпляра. Он отслеживает новые релизы, отправляет их в ваш клиент для загрузки, а затем переименовывает полученные файлы и размещает их в вашей библиотеке. Он не воспроизводит контент, поэтому его нужно использовать в связке с плеером, например, Audiobookshelf.

Проект Readarr был закрыт 27 июня 2025 года. В официальном уведомлении команды Servarr указана причина: метаданные проекта стали непригодны для использования, а усилия сообщества по переходу на Open Library зашли в тупик. Репозиторий переведен в архив. В результате коллекции книг и аудиокниг остались без поддерживаемого менеджера, и эту задачу взял на себя Chaptarr. Он сохраняет привычную структуру, знакомую по Sonarr и Radarr (индексаторы, клиенты загрузки, профили качества, корневые папки), и добавляет функции для работы с аудиокнигами: организацию с учетом дикторов, поддержку нескольких изданий одного произведения, работу с форматами M4B и разбитыми на главы MP3, а также конвертацию MP3 в M4B.

В этом руководстве использовался тег образа chaptarr/chaptarr:0.9.925, который был самым свежим релизом на 9 августа 2026 года. По состоянию на 11 октября 2026 года последним релизом является 0.9.965, выпущенный 27 сентября 2026 года. Приведенные ниже шаги тестировались только на версии 0.9.925, поэтому в файлах указан именно этот тег; ознакомьтесь с примечаниями к выпуску, прежде чем переходить на более новую версию. Chaptarr позиционирует себя как бета-версию программного обеспечения. Прочитайте раздел об обслуживании в конце руководства, прежде чем подключать его к библиотеке, которую вы не сможете восстановить в случае потери данных.

Что необходимо перед началом работы

VPS с установленным Docker и плагином Compose, а также достаточный объем дискового пространства для библиотеки. Аудиокниги занимают много места, а импорт без использования жестких ссылок временно создает две копии файла, что описано в разделе о томах ниже. Если Docker еще не установлен на сервере, начните с установки и запуска Docker на VPS и вернитесь сюда.

На данный момент Chaptarr поставляется только в виде образа Docker. Нативная поддержка находится в разработке, планируется экспериментальная сборка для Windows, дистрибутивных пакетов нет. По умолчанию контейнер хранит базу данных в /config в формате SQLite. Если вы уже используете PostgreSQL, его можно подключить через переменные окружения Chaptarr__Postgres__*. Для одного пользователя на одном сервере SQLite является оптимальным выбором.

Сервис Compose для Chaptarr

Этот сервис встраивается в существующий стек. Он фиксирует конкретный релиз, публикует веб-интерфейс только на loopback-интерфейсе и подключается к сети, которую уже использует ваш клиент для загрузок.

services:
  chaptarr:
    image: chaptarr/chaptarr:0.9.925
    container_name: chaptarr
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK=002
      - TZ=Europe/Berlin
    volumes:
      - ./config:/config
      - /srv/media/audiobooks:/audiobooks
      - /srv/media/ebooks:/ebooks
      - /srv/media/downloads:/downloads
    ports:
      - 127.0.0.1:8789:8789
    restart: unless-stopped
    networks:
      - arr

networks:
  arr:
    external: true

Строка external: true означает «эта сеть уже существует, подключиться к ней». Используйте этот параметр, если Prowlarr и ваш торрент-клиент запущены из другого проекта Compose, иначе второй файл Compose создаст собственную изолированную сеть, и Chaptarr не сможет разрешить qbittorrent по имени. Узнайте реальное имя сети через docker network ls. Если ваш стек уже описан в одном файле, добавьте сервис chaptarr: в этот файл, а весь блок networks: удалите. Общая структура описана в полном стеке arr в Docker Compose, а правила именования — в том, как разрешаются сети и имена сервисов в Compose.

Создайте каталог конфигурации самостоятельно, затем запустите сервис.

mkdir -p ./config
sudo chown 1000:1000 ./config
docker compose up -d
docker compose ps
docker compose logs -f chaptarr

docker compose ps должен показать, что контейнер находится в состоянии Up. Если контейнер помечен как Restarting, значит, он не смог запуститься и система пытается перезапустить его; причина почти всегда кроется в каталоге конфигурации. Лог перестает обновляться, как только приложение начинает прослушивать порт 8789.

PUID, PGID и директории, создаваемые Docker от имени root

Если оставить параметры PUID=99 и PGID=100 не заданными, Chaptarr использует значения по умолчанию. Это стандартные значения для unRAID, но на обычном VPS с Ubuntu они не соответствуют ни одному системному пользователю, поэтому файлы создаются с владельцем, недоступным для записи из вашей учетной записи. Узнайте свои идентификаторы с помощью команд id -u и id -g и укажите их в файле конфигурации.

Каждый контейнер, работающий с одними и теми же файлами, должен использовать одну и ту же пару идентификаторов. Клиент для загрузки пишет данные в /srv/media/downloads, Chaptarr перемещает файл в /srv/media/audiobooks, а плеер считывает его оттуда. Если клиент для загрузки работает от имени 1000:1000, а Chaptarr — от имени 99:100, импорт завершится ошибкой. Важно не только владение файлом: для создания, переименования или удаления файла требуются права на запись в директории, где он находится. Директории, созданные пользователем 1000 с обычным режимом доступа 755, не предоставляют 99:100 прав на запись, поэтому Chaptarr не может ни добавить книгу в библиотеку, ни удалить её из папки загрузок. Параметр UMASK=002 делает новые файлы доступными для записи группой, что необходимо, когда несколько контейнеров используют одну общую группу для медиафайлов. Полное описание соответствий приведено в как PUID и PGID отображают пользователя контейнера на файлы хоста.

В README упоминается одна специфическая проблема, которую стоит повторить. Если директория ./config не существует в момент запуска docker compose up, Docker создаст её автоматически, назначив владельцем root:root. После этого контейнер будет запущен с UID 1000 и не сможет записать данные в собственную базу, из-за чего завершит работу и будет постоянно перезапускаться. Проверьте владельца с помощью ls -ln ./config, которая выводит числовые идентификаторы вместо имен. Два нуля означают, что владельцем является root. Исправьте это командой sudo chown -R 1000:1000 ./config и снова запустите контейнер.

Почему раздельные тома для аудиокниг и электронных книг лишают вас жестких ссылок

Приведенная выше схема монтирует /audiobooks, /ebooks и /downloads как отдельные привязки (bind mounts), что соответствует команде запуска самого проекта. Такая конфигурация легко читается, но у нее есть один существенный недостаток: жесткие ссылки перестают работать.

Жесткая ссылка — это второе имя для тех же данных на диске. Она не занимает дополнительного места и создается мгновенно, поэтому семейство приложений arr предпочитает их копированию. Жесткая ссылка работает только в пределах одной файловой системы. Внутри контейнера это три разные точки монтирования, поэтому ядро запрещает создание ссылки, даже если пути на хосте находятся на одном диске. Проверьте это самостоятельно.

docker exec chaptarr sh -c 'touch /downloads/linktest && ln /downloads/linktest /audiobooks/linktest'

Команда завершается с ошибкой, заканчивающейся на Invalid cross-device link. Это ядро блокирует создание ссылки между разными точками монтирования, и именно по этой причине Chaptarr переключается на копирование файла. Копия будет корректной, но процесс займет больше времени, и аудиокнига будет существовать в двух экземплярах, пока вы не удалите торрент, чего вы не сделаете, пока продолжаете его раздавать. Удалите /srv/media/downloads/linktest после завершения.

Чтобы сохранить возможность использования жестких ссылок, смонтируйте один родительский каталог:

    volumes:
      - ./config:/config
      - /srv/media:/data

Затем установите корневые папки внутри Chaptarr в /data/audiobooks и /data/ebooks и предоставьте клиенту загрузки такое же монтирование /srv/media:/data, чтобы оба контейнера видели один и тот же путь. Сначала убедитесь, что на стороне хоста используется одна файловая система: df -h /srv/media/downloads /srv/media/audiobooks должен выводить одинаковое значение в столбце Filesystem для обоих путей. Разные значения означают разные диски, и никакая схема монтирования не позволит создать жесткие ссылки между ними. Компромисс между этим подходом и именованными томами (named volumes) описан в bind mounts против именованных томов для медиа.

Доступ к веб-интерфейсу без его публикации

Строка с портом публикует его на 127.0.0.1 не просто так. ufw deny 8789 не защищает опубликованный порт Docker, так как Docker записывает собственные правила NAT (network address translation) в цепочку, которую ядро обрабатывает раньше, чем правила ufw. В результате трафик перенаправляется до того, как ваше правило будет проверено. Это поведение постоянно сбивает пользователей с толку, и оно подробно описано в почему опубликованный порт Docker игнорирует правила ufw. Привязка к loopback полностью решает эту проблему.

Получите доступ к интерфейсу через SSH-туннель с вашего локального компьютера:

ssh -N -L 8789:127.0.0.1:8789 you@your-server

Оставьте этот процесс запущенным и откройте http://127.0.0.1:8789 в браузере. Настройте аутентификацию при первом запуске. Только после этого стоит рассматривать возможность использования reverse proxy с TLS (transport layer security) перед приложением. Когда вы начнете использовать туннели для трех или четырех таких инструментов, каждый со своим паролем, более аккуратным решением станет установка прокси перед self-hosted сервером единого входа, таким как Authentik. Тогда один вход в систему будет открывать доступ ко всем приложениям, а одна процедура отзыва прав закроет их все.

Подключение индексаторов и клиента загрузки

Chaptarr поддерживает стандартные протоколы индексаторов и клиентов загрузки, используемые в семействе arr. Prowlarr передает настройки индексаторов в него так же, как в Sonarr, а обычные клиенты для torrent и usenet подключаются без дополнительной настройки.

Один параметр вызывает затруднения почти у всех пользователей. Когда Chaptarr запрашивает адрес хоста клиента загрузки, не вводите localhost или 127.0.0.1. Внутри контейнера этот адрес указывает на сам контейнер, поэтому Chaptarr пытается обратиться к собственному порту 8080 и сообщает об ошибке подключения. Используйте имя контейнера, qbittorrent, и порт 8080. Убедитесь, что оба контейнера находятся в одной сети с помощью команды docker network inspect arr, которая выводит список всех подключенных контейнеров по их именам.

Если ваш клиент загрузки работает через VPN-контейнер с использованием network_mode: "service:gluetun", у него нет собственного имени в сети, так как он использует сетевое пространство имен Gluetun. Указывайте его как gluetun на порту, который открывает Gluetun. Эта схема и соответствующая маршрутизация описаны в разделе маршрутизация клиента загрузки через Gluetun.

Разрыв с Readarr: реальная стоимость миграции

Chaptarr несовместим с источниками метаданных Readarr. Он определяет названия, авторов и издания через собственный конвейер, работающий с несколькими провайдерами, поэтому идентификаторы, сохраненные Readarr, здесь бесполезны. Прямой импорт базы данных или простое обновление невозможны.

Для существующей библиотеки это означает, что файлы остаются в безопасности, а настройки — нет. Процесс миграции никак не затрагивает данные на диске. Вы добавляете корневую папку, запускаете импорт библиотеки, и Chaptarr сопоставляет найденные файлы со своими метаданными. Вам придется вручную восстановить: профили качества, форматы именования, настройки индексаторов и клиентов, а также исправить все ошибки сопоставления, допущенные Chaptarr. Большая библиотека потребует ручной проверки, поэтому планируйте на это вечер, а не десять минут.

Выполняйте действия в следующем порядке. Остановите контейнер Readarr, но сохраните его том с конфигурацией, чтобы иметь возможность просматривать старые настройки во время переноса. Сначала укажите Chaptarr одну небольшую папку и проверьте результаты сопоставления, прежде чем импортировать всё остальное. Удаляйте старый контейнер только после того, как убедитесь, что всё работает корректно.

Перед сканированием всей библиотеки стоит учесть один нюанс конфиденциальности: запросы метаданных отправляются на api2.chaptarr.com. В README указано, что эти запросы могут содержать идентификаторы провайдеров, поисковые фразы, тип медиа, теги и имена файлов, но не включают полные пути, идентификационные данные пользователя и учетные данные. Имена файлов покидают ваш сервер. Это стандартное поведение для сервиса метаданных, но решение об использовании следует принимать осознанно.

Передача аудиокниг в плеер

Chaptarr занимается организацией файлов. Воспроизведение — задача другой программы. Обычно для этого используют Audiobookshelf, так как он отслеживает позицию прослушивания на разных устройствах и имеет мобильные приложения. Официальный образ — ghcr.io/advplyr/audiobookshelf:latest, а в документации Compose приводится пример, где порт хоста 13378 пробрасывается на порт 80 контейнера.

  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    container_name: audiobookshelf
    ports:
      - 127.0.0.1:13378:80
    volumes:
      - ./abs/config:/config
      - ./abs/metadata:/metadata
      - /srv/media/audiobooks:/audiobooks
    environment:
      - TZ=Europe/Berlin
    restart: unless-stopped

Примонтируйте тот же путь хоста, в который пишет Chaptarr, а затем добавьте /audiobooks в качестве библиотеки через веб-интерфейс. После следующего сканирования появится новый импорт.

Если вы уже используете Jellyfin, можно добавить папку как библиотеку туда. Плеер будет воспроизводить файлы, однако функция возобновления прослушивания для одного длинного файла аудиокниги работает хуже, чем в специализированном сервере. Настройка этого компонента описана в запуске Jellyfin в качестве медиасервера на VPS. Что касается электронных книг, передайте /srv/media/ebooks приложению для чтения; работа Chaptarr завершается сразу после того, как файл переименован и перемещен в нужную директорию.

Риски сопровождения: лицензия, среда выполнения и быстро меняющиеся теги

Chaptarr распространяется по лицензии GPL-3.0, авторские права принадлежат участникам Chaptarr, а части кода — команде Servarr. Это гарантирует открытость исходного кода и возможность создания форка в случае прекращения поддержки текущим мейнтейнером. Проект базируется на .NET 10 — актуальной версии среды выполнения с долгосрочной поддержкой (LTS) на август 2026 года, что обеспечивает поддержку базовой платформы в течение многих лет. Оба фактора важны при оценке жизнеспособности проекта в долгосрочной перспективе.

Номера версий меняются быстро. Версия 0.9.925 была выпущена 9 августа 2026 года, а за последующие семь недель вышло еще пять релизов. Все версии вплоть до 0.9.958 публиковались как предварительные (pre-release); версия 0.9.965 от 27 сентября 2026 года стала первым полноценным релизом. Фиксируйте конкретный тег. Использование latest означает, что автоматическое обновление docker compose pull может привести к смене нескольких версий за неделю. Учитывая молодость проекта, API может меняться между релизами, что нарушит работу ваших скриптов или дашбордов. Фиксация версий — полезная привычка для любого самостоятельно размещаемого проекта. Именно поэтому в руководстве по запуску openGym как трекера тренировок развертывание выполняется из фиксированного git-тега.

Делайте резервную копию перед каждым обновлением и выполняйте обновление осознанно.

docker compose stop chaptarr
sudo tar czf chaptarr-config-backup.tgz ./config
docker compose start chaptarr

docker compose pull chaptarr
docker compose up -d chaptarr

За шесть месяцев работы и более чем одиннадцать тысяч пользователей проект не сообщал о случаях потери данных. Тем не менее, разработчики рекомендуют создавать резервные копии и не использовать проект с библиотеками, потеря которых критична. Относитесь к обеим рекомендациям серьезно. Копируйте архив конфигурации за пределы сервера, так как резервная копия, хранящаяся на том же диске, что и исходные данные, не является надежной. Одного tar-архива достаточно только потому, что Chaptarr хранит свое состояние в одном файле SQLite в /config. Если проект использует отдельный сервер баз данных, необходимо выполнять дамп базы. Именно так выглядит процесс резервного копирования при самостоятельном размещении Chatwoot на VPS, где требуется сохранять данные Postgres и загруженные файлы.

Режимы сбоев и соответствующие им сообщения

Контейнер перезапускается в цикле. docker compose ps показывает Restarting. Выполните ls -ln ./config. Два нуля в столбцах владельца означают, что Docker создал каталог от имени root, и пользователь контейнера не имеет прав на запись в базу данных. Выполните sudo chown -R 1000:1000 ./config.

Импорт не завершается, файлы остаются в папке загрузок. Chaptarr может прочитать файл загрузки, но не может записать его в библиотеку. Сравните ls -ln /srv/media/audiobooks с вашими PUID и PGID. Каталог, принадлежащий другому UID или группе без прав на запись для группы, блокирует перемещение. UMASK=002 предотвращает второй случай для новых файлов.

Использование диска удваивается после каждого импорта. Жесткая ссылка не была создана, поэтому файл был скопирован. Выполните тест ln из раздела томов. Ошибка, заканчивающаяся на Invalid cross-device link, подтверждает это; решением является монтирование с общим родительским каталогом.

Клиент загрузок не подключается. Вы указали localhost в качестве хоста. Внутри контейнера это означает сам Chaptarr. Используйте имя контейнера и проверьте, что docker network inspect arr показывает оба контейнера.

Compose отказывается запускать сервис. Bind for 127.0.0.1:8789 failed: port is already allocated означает, что порт занят другим процессом. Найдите его с помощью sudo ss -lntp | grep 8789.

Браузер ничего не отображает. При привязке порта к 127.0.0.1 вашему ноутбуку не к чему подключаться через интернет. Это ожидаемое поведение. Сначала откройте SSH-туннель.

FAQ

Можно ли перенести библиотеку Readarr в Chaptarr?

Не как импорт. Chaptarr несовместим с источниками метаданных Readarr и использует собственный конвейер провайдеров, поэтому идентификаторы из базы данных Readarr бесполезны, а прямого конвертера баз данных не существует. Ваши файлы на диске останутся нетронутыми. Добавьте те же пути в качестве корневых папок (root folders), запустите импорт библиотеки и позвольте Chaptarr самостоятельно сопоставить файлы. Профили качества, форматы именования, настройки индексаторов и исправление ошибок сопоставления выполняются вручную, поэтому начните с одной небольшой папки, прежде чем импортировать всё остальное.

Почему Chaptarr не может записывать данные в мою папку с аудиокнигами?

У пользователя контейнера нет прав на запись в эту директорию, обычно из-за того, что он работает под UID, отличным от владельца файлов. Если переменные не заданы, Chaptarr использует значения по умолчанию PUID=99 и PGID=100 — это значения для unRAID, которые не подходят для обычного Ubuntu VPS. Установите их в соответствии с вашими id -u и id -g, используйте ту же пару для клиента загрузки и настройте UMASK=002, чтобы новые файлы оставались доступными для записи группой. Проверьте владельца с помощью ls -ln в директории библиотеки, так как эта команда выводит числовые идентификаторы, которые проще сравнивать.

Почему после импорта объем используемого дискового пространства удвоился?

Chaptarr скопировал файл, так как не смог создать жесткую ссылку (hardlink). Монтирование /downloads и /audiobooks как отдельных привязок (binds) делает их разными точками монтирования внутри контейнера, а ядро запрещает создание жестких ссылок между разными точками монтирования с ошибкой Invalid cross-device link. Смонтируйте одну родительскую директорию, например /srv/media:/data, и используйте /data/downloads и /data/audiobooks внутри приложения. Оба пути также должны находиться на одной файловой системе хоста, что можно подтвердить командой df -h.

Умеет ли Chaptarr воспроизводить мои аудиокниги?

Нет. Он находит, скачивает, переименовывает и упорядочивает файлы, а воспроизведение — это задача отдельной программы. Чаще всего используют Audiobookshelf, так как он запоминает позицию прослушивания на разных устройствах; используйте официальный образ ghcr.io/advplyr/audiobookshelf:latest с примонтированным тем же путем к аудиокнигам на хосте. Jellyfin также может воспроизводить файлы, если добавить папку как библиотеку, но функция возобновления воспроизведения на длинных аудиокнигах в одном файле работает хуже.

Безопасно ли запускать Chaptarr на важной для меня библиотеке?

Это бета-версия программного обеспечения от молодого форка, и проект открыто заявляет об этом, хотя за шесть месяцев работы и более чем у одиннадцати тысяч пользователей не было зафиксировано случаев потери данных. Обнадеживающими факторами являются лицензия GPL-3.0, которая позволяет форкать код, и база .NET 10 — среда выполнения с долгосрочной поддержкой (LTS) по состоянию на август 2026 года. Фиксируйте конкретный тег образа, например 0.9.925, вместо latest, делайте резервную копию /config перед каждым обновлением и храните этот архив вне сервера.