Docker on 吾爱主机

Docker 桥接网络与嵌入式 DNS：原理、连通性与工程实践

Tue, 21 Jul 2026 00:00:00 +0800

本地 docker run 能通、Compose 里服务名却解析失败；两个容器“看起来在同一台机器”却互 ping 不通；或者明明没 -p，却发现同网段容器已经能访问全部端口——这些日常问题，大多不是“Docker 坏了”，而是 bridge 网络模型 + DNS 解析路径 理解不到位。

本文基于 Docker 官方 Networking overview、Bridge network driver、Packet filtering and firewalls、Networking in Compose 与 Legacy container links，把 默认 bridge 与用户自定义 bridge 的差异、嵌入式 DNS（127.0.0.11）、端口可达性、防火墙/iptables 协作，以及可复现的连通性实验 讲清楚，方便你在排障时按机制定位。

一、问题背景：容器眼里只有网卡，没有“魔法互联”

从容器视角看，网络很朴素：一张网卡、一个 IP、默认网关、路由表和 DNS。容器并不知道对端是不是另一个 Docker 容器，也不知道自己挂在 default bridge 还是自定义网络上。

因此，工程里真正要掌握的是 Docker 如何在宿主机上拼出这张网：

用哪种 network driver 创建隔离域；
容器如何获得 IP，以及如何访问外网（masquerading）；
同网/跨网时，哪些端口天然可达，哪些必须 publish；
名字解析走 宿主 /etc/resolv.conf 拷贝，还是 Docker 嵌入式 DNS。

把这四条对齐后，再看 docker network inspect 和 cat /etc/resolv.conf，排障会快很多。

二、核心机制：bridge 网络在做什么

2.1 软件桥与隔离边界

Bridge 驱动在 Linux 上使用软件网桥：

同一 bridge 网络内的容器可互通；
默认阻止来自其他 bridge 网络、以及 Docker 宿主机之外的直接访问；
通过 masquerading（源地址伪装） 让容器出网时，外部只看到宿主机 IP；
支持 port publishing，把容器端口映射到宿主机地址，供外部或其他网络访问。

官方明确：bridge 面向 同一 Docker daemon 主机 上的容器；跨主机通信需要 OS 级路由或 overlay 等方案。

2.2 内置驱动速览（选型锚点）

Driver	典型用途
`bridge`	默认驱动；同机容器互联（本文重点）
`host`	去掉网络隔离，直接用宿主机网络栈
`none`	完全隔离，无网络
`overlay`	多 daemon / Swarm 跨节点
`macvlan` / `ipvlan`	让容器更像“物理网”上的设备 / VLAN 集成

没有特殊需求时，应用栈优先用 用户自定义 bridge，而不是长期堆在 default bridge 上。

2.3 默认 bridge vs 用户自定义 bridge（必须分清）

Docker 首次启动会自动创建名为 bridge 的 default bridge。未指定 --network 的容器会连上它。

官方对用户自定义 bridge 的结论很直接：User-defined bridge networks are superior to the default bridge network. 关键差异如下。

维度	default bridge	用户自定义 bridge
名字解析	默认只能靠 IP；`--link` 为 legacy	自动 DNS：可用容器名/别名互访
隔离	未指定网络的容器都挤在一起，无关栈可能互通	只有加入该网络的容器互通，作用域清晰
热插拔	要从 default bridge 换走，通常需停容器重建	运行中可用 `docker network connect/disconnect`
配置粒度	全局一份（常需改 daemon 并重启）	每个网络可独立 `docker network create` 配置
生产建议	官方视为 legacy 细节，不建议生产依赖	推荐作为同机服务互联默认选择

同一用户自定义 bridge 内的容器，彼此相当于暴露全部端口；若要对其他网络或宿主机外访问，才需要 -p/--publish。

2.4 嵌入式 DNS：`127.0.0.11`

DNS 是 default bridge 与自定义网络最容易踩坑的分界线：

