Cómo recuperar Jellyfin sin volver a crear usuarios y biblioteca

Tus películas siguen en el disco, pero Jellyfin vuelve a pedirte que crees un administrador. Eso puede ocurrir si arrancas con una carpeta de configuración vacía. Los archivos de vídeo y los datos del servidor son dos cosas que hay que conservar por separado.

Esta guía parte de la imagen oficial de Jellyfin en Docker sobre Linux, con ./config montado en /config y las rutas de datos predeterminadas. Vamos a copiar ese directorio con el servidor detenido y a probar la restauración en otra carpeta. Antes de actualizar, interesa saber si puedes volver a entrar con tus usuarios y conservar su biblioteca.

Si tu problema es que el servidor mantiene usuarios y carátulas, pero no encuentra las películas, empieza por rutas, montajes y permisos. Restaurar una base de datos no monta un disco ausente.

Si vienes a cambiar de versión y ya tienes una copia ensayada, continúa con actualizar Jellyfin y preparar la vuelta atrás.

Qué necesitas guardar

• Configuración y datos de Jellyfin: ./config se monta en /config. Copia el directorio completo con Jellyfin detenido.
• Películas, series y música: en este ejemplo una carpeta del host se monta en /media. Respáldalas aparte; copiar /config no las incluye.
• Definición del despliegue: guarda de forma privada compose.yaml o docker-compose.yml, .env y los archivos que referencian. Anota también versión y UID/GID.
• Caché: ./cache se monta en /cache. En nuestro ensayo se creó vacía; debe ser escribible por Jellyfin.

Si has definido JELLYFIN_DATA_DIR, JELLYFIN_CONFIG_DIR, metadatos fuera del directorio habitual o una base de datos externa, identifica también esas rutas y su copia coherente. No apliques el ejemplo a ciegas. La distribución LinuxServer.io tiene otra organización; esta prueba no la cubre.

Jellyfin 10.11 y posteriores incluyen además una copia nativa en Panel → Copias de seguridad. Puede hacerse con el servidor encendido; el proyecto recomienda poca actividad y ningún escaneo en curso. Guarda la base de datos y ofrece opciones para metadatos, subtítulos y trickplay. Comprueba al menos 5 GB libres, pero puede necesitar más. La documentación oficial explica esa vía y su restauración, que reinicia el servidor. Los comandos de abajo son para una copia manual, no para extraer su ZIP nativo.

Antes de parar: confirma montaje, versión y permisos

Desde el directorio de tu proyecto Compose, con Jellyfin todavía en marcha:

jf_container=$(docker compose ps -q jellyfin)
test -n "$jf_container" || { echo "No hay servicio jellyfin en marcha"; exit 1; }
docker inspect --format '{{json .Mounts}}' "$jf_container"
docker inspect --format '{{.Config.Image}} | usuario={{.Config.User}}' "$jf_container"
docker image inspect "$(docker inspect --format '{{.Image}}' "$jf_container")" \
  --format '{{json .RepoDigests}} | {{.Architecture}}'

En Mounts, busca Destination: /config y su Source. Debe corresponder a la carpeta que vas a copiar. Si es un volumen nombrado, un enlace simbólico o está en otro lugar, usa su origen real: los comandos siguientes asumen una carpeta normal ./config. Comprueba también la ruta interna de los medios, por ejemplo /media.

Anota la versión que muestra el panel, la referencia jellyfin/jellyfin@sha256:…, la arquitectura y el usuario efectivo del contenedor. Un ID local de imagen y un digest de repositorio no son lo mismo. Si no hay RepoDigests, conserva la imagen local con docker image save o consigue una referencia oficial comprobada antes del ensayo.

No restaures primero con latest para fijar la versión después. Jellyfin aplica migraciones al arrancar y no admite deshacerlas sobre ese directorio. Para volver a una versión anterior hacen falta su copia previa y la versión correspondiente.

Copia manual con una parada limpia

Elige un momento sin reproducciones. Sustituye la ruta de destino por la tuya: debe quedar fuera de config, tener espacio suficiente y no estar dentro de la carpeta de películas. Estos comandos se ejecutan desde el proyecto con ./config ya comprobado.

umask 077
jf_project=$(pwd -P)
jf_backup="/ruta/de/tus/copias/jellyfin-$(date -u +%Y%m%d-%H%M%S)"
mkdir -p "$jf_backup" || exit 1
test -d "$jf_project/config" && test ! -L "$jf_project/config" || exit 1

