Jellyfin

Обзор

Jellyfin — медиасервер для домашней коллекции фильмов, сериалов, музыки и фотографий. Он сканирует папки, подтягивает обложки, описания и актёрский состав, помнит, на каком месте вы остановились, и отдаёт видео в браузер, на телефон, планшет, телевизор и приставку. Подойдёт тем, кто собирает библиотеку локально и не хочет зависеть от подписок и доступности сервисов.

Проект — форк Emby, сделанный после её перехода на закрытую лицензию, и остаётся полностью свободным: нет платных функций, подписки и обязательной учётной записи у разработчика. Клиенты есть для Android, iOS, Android TV, Kodi и настольных систем, а веб-интерфейс работает в любом браузере.

Рецепт поднимает один контейнер. Настройки, база и метаданные лежат в Docker volume, кэш — в отдельном volume, а каталог с медиатекой подключается только для чтения. Уровень reliable не заявлен: Jellyfin использует встроенную SQLite, а в рецепте нет мониторинга и ресурсных лимитов.

Транскодирование — самая тяжёлая часть работы сервера. Если клиенты играют файлы напрямую, хватит слабого процессора; если нет, потребуется быстрый CPU или аппаратное ускорение, которое в этом рецепте не настроено.

Оценка безопасности

Контейнер запускается без privileged, host network и доступа к Docker socket, с no-new-privileges; наружу открыт только веб-порт и только на 127.0.0.1. Медиатека подключена в режиме read-only, поэтому сервер не может изменить или удалить ваши файлы. DLNA и автообнаружение, которым нужна host network, намеренно выключены.

Главный риск — первый запуск: мастер начальной настройки не требует пароля, и до создания администратора порт нельзя открывать наружу. Контейнер работает от root, как в официальной инструкции upstream; если это критично, задайте user: и самостоятельно выставьте права на volume. Публикуйте сервер только по HTTPS, включайте сильные пароли, а число внешних пользователей ограничивайте: один поток транскодирования 4K способен занять весь процессор.

Образ рецепта просканирован Trivy; найденные критические CVE перечислены в карточке. Как и у любого крупного медиасервера, это в основном уязвимости системных библиотек базового образа, которые закрываются очередным релизом upstream.

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

1. Проверьте сервер Ubuntu или Debian

Для этого рецепта выделите минимум 2 ядра CPU, 1 ГБ RAM и 5 ГБ диска под сам сервер; рекомендуется 4 ГБ RAM. Это консервативная оценка рецепта: upstream не публикует формальные минимальные требования, потому что нагрузка зависит от сценария. Прямое воспроизведение почти не требует ресурсов, а транскодирование одного потока 4K способно занять весь процессор. Место под медиатеку считайте отдельно. Нужны Ubuntu 22.04+ или Debian 12+ с Docker Engine и Docker Compose v2.24+.

docker --version
docker compose version
nproc && free -m

2. Разложите медиатеку по структуре, понятной Jellyfin

Обложки и описания подтягиваются автоматически, только если файл назван по правилам upstream: каталог на фильм, имя с годом в скобках.

/srv/media/Movies/Sintel (2010)/Sintel (2010).mkv
/srv/media/Movies/Tears of Steel (2012)/Tears of Steel (2012).mkv
/srv/media/Shows/Название сериала (2021)/Season 01/Название сериала S01E01.mkv

3. Подготовьте файлы и переменные

Поместите файлы рецепта в отдельный каталог и создайте закрытый .env:

mkdir -p ~/services/jellyfin
cd ~/services/jellyfin
cp .env.example .env
chmod 600 .env
sed -i "s|^JELLYFIN_MEDIA_LOCATION=.*|JELLYFIN_MEDIA_LOCATION=/srv/media|" .env

JELLYFIN_VERSION закрепляет образ; JELLYFIN_PORT задаёт локальный порт; JELLYFIN_PUBLISHED_URL — внешний адрес, который сервер сообщает клиентам; JELLYFIN_MEDIA_LOCATION — каталог с медиатекой, он подключается только для чтения; JELLYFIN_CONFIG_VOLUME и JELLYFIN_CACHE_VOLUME — имена Docker volume; TZ задаёт часовой пояс.

