---
title: 后端-07-Docker与容器化
aliases:
  - Docker
  - 容器化
  - Container
  - Docker Compose
tags:
  - 后端/运维
  - 类型/教程
created: 2026-10-11
updated: 2026-10-11
level: 进阶
prerequisites:
  - "[[操作系统]]"
  - "[[计算机网络]]"
  - "[[工具-02-命令行与Shell]]"
sources:
  - https://docs.docker.com/get-started/
  - https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/
  - https://docs.docker.com/get-started/docker-concepts/building-images/
  - https://docs.docker.com/build/building/multi-stage/
  - https://docs.docker.com/reference/dockerfile/
  - https://docs.docker.com/engine/storage/volumes/
  - https://docs.docker.com/engine/storage/bind-mounts/
  - https://docs.docker.com/engine/network/
  - https://docs.docker.com/reference/compose-file/
  - https://docs.docker.com/compose/how-tos/startup-order/
  - https://docs.docker.com/compose/how-tos/environment-variables/
  - https://docs.docker.com/reference/cli/docker/container/run/
  - https://kubernetes.io/zh-cn/docs/concepts/configuration/manage-resources-containers/
  - https://learn.microsoft.com/zh-cn/dotnet/core/docker/build-container
---

# 后端-07-Docker与容器化

> [!abstract] 这篇讲什么
> 容器（container）解决的核心问题是「**在我机器上能跑**」。本篇从环境依赖不一致的根因讲起，把镜像、容器、仓库、分层存储、写时复制这些容易混的概念拆清楚，然后给出**可以直接复制运行的 Dockerfile 与 Compose 编排文件**，覆盖数据持久化、网络、镜像优化、资源限制与容器化边界。
> 读完你应该能做到三件事：① 把一个 Node 或 .NET 应用打成小于 200 MB 的生产镜像；② 用 `compose.yaml` 一键起「应用 + 数据库 + Redis + 反向代理」；③ 说出至少五个容器化踩坑点。

## 一、是什么：容器要解决的问题

### 1.1 「在我机器上能跑」的根因

你在本地写完代码，测试全绿，提交上线，服务器报错。这不是玄学，根因通常只有三类：

| 根因 | 具体表现 | 传统做法的痛 |
|---|---|---|
| **环境依赖不一致** | 本地 Node 20 / 服务器 Node 18；本地 OpenSSL 3 / 服务器 OpenSSL 1.1 | 靠文档记录版本，靠人执行，靠运气 |
| **依赖冲突** | A 服务要 Python 3.9，B 服务要 Python 3.12；两个应用抢同一个 `libssl` | 只能装虚拟机，或者忍受版本妥协 |
| **部署步骤手工化** | 「先装 nginx，再改配置，再 `systemctl restart`，再跑迁移脚本」 | 步骤写在不更新的 Wiki 里，换人做就漏 |

容器给出的答案是把**应用和它的全部运行时依赖一起打包成不可变的镜像（image）**。镜像里除了你的代码，还有操作系统用户空间的文件、语言运行时、系统库、环境变量。于是「运行你的应用」这件事从「在目标机器上复现一套环境」变成了「在目标机器上跑一个镜像」——后者是幂等的。

> [!important] 一句话概括
> 容器不是让程序跑得更快，而是让**「能跑」这件事变得可复制、可版本化、可回滚**。

### 1.2 容器与虚拟机的对比

初学者最容易把容器当成「轻量虚拟机」。先看这张表，再看第 2.4 节的原理辨析。

| 对比维度 | 虚拟机（Virtual Machine, VM） | 容器（Container） |
|---|---|---|
| 隔离级别 | 硬件级虚拟化，各自有独立内核（kernel） | 操作系统级虚拟化，**共享宿主机内核**，靠 namespace 隔离视图、cgroup 限制资源 |
| 启动速度 | 数十秒到分钟级（要走完整引导流程） | 毫秒到秒级（本质是启动一个进程） |
| 资源开销 | 每台 VM 固定占用一部分内存与 CPU 给 Guest OS | 无 Guest OS 开销，只多出容器进程本身 |
| 镜像体积 | GB 级（含完整操作系统） | 几十 MB 到几百 MB（只含用户空间文件） |
| 同机密度 | 通常几十台 | 通常几百到上千个 |
| 隔离强度 | **强**，内核漏洞不易跨 VM | **弱于 VM**，内核漏洞可能逃逸（escape） |
| 适用场景 | 需要不同内核、强隔离、异构操作系统 | 同一内核上的应用交付、微服务、CI 构建 |

> [!warning] 隔离强度的取舍
> 容器共享内核意味着：宿主机内核的提权漏洞是**所有容器共同的攻击面**。多租户场景（比如给别人跑不可信代码的 SaaS）要么加强（gVisor、Kata Containers、seccomp/AppArmor），要么退回虚拟机。不要相信「容器等于沙箱」。

## 二、核心概念辨析

### 2.1 镜像、容器、仓库三者的关系

这三个词的关系可以用「类 / 对象 / 代码托管平台」来类比：

| 概念 | 英文 | 本质 | 类比 |
|---|---|---|---|
| 镜像 | image | **只读**的模板，由一层层文件系统叠加而成 | 类（class） |
| 容器 | container | 镜像之上加一个**可写层**后的运行实例 | 对象（instance） |
| 仓库 | registry / repository | 集中存放与分发镜像的服务 | 制品库 / 应用商店 |

一个容器 = 只读镜像层（可能多个） + 一个可写层 + 一组运行时配置（网络、挂载、环境变量）。

一条命令就能验证这层关系：

```bash
# 同一个镜像可以起多个互不影响的容器
docker run -d --name web1 nginx:1.27-alpine
docker run -d --name web2 nginx:1.27-alpine
docker ps --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'
```

### 2.2 分层存储与联合文件系统

镜像不是一个大文件，而是**一组只读层的堆叠**。每一层是「相对于上一层的文件增删改」：

```text
容器可写层（Container layer，读写，容器删除即丢失）
──────────────────────────────────────────────
第 4 层  COPY . /app                      （你的代码）
第 3 层  RUN npm ci --omit=dev            （npm 依赖）
第 2 层  WORKDIR /app
第 1 层  node:20-alpine 基础镜像           （发行版文件 + Node 运行时）
──────────────────────────────────────────────
```

把这些层「叠加」成看起来像一棵完整目录树的技术叫**联合文件系统（Union File System, UnionFS）**。Docker 在不同平台用不同实现（`overlay2` 最常见，Windows 上还有 `windowsfilter`），但对使用者是透明的。

分层的直接收益：

- **层可以共享**：`node:20-alpine` 只存一份，10 个基于它的镜像共用。
- **层可以复用缓存**：构建时如果某一层没变，直接复用，不用重跑。
- **传输更省**：`docker pull` 只需下载本地缺失的层。

### 2.3 写时复制

容器启动时不会把镜像层复制一遍。读文件时直接读只读层；**一旦要修改某个文件，才把它复制到可写层再改**，这叫**写时复制（Copy-on-Write, CoW）**。

写时复制带来两个必须记住的后果：

1. **容器内写入的数据会随容器删除而消失**——它落在可写层里，而可写层的生命周期等于容器。这正是第 6 节「数据持久化」存在的原因。
2. **修改大文件代价高**——比如容器里 `sed -i` 一个 500 MB 的数据文件，Docker 会先复制整份到可写层。

> [!warning] 常见误解
> `docker restart` 不会丢数据（可写层还在），`docker rm` 才会。很多人把「重启后数据还在」当成「数据持久化了」，直到删容器时才发现数据库文件没了。

### 2.4 容器为什么不是「轻量虚拟机」

把三个机制分开看就清楚了：

- **namespace（命名空间）**：决定「你能看到什么」。PID namespace 让容器内看不到宿主机其他进程；NET namespace 给容器独立网卡、路由表；MNT namespace 给独立挂载点；UTS 给独立主机名；IPC 给独立进程间通信；USER 让容器内 root 可以映射成宿主机普通用户。
- **cgroup（控制组）**：决定「你能用多少」。限制 CPU、内存、IO 带宽，`docker run --memory` / `--cpus` 最终落到 cgroup 参数上。
- **UnionFS**：决定「你的文件系统长什么样」。

虚拟机靠 Hypervisor 虚拟出一整套硬件并引导一个独立内核；容器只是宿主机上**一个被限制了视野和资源的普通进程**。所以：

