# Docker 常用命令速查

## 1. 镜像（Image）操作

### 基础命令

| 命令 | 作用 | 例子 |
|------|------|------|
| `docker pull` | 从仓库拉取镜像 | `docker pull nginx:latest` |
| `docker images` | 列出本地镜像 | `docker images` / `docker images --no-trunc` |
| `docker search` | 搜索镜像（官方仓库） | `docker search nginx` |
| `docker build` | 从 Dockerfile 构建镜像 | `docker build -t myapp:1.0 .` |
| `docker tag` | 给镜像打标签 | `docker tag myapp:1.0 myrepo/myapp:1.0` |
| `docker rmi` | 删除镜像 | `docker rmi myapp:1.0` / `docker rmi -f $(docker images -q)` |
| `docker inspect` | 查看镜像详细信息 | `docker inspect nginx:latest` |
| `docker save` | 导出镜像为 tar 文件 | `docker save -o nginx.tar nginx:latest` |
| `docker load` | 从 tar 文件导入镜像 | `docker load -i nginx.tar` |

### build 常用参数

```bash
docker build \
  -t myapp:1.0 \              # 镜像名:标签
  -f Dockerfile.prod \        # 指定 Dockerfile 路径（默认 ./Dockerfile）
  --build-arg VERSION=1.0 \   # 传递构建参数（对应 ARG 指令）
  --no-cache \                # 跳过缓存，全量重新构建
  .                           # 构建上下文（通常是当前目录）
```

### Dockerfile 关键指令

| 指令 | 作用与区别 | 注意 |
|------|---------|------|
| `FROM` | 基础镜像（第一行） | 不能省略。如 `FROM ubuntu:20.04` 或 `FROM scratch`（空镜像） |
| `WORKDIR` | 设置容器工作目录 | 不存在时自动创建。RUN/CMD 等指令在此目录执行。多次写会累加路径 |
| `RUN` | 执行 shell 命令（构建时） | 每条 RUN 产生新的镜像层。合并多条命令减少层数：`RUN apt-get update && apt-get install -y xxx` |
| `COPY` | 复制本地文件/目录到镜像 | 比 ADD 更明确，优先用。路径相对于构建上下文 |
| `ADD` | 复制文件，支持远程 URL 和自动解压 tar | 一般不用（除非需要自动解压）。远程 URL 应用 `RUN wget` 代替 |
| `ENV` | 设置环境变量 | `ENV KEY=value` 或 `ENV KEY1=val1 KEY2=val2`。容器内可用，构建时后续行也可用 |
| `ARG` | 构建参数（仅构建时可用） | `ARG VERSION=1.0`。`docker build --build-arg VERSION=2.0` 覆盖。容器内不可用 |
| `CMD` | 容器默认启动命令 | 仅最后一条生效。可被 `docker run` 的命令行覆盖。推荐 JSON 数组形式：`CMD ["python", "app.py"]` |
| `ENTRYPOINT` | 容器启动入口点 | 不易被覆盖（需 `--entrypoint` 强制）。与 CMD 搭配：ENTRYPOINT 是主程序，CMD 是默认参数 |
| `EXPOSE` | 声明容器监听端口 | 仅文档作用，不做端口映射。映射还需 `docker run -p` |
| `VOLUME` | 声明数据卷挂载点 | `VOLUME ["/data"]`。仅标记用，真正挂载需 `docker run -v` |
| `USER` | 指定运行用户 | 默认 root。安全起见，非 root 用户应存在：`RUN useradd -m appuser && USER appuser` |
| `LABEL` | 添加元数据标签 | `LABEL version="1.0" maintainer="xxx@example.com"`。`docker inspect` 可查 |

### 常见坑

- **ENV vs ARG**：ENV 在构建和容器运行时都可用；ARG 仅构建时有效。容器内看不到 ARG。
- **CMD vs ENTRYPOINT**：`CMD ["sh", "-c", "python app.py"]` 是 shell 形式（建议用数组形式避免 shell 解析坑）；ENTRYPOINT 通常配 CMD：`ENTRYPOINT ["python"]` + `CMD ["app.py"]` 这样 `docker run myapp --debug` 会变成 `python --debug`。
- **RUN 缓存**：如果构建上下文没变，RUN 会用缓存。改代码后第一次 build 要 `--no-cache` 重建。
- **COPY vs ADD**：一般只用 COPY。ADD 自动解压 tar 可能不符合预期。

