Docker Networking

Docker Networking — 网络配置与容器通信

Comprehensive guidance for Docker networking modes, configuration, and troubleshooting.

When to Use

ALWAYS use this skill when the user mentions:

• "docker network", "容器网络"
• "bridge network", "host network", "overlay network"
• "端口映射", "publish port"
• "容器之间怎么通信", "跨容器通信"
• "网络不通", "network troubleshooting"

Network Mode Comparison

Custom Bridge Network (Recommended)

# Create a custom network
docker network create --driver bridge mynet

# Run containers on it
docker run -d --name app1 --network mynet nginx:alpine
docker run -d --name app2 --network mynet nginx:alpine

# DNS resolution works automatically
docker exec app1 ping app2    # ✅ responds
docker exec app1 nslookup app2  # ✅ resolves

# Benefits over default bridge:
# - Automatic DNS resolution
# - Container isolation from default bridge
# - Can connect/disconnect at runtime

Port Publishing

# Basic port mapping
docker run -p 8080:80 nginx     # host:8080 → container:80
docker run -p 8080              # random host port → container:8080
docker run -P nginx             # publish all EXPOSE'd ports to random host ports

# Multiple ports
docker run -p 8080:80 -p 8443:443 nginx

# Bind to specific interface
docker run -p 127.0.0.1:8080:80 nginx  # only localhost

Service Discovery

Custom bridge network provides automatic DNS:

┌──────────────────────────────────┐
│  my-network (bridge)             │
│                                  │
│  ┌──────┐  ┌──────┐  ┌──────┐   │
│  │ app1 │  │ app2 │  │  db  │   │
│  └──┬───┘  └──┬───┘  └──┬───┘   │
│     │         │         │        │
│     └─── DNS: app2 → 172.18.0.3 │
│          DNS: db → 172.18.0.4   │
└──────────────────────────────────┘

app1 can connect to db:5432 directly — no IP needed!

Overlay Network (Swarm)

# Create overlay for multi-host
docker network create --driver overlay --attachable my-overlay

# In compose:
networks:
  backend:
    driver: overlay

Network Troubleshooting

# Inspect network details
docker network inspect mynet

# Test connectivity from container
docker exec app1 ping -c 3 app2
docker exec app1 nslookup db
docker exec app1 curl http://app2:8080/health

# Check iptables (host)
sudo iptables -t nat -L DOCKER -n

Workflow — 推荐配置流程

Step 1: 确定需求: 容器间通信？端口暴露？跨主机？选择网络模式 Step 2: 创建网络: docker network create --driver bridge mynet Step 3: 启动容器: docker run -d --network mynet --name db mysql + docker run -d --network mynet --name api myapp Step 4: 验证连通性: docker exec api ping db（服务名 DNS 解析） Step 5: 排查问题: docker network inspect mynet → docker exec api nslookup db

Gotchas — Common Pitfalls

• Default bridge no DNS: Containers on the default bridge CANNOT resolve each other by name. → Recovery: docker network create mynet && docker run --network mynet ...; always use custom bridge networks.
• Port already in use: -p 8080:80 fails if host port 8080 is taken. → Recovery: lsof -i :8080 to find the process; use -p 8081:80 or -p 80 for random host port.
• Mac host networking limitation: --network host on Docker Desktop (Mac) joins the VM's network, not the Mac's. → Recovery: Publish ports with -p instead of --network host.
• Overlay without Swarm: Overlay networks only work with Swarm mode. → Recovery: docker swarm init first, or add --attachable flag for standalone containers.
• EXPOSE does NOT publish: EXPOSE in Dockerfile is documentation only. → Recovery: Always use -p or Compose ports: to actually make ports accessible.

Boundary — 能力边界（适用与不适用场景）

When NOT to Use This Skill

Security & Stability

• Use --internal flag for networks that should not have internet access.
• Encrypt overlay network traffic: --opt encrypted=true.
• Avoid --network host in production — no network isolation.
• No executable scripts bundled. Guidance only.

📚 官方文档参考

🧭 Docker Skills Journey

📍 You are here: `docker-networking` — 网络配置

← Previous: docker-run | → Next: docker-compose

FAQ

