介绍
## When to Use
用户需要 Docker 专业知识——从构建镜像到生产部署。Agent 处理 Dockerfile、编排、网络、安全加固以及故障排查。
## 快速参考
| 主题 | 文件 | |-------|------| | Dockerfile 最佳实践 | `images.md` | | Docker Compose 模式 | `compose.md` | | 网络与卷 | `infrastructure.md` | | 安全加固 | `security.md` |
## 镜像构建陷阱
- `apt-get update` 和 `apt-get install` 放在分开的 RUN 层中 = 几周后包过时——务必合并它们 - 今天的 `python:latest` 与明天的 `python:latest` 不同——请锁定版本，如 `python:3.11.5-slim` - 多阶段构建：遗忘的 `--from=builder` 会悄无声息地从错误的阶段复制文件 - 在 RUN 之前 COPY 会在每次文件变更时使缓存失效——先复制 requirements，安装，然后再复制代码
## 运行时崩溃
- 默认日志驱动没有大小限制——一个日志量大的容器会占满磁盘并导致宿主机崩溃 - OOM killer 会毫无征兆地出击——为每个容器使用 `-m 512m` 设置内存限制 - 容器默认以 root 身份运行——添加 `USER nonroot`，否则安全扫描会失败且平台会拒绝部署 - 容器内的 `localhost` 是容器自身的 localhost，而非宿主机——绑定到 `0.0.0.0`
## 网络陷阱
- 容器 DNS 仅在自定义网络上有效——默认 bridge 网络无法解析容器名称 - 发布的端口默认绑定到 `0.0.0.0`——若仅限本地访问，请使用 `127.0.0.1:5432:5432` - 已杀死容器的僵尸连接——设置适当的健康检查和重启策略 - 端口已被占用：之前的容器仍在停止中——等待或强制删除
## Compose 陷阱
- `depends_on` 仅等待容器启动，而非服务就绪——请配合 healthcheck 使用 `condition: service_healthy` - `.env` 文件位于错误目录会被静默忽略——必须紧邻 docker-compose.yml - 卷挂载会覆盖容器内的文件——空的宿主机目录 = 空的容器目录 - YAML 锚点不跨文件工作——extends 已弃用，请使用多个 compose 文件
## 卷与数据
- Dockerfile 中 VOLUME 指令创建的匿名卷会悄然累积——请使用命名卷 - 挂载卷存在宿主机权限问题——容器用户必须匹配宿主机用户或使用 `:z` 后缀 - `docker system prune` 不会删除命名卷——必须显式添加 `-volumes` 标志 - 已停止容器的数据会一直保留，直到容器被删除——`docker rm` 会删除数据
## 资源泄漏
- 悬空镜像无限增长——定期执行 `docker image prune` - 构建缓存永久增长——`docker builder prune` 回收空间 - 已停止的容器占用磁盘——`docker container prune` 或在运行时使用 `--rm` - compose 项目产生的网络堆积——`docker network prune`
## 密钥与安全
- ENV 和 COPY 会将密钥永久烘焙进层历史中——请使用 secrets 挂载或运行时环境变量 - `--privileged` 禁用所有安全机制——几乎从不需要，请寻找具体的 capability - 来自未知注册中心的镜像可能是恶意的——请验证来源 - 构建参数在镜像历史中可见——切勿用于密钥
## 调试
- 退出代码 137 = OOM killed，139 = segfault——检查 `docker inspect --format='{{.State.ExitCode}}'` - 容器无法启动：即使对失败的容器也要检查日志——`docker logs <container>` - distroless 镜像中没有 shell——`docker cp` 复制文件出来或使用 debug sidecar - 检查已死容器的文件系统——`docker cp deadcontainer:/path ./local`