---

## 2. 容器（Container）操作

### 基础命令

| 命令 | 作用 | 例子 |
|------|------|------|
| `docker run` | 创建并启动容器 | `docker run -d -p 8080:80 nginx` |
| `docker ps` | 列出运行中的容器 | `docker ps` / `docker ps -a`（全部） |
| `docker logs` | 查看容器日志 | `docker logs myapp` / `docker logs -f myapp`（跟踪） |
| `docker exec` | 在运行中容器执行命令 | `docker exec -it myapp bash` |
| `docker stop` | 优雅停止容器 | `docker stop myapp` |
| `docker start` | 启动已停止的容器 | `docker start myapp` |
| `docker restart` | 重启容器 | `docker restart myapp` |
| `docker rm` | 删除容器 | `docker rm myapp` / `docker rm -f myapp`（强制） |
| `docker inspect` | 查看容器详细信息 | `docker inspect myapp` |
| `docker stats` | 实时查看容器资源占用 | `docker stats myapp` / `docker stats --no-stream`（单次） |
| `docker top` | 查看容器内运行的进程 | `docker top myapp` |
| `docker cp` | 在主机与容器间复制文件 | `docker cp myapp:/data/file.txt ./` / `docker cp ./file.txt myapp:/data/` |
| `docker diff` | 查看容器文件系统变化 | `docker diff myapp` |

### docker run 常用参数详解

```bash
docker run \
  -d \                                    # detach，后台运行
  --name myapp \                          # 容器名称
  -p 8080:80 \                            # 端口映射：主机:容器（-p 8080:80/udp 指定协议）
  -v /host/data:/container/data \        # 数据卷挂载：绑定挂载（bind mount）
  -v named-volume:/data \                 # 使用命名卷
  -e ENV_VAR=value \                      # 环境变量
  -e ENV_FROM_FILE \                      # 从 --env-file 读取
  --rm \                                  # 容器停止后自动删除
  --network mynet \                       # 指定网络
  -w /app \                               # 工作目录（覆盖 WORKDIR）
  --restart=always \                      # 重启策略（no/always/unless-stopped/on-failure:3）
  -u appuser \                            # 运行用户（覆盖 USER）
  --privileged \                          # 以特权模式运行（危险！给容器完整宿主权限）
  --cap-add=NET_ADMIN \                   # 添加特定 Linux 能力
  -m 512m \                               # 内存限制
  --cpus=1 \                              # CPU 数限制
  --memory-swap=1g \                      # 内存+交换区限制
  nginx:latest                            # 镜像:标签
```

### logs 常用参数

```bash
docker logs \
  -f \                    # follow，持续输出
  -n 100 \                # 显示最后 N 行
  --tail=50 \             # 等价于 -n 50
  --timestamps \          # 显示时间戳
  --since 2024-01-01 \    # 显示时间戳之后的日志
  --until 2024-01-02 \    # 显示时间戳之前的日志
  myapp
```

### exec 常用

```bash
docker exec -it myapp bash              # 进入容器交互式 bash
docker exec -u root myapp whoami        # 以 root 用户执行
docker exec myapp ps aux                # 查看容器内进程（不交互）
```

---

## 3. 数据卷与网络

### 数据卷（Volume）

| 类型 | 命令 | 区别与应用 |
|------|------|----------|
| **绑定挂载** (bind mount) | `docker run -v /host/path:/container/path myapp` | 直接挂载宿主目录。同步双向，修改立即可见。用于开发阶段代码热更新 |
| **命名卷** (named volume) | `docker volume create mydata` <br> `docker run -v mydata:/data myapp` | Docker 管理的卷。数据存储位置由 Docker 控制（`/var/lib/docker/volumes/`）。生产推荐 |
| **匿名卷** | `docker run -v /data myapp` | 不指定名称。Docker 自动生成 UUID 作卷名。难以管理，不推荐 |

### 卷操作命令

```bash
docker volume create mydata                    # 创建命名卷
docker volume ls                               # 列出所有卷
docker volume inspect mydata                   # 查看卷详细信息（路径等）
docker volume prune                            # 删除未被使用的卷
docker volume rm mydata                        # 删除指定卷
docker run -v mydata:/data --mount type=volume,source=mydata,target=/data myapp  # --mount 方式
```

