容器 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/

Linux cgroup v2 内存控制与 OOM Killer：原理、观测与容器化实践

Thu, 16 Jul 2026 00:00:00 +0800

线上最棘手的一类故障，往往不是“服务报了明确业务错误”，而是进程突然消失：容器退出码 137、Pod 状态里出现 OOMKilled，或者主机 dmesg 里留下一行 Out of memory: Killed process。表象是“内存不够”，根因通常落在 内存如何被记账、如何被限制、以及内核如何选择牺牲者。

本文以 Linux cgroup v2 memory 控制器 与 OOM Killer 为主线，结合 Docker / Kubernetes 的常见映射，把“限多少、什么时候开始回收、什么时候杀进程、怎么排”讲清楚。

一、先建立两层模型：全局 OOM vs cgroup OOM

Linux 里至少要区分两种“内存不够”：

场景	典型触发	影响范围
全局内存压力	整机可用内存 + 可回收页不够，分配失败	OOM killer 在系统范围内按启发式选进程
cgroup 内存上限	某 cgroup 的 `memory.max` 触顶且回收失败	OOM 只发生在该 cgroup 内（不会跨出该 cgroup 去杀别人）

这解释了一个常见错觉：给容器设了 -m 512m，为什么还会拖垮宿主机？
因为：

没设硬限制时，容器与宿主机共享整机内存；
即使设了 limit，仍可能有内核开销、page cache 统计差异、swap 配置、以及 宿主级其他进程 的压力；
Docker 默认会尽量保护 daemon 自身，但不会自动把所有容器都“隔离成绝对安全沙箱”。

因此工程上要同时看：

进程/容器是否撞到了 自己的 limit；
节点是否发生了 系统级 OOM / kubelet 驱逐。

二、cgroup v2 的内存阶梯：min / low / high / max

cgroup v2 memory 控制器把控制面拆成“保护、限速、硬顶”几层。官方接口里最核心的是这些文件（单位均为字节）：

接口	角色	关键语义
`memory.current`	观测	当前 cgroup 及其后代已用内存
`memory.min`	硬保护	在 effective min 内，内存不会被回收；若系统没有其他可回收内存，可能直接触发 OOM
`memory.low`	尽力保护	在 effective low 内，尽量不被回收；只有无保护可回收内存时才可能被碰
`memory.high`	节流线	超高后进程被 throttling，并承受很重的 direct reclaim；不会因此调用 OOM killer
`memory.max`	硬上限	用量到顶且无法压回时，在该 cgroup 内调用 OOM killer
`memory.oom.group`	策略	设为 `1` 时，把 cgroup 当不可分割工作负载：要么一起杀，要么都不杀（`oom_score_adj=-1000` 的任务例外）
`memory.events`	事件计数	`high` / `max` / `oom` / `oom_kill` 等，是最好的“快撞墙”信号
`memory.peak`	峰值	自创建或重置以来的最大用量

可以把它理解成一条阶梯：

usage
 │
 │ memory.min ── 硬保护（尽量不回收；保护过猛可能反噬）
 │ memory.low ── 软保护（有余量时优先回收别人）
 │ memory.high ── 开始重压回收 + 节流（通常还不杀）
 │ memory.max ── 硬顶；回收失败 → cgroup OOM
 ▼

1. 为什么要有 `high`，而不是只设 `max`？

memory.max 是“悬崖”：到顶就可能杀进程。
memory.high 是“缓坡”：先让工作负载变慢、开始回收，给外部控制器（或人）反应时间。内核文档明确：high 越界 never invokes the OOM killer，极端情况下甚至可能被短暂突破。

生产里更健康的模式往往是：

high 设在“可接受抖动”的水位；
max 设在“绝对不可越过”的水位；
用 memory.events 的 high/max 做告警，而不是等进程死了再看。

2. `min`/`low` 保护不是免费的

memory.min 是硬保护：保护区内页面在“任何条件下”都不应被回收；如果系统已经没有未保护可回收内存，就可能 直接 OOM。
memory.low 是 best-effort：优先保护，但仍可能在全局极端压力下被回收。

因此：