$$
\text{容器启动耗时} \approx \text{进程创建耗时} + O(\text{挂载命名空间})
\quad\ll\quad
\text{虚拟机启动耗时} \approx \text{内核引导} + O(\text{设备初始化})
$$

### 2.5 容器内进程与 PID 1 的信号处理

这是最容易被忽略、又最容易导致「`docker stop` 停不掉 / 停得特别慢」的问题。

容器里第一个启动的进程的 PID 是 **1**。在 Linux 中，PID 1 有三个特殊职责：

1. 它是**孤儿进程的收养者**（reparent 的目标）。
2. 它必须**回收僵尸进程**（zombie process，即已结束但未被 `wait` 的子进程）。
3. 它**不会自动获得默认信号处理**：内核不会给 PID 1 安装默认动作，未被显式注册的信号会被**直接忽略**。

后果：如果你的应用是 `node server.js`，而它没有注册 `SIGTERM` 处理器，那么 `docker stop` 发出的 `SIGTERM` 会被忽略，Docker 等 10 秒（默认 `--stop-timeout=10`）后发 `SIGKILL` 强杀。表现就是「每次停止都要等 10 秒」，且**连接被硬断开，没有优雅退出**。

三种解法：

```dockerfile
# 方案 A：应用自身正确注册 SIGTERM（推荐）
# Node 示例：process.on('SIGTERM', () => server.close(() => process.exit(0)))
```

```bash
# 方案 B：用 --init 让 docker 注入一个微型 init（tini）当 PID 1，负责转发信号与回收僵尸
docker run -d --init --name web nginx:1.27-alpine
```

```dockerfile
# 方案 C：镜像里显式使用 tini
FROM node:20-alpine
RUN apk add --no-cache tini
ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "server.js"]
```

> [!warning] 你会遇到的真实症状
> `docker stop` 耗时正好 10 秒 → 99% 是信号没被正确处理。若容器内还 fork 了子进程而 PID 1 不回收，`docker exec ps aux` 会出现一堆 `<defunct>`。

## 三、安装与验证

### 3.1 验证安装

```bash
docker --version
# Docker version 27.x.x, build xxxxxxx

docker info
# 会打印 Server 端信息：Storage Driver、Cgroup Version、Operating System 等

# 最经典的冒烟测试：拉一个几十 KB 的镜像并运行
docker run --rm hello-world
```

`docker run hello-world` 成功说明整条链路都通：客户端 → 守护进程（daemon）→ 拉取镜像 → 创建容器 → 运行 → 输出。

### 3.2 Windows 上 Docker Desktop 与 WSL2 后端的关系

Windows 上没有原生的 Linux 内核，而绝大多数镜像（`nginx`、`postgres`、`node`）都是 Linux 镜像。Docker Desktop 的解法是：

| 概念 | 作用 |
|---|---|
| **WSL2**（Windows Subsystem for Linux 2） | 微软提供的轻量级 Linux 虚拟机，内含真实 Linux 内核 |
| **Docker Desktop** | Windows 上的图形客户端 + 守护进程管理器，把 Linux 引擎跑在 WSL2 发行版里 |
| **docker CLI** | 你在 PowerShell 里敲的 `docker` 命令，通过命名管道连到 WSL2 里的引擎 |

实践要点：

```powershell
# 1. 确认 WSL2 已就绪
wsl --status
wsl --list --verbose      # 应能看到 docker-desktop 发行版，VERSION 为 2

# 2. 若未安装 WSL2
wsl --install

# 3. 引擎跑在 WSL2 里的经典坑：项目放在 Windows 盘（/mnt/c/...）时绑定挂载极慢
#    解决：把代码放在 WSL 文件系统内，如 \\wsl$\Ubuntu\home\me\project
```

> [!tip] 性能建议
> 在 Windows 上做开发，**把项目放在 WSL2 文件系统内**而不是 `C:\` 下，绑定挂载（bind mount）的 IO 性能差距可以达到数倍甚至十倍以上。这是「Docker 在 Windows 上很卡」的最常见原因。

## 四、镜像操作命令表

| 命令 | 用途 | 常用示例 |
|---|---|---|
| `docker pull` | 从仓库拉取镜像 | `docker pull postgres:16-alpine` |
| `docker images` | 列出本地镜像 | `docker images --format 'table {{.Repository}}\t{{.Tag}}\t{{.Size}}'` |
| `docker rmi` | 删除镜像 | `docker rmi nginx:1.27-alpine` |
| `docker tag` | 给镜像打新标签（不复制数据） | `docker tag myapp:dev registry.example.com/team/myapp:v1.2.0` |
| `docker push` | 推送镜像到仓库 | `docker push registry.example.com/team/myapp:v1.2.0` |
| `docker save` | 把镜像导出为 tar 文件 | `docker save -o myapp.tar myapp:v1` |
| `docker load` | 从 tar 文件导入镜像 | `docker load -i myapp.tar` |
| `docker inspect` | 查看镜像/容器的完整 JSON 元数据 | `docker inspect --format '{{.Config.Env}}' myapp:v1` |
| `docker history` | 查看镜像**每一层**是怎么产生的 | `docker history --no-trunc myapp:v1` |
| `docker build` | 由 Dockerfile 构建镜像 | `docker build -t myapp:v1 .` |
| `docker image prune` | 清理悬空镜像（dangling image） | `docker image prune -f` |

几个高频用途说明：

- **`docker history` 是排查「镜像为什么这么大」的第一工具**。它会逐层列出大小与创建命令，通常能立刻定位到某一条 `RUN` 装了不该装的东西。
- **`docker inspect` 用 `--format` 配合 Go 模板**，可以直接喂给脚本：
  ```bash
  # 取容器 IP
  docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' web1
  # 取镜像暴露的端口
  docker inspect -f '{{.Config.ExposedPorts}}' nginx:1.27-alpine
  ```
- **`save` / `load` 与 `export` / `import` 不是一回事**：`save` 保留完整分层与元数据（`CMD`、`ENV` 等），`export` 只导出容器当前文件系统为一个扁平 tar，元数据全丢。跨离线环境搬镜像用 `save`/`load`。

> [!danger] 危险的镜像清理命令
> ```bash
> docker system prune -a --volumes
> ```
> 这条命令会删除**所有未被使用的镜像、网络、构建缓存，以及所有未被使用的数据卷**。被删的数据卷里的数据库数据**无法恢复**。执行前务必先 `docker volume ls` 与 `docker ps -a` 确认，生产环境不要执行。

## 五、容器操作命令表

### 5.1 `docker run` 常用参数

| 参数 | 含义 | 备注 |
|---|---|---|
| `-d` | 后台运行（detached） | 不加则前台运行并占用终端 |
| `-it` | `-i` 保持 stdin 打开 + `-t` 分配伪终端 | 交互式进入才需要 |
| `--rm` | 容器退出后自动删除 | 一次性任务必加，避免垃圾容器堆积 |
| `-p 主机端口:容器端口` | 端口映射 | 注意方向：左主机，右容器 |
| `-v 主机路径:容器路径` | 挂载（bind mount） | Windows 路径见第 6.2 节 |
| `--name` | 给容器命名 | 不指定会随机起名；名字唯一 |
| `-e KEY=VALUE` | 注入环境变量 | 密钥不要写在命令行（会进 shell 历史） |
| `--network` | 指定网络 | 自定义网络内可用服务名互访 |
| `--memory` / `--cpus` | 资源限制 | 生产必设，防止单容器打满宿主机 |
| `--restart` | 重启策略 | `no` / `on-failure` / `always` / `unless-stopped` |
| `--init` | 注入 tini 作 PID 1 | 见第 2.5 节 |

一个把参数用全的典型调用：

```bash
docker run -d \
  --name api \
  --restart unless-stopped \
  -p 8080:3000 \
  -e NODE_ENV=production \
  -e TZ=Asia/Shanghai \
  --network app-net \
  --memory 512m --cpus 1.5 \
  -v "$PWD/data:/app/data" \
  --init \
  myapp:v1.2.0
