Mapeo de puertos en Docker: no dejes que «puerto ya asignado» arruine tu viernes por la noche

Un viernes a las siete y media de la tarde, estás a punto de cerrar el portátil y marcharte. De repente, el product manager te escribe: «¿Puedes desplegar rápido un entorno de pruebas? El cliente quiere ver el demo mañana por la mañana».

Vale. Abres la terminal y escribes el comando docker run de siempre:

docker run -d -p 8080:80 nginx

Pulsas Enter. En pantalla aparece una línea de error en rojo:

Error response from daemon: driver failed programming external connectivity on endpoint romantic_euler:
Bind for 0.0.0.0:8080 failed: port is already allocated.

El corazón se te encoge. ¿El 8080 está ocupado? ¿Quién lo usa? ¿Por qué? ¿Y ahora qué?

¿Te suena? Apuesto a que al menos la mitad de quienes usan Docker se han tirado de los pelos ante este mensaje. Lo peor es que solo querías levantar un contenedor sencillo y acabas investigando puertos, procesos y reglas de firewall: lo que debería llevar cinco minutos se alarga media hora.

¿Qué demonios es el mapeo de puertos?

En pocas palabras, suena más misterioso de lo que es.

Puedes imaginar un contenedor Docker como un edificio de apartamentos. Dentro tiene sus propios «números de habitación» (puertos): nginx, por ejemplo, escucha por defecto en el 80. El problema es que ese edificio es independiente: desde fuera nadie sabe qué habitaciones hay ni cómo entrar.

El mapeo de puertos es el «traductor de números» en la puerta del edificio: alguien llama al 3000 de fuera y el traductor lo lleva a la habitación 80 del contenedor. Eso es lo que hace -p 3000:80: mapea el puerto 3000 del host al 80 del contenedor.

El formato es simple: -p puerto_host:puerto_contenedor. Al principio siempre me confundía el orden; luego me quedé con una regla: «fuera conecta con dentro» — el puerto exterior va primero, el interior después.

¿Qué diferencia hay entre -p y -P?

Estos dos parámetros confunden a mucha gente. -p (minúscula) es mapeo manual: tú decides qué puerto va a dónde. -P (mayúscula) es el modo perezoso: Docker mapea automáticamente todos los puertos expuestos del contenedor a puertos altos aleatorios del host (normalmente entre 32768 y 61000).

Con -P tienes que usar docker ps o docker port para ver qué puerto asignó Docker:

docker run -d -P nginx
docker port <container_id>

La salida puede ser algo así:

80/tcp -> 0.0.0.0:32768

Significa que el 80 del contenedor quedó mapeado al 32768 del host. Es cómodo, pero en producción no lo recomiendo: el número de puerto no es fijo y complica la configuración.

Cuando el puerto está ocupado: tres trucos para encontrar al culpable

Volvamos al escenario del principio: el puerto está ocupado. ¿Qué haces?

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Primer truco: comprueba si lo ocupa Docker

A veces reinicias un contenedor y el anterior no se detuvo del todo, dejando el puerto bloqueado. Primero mira si hay contenedores zombi con docker ps -a:

docker ps -a | grep 8080

Si encuentras alguno, elimínalo directamente:

docker rm -f <container_id>

Segundo truco: mira qué proceso del host usa ese puerto

Si no es Docker, será algún proceso del host. El comando depende del sistema:

En Linux/Mac:

# Método 1: con lsof
sudo lsof -i :8080

# Método 2: con netstat
sudo netstat -tulnp | grep 8080

# Método 3: con ss (más rápido)
sudo ss -tulnp | grep 8080

La salida suele parecerse a esto:

COMMAND  PID  USER   FD   TYPE DEVICE SIZE/OFF NODE NAME
node    1234  odensu   21u  IPv4  0x1234      0t0  TCP *:8080 (LISTEN)

Ahí está: PID 1234, un proceso node. Puedes:

1. Matarlo (si estás seguro de que no lo necesitas): kill -9 1234
2. O cambiar el puerto al levantar el contenedor Docker

En Windows es un poco más engorroso:

# Consultar el puerto
netstat -ano | findstr :8080

# Salida similar a:
# TCP    0.0.0.0:8080    0.0.0.0:0    LISTENING    1234

# Consultar el proceso
tasklist | findstr 1234

# Matar el proceso
taskkill /PID 1234 /F

Tercer truco: cambia de puerto y listo

Muchas veces no hace falta tanto lío. ¿El 8080 está ocupado? Usa el 8081:

docker run -d -p 8081:80 nginx

