Manejo de Archivos Grandes

Cuando despliegas un proyecto en Zeabur a través de Git, tu repositorio se descarga y se usa como contexto de construcción. Los archivos grandes en el repositorio — como binarios, conjuntos de datos, archivos multimedia o modelos de aprendizaje automático — pueden aumentar significativamente el tiempo de construcción o incluso causar que la construcción falle.

Esta guía explica por qué los archivos grandes causan problemas y cómo manejarlos.

Por qué los Archivos Grandes Causan Problemas

Límite de Tamaño del Contexto de Construcción

Al desplegar desde GitHub, Zeabur descarga tu repositorio como un archivo ZIP. Este archivo tiene un límite de tamaño de 1 GiB — si tu repositorio excede este límite, la construcción fallará. Incluso por debajo de este límite, los repositorios grandes resultarán en construcciones más lentas debido al mayor tiempo de descarga y extracción.

Git LFS No Soportado

Si tu repositorio usa Git LFS, el servidor de construcción solo recibirá los archivos de puntero LFS en lugar del contenido real de los archivos. Necesitarás mover estos archivos a una solución de almacenamiento externo.

Tamaño de la Imagen del Contenedor

Los archivos grandes incluidos en la imagen final del contenedor aumentarán el tiempo necesario para desplegar, escalar y reiniciar tu servicio. Mantener la imagen ligera asegura arranques en frío más rápidos y un uso más eficiente de los recursos.

Prácticas Recomendadas

Eliminar Archivos Grandes de tu Repositorio

Dado que Zeabur descarga el repositorio completo para la construcción, los archivos grandes no pueden excluirse mediante .dockerignore o mecanismos similares. Debes eliminar los archivos grandes del repositorio directamente.

Usa .gitignore para evitar que se hagan commit de archivos grandes:

# Conjuntos de datos y archivos multimedia grandes
*.csv
*.parquet
data/
assets/videos/

# Artefactos de construcción
dist/
*.log

# Modelos de aprendizaje automático
*.bin
*.h5
*.onnx

Usar Almacenamiento de Objetos Externo para Activos Grandes

Para activos estáticos grandes como imágenes, videos o modelos de aprendizaje automático, almacénalos en un servicio de almacenamiento de objetos externo (por ejemplo, AWS S3, Cloudflare R2 o cualquier servicio compatible con S3) y referéncialos por URL en tu aplicación.

Esto mantiene tu repositorio e imagen del contenedor pequeños mientras permite que tu aplicación acceda a los archivos que necesita en tiempo de ejecución.

Usar Volumes para Datos en Tiempo de Ejecución

Si tu aplicación genera o requiere archivos grandes en tiempo de ejecución — como archivos subidos por usuarios, archivos de caché o bases de datos — usa Volúmenes Persistentes en lugar de incluirlos en la imagen del contenedor.

Los archivos almacenados en volúmenes persisten entre despliegues y reinicios del servicio, y no afectan el tamaño del contexto de construcción.

Mantener tu Repositorio Ligero

Sigue estas mejores prácticas generales para mantener tu repositorio pequeño:

• No hagas commit de binarios — los archivos compilados, ejecutables y archivos comprimidos deben construirse en CI o descargarse en tiempo de ejecución.
• Usa .gitignore — excluye artefactos de construcción, dependencias (node_modules, venv) y archivos temporales.
• Divide repositorios grandes — si tu repositorio contiene muchos servicios independientes, considera dividirlos en repositorios separados y usar Rutas de Vigilancia o Directorio Raíz para gestionar los despliegues.