default bridge：容器通常拿到宿主 /etc/resolv.conf 的拷贝，按宿主配置解析公网名；默认不能靠容器名互访。
自定义网络（含 Compose 默认项目网络）：使用 Docker embedded DNS。
- 地址固定为 127.0.0.11；
- 没有 IPv6 等价地址，IPv6-only 容器仍用该 IPv4 地址；
- 容器名/别名解析在嵌入式 DNS 完成；
- 外部域名查询会转发到宿主上配置的 DNS。

若应用硬编码了 DNS 服务器地址，官方建议写 127.0.0.11（在自定义网络场景下），而不是宿主上的 8.8.8.8 之类——后者会绕过容器名解析。

可用标志（docker run / docker create）：

标志	作用
`--dns`	指定 DNS 服务器；注意解析发生在容器网络命名空间，`--dns=127.0.0.1` 指容器自己的 loopback
`--dns-search`	搜索域
`--dns-opt`	`resolv.conf` 选项
`--hostname`	容器主机名（默认多为容器 ID）

宿主 /etc/hosts 的自定义条目不会自动继承进容器；额外主机名用 --add-host / Compose extra_hosts。

2.5 端口可达性与防火墙协作

同 bridge 网络：容器端口对宿主及同网其他容器可达；
默认配置下，其他 bridge 网络或宿主机外访问需要 publish；
Linux 上 Docker 会创建防火墙规则以实现隔离、端口发布与 NAT；不要随意改 Docker 生成的规则；
默认后端多为 iptables，也支持 nftables；bridge 上两者功能等价；
对 ipvlan / macvlan / host，Docker 不创建这套 bridge 规则；
Docker 常会打开 IP 转发，并可能把转发默认策略设为 drop（防止宿主机无意变成路由器）；
Docker 与 ufw 不兼容的常见根因：Docker 在 nat 表改写流量，可能在 ufw 的 INPUT/OUTPUT 之前分流，导致“ufw 规则像没生效”。

常用网络级选项（docker network create --opt）：

Option	默认	含义
`com.docker.network.bridge.enable_ip_masquerade`	`true`	出网伪装
`com.docker.network.bridge.enable_icc`	`true`	同网容器互通；可关以强制“只经代理/发布口访问”
`com.docker.network.bridge.host_binding_ipv4`	全部地址	未写主机 IP 时的默认绑定地址
`com.docker.network.driver.mtu`	`0`（不限制）	MTU

2.6 Compose 如何落地同一套模型

docker compose up 默认会创建名为 <project-name>_default 的 bridge 网络，服务全部加入，并向内部 DNS 注册服务名。因此 Compose 里写 http://api:8080 往往能通，而“裸 default bridge 起两个容器却写容器名”会失败——这不是 Compose 魔法，而是 自定义网络 + 嵌入式 DNS。

还可声明 internal: true 的网络（无默认出网网关），把数据库等后端放在“只能被同项目服务访问”的网段上。

三、实践：可复现的连通性与 DNS 实验

下面命令假定本机已安装 Docker Engine。若无 alpine 镜像，会自动拉取。

3.1 观察 default bridge：能通 IP，不能靠名字

# 两个容器都挂在 default bridge（未指定 --network）
docker run -d --name dns-a alpine sleep 3600
docker run -d --name dns-b alpine sleep 3600

# 看 IP
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' dns-a
IP_A=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' dns-a)

# IP 互通通常成功
docker exec dns-b ping -c1 "$IP_A"

# 名字解析：在 default bridge 上通常失败（无嵌入式 DNS 的容器名互访）
docker exec dns-b ping -c1 dns-a || echo "name resolve failed as expected on default bridge"

# 看 resolv.conf：往往是宿主 DNS 拷贝，而不是 127.0.0.11
docker exec dns-b cat /etc/resolv.conf

清理：

docker rm -f dns-a dns-b

3.2 用户自定义 bridge：容器名解析 + `127.0.0.11`

docker network create demo-net

docker run -d --name web --network demo-net alpine sleep 3600
docker run -d --name db --network demo-net alpine sleep 3600

# 名字应可解析
docker exec web ping -c1 db
docker exec db ping -c1 web

# 嵌入式 DNS
docker exec web cat /etc/resolv.conf
# 期望 nameserver 为 127.0.0.11