```

### 5.2 生命周期与排查命令

| 命令 | 用途 | 关键参数 |
|---|---|---|
| `docker ps` | 列出**运行中**容器 | `-a` 含已停止；`-q` 只输出 ID |
| `docker logs` | 查看容器标准输出/错误 | `-f` 跟踪；`--tail 100`；`-t` 带时间戳 |
| `docker exec` | 在**运行中**容器里执行新命令 | `-it` 交互；`-u` 指定用户 |
| `docker attach` | 附着到容器的 **PID 1** 标准输入输出 | `--sig-proxy=false` 让 Ctrl+C 不影响容器 |
| `docker stop` | 发送 SIGTERM，超时后 SIGKILL | `-t 30` 改超时 |
| `docker start` | 启动已存在但停止的容器 | 保留原可写层数据 |
| `docker rm` | 删除容器 | `-f` 强制删除运行中的；`-v` 同时删匿名卷 |
| `docker stats` | 实时资源占用 | `--no-stream` 只取一次快照 |
| `docker top` | 查看容器内进程 | 排查僵尸进程 |
| `docker cp` | 宿主机与容器间复制文件 | `docker cp api:/app/log.txt .` |

### 5.3 `docker exec` 与 `docker attach` 的区别

这是面试与实操双高频问题：

| 维度 | `docker exec` | `docker attach` |
|---|---|---|
| 做什么 | 在容器内**新起一个进程**（如 `bash`） | 把当前终端接到容器 **PID 1** 的 stdio 上 |
| 退出影响 | `exit` 只结束这个新进程，容器继续跑 | 按 Ctrl+C 会把 SIGINT 发给 PID 1，**可能直接停掉容器** |
| 适用场景 | 排查问题、看文件、连数据库客户端 | 看一个前台进程的输出（如调试交互式程序） |
| 能否同时多人 | 可以，互不干扰 | 多人 attach 时输入会混乱 |
| 容器必须运行中 | 是 | 是 |

```bash
# 排查时正确的姿势
docker exec -it api sh          # alpine 镜像没有 bash，用 sh
docker exec api env | sort      # 确认环境变量真的注入了
docker exec api cat /etc/hosts  # 看服务名解析
```

> [!tip] 排查口诀
> **看日志用 `logs`，进容器用 `exec`，`attach` 基本只在调试 PID 1 行为时使用。**

## 六、Dockerfile 编写

### 6.1 逐指令讲解

| 指令 | 作用 | 关键注意点 |
|---|---|---|
| `FROM` | 指定基础镜像，必须是第一条（`ARG` 除外） | 支持 `AS <name>` 命名阶段；生产建议固定到具体 tag 甚至 digest |
| `WORKDIR` | 设置后续指令的工作目录，目录不存在会自动创建 | **不要用 `RUN cd /app`**，那只对当层有效 |
| `COPY` | 从构建上下文复制文件进镜像 | 优先 `COPY` 而非 `ADD`；`ADD` 会自动解压 tar、支持 URL，容易意外 |
| `RUN` | 在**构建期**执行命令，结果固化进层 | 多个命令用 `&&` 串起来并清理缓存，减少层数与体积 |
| `ENV` | 设置**构建期与运行期都生效**的环境变量 | 密钥不要用 `ENV` 写进镜像（`docker history` 能看到） |
| `ARG` | 只在**构建期**存在的变量 | 同样不能用来传密钥 |
| `EXPOSE` | 声明容器监听的端口（**文档性质**） | 它不会真的发布端口，仍需 `-p` 或 Compose `ports` |
| `CMD` | 提供默认命令，**可被 `docker run` 参数覆盖** | 一个 Dockerfile 只有最后一条生效 |
| `ENTRYPOINT` | 定义容器的固定可执行体，**不易被覆盖** | 需用 `--entrypoint` 才能覆盖 |
| `USER` | 指定后续指令与运行时使用的用户 | 生产应配合非 root 用户 |
| `HEALTHCHECK` | 定义容器健康检查命令 | Compose/K8s 健康检查更常用，但镜像内置也可 |
| `VOLUME` | 声明匿名卷挂载点 | 副作用大，容易造成「数据写进去了却找不到」，见第 6 节 |

### 6.2 `CMD` 与 `ENTRYPOINT` 的区别与两种组合模式

记忆方式：**`ENTRYPOINT` 是「谁」，`CMD` 是「默认参数」**。

**模式一：只写 `CMD`（默认参数可整条替换）**

```dockerfile
FROM nginx:1.27-alpine
CMD ["nginx", "-g", "daemon off;"]
```

```bash
docker run mynginx              # 执行 nginx -g "daemon off;"
docker run mynginx echo hi      # 整条 CMD 被替换 → 执行 echo hi
```

**模式二：`ENTRYPOINT` + `CMD` 组合（推荐给应用镜像）**

```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY . .
ENTRYPOINT ["node", "server.js"]
CMD ["--port", "3000"]
```

```bash
docker run myapp                       # node server.js --port 3000
docker run myapp --port 8080           # 只有 CMD 部分被替换 → node server.js --port 8080
```

> [!important] 结论
> 想让镜像「像一个命令」用（可以接参数），用 `ENTRYPOINT` + `CMD`；想让镜像「像一个默认行为」用，只写 `CMD`。二者同时存在时，`docker run` 后面跟的参数**只会覆盖 `CMD`**。

### 6.3 shell 形式与 exec 形式的区别

同一指令有两种写法：

```dockerfile
# shell 形式（Shell form）：会被包成 /bin/sh -c "..."
CMD node server.js

# exec 形式（Exec form）：直接以 JSON 数组形式 exec，不经过 shell
CMD ["node", "server.js"]
```

| 维度 | shell 形式 | exec 形式 |
|---|---|---|
| 是否经过 shell | 是（`/bin/sh -c`） | 否，直接 `execve` |
| PID 1 是谁 | **`/bin/sh`** | **你的程序** |
| 能否收到 `SIGTERM` | 不能直接收到，被 `sh` 挡住 | 能 |
| 环境变量替换 | 支持 `$VAR` 展开 | 不支持（需要 shell 展开就用 shell 形式） |
| 是否容易优雅退出 | 否 | 是 |

**为什么 exec 形式能正确接收信号**：`docker stop` 只把 `SIGTERM` 发给了 PID 1。shell 形式下 PID 1 是 `/bin/sh`，多数 shell 不会把信号转发给子进程，于是你的 Node 进程根本不知道要退出；10 秒后被 `SIGKILL` 硬杀。exec 形式下你的进程**就是** PID 1，信号直达。

> [!warning] 常见坑
> ```dockerfile
> CMD node server.js     # ❌ 信号被 sh 吃掉，docker stop 永远等 10 秒
> CMD ["node", "server.js"]   # ✅
> ```
> 需要 shell 特性（管道、变量展开）时，可以用 `ENTRYPOINT ["/bin/sh", "-c", "exec node server.js \"$@\"", "--"]` 的写法，关键在 `exec` 关键字让 `sh` 把自身替换成 node。

### 6.4 多阶段构建：解决构建工具污染运行镜像

问题：构建需要编译器、SDK、devDependencies（可能几百 MB），但运行只需要产物和运行时。传统做法是把两者塞进同一个镜像，结果镜像臃肿且攻击面大。

**多阶段构建（multi-stage build）** 允许在一个 Dockerfile 里写多个 `FROM`，用 `COPY --from=<stage>` 只把产物搬到最终镜像。

**完整例子一：Node 应用**

```dockerfile
# ---------- 阶段 1：构建 ----------
FROM node:20-alpine AS builder
WORKDIR /src

# 先只复制依赖清单，让依赖层能被缓存复用（见 6.5 层顺序原则）
COPY package.json package-lock.json ./
RUN npm ci

# 再复制源码并构建
COPY . .
RUN npm run build && npm prune --omit=dev

# ---------- 阶段 2：运行 ----------
FROM node:20-alpine AS runtime

# 只装运行期需要的少量系统包
RUN apk add --no-cache tini curl

# 用非 root 用户运行（见第 11 节）
RUN addgroup -S app && adduser -S app -G app
WORKDIR /app

# 只搬运产物与生产依赖，构建工具链不进最终镜像
COPY --from=builder /src/node_modules ./node_modules
COPY --from=builder /src/dist ./dist
COPY --from=builder /src/package.json ./

ENV NODE_ENV=production
ENV PORT=3000
EXPOSE 3000

USER app
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD curl -fsS http://127.0.0.1:3000/healthz || exit 1

ENTRYPOINT ["/sbin/tini", "--"]
CMD ["node", "dist/server.js"]
```

**完整例子二：.NET 应用**

```dockerfile
# ---------- 阶段 1：还原与发布 ----------
FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
WORKDIR /src

# 先复制 csproj 单独还原，最大化利用层缓存
COPY *.csproj ./
RUN dotnet restore