### 网络（Network）

```bash
docker network create mynet                    # 创建自定义网络（bridge 类型）
docker network ls                              # 列出所有网络
docker network inspect mynet                   # 查看网络详情（关联容器等）
docker network connect mynet container1        # 容器连接网络（容器运行中）
docker network disconnect mynet container1     # 容器断开网络
docker network prune                           # 删除未被使用的网络
docker network rm mynet                        # 删除指定网络

# 启动容器加入网络
docker run -d --name app --network mynet nginx
```

### 网络模式

| 模式 | 用途 | 命令 |
|------|------|------|
| bridge（默认） | 容器间通过网络通信 | `docker run -d nginx`（自动 bridge） |
| host | 容器共享宿主网络栈，性能最好 | `docker run --network host nginx` |
| none | 容器无网络 | `docker run --network none nginx` |
| container | 容器共享另一容器网络 | `docker run --network container:web nginx` |

**自定义 bridge 网络的好处**：容器间可用容器名 DNS 解析（而默认 bridge 网络不行），简化跨容器通信。

---

## 4. 镜像与容器清理

| 操作 | 命令 | 说明 |
|------|------|------|
| 删除未使用容器 | `docker container prune` | 删除所有停止的容器。加 `-f` 跳过确认 |
| 删除未使用镜像 | `docker image prune` | 删除未被容器引用的镜像。`-a` 删除所有不用镜像 |
| 删除未使用卷 | `docker volume prune` | 删除未被挂载的卷。**注意数据丢失！** |
| 删除未使用网络 | `docker network prune` | 删除未被使用的网络 |
| 一键清理（谨慎） | `docker system prune` | 清理容器、镜像、卷、网络。`-a` 更激进。**确保不需要数据后再用！** |
| 查看磁盘占用 | `docker system df` | 列出各组件占用空间 |

### 磁盘占用排查

```bash
# 查看磁盘占用概览
docker system df

# 查看各镜像大小
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

# 查看各容器大小（包括日志）
docker ps -a --format "table {{.Names}}\t{{.Size}}"

# 查看具体卷占用
du -sh /var/lib/docker/volumes/*/

# 清理容器日志（容器运行中）
docker exec myapp bash -c "truncate -s 0 /var/log/app.log"
# 或直接清理宿主日志文件
truncate -s 0 /var/lib/docker/containers/容器ID/容器ID-json.log
```

---

## 5. Docker Compose

### 常用子命令

| 命令 | 作用 | 例子 |
|------|------|------|
| `docker compose up` | 启动所有服务 | `docker compose up -d` / `docker compose up --build` |
| `docker compose down` | 停止并删除服务 | `docker compose down` / `docker compose down -v`（删卷） |
| `docker compose ps` | 列出 compose 管理的容器 | `docker compose ps` |
| `docker compose logs` | 查看服务日志 | `docker compose logs -f web` |
| `docker compose exec` | 在服务容器执行命令 | `docker compose exec web bash` |
| `docker compose build` | 构建镜像（不启动） | `docker compose build` / `docker compose build --no-cache` |
| `docker compose pull` | 拉取镜像 | `docker compose pull` |
| `docker compose restart` | 重启服务 | `docker compose restart web` |
| `docker compose stop` | 停止服务（不删） | `docker compose stop web` |
| `docker compose start` | 启动已停止服务 | `docker compose start web` |

### compose 文件关键字段

