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

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:
Ventana de terminal
```
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"