Cómo instalar JuiceFS como sistema de ficheros compartido

Actualizado: 2026-05-03

Después de convivir un tiempo con JuiceFS en un clúster de tres nodos, creo que merece la pena escribir el tutorial de instalación que me habría gustado encontrar al empezar. Hay buena documentación oficial, pero está fragmentada entre casos de uso muy distintos, y quien llega desde NFS o desde un bind mount clásico se pierde en la primera decisión importante: qué backend de metadatos elegir y cómo montar la cosa sin sorpresas.

Este recorrido asume un escenario concreto: tres servidores Linux modernos que necesitan ver los mismos ficheros, una base de datos PostgreSQL ya disponible, y almacenamiento compatible con S3 como destino final de los datos. Es el patrón más común en despliegues pequeños y medianos.

Puntos clave

• JuiceFS delega datos en un object store (S3, MinIO, Hetzner) y metadatos en una base de datos que ya operas (Redis, PostgreSQL, MySQL).
• Desde el cliente es un filesystem FUSE POSIX con cache local configurable — se monta y se usa como cualquier otro directorio.
• El bucket de object store debe ser exclusivo de JuiceFS: usa una estructura de claves interna que asume exclusividad.
• La opción --free-space-ratio 0.3 es importante y se olvida a menudo — sin ella, un pico puede llenar el disco de caché.
• Para casos simples en una sola red, NFS sigue siendo válido. JuiceFS compensa cuando se quiere replicación o sobrevivir a fallos de nodo.

Por qué JuiceFS y no otra cosa

La alternativa clásica es NFS. Funciona, es conocido y está soportado por cualquier kernel Linux, pero viene con una mochila de problemas bien documentados: semántica de caché frágil, dificultad para escalar lecturas, y una superficie de red que los administradores suelen tener que proteger con cortafuegos específicos. Cuando alguno de los nodos se cae, la experiencia desde los clientes puede ir desde el bloqueo prolongado hasta el ruido en logs difícil de diagnosticar.

CephFS resuelve el problema a lo grande, pero instalar Ceph para compartir unos cuantos terabytes entre tres máquinas es matar mosquitos a cañonazos. La operación de un clúster Ceph en producción tiene una curva de aprendizaje notable y exige dedicación.

JuiceFS ocupa un hueco intermedio. Delega los datos en un object store (S3, Hetzner Object Storage, MinIO, Backblaze B2, lo que tengas) y los metadatos en una base de datos que ya sabes operar. Desde el lado del cliente es un sistema FUSE que se comporta como un filesystem POSIX normal, con cache local configurable. La parte elegante es que toda la complejidad distribuida queda absorbida por componentes que ya conoces y sabes monitorizar. Este mismo principio de reutilización de infraestructura existente es el que analizamos en Vector para observabilidad.

Preparación del backend

Antes de tocar JuiceFS conviene tener resueltas dos piezas.

El object store: necesitas un endpoint, unas credenciales y nombre de bucket. Si usas AWS S3, MinIO autohospedado o cualquier servicio compatible, la configuración es equivalente. Lo único importante es que el bucket no se comparta con otros sistemas: JuiceFS usa una estructura de claves interna que asume exclusividad.

La base de datos de metadatos: recomiendo PostgreSQL si ya tienes una instancia disponible. JuiceFS crea sus tablas en un esquema propio, la carga es moderada, y la operación (backups, monitorización, alta disponibilidad) se beneficia de toda la infraestructura que ya tengas para PG. Redis es más rápido en operaciones muy intensivas, pero para cargas típicas la diferencia no justifica añadir un componente nuevo.

Crea una base de datos dedicada y un usuario con permisos sobre ella.

Formateo inicial

Con el backend preparado, el primer paso es formatear el volumen. Esto es equivalente a un mkfs clásico, pero aplicado a la combinación de object store y base de metadatos. Solo se hace una vez desde uno de los nodos:

juicefs format 
  --storage s3 
  --bucket https://endpoint/bucket 
  --access-key <KEY> 
  --secret-key <SECRET> 
  --compress lz4 
  postgres://usuario:password@host:5432/juicefs mi-volumen

