Docker 管理

管理 Docker 容器、镜像、卷、网络和 Compose 堆栈 — 包括生命周期操作、调试、清理以及 Dockerfile 优化。

技能元数据

来源	可选 — 使用 hermes skills install official/devops/docker-management 安装
路径	optional-skills/devops/docker-management
版本	1.0.0
作者	sprmn24
许可证	MIT
标签	docker, containers, devops, infrastructure, compose, images, volumes, networks, debugging

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

Docker 管理

使用标准 Docker CLI 命令管理 Docker 容器、镜像、卷、网络和 Compose 堆栈。除 Docker 本身外，无需其他依赖项。

何时使用

• 运行、停止、重启、移除或检查容器
• 构建、拉取、推送、标记或清理 Docker 镜像
• 使用 Docker Compose（多服务堆栈）
• 管理卷或网络
• 调试崩溃的容器或分析日志
• 检查 Docker 磁盘使用情况或释放空间
• 审查或优化 Dockerfile

前提条件

• 已安装并运行 Docker Engine
• 用户已添加到 docker 组（或使用 sudo）
• Docker Compose v2（包含在现代 Docker 安装中）

快速检查：

docker --version && docker compose version

快速参考

任务	命令
运行容器（后台）	docker run -d --name NAME IMAGE
停止 + 移除	docker stop NAME && docker rm NAME
查看日志（跟随）	docker logs --tail 50 -f NAME
进入容器 Shell	docker exec -it NAME /bin/sh
列出所有容器	docker ps -a
构建镜像	docker build -t TAG .
Compose 启动	docker compose up -d
Compose 停止	docker compose down
磁盘使用情况	docker system df
清理悬空资源	docker image prune && docker container prune

流程

1. 确定领域

确定请求属于哪个领域：

• 容器生命周期 → run, stop, start, restart, rm, pause/unpause
• 容器交互 → exec, cp, logs, inspect, stats
• 镜像管理 → build, pull, push, tag, rmi, save/load
• Docker Compose → up, down, ps, logs, exec, build, config
• 卷和网络 → create, inspect, rm, prune, connect
• 故障排除 → 日志分析、退出代码、资源问题

2. 容器操作

运行新容器：

# Detached service with port mapping
docker run -d --name web -p 8080:80 nginx

# With environment variables
docker run -d -e POSTGRES_PASSWORD=secret -e POSTGRES_DB=mydb --name db postgres:16

# With persistent data (named volume)
docker run -d -v pgdata:/var/lib/postgresql/data --name db postgres:16

# For development (bind mount source code)
docker run -d -v $(pwd)/src:/app/src -p 3000:3000 --name dev my-app

# Interactive debugging (auto-remove on exit)
docker run -it --rm ubuntu:22.04 /bin/bash

# With resource limits and restart policy
docker run -d --memory=512m --cpus=1.5 --restart=unless-stopped --name app my-app

关键标志：-d 分离模式，-it 交互式+tty，--rm 自动移除，-p 端口（主机:容器），-e 环境变量，-v 卷，--name 名称，--restart 重启策略。

管理运行中的容器：

docker ps                        # running containers
docker ps -a                     # all (including stopped)
docker stop NAME                 # graceful stop
docker start NAME                # start stopped container
docker restart NAME              # stop + start
docker rm NAME                   # remove stopped container
docker rm -f NAME                # force remove running container
docker container prune           # remove ALL stopped containers

与容器交互：

docker exec -it NAME /bin/sh          # shell access (use /bin/bash if available)
docker exec NAME env                   # view environment variables
docker exec -u root NAME apt update    # run as specific user
docker logs --tail 100 -f NAME         # follow last 100 lines
docker logs --since 2h NAME            # logs from last 2 hours
docker cp NAME:/path/file ./local      # copy file from container
docker cp ./file NAME:/path/           # copy file to container
docker inspect NAME                    # full container details (JSON)
docker stats --no-stream               # resource usage snapshot
docker top NAME                        # running processes

3. 镜像管理

# Build
docker build -t my-app:latest .
docker build -t my-app:prod -f Dockerfile.prod .
docker build --no-cache -t my-app .              # clean rebuild
DOCKER_BUILDKIT=1 docker build -t my-app .       # faster with BuildKit

# Pull and push
docker pull node:20-alpine
docker login ghcr.io
docker tag my-app:latest registry/my-app:v1.0
docker push registry/my-app:v1.0

# Inspect
docker images                          # list local images
docker history IMAGE                   # see layers
docker inspect IMAGE                   # full details

