Docker 镜像制作实践

0.1 确认 Docker 可用#

1
docker --version
2
docker info
3
docker images

0.2 拉取本次实验的基础镜像#

1
docker pull python:3.9-slim
2
docker pull alpine:3.7

0.3 最终的项目结构#

1
.
2
├── Dockerfile          # 镜像的"配方"
3
├── requirements.txt    # Python 依赖清单
4
├── app.py              # 业务代码
5
└── .dockerignore       # 构建上下文的"黑名单"（必备，但教程里常被忽略）

四个文件就够，这就是”最小样例”的含义 —— 没有多余的东西，但每一条指令都有存在的理由。

1.1 一句话定义#

Docker 镜像是一个轻量级、可执行的只读软件包，里面打包了运行应用所需的全部内容：

1.2 镜像 vs 容器（最容易混淆的一对）#

1.3 镜像的四个关键组件#

• 层（Layer）：不可变的文件系统层，堆叠成完整镜像
• 基础镜像（Base Image）：构建阶段继承的起点，通常已包含多层文件系统和运行配置
• 镜像配置：默认命令、环境变量、工作目录等元数据；Dockerfile 是构建配方，并非镜像必须携带的组成部分
• 镜像 ID / 标签：唯一标识与版本别名

步骤 1：编写 Dockerfile#

1
# 使用Python官方镜像作为基础镜像
2
FROM python:3.9-slim
3

4
# 设置工作目录
5
WORKDIR /app
6

7
# 复制requirements.txt文件
8
COPY requirements.txt .
9

10
# 安装依赖项
11
RUN pip install --no-cache-dir -r requirements.txt
12

13
# 复制应用程序代码
14
COPY . .
15

16
# 暴露端口
17
EXPOSE 80
18

19
# 运行应用程序
20
CMD ["python", "app.py"]

逐条指令拆解：

步骤 2：编写 requirements.txt 与 app.py#

requirements.txt：

1
Flask==2.1.0
2
Werkzeug==2.1.2

app.py：

1
from flask import Flask
2

3
app = Flask(__name__)
4

5

6
@app.route('/')
7
def hello_world():
8
    return 'Hello, World!'
9

10

11
if __name__ == '__main__':
12
    app.run(host='0.0.0.0', port=80)

步骤 3：构建镜像#

1
docker build -t my-python-app:latest .

旧式构建器的输出示意如下，ID 仅用于说明格式，并非本次实测结果。构建步骤不等于文件系统层；BuildKit 的输出格式也不同：

1
Sending build context to Docker daemon   5.12kB
2
Step 1/7 : FROM python:3.9-slim
3
 ---> a438d5c1bb1b
4
Step 2/7 : WORKDIR /app
5
 ---> Using cache
6
Step 3/7 : COPY requirements.txt .
7
 ---> 3f2a1c9e8d40
8
Step 4/7 : RUN pip install --no-cache-dir -r requirements.txt
9
 ---> Running in 7c1e2f9a5b33
10
Collecting Flask==2.1.0
11
...
12
 ---> 9b7d4e2c1a55
13
Step 5/7 : COPY . .
14
 ---> c4e8a1b72d90
15
Step 6/7 : EXPOSE 80
16
 ---> Running in 5a9c3e7b1d24
17
Step 7/7 : CMD ["python", "app.py"]
18
 ---> 8e1f6a3b9c07
19
Successfully built 8e1f6a3b9c07
20
Successfully tagged my-python-app:latest

注意 ---> Using cache —— 这就是 分层与缓存 要讲的层缓存。

步骤 4：运行容器#

1
docker run -d -p 5000:80 my-python-app:latest

-p 5000:80 的含义：宿主机 5000 端口 → 容器 80 端口。左边是宿主机，右边是容器。

验证：

1
curl localhost:5000
2
# Hello, World!
3

4
docker ps
5
# CONTAINER ID   IMAGE                  PORTS                  NAMES
6
# 3a1b2c3d4e5f   my-python-app:latest   0.0.0.0:5000->80/tcp   quirky_turing

步骤 5：Cloud Studio 里访问服务#

在 Cloud Studio 中打开端口插件，选择 5000 端口即可在浏览器里看到 Hello, World!。

3.1 命令的完整语法#

1
docker build -t your_image_name:tag -f path/to/Dockerfile .

3.2 “从哪一层开始打包” —— 两个层面，两个答案#

这个问题其实混淆了两件事，必须分开答。

① 从”文件打包”的角度：起点是 .

docker build 的位置参数确定构建上下文。旧式构建器会将过滤后的上下文打包发送给 daemon；现代默认构建器 BuildKit 支持按需传输和缓存，不能一概描述成「每次把全部文件打成 tar」。

所以：