O deja que Docker elija:

docker run -d -p 0:80 nginx

Si escribes 0 como puerto del host, Docker asigna uno libre automáticamente. Luego consulta cuál fue con docker ps.

Mapeo de varios puertos y enlace a IP

¿Cómo mapear varios puertos?

A veces un contenedor necesita exponer más de un puerto. Por ejemplo, una app full stack con frontend en 3000, backend en 8000 y base de datos en 5432:

docker run -d \
  -p 3000:3000 \
  -p 8000:8000 \
  -p 5432:5432 \
  my-fullstack-app

Varios parámetros -p, uno tras otro.

También existe el truco del rango de puertos:

docker run -d -p 8000-8010:8000-8010 my-app

Esto mapea del 8000 al 8010 del host a los mismos puertos del contenedor. Sinceramente, casi nunca lo uso: es fácil liarse al gestionarlo.

Enlazar a una IP concreta

Por defecto, Docker enlaza los puertos a 0.0.0.0, es decir, todas las interfaces de red pueden acceder. Si solo quieres acceso local, especifica 127.0.0.1:

docker run -d -p 127.0.0.1:8080:80 nginx

Así la red externa no puede llegar al contenedor; solo la máquina local. Si el servidor tiene varias tarjetas de red, también puedes enlazar a una IP concreta:

docker run -d -p 192.168.1.100:8080:80 nginx

«Ya mapeé el puerto, ¿por qué sigo sin poder acceder?»

Es el problema que más he visto. El mapeo parece correcto, docker ps lo confirma, pero el navegador no conecta. Te cuento varias trampas en las que he caído.

Trampa 1: el servicio dentro del contenedor no escucha en 0.0.0.0

Es la que más se pasa por alto. Muchas aplicaciones escuchan solo en 127.0.0.1 (localhost), es decir, solo aceptan conexiones desde dentro del contenedor; las peticiones externas no entran.

Por ejemplo, una app Node.js:

// Forma incorrecta
app.listen(3000, 'localhost');  // Solo escucha en 127.0.0.1

// Forma correcta
app.listen(3000, '0.0.0.0');    // Escucha en todas las interfaces

Lo mismo con Python Flask:

# Incorrecto
app.run(host='127.0.0.1')

# Correcto
app.run(host='0.0.0.0')

¿Cómo comprobarlo? Entra al contenedor:

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

docker exec -it <container_id> netstat -tulnp

Si ves 127.0.0.1:3000 en lugar de 0.0.0.0:3000 o :::3000, ese es el problema.

Trampa 2: el firewall te bloquea

En servidores Linux, el firewall (firewalld o ufw) puede interceptar el puerto. Yo lo viví en CentOS: el mapeo estaba bien configurado, pero desde fuera no entraba nada.

Comprueba el estado del firewall:

# CentOS/RHEL
sudo firewall-cmd --list-all

# Ubuntu/Debian
sudo ufw status

Si está activo, abre el puerto:

# CentOS/RHEL
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

# Ubuntu/Debian
sudo ufw allow 8080/tcp

O, si el entorno es seguro (por ejemplo, una máquina de desarrollo), puedes desactivar el firewall temporalmente para probar:

# CentOS/RHEL
sudo systemctl stop firewalld

# Ubuntu/Debian
sudo ufw disable

En producción, no hagas esto.

Trampa 3: el grupo de seguridad del proveedor cloud no está configurado

Si usas Alibaba Cloud, AWS, Tencent Cloud u otro proveedor, además del firewall del sistema existe el «grupo de seguridad»: un firewall a nivel de plataforma con prioridad aún mayor.

La primera vez que usé Alibaba Cloud ECS me pasó exactamente esto: firewall del sistema desactivado, Docker bien configurado, y aun así sin acceso. Al final faltaba la regla de entrada en el grupo de seguridad.

Solución: entra en la consola del proveedor, localiza el grupo de seguridad y añade una regla de entrada para el puerto que necesitas. Cada plataforma es distinta, pero la idea es la misma.

Trampa 4: el modo de red de Docker no es el adecuado

Docker tiene varios modos de red: bridge (por defecto), host, none y container. Si usas --network host, el parámetro -p deja de tener efecto porque el contenedor usa directamente la pila de red del host:

# Así el parámetro -p se ignora
docker run -d --network host -p 8080:80 nginx

Con el modo host, el servicio escucha en el mismo puerto dentro y fuera del contenedor; no hace falta mapear. Tiene el mejor rendimiento, pero aumenta el riesgo de conflictos de puertos.