Dos opciones merecen atención:

• La compresión lz4 es un buen valor por defecto: añade un coste de CPU pequeño y reduce el volumen enviado al object store entre un 20% y un 40% dependiendo del contenido. Si vas a guardar mucho contenido ya comprimido (vídeo, imágenes, archivos), puedes desactivarla.
• El nombre del volumen (mi-volumen en el ejemplo) es metadato interno de JuiceFS y aparece en métricas y logs.

No se recomienda formatear con --trash-days 0 en producción. La papelera interna de JuiceFS ha salvado más de un borrado accidental.

Montaje en cada nodo

Una vez formateado, cada nodo monta el filesystem con un comando único:

juicefs mount 
  --cache-dir /var/juicefs-cache 
  --cache-size 20480 
  --free-space-ratio 0.3 
  postgres://usuario:password@host:5432/juicefs 
  /mnt/jfs

Las opciones de caché son donde más variación vas a tener entre nodos:

• El tamaño se expresa en MiB; 20480 equivale a 20 GiB. Si un nodo tiene disco SSD rápido y espacio, vale la pena subir este valor.
• --free-space-ratio 0.3 es importante y se olvida a menudo. Le dice a JuiceFS que, si el disco donde vive la caché baja del 30% libre, empiece a expulsar entradas. Sin esto, un pico de actividad puede llenar el disco y causar problemas al sistema.

Para hacer el montaje persistente entre reinicios, lo limpio es crear una unidad systemd que ejecute el mismo comando con ExecStart. Esto da más control sobre dependencias (esperar a la red, a PostgreSQL, etc.) que el enfoque fstab.

Verificación y primeras pruebas

Antes de considerarlo operativo, hay tres pruebas que conviene hacer:

1. Crear un fichero en un nodo y leerlo desde otro: si la configuración es correcta, debería aparecer en segundos. Si tarda mucho más, probablemente haya un problema de red con el object store o los metadatos.
2. Escribir un fichero grande (varios GB) desde un nodo mientras se monitoriza el uso de CPU y red. Para cargas grandes, JuiceFS usa múltiples conexiones paralelas al object store, y la velocidad debería acercarse al ancho de banda disponible.
3. Apagar el nodo que escribió el fichero y comprobar que los otros siguen leyéndolo sin problema. Este es el test que separa un sistema de ficheros compartido real de un espejismo: los datos viven en el object store, no en el disco local del nodo escritor.

Mantenimiento y monitorización

Una vez en marcha, lo que hay que vigilar no es tanto el filesystem en sí como sus dependencias:

• La base de datos de metadatos necesita monitorización normal de PostgreSQL: duración de transacciones, conexiones activas, tamaño de tablas.
• El object store necesita vigilancia de coste y de tasa de errores.
• JuiceFS expone métricas Prometheus por un endpoint HTTP local que conviene scrapear.

La operación más delicada que vas a necesitar tarde o temprano es la limpieza de bloques huérfanos (juicefs gc). JuiceFS es conservador por diseño: cuando borras un fichero, marca sus bloques como liberables pero no los borra del object store hasta que el recolector los limpia. Ejecutar gc semanalmente con --compact es una buena higiene, especialmente si tu carga implica mucho borrado.

Si alguna vez tienes que migrar a otro object store, JuiceFS tiene un comando sync que hace la copia en paralelo sin parar el servicio. Con NFS, esa operación sería una obra mayor.

Conclusión

Lo que hace que JuiceFS sea una buena opción no es ninguna prestación particular, sino la alineación con componentes que ya operas. Todos los equipos que administran Linux de verdad saben hacer backup de Postgres, monitorizar un bucket S3 y leer métricas Prometheus. JuiceFS convierte eso en un filesystem compartido, y lo hace sin exigir aprender un nuevo plano operativo.

La alternativa honesta sigue siendo NFS para casos muy sencillos donde todos los clientes están en la misma red y el riesgo de fallo no es crítico. Para cualquier caso un poco más serio, o donde se quiera replicación entre regiones sin reconfigurar el cliente, merece la pena probar esta ruta.