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) ```bash # 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 ```bash # 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) ```bash # Create overlay for multi-host docker network create --driver overlay --attachable my-overlay # In compose: networks: backend: driver: overlay ``` ## Network Troubleshooting ```bash # 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: 支持中文文档和中文注释，详见国内适配章节。