When to Use
Use when the task involves Docker, Dockerfiles, container builds, Compose, image publishing, networking, volumes, logs, debugging, or production container operations. This skill is stateless and should be applied directly whenever Docker work appears.
Quick Reference
| Topic | File |
|---|
| Essential commands | INLINECODE0 |
| Dockerfile patterns |
images.md |
| Compose orchestration |
compose.md |
| Networking & volumes |
infrastructure.md |
| Security hardening |
security.md |
Core Rules
1. Pin Image Versions
- -
python:3.11.5-slim not INLINECODE6 - Today's latest differs from tomorrow's — breaks immutable builds
2. Combine RUN Commands
- -
apt-get update && apt-get install -y pkg in ONE layer - Separate layers = stale package cache weeks later
3. Non-Root by Default
- - Add
USER nonroot in Dockerfile - Running as root fails security scans and platform policies
4. Set Resource Limits
- -
-m 512m on every container - OOM killer strikes without warning otherwise
5. Configure Log Rotation
- - Default json-file driver has no size limit
- One chatty container fills disk and crashes host
Image Traps
- - Multi-stage builds: forgotten
--from=builder copies from wrong stage silently - COPY before RUN invalidates cache on every file change — copy requirements first, install, then copy code
- INLINECODE11 extracts archives automatically — use
COPY unless you need extraction - Build args visible in image history — never use for secrets
Runtime Traps
- -
localhost inside container is container's localhost — bind to INLINECODE14 - Port already in use: previous container still stopping — wait or force remove
- Exit code 137 = OOM killed, 139 = segfault — check with INLINECODE15
- No shell in distroless images —
docker cp files out or use debug sidecar
Networking Traps
- - Container DNS only works on custom networks — default bridge can't resolve names
- Published ports bind to
0.0.0.0 — use 127.0.0.1:5432:5432 for local-only - Zombie connections from killed containers — set health checks and restart policies
Compose Traps
- -
depends_on waits for container start, not service ready — use INLINECODE20 - INLINECODE21 file in wrong directory silently ignored — must be next to docker-compose.yml
- Volume mounts overwrite container files — empty host dir = empty container dir
- YAML anchors don't work across files — use multiple compose files instead
Volume Traps
- - Anonymous volumes accumulate silently — use named volumes
- Bind mounts have permission issues — container user must match host user
- INLINECODE22 doesn't remove named volumes — add
--volumes flag - Stopped container data persists until container removed
Resource Leaks
- - Dangling images grow unbounded —
docker image prune regularly - Build cache grows forever —
docker builder prune reclaims space - Stopped containers consume disk —
docker container prune or --rm on run - Networks pile up from compose projects — INLINECODE28
Secrets and Security
- - ENV and COPY bake secrets into layer history permanently — use secrets mount or runtime env
- INLINECODE29 disables all security — almost never needed, find specific capability instead
- Images from unknown registries may be malicious — verify sources
- Build args visible in image history — don't use for secrets
Debugging
- - Exit code 137 = OOM killed, 139 = segfault — check INLINECODE30
- Container won't start: check logs even for failed containers — INLINECODE31
- No shell in distroless images —
docker cp files out or use debug sidecar - Inspect filesystem of dead container — INLINECODE33
Related Skills
Install with
clawhub install <slug> if user confirms:
- -
devops — deployment pipelines - INLINECODE36 — host system management
- INLINECODE37 — server administration
Feedback
- - If useful: INLINECODE38
- Stay updated: INLINECODE39
何时使用
当任务涉及Docker、Dockerfile、容器构建、Compose、镜像发布、网络、卷、日志、调试或生产环境容器操作时使用。此技能为无状态技能,一旦出现Docker相关工作即可直接应用。
快速参考
| 主题 | 文件 |
|---|
| 基础命令 | commands.md |
| Dockerfile模式 |
images.md |
| Compose编排 | compose.md |
| 网络与卷 | infrastructure.md |
| 安全加固 | security.md |
核心规则
1. 固定镜像版本
- - 使用 python:3.11.5-slim 而非 python:latest
- 今天的latest版本与明天的不同——会破坏不可变构建
2. 合并RUN命令
- - 在单个层中执行 apt-get update && apt-get install -y pkg
- 分离的层会导致数周后出现过时的包缓存
3. 默认使用非root用户
- - 在Dockerfile中添加 USER nonroot
- 以root身份运行会导致安全扫描和平台策略失败
4. 设置资源限制
- - 每个容器添加 -m 512m
- 否则OOM killer会在无预警的情况下触发
5. 配置日志轮转
- - 默认的json-file驱动没有大小限制
- 一个话多的容器会填满磁盘并导致主机崩溃
镜像陷阱
- - 多阶段构建:忘记 --from=builder 会静默地从错误阶段复制内容
- COPY在RUN之前执行,每次文件变更都会使缓存失效——先复制依赖文件,安装,再复制代码
- ADD 会自动解压归档文件——除非需要解压,否则使用 COPY
- 构建参数在镜像历史中可见——切勿用于机密信息
运行时陷阱
- - 容器内的 localhost 是容器的本地主机——应绑定到 0.0.0.0
- 端口已被占用:前一个容器仍在停止中——等待或强制移除
- 退出码137 = OOM被杀死,139 = 段错误——使用 docker inspect --format={{.State.ExitCode}} 检查
- distroless镜像中没有shell——使用 docker cp 导出文件或使用调试sidecar
网络陷阱
- - 容器DNS仅在自定义网络上工作——默认桥接网络无法解析名称
- 已发布的端口绑定到 0.0.0.0——使用 127.0.0.1:5432:5432 实现仅本地访问
- 被杀死容器的僵尸连接——设置健康检查和重启策略
Compose陷阱
- - dependson 等待容器启动,而非服务就绪——使用 condition: servicehealthy
- 位于错误目录的 .env 文件会被静默忽略——必须与docker-compose.yml在同一目录
- 卷挂载会覆盖容器文件——空的主机目录 = 空的容器目录
- YAML锚点不能跨文件使用——改用多个compose文件
卷陷阱
- - 匿名卷会静默累积——使用命名卷
- 绑定挂载存在权限问题——容器用户必须与主机用户匹配
- docker system prune 不会移除命名卷——添加 --volumes 标志
- 已停止容器的数据会持续存在,直到容器被移除
资源泄漏
- - 悬空镜像无限增长——定期执行 docker image prune
- 构建缓存永远增长——docker builder prune 回收空间
- 已停止的容器占用磁盘——docker container prune 或在运行时使用 --rm
- 来自compose项目的网络堆积——docker network prune
机密与安全
- - ENV和COPY会将机密信息永久嵌入层历史——使用机密挂载或运行时环境变量
- --privileged 禁用所有安全措施——几乎不需要,应寻找特定能力
- 来自未知仓库的镜像可能是恶意的——验证来源
- 构建参数在镜像历史中可见——不要用于机密信息
调试
- - 退出码137 = OOM被杀死,139 = 段错误——检查 docker inspect --format={{.State.ExitCode}}
- 容器无法启动:即使对于失败的容器也要检查日志——docker logs
- distroless镜像中没有shell——使用 docker cp 导出文件或使用调试sidecar
- 检查已死亡容器的文件系统——docker cp deadcontainer:/path ./local
相关技能
如果用户确认,使用 clawhub install
安装:
- - devops — 部署流水线
- linux — 主机系统管理
- server — 服务器管理
反馈
- - 如果有用:clawhub star docker
- 保持更新:clawhub sync