Настройки, база, метаданные и учётные записи лежат в volume /config. В /cache находятся превью и временные файлы транскодирования — этот volume восстанавливается повторным сканированием и в backup не нужен.

4. Пройдите мастер первичной настройки

Мастер не защищён паролем: пока администратор не создан, любой, кто откроет порт, станет владельцем сервера. Поэтому первый запуск делайте через localhost или SSH-туннель.

docker compose pull
docker compose up -d
docker compose ps
ssh -L 8096:127.0.0.1:8096 user@server.example

Откройте http://localhost:8096, выберите язык интерфейса, создайте администратора и добавьте библиотеку, указав путь /media/Movies — это путь внутри контейнера, а не на хосте. После сканирования проверьте, что обложки подтянулись.

Запуск на VPS

На VPS оставьте bind 127.0.0.1, закройте порт 8096 снаружи и публикуйте сервис только через HTTPS reverse proxy. Проверьте состояние и API:

docker compose up -d
docker compose ps
curl --fail http://127.0.0.1:8096/health

Учитывайте, что общий vCPU почти всегда слишком слаб для транскодирования. Держите файлы в форматах, которые клиенты играют напрямую, и следите за разделом Dashboard → Playback, чтобы понимать, когда сервер начинает перекодировать.

Доступ в локальной сети

Без TLS используйте SSH-туннель или VPN. Если reverse proxy работает на другом узле доверенной LAN, замените 127.0.0.1 в compose.yaml на конкретный LAN-адрес сервера и ограничьте порт firewall адресом proxy.

Автообнаружение сервера клиентами использует UDP-порт 7359: чтобы включить его, добавьте - "7359:7359/udp" в раздел ports. DLNA требует network_mode: host и в рецепте не включён — это осознанный отказ от сетевой изоляции контейнера, и включать его стоит только в доверенной сети.

Домен и HTTPS

Замените media.example.com в выбранном файле из proxy/ одним доменом и укажите тот же адрес в JELLYFIN_PUBLISHED_URL. proxy/Caddyfile автоматически получает сертификат; proxy/nginx.conf ожидает сертификат Certbot; proxy/traefik.yaml использует resolver letsencrypt. Для Traefik в контейнере замените 127.0.0.1 на доступный ему host gateway.

Все примеры отключают буферизацию ответа и передают WebSocket: без этого перемотка рвётся, а клиенты теряют связь с сервером. Чтобы в журнале активности были настоящие адреса пользователей, добавьте адрес proxy в Dashboard → Networking → Known proxies.

curl --fail https://media.example.com/health

Резервное копирование

chmod +x backup.sh restore.sh
./backup.sh

Скрипт останавливает контейнер, архивирует весь volume /config и снова его запускает. Остановка обязательна: базы SQLite копируются согласованно только у выключенного сервера. В архив попадают настройки, пользователи, метаданные, изображения и история просмотра.

Медиатека в архив не входит: это ваши файлы, и копировать их нужно отдельно. Кэш также не сохраняется — он восстанавливается повторным сканированием.

Дополнительно в Jellyfin 10.11 есть собственный механизм: Dashboard → Backups → Create Backup создаёт архив в /config/data/backups, не останавливая сервер. Он удобен перед обновлением и попадает внутрь копии, созданной backup.sh.

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

Восстановление полностью заменяет содержимое /config выбранным архивом:

./restore.sh ./backups/jellyfin-YYYYMMDDTHHMMSSZ.tar.gz
docker compose ps
curl --fail http://127.0.0.1:8096/health

Перед заменой скрипт создаёт страховочную копию текущих данных и очищает кэш: превью и трансокды от прежней базы после подмены становятся недействительными. Медиатека при этом не трогается, но пути к библиотекам в восстановленной базе должны совпадать с текущим монтированием /media.

Обновление

Создайте backup и прочитайте release notes. Измените только закреплённый JELLYFIN_VERSION, затем выполните:

