镜像管理

一、拉取与推送

docker pull — 拉取镜像

docker pull [OPTIONS] NAME[:TAG|@DIGEST]

常用参数：

参数	说明	示例
-a / --all-tags	拉取镜像的所有 tag	docker pull -a nginx
--platform	指定平台（linux/amd64、linux/arm64）	docker pull --platform linux/arm64 nginx
-q / --quiet	静默模式，减少输出	docker pull -q nginx

使用场景：

# 拉取指定版本
docker pull nginx:1.24-alpine

# 拉取时指定平台（在 ARM 机器上拉取 amd64 镜像）
docker pull --platform linux/amd64 mysql:8.0

# 拉取私有仓库镜像（需先 login）
docker pull harbor.example.com/project/myapp:1.0

常见问题：

Q：拉取慢怎么办？

A：配置镜像加速器（参考 配置/Ubuntu 下 Docker 常用配置.md），或使用 docker pull 镜像代理地址/镜像名（如 docker pull docker.1ms.run/nginx:alpine）

Q：no matching manifest 报错？

A：镜像不支持当前 CPU 架构，用 --platform 指定平台，或使用支持多架构的镜像。

---

docker push — 推送镜像

docker push [OPTIONS] NAME[:TAG]

参数：

参数	说明
--all-tags	推送镜像的所有 tag
-q / --quiet	静默模式

使用场景：

# 推送前必须先打标签（含仓库地址）
docker tag myapp:1.0 harbor.example.com/project/myapp:1.0
docker push harbor.example.com/project/myapp:1.0

# 推送所有标签
docker push --all-tags harbor.example.com/project/myapp

常见问题：

Q：denied: requested access to the resource is denied

A：未登录或用户名/仓库名错误。先 docker login，确认镜像名包含正确的 namespace。

Q：推送慢或超时？

A：检查网络，或配置 max-concurrent-uploads（参考 配置/ 目录）。

---

docker login / logout — 登录/登出仓库

docker login [OPTIONS] [SERVER]
docker logout [SERVER]

参数：

参数	说明
-u / --username	用户名
-p / --password	密码（不推荐明文）
--password-stdin	从标准输入读取密码（推荐）

使用场景：

# 交互式登录
docker login

# 非交互式（脚本/CI 推荐）
echo "$DOCKER_PASSWORD" | docker login -u "$DOCKER_USERNAME" --password-stdin

# 登录私有仓库
docker login harbor.example.com -u admin --password-stdin < password.txt

# 登出
docker logout harbor.example.com

tips：密码不要写在命令里（-p 123456），会留在 shell 历史中。用 --password-stdin 或环境变量。

---

二、查看与检查

docker images / docker image ls — 列出本地镜像

docker images [OPTIONS] [REPOSITORY[:TAG]]
docker image ls [OPTIONS] [REPOSITORY[:TAG]]

常用参数：

参数	说明	示例
-a / --all	显示所有镜像（含中间层）	docker images -a
-q / --quiet	只显示镜像 ID	docker images -q
--digests	显示摘要信息	docker images --digests
--filter	按条件过滤	docker images --filter "dangling=true"
--format	自定义输出格式	docker images --format "table {{.Repository}}\t{{.Size}}"
-f	同 --filter	docker images -f "label=version=1.0"

常用过滤器：

过滤器	说明	示例
dangling=true	虚悬镜像（<none>:<none>）	docker images -f dangling=true
label=key	包含指定标签	docker images -f "label=maintainer=admin"
before=image	在指定镜像之前创建的	docker images -f "before=nginx:1.0"
since=image	在指定镜像之后创建的	docker images -f "since=nginx:1.0"
reference=pattern	匹配名称模式	docker images -f "reference=myapp*"

使用场景：

# 列出所有镜像并按大小排序
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}" | sort -k3 -h

# 查看虚悬镜像（构建异常产生的残留）
docker images -f dangling=true

# 清理虚悬镜像
docker rmi $(docker images -f dangling=true -q)

# 查看某个仓库的所有镜像
docker images nginx

---

docker inspect — 查看镜像/容器详细信息

docker inspect [OPTIONS] NAME|ID [NAME|ID...]

参数：

参数	说明
-f / --format	使用 Go 模板格式化输出
-s / --size	显示总文件大小
--type	指定类型（image/container/network/volume）

常用场景：

# 查看镜像完整信息（JSON）
docker inspect nginx:alpine

# 查看镜像大小
docker inspect nginx:alpine --format='{{.Size}}' | numfmt --to=iec

# 查看镜像架构
docker inspect nginx:alpine --format='{{.Architecture}}'

# 查看镜像环境变量
docker inspect nginx:alpine --format='{{.Config.Env}}'

