Mantenimiento de la cola de imágenes

Este documento explica cómo funciona la cola de imágenes asíncrona del plugin, cómo supervisar su progreso y cómo mantener, procesar manualmente o vaciar la cola en entornos de producción.

Cuándo utilizar este documento

Lea este documento si es administrador del sitio y necesita comprender por qué las imágenes de los vehículos aún no aparecen después de una importación, por qué está creciendo la cola de imágenes o cómo gestionar las descargas de imágenes en sitios con catálogos grandes o recursos de servidor limitados.

Descripción general

Cuando el Modo de cola de imágenes está activado (el valor predeterminado para las importaciones programadas y activadas por REST), el plugin no descarga todas las imágenes de los vehículos durante la ejecución principal de la importación. En su lugar:

1. Solo la primera imagen de cada vehículo se descarga inmediatamente durante la importación.
2. Las URL de las imágenes restantes se almacenan en una cola persistente en la tabla de opciones WordPress (as24ci_image_queue).
3. Después de cada ejecución de importación, se programa un ejecutor de la cola de imágenes independiente como un evento único de WP-Cron para procesar las imágenes en cola por lotes.
4. El ejecutor se ejecuta repetidamente, procesando 30 imágenes por lote, hasta que la cola está vacía o se agota el tiempo asignado.

Este enfoque mantiene cada ejecución de importación corta y predecible, incluso para catálogos con muchas imágenes por vehículo.

Para las importaciones manuales iniciadas desde la pestaña del Importador (no a través de cron o REST), el modo de cola está desactivado por defecto y todas las imágenes se descargan inmediatamente durante la importación.

Cómo funciona el ejecutor de la cola de imágenes

El ejecutor de la cola de imágenes:

1. Adquiere su propio bloqueo temporal (as24ci_image_queue_running, TTL de 10 minutos) para evitar la superposición de ejecutores.
2. Lee la cola actual desde la opción as24ci_image_queue.
3. Procesa los elementos en lotes de 30 imágenes, comprobando después de cada lote si se ha alcanzado el tiempo asignado (el TTL del bloqueo menos 60 segundos, aproximadamente 540 segundos).
4. Vuelve a escribir la cola restante en la base de datos después de cada lote.
5. Registra las estadísticas de ejecución (processed, failed, remaining, timestamp) en la opción as24ci_image_queue_last_run.
6. Si quedan elementos después de agotarse el tiempo asignado, programa otro evento único de WP-Cron inmediatamente para que el procesamiento continúe en la siguiente solicitud disponible.
7. Libera el bloqueo al finalizar.

Una vez procesados todos los elementos en cola para una publicación de vehículo, el ejecutor reconstruye los metadatos de la publicación _as24ci_image_ids a partir de los ID de adjuntos reales en la base de datos y finaliza el hash de la imagen, de modo que la siguiente ejecución de importación pueda detectar correctamente futuros cambios.

Deduplicación de imágenes

El importador de imágenes deduplica las imágenes por URL de origen. Antes de descargar una imagen, comprueba si ya existe un adjunto con los mismos metadatos de publicación _as24ci_source_url. Si se encuentra una coincidencia, se reutiliza el adjunto existente en lugar de descargarlo de nuevo. Esto se aplica tanto a las importaciones inmediatas como a las de modo de cola.

Esto significa que volver a ejecutar una importación o volver a procesar la cola no creará adjuntos duplicados para las imágenes que ya se importaron correctamente.

Conversión a WebP

Si la opción Convertir a WebP está activada, cada imagen descargada se convierte al formato WebP antes de añadirse a la biblioteca de medios. El plugin intenta primero con GD, y luego con Imagick como alternativa. Si ninguno está disponible o la conversión falla, se utiliza el formato de imagen original. Los resultados de la conversión se registran con nivel de advertencia (warning) cuando fallan.

La calidad de WebP es configurable (1–100, por defecto 80). El valor de calidad también se puede anular a nivel de código mediante el filtro as24ci_webp_quality.

Supervisión de la cola de imágenes

Pestaña Sistema y Ayuda

1. Abra ADP Car Market Hub → Sistema y Ayuda.
2. En la tabla Tareas en segundo plano, busque la fila Procesador de imágenes (hook: as24ci_image_queue_process).
3. La columna Próxima ejecución muestra cuándo está programada la siguiente invocación del ejecutor.
4. La columna Estado muestra: - Programado (verde) — hay un evento del ejecutor en cola - En ejecución (ámbar) — el ejecutor está activo actualmente - Bloqueo atascado (rojo) — se detectó un bloqueo obsoleto; se borrará automáticamente en el siguiente intento de ejecución - No programado (ámbar) — no hay ningún ejecutor en cola actualmente (esperado cuando la cola está vacía)
5. La pestaña Sistema y Ayuda muestra una insignia de advertencia cuando el tamaño de la cola supera los 1.000 elementos, lo que indica que el procesamiento de imágenes se está retrasando.

Estadísticas de la última ejecución de la cola de imágenes