# Cleanup
docker image prune                     # remove dangling (untagged) images
docker image prune -a                  # remove ALL unused images (careful!)
docker image prune -a --filter "until=168h"   # unused images older than 7 days

4. Docker Compose

# Start/stop
docker compose up -d                   # start all services detached
docker compose up -d --build           # rebuild images before starting
docker compose down                    # stop and remove containers
docker compose down -v                 # also remove volumes (DESTROYS DATA)

# Monitoring
docker compose ps                      # list services
docker compose logs -f api             # follow logs for specific service
docker compose logs --tail 50          # last 50 lines all services

# Interaction
docker compose exec api /bin/sh        # shell into running service
docker compose run --rm api npm test   # one-off command (new container)
docker compose restart api             # restart specific service

# Validation
docker compose config                  # validate and view resolved config

最小化 compose.yml 示例：

services:
  api:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://user:pass@db:5432/mydb
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: mydb
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  pgdata:

5. 卷和网络

# Volumes
docker volume ls                       # list volumes
docker volume create mydata            # create named volume
docker volume inspect mydata           # details (mount point, etc.)
docker volume rm mydata                # remove (fails if in use)
docker volume prune                    # remove unused volumes

# Networks
docker network ls                      # list networks
docker network create mynet            # create bridge network
docker network inspect mynet           # details (connected containers)
docker network connect mynet NAME      # attach container to network
docker network disconnect mynet NAME   # detach container
docker network rm mynet                # remove network
docker network prune                   # remove unused networks

6. 磁盘使用和清理

在清理之前始终先进行诊断：

# Check what's using space
docker system df                       # summary
docker system df -v                    # detailed breakdown

# Targeted cleanup (safe)
docker container prune                 # stopped containers
docker image prune                     # dangling images
docker volume prune                    # unused volumes
docker network prune                   # unused networks

# Aggressive cleanup (confirm with user first!)
docker system prune                    # containers + images + networks
docker system prune -a                 # also unused images
docker system prune -a --volumes       # EVERYTHING — named volumes too

警告： 未经用户确认，切勿运行 docker system prune -a --volumes。这会删除可能包含重要数据的命名卷。

常见陷阱

问题	原因	修复方法
容器立即退出	主进程完成或崩溃	检查 docker logs NAME，尝试 docker run -it --entrypoint /bin/sh IMAGE
"port is already allocated"（端口已被占用）	另一个进程正在使用该端口	使用 docker ps 或 lsof -i :PORT 查找该进程
"no space left on device"（设备上没有剩余空间）	Docker 磁盘已满	运行 docker system df 然后进行针对性清理
无法连接到容器	应用在容器内绑定到 127.0.0.1	应用必须绑定到 0.0.0.0，检查 -p 映射
卷权限被拒绝	主机与容器之间的 UID/GID 不匹配	使用 --user $(id -u):$(id -g) 或修复权限
Compose 服务无法相互访问	网络或服务名称错误	服务使用服务名作为主机名，检查 docker compose config
构建缓存未生效	Dockerfile 中的层顺序错误	将很少变化的层放在前面（依赖项在源代码之前）
镜像过大	未使用多阶段构建，无 .dockerignore	使用多阶段构建，添加 .dockerignore

验证

在任何 Docker 操作之后，验证结果：

• 容器已启动？ → docker ps（检查状态是否为 "Up"）
• 日志正常？ → docker logs --tail 20 NAME（无错误）
• 端口可访问？ → curl -s http://localhost:PORT 或 docker port NAME
• 镜像已构建？ → docker images | grep TAG
• Compose 堆栈健康？ → docker compose ps（所有服务均为 "running" 或 "healthy"）
• 磁盘空间已释放？ → docker system df（比较前后差异）

Dockerfile 优化建议

在审查或创建 Dockerfile 时，建议进行以下改进：

1. 多阶段构建 — 将构建环境与运行时环境分离，以减小最终镜像的大小
2. 层顺序优化 — 将依赖项置于源代码之前，这样更改不会使缓存的层失效
3. 合并 RUN 命令 — 减少层数，减小镜像体积
4. 使用 .dockerignore — 排除 node_modules、.git、__pycache__ 等文件
5. 固定基础镜像版本 — 使用 node:20-alpine 而非 node:latest
6. 以非 root 用户运行 — 添加 USER 指令以提升安全性
7. 使用 slim/alpine 基础镜像 — 使用 python:3.12-slim 而非 python:3.12