Tecnología · GUÍA PRÁCTICA
¿Docker Compose encontró contenedores huérfanos? Audita la propiedad antes de borrarlos
Un aviso de contenedor huérfano no demuestra que pueda desecharse. Confirma el proyecto efectivo, las etiquetas de propiedad y los datos montados; separa cambios de servicio, colisiones de nombre, conjuntos de archivos y ejecuciones puntuales, y elige la acción mínima.
Docker Compose llama huérfano a un contenedor asociado con la identidad efectiva del proyecto cuando su servicio no aparece en el modelo Compose usado por el comando actual. Puede ser el resultado esperado de renombrar un servicio, pero también una colisión entre proyectos, otro conjunto de archivos o un contenedor detenido de una ejecución puntual.
El aviso es una prueba que investigar, no permiso para borrar. La pregunta segura no es solo si existe `--remove-orphans`, sino qué proyecto y servicio creó cada contenedor, si la configuración todavía pretende administrarlo y si sus montajes guardan datos necesarios.
Esta guía empieza con comandos de solo lectura. No recomienda un prune global, no elimina volúmenes con nombre ni externos y no oculta el aviso antes de entender la propiedad.
1. Conserva el aviso exacto y pausa la limpieza
Guarda el aviso completo, el comando, el directorio de trabajo y cada argumento `-f`, `--project-directory`, `-p` o `--project-name`. Mientras la propiedad esté abierta, no ejecutes `docker container prune`, `docker compose down -v` ni repitas con `--remove-orphans`.
Registra `docker compose version`, el Docker context, los archivos Compose y el entorno que afecta al nombre, como `COMPOSE_PROJECT_NAME` y el `.env` seleccionado.
Usa `docker ps -a --no-trunc` para anotar ID, estado y nombre; las etiquetas y el modelo efectivo son la prueba principal.
2. Resuelve el nombre efectivo del proyecto Compose
La prioridad documentada es: `-p`, `COMPOSE_PROJECT_NAME`, el último `name` de nivel superior de los archivos indicados, el nombre base del directorio del proyecto y, por último, el directorio actual. Reconstruye la invocación antes de suponer que dos archivos son proyectos separados.
Renderiza `docker compose config` con los mismos archivos, profiles, entorno y opciones, y conserva el nombre y la lista de servicios sin exponer secretos.
Si dos repositorios resuelven el mismo nombre, dales identidades estables y distintas; no borres un contenedor válido del otro proyecto.
3. Lee las etiquetas Compose de cada contenedor avisado
Inspecciona el ID exacto y registra `com.docker.compose.project`, `com.docker.compose.service`, `com.docker.compose.project.config_files`, `com.docker.compose.project.working_dir` y el indicador de ejecución puntual disponible. Usa el JSON de `docker inspect`, no un nombre truncado.
Una etiqueta de proyecto distinta es una condición para parar. Incluso si coincide y el servicio no está en el modelo, solo existe un candidato a huérfano, no una eliminación segura.
Compara también archivos y directorios para detectar cambios de nombre, orden de `-f` o automatización ejecutada desde otra ruta.
4. Separa las cuatro causas habituales
Un servicio renombrado o borrado mantiene la etiqueta de proyecto, pero la antigua etiqueta de servicio ya no aparece; confirma el cambio en control de versiones o despliegues. En una colisión de nombre, la identidad parece igual aunque las aplicaciones o raíces sean distintas; corrige los nombres antes de eliminar.
Un contenedor de `docker compose run` puede quedar detenido.
Un issue ascendente muestra acumulación en una versión concreta, pero no debe generalizarse: revisa etiquetas, estado, código de salida y versión.
Si el servicio pertenece a otra combinación admitida de `-f` o profile, conserva y documenta ese modelo propietario.
5. Audita montajes y volúmenes antes de tocar el contenedor
Registra bind mounts, volúmenes con nombre y anónimos mediante `docker inspect`. Un contenedor detenido puede ser el mapa más claro de datos no documentados; confirma copias y restauración con el responsable del servicio.
La referencia de Compose down separa contenedores y redes de los volúmenes. Los volúmenes con nombre no son capas desechables y los externos se administran fuera del proyecto.
No añadas `-v` por el aviso. Si hay puertos o trabajo activo, identifica usuarios y dependencias antes de detener.
6. Elige la acción de menor alcance
Solo usa un comando Compose del mismo proyecto y conjunto de archivos cuando hayas probado que el contenedor está obsoleto, pertenece al proyecto actual, no presta un trabajo necesario y sus datos están protegidos. `docker compose up --remove-orphans` elimina servicios ausentes del modelo actual; primero prueba que el alcance es correcto.
Ante una colisión, cambia la identidad sin borrar. Si pertenece a otro profile o conjunto de archivos, consérvalo.
Para una ejecución puntual, prioriza su ciclo de vida normal y una solución específica de versión frente a un prune global. Después, repite el comando original y verifica que proyectos, puertos, redes y montajes ajenos no cambiaron.
Prueba | Rama probable | Acción mínima segura La etiqueta project difiere | Propiedad incorrecta | Parar y resolver invocación y nombre Mismo project y servicio antiguo ausente tras un cambio intencional | Servicio obsoleto confirmado | Proteger datos y retirar con alcance de proyecto Raíces no relacionadas resuelven el mismo nombre | Colisión de proyecto | Asignar nombres distintos y conservar contenedores válidos Contenedor puntual detenido con prueba coincidente | Ciclo de vida puntual | Comprobar salida y versión; tratar solo ese contenedor Servicio de otro archivo/profile admitido | Recurso esperado | Conservar y documentar la invocación propietaria
7. Valida el resultado y prepara un registro para soporte
La aceptación exige un propietario project/service para cada contenedor, recursos conservados vinculados a invocaciones admitidas, eliminaciones probadas como obsoletas, montajes necesarios presentes y ningún efecto del comando original sobre otro proyecto.
Para soporte, aporta versiones Compose/Engine, context, nombre efectivo, orden de archivos, ID y etiquetas, estado, código de salida y tipos de montaje, siempre sin credenciales ni secretos.
Solo plantea una regresión tras descartar prioridad del nombre, conjuntos de archivos, etiquetas, estado puntual y ciclo de vida normal.
Preguntas frecuentes
¿Qué significa contenedor huérfano en Docker Compose? Está asociado al proyecto efectivo, pero su servicio no figura en el modelo actual. Puede deberse a un servicio retirado, una colisión de nombre, otro conjunto de archivos/profiles o una ejecución puntual.
¿`--remove-orphans` siempre es seguro? No. Solo cuando el alcance del proyecto es correcto, el candidato está realmente obsoleto y los datos y montajes necesarios están protegidos.
¿Por qué dos archivos no relacionados ven los mismos contenedores? Pueden resolver el mismo nombre por el directorio, una variable, `name` o un `-p` explícito. Usa nombres estables y distintos.
¿Conviene usar `docker container prune` para quitar el aviso? No como primer paso. Su alcance es mayor y no explica la propiedad. Inspecciona y trata solo contenedores probados como obsoletos.
