Actualizado: 2026-07-12

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. El diseño original de NFS (Network File System[1], NFSv2) era deliberadamente stateless; no fue hasta NFSv4 cuando el protocolo pasó a ser stateful, un cambio que arrastra buena parte de esa fragilidad de caché. 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: un clúster de Metadata Servers (MDS) reparte los metadatos y los clientes hablan directamente con RADOS, el object store distribuido de Ceph, para leer y escribir bloques, según la documentación oficial de CephFS[2]. 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. El propio repositorio de JuiceFS en GitHub[3] documenta un rendimiento hasta diez veces superior al de EFS o S3FS en pruebas secuenciales, y pasa las 8813 pruebas de compatibilidad POSIX de pjdfstest. 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. La documentación oficial de JuiceFS sobre motores de metadatos[4] cifra el coste de un motor relacional como PostgreSQL en unos 600 bytes por fichero, una cifra útil para dimensionar el disco de la base de datos antes de arrancar. 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, activada por defecto desde la versión 1.0.0 según la documentación de la papelera[5], ha salvado más de un borrado accidental; la limpieza corre cada hora por defecto, así que no esperes ver espacio liberado al instante. La papelera de JuiceFS resuelve un problema puntual, no sustituye un backup real: para eso sigo confiando en restic, apuntando también contra el bucket S3.

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:

  • 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.

  • 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.

  • 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 en http://localhost:9567/metrics según la documentación de monitorización[6], un endpoint local que conviene scrapear. Si aún no tienes claro cómo configurar las alertas sobre esas métricas sin acabar ignorándolas, ya escribí sobre cómo escribir alertas de Prometheus que se atiendan de verdad.

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.

Preguntas frecuentes

¿Puedo usar JuiceFS sin un object store compatible con S3?

No de forma práctica. JuiceFS necesita un backend de datos por bloques, y S3 (o un compatible: MinIO, Hetzner Object Storage, Backblaze B2) es la opción estándar. También admite otros backends, como el sistema de ficheros local o HDFS, pero pierdes la ventaja distribuida que justifica elegir JuiceFS en primer lugar.

¿Qué pasa si la base de datos de metadatos se cae?

El filesystem deja de responder hasta que la base de datos vuelve. Los datos del object store no se pierden, pero ningún cliente puede leer ni escribir mientras los metadatos no estén disponibles. Por eso la alta disponibilidad de PostgreSQL, con réplicas y failover, importa tanto como la del propio JuiceFS.

¿JuiceFS funciona bien con muchos ficheros pequeños?

Con matices. El coste por fichero en la base de metadatos ronda los 600 bytes, así que millones de ficheros pequeños presionan más la base de datos que el object store. Para cargas con decenas de millones de ficheros conviene dimensionar bien PostgreSQL desde el principio, no sobre la marcha.

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.

Este artículo también está disponible en inglés.

Fuentes:

  1. JuiceFS — documentación oficial: introducción[7]
  2. JuiceFS — bases de datos para metadatos (PostgreSQL, Redis, MySQL)[4]
  3. JuiceFS — papelera de reciclaje (trash)[5]
  4. JuiceFS — monitorización y métricas Prometheus[6]
  5. juicedata/juicefs — repositorio en GitHub[3]
  6. Ceph — documentación oficial de CephFS[2]
  7. Network File System — Wikipedia[1]
Visitas: 269

Fuentes

  1. Network File System
  2. documentación oficial de CephFS
  3. repositorio de JuiceFS en GitHub
  4. documentación oficial de JuiceFS sobre motores de metadatos
  5. documentación de la papelera
  6. documentación de monitorización
  7. JuiceFS — documentación oficial: introducción