Guarda también el Compose y su .env, si existe. La salida de docker compose config puede contener secretos resueltos: no la publiques ni la pegues en un foro. Una copia de config también puede contener credenciales, sesiones y rutas privadas.

docker compose stop --timeout 60 jellyfin || exit 1
docker inspect --format '{{.State.Running}} {{.State.ExitCode}} {{.State.OOMKilled}}' \
  "$jf_container"
docker logs --tail 30 "$jf_container"

Debe estar detenido. En nuestro ensayo vimos false 0 false y mensajes de cierre de Jellyfin. Un código 137, un OOM o un cierre forzado requieren investigar antes de considerar limpia la copia; false por sí solo no basta. Docker puede matar el proceso si agota el plazo de parada.

sudo tar --acls --xattrs --numeric-owner -czpf "$jf_backup/config.tar.gz" \
  -C "$jf_project" config || exit 1
sudo chown "$(id -u):$(id -g)" "$jf_backup/config.tar.gz" || exit 1
chmod 600 "$jf_backup/config.tar.gz" || exit 1
tar -tzf "$jf_backup/config.tar.gz" > "$jf_backup/contenido.txt" || exit 1
(cd "$jf_backup" && sha256sum config.tar.gz > config.tar.gz.sha256) || exit 1
docker compose start jellyfin

Ejecuta el bloque paso a paso y comprueba que cada comando termina correctamente. Si falla la copia, no actualices Jellyfin contando con ese archivo. Puedes volver a arrancar el servicio original con docker compose start jellyfin mientras resuelves espacio, permisos o destino.

El checksum detecta cambios en el archivo. No prueba que el servidor pueda recuperarse. Lleva después la copia a un destino separado, según tu plan de copias 3-2-1; otra carpeta del mismo disco no protege de perder ese disco.

Prueba la restauración sin pisar el servidor actual

Primero comprueba el checksum. Usa una carpeta nueva: no mezcles una copia antigua con archivos de una instalación que ya ha arrancado.

(cd "$jf_backup" && sha256sum -c config.tar.gz.sha256) || exit 1
jf_restore="$jf_project/ensayo-jellyfin"
mkdir "$jf_restore" || exit 1
sudo tar --acls --xattrs --numeric-owner -xzpf "$jf_backup/config.tar.gz" \
  -C "$jf_restore" || exit 1

Si mkdir dice que la carpeta ya existe, elige otra y para antes de extraer. Trabaja sólo con tu propio archivo de copia. El original debe quedarse intacto; el servidor de prueba usará la copia extraída.

Prepara una caché escribible. En el siguiente ejemplo el usuario es 1000:1000; sustitúyelo por el UID/GID que anotaste y conserva los propietarios del directorio restaurado. No uses chmod -R 777 para hacer desaparecer un error.

sudo install -d -m 0750 -o 1000 -g 1000 "$jf_restore/cache" || exit 1
jf_image='jellyfin/jellyfin@sha256:PEGA_AQUI_EL_DIGEST_GUARDADO'
jf_media='/ruta/real/de/tus/peliculas'

docker run -d --name jellyfin-ensayo \
  --user 1000:1000 \
  --publish 127.0.0.1:18096:8096 \
  --mount "type=bind,src=$jf_restore/config,dst=/config" \
  --mount "type=bind,src=$jf_restore/cache,dst=/cache" \
  --mount "type=bind,src=$jf_media,dst=/media,readonly" \
  "$jf_image"

Sustituye el digest y las rutas antes de ejecutar. Si la biblioteca usaba /peliculas dentro del contenedor, conserva dst=/peliculas en vez de /media. El origen del host puede cambiar; la ruta que guarda Jellyfin debe seguir existiendo. --mount falla cuando falta el origen, en lugar de crearte silenciosamente una carpeta vacía.

Abre http://127.0.0.1:18096 en el propio servidor. Si trabajas desde otro ordenador, abre este túnel desde ese ordenador y mantén la terminal abierta:

ssh -N -L 18096:127.0.0.1:18096 usuario@servidor

Sustituye usuario@servidor por tu acceso SSH y abre entonces http://127.0.0.1:18096 en ese ordenador. El bind a localhost impide entrar directamente por la IP de la LAN. No cambies a red host ni publiques el puerto UDP de descubrimiento para esta prueba. La copia conserva la identidad del servidor: mantén el clon fuera de los clientes habituales.

Qué comprobar antes de confiar en la copia