# 同网端口：无需 -p，另一容器即可访问（这里用 nc 示意）
docker exec -d db sh -c 'echo hi | nc -l -p 9000'
docker exec web sh -c 'nc -w 2 db 9000'

运行中热挂网络：

docker run -d --name side alpine sleep 3600 # 先在 default bridge
docker network connect demo-net side
docker exec side ping -c1 web
docker network disconnect demo-net side

清理：

docker rm -f web db side
docker network rm demo-net

3.3 “前后端分离网络”拓扑（多网卡容器）

docker network create frontend
docker network create --internal backend # 无默认出网，适合数据库平面

docker run -d --name api --network frontend alpine sleep 3600
docker network connect backend api

docker run -d --name pg --network backend alpine sleep 3600

# api 能访问 pg（同 backend）；pg 默认不应依赖出网
docker exec api ping -c1 pg

# 可选：限制默认绑定，仅本机可访问已发布端口
docker network create \
 --opt com.docker.network.bridge.host_binding_ipv4=127.0.0.1 \
 local-only

3.4 Compose 最小可运行示意

# compose.yaml
services:
 web:
 image: alpine
 command: sleep 3600
 depends_on: [api]
 api:
 image: alpine
 command: sleep 3600
 networks: [default, backend]
 db:
 image: alpine
 command: sleep 3600
 networks: [backend]

networks:
 backend:
 internal: true

docker compose up -d
docker compose exec web ping -c1 api # 服务名 DNS
docker compose exec api ping -c1 db
docker compose down

3.5 关闭 ICC（强制“不能随意横穿”）

docker network create \
 --opt com.docker.network.bridge.enable_icc=false \
 no-icc-net

# 同网容器在 ICC 关闭后，默认相互连通会被限制
# 常用于强制流量只经反向代理或显式发布路径（结合具体策略验证）
docker network rm no-icc-net

四、常见坑与排查清单

症状	优先检查
容器名 ping 不通	是否挂在 default bridge？自定义网络里 `cat /etc/resolv.conf` 是否为 `127.0.0.11`？
Compose 服务名不通	是否在同一 project 网络？服务是否显式挂到不同 network 且未共享？`docker network inspect <project>_default`
外网不能访问容器	是否 `-p/--publish`？安全组/云防火墙？绑定是否被 `host_binding_ipv4=127.0.0.1` 限制在本机？
容器不能出网	`enable_ip_masquerade`？宿主 IP 转发？DNS 是否异常？`iptables=false` 是否误关 Docker 防火墙规则？
ufw “放行了仍异常”	已知 Docker 与 ufw 规则路径冲突，publish 流量可能绕过 ufw 链
`--link` 老项目	官方标为 legacy，推荐迁移到 user-defined networks；环境变量共享改用 env/volume/Compose
单网容器极多不稳定	内核限制：单 bridge 约 1000+ 容器时可能不稳定（见 moby#44973）
多网卡默认路由怪	多网络时默认网关可能变化；可用 `gw-priority` 指定优先网关
宿主 hosts 改了容器不生效	宿主 `/etc/hosts` 不继承；用 `--add-host` / `extra_hosts`

推荐排查命令：

docker network ls
docker network inspect <net>
docker inspect -f '{{json .NetworkSettings.Networks}}' <ctr> | jq .
docker exec <ctr> cat /etc/resolv.conf
docker exec <ctr> ip route
docker exec <ctr> getent hosts <peer-name>
# 宿主侧（Linux）
ip link show type bridge
# 注意：不要随手 flush Docker 管理的 iptables 链

五、工程建议（可直接落到规范）

新项目默认创建用户自定义 bridge（或直接用 Compose 项目网络），避免依赖 default bridge 与 --link。
服务发现用名字，不写死容器 IP；IP 会随重建变化，DNS 是稳定契约。
前后端分层网络：对外服务进可出网网络，数据库进 internal 网络；需要两边都通的 BFF/API 同时 attach。
只 publish 必要端口，生产优先绑定具体主机地址，避免 0.0.0.0 无脑暴露。
不要手改 Docker 生成的防火墙规则；若必须对接企业防火墙，走官方允许的集成方式，而不是 iptables=false 一刀切。
应用若强制配置 DNS，自定义网络场景优先 127.0.0.11，以免丢掉容器名解析。
跨主机通信升级到 overlay / 服务网格 / 云网络，不要指望单机 bridge “自动跨机”。

