在生产环境中，Docker 容器如果没有设置内存边界，可能持续占用宿主机资源，最终触发 Linux OOM 机制，导致容器进程甚至关键系统进程被终止。合理配置内存与 Swap，不只是限制资源用量，更是保障服务稳定性的基础。本文将介绍常用参数、配置示例，以及 Swap 不生效时的系统化排查方法。🧭
一、理解 Docker 的内存限制机制
Docker 本身并不直接管理物理内存，而是通过 Linux cgroup 将资源限制交给内核执行。未设置限制时，容器原则上可以使用宿主机允许分配的全部内存。可参考 Docker 资源约束官方文档。
--memory，简写为 -m，用于设置容器能够使用的内存硬上限。例如，执行 docker run -d --name web -m 512m nginx，表示 web 容器最多使用 512 MB 内存。达到上限后，内核会尝试回收内存；如果仍无法满足分配请求，容器内的进程可能被 OOM Killer 终止。
--memory-reservation 用于设置软限制。它通常应低于硬限制，当宿主机出现内存竞争时，内核会依据该值回收资源。例如：docker run -d -m 1g --memory-reservation 768m nginx。软限制并不等于容器在任何情况下都只能使用 768 MB。
二、正确理解 --memory-swap
--memory-swap 表示容器可使用的“内存加 Swap”总量，而不是单独的 Swap 容量。例如同时设置 --memory 512m --memory-swap 1g，容器最多可使用 512 MB 内存，并可额外使用约 512 MB Swap。这个概念最容易被误解。⚠️
- --memory-swap 与 --memory 相等：容器不能使用 Swap。例如两者都为 512m。
- --memory-swap 大于 --memory：两者之差是容器可使用的最大 Swap 空间。
- --memory-swap 设置为 -1：在内核与宿主机配置允许的前提下，容器可使用宿主机上的可用 Swap。
- 只设置 --memory：Docker 通常会将内存与 Swap 总量设置为内存限制的两倍，但实际效果仍取决于宿主机、cgroup 版本及运行环境。
- --memory-swap 设置为 0：其效果通常与未设置该参数相同，不代表禁用 Swap。
如果需要明确禁止容器使用 Swap，可将两个参数设置为相同值，例如：docker run -d --memory 512m --memory-swap 512m nginx。对于数据库、低延迟接口等对响应时间敏感的服务，这种方式可以避免频繁换页造成明显抖动，但必须预留充足内存。
三、Docker Compose 配置注意事项
使用 Compose 时，应先确认当前 Compose 版本及部署模式支持哪些资源字段。普通 Compose 场景可在服务中配置 mem_limit: 512m 和 memswap_limit: 1g。如果使用 Swarm，则通常在 deploy.resources.limits.memory 中声明内存限制，但 deploy 字段在非 Swarm 模式下的处理方式可能不同。
修改配置后应重新创建容器，而不是只重启旧容器。可以执行 docker compose up -d --force-recreate，随后通过 docker inspect 容器名 检查 HostConfig 中的 Memory 和 MemorySwap，确认参数已经写入容器配置。🔍
四、Swap 不生效的常见原因
1. 宿主机没有启用交换空间
容器不能凭空创建可用的 Swap。先在宿主机执行 swapon --show 和 free -h。如果没有任何交换分区或交换文件，即使设置了 --memory-swap，容器也无法使用 Swap。需要按照操作系统规范创建交换文件或启用交换分区，并妥善配置开机挂载。
2. 内核或 cgroup 未启用 Swap 控制
执行 docker info，检查是否出现 WARNING: No swap limit support。出现该提示，通常说明当前内核、启动参数或 cgroup 控制器没有提供 Docker 所需的 Swap 限制能力。此时需要根据发行版文档调整内核启动配置，而不是反复修改 docker run 参数。
3. 混淆 cgroup v1 与 v2 的指标文件
不同 cgroup 版本的检查路径不同。可执行 stat -fc %T /sys/fs/cgroup 判断环境：输出 cgroup2fs 通常表示 cgroup v2。v2 常见文件包括 memory.max、memory.swap.max、memory.current 和 memory.swap.current；v1 则常见 memory.limit_in_bytes、memory.memsw.limit_in_bytes 等文件。
4. 测试负载没有形成真正的内存压力
Linux 会优先回收文件页缓存，并不保证内存刚接近上限就立即换出匿名页。因此，“没有观察到 Swap 增长”不一定表示限制失效。测试时应持续观察 docker stats、free -h、vmstat 1 以及相应 cgroup 指标，避免只依据某一次瞬时结果下结论。
5. swappiness 策略影响换出倾向
--memory-swappiness 用于影响容器匿名内存页的换出倾向，有效范围通常为 0 至 100。较低的值表示尽量减少换出，较高的值表示允许更积极地使用 Swap。它影响的是换出策略，而不是增加 Swap 配额；如果宿主机没有 Swap，调整该参数不会产生可用交换空间。
五、推荐的排查顺序
- 执行 free -h 与 swapon --show，确认宿主机确实存在可用 Swap。
- 执行 docker info，确认没有 Swap 限制能力警告。
- 通过 docker inspect 核对 Memory、MemorySwap 等实际配置值。
- 识别 cgroup v1 或 v2，并读取对应的内存与 Swap 指标文件。
- 使用可控测试负载逐步增加内存占用，同时观察 Swap、OOM 事件和容器退出状态。
- 若容器异常退出，执行 docker inspect --format '{{.State.OOMKilled}}' 容器名，并结合 dmesg 或系统日志判断是否发生 OOM Kill。
不要把 Swap 当作物理内存的等价替代品。Swap 能为短时内存峰值提供缓冲，但磁盘或固态存储的访问延迟通常高于内存，持续依赖 Swap 可能让服务表现为“没有崩溃，但响应越来越慢”。
总结
Docker 内存与 Swap 配置的关键，是分清 --memory 代表内存硬限制，而 --memory-swap 代表内存与 Swap 的总上限。当交换空间不生效时，应依次检查宿主机 Swap、内核能力、cgroup 版本、容器实际参数和测试方法。生产环境中建议先通过压力测试确定合理边界，再配合监控与告警持续观察 OOM、内存回收和 Swap 活动，从而在资源利用率与服务稳定性之间取得平衡。✅