Flujo rápido de diagnóstico

Cuando un puerto no responde, suelo seguir este orden:

1. docker ps — confirma que el mapeo es correcto
2. docker logs <container_id> — revisa si el contenedor falló al arrancar
3. docker exec -it <container_id> netstat -tulnp — comprueba si el servicio escucha en 0.0.0.0
4. curl localhost:8080 — prueba desde el host para descartar problemas de red
5. Revisa las reglas del firewall del sistema
6. Revisa el grupo de seguridad del proveedor cloud

Siguiendo este flujo, casi siempre encuentras el problema.

¿El mapeo de puertos ralentiza el rendimiento?

Siendo honestos: sí, pero el impacto depende del caso.

El mapeo de puertos en Docker se basa en iptables (Linux) o en userland proxy (modo compatible multiplataforma). Cada paquete que pasa por el mapeo recorre lógica de reenvío, y eso tiene un costo.

Hice una prueba sencilla con ab (Apache Bench) sobre un contenedor nginx:

• Acceso directo a la IP del contenedor (sin mapeo): unas 50.000 peticiones/segundo
• Acceso a través del mapeo de puertos: unas 45.000 peticiones/segundo

Una diferencia de alrededor del 10 %. Para la mayoría de aplicaciones es aceptable. Pero si tu servicio es muy sensible al rendimiento (trading de alta frecuencia, servidores de juegos), quizá convenga optimizar.

Optimización 1: usar el modo de red host

Como comentamos, con --network host el contenedor usa la pila de red del host y no hay costo de mapeo:

docker run -d --network host nginx

Es lo más rápido, pero tiene dos contrapartidas:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

1. Los puertos del contenedor pueden chocar con los del host
2. Pierdes el aislamiento de red y con él parte de la seguridad

Úsalo con cuidado en producción.

Optimización 2: desactivar userland proxy

Por defecto, Docker usa iptables y userland proxy a la vez. Este último es un proxy en Go: buena compatibilidad, peor rendimiento. Si tu sistema soporta iptables (casi todos los Linux), puedes desactivarlo:

Edita /etc/docker/daemon.json:

{
  "userland-proxy": false
}

Reinicia Docker:

sudo systemctl restart docker

Reduce algo el costo, aunque la mejora no suele ser espectacular (quizá un 5 %).

Optimización 3: reducir mapeos innecesarios

Algunos servicios solo los usan otros contenedores y no necesitan exponerse al host. Por ejemplo, una base de datos que solo consume la app: no la mapees:

# Sin mapeo de puertos, solo comunicación dentro de la red Docker
docker run -d --name postgres --network mynet postgres

# La app se conecta a la base de datos (por nombre de contenedor)
docker run -d --name app --network mynet -p 3000:3000 my-app

La comunicación entre contenedores por la red Docker es mucho más rápida que pasar por mapeo de puertos.

¿Cuándo merece la pena preocuparse por el rendimiento?

En la práctica, el costo del mapeo de puertos suele ser irrelevante. Lo que de verdad importa es:

1. Los cuellos de botella de la propia aplicación (consultas a la base de datos, lógica del código)
2. Los límites de recursos del contenedor (CPU, memoria)
3. El I/O de disco y el ancho de banda de red

La pérdida del mapeo de puertos casi nunca está en el top de la lista. A menos que tu QPS esté en decenas de miles, optimiza primero el código de la aplicación.

Para cerrar

Volvamos al escenario del principio: viernes a las siete y media, el product manager pide un entorno de pruebas rápido. Ahora ya sabes:

Si aparece «port already allocated», primero revisa con docker ps -a si quedó un contenedor viejo, luego usa lsof o netstat para ver qué ocupa el puerto en el host. Si no hay más remedio, cambia de puerto o deja que Docker asigne uno (-p 0:80).

Si el puerto está mapeado pero no puedes acceder, sigue este orden: dirección de escucha del servicio dentro del contenedor → firewall del host → grupo de seguridad cloud → modo de red de Docker. En nueve de cada diez casos encuentras el problema.

El mapeo de puertos es lo más básico de Docker y también donde más dolores de cabeza aparecen. Pero si entiendes el principio y dominas el diagnóstico, dejarás de perder tiempo con esto.

La próxima vez que te atasques con un puerto, no entres en pánico. Respira, sigue el flujo y el problema se resuelve. Y podrás salir a tu hora y disfrutar del viernes por la noche.

Por cierto, guarda este artículo — el día que vuelva a pasarte, abrirlo te ahorrará tiempo. Yo hago exactamente eso.