# 查看镜像暴露端口
docker inspect nginx:alpine --format='{{.Config.ExposedPorts}}'

# 查看镜像的 CMD
docker inspect nginx:alpine --format='{{.Config.Cmd}}'

# 查看镜像的 ENTRYPOINT
docker inspect nginx:alpine --format='{{.Config.Entrypoint}}'

# 查看镜像层信息
docker inspect nginx:alpine --format='{{.RootFS.Layers}}'

---

docker history — 查看构建历史

docker history [OPTIONS] IMAGE

参数：

参数	说明
-q / --quiet	只显示镜像 ID
--no-trunc	显示完整输出
-H / --human	以可读格式显示大小和时间

使用场景：

# 查看镜像构建历史（每层的大小）
docker history nginx:alpine

# 查看完整命令（不截断）
docker history --no-trunc nginx:alpine

# 只查看构建命令（排查镜像大小问题）
docker history --no-trunc nginx:alpine | head -10

---

三、构建与创建

docker build — 从 Dockerfile 构建镜像

docker build [OPTIONS] PATH | URL | -

完整参数表（按功能分组）：

路径/上下文：

参数	说明	示例
-f / --file	指定 Dockerfile 路径	docker build -f docker/Dockerfile.prod .
--build-arg	传递构建参数	docker build --build-arg VERSION=1.0 .
--target	多阶段构建指定目标阶段	docker build --target builder .

标签/命名：

参数	说明	示例
-t / --tag	镜像名:标签	docker build -t myapp:1.0 .
--label	添加标签	docker build --label version=1.0 .

缓存控制：

参数	说明	示例
--no-cache	不使用缓存	docker build --no-cache .
--cache-from	指定缓存源	docker build --cache-from myapp:latest .

输出控制：

参数	说明	示例
-q / --quiet	静默模式	docker build -q .
--progress	输出格式（auto/plain/tty）	--progress=plain

高级：

参数	说明	示例
--squash	压缩层（实验性）	docker build --squash .
--platform	指定平台	docker build --platform linux/amd64 .

使用场景：

# 基础构建
docker build -t myapp:1.0 .

# 指定 Dockerfile（非默认名称）
docker build -f Dockerfile.prod -t myapp:1.0 .

# 传递构建参数
docker build --build-arg APP_ENV=production -t myapp:1.0 .

# 多阶段构建只构建到中间阶段（调试用）
docker build --target builder -t myapp-builder:1.0 .

# 使用缓存源加速 CI 构建
docker pull myapp:latest || true
docker build --cache-from myapp:latest -t myapp:1.0 .

# 压缩镜像层（减小体积，实验性）
docker build --squash -t myapp:1.0 .

使用 .dockerignore：

在构建上下文目录创建 .dockerignore，排除不需要的文件：

# .dockerignore 示例
.git/
node_modules/
*.log
*.tmp
.env

---

docker commit — 从容器创建镜像

docker commit [OPTIONS] CONTAINER [REPOSITORY[:TAG]]

参数：

参数	说明
-a / --author	作者信息
-c / --change	应用 Dockerfile 指令
-m / --message	提交说明
-p / --pause	提交时暂停容器（默认 true）

使用场景：

# 容器内做修改后保存为镜像（临时调试用）
docker commit -m "修复配置" -a "admin" mycontainer myapp:hotfix

# 提交时修改 CMD
docker commit -c 'CMD ["python", "app.py"]' mycontainer myapp:1.0

tips：docker commit 创建的镜像无法追溯构建过程，不可复现。生产环境应使用 Dockerfile。

---

docker save / load — 镜像导出与导入

# 导出
docker save [OPTIONS] IMAGE [IMAGE...] > FILE.tar
docker save -o FILE.tar IMAGE [IMAGE...]

# 导入
docker load [OPTIONS]
docker load -i FILE.tar

参数（save）：

参数	说明
-o / --output	输出到文件（而非 stdout）

参数（load）：

参数	说明
-i / --input	从文件加载（而非 stdin）
-q / --quiet	静默模式

使用场景：

# 导出单个镜像
docker save -o nginx.tar nginx:alpine

# 导出多个镜像
docker save -o all-images.tar nginx:alpine redis:alpine mysql:8.0

# 使用 gzip 压缩导出（节省空间）
docker save myapp:1.0 | gzip > myapp.tar.gz

# 导入镜像
docker load -i nginx.tar

# 从压缩文件导入
gunzip -c myapp.tar.gz | docker load

场景技巧：

# 从一台机器迁移镜像到另一台（无网络环境）
# 源机器
docker save -o myapp.tar myapp:1.0
scp myapp.tar user@target:/tmp/

