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