• 打包的根 = . = 你敲命令时的当前目录
• 上下文大小 = . 下面有多少东西（这就是为什么 .dockerignore 至关重要）
• 普通本地 COPY 不能借 ../ 读取上下文外文件；不同构建器可能拒绝或规范化该路径，不能依赖它越界读取

② 从”镜像分层”的角度：起点是 FROM 的基础镜像

镜像的层由 Dockerfile 指令生成，FROM python:3.9-slim 把基础镜像的所有层整体继承过来，之后 RUN / COPY / ADD 每条新增一层。FROM 是构建阶段的起点，不代表只有一个「第 0 层」。

3.3 上下文 ≠ 镜像内容#

这是个关键区分：

• 上下文中的文件只是构建期间可访问的输入，不会自动全部进入镜像
• COPY / ADD 可复制文件，RUN 也可以生成或下载文件进入镜像层
• 构建缓存可能保留输入和中间结果，不能假设构建结束后相关内容全部消失

3.4 三种常见写法对照#

3.5 .dockerignore 必须配#

1
__pycache__/
2
*.py[cod]
3
.venv/
4
venv/
5
.git/
6
.gitignore
7
.dockerignore
8
Dockerfile
9
README.md

没有它，COPY . . 会把本地的虚拟环境（动辄几百 MB）、.git 历史、IDE 配置全塞进镜像，还会直接击穿构建缓存（见下节）。

4.1 为什么先 COPY requirements.txt 再 COPY 代码？#

这是本 Dockerfile 里最”值钱”的一行设计。看两种写法的对比：

写法 A（教程的写法，正确）

1
COPY requirements.txt .
2
RUN pip install -r requirements.txt
3
COPY . .

改 app.py 时：requirements.txt 没变 → 前两层命中缓存 → 跳过 pip install，构建秒级完成。

写法 B（反例）

1
COPY . .
2
RUN pip install -r requirements.txt

改任何一个文件 → COPY . . 那一层的校验和变了 → 后面所有层缓存全部失效 → 每次都重装全部依赖，改一行代码等三分钟。

4.2 层是共享的，不是复制的#

两个镜像如果都 FROM python:3.9-slim，那基础镜像的层在磁盘上只存一份，被两个镜像共同引用。这就是为什么本地镜像列表的 SIZE 加起来很大，实际磁盘占用却小得多。

1
docker system df    # 看真实占用，会发现"共享"带来的节省

4.3 镜像只读 + 写时复制（Copy-on-Write）#

镜像层全是只读的。docker run 时，Docker 在所有只读层之上加一层薄薄的可读写容器层：

• 读文件：从上层往下找，找到就返回
• 改文件：先把文件从只读层复制到容器层，再改（这就是 CoW）
• 删文件：在容器层打一个”白化”（whiteout）标记，遮住下层文件

验证一下分层：

1
docker image history my-python-app:latest
2
docker image inspect --format='{{.RootFS.Layers}}' my-python-app:latest

5.1 列出镜像#

1
docker images                                    # 列出本地镜像
2
docker images -a                                 # 含中间层镜像
3
docker images --no-trunc                         # 显示完整 64 位镜像 ID
4
docker images my-python-app                      # 按名称过滤
5
docker images my-python-app:latest               # 按名称+标签过滤
6
docker images --filter=reference='my-python-app' # 用 --filter
7
docker images --format "table {{.Repository}}\t{{.Tag}}\t{{.Size}}"

5.2 拉取指定标签的镜像#

1
docker pull alpine:3.7

不写标签就是 :latest。

5.3 查看详情与历史#

1
docker image inspect my-python-app:latest                        # 完整元数据
2
docker image inspect --format='{{.Config.Env}}' my-python-app    # 只看环境变量
3
docker image inspect --format='{{.RootFS.Layers}}' my-python-app # 看层列表
4
docker image history my-python-app:latest                        # 看每层的构建指令

5.4 清理#

1
docker image prune              # 删除悬空镜像（<none>:<none>）
2
docker image prune -a           # 删除所有未被容器引用的镜像
3
docker system prune -a --volumes # 系统级大扫除（含数据卷，慎用）

（图 2 —— 原图待补）

[!note] 什么是悬空镜像 悬空镜像（dangling image） 是重新构建后被新镜像抢占了名字、只剩 <none>:<none> 的旧镜像。它们不承载业务逻辑，但很占磁盘。

6.1 为什么必须有标签策略#

• 版本控制与回滚：出问题时能一键退回上一个版本
• 可追溯：知道线上跑的是哪次构建
• 支撑自动化：CI/CD 靠标签决定部署什么

6.2 打标签的三种时机#

① 构建时指定

1
docker build -t my-python-app:1.0.0 .
2
docker build -t csc/csc_app:1 -t csc/csc_webapp:1 .   # 一次构建打多个标签

② 构建后追加