# 目标机器
docker load -i /tmp/myapp.tar

---

docker export / import — 容器导出与导入（快照）

# 导出容器快照（不含历史层）
docker export [OPTIONS] CONTAINER > FILE.tar
docker export -o FILE.tar CONTAINER

# 导入快照为镜像（单层，无历史）
docker import [OPTIONS] file|URL|- [REPOSITORY[:TAG]]

export 参数：

参数	说明
-o / --output	输出到文件

import 参数：

参数	说明
-c / --change	应用 Dockerfile 指令
-m / --message	提交说明

使用场景：

# 导出容器当前文件系统
docker export mycontainer > mycontainer.tar

# 导入为镜像
docker import mycontainer.tar myapp:snapshot

# 导入时设置 CMD
docker import -c 'CMD ["/app/start.sh"]' mycontainer.tar myapp:1.0

save 与 export 的区别：

维度	docker save	docker export
操作对象	镜像	容器
是否保留历史层	保留	不保留（单层快照）
体积	大	小
适用场景	镜像备份、迁移	容器快照、精简镜像

---

四、删除与清理

docker rmi — 删除镜像

docker rmi [OPTIONS] IMAGE [IMAGE...]
docker image rm [OPTIONS] IMAGE [IMAGE...]

参数：

参数	说明
-f / --force	强制删除（即使有容器依赖）
--no-prune	不删除未标记的父镜像

使用场景：

# 删除单个镜像
docker rmi myapp:1.0

# 删除多个镜像
docker rmi nginx:alpine redis:alpine

# 强制删除（有依赖时）
docker rmi -f myapp:1.0

# 删除所有悬空镜像
docker rmi $(docker images -f dangling=true -q)

# 删除所有镜像（危险）
docker rmi -f $(docker images -q)

常见问题：

Q：image is being used by a running container

A：有运行中的容器在使用该镜像。先 docker stop 和 docker rm 容器，或使用 -f 强制删除。

Q：image is being used by a stopped container

A：有停止的容器还在引用该镜像。删除容器或用 -f。

---

docker image prune — 清理未使用镜像

docker image prune [OPTIONS]

参数：

参数	说明
-a / --all	删除所有未使用镜像（含未被容器引用的）
-f / --force	不提示确认
--filter	过滤条件

使用场景：

# 清理虚悬镜像
docker image prune

# 清理所有未使用镜像
docker image prune -a

# 清理所有未使用镜像（不提示）
docker image prune -a -f

# 清理 24 小时前创建的未使用镜像
docker image prune -a --filter "until=24h"

---

五、标签管理

docker tag — 打标签

docker tag SOURCE_IMAGE[:TAG] TARGET_IMAGE[:TAG]

使用场景：

# 为推送准备标签（含仓库地址）
docker tag myapp:1.0 harbor.example.com/project/myapp:1.0

# 打 latest 标签
docker tag myapp:1.0 myapp:latest

# 一个镜像打多个标签
docker tag myapp:1.0 myapp:stable
docker tag myapp:1.0 myapp:v1.0.0

# 为官方镜像打私有仓库标签
docker tag nginx:alpine harbor.example.com/proxy/nginx:alpine

---

六、常见问题汇总

Q1：docker build 很慢怎么办？

1. 使用构建缓存：把变动少的指令放前面（先 COPY package.json，再 COPY .）
2. 使用 --cache-from 复用已有镜像
3. 使用 BuildKit：DOCKER_BUILDKIT=1 docker build ...

Q2：镜像体积太大怎么优化？

参考Docker 镜像优化最佳实践

Q3：docker save 和 docker export 选哪个？

• 备份/迁移镜像（保留历史）→ docker save
• 快速导出容器快照（不关心历史）→ docker export

Q4：虚悬镜像（<none>:<none>）怎么产生的？

• 构建新镜像时旧 tag 被覆盖
• docker build 中间层（使用 -a 才会显示）

清理：docker image prune

---

七、命令速查表

操作	命令
拉取镜像	docker pull <image>[:tag]
推送镜像	docker push <repo>/<image>[:tag]
登录仓库	docker login
登出仓库	docker logout
列出镜像	docker images
查看镜像详情	docker inspect <image>
查看构建历史	docker history <image>
构建镜像	docker build -t <name> .
从容器创建镜像	docker commit <container> <name>
导出镜像（含历史）	docker save -o <file>.tar <image>
导入镜像	docker load -i <file>.tar
导出容器快照	docker export <container> > <file>.tar
导入快照	docker import <file>.tar <name>
打标签	docker tag <image> <new-tag>
删除镜像	docker rmi <image>
清理未使用镜像	docker image prune -a