• Entra con el administrador y con un usuario normal. Si aparece el asistente de instalación, comprueba el montaje antes de crear otra cuenta.
• Revisa el nombre de la biblioteca y su ruta; abre un elemento que ya conocías.
• Comprueba un favorito, un elemento visto y otro con una posición de reanudación conocida. Que aparezcan los títulos no acredita todos esos datos.
• Reproduce el mismo archivo desde el cliente de prueba. Si necesitas GPU, añade su configuración real después de verificar los datos: este contenedor de ensayo no recibe dispositivos gráficos.
• Comprueba que el respaldo y la instalación original no se han utilizado como directorio activo.

Cuando termines, detén únicamente el ensayo:

docker stop --timeout 60 jellyfin-ensayo

Para una recuperación real, detén el servicio afectado, conserva aparte su directorio actual y copia el respaldo al destino correcto. Fija la versión adecuada antes del primer arranque. No borres el directorio anterior hasta haber comprobado la recuperación. Si el archivo existe en el host pero no dentro de Jellyfin, vuelve al diagnóstico de biblioteca vacía.

Actualizar Jellyfin con una vuelta atrás preparada

Si la copia ya se ha restaurado bien, puedes preparar el cambio de versión. El punto delicado es el primer arranque: la nueva imagen puede migrar la base de datos. Volver al tag anterior no devuelve la base de datos a su estado anterior. Para retroceder necesitas la imagen anterior y una copia hecha antes de la migración.

Este recorrido usa el servicio jellyfin del mismo proyecto Compose y la imagen oficial. Si lo gestionas con Portainer, un NAS o LinuxServer.io, conserva su método de despliegue; no crees al lado un segundo proyecto con estos comandos.

1. Elige la versión antes de descargarla

Lee las notas oficiales de la versión de destino y comprueba requisitos de migración, espacio libre y compatibilidad de plugins. Una etiqueta de ejemplo no es una recomendación de versión actual. Guarda el Compose anterior, su .env y el digest de la imagen que está usando el contenedor, tal como se explica arriba.

Comprueba primero el nombre del servicio: los comandos usan jellyfin; sustitúyelo si el tuyo tiene otro nombre. Conserva también el nombre de proyecto (-p o COMPOSE_PROJECT_NAME) y la selección de archivos Compose.

Cambia sólo la referencia image de Jellyfin por la versión o digest oficial elegido. Si procede de una variable en .env, cambia esa variable. No cambies a la vez rutas, usuario, puertos ni aceleración: dificultaría saber qué ha fallado. Desde el mismo directorio y con los mismos archivos Compose que usas habitualmente:

docker compose config --quiet
docker compose config --images

Comprueba que la salida incluye la imagen de destino esperada. Puede listar también las de otros servicios. Si sigue mostrando latest o una versión distinta, revisa variables y archivos de configuración adicionales antes de continuar. No compartas la salida completa de docker compose config: puede resolver secretos.

docker compose pull jellyfin

pull descarga la imagen y no arranca ni sustituye el contenedor actual. Hazlo antes de la parada para no añadir la descarga al corte de servicio. Si falla, resuélvelo con el servidor anterior todavía en marcha; no encadenes a ciegas el siguiente paso.

2. Haz la copia final y deja el servicio detenido

Cuando nadie esté reproduciendo, repite el apartado Copia manual con una parada limpia, con un destino nuevo. Si has cambiado de terminal, vuelve a definir y comprobar jf_project y jf_backup, y obtén de nuevo jf_container con el bloque inicial; esas variables no se conservan entre sesiones. Conserva también la configuración de despliegue anterior y la referencia de imagen anterior: el Compose que acabas de editar ya apunta al destino nuevo.

En esta ocasión, no ejecutes el último docker compose start jellyfin de aquel bloque. Verifica parada limpia, archivo legible y checksum; deja Jellyfin detenido entre la copia final y la recreación. Si esa comprobación falla, no actualices. docker compose start jellyfin vuelve a arrancar el contenedor anterior existente, sin aplicar la nueva imagen del Compose, mientras resuelves el problema.

Con la copia final comprobada y la referencia de destino confirmada:

docker compose up --no-deps --pull never -d jellyfin
docker compose ps jellyfin
docker compose logs --tail 80 jellyfin

Ejecuta cada línea sólo si la anterior terminó bien. up aplica el cambio al servicio; --no-deps evita arrancar sus dependencias y --pull never usa la imagen descargada en el paso anterior. No hace falta bajar todo el proyecto ni borrar volúmenes. Si antes usabas -f para seleccionar archivos Compose, conserva esa misma selección en todos los comandos.

