前言
在 Docker 环境中，容器默认使用私有 IP 段（如 172.17.0.0/16 或自定义的 172.18.0.0/16、172.20.0.0/16），这些地址在互联网上是不可路由的。要让容器能访问外部网络（如 ping 8.8.8.8、拉取镜像、访问 API），必须在宿主机上对容器发出的流量进行源地址 NAT（SNAT/MASQUERADE）。
Docker 的大部分“上网”魔法，其实就靠一条自动添加的 MASQUERADE 规则。
1. Docker 默认网络（docker0）的 MASQUERADE 是怎么工作的？
当你安装 Docker 并第一次启动容器时，Docker daemon 会自动完成以下操作：
- 创建 bridge 网络 docker0（默认子网通常是 172.17.0.0/16）
- 开启宿主机的 IP 转发（net.ipv4.ip_forward=1）
- 在 iptables nat 表的 POSTROUTING 链中添加一条核心规则：
-A POSTROUTING -s 172.17.0.0/16 ! -o docker0 -j MASQUERADE
# 或新版更常见的写法
-A POSTROUTING -s 172.17.0.0/16 ! -d 172.17.0.0/16 -j MASQUERADE
这条规则的含义：
- 源地址属于 docker0 子网（所有默认网络容器）
- 目的地址不是 docker0 子网（避免容器间通信也做无谓 NAT）
- 对匹配的包执行 MASQUERADE：把源 IP 改为外出接口的当前 IP（由 Linux 路由表决定）
MASQUERADE 与 SNAT 的关键区别在于：它不写死 IP，而是动态取当前路由选择的出口 IP，所以特别适合动态公网 IP 环境（家用路由器、4G/5G 拨号、某些云厂商弹性 IP）。
Docker 默认网络的上网原理：
容器 → veth → docker0 → 宿主机路由 → POSTROUTING MASQUERADE → 用宿主机出口 IP 发到互联网
2. 自定义网络的 MASQUERADE 行为
当你执行 docker network create my-net 创建自定义 bridge 网络时，Docker 默认也会自动为它添加一条类似的 MASQUERADE 规则，例如：
-A POSTROUTING -s 172.18.0.0/16 ! -o br-xxxxxxxxxxxx -j MASQUERADE
每个自定义 bridge 网络都会有一条独立的规则，互不干扰。
但有几种情况会导致自定义网络缺少 MASQUERADE：
-
创建时显式关闭了 masquerade
docker network create my-net --opt com.docker.network.bridge.enable_ip_masquerade=false -
Docker daemon 全局关闭了 ip-masq
/etc/docker/daemon.json中有"ip-masq": false -
iptables 规则被清空或覆盖（防火墙重启、k8s 网络插件、nftables 切换等）
-
网络是 external: true 的 compose 项目，但创建时没启用 masquerade
3. 快速排查与修复步骤
遇到“自定义网络容器能互 ping 但上不了外网”时，按以下顺序检查：
-
查看网络子网
docker network inspect <网络名> | grep -i subnet -
查看是否有对应 MASQUERADE 规则
sudo iptables -t nat -L POSTROUTING -n -v | grep MASQUERADE -
如果缺少，立即手动补上（替换成你的子网）
sudo iptables -t nat -A POSTROUTING -s 172.20.0.0/16 ! -d 172.20.0.0/16 -j MASQUERADE -
让规则持久化（推荐）
- Ubuntu/Debian：安装
iptables-persistent并netfilter-persistent save - 或加到开机脚本 / systemd timer
- Ubuntu/Debian：安装
-
最佳实践：重新创建网络（默认带 masquerade）
docker network rm <网络名> docker network create <网络名>
4. 总结
Docker bridge 网络（包括默认 docker0 和自定义网络）默认会自动添加 MASQUERADE 规则，让容器流量伪装成宿主机出口 IP，从而访问外网。
一旦这条规则缺失或被关闭，容器就“上不了网”。排查时优先看 iptables nat POSTROUTING 链中是否有对应子网的 MASQUERADE 条目——找到了，问题就解决了 90%。