六、总结

Docker 单机互联的主干是 bridge：软件桥提供 L2 邻接与隔离，masquerade 解决出网，publish 解决入站，嵌入式 DNS（127.0.0.11） 解决自定义网络上的名字发现。default bridge 适合“随手跑个容器”，但缺少容器名 DNS、隔离弱、配置粗，官方更推荐 user-defined bridge；Compose 的服务名互通，本质上就是把这套模型产品化了。

记住一条排障主线：

先看容器挂在哪张网 → 再看 /etc/resolv.conf 是不是 127.0.0.11 → 再判断该不该有 publish → 最后才怀疑防火墙/宿主路由。

按这条线做，大部分“容器网络玄学”都会变成可验证的配置问题。

参考资料

Docker Docs — Networking overview（官方；DNS / default bridge / drivers）
Docker Docs — Bridge network driver（官方；default vs user-defined、选项表、ICC/masquerade）
Docker Docs — Network drivers（官方；bridge/host/overlay/macvlan 等选型）
Docker Docs — Packet filtering and firewalls（官方；iptables/nftables、ufw 注意点）
Docker Docs — Networking in Compose（官方；项目默认网络与服务名 DNS）
Docker Docs — Legacy container links（官方；--link legacy 与迁移建议）
源码文档镜像（核验用）：docker/docs content/manuals/engine/network/

Docker Compose 5.3 原生 pre_start 初始化容器实战：让本地编排更接近 Kubernetes Init Container

Wed, 08 Jul 2026 09:08:00 +0800

Docker Compose 在 2026 年 7 月连续发布了 v5.3.0 和 v5.3.1。其中 v5.3.1 主要是内部流程与依赖更新；真正值得一线工程团队关注的变化，是 v5.3.0 引入了对 Compose Spec pre_start 生命周期钩子的原生支持。官方发布说明明确写到：这个版本 introduces native support for init containers；对应合并的 PR 说明也进一步确认，pre_start 会以临时容器形式在服务容器启动前运行，非零退出码会阻止服务启动。

这意味着，过去很多只能写进镜像入口脚本、Makefile 或 CI/CD 脚本里的初始化动作，现在可以被声明在 compose.yaml 中：等待依赖、初始化共享卷、生成配置、执行轻量迁移、预热本地开发数据，都可以变成 Compose 编排的一部分。对于把 Docker Compose 当作本地开发、集成测试和小规模部署工具的团队来说，这次更新比普通补丁版本更有工程价值。

版本与来源核验

本文基于多源官方资料整理，而不是复制单篇网文：

版本	发布时间	关键信息
Docker Compose `v5.3.0`	2026-07-02	引入原生 init containers / `pre_start` 支持，包含 OCI token transport、`run` 事件作用域等修复
Docker Compose `v5.3.1`	2026-07-07	最新补丁版本，主要包含 CI hardening、依赖升级与 Docker CLI `29.6.1` 等依赖更新
Compose Spec	持续维护	定义 `pre_start`：在服务容器启动前按顺序运行初始化容器，全部退出 `0` 后才启动服务

因此，生产或团队模板中如果准备试用 pre_start，建议直接升级到 v5.3.1 或后续更高版本，而不是停留在刚发布的 v5.3.0。

pre_start 到底解决什么问题

传统 Compose 项目里，初始化逻辑通常散落在几个位置：

写进业务镜像的 entrypoint.sh；
在 docker compose up 前手动执行脚本；
在 CI 中先跑 docker compose run --rm migrate；
使用 depends_on.condition: service_healthy 等待依赖服务健康后再启动主服务。

这些做法都能工作，但都有缺点。入口脚本会把“容器启动”与“环境初始化”强耦合，脚本失败时排查困难；CI 前置命令容易和开发者本地流程不一致；depends_on 更偏向依赖顺序和健康检查，并不负责在主容器启动前执行一次性任务。