保护值叠加超过父 cgroup/整机能力时，会发生 overcommit of protection；
effective 边界还会受祖先 cgroup 限制；
把所有关键服务都设成很高的 min，等于在内存不够时更容易触发“保谁都保不住”的 OOM。

三、OOM Killer：它到底怎么选人

1. 评分：`oom_score` 与 `oom_score_adj`

当内核决定必须杀进程腾内存时，会给候选任务打 badness 分。man-pages 对 /proc/<pid>/oom_score / oom_score_adj 的说明可概括为：

分数大致落在 0（几乎不杀）到 1000（优先杀）；
主要依据是任务相对其 allowed memory 的用量比例（RSS/swap 等估计）；
用满允许内存 ≈ 1000，用一半 ≈ 500；
root 进程额外获得约 3% 的“更宽容”额度；
oom_score_adj 范围 -1000 ~ +1000，在启发式结果上再加减；
oom_score_adj = -1000 表示 OOM 保护（基本不会被选中）。

“allowed memory”取决于 OOM 上下文：

系统全局 OOM → 整机可分配资源；
cgroup/limit 触顶 → 该 limit 本身；
cpuset / mempolicy 节点耗尽 → 对应节点集合。

2. 系统级可调旋钮（`/proc/sys/vm/*`）

参数	默认（文档）	作用
`oom_dump_tasks`	`1`	OOM 杀进程时是否打印系统任务摘要（pid/rss/oom_score_adj 等），便于事后定位
`oom_kill_allocating_task`	`0`	`0`：扫描任务列表按启发式选“更该杀”的；`1`：直接杀触发分配失败的那个任务（省扫描）
`panic_on_oom`	`0`	`0` 杀进程求生；`1` 全局 OOM 可 panic（节点局部耗尽未必）；`2` 连 memory cgroup OOM 也整机 panic
`overcommit_memory`	`0`	`0` 启发式拒绝明显 overcommit；`1` 几乎总是允许，直到真正用完；`2` never overcommit 策略

大多数业务机保持默认即可；集群 failover / 取证 场景才会认真考虑 panic_on_oom + kdump。
不要把 oom_kill_allocating_task=1 当成“优化”随手打开：它可能杀掉“刚好申请最后一页”的 innocuous 任务，而放过真正的内存黑洞。

3. cgroup 内 OOM 的边界

cgroup v2 文档强调两点：

触达 memory.max 且无法回收时，OOM killer 在该 cgroup 内被调用；
一旦在某个 cgroup 触发 OOM，不会去杀该 cgroup 外的任务（与祖先 memory.oom.group 取值无关）。

memory.oom.group=1 适合“多进程必须同生共死”的工作负载（例如某个多 worker 服务希望要么整组重启，要么都不半残）。
但要注意：被 -1000 保护的任务仍是例外。

四、工程映射：Docker 与 Kubernetes

1. Docker：把 limit 落到 cgroup

Docker 官方资源限制文档给出了与内存相关的关键选项：

# 硬上限（最小允许约 6m）
docker run -d --name demo -m 512m your-image

# 内存 + swap 总预算（细节依赖 --memory-swap 语义）
docker run -d -m 512m --memory-swap 1g your-image

# 软预留（争用时更“敏感”，不保证不越界）
docker run -d -m 1g --memory-reservation 512m your-image

# 一般不要关 OOM killer；若关闭，必须同时设置 -m
docker run -d -m 512m --oom-kill-disable your-image

要点：

-m/--memory：容器可用内存上限；
--memory-reservation：软限制，需小于 --memory，争用时生效，不保证永不越界；
--oom-kill-disable：禁用容器内 OOM killer；文档要求 仅在同时设置了 -m 时使用，否则可能把压力转嫁给宿主机，拖垮整机；
Docker daemon 会调整自身 OOM 优先级，降低“杀 daemon 导致全盘崩溃”的概率；容器进程默认没有这种优待。

2. Kubernetes：request / limit / QoS / 驱逐

Kubernetes 文档把资源语义拆成两层：

调度与预留：requests 供 kube-scheduler 选型，kubelet 也会为容器预留至少 request 量；
运行时强制：limits 由 kubelet/容器运行时落到 cgroup；memory limit 由内核通过 OOM kill 强制。

