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

Mode	Isolation	Use Case	Cross-Host?
bridge (default)	Container-level	Single-host containers	❌
host	None (share host)	Max performance, no isolation	❌
overlay	Container-level	Swarm multi-host	✅
none	Full	No networking needed	❌
macvlan/ipvlan	MAC/IP-level	Legacy apps needing physical IP	✅

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 — 能力边界（适用与不适用场景）

分类	场景	说明
✅ 能做	单机容器网络配置	bridge/host/none 模式选择
✅ 能做	容器间 DNS 通信	自定义 bridge 网络 + 服务名解析
✅ 能做	端口发布	-p host:container 端口映射
⚠️ 需条件	跨主机通信	需要 overlay 网络 + Swarm 模式
⚠️ 需条件	macOS --network host	行为不同于 Linux，建议用 -p 替代
❌ 超范围	K8s 网络策略（NetworkPolicy）	使用 docker-production + K8s 文档
❌ 超范围	外部负载均衡（Nginx/HAProxy）	基础设施层级
❌ 超范围	iptables/nftables 精细配置	Linux 网络管理

When NOT to Use This Skill

❌ Skip	✅ Use Instead
Docker basics	docker-basics
Running containers	docker-run
Compose networking	docker-compose (compose handles network creation automatically)
Kubernetes networking	K8s documentation

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 网络概述	https://docs.docker.com/network/
docker network 命令	https://docs.docker.com/reference/cli/docker/network/
网络驱动	https://docs.docker.com/network/drivers/
Bridge 网络	https://docs.docker.com/network/bridge/
Overlay 网络	https://docs.docker.com/network/overlay/
端口发布	https://docs.docker.com/network/#published-ports

🧭 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: 支持中文文档和中文注释，详见国内适配章节。