```yaml
version: '3.9'

services:
  web:
    image: nginx:latest                         # 使用现有镜像
    # build: .                                  # 或从 Dockerfile 构建
    # build:
    #   context: .
    #   dockerfile: Dockerfile.prod
    #   args:
    #     VERSION: 1.0
    
    container_name: my-web                      # 容器名
    ports:
      - "8080:80"                               # 端口映射
      - "443:443/tcp"
    
    volumes:
      - ./data:/app/data                        # 绑定挂载
      - app-data:/data                          # 命名卷
    
    environment:                                # 环境变量
      - DATABASE_URL=postgres://db:5432/mydb
      - DEBUG=true
    # env_file: .env                            # 或从文件读取
    
    networks:
      - backend                                 # 自定义网络
    
    depends_on:
      - db                                      # 服务依赖
    
    restart: always                             # 重启策略
    
    healthcheck:                                # 健康检查
      test: ["CMD", "curl", "-f", "http://localhost/health"]
      interval: 10s
      timeout: 3s
      retries: 3
      start_period: 40s
    
    command: python app.py                      # 覆盖 CMD
    working_dir: /app                           # 工作目录
    user: appuser                               # 运行用户
    
    # 资源限制
    deploy:
      resources:
        limits:
          cpus: '1'
          memory: 512M
        reservations:
          cpus: '0.5'
          memory: 256M

  db:
    image: postgres:13
    environment:
      POSTGRES_DB: mydb
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
    volumes:
      - db-data:/var/lib/postgresql/data
    networks:
      - backend

# 定义命名卷
volumes:
  app-data:
  db-data:

# 定义网络
networks:
  backend:
    driver: bridge
```

### 常用模式

```bash
# 后台启动并查看日志
docker compose up -d && docker compose logs -f

# 完整重建（包括卷）
docker compose down -v && docker compose up -d --build

# 查看服务配置（合并后的）
docker compose config

# 验证 compose 文件格式
docker compose config --quiet

# 进入服务容器
docker compose exec web bash

# 一次性运行命令（不启动服务）
docker compose run --rm web python manage.py migrate
```

---

## 6. 排查与高频组合命令

### 快速诊断套路

```bash
# 1. 容器启动失败？查日志
docker logs myapp
docker logs myapp --tail 50 --timestamps

# 2. 进去容器看看
docker exec -it myapp bash
# 在容器内执行：ps aux, netstat -tlnp, env

# 3. 检查网络连通性
docker exec myapp curl http://service:8080/health
docker exec myapp ping db

# 4. 检查资源占用
docker stats myapp

# 5. 查看容器所有配置
docker inspect myapp | jq .

# 6. 看镜像的分层
docker history myapp:1.0
```

### 常用组合

```bash
# 构建 + 启动 + 查看日志
docker build -t myapp . && docker run -d --name myapp myapp && docker logs -f myapp

# 清理所有停止容器并查看磁盘占用
docker container prune -f && docker system df

# 修改配置后重启
docker compose down && docker compose up -d --build

# 导出容器为镜像（容器改动打包）
docker commit myapp myapp:backup

# 查找特定镜像的所有容器
docker ps -a --filter ancestor=nginx

# 批量删除镜像（危险！）
docker rmi $(docker images -q nginx)

# 实时监控多个容器日志
docker logs -f myapp1 myapp2 myapp3

# 进容器改文件后，验证改动后查看差异
docker exec myapp cat /config.json
docker diff myapp
```

### 性能排查

```bash
# 容器内可用资源（宿主总资源）
docker run alpine free -h

# 查看容器实际使用
docker stats --no-stream

# 查看容器内存峰值（需在容器停止后）
docker inspect myapp | grep -A 5 Memory

# 查看容器初始化时间
docker events --filter container=myapp --since 10m

# 检查日志大小（单个容器日志可能很大）
du -h /var/lib/docker/containers/容器ID/
```

### 网络排查

```bash
# 检查容器能否解析 DNS
docker exec myapp nslookup db

# 测试容器间连通
docker exec web curl http://db:5432

# 查看容器网络配置
docker inspect myapp --format='{{.NetworkSettings.Networks}}'

# 进入 bridge 网络的 container namespace（调试用）
docker run -it --network container:myapp nicolaka/netshoot sh

# 查看宿主网桥
ip link show | grep docker
```

---

## 7. 速查表（最常用的 10 条）

```bash
# 拉镜像
docker pull nginx

# 启动容器
docker run -d -p 8080:80 --name web nginx

# 查看日志
docker logs -f web

# 进入容器
docker exec -it web bash

# 列出容器
docker ps -a

# 构建镜像
docker build -t myapp:1.0 .

# 启动 compose
docker compose up -d

# 查看资源占用
docker stats

# 清理垃圾
docker system prune -a

# 导出镜像
docker save -o app.tar myapp:1.0 && docker load -i app.tar
```

---

**更新日期**：2026-07-11  
**用途**：快速查阅，配合官方文档深化理解。命令参数持续变化，遇到新版本时以 `docker <command> --help` 为准。