与 CPU 不同：CPU 超限通常是节流；内存超限更可能直接被内核杀掉。文档也提醒：OOM 是 反应式 的——容器可能短暂超过 limit，但在内核感知到压力后才被终止。

QoS 类（Guaranteed / Burstable / BestEffort）主要影响 节点资源压力下的驱逐优先级：

节点资源不足时，通常先考虑驱逐 BestEffort，再 Burstable，最后 Guaranteed；
因资源压力驱逐时，候选对象通常是 超过 request 的 Pod；
Guaranteed（各容器 request=limit 且都 >0 的经典条件）最不容易被驱逐，但 不等于永远不被 OOM：一旦超过自己的 memory limit，仍可能 OOMKilled。

一个可复现的排查入口：

kubectl describe pod <pod> | sed -n '/Last State/,/Events/p'
# 常见：Reason: OOMKilled, Exit Code: 137

五、可复现观测：别等 dmesg 再救火

1. 先确认 cgroup v2 与容器路径

# 多数现代发行版默认 cgroup v2 统一层级
mount | grep cgroup
stat -fc %T /sys/fs/cgroup

# 看某个进程属于哪个 cgroup
pidof java | head -n1 | xargs -I{} cat /proc/{}/cgroup

2. 读 memory 接口（容器内或宿主机 cgroup 路径）

CG=/sys/fs/cgroup # 或容器对应的子路径，如 /sys/fs/cgroup/system.slice/docker-<id>.scope

cat $CG/memory.current
cat $CG/memory.max
cat $CG/memory.high
cat $CG/memory.peak
cat $CG/memory.events
# 关注：high / max / oom / oom_kill 是否持续上涨

解释事件：

`memory.events` 字段	含义（工程视角）
`high`	触碰 high 边界，被节流/强制回收的次数
`max`	用量几乎要越过 max；若 direct reclaim 失败，将进入 OOM 状态
`oom`	已到 limit，分配即将失败
`oom_kill`	实际发生了 OOM kill

3. 看谁更容易被杀

# 分数越高越危险
ps -eo pid,user,comm,rss,oom_score,oom_score_adj --sort=-oom_score | head

# 某个关键守护进程是否被错误保护/错误牺牲
cat /proc/$(pidof dockerd)/oom_score_adj

4. 对照内核日志

dmesg -T | egrep -i 'out of memory|killed process|oom'
journalctl -k -b --no-pager | egrep -i 'out of memory|killed process'

若 oom_dump_tasks=1（默认），日志里通常能看到候选任务的 rss、oom_score_adj 等信息，用来回答“为什么杀的是 A 不是 B”。

六、常见坑与排查清单

坑 1：只设 request，不设 limit

调度时“看起来能放下”，运行时可以吃爆节点；最终变成 节点级压力 + 驱逐/全局 OOM，故障面比单容器 OOM 更大。

坑 2：limit 设太紧，没有 `high` 缓冲与观测

应用启动峰值、JVM 堆外、page cache、临时解压都可能把 current 顶到 max。
结果是频繁 OOMKilled 重启，而不是平滑降速。优先补：

真实峰值观测（memory.peak、容器监控）；
合理 limit；
能用 high 水位告警就不要只用死亡事件告警。

坑 3：把 `oom_score_adj=-1000` 到处贴

保护数据库/核心 agent 合理；若把内存泄漏服务也保护起来，OOM killer 只能去杀更无辜的进程，整机稳定性更差。

坑 4：`--oom-kill-disable` 却没有硬上限

Docker 文档明确警告：关 OOM killer 时必须配合 -m。否则容器可把宿主内存吃穿。

坑 5：混淆“kubelet 驱逐”与“cgroup OOM”

现象	更像
Pod 事件里有 eviction、磁盘/内存 pressure	kubelet 驱逐
Container `Last State: OOMKilled` / exit 137	cgroup/内核 OOM
宿主 `dmesg` 出现 Killed process，且受害进程不一定是容器	全局 OOM 或选中了别的任务

坑 6：用错“内存用量”口径

