Docs/ Infraestructura/ Almacenamiento y volúmenes

Almacenamiento y volúmenes

Almacenamiento persistente para tus contenedores, con soporte para disco local, S3 y Cloudflare R2 como backends de almacenamiento.

¿Qué son los volúmenes?

Por defecto, los sistemas de archivos de los contenedores son efímeros -- cualquier dato escrito dentro de un contenedor se pierde cuando el contenedor se reinicia o se redespliega. Los volúmenes resuelven esto proporcionando almacenamiento persistente que sobrevive a los eventos del ciclo de vida del contenedor.

Los casos de uso comunes para volúmenes incluyen:

Directorios de datos de bases de datos (PostgreSQL, MySQL, MongoDB)
Archivos subidos por usuarios y medios
Registros de la aplicación que necesitan persistir
Configuración compartida entre contenedores
Directorios de caché que deben sobrevivir a los reinicios

Note

sh0 crea automáticamente volúmenes para servicios de bases de datos (PostgreSQL, MySQL, Redis, MongoDB). Solo necesitas crear volúmenes manualmente para almacenamiento personalizado de la aplicación.

Crear volúmenes persistentes

Puedes crear volúmenes a través del panel de control o la API.

Vía el panel de control:

Navega a la pestaña Configuración → Almacenamiento de tu aplicación.
Haz clic en Agregar volumen.
Ingresa un nombre de volumen (por ejemplo, uploads) y la ruta de montaje del contenedor.
Opcionalmente establece un límite de tamaño.
Haz clic en Crear.

Creating a new persistent volume in the dashboard

Vía la API:

Terminal

curl -X POST https://your-server:9000/api/apps/my-app/mounts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "uploads",
    "mount_path": "/app/uploads",
    "size_limit_mb": 5120
  }'

Montar volúmenes en contenedores

Cuando creas un volumen, especificas la ruta dentro del contenedor donde se montará. Los datos del volumen se almacenan en el sistema de archivos del host y se montan en el contenedor en la ruta especificada.

docker-compose.yml

services:
  web:
    image: my-app:latest
    volumes:
      - uploads:/app/uploads
      - logs:/var/log/app

volumes:
  uploads:
  logs:

Al desplegar vía Docker Compose, sh0 automáticamente crea y administra los volúmenes con nombre definidos en tu archivo compose.

Volume mount configuration showing container path mapping

Warning

Evita montar volúmenes en rutas que contengan código de la aplicación (por ejemplo, /app). Esto anulará tu código desplegado con lo que esté en el volumen. Monta volúmenes en subdirectorios como /app/data o /app/uploads en su lugar.

Rutas y permisos de volúmenes

sh0 almacena los datos de volúmenes en el host en:

Host Path

/var/lib/sh0/volumes/{stack_id}/{volume_name}

Los permisos se establecen para coincidir con el usuario del contenedor. Si tu aplicación se ejecuta como un usuario no root (que sh0 aplica por defecto), el directorio del volumen pertenece al UID/GID de ese usuario.

Tip

Si encuentras errores de permisos, verifica el UID de tu aplicación dentro del contenedor con id y asegúrate de que el directorio del volumen tenga la propiedad correspondiente. Puedes corregir permisos desde la terminal de sh0.

Proveedores de almacenamiento

Además de los volúmenes locales, sh0 admite proveedores de almacenamiento externos para respaldos y almacenamiento de objetos.

Disco local

El backend de almacenamiento predeterminado. Los volúmenes se almacenan directamente en el sistema de archivos del servidor. Esta es la opción más sencilla y ofrece el mejor rendimiento para la mayoría de las cargas de trabajo.

Amazon S3

Configura un bucket S3 para respaldos y almacenamiento de archivos grandes. Navega a Configuración → Proveedores de almacenamiento para agregar tus credenciales de S3.

Terminal

curl -X POST https://your-server:9000/api/storage-providers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backups",
    "type": "s3",
    "bucket": "my-backups",
    "region": "us-east-1",
    "access_key_id": "AKIA...",
    "secret_access_key": "..."
  }'

S3 storage provider configuration form

Cloudflare R2

Cloudflare R2 es un almacén de objetos compatible con S3 con cero cargos de transferencia de salida. sh0 admite R2 de forma nativa -- configúralo de la misma manera que S3, usando tu endpoint de R2:

Terminal

curl -X POST https://your-server:9000/api/storage-providers \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "r2-backups",
    "type": "s3",
    "bucket": "my-backups",
    "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
    "access_key_id": "...",
    "secret_access_key": "..."
  }'

Cloudflare R2 storage provider setup

Administrar almacenamiento

El panel de Almacenamiento en el panel de control muestra todos los volúmenes de un stack, sus tamaños y a qué contenedores están montados. Desde aquí puedes:

Explorar archivos: Usa el administrador de archivos integrado para ver el contenido del volumen.
Descargar archivos: Exportar archivos individuales o directorios completos.
Redimensionar: Aumentar el límite de tamaño de un volumen.
Eliminar: Remover un volumen y todos sus datos (requiere confirmación).
Respaldar: Activar un respaldo manual a un proveedor de almacenamiento configurado.

Storage management panel showing volumes and their usage

Danger

Eliminar un volumen destruye permanentemente todos los datos que contiene. Esta acción no se puede deshacer. Siempre crea un respaldo antes de eliminar un volumen.

Custom Domains

Scaling