./backup.sh
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 jellyfin

Обновляйте версии последовательно и не пропускайте мажорные релизы: миграции базы рассчитаны на переход с предыдущей версии.

Откат

В Jellyfin нет механизма понижения версии. Миграции применяются при первом же запуске нового образа, после чего данные перестают открываться прежней версией. Единственный путь назад — вернуть прежний JELLYFIN_VERSION в .env и восстановить архив, снятый до обновления:

docker compose pull
./restore.sh ./backups/jellyfin-before-update.tar.gz
docker compose up -d

История просмотра и правки метаданных, сделанные после обновления, в таком архиве отсутствуют.

Остановка и полное удаление

docker compose down удаляет контейнер, но сохраняет настройки. Полное необратимое удаление после проверки backup:

docker compose down
docker volume rm jellyfin-config jellyfin-cache
rm -rf ~/services/jellyfin

Каталог JELLYFIN_MEDIA_LOCATION остаётся нетронутым: рецепт подключает его только для чтения и никогда не удаляет.

Источники: установка в контейнере, быстрый старт, именование фильмов, backup и restore и reverse proxy.

Диагностика

Контейнер не становится healthy

docker compose ps
docker compose logs --tail=200 jellyfin
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q jellyfin)"

Healthcheck образа обращается к http://localhost:8096/health внутри контейнера. Чаще всего проблема в правах на volume /config или в нехватке места на диске.

Библиотека пустая после сканирования

Проверьте путь: в настройках библиотеки должен быть путь внутри контейнера (/media/Movies), а не путь хоста (/srv/media/Movies).

docker compose exec jellyfin ls -la /media

Если каталог виден, а файлы не находятся — дело в именовании. Jellyfin ожидает отдельный каталог на фильм и год в скобках; файлы вида film1.mkv в общей куче не распознаются.

Обложки и описания не подтянулись

Метаданные скачиваются из внешних источников, поэтому серверу нужен доступ в интернет. Проверьте связь и запустите обновление вручную:

docker compose exec jellyfin curl -sI https://api.themoviedb.org | head -1

Затем Dashboard → Libraries → Scan All Libraries. Для отдельного фильма помогает пункт «Identify» с ручным указанием года или ссылки на базу.

Видео не воспроизводится или тормозит

Откройте Dashboard → Playback и посмотрите, идёт ли транскодирование. Прямое воспроизведение почти не нагружает сервер, транскодирование 4K занимает весь процессор. Аппаратное ускорение в этом рецепте не настроено: чтобы включить его, нужно пробросить устройство в compose.yaml:

    devices:
      - /dev/dri:/dev/dri

и выбрать метод в Dashboard → Playback → Transcoding. Проверьте, что у пользователя внутри контейнера есть доступ к устройству.

Перемотка рвётся при работе через reverse proxy

Отключите буферизацию ответа и разрешите WebSocket. В Nginx нужны proxy_buffering off и заголовки Upgrade/Connection, в Caddy и Traefik upgrade работает автоматически. Все примеры в proxy/ уже настроены.

В журнале активности один и тот же IP-адрес

Это адрес reverse proxy. Добавьте его в Dashboard → Networking → Known proxies, и сервер начнёт доверять заголовку X-Forwarded-For.

Клиенты не находят сервер автоматически

Автообнаружение использует UDP-порт 7359, который в рецепте не опубликован. Добавьте - "7359:7359/udp" в ports или указывайте адрес сервера в клиенте вручную. DLNA требует host network и в рецепте отключён намеренно.

Мало места на диске

docker system df -v | grep jellyfin
docker compose exec jellyfin du -sh /cache/* /config/metadata

Кэш превью и трансокдов можно удалить целиком: он восстановится. Метаданные в /config/metadata растут вместе с библиотекой — их удаление приведёт к повторному скачиванию обложек.

После обновления сервер не стартует

Смотрите логи миграций:

docker compose logs --tail=200 jellyfin | grep -i "migration\|error"

Понижение версии в Jellyfin не поддерживается: вернуться можно только восстановлением архива, снятого до обновления.