RSS、cgroup memory.current、容器运行时 working set、JVM heap used 不是同一个数。
排 OOM 时以 cgroup 记账 + kernel 日志 为准，再用进程级工具交叉验证。

七、一套可执行的生产建议

每个有状态/高风险服务都要有 memory limit，并基于压测峰值留 20%–40% 余量（按语言运行时特性调整）。
优先监控 memory.events 与 working set 趋势，把 high/max 当预警，把 oom_kill 当事故。
K8s 上让关键链路尽量 Guaranteed 或至少 request≈实际稳态；limit 不要拍脑袋抄 CPU 倍数。
保护面要窄：-1000 只给真正的系统关键路径；业务进程靠 limit 与弹性，而不是全局免死金牌。
复盘时固定三件套：memory.current/max/events + oom_score(_adj) + dmesg/journal。
不要默认改 panic_on_oom / oom_kill_allocating_task，除非你清楚故障域与取证目标。

八、总结

cgroup v2 用 min/low/high/max 把内存控制从“一刀切 hard cap”扩展成“保护 + 节流 + 硬顶”。
high 负责让系统先变慢并回收；max 才是 OOM 悬崖。
OOM killer 按 badness/oom_score_adj 选人；cgroup OOM 默认 杀在组内，memory.oom.group 可改变是否整组同生共死。
Docker 的 -m、K8s 的 limits.memory 最终都落到内核 cgroup；CPU 超限多半被节流，内存超限更可能被杀。
可观测性的关键不是“死了没有”，而是 memory.events 是否在反复逼近上限。

把内存限制当成“开关”只会得到随机的 137；把它当成“阶梯 + 评分 + 事件流”，才能在容器化环境里稳定控风险。

参考资料

Linux Kernel Docs — Control Group v2（memory.current / min / low / high / max / oom.group / events）: https://docs.kernel.org/admin-guide/cgroup-v2.html
Linux Kernel Docs — Documentation for /proc/sys/vm/（oom_dump_tasks、oom_kill_allocating_task、panic_on_oom、overcommit_memory、swappiness）: https://docs.kernel.org/admin-guide/sysctl/vm.html
man-pages — proc_pid_oom_score(5): https://man7.org/linux/man-pages/man5/proc_pid_oom_score.5.html
man-pages — proc_pid_oom_score_adj(5): https://man7.org/linux/man-pages/man5/proc_pid_oom_score_adj.5.html
Docker Docs — Resource constraints（memory options、OOME、--oom-kill-disable）: https://docs.docker.com/engine/containers/resource_constraints/
Kubernetes Docs — Resource Management for Pods and Containers: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/
Kubernetes Docs — Pod Quality of Service Classes: https://kubernetes.io/docs/concepts/workloads/pods/pod-qos/

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/

Debian12 安装Docker及Docker-compose

Sun, 17 Dec 2023 18:10:00 +0800

在 Debian 12 上安装最新版的 Docker 和 Docker Compose 可以按照以下步骤进行。以下指南将带您通过安装 Docker Engine、配置 Docker 官方仓库以及安装 Docker Compose 的最新版本。

一、更新系统

首先，确保您的系统包索引是最新的，并安装必要的依赖包。

sudo apt update
sudo apt upgrade -y
sudo apt install -y ca-certificates curl gnupg lsb-release

二、添加 Docker 官方的 GPG 密钥

为了确保下载的软件包的安全性，需要添加 Docker 的官方 GPG 密钥。

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

三、设置 Docker 仓库

将 Docker 的官方仓库添加到 APT 源中。

echo "deb [arch=&#36;(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian &#36;(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

四、安装 Docker Engine、Docker CLI 和 containerd

首先，更新包索引，然后安装 Docker Engine 及其组件。

sudo apt update

sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

注意：docker-compose-plugin 是 Docker 官方提供的 Compose 插件，可以作为 Docker CLI 的一部分使用。如果您需要独立的 Docker Compose，可参考后续步骤。

五、启动并启用 Docker 服务

确保 Docker 服务已启动并设置为开机自启。

sudo systemctl start docker

sudo systemctl enable docker

六、验证 Docker 安装

