Jellyfin: типичные ошибки и как их исправить

Коротко о главном

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

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

Большинство проблем с Jellyfin сводится к нескольким повторяющимся ошибкам. Ниже — что проверить в первую очередь и как не усугубить ситуацию.

Почему это происходит

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

Типичные ошибки

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

1. Видео не воспроизводится

Проверьте, поддерживает ли клиент кодек. Включите транскодирование или используйте совместимый формат. Смотрите журнал Jellyfin.

2. Нет доступа к файлам

Проверьте права пользователя jellyfin и права на каталоги. В Docker путь должен быть смонтирован внутрь контейнера.

3. Транскодирование падает

Проверьте /dev/dri, драйверы и выбранный ускоритель. Для NVIDIA нужны дополнительные библиотеки и права.

Как настроить правильно

Правильная последовательность проста: проверить версию и зависимости, сделать резервную копию конфигурации, внести минимальное изменение, проверить логи и только потом двигаться дальше.

Установка

В Debian, Ubuntu и Linux Mint используется пакетный менеджер APT:

sudo apt install jellyfin

В Fedora и RHEL-совместимых системах пакет ставится через DNF:

sudo dnf install jellyfin

В Arch Linux и производных пакет доступен в официальных репозиториях:

sudo pacman -S jellyfin-server jellyfin-web

1. Подготовьте медиатеку

Разложите файлы по понятной структуре: фильмы отдельно, сериалы по сезонам. Jellyfin ориентируется на имена файлов и папок.

tree -L 2 /srv/media | head -30
sudo chown -R jellyfin:jellyfin /srv/media

2. Установите и запустите

После установки откройте веб-интерфейс на порту 8096 и пройдите мастер настройки. Не публикуйте порт в интернет до настройки TLS.

sudo systemctl enable --now jellyfin
systemctl status jellyfin --no-pager
curl -I http://127.0.0.1:8096

3. Добавьте библиотеки

Укажите тип содержимого и пути. Не добавляйте корень диска целиком: сервер будет сканировать лишнее и показывать мусор.

# веб-интерфейс → Dashboard → Libraries → Add Media Library

4. Включите аппаратное транскодирование

Проверьте наличие устройства рендеринга и права пользователя jellyfin. Без этого сервер будет транскодировать на CPU и может не справляться.

ls -l /dev/dri
id jellyfin
groups jellyfin

Рабочий конфиг

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

services:
  jellyfin:
    image: jellyfin/jellyfin:latest
    ports:
      - "127.0.0.1:8096:8096"
    volumes:
      - ./config:/config
      - ./cache:/cache
      - /srv/media:/media:ro
    restart: unless-stopped

Практические советы

Эти рекомендации проверены на повседневных задачах. Начните с тех, которые закрывают вашу текущую боль, а не со всего списка сразу.

Совет 1. Называйте файлы по схеме Name (Year) и указывайте сезон/эпизод — это р

Называйте файлы по схеме Name (Year) и указывайте сезон/эпизод — это резко улучшает распознавание.

Совет 2. Прямое воспроизведение лучше транскодирования: подбирайте клиенты и фо

Прямое воспроизведение лучше транскодирования: подбирайте клиенты и форматы.

Совет 3. Ограничьте транскодирование по CPU и проверяйте нагрузку.

Ограничьте транскодирование по CPU и проверяйте нагрузку.

Совет 4. Храните конфигурацию и базу в отдельном каталоге, чтобы пережить переу

Храните конфигурацию и базу в отдельном каталоге, чтобы пережить переустановку.

Профилактика

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

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

Итог

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