Q1: 如何快速上手此技能？ A: 参考上方的快速开始章节，按步骤操作即可。

Q2: 遇到版本不兼容问题怎么办？ A: 检查依赖版本，使用 lock 文件锁定，参考常见陷阱章节。

Q3: 如何在生产环境使用？ A: 参考最佳实践章节，确保配置正确，做好监控和日志。

Q4: 性能如何优化？ A: 参考性能优化相关文档，使用缓存、索引等手段。

Q5: 如何贡献或反馈问题？ A: 在 GitHub 仓库提交 Issue 或 Pull Request。

Q6: 是否支持中文？ A: 支持中文文档和中文注释，详见国内适配章节。

Web + Database on custom network

# 1. Create custom network
docker network create app-net

# 2. Start database
docker run -d --name db --network app-net   -e POSTGRES_PASSWORD=secret   -v pgdata:/var/lib/postgresql/data   postgres:16-alpine

# 3. Start web app (connects to db by name!)
docker run -d --name web --network app-net   -e DATABASE_URL=postgres://postgres:secret@db:5432/mydb   -p 8080:8080   myapp:latest

# 4. Verify: web can reach db via DNS
docker exec web ping -c 2 db     # ✅
docker exec web nslookup db      # ✅ resolves to 172.x.x.x

自定义网络：多容器 DNS 互通

# 创建自定义 bridge 网络
docker network create --driver bridge myapp-net

# 运行数据库
docker run -d --name db \
  --network myapp-net \
  -e MYSQL_ROOT_PASSWORD=secret \
  mysql:8.4

# 运行应用（通过服务名 db 连接数据库）
docker run -d --name api \
  --network myapp-net \
  -p 8080:8080 \
  -e DB_HOST=db \
  -e DB_PORT=3306 \
  myapp:latest

# 验证 DNS 解析
docker exec api ping db
docker exec api nslookup db   # 返回 db 容器的 IP

动态连接/断开网络

# 运行时不指定网络
docker run -d --name redis redis:7-alpine

# 动态连接到网络
docker network connect myapp-net redis

# 断开
docker network disconnect myapp-net redis

查看网络详情

docker network ls
docker network inspect myapp-net

# 输出：
# {
#   "Containers": {
#     "abc...": { "Name": "db", "IPv4Address": "172.18.0.2/16" },
#     "def...": { "Name": "api", "IPv4Address": "172.18.0.3/16" }
#   }
# }

Docker Network Modes

Port Mapping Reference

-p HOST_PORT:CONTAINER_PORT[/PROTOCOL]

# Map container port 80 to host port 8080
docker run -p 8080:80 nginx

# Map to random host port
docker run -p 80 nginx
docker port <container>      # See which host port was assigned

# Protocol-specific
docker run -p 8080:80/tcp -p 8080:80/udp nginx

# Bind to specific interface
docker run -p 127.0.0.1:8080:80 nginx   # localhost only
docker run -p 0.0.0.0:8080:80 nginx     # all interfaces

# Publish all EXPOSE'd ports to random host ports
docker run -P nginx

In compose.yml

ports:
  - "8080:80"              # host:container
  - "127.0.0.1:8443:443"   # bind to localhost
  - "8080:8080/udp"        # UDP

网络排查四步诊断法

步骤 1：inspect 收集信息

# 查看容器网络配置
docker inspect --format='{{json .NetworkSettings.Networks}}' web | jq .

# 查看网关和 IP
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}} {{.Gateway}}{{end}}' web

# 查看 DNS 配置
docker exec web cat /etc/resolv.conf

步骤 2：连通性测试

# 容器间 ping
docker exec web ping api

# 端口测试
docker exec web nc -zv db 3306

# DNS 解析
docker exec web nslookup api
docker exec web nslookup api.myapp-net   # 完整域名

步骤 3：iptables 检查

# 查看 NAT 规则（端口映射）
sudo iptables -t nat -L DOCKER -n

# 查看 FORWARD 规则
sudo iptables -L DOCKER-USER -n

步骤 4：抓包分析

# 抓取容器网卡流量
docker run --rm --net container:web nicolaka/netshoot \
  tcpdump -i eth0 port 80

常见问题速查