1
docker tag my-python-app:latest my-python-app:1.0.0
2
docker tag my-python-app:latest my-python-app:prod

③ 用镜像 ID 打标签

1
docker tag 8a7ffbdffc07 my-python-app:1.0.0

6.3 推荐的标签策略#

1
# 语义化版本
2
docker tag my-python-app:latest my-python-app:1.0.0
3
docker tag my-python-app:latest my-python-app:1.0
4
docker tag my-python-app:latest my-python-app:1
5

6
# 按环境
7
docker tag my-python-app:latest my-python-app:prod
8
docker tag my-python-app:latest my-python-app:dev
9

10
# 结合构建信息（可追溯到代码提交）
11
docker tag my-python-app:latest my-python-app:$(git rev-parse --short HEAD)
12
docker tag my-python-app:latest my-python-app:$(date +%Y%m%d-%H%M%S)

6.4 删除与”重命名”标签#

1
docker rmi my-python-app:old-tag        # 删标签（若该镜像还有别的标签，只删标签不删数据）
2
docker tag my-python-app:old my-python-app:new && docker rmi my-python-app:old   # 重命名

7.1 完整流程#

步骤 1：在 Docker Hub 注册并登录，进入 Repositories 标签页创建一个仓库（例如 cloudstudio）。

步骤 2：用「用户名/仓库名」的格式构建

1
docker build -t keiran479/cloudstudio .

步骤 3：登录

1
docker login -u <username>

1
echo $DOCKER_PASSWORD | docker login -u <username> --password-stdin

步骤 4：推送

1
docker push keiran479/cloudstudio

步骤 5：在 Docker Hub 页面确认镜像已上线。

7.2 推送指定版本到私有仓库#

1
docker tag my-python-app:latest keiran479/my-python-app:v1
2
docker login -u <username>
3
docker push keiran479/my-python-app:v1

7.3 推送的原理#

docker push 并不会把整个镜像无脑上传。它会：

1. 读取镜像的 manifest（层清单）
2. 逐层计算 SHA256，只上传远端仓库不存在的层
3. 已存在的层直接跳过（输出里表现为 Layer already exists 或 Mounted from ...）

这就是为什么基于同一基础镜像的第二个镜像推送得飞快 —— 底层的 python:3.9-slim 早就在 Hub 上了。

7.4 推送失败的四个常见原因#

8.1 语法与定位#

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

8.2 实操：给 Ubuntu 装上 nmap 并固化#

1
# 1. 拉取基础镜像
2
docker pull alex43/ubuntu-with-git:v1.0
3

4
# 2. 交互式启动容器
5
docker run -it alex43/ubuntu-with-git:v1.0 /bin/bash
6

7
# 3. 在容器内修改
8
nmap --version          # 先确认没装
9
apt-get install nmap
10
nmap --version          # 确认装好了
11
exit
12

13
# 4. 提交为新镜像
14
docker commit <container_id> ubuntu-with-nmap:v1.0
15

16
# 5. 验证
17
docker images
18

19
# 6. 基于新镜像启动，改动仍在
20
docker run -it ubuntu-with-nmap:v1.0 /bin/bash

8.3 commit vs push vs save#

8.4 什么时候该用 commit#

✅ 适合：快速原型验证、保存调试现场、临时修复、实验性改动 ❌ 不适合：正式交付

9.1 五个高频故障#

9.2 镜像优化六条#

1. 用多阶段构建 —— 编译期依赖不进最终镜像
2. 优化层顺序 —— 不常变的层放前面
3. 必配 .dockerignore —— 减小上下文、保护缓存
4. 锁定基础镜像版本 —— 不用 latest
5. 合并 RUN 指令 —— RUN a && b && c 减少层数，并在同一层内清理缓存
6. 构建过程中清理 —— pip install --no-cache-dir、apt-get clean && rm -rf /var/lib/apt/lists/*

第 5、6 条配合使用的正确姿势：

1
RUN apt-get update \
2
    && apt-get install -y --no-install-recommends gcc \
3
    && apt-get clean \
4
    && rm -rf /var/lib/apt/lists/*

10.1 本次实操的最小闭环#

1
# 构建
2
docker build -t my-python-app:1.0.0 .
3

4
# 运行
5
docker run -d -p 5000:80 --name myapp my-python-app:1.0.0
6

7
# 验证
8
curl localhost:5000          # Hello, World!
9

10
# 打标签
11
docker tag my-python-app:1.0.0 my-python-app:latest
12

13
# 发布
14
docker tag my-python-app:1.0.0 <username>/my-python-app:1.0.0
15
docker push <username>/my-python-app:1.0.0
16

17
# 清理
18
docker stop myapp && docker rm myapp
19
docker image prune

10.2 三个必须刻进脑子里的原理#

10.3 一句话收尾#

#Docker #镜像 #容器化 #云原生 #教程笔记