通过运行一个测试容器来验证 Docker 是否正确安装。

sudo docker run hello-world

如果看到类似 “Hello from Docker!” 的输出，说明 Docker 已成功安装。

七、安装 Docker Compose 最新版

虽然前面的步骤已经安装了 docker-compose-plugin，您可能仍然希望安装独立的 Docker Compose，以便使用 docker-compose 命令。以下是安装最新版 Docker Compose 的步骤：

获取最新的 Docker Compose 版本号

访问 Docker Compose 的 GitHub 发布页面获取最新版本号。例如，假设最新版本是 v2.20.2。

下载 Docker Compose 二进制文件

使用 curl 下载适用于 Linux 的 Docker Compose 二进制文件，并将其移动到 /usr/local/bin 目录。

DOCKER_COMPOSE_VERSION=&#36;(curl -s https://api.github.com/repos/docker/compose/releases/latest | grep tag_name | cut -d '"' -f 4)

sudo curl -L "https://github.com/docker/compose/releases/download/&#36;{DOCKER_COMPOSE_VERSION}/docker-compose-&#36;(uname -s)-&#36;(uname -m)" -o /usr/local/bin/docker-compose

赋予可执行权限

sudo chmod +x /usr/local/bin/docker-compose

创建符号链接（可选）

为了便于使用 docker-compose 命令，可以创建一个符号链接到 /usr/bin。

sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

验证 Docker Compose 安装

docker-compose --version

您应该会看到类似 docker-compose version 2.20.2, build … 的输出，确认安装成功。

八、配置当前用户使用 Docker（可选）

为了避免每次运行 Docker 命令时都需要使用 sudo，可以将当前用户添加到 docker 组中。

sudo usermod -aG docker &#36;USER

注意：执行上述命令后，您需要重新登录才能使组更改生效。

九、测试无 sudo 的 Docker 命令

重新登录后，运行以下命令以确认是否可以不使用 sudo 运行 Docker 命令：

docker run hello-world

如果看到 “Hello from 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（强制“不能随意横穿”）

四、常见坑与排查清单

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

六、总结

参考资料

Linux cgroup v2 内存控制与 OOM Killer：原理、观测与容器化实践

一、先建立两层模型：全局 OOM vs cgroup OOM

二、cgroup v2 的内存阶梯：min / low / high / max

1. 为什么要有 high，而不是只设 max？

2. min/low 保护不是免费的

三、OOM Killer：它到底怎么选人

1. 评分：oom_score 与 oom_score_adj

2. 系统级可调旋钮（/proc/sys/vm/*）

3. cgroup 内 OOM 的边界

四、工程映射：Docker 与 Kubernetes

1. Docker：把 limit 落到 cgroup

2. Kubernetes：request / limit / QoS / 驱逐

五、可复现观测：别等 dmesg 再救火

1. 先确认 cgroup v2 与容器路径

2. 读 memory 接口（容器内或宿主机 cgroup 路径）

3. 看谁更容易被杀

4. 对照内核日志

六、常见坑与排查清单

坑 1：只设 request，不设 limit

坑 2：limit 设太紧，没有 high 缓冲与观测

坑 3：把 oom_score_adj=-1000 到处贴

坑 4：--oom-kill-disable 却没有硬上限

坑 5：混淆“kubelet 驱逐”与“cgroup OOM”

坑 6：用错“内存用量”口径

七、一套可执行的生产建议

八、总结

参考资料

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

版本与来源核验

pre_start 到底解决什么问题

一个最小可用示例

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

适合落地的场景

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

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

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

升级与验证建议

注意事项

总结

参考资料

Debian12 安装Docker及Docker-compose

2.4 嵌入式 DNS：`127.0.0.11`

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

1. 为什么要有 `high`，而不是只设 `max`？

2. `min`/`low` 保护不是免费的

1. 评分：`oom_score` 与 `oom_score_adj`

2. 系统级可调旋钮（`/proc/sys/vm/*`）

坑 2：limit 设太紧，没有 `high` 缓冲与观测

坑 3：把 `oom_score_adj=-1000` 到处贴

坑 4：`--oom-kill-disable` 却没有硬上限