pre_start 的定位更像 Kubernetes 的 Init Container：它不是在主容器内部执行命令，而是创建一个短生命周期的临时容器。这个临时容器可以使用自己的镜像，也可以默认继承服务镜像；它与服务加入相同网络，并共享服务声明的卷挂载。只有这些步骤按声明顺序全部成功退出后，服务容器才会真正启动。

一个最小可用示例

假设 Web 服务启动前需要在共享卷里生成配置文件，可以写成：

services:
 web:
 image: nginx:alpine
 volumes:
 - web-conf:/etc/nginx/conf.d
 pre_start:
 - image: alpine
 command: >-
 sh -c 'cat > /etc/nginx/conf.d/default.conf <<EOF
 server { listen 80; location / { return 200 "ok\\n"; } }
 EOF'
 ports:
 - "8080:80"

volumes:
 web-conf:

这里的关键点是：pre_start 容器先把配置写入 web-conf，主服务随后挂载同一个卷并读取配置。如果初始化命令退出非零，web 不会继续启动，这比“主容器启动后才发现配置缺失”更早暴露问题。

如果初始化逻辑需要和业务镜像使用同一套工具链，也可以省略 image，让 hook 默认使用父服务镜像：

services:
 api:
 build: .
 command: ./start-api
 volumes:
 - app-data:/app/data
 pre_start:
 - command: ./bin/prepare-runtime-cache --output /app/data/cache.json

volumes:
 app-data:

官方 PR 中的端到端测试也覆盖了这类场景：当 hook 未指定镜像时，会回退到服务自身构建出的镜像。

运行语义：不要把它当成万能任务调度器

从 Docker Compose PR 的说明看，当前实现有几个重要边界：

pre_start 当前按“每个服务一次”运行，而不是每个副本都运行；
仅当没有副本已经在运行时触发，例如首次 up、--force-recreate 或 Compose 规范发生变化；
普通 scale up 不会重新触发已有服务的 pre_start；
per_replica: true 在当前 Compose 实现中会被提前拒绝；
hook 非零退出会阻止服务以及依赖它的服务继续启动；
多个 pre_start 步骤会按声明顺序执行。

这几个规则决定了它适合“服务级别的一次性准备”，不适合做每个副本都必须执行的注册、预热或本地临时目录初始化。如果你的任务必须随副本扩容逐个执行，现阶段仍应使用应用自身启动逻辑、编排平台能力，或等待 Compose 后续支持完整的 per_replica 语义。

适合落地的场景

1. 本地开发数据库初始化

在开发环境中，很多团队会把数据库、缓存、对象存储模拟器和应用服务放进同一个 Compose 项目。pre_start 可以用于生成测试数据、写入默认配置，或者确认迁移脚本已经运行。

services:
 app:
 build: .
 depends_on:
 db:
 condition: service_healthy
 pre_start:
 - image: alpine
 command: sh -c 'echo "seed-ready" > /shared/state.txt'
 environment:
 - APP_ENV=local
 volumes:
 - app-shared:/shared

 db:
 image: postgres:17
 healthcheck:
 test: ["CMD-SHELL", "pg_isready -U postgres"]
 interval: 5s
 timeout: 3s
 retries: 20

volumes:
 app-shared:

这里仍然建议保留数据库健康检查。pre_start 负责“服务启动前做什么”，depends_on 和 healthcheck 负责“依赖是否已经可用”，二者不是替代关系。

2. 集成测试中的夹具准备

CI 里经常需要启动一组服务进行端到端测试。把夹具准备放在 pre_start 中，可以让开发者本地执行和 CI 执行保持一致：

docker compose up --build --abort-on-container-exit

如果初始化失败，Compose 会在服务启动阶段就返回错误，日志也更集中。相比在 CI YAML 中堆多段 shell，Compose 文件成为更清晰的环境说明书。

3. 共享卷中的配置或证书生成

对一些内部工具、反向代理或 demo 环境，可以用 pre_start 生成临时证书、模板配置、静态资源索引等，再让主服务读取。注意这只适合非敏感或临时材料；生产密钥仍应交给 Secret 管理系统，不要把长期敏感信息写进普通卷。