El plugin almacena los resultados de la ejecución más reciente del ejecutor en la opción as24ci_image_queue_last_run. Estas estadísticas incluyen:

• processed — imágenes descargadas correctamente en la última ejecución
• failed — imágenes que no se pudieron descargar
• remaining — elementos que aún esperan en la cola
• timestamp — marca de tiempo Unix de la última ejecución

Estos valores se muestran en la pestaña Sistema y Ayuda y se pueden utilizar para evaluar el rendimiento de la cola.

Pestaña Importación y Límites

La pestaña Automatización proporciona acciones de control manual para la cola de imágenes:

• Ejecutar cola de imágenes ahora — activa el ejecutor inmediatamente a través de una solicitud AJAX. Útil cuando desea forzar el procesamiento de imágenes sin esperar al siguiente evento programado.
• Vaciar cola de imágenes — descarta todos los elementos pendientes en la cola. Utilice esto cuando desee detener el procesamiento de imágenes, por ejemplo, si se puso en cola un lote grande de imágenes incorrectas. Esto no elimina las imágenes que ya se han descargado.

Paso a paso: procesar una cola de imágenes atascada

1. Abra ADP Car Market Hub → Sistema y Ayuda.
2. Compruebe la tabla Tareas en segundo plano para ver la fila del Procesador de imágenes. Si el estado es No programado pero la cola no está vacía (la insignia de advertencia es visible o las estadísticas de la última ejecución muestran un recuento restante distinto de cero), el evento cron del ejecutor no se volvió a programar.
3. Haga clic en Ejecutar cola de imágenes ahora en la barra de acciones de la pestaña Sistema y Ayuda para iniciar un ejecutor inmediatamente.
4. Espere a que se complete la ejecución (normalmente de unos segundos a unos minutos, dependiendo del tamaño de la cola).
5. Actualice la pestaña Sistema y Ayuda para verificar que la cola está disminuyendo.
6. Si el ejecutor se ejecuta pero la cola no disminuye (por ejemplo, si fallan todas las imágenes), compruebe el registro en busca de entradas de [ERROR] y [WARNING] relacionadas con Image queue worker o Image download failed.

Paso a paso: vaciar la cola de imágenes

Utilice este procedimiento cuando desee abandonar todas las descargas de imágenes pendientes (por ejemplo, después de eliminar un Seller ID o tras una eliminación masiva de vehículos).

1. Abra ADP Car Market Hub → Sistema y Ayuda o Importación y Límites.
2. Haga clic en Vaciar cola de imágenes.
3. Confirme la acción cuando se le solicite.
4. La opción de la cola se borrará y no se realizarán más descargas de imágenes en segundo plano para los elementos descartados.
5. Los vehículos a los que se les borraron las imágenes restantes solo tendrán la primera imagen (descargada durante la ejecución de la importación) hasta la próxima importación completa.

Límites de tamaño de la cola

El plugin impone un límite estricto de 20.000 elementos en la cola de imágenes. Si la cola crece más allá de este límite, se registra una advertencia y se ejecuta un paso de deduplicación para agrupar las entradas duplicadas. Verifique este comportamiento en la versión actual del plugin antes de publicar.

Referencia de configuración

Notas de funcionamiento

• El modo de cola de imágenes solo se aplica durante las importaciones activadas por WP-Cron o el endpoint cron de REST. Las importaciones manuales desde la pestaña del Importador siempre descargan todas las imágenes inmediatamente (a menos que se aplique el límite máximo de imágenes).
• La cola de imágenes persiste entre las ejecuciones de importación. Si el ejecutor no ha terminado de procesar un lote anterior cuando se ejecuta una nueva importación, las nuevas URL de imágenes se añaden a la cola existente.
• Si se elimina la publicación de un vehículo después de que sus URL de imágenes se hayan puesto en cola pero antes de que el ejecutor las procese, el ejecutor omitirá silenciosamente los elementos cuya publicación ya no exista.
• La cola de imágenes almacena metadatos por elemento, incluidos el ID de la publicación del vehículo, el Listing ID, la URL de la imagen y un hash de la imagen. Esto permite al ejecutor finalizar los hashes de las imágenes correctamente después de que se hayan procesado todas las imágenes de un vehículo.
• En sitios con catálogos grandes (cientos de vehículos con muchas imágenes cada uno), la cola de imágenes puede crecer hasta varios miles de elementos después de la primera importación. Este es un comportamiento esperado. La cola disminuirá de manera constante en las ejecuciones posteriores del ejecutor, siempre que WP-Cron (o el hook cron del ejecutor de la cola de imágenes) esté funcionando.
• Si el espacio en disco en el directorio de subidas (uploads) es bajo, las descargas de imágenes fallarán. La pestaña Sistema y Ayuda muestra la disponibilidad de espacio en disco. Libere espacio antes de ejecutar una importación de imágenes grande.

Resolución de problemas

Documentos relacionados

• Supervisión de importaciones
• Registro y supervisión
• Operación diaria
• Mantenimiento semanal