Audiobookshelf

Обзор

Audiobookshelf

Личный сервер ваших аудиокниг без DRM и подкастов. Отдельные аккаунты сохраняют позицию, закладки и коллекции, а права библиотек ограничивают доступ обычного слушателя.

Это сервер собственной медиатеки, в том числе альтернатива ведению аудиобиблиотеки в Plex. Он не предоставляет коммерческий каталог и не заменяет подписку на контент. В upstream есть Android/iOS и OIDC; рецепт проверяет браузер и локальные аккаунты.

Контейнер фиксированной версии работает от UID/GID 1000 с read-only корнем, без capabilities и с одним томом /data. В нём база SQLite, ключ подписи, метаданные, обложки, аудиокниги и подкасты. Сервис tools создаёт первого администратора через штатный API.

25 октября 2026 на amd64 проверены настройка, права обычного пользователя, сканирование, настоящая HTTP range-передача аудио, прогресс, закладка, коллекция и восстановление после удаления тома. Неполный архив отклоняется до изменения данных; backup сохраняет остановленное состояние. По три реальных скриншота на язык содержат собственную озвучку и обложки. ARM64, мобильные клиенты, OIDC, внешние подкасты/метаданные и TLS не проверены.

Оценка безопасности (2026-10-25): loopback, процесс UID 1000, read-only корень, без host/Docker socket, отдельная начальная инициализация. Защитите первый запуск и полный том с личными данными. Это проверка конфигурации, не сканирование уязвимостей.

Пошаговая инструкция

Установка Audiobookshelf

Нужны Docker Engine, Compose >=2.24, 1 CPU, минимум 512 МБ RAM (лучше 1 ГБ) и диск для медиатеки и backup. Образ поддерживает amd64/arm64; проверен amd64.

cp .env.example .env
chmod 600 .env
openssl rand -hex 24

Запишите полученный пароль в AUDIOBOOKSHELF_ADMIN_PASSWORD. Запустите и инициализируйте локально до включения публичного reverse proxy:

docker compose up -d --wait
docker compose run --rm -T bootstrap
docker compose ps

Откройте http://127.0.0.1:13378, войдите как admin с паролем из .env. Для удалённого сервера: ssh -L 13378:127.0.0.1:13378 user@server. Пока bootstrap не завершён, первый аккаунт создаётся без авторизации. Повторный bootstrap сохраняет прежние credentials; изменение .env не сбрасывает пароль. Меняйте его в приложении.

Переменные

• AUDIOBOOKSHELF_VERSION: фиксированная версия официального образа, 2.37.2.
• AUDIOBOOKSHELF_PORT: HTTP-порт loopback, 13378.
• AUDIOBOOKSHELF_ADMIN_PASSWORD: уникальный начальный пароль от 16 символов, без CHANGE_ME.
• AUDIOBOOKSHELF_DATA_VOLUME: именованный том всех данных; каждой установке нужно уникальное имя.
• TZ: часовой пояс IANA, Etc/UTC.
• AUDIOBOOKSHELF_BACKUP_DIR: необязательный каталог backup, по умолчанию ./backups.

Медиатека

В администрировании создайте книжную библиотеку с путём /data/audiobooks; для подкастов используйте /data/podcasts. Каждую книгу храните в отдельном каталоге автора/названия. Пример копирования своего каталога:

docker compose cp './Моя книга' audiobookshelf:/data/audiobooks/
docker compose run --rm permissions

Запустите сканирование. Размещайте только разрешённые вам материалы. Файлы вне /data в backup не входят. Создайте обычных слушателей с доступом к нужным библиотекам, не передавайте root-аккаунт.

HTTPS

После bootstrap выберите proxy/Caddyfile или proxy/nginx.conf, замените домен и при необходимости порт upstream. Примеры рассчитаны на прокси на том же хосте. Контейнерному прокси нужен отдельно настроенный сетевой маршрут: его 127.0.0.1 указывает на него самого. Порт 13378 оставьте закрытым. OIDC и общий RSS-доступ не включены.

Backup и восстановление

./backup.sh
./restore.sh backups/audiobookshelf-TIMESTAMP.tar