COPY . ./
RUN dotnet publish -c Release -o /app/publish /p:UseAppHost=false

# ---------- 阶段 2：运行 ----------
# 注意：发布时用的是 sdk 镜像，运行时只需要 aspnet/runtime 镜像
FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS runtime
WORKDIR /app

# 容器内时区默认 UTC，需要本地时间时显式安装/设置
ENV TZ=Asia/Shanghai
ENV DOTNET_EnableDiagnostics=0

COPY --from=build /app/publish .

EXPOSE 8080
ENV ASPNETCORE_URLS=http://+:8080

USER app
ENTRYPOINT ["dotnet", "MyApp.dll"]
```

> [!tip] 体积对比的直觉
> .NET 的 `sdk:9.0` 镜像约 800 MB 量级，`aspnet:9.0` 约 200 MB 量级。单靠多阶段构建，最终镜像就能小几百 MB——这不是优化技巧，而是**基础事实**：构建工具不该出现在生产镜像里。

### 6.5 `.dockerignore` 的必要性

`docker build .` 中的 `.` 是**构建上下文（build context）**。Docker 客户端会先把上下文整体打包发给守护进程（或构建器）。如果上下文里有 `node_modules`、`.git`、`bin/obj`、日志、`*.tar`，后果是：

1. 每次构建都要传输几百 MB，构建时间暴涨。
2. `COPY . .` 会把本地 `node_modules` 覆盖掉镜像内刚装好的依赖，导致「本地能跑、镜像里跑不起来」。
3. 密钥文件（`.env`、`*.pem`）可能被复制进镜像，直接泄露。

```gitignore
# .dockerignore
.git
.gitignore
node_modules
dist
build
bin
obj
*.log
*.tar
*.tar.gz
.env
.env.*
!.env.example
.vscode
.idea
Dockerfile*
compose*.yaml
README.md
```

> [!danger] `.dockerignore` 漏写 `.env` 等于把密钥打进镜像
> 镜像层是**不可变且可被任何人拉取**的。一旦 `COPY . .` 把 `.env` 带进去，即使后续层删掉它，`docker history` + 层提取依然能拿到内容。补救办法只有一个：**轮换（rotate）所有已泄露的密钥，然后重建镜像**。

## 七、镜像优化

### 7.1 基础镜像选择

| 基础镜像 | 体积量级 | 优点 | 缺点 | 适用 |
|---|---|---|---|---|
| `debian`（如 `node:20`） | 较大 | 兼容性最好，glibc 完整，`apt` 可用 | 体积大，CVE 面大 | 依赖原生模块、需要完整工具链 |
| `slim`（如 `node:20-slim`） | 中等 | 去掉文档与部分工具，兼容性仍好 | 依然有 shell 与包管理器 | 通用生产首选 |
| `alpine`（如 `node:20-alpine`） | 很小 | 体积最小，社区广泛使用 | 用 **musl libc**，某些预编译原生模块不兼容；`DNS` 解析行为与 glibc 有差异 | 纯解释型应用、Go 静态二进制 |
| `distroless` | 很小 | 无 shell、无包管理器，攻击面极小 | 无法 `exec` 进去排查，调试困难；需交叉构建 | 安全要求高的生产 |
| `scratch` | 最小（0 B） | 只有你的二进制 | 仅适用静态编译（Go/Rust） | 极简静态服务 |

> [!warning] Alpine 的 musl 陷阱
> 某些 npm 包（尤其带原生扩展的）在 alpine 上会编译失败或运行时段错误，因为官方预编译二进制是给 glibc 的。判断方式：`ldd` 报 `not found`、构建时报 `node-gyp` 错误。此时退回 `-slim` 比强行折腾 musl 更划算。

### 7.2 合并 `RUN` 与清理缓存

每一条 `RUN` 都会产生一层。层一旦生成就**无法在下一次构建中变小**——你后面删掉文件，只是在新层里加了一个「已删除」标记，文件仍存在于旧层，镜像体积不减。

```dockerfile
# ❌ 反例：3 层，且 apt 缓存永久留在第 1 层
RUN apt-get update
RUN apt-get install -y --no-install-recommends curl ca-certificates
RUN rm -rf /var/lib/apt/lists/*
```

```dockerfile
# ✅ 正例：1 层，清理在同一层内完成
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl ca-certificates \
 && rm -rf /var/lib/apt/lists/*
```

```dockerfile
# ✅ Alpine 对应写法
RUN apk add --no-cache curl ca-certificates
```

### 7.3 利用构建缓存与层顺序原则

构建缓存是**逐层匹配**的：某一层的指令文本、依赖文件内容、上一层的结果任一变化，该层及其**之后所有层**的缓存全部失效。

由此得到最重要的原则：**变化频率低的放前面，变化频率高的放后面。**

```dockerfile
# ❌ 反例：改一行源码 → 依赖层失效 → 每次都要重新 npm ci（可能几分钟）
COPY . .
RUN npm ci
RUN npm run build
```

```dockerfile
# ✅ 正例：改源码只影响最后两层，依赖层命中缓存
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build
```

其他提高命中率的技巧：

```bash
# 使用 BuildKit 的缓存挂载，让包管理器缓存跨构建复用
DOCKER_BUILDKIT=1 docker build \
  --build-arg BUILDKIT_INLINE_CACHE=1 \
  -t myapp:v1 .
```

```dockerfile
# 语法声明放在文件首行，启用 BuildKit 高级特性
# syntax=docker/dockerfile:1
FROM node:20-alpine
WORKDIR /app
COPY package.json package-lock.json ./
RUN --mount=type=cache,target=/root/.npm npm ci
```

### 7.4 体积优化前后的对比示例

以一个真实的 Node API 项目为例（数值来自构建输出的 `docker images`）：

| 版本 | 做法 | 体积 |
|---|---|---|
| v0（新手写法） | `FROM node:20`，`COPY . .`，`RUN npm install`，无 `.dockerignore` | 约 1.1 GB |
| v1 | 换 `node:20-alpine`，加 `.dockerignore`，`npm ci --omit=dev` | 约 190 MB |
| v2 | 多阶段构建，只搬运 `dist` + 生产依赖 | 约 120 MB |
| v3 | 固定基础镜像 digest，去掉多余系统包，`npm prune` | 约 95 MB |

优化收益不只在磁盘：镜像小 → 拉取快 → 扩容时新实例就绪更快 → 故障恢复更快。

## 八、数据持久化

### 8.1 容器内数据为什么易失

回到第 2.3 节：容器写入落在可写层，可写层生命周期等于容器。因此：

```bash
docker run -d --name db postgres:16-alpine -e POSTGRES_PASSWORD=secret
# ... 写入了一些数据 ...
docker rm -f db        # 可写层被删除，数据一起消失
```

要让数据活过容器，必须把它放到**容器之外**：数据卷（volume）或绑定挂载（bind mount）。

### 8.2 三种挂载方式对比

| 类型 | 声明方式 | 存储位置 | 谁管理 | 适用场景 |
|---|---|---|---|---|
| **匿名卷**（anonymous volume） | `-v /var/lib/postgresql/data`（只写容器路径）或 Dockerfile `VOLUME` | Docker 管理的 `volumes/<随机ID>/_data` | Docker | 临时隔离数据；**难以追踪，生产不推荐** |
| **命名卷**（named volume） | `-v pgdata:/var/lib/postgresql/data` | Docker 管理的 `volumes/pgdata/_data` | Docker | **数据库、需要备份的持久数据（推荐）** |
| **绑定挂载**（bind mount） | `-v /host/path:/container/path` | 宿主机任意路径 | 你自己 | 开发时挂源码做热重载；挂配置文件 |

```bash
# 命名卷：由 Docker 管理，可列出、可备份、跨容器复用
docker volume create pgdata
docker run -d --name db -v pgdata:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret postgres:16-alpine
docker volume ls
docker volume inspect pgdata
```

```bash
# 绑定挂载：开发时把本地代码挂进容器
docker run -d --name api -p 3000:3000 \
  -v "$PWD/src:/app/src" \
  -v "$PWD/package.json:/app/package.json:ro" \
  myapp:dev
```

### 8.3 Windows 路径注意事项

Windows 上写绑定挂载有三个坑：

```powershell
# 坑 1：Git Bash / MSYS 会把 /app/src 当成 Windows 路径自动转换（MSYS_NO_PATHCONV）
docker run -v /d/proj/src:/app/src myapp      # 可能变成 D:\d\proj\src
# 解决：用双斜杠或停用转换
docker run -v "//d/proj/src:/app/src" myapp
MSYS_NO_PATHCONV=1 docker run -v /d/proj/src:/app/src myapp
```

```powershell
# 坑 2：PowerShell 里用 ${PWD} 而不是 $PWD，且路径含空格要加引号
docker run -v "${PWD}\src:/app/src" myapp
docker run -v "D:\My Projects\src:/app/src" myapp
```

```yaml
# 坑 3：compose.yaml 里相对路径以 compose 文件所在目录为基准，用 ./ 明确表达
services:
  api:
    volumes:
      - ./src:/app/src          # 相对 compose 文件
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:
```

另需注意：**挂载到非空目录会遮蔽（shadow）容器内原有内容**。把空目录挂到 `/app/node_modules` 会让镜像里装好的依赖「消失」——这是开发环境最经典的报错来源。解决：为 `node_modules` 单独挂一个匿名卷：

```yaml
volumes:
  - ./src:/app/src
  - /app/node_modules      # 匿名卷占位，保护镜像内的依赖
```

> [!danger] 数据卷删除不可逆
> ```bash
> docker volume rm pgdata
> docker compose down -v      # -v 会删除 compose 中声明的所有命名卷
> ```
> 这两条命令会**永久删除数据库数据**。生产环境执行 `down -v` 前必须确认备份已完成。日常停止服务用 `docker compose down`（不加 `-v`）或 `docker compose stop`。

## 九、网络

### 9.1 默认 bridge 网络与端口映射规则

安装 Docker 后会存在几个内置网络：

```bash
docker network ls
# NETWORK ID     NAME      DRIVER    SCOPE
# xxxx           bridge    bridge    local     ← 默认网络
# xxxx           host      host      local
# xxxx           none      null      local
```

**默认 bridge 网络的两个重要缺陷**：

1. **只能用 IP 互访，不能用容器名**（默认 bridge 不提供内置 DNS 解析）。
2. 必须显式 `-p` 发布端口，宿主机外部才能访问。

端口映射规则 `-p 主机:容器`：

```bash
docker run -d -p 8080:80 nginx:1.27-alpine
#                 ↑    ↑
#              宿主机  容器内监听端口
# 访问 http://localhost:8080 → 命中容器 80

docker run -d -p 127.0.0.1:8080:80 nginx:1.27-alpine
# 只绑定回环，仅本机可访问（数据库等不应暴露到公网的场景）

docker run -d -p 8080:80/udp some-udp-service
# 默认是 TCP，UDP 要显式写

docker run -d -P nginx:1.27-alpine
# -P 大写：把镜像 EXPOSE 的所有端口随机映射到宿主机高位端口
```

方向记反是最常见的低级错误：`-p 80:8080` 与 `-p 8080:80` 完全不同。

### 9.2 容器间通过服务名互访的原理

创建**自定义网络**后，Docker 会为该网络启用**内置 DNS 服务**（内嵌 DNS resolver，监听 `127.0.0.11`）。容器内的 DNS 查询会被转发到这个解析器，它知道同网络内所有容器的名字与别名。

```bash
docker network create app-net

docker run -d --name db  --network app-net -e POSTGRES_PASSWORD=secret postgres:16-alpine
docker run -d --name api --network app-net -e DB_HOST=db myapp:v1

# api 容器内可以直接用服务名连接数据库
docker exec -it api sh -c 'ping -c1 db; getent hosts db'
```

> [!important] 关键结论
> **同一自定义网络内，容器名即主机名。** 这也是 Compose 能工作的基础：Compose 会为项目创建默认网络，并把每个服务名注册为可解析的主机名，所以 `compose.yaml` 里写 `DB_HOST=db` 就能连上名为 `db` 的服务。

### 9.3 host 与 none 模式

| 网络模式 | 行为 | 适用 | 风险 |
|---|---|---|---|
| `bridge`（默认） | 独立网络栈 + NAT + 端口映射 | 绝大多数场景 | 无特殊 |
| `host` | **直接共享宿主机网络栈**，不再有端口映射 | 高性能网络、需要绑定大量端口 | 端口冲突直接变成宿主机冲突；隔离性下降 |
| `none` | 只有 `lo` 回环，无网络 | 完全离线的批处理任务 | 无法访问网络 |
| `container:<name>` | 共享另一个容器的网络栈 | sidecar 模式 | 生命周期耦合 |

```bash
docker run -d --network host nginx:1.27-alpine
# 此时 nginx 直接监听宿主机 80，-p 参数无效
```

### 9.4 端口冲突的排查

```bash
# 1. 看 Docker 层的报错
docker run -p 8080:80 nginx:1.27-alpine
# docker: Error response from daemon: driver failed programming external
# connectivity ... bind: address already in use

# 2. 查是谁占了端口
docker ps --format 'table {{.Names}}\t{{.Ports}}' | grep 8080
ss -ltnp | grep :8080          # Linux
netstat -ano | findstr :8080   # Windows，最后一列是 PID

# 3. 找到占用者后处理
docker stop <name>
# 或改用其他宿主机端口
docker run -d -p 8081:80 --name web2 nginx:1.27-alpine
```

> [!tip] 排查顺序
> 端口冲突先问三个问题：① 是不是有另一个容器映射了同一端口？② 是不是宿主机上有 nginx/其他服务在监听？③ 是不是上一次的容器没删干净（`docker ps -a` 里 `Exited` 但端口预留）？最后一个问题在反复 `docker run` 调参时最常见。

## 十、Docker Compose

### 10.1 多容器编排的痛点

用 `docker run` 起一套「应用 + 数据库 + Redis + Nginx」需要：

- 手写 4 条长命令，参数极易写错；
- 手动 `docker network create` 并给每个容器加 `--network`；
- 手动保证启动顺序（先数据库再应用）；
- 每次改动都要重建容器，命令历史难以维护与交接。

Compose 把这一切收进一个声明式的 `compose.yaml`：一条 `docker compose up -d` 起全套。

### 10.2 完整编排示例

```yaml
# compose.yaml
name: myapp

services:
  # ---------- 反向代理 ----------
  nginx:
    image: nginx:1.27-alpine
    ports:
      - "80:80"
    volumes:
      - ./nginx/default.conf:/etc/nginx/conf.d/default.conf:ro
    depends_on:
      api:
        condition: service_healthy      # 等 API 健康后再启动
    networks: [app-net]
    restart: unless-stopped

  # ---------- 应用 ----------
  api:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        NODE_ENV: production
    image: myapp-api:local
    env_file:
      - .env                            # 敏感配置从文件读，不进 Git
    environment:
      NODE_ENV: production
      TZ: Asia/Shanghai
      DB_HOST: db                       # 服务名即主机名
      DB_PORT: "5432"
      REDIS_URL: redis://cache:6379
    expose:
      - "3000"                          # 只在内部网络暴露，不发布到宿主机
    depends_on:
      db:
        condition: service_healthy
      cache:
        condition: service_healthy
    volumes:
      - ./uploads:/app/uploads
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:3000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 20s
    networks: [app-net]
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: "1.5"
          memory: 512M

  # ---------- PostgreSQL ----------
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password   # 密码从 secret 读
    volumes:
      - pgdata:/var/lib/postgresql/data
      - ./db/init:/docker-entrypoint-initdb.d:ro          # 首次初始化脚本
    healthcheck:
      # -U 与 -d 必须写对，否则 pg_isready 会因默认库不存在而失败
      test: ["CMD-SHELL", "pg_isready -U appuser -d appdb"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s
    networks: [app-net]
    restart: unless-stopped
    # 注意：数据库端口不发布到宿主机，只在内部网络可见

  # ---------- Redis ----------
  cache:
    image: redis:7-alpine
    command: ["redis-server", "--appendonly", "yes", "--maxmemory", "256mb", "--maxmemory-policy", "allkeys-lru"]
    volumes:
      - redisdata:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 3s
      retries: 5
    networks: [app-net]
    restart: unless-stopped

networks:
  app-net:
    driver: bridge

volumes:
  pgdata:
  redisdata:

secrets:
  db_password:
    file: ./secrets/db_password.txt
```

配套的 Nginx 配置 `nginx/default.conf`：

```nginx
server {
    listen 80;
    server_name _;

    # 传给应用的真实信息
    location / {
        proxy_pass http://api:3000;
        proxy_http_version 1.1;
        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        "upgrade";
        proxy_read_timeout 60s;
    }
}
```

### 10.3 `depends_on` + `healthcheck` 解决启动顺序问题

经典故障现场：应用容器先于数据库就绪而启动，连接被拒绝 → 应用崩溃退出 → 因为 `restart: unless-stopped` 反复重启，看起来像「随机失败」。

**`depends_on` 单独使用是不够的**：它默认只保证「启动顺序」（容器被创建的顺序），**不保证「就绪」**——数据库进程启动了但还没接受连接，依赖它的应用照样失败。

正确做法是 `depends_on` + `condition: service_healthy` + 可靠的 `healthcheck`：

| 写法 | 语义 | 是否够用 |
|---|---|---|
| `depends_on: [db]` | 只保证 db 容器**先启动** | ❌ 不够 |
| `depends_on: {db: {condition: service_started}}` | 同上（新语法的显式写法） | ❌ 不够 |
| `depends_on: {db: {condition: service_healthy}}` | 等 db **健康检查通过** | ✅ 推荐 |

```bash
# 观察健康状态：STATUS 列会显示 (healthy) / (unhealthy) / (health: starting)
docker compose ps
docker inspect --format '{{.State.Health.Status}}' myapp-db-1
```

> [!warning] 健康检查本身也可能是错的
> `pg_isready` 不带 `-U` / `-d` 时，在某些配置下会因默认数据库不存在而持续返回失败，导致应用永远等不到启动。**健康检查命令必须自己先手动验证过**：`docker compose exec db pg_isready -U appuser -d appdb`。

### 10.4 `env_file` 与环境变量

优先级从低到高（后者覆盖前者）：

1. `compose.yaml` 中 `environment` 里写死的值
2. `env_file` 指定的文件
3. 宿主机 shell 中已存在的环境变量
4. `docker compose run -e KEY=VALUE` 命令行传入

```bash
# .env 放在 compose 文件同目录，会被自动读取用于 compose 文件内的 ${VAR} 插值
cat > .env <<'EOF'
POSTGRES_PASSWORD=change-me-in-real-env
API_PORT=3000
EOF

# 验证变量真的注入了容器
docker compose exec api env | grep -E 'DB_HOST|REDIS_URL'
```

注意区分两个概念：`.env` 用于 **Compose 文件自身的变量插值**；`env_file:` 指定的文件用于**注入容器内部的环境变量**。二者可以都指 `.env`，但语义不同。

### 10.5 常用 Compose 命令

| 命令 | 用途 | 注意 |
|---|---|---|
| `docker compose up -d` | 构建并后台启动全部服务 | `--build` 强制重建镜像 |
| `docker compose logs -f api` | 跟踪某服务日志 | `--tail 200` 限制行数 |
| `docker compose ps` | 查看服务状态与健康 | 排查启动顺序必看 |
| `docker compose exec api sh` | 进入运行中的服务 | 不用写容器名，用服务名 |
| `docker compose restart api` | 重启单个服务 | 不重建镜像 |
| `docker compose down` | 停止并删除容器与网络 | **保留**命名卷 |
| `docker compose down -v` | 同时删除命名卷 | ⚠️ 数据丢失，见第 8.3 节 danger |
| `docker compose build --no-cache` | 完全不用缓存重建 | 排查缓存导致的问题时使用 |
| `docker compose config` | 校验并打印最终合并后的配置 | 排查变量插值问题的利器 |

### 10.6 开发环境用挂载实现热重载

生产镜像追求「不可变」，开发环境追求「改完立刻生效」。用 Compose 的 override 文件分离二者：

```yaml
# compose.override.yaml —— 只在开发时自动生效（docker compose up 会自动合并）
services:
  api:
    build:
      target: builder          # 用构建阶段（含 devDependencies 与源码）
    command: ["npm", "run", "dev"]
    environment:
      NODE_ENV: development
    volumes:
      - ./src:/app/src                 # 源码实时同步
      - ./package.json:/app/package.json:ro
      - /app/node_modules              # 匿名卷保护镜像内依赖（见 8.3 节）
    ports:
      - "9229:9229"                    # Node 调试端口
```

```bash
# 开发：自动合并 compose.override.yaml
docker compose up -d

# 生产：忽略 override 文件，只用 compose.yaml
docker compose -f compose.yaml up -d
```

## 十一、镜像仓库

### 11.1 公共仓库与私有仓库

| 类型 | 代表 | 特点 |
|---|---|---|
| 公共镜像仓库 | Docker Hub、各云厂商公共镜像 | 使用方便，但有拉取速率限制、镜像可信度需自行判断 |
| 私有镜像仓库 | 云厂商容器镜像服务、自建 Harbor / registry | 需认证，内网拉取快，适合公司内部镜像 |
| 开源项目镜像 | 官方组织维护的镜像 | 如 .NET 官方镜像在 Microsoft 容器注册表（MCR） |

### 11.2 镜像命名规则

```text
registry/namespace/name:tag
   ↑        ↑        ↑    ↑
   │        │        │    └─ 标签，默认 latest
   │        │        └────── 镜像名
   │        └─────────────── 命名空间/组织/用户名
   └──────────────────────── 仓库地址，省略则默认 Docker Hub
```

```bash
# 省略 registry 与 namespace：等价于 docker.io/library/nginx:latest
docker pull nginx

# 完整写法
docker pull registry.example.com/team/myapp:v1.2.0

# 打标签并推送（tag 必须与目标仓库路径完全一致）
docker tag myapp:local registry.example.com/team/myapp:v1.2.0
docker login registry.example.com
docker push registry.example.com/team/myapp:v1.2.0

# 用 digest 精确锁定（比 tag 更严格，tag 可被覆盖，digest 不会）
docker pull registry.example.com/team/myapp@sha256:<digest>
```

### 11.3 `latest` 标签为什么不该用于生产

`latest` **不是「最新版本」的语义保证**，它只是「没指定 tag 时的默认值」。它可被反复覆盖，因此：

- 同一个 `myapp:latest` 在不同时间、不同机器上可能是**完全不同的镜像**；
- 出现故障时无法回答「线上跑的到底是哪个版本」，回滚无从下手；
- K8s 这类编排系统在 `imagePullPolicy` 上对 `latest` 有特殊行为，容易误判。

```bash
# 推荐：用不可变标签（语义化版本或 Git commit SHA）
docker build -t registry.example.com/team/myapp:1.2.0 -t registry.example.com/team/myapp:$(git rev-parse --short HEAD) .
docker push --all-tags registry.example.com/team/myapp
```

> [!important] 生产镜像标签规则
> **同时打两个标签**：人类可读的版本号（`1.2.0`）与机器可追溯的提交号（`sha-3f9c1ab`）。部署用提交号，沟通用版本号。

### 11.4 镜像漏洞扫描思路

镜像 = 基础镜像 + 系统包 + 语言依赖，三处都可能引入已知漏洞（CVE）。

```bash
# Docker Scout（Docker Desktop 附带）
docker scout cves myapp:1.2.0
docker scout recommendations myapp:1.2.0

# 开源替代：Trivy
trivy image --severity HIGH,CRITICAL myapp:1.2.0

# 语言层依赖审计（与镜像扫描互补）
npm audit --omit=dev
dotnet list package --vulnerable --include-transitive
pip-audit
```

持续治理的三条实践：

1. **定期重建**：基础镜像的安全更新只有重建才会进入你的镜像。设一个每月重建计划。
2. **扫描进流水线**：把高危漏洞作为 CI 的失败条件（见第 12 节与 [[工具-08-CICD入门]]）。
3. **减小攻击面**：不用 `-slim`/`alpine`/`distroless` 之外的选择时，至少删掉编译器、包管理器、curl 等运行时不必要的东西。

## 十二、容器化的边界与陷阱

### 12.1 一个容器只跑一个服务

反模式：把 nginx + PHP + cron + sshd 塞进一个容器，用 supervisor 管理。后果：

- 无法独立扩缩容（流量大的是应用，不是 cron）；
- 无法独立升级（改 nginx 配置要重启整个容器）；
- 日志混在一起，健康检查语义含糊（谁不健康？）；
- 生命周期冲突（cron 跑完退出会把容器带停）。

正确做法：拆成多个容器，用 Compose/K8s 编排；需要共享文件时用卷。

### 12.2 日志输出到 stdout

容器应该把日志写到**标准输出/标准错误**，而不是文件。原因：Docker 会捕获 stdout/stderr 并提供 `docker logs`、日志驱动（json-file、fluentd、云日志）等统一采集通道。写到容器内文件会导致日志随容器删除而丢失、无法统一采集、且磁盘被静默写满。

```javascript
// ✅ 输出 JSON 到 stdout，由平台采集
console.log(JSON.stringify({ level: "info", msg: "order.created", orderId, ts: Date.now() }));
```

```nginx
# ✅ Nginx 默认示例配置里日志写文件；容器里改成软链接到 stdout/stderr
RUN ln -sf /dev/stdout /var/log/nginx/access.log \
 && ln -sf /dev/stderr /var/log/nginx/error.log
```

### 12.3 配置通过环境变量注入

十二要素应用（Twelve-Factor App）的第三条就是「在环境中存储配置」。镜像应该**构建一次，多环境运行**：

```bash
# ✅ 同一镜像，不同环境
docker run -e NODE_ENV=staging -e DB_HOST=staging-db myapp:1.2.0
docker run -e NODE_ENV=production -e DB_HOST=prod-db   myapp:1.2.0
```

```dockerfile
# ❌ 反模式：把环境差异写进镜像
ENV DB_HOST=prod-db.internal
```

### 12.4 时区问题

**几乎所有精简基础镜像的默认时区都是 UTC**。表现：日志时间比北京时间早 8 小时，定时任务在错误的时刻执行。

```dockerfile
# 方案 A：只设 TZ 环境变量（要求基础镜像内有 tzdata）
ENV TZ=Asia/Shanghai
RUN apk add --no-cache tzdata   # alpine 需要显式装
```

```yaml
# 方案 B：Compose 中挂载宿主机时区文件（不装 tzdata）
services:
  api:
    environment:
      TZ: Asia/Shanghai
    volumes:
      - /etc/localtime:/etc/localtime:ro
```

> [!tip] 更稳的做法
> 让应用**始终以 UTC 存储和计算时间**，只在展示层做时区转换。这样容器时区是什么都不影响正确性，只有日志可读性受影响。

### 12.5 权限与非 root 用户运行

容器内默认是 root。虽然受 namespace 限制，但一旦发生逃逸或挂载了宿主机目录，root 权限意味着严重后果。而且部分编排平台（如 Kubernetes 的受限 Pod 安全标准）**直接拒绝**以 root 运行的容器。

```dockerfile
# Debian/Ubuntu 系
RUN groupadd -r app && useradd -r -g app -d /app -s /sbin/nologin app
WORKDIR /app
COPY --chown=app:app . .
USER app

# Alpine 系
RUN addgroup -S app && adduser -S app -G app
COPY --chown=app:app . .
USER app
```

```bash
# 运行时覆盖为任意非 root UID（K8s 场景常用）
docker run --user 1000:1000 myapp:1.2.0

# 更严格：禁止提权、只读根文件系统
docker run --read-only --security-opt no-new-privileges \
  --tmpfs /tmp myapp:1.2.0
```

注意：切到非 root 后，容器内需要写入的目录（上传目录、临时目录、日志目录）必须**提前 `chown`**，否则会出现 `EACCES` 报错。

### 12.6 资源限制

不限制资源的容器在异常时（内存泄漏、死循环）可以吃光宿主机资源，导致**同宿主机的其他容器一起被拖死**，甚至触发宿主机 OOM Killer。

```bash
# 内存上限 512 MB，CPU 上限 1.5 核
docker run -d --memory 512m --memory-swap 512m --cpus 1.5 myapp:1.2.0

# 查看实际限制
docker stats --no-stream
docker inspect -f '{{.HostConfig.Memory}} {{.HostConfig.NanoCpus}}' api
```

| 参数 | 含义 | 注意 |
|---|---|---|
| `--memory` | 内存硬上限 | 超出会被 OOM Killer 杀死（退出码 137） |
| `--memory-swap` | 内存 + swap 总量 | 设为与 `--memory` 相等可禁用 swap |
| `--cpus` | CPU 核数上限（可为小数） | 是配额不是预留 |
| `--cpu-shares` | 相对权重（软限制） | 仅在 CPU 争抢时生效 |
| `--pids-limit` | 进程数上限 | 防 fork 炸弹 |
| `--restart` | 重启策略 | `unless-stopped` 常用于单机服务 |

> [!warning] 退出码 137
> 容器退出码 `137` = `128 + 9`，即被 `SIGKILL`。最常见原因就是**内存超限被 OOM Killer 杀**。排查：`docker inspect -f '{{.State.OOMKilled}}' api` 返回 `true` 即确认。此时要么提高上限，要么修内存泄漏——盲目提高上限只是把问题推迟。

## 十三、CI 中构建与推送镜像的要点

核心原则与本地一致，但有四个额外注意点：

```yaml
# GitHub Actions 片段示意（概念通用，流水线设计见 [[工具-08-CICD入门]]）
- name: Build and push
  run: |
    # 1. 用 commit SHA 作为不可变标签
    IMAGE=registry.example.com/team/myapp:${GITHUB_SHA::7}
    # 2. 启用 BuildKit 与分层缓存，把缓存导出到 registry 复用
    docker build \
      --cache-from type=registry,ref=registry.example.com/team/myapp:buildcache \
      --cache-to   type=registry,ref=registry.example.com/team/myapp:buildcache,mode=max \
      -t "$IMAGE" -t registry.example.com/team/myapp:latest .
    # 3. 推送前扫描，高危即失败
    trivy image --exit-code 1 --severity CRITICAL "$IMAGE"
    # 4. 通过 CI 的凭据机制登录，不要把密码写进脚本
    echo "$REGISTRY_TOKEN" | docker login registry.example.com -u "$REGISTRY_USER" --password-stdin
    docker push --all-tags registry.example.com/team/myapp
```

| 要点 | 原因 |
|---|---|
| **绝不构建两次** | 「测试用一个镜像、部署用另一个镜像」会让通过测试的产物与线上产物不是同一个东西。构建一次，同一 digest 贯穿全流程 |
| **凭据用 CI secret** | 写进仓库 = 泄露。用 `--password-stdin` 避免密码出现在进程列表 |
| **用 registry 做构建缓存** | CI runner 每次是干净环境，本地缓存不存在，必须把缓存推到 registry |
| **构建产物要可追溯** | 标签里带 SHA，并在镜像上加 OCI 标签记录源码仓库与提交 |
| **扫描卡在推送前** | 推上去再扫描已经晚了，镜像可能已被拉取 |

## 十四、常见坑

> [!warning] 高频踩坑清单
> 1. **`CMD` 用 shell 形式** → `docker stop` 固定等 10 秒，无优雅退出。改 exec 形式。
> 2. **把数据库数据留在容器可写层** → `docker rm` 后数据全丢。用命名卷。
> 3. **`COPY . .` 不带 `.dockerignore`** → 本地 `node_modules` 覆盖镜像内依赖，构建上下文几百 MB。
> 4. **`EXPOSE` 当成发布端口** → `EXPOSE 3000` 之后仍然访问不到，必须 `-p` 或 Compose `ports`。
> 5. **`-p 80:8080` 方向写反** → 访问不到且报错莫名其妙。记法：左主机、右容器。
> 6. **`depends_on` 当作就绪等待** → 应用先于数据库就绪启动，随机崩溃。要配 `condition: service_healthy`。
> 7. **`docker compose down -v` 手滑** → 命名卷被删，数据库数据永久丢失。
> 8. **`RUN apt-get update` 与 `install` 分行** → 缓存过期导致构建随机失败，且镜像层无法变小。
> 9. **层顺序错误**：`COPY . .` 放在 `npm ci` 之前 → 改一行代码就重装全部依赖。
> 10. **开发环境把空目录挂到 `/app/node_modules`** → 依赖「消失」，模块找不到。
> 11. **镜像里用 `ENV` 写密钥** → `docker history`/`inspect` 直接可见，且永远留在层里。
> 12. **未设 `--memory`** → 内存泄漏的容器拖垮整台宿主机上所有服务。
> 13. **容器时区 UTC** → 日志时间差 8 小时，定时任务错点执行。
> 14. **以 root 运行** → 违反最小权限，部分编排平台直接拒绝启动。
> 15. **`latest` 标签部署生产** → 无法确认线上版本，无法可靠回滚。

> [!danger] 生产环境禁用清单
> - `docker system prune -a --volumes`：删除所有未使用镜像与**数据卷**。
> - `docker compose down -v`：删除项目所有命名卷。
> - `docker volume rm <name>`：删除数据卷。
> - `docker rmi -f <image>`：强制删镜像，可能影响正在运行的容器。
> - `docker kill`：直接 SIGKILL，跳过优雅退出，可能丢未落盘数据。
> - 在 Dockerfile 里执行 `curl ... | sh`：以构建权限执行远程脚本，供应链风险。
> 以上命令在**测试环境也要先确认没有重要数据**；在生产环境执行前必须确认备份已完成并有人复核。

## 十五、练习题

> [!question] 练习 1：基础命令与生命周期
> 用一条命令启动一个 alpine 容器，在里面创建 `/data/hello.txt` 写入内容，然后：
> ① 用 `docker exec` 确认文件存在；② `docker restart` 后文件还在吗？③ `docker rm` 后重新用同一镜像起容器，文件还在吗？请解释原因，并给出让文件「永远在」的改造方案。
>
> 参考思路：重启保留可写层所以文件在；`rm` 后不在，因为数据在可写层。改造方案是 `-v hello-vol:/data`。

> [!question] 练习 2：Dockerfile 优化
> 下面这个 Dockerfile 有三个可优化点，请指出并给出改进版本：
> ```dockerfile
> FROM node:20
> COPY . .
> RUN npm install
> RUN apt-get update
> RUN apt-get install -y curl
> CMD npm start
> ```
>
> 参考思路：① 基础镜像换 `node:20-slim` 或 alpine 并改多阶段；② `COPY package*.json` 前置以利用缓存；③ `apt-get update` 与 install 合并并清理，或干脆不装 curl（用 Node 自身做健康检查）；④ `CMD` 改 exec 形式 `CMD ["npm","start"]`（更好的做法是直接 `CMD ["node","server.js"]` 避免 npm 当中介进程）；⑤ 补 `.dockerignore`。

> [!question] 练习 3：Compose 编排与启动顺序
> 写一个 `compose.yaml`，包含 `api`（自建镜像）与 `db`（postgres:16-alpine）。要求：`api` 必须在 `db` 健康检查通过后才启动；`db` 的数据用命名卷持久化；`db` 的端口**不暴露**到宿主机；`api` 的内存限制 512 MB。写出完整文件并说明 `condition: service_healthy` 与 `depends_on: [db]` 的区别。

> [!question] 练习 4：信号与 PID 1
> 一个 Node 应用的容器执行 `docker stop` 总是耗时约 10 秒。请列出至少三种可能原因和对应的验证/修复手段。
>
> 参考思路：① `CMD` 为 shell 形式，`sh` 是 PID 1 且不转发信号 → 改 exec 形式；② 应用未注册 `SIGTERM` 处理器 → 在代码里 `process.on('SIGTERM', close)`；③ 应用被 `npm start` 包了一层，npm 是 PID 1 且不转发 → 直接 `CMD ["node","server.js"]`；④ 容器内有僵尸子进程堆积 → 加 `--init`。验证：`docker exec <c> ps -o pid,ppid,comm` 看谁是 PID 1。

> [!question] 练习 5：数据持久化与安全
> 团队有人把 `.env` 里的数据库密码通过 `docker build --build-arg DB_PASSWORD=...` 传进镜像并写进了配置。请说明这条路径为什么危险、如何确认是否已泄露、以及完整的补救步骤。
>
> 参考思路：`ARG` 值会记录在镜像历史中（`docker history --no-trunc`、`docker inspect` 可见），且镜像层不可变、可被推送到仓库后由他人拉取。确认方式：`docker history --no-trunc <image>`。补救：① 立即轮换数据库密码；② 从 Dockerfile 移除 `ARG`/`ENV`，改为运行时 `-e` 或 secret；③ 重新构建并**删除旧镜像标签**（旧镜像仍可从仓库按 digest 拉取，必要时联系仓库管理员清理）；④ 在 CI 中加入密钥扫描。

## 十六、FAQ

> [!question] `docker run` 和 `docker start` / `docker create` 有什么区别？
> `docker create` 只创建容器（状态 `Created`），不启动；`docker start` 启动一个已存在的容器，**保留原可写层**；`docker run` = `create` + `start`，默认每次都是**全新的容器**。所以「改了配置想重启」用 `restart`，「要干净重来」用 `run`。调试时 `docker run --rm` 能避免垃圾容器堆积。

> [!question] 镜像删不掉，报 `image is being used by running container` 怎么办？
> 说明有容器（可能是已停止的）在用这个镜像。解决顺序：`docker ps -a | grep <image>` 找到容器 → `docker rm <container>`（运行中先 `stop`）→ 再 `docker rmi <image>`。如果报 `image has dependent child images`，说明有基于它的子镜像，需要先处理子镜像，或直接用 `<repository>:<tag>` 而不是 IMAGE ID 删除。

> [!question] 容器里 `curl localhost:3000` 不通，但应用日志显示已启动，为什么？
> 应用很可能绑定到了 `127.0.0.1`。在容器内 `127.0.0.1` 只代表容器自己的回环地址，而 `-p` 的端口转发是**从外部进入容器网卡**的，需要应用监听 `0.0.0.0`。修复：把监听地址配置为 `0.0.0.0`（Node 的 `server.listen(3000, '0.0.0.0')`、ASP.NET Core 的 `ASPNETCORE_URLS=http://+:8080`）。这也解释了为什么「宿主机 curl 通、容器内 curl 不通」或反之的现象。

> [!question] 容器需要访问宿主机上的服务（比如宿主机的 MySQL），地址该写什么？
> **不要写 `localhost`**——那指向容器自己。Windows/macOS 上 Docker Desktop 提供特殊域名 `host.docker.internal`；Linux 上可以用 `--add-host=host.docker.internal:host-gateway`，或直接用宿主机在 docker0 网桥上的 IP（通常是 `172.17.0.1`）。更干净的做法是把那个服务也放进 Compose 网络里，用服务名互访。

> [!question] `alpine` 镜像里没有 `bash`，脚本跑不了怎么办？
> 两个选择：① 用 `sh`（POSIX shell）改写脚本，大多数场景 `sh` 够用；② 如果确实依赖 bash 特性，`apk add --no-cache bash`，代价是镜像变大。**不要**为了图方便把基础镜像换成完整版——更好的方向是让启动逻辑简单到 `sh` 就能胜任。

## 相关笔记

- [[后端-08-部署与运维基础]]——镜像构建完成后，如何把它放上服务器、配反向代理、做监控与回滚
- [[工具-08-CICD入门]]——在流水线中自动构建、扫描与推送镜像
- [[操作系统]]——namespace、cgroup、进程与信号、PID 1 的机制基础
- [[计算机网络]]——端口、NAT、DNS 解析与反向代理涉及的网络层概念
- [[工具-02-命令行与Shell]]——Docker 命令背后的 Shell 基础与常用运维命令

## 参考来源

- [Docker 官方文档：Get started](https://docs.docker.com/get-started/)
- [Docker 官方文档：What is a container?](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-a-container/)
- [Docker 官方文档：Building images](https://docs.docker.com/get-started/docker-concepts/building-images/)
- [Docker 官方文档：Multi-stage builds](https://docs.docker.com/build/building/multi-stage/)
- [Docker 官方文档：Dockerfile reference](https://docs.docker.com/reference/dockerfile/)
- [Docker 官方文档：Volumes](https://docs.docker.com/engine/storage/volumes/)
- [Docker 官方文档：Bind mounts](https://docs.docker.com/engine/storage/bind-mounts/)
- [Docker 官方文档：Networking overview](https://docs.docker.com/engine/network/)
- [Docker 官方文档：Compose file reference](https://docs.docker.com/reference/compose-file/)
- [Docker 官方文档：Control startup and shutdown order in Compose](https://docs.docker.com/compose/how-tos/startup-order/)
- [Docker 官方文档：Environment variables in Compose](https://docs.docker.com/compose/how-tos/environment-variables/)
- [Docker 官方文档：docker container run](https://docs.docker.com/reference/cli/docker/container/run/)
- [Kubernetes 中文文档：为 Pod 和容器管理资源](https://kubernetes.io/zh-cn/docs/concepts/configuration/manage-resources-containers/)
- [Microsoft Learn：教程 - 容器化 .NET 应用](https://learn.microsoft.com/zh-cn/dotnet/core/docker/build-container)
- 版本号与镜像标签以各官方文档最新说明为准。
