Almacenamiento de ficheros (On-Premise)

Solo On-Premise

La configuración de almacenamiento de ficheros aplica exclusivamente a instalaciones On-Premise de Floogos. En la versión cloud (SaaS), el almacenamiento es gestionado internamente y no requiere ninguna configuración.

---

¿Qué es el almacenamiento de ficheros?

Varios nodos generan archivos durante la ejecución de workflows — reportes Excel, PDFs, exportaciones JSON, archivos ZIP — y los exponen mediante una URL de descarga que los nodos siguientes o los usuarios finales pueden utilizar.

Por defecto esos archivos se escriben en una carpeta local (./temporal) del servidor del engine. Esto funciona correctamente para instalaciones de instancia única, pero falla en entornos de alta disponibilidad con múltiples instancias: el archivo generado en la instancia A no existe en la instancia B.

Floogos soporta tres backends de almacenamiento para resolver esto:

Backend	Cuándo usarlo
local	Instancia única. Sin configuración extra. Por defecto.
nfs	Múltiples instancias en la misma red. Requiere un montaje NFS en cada servidor.
bucket	Multi-instancia o multi-región. Sin red compartida. Compatible con Linode Object Storage, AWS S3, MinIO, Cloudflare R2 y cualquier proveedor S3-compatible.

---

Nodos que usan el almacenamiento de ficheros

Nodo	Salida
Save to Excel	Hoja de cálculo .xlsx
Base64 to File	Cualquier archivo decodificado desde base64
Schema to Excel	.xlsx exportado desde schemas de BD
Save to JSON	Exportación de datos .json
Format Excel from Summary	Resumen de batch .csv
Hub Fiscal Export PDF	Tickets .pdf / .html / .zip

Todos estos nodos usan automáticamente el backend activo. No es necesario modificar la configuración del workflow.

---

Estructura de archivos

La misma organización de carpetas se aplica en los tres backends:

cli_101/
  reporte-1750000000000.xlsx
  factura-1750000001234.pdf
cli_202/
  exportacion-1750000005678.zip

En modo bucket, cli_101/ es un prefijo de clave de objeto, no una carpeta real.

---

Backend: local (por defecto)

Sin configuración adicional.

# Nada que configurar — comportamiento por defecto
# Archivos en ./temporal/cli_{id}/

---

Backend: nfs

Paso 1 — Montar el NFS en cada instancia del engine:

sudo apt-get install -y nfs-common
sudo mkdir -p /var/www/nfs
sudo chown -R nodeuser:nodeuser /var/www/nfs

# Montar (reemplazar con la IP del servidor NFS y la ruta del export)
sudo mount -t nfs 10.0.0.5:/exports/floogos /var/www/nfs

# Montaje permanente — agregar a /etc/fstab
10.0.0.5:/exports/floogos  /var/www/nfs  nfs  defaults,_netdev  0  0

Paso 2 — Variables de entorno:

STORAGE_TYPE=nfs
STORAGE_PATH=/var/www/nfs

# Opcional — si nginx sirve los archivos directamente desde el NFS
# Sin esto, las URLs de descarga usan ENGINE_HOST/download/...
STORAGE_URL=https://static.tu-empresa.com

Configuración nginx para servir archivos del NFS directamente (opcional):

location /files/ {
    alias /var/www/nfs/;
    add_header Content-Disposition "attachment";
    location ~ ^/files/cli_[0-9]+/ { allow all; }
    deny all;
}

Con ese bloque nginx: STORAGE_URL=https://tu-empresa.com/files

---

Backend: bucket (S3-compatible)

Proveedores soportados: Linode Object Storage, AWS S3, MinIO, Cloudflare R2 y cualquier API S3-compatible.

STORAGE_TYPE=bucket

# Endpoint del proveedor S3-compatible (omitir para AWS S3 estándar)
STORAGE_BUCKET_ENDPOINT=https://us-east-1.linodeobjects.com

STORAGE_BUCKET_REGION=us-east-1
STORAGE_BUCKET_NAME=floogos-files
STORAGE_BUCKET_KEY=tu_access_key_id
STORAGE_BUCKET_SECRET=tu_secret_access_key

# Opcional — URL pública base (CDN, dominio personalizado, etc.)
# Si se omite, el engine construye la URL desde ENDPOINT + BUCKET_NAME
STORAGE_URL=https://floogos-files.us-east-1.linodeobjects.com

El bucket debe ser de lectura pública para que los usuarios puedan descargar los archivos directamente. Si se necesita acceso privado, generar URLs pre-firmadas usando el nodo AWS S3 después del nodo generador de archivos.

Linode Object Storage — ejemplo completo

