backend/docs/commands/MEDIA_CLEANUP_GUIDE.md

Comando de Limpieza de Archivos Media

Este documento explica cómo utilizar los comandos de limpieza de archivos media huérfanos en el proyecto Django.

¿Qué son los archivos huérfanos?

Los archivos huérfanos son archivos que existen físicamente en el directorio /media/ pero que no están referenciados en ningún campo de archivo (FileField o ImageField) de la base de datos. Esto puede ocurrir por:

• Eliminación de registros sin eliminar sus archivos asociados
• Errores en procesos de carga de archivos
• Archivos temporales que nunca se limpiaron
• Migraciones de datos incorrectas

Comandos Disponibles

1. cleanup_media (Comando Original)

python manage.py cleanup_media [opciones]

2. cleanup_media_fast (Comando Optimizado)

python manage.py cleanup_media_fast [opciones]

Opciones Disponibles

Opciones Comunes (ambos comandos):

• --dry-run: Muestra qué archivos se eliminarían sin eliminarlos realmente
• --verbose: Muestra información detallada del proceso
• --help: Muestra ayuda del comando

Opciones del cleanup_media:

• --batch-size N: Tamaño del lote para procesar archivos (default: 10000)

Opciones del cleanup_media_fast:

• --limit N: Limitar el número de archivos huérfanos a procesar
• --sample-size N: Tamaño de muestra para análisis rápido (default: 10000)
• --quick-scan: Hacer un escaneo rápido con muestra limitada

Uso Recomendado

1. Análisis Inicial (Siempre hacer primero)

# Escaneo rápido para obtener una estimación
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan --dry-run --verbose"

# O escaneo completo para números exactos (puede tomar tiempo)
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --dry-run --verbose"

2. Limpieza por Lotes (Recomendado para grandes volúmenes)

# Limpiar muestra de 10,000 archivos
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan --verbose"

# Limpiar hasta 5,000 archivos específicos
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --limit 5000 --verbose"

3. Limpieza Completa

# Eliminar todos los archivos huérfanos (CUIDADO: puede tomar mucho tiempo)
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --verbose"

Ejemplos de Salida

Dry Run (Modo Prueba):

Iniciando análisis en: /app/media
Modo escaneo rápido - muestra de 10000 archivos
Obteniendo muestra de archivos...
Muestra obtenida: 10000 archivos
Encontrados 5 modelos con campos de archivo
Procesando Document...
  Document: 2059405 registros procesados
Archivos huérfanos encontrados: 2763 (72.57 MB) - Tiempo: 7.81s

--- MODO PRUEBA: Los siguientes archivos se eliminarían ---
  - documents/vu_AC_0101_230_1703_3004804_4.pdf
  - documents/vu_AC_0101_300_3172_4001419_2.pdf
  ... y 2743 archivos más

Eliminación Real:

¿Estás seguro de que quieres eliminar 2763 archivos? (s/N): s
Progreso: 36.2% (1000 eliminados)
Progreso: 72.4% (2000 eliminados)
Eliminados 2763 archivos huérfanos (51.32 MB)

Casos de Uso

Caso 1: Primera vez ejecutando el comando

# 1. Hacer análisis inicial
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan --dry-run"

# 2. Si hay pocos archivos (<5000), eliminar todos
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan"

# 3. Si hay muchos archivos, eliminar por lotes
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --limit 10000"

Caso 2: Mantenimiento regular

# Escaneo rápido y limpieza
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan"

Caso 3: Limpieza masiva después de migración de datos

# 1. Análisis completo primero
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --dry-run"

# 2. Limpieza por lotes grandes
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --limit 50000"

Consideraciones de Seguridad

⚠️ IMPORTANTE - Hacer Backup

Siempre haz un backup de tu directorio /media/ antes de ejecutar eliminaciones masivas:

# Backup del directorio media
docker exec backend tar -czf /tmp/media_backup.tar.gz /app/media/

# Copiar backup al host
docker cp backend:/tmp/media_backup.tar.gz ./media_backup_$(date +%Y%m%d_%H%M%S).tar.gz

✅ Buenas Prácticas

1. Siempre usar --dry-run primero para ver qué se va a eliminar
2. Empezar con lotes pequeños (--limit) en lugar de eliminar todo de una vez
3. Verificar la aplicación después de cada limpieza para asegurar que no se rompió nada
4. Ejecutar en horarios de bajo tráfico para grandes volúmenes
5. Monitorear el espacio en disco antes y después

🚨 Advertencias

• Los archivos eliminados NO SE PUEDEN RECUPERAR fácilmente
• El comando solo verifica referencias en la BD, no enlaces desde código o templates
• Archivos muy recientes podrían estar en proceso de ser referenciados

Troubleshooting

Error: "Too many open files"

# Aumentar límite de archivos abiertos
docker exec -it backend bash -c "ulimit -n 65536 && cd /app && python manage.py cleanup_media_fast --quick-scan"

Proceso muy lento

# Usar modo quick-scan en lugar de escaneo completo
docker exec -it backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan --dry-run"

Verificar que el comando existe

# Listar comandos disponibles
docker exec -it backend bash -c "cd /app && python manage.py help"

Automatización

Para automatizar la limpieza regular, puedes crear un cron job:

# Ejecutar limpieza semanal los domingos a las 2 AM
0 2 * * 0 docker exec backend bash -c "cd /app && python manage.py cleanup_media_fast --quick-scan" >> /var/log/media_cleanup.log 2>&1

Monitoreo

Para monitorear el efecto de la limpieza:

# Antes de limpiar
docker exec backend du -sh /app/media/

# Después de limpiar (verificar el cambio)
docker exec backend du -sh /app/media/