升级与验证建议

升级前先确认当前版本：

docker compose version

升级后重点检查三类流程：

首次 docker compose up：确认 hook 顺序、日志和失败行为；
再次 docker compose up：确认已运行服务不会无意义重复执行初始化；
docker compose up --force-recreate 或修改 compose.yaml：确认变更后会按预期重新执行。

还可以专门构造一个失败用例：

services:
 demo:
 image: alpine
 command: sleep 300
 pre_start:
 - image: alpine
 command: sh -c 'exit 17'

执行 docker compose up demo 后，预期主服务不会启动。这类“失败路径测试”比只验证成功路径更重要，因为 pre_start 的核心价值之一正是把启动前置条件变成可失败、可观测的编排步骤。

注意事项

不要把耗时很长、需要重试队列或人工审批的任务放进 pre_start，否则会阻塞服务启动；
不要假设 scale up 会为新增副本重新执行初始化；
不要把它当作数据库迁移的唯一保护，生产迁移仍应有幂等、锁和回滚策略；
对共享卷写入要保持幂等，避免 --force-recreate 后重复生成脏数据；
团队模板中应固定最低 Compose 版本，否则旧环境会因为不认识字段而失败。

总结

Docker Compose v5.3.x 的 pre_start 支持，让 Compose 在本地编排和集成测试场景中补上了一个长期缺口：服务启动前的初始化任务终于可以以声明式方式进入 compose.yaml。它不是 Kubernetes 的完整替代品，也不是通用任务调度系统，但非常适合处理服务级别、短生命周期、可幂等的一次性准备动作。

对工程团队来说，推荐的落地路径是：先升级到 v5.3.1 或更高版本，在非生产 Compose 项目中选择一个低风险初始化步骤试点；随后把成功路径、失败路径、重复 up、--force-recreate 和扩容行为都纳入验证。只要边界理解清楚，pre_start 会让 Compose 项目更可读、更一致，也更接近现代容器编排的生命周期模型。

参考资料

Docker Compose GitHub Release：v5.3.1（2026-07-07），https://github.com/docker/compose/releases/tag/v5.3.1
Docker Compose GitHub Release：v5.3.0（2026-07-02），https://github.com/docker/compose/releases/tag/v5.3.0
Docker Compose PR #13862：Pre start init containers，https://github.com/docker/compose/pull/13862
Compose Specification：pre_start lifecycle hook，https://github.com/compose-spec/compose-spec/blob/main/spec.md#pre_start
Docker Docs：Compose release notes，https://docs.docker.com/compose/releases/release-notes/

Docker on 吾爱主机

Docker 桥接网络与嵌入式 DNS：原理、连通性与工程实践

一、问题背景：容器眼里只有网卡，没有“魔法互联”

二、核心机制：bridge 网络在做什么

2.1 软件桥与隔离边界

2.2 内置驱动速览（选型锚点）

2.3 默认 bridge vs 用户自定义 bridge（必须分清）

2.4 嵌入式 DNS：127.0.0.11

2.5 端口可达性与防火墙协作

2.6 Compose 如何落地同一套模型

三、实践：可复现的连通性与 DNS 实验

3.1 观察 default bridge：能通 IP，不能靠名字

3.2 用户自定义 bridge：容器名解析 + 127.0.0.11

3.3 “前后端分离网络”拓扑（多网卡容器）

3.4 Compose 最小可运行示意

3.5 关闭 ICC（强制“不能随意横穿”）

四、常见坑与排查清单

五、工程建议（可直接落到规范）

六、总结

参考资料

Docker Compose 5.3 原生 pre_start 初始化容器实战：让本地编排更接近 Kubernetes Init Container

版本与来源核验

pre_start 到底解决什么问题

一个最小可用示例

运行语义：不要把它当成万能任务调度器

适合落地的场景

1. 本地开发数据库初始化

2. 集成测试中的夹具准备

3. 共享卷中的配置或证书生成

升级与验证建议

注意事项

总结

参考资料

2.4 嵌入式 DNS：`127.0.0.11`

3.2 用户自定义 bridge：容器名解析 + `127.0.0.11`