3. Comprueba la biblioteca antes de darlo por terminado

Espera a que el registro confirme el arranque y termine cualquier migración que corresponda. Una biblioteca grande puede tardar; no reinicies repetidamente por ver la interfaz aún inaccesible. Si aparece un error o falta espacio, conserva el mensaje concreto para decidir la recuperación.

Comprueba la versión en el panel, el acceso de administrador y usuario normal, bibliotecas, favoritos y una posición de reanudación. Reproduce un archivo conocido en el cliente que utilizas, con su audio y subtítulos habituales. Revisa también los plugins que necesites. Un contenedor «Up» o una portada con carátulas no demuestra que ese recorrido funcione.

Si necesitas volver a la versión anterior

Detén únicamente Jellyfin. Conserva aparte la configuración que haya modificado la nueva versión y sus registros. Restaura la copia previa en una carpeta vacía, con propietarios y rutas comprobados; no la extraigas encima de la base migrada. Recupera el Compose y la referencia de imagen anteriores antes del primer arranque. Si la referencia era latest, sustitúyela por el digest anterior que guardaste.

Verifica primero otra copia extraída en el ensayo aislado de esta guía; no conviertas ese clon en el servidor habitual. Para la recuperación real, deja los datos restaurados en la ruta que tu Compose monta en /config, con Jellyfin detenido. Con el Compose anterior y su imagen disponibles localmente, ejecuta docker compose up --no-deps --pull never -d jellyfin: aplica la configuración anterior. No uses start para este paso, porque podría arrancar el contenedor de la versión nueva aunque hayas editado el Compose. Al arrancar la recuperación real, comprueba de nuevo usuarios, biblioteca y reproducción. Los cambios posteriores a la copia —por ejemplo, nuevas marcas de visto— no estarán en ella. Conserva ambas carpetas hasta confirmar el resultado; no uses una versión antigua para abrir la base ya migrada.

Alcance comprobado el 9 de noviembre: ensayamos Compose con Jellyfin 10.11.11, una copia de laboratorio y dos clips sintéticos. Descargamos la referencia fijada, recreamos el contenedor y recuperamos la configuración anterior. Se conservaron los dos accesos, favoritos, visto, reanudación de diez segundos y bytes del archivo servido. Se usó la misma versión en los tres pasos: no es una prueba de migración entre versiones, de plugins ni de reproducción audiovisual en una TV. La incompatibilidad de un downgrade sobre datos migrados procede de la documentación oficial de Jellyfin.

Lo que recuperó nuestra prueba

El 2 de noviembre de 2026 creamos una instancia aislada de Jellyfin 10.11.11 con dos usuarios y dos clips sintéticos. Tras una parada limpia, archivamos /config, restauramos sus 23 archivos en otro directorio y arrancamos la misma imagen con caché nueva y medios en solo lectura.

Ambos usuarios pudieron autenticarse con sus contraseñas y conservaron sus IDs. El favorito y el estado de visto persistieron; una segunda entrada conservó una posición de diez segundos que habíamos fijado mediante la API. En el cliente web, «Continuar» inició el clip de un minuto desde esa marca y el tiempo de reproducción avanzó sin error del reproductor. Es una comprobación técnica; no hicimos una evaluación de sonido. El archivo servido desde el clon mantuvo el SHA-256 del original. La copia comprimida y la configuración de origen siguieron intactas.

Es una restauración en el mismo host, con una biblioteca pequeña. No ensayamos pérdida del servidor, cambio de arquitectura, plugins, rutas personalizadas ni una TV física. La comprobación de bytes y datos no sustituye la reproducción en tu cliente. Tampoco probamos aquí la restauración nativa del ZIP de Jellyfin.

Fuentes y siguiente paso

• Jellyfin: copia y restauración: copia nativa, parada manual y compatibilidad de versiones.

• Jellyfin en contenedores: montajes y usuario de la imagen oficial.

• Docker: parada de contenedores y bind mounts: señal, timeout y comportamiento de rutas inexistentes.

• Docker Compose: pull y up: descarga, recreación y selección del servicio.

Fuentes de copia consultadas el 2 de noviembre y contrastadas para la ampliación de actualización el 9 de noviembre de 2026. Si todavía estás montando el servidor, empieza por instalar Jellyfin en Docker. Con una instalación existente, el siguiente paso es ensayar su recuperación con un respaldo privado antes de la próxima actualización.