Backup останавливает приложение, сохраняет весь том, .env и Compose и возвращает прежнее состояние запуска. Архив может быть размером со всю медиатеку. Шифруйте его и копируйте на другой сервер. На хосте нужны Bash, tar, gzip и Docker; для smoke также Python 3 и OpenSSL.

Восстановление

Восстанавливайте только доверенные архивы. До изменения данных проверяются база и каталоги медиа, создаётся страховочный backup, затем данные заменяются и ожидается health. На новом сервере сначала один раз запустите рецепт. Сохранённая .env автоматически не исполняется: сравните её вручную и используйте соответствующую версию образа. Действуют восстановленные пароли и ключ JWT. После восстановления проверьте воспроизведение и позицию слушателя.

Обновления

Сделайте внешний backup, изучите release notes, задайте явную проверенную версию в .env, выполните docker compose pull && docker compose up -d --wait. Проверьте вход и аудио. Для отката миграции базы восстановите полный архив с соответствующей версией; одной смены тега может не хватить.

VPS

Оставьте HTTP-порт на loopback и закройте его в firewall. Сначала SSH-туннель и bootstrap, затем домен и HTTPS.

LAN / VPN

Для домашнего сервера используйте SSH-туннель или защищённый VPN-прокси. Не открывайте неинициализированный сервис недоверенной сети.

Caddy

После bootstrap подключите proxy/Caddyfile, задайте домен и DNS. Caddy получает TLS-сертификат.

Nginx

После bootstrap используйте proxy/nginx.conf, задайте домен и действующие TLS-сертификаты. Пример поддерживает WebSocket и длительные потоки.

Traefik

После bootstrap подключите proxy/traefik.yaml к file provider прокси на том же хосте. Нужны websecure и letsencrypt. Для контейнерного прокси настройте маршрут отдельно.

Data / Данные

Один именованный том хранит config, metadata, audiobooks и podcasts. Не удаляйте его при обычном обновлении. Нужны права UID/GID 1000.

Rollback / Откат

Сохраните текущее состояние, затем восстановите полный архив до обновления вместе с соответствующей версией образа. Не запускайте старую версию поверх мигрировавшей базы.

Removal / Удаление

docker compose down сохраняет том. После проверенного внешнего backup команда docker compose down --volumes необратимо удаляет медиатеку, аккаунты и прогресс.

Сообщить о проблеме с рецептом

Рассказать, как прошло на вашем сервере

Откроется предзаполненный issue на GitHub. Нужен аккаунт GitHub; после отправки сообщение будет публичным.

Диагностика

Решение проблем

• Экран настройки или ошибка bootstrap: оставьте сервис на loopback, задайте уникальный пароль от 16 символов и выполните docker compose run --rm -T bootstrap. Шаблонный пароль отклоняется; существующие и восстановленные аккаунты сохраняют прежний.
• Нет прав: /data должен быть доступен UID/GID 1000. Сервис permissions создаёт каталоги; скопированным от root файлам может потребоваться исправление владельца. Не открывайте личные данные всем пользователям.
• Нет книг: создайте библиотеку /data/audiobooks, проверьте наличие и чтение файлов, выполните штатное сканирование. Коммерческого каталога в рецепте нет.
• У слушателя пусто: активируйте аккаунт и разрешите нужную библиотеку. Отдельно проверьте права загрузки, изменения и удаления.
• Не играет через прокси: проверьте Range и потоковые запросы, порт upstream; сначала убедитесь в воспроизведении с loopback. TLS-примеры не проверены сквозным тестом.
• В архиве нет медиа: архив только с базой отклоняется. Сохраняйте том целиком; внешним каталогам нужен свой план восстановления.
• После restore другой пароль: .env используется только при первой инициализации. Нужен пароль восстановленного аккаунта или штатная процедура upstream.

docker compose ps
docker compose logs --tail=100 audiobookshelf

Логи, настройки, метаданные и backup могут содержать личные сведения и credentials. Скрывайте их перед публикацией. Изолированная разрушительная проверка использует только временные данные: ./smoke-test.sh.