STORAGE_TYPE=bucket
STORAGE_BUCKET_ENDPOINT=https://us-east-1.linodeobjects.com
STORAGE_BUCKET_REGION=us-east-1
STORAGE_BUCKET_NAME=mi-empresa-floogos
STORAGE_BUCKET_KEY=LINODE_ACCESS_KEY
STORAGE_BUCKET_SECRET=LINODE_SECRET_KEY
STORAGE_URL=https://mi-empresa-floogos.us-east-1.linodeobjects.com

AWS S3 — ejemplo completo

STORAGE_TYPE=bucket
STORAGE_BUCKET_REGION=eu-west-1
STORAGE_BUCKET_NAME=mi-empresa-floogos
STORAGE_BUCKET_KEY=AKIAIOSFODNN7EXAMPLE
STORAGE_BUCKET_SECRET=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
# STORAGE_BUCKET_ENDPOINT no es necesario para AWS S3 estándar
STORAGE_URL=https://mi-empresa-floogos.s3.eu-west-1.amazonaws.com

MinIO — ejemplo completo

STORAGE_TYPE=bucket
STORAGE_BUCKET_ENDPOINT=https://minio.tu-empresa.com
STORAGE_BUCKET_REGION=us-east-1
STORAGE_BUCKET_NAME=floogos
STORAGE_BUCKET_KEY=minioadmin
STORAGE_BUCKET_SECRET=minioadmin
STORAGE_URL=https://minio.tu-empresa.com/floogos

---

Solo en instalaciones on-premise

Las variables de entorno se configuran en el servidor donde corre Floogos, así que aplican a las instalaciones on-premise. En Floogos Cloud no tenés acceso a ellas: esos valores los gestiona el equipo de Floogos. Si necesitás cambiar alguno para tu cuenta, escribinos a soporte.

Referencia de variables de entorno

Variable	Backend	Obligatoria	Ejemplo
STORAGE_TYPE	todos	No (default: local)	nfs | bucket
STORAGE_PATH	nfs	Sí	/var/www/nfs
STORAGE_URL	nfs, bucket	No	https://static.tu-empresa.com
STORAGE_BUCKET_ENDPOINT	bucket	No*	https://us-east-1.linodeobjects.com
STORAGE_BUCKET_REGION	bucket	Sí	us-east-1
STORAGE_BUCKET_NAME	bucket	Sí	floogos-files
STORAGE_BUCKET_KEY	bucket	Sí	access key ID
STORAGE_BUCKET_SECRET	bucket	Sí	secret access key

*STORAGE_BUCKET_ENDPOINT es obligatorio para Linode, MinIO y Cloudflare R2. Para AWS S3 estándar se puede omitir.

---

Aplicar la configuración

Reiniciar el engine después de cambiar las variables de entorno:

pm2 restart all
# o
systemctl restart floogos-engine

Al arrancar el engine muestra en consola el backend activo:

# Local
📁 [Storage] backend=local basePath=/srv/floogos/temporal

# NFS
📁 [Storage] backend=nfs basePath=/var/www/nfs

# Bucket
📁 [Storage] backend=bucket bucket=floogos-files

Si aparece backend=local cuando se esperaba otro backend, las variables de entorno no se cargaron correctamente.

---

Limpieza automática de archivos

El engine elimina automáticamente los archivos antiguos cada día a las 02:00 UTC.

Backend	TTL por defecto
local	72 horas (3 días)
nfs	168 horas (7 días)
bucket	168 horas (7 días) — usa ListObjectsV2 + DeleteObject, sin coste de egress

Para archivos que necesiten almacenamiento permanente, usar el nodo AWS S3 o el nodo Google Drive tras el nodo generador de archivos.

---

Solución de problemas

Las URLs de descarga devuelven 404

• NFS: verificar que el montaje está activo (df -h | grep nfs) y que nginx apunta a la misma ruta
• Bucket: verificar que el bucket es público y que STORAGE_URL coincide con el endpoint del proveedor

Los archivos no se crean

• NFS: probar permisos de escritura: sudo -u nodeuser touch /var/www/nfs/test.txt
• Bucket: verificar que las keys tienen permiso s3:PutObject; probar con AWS CLI:

  aws s3 cp test.txt s3://floogos-files/ --endpoint-url https://us-east-1.linodeobjects.com

En alta disponibilidad, una instancia no ve los archivos de otra

• NFS: confirmar que el NFS está montado en todas las instancias
• Bucket: esto no debería ocurrir con bucket — todas las instancias leen del mismo endpoint S3

El cleanup no elimina objetos del bucket

• Verificar que las keys tienen permisos s3:ListBucket y s3:DeleteObject
• Revisar los logs del engine a las 02:00 UTC: pm2 logs | grep "Storage cleanup"