Docker 入门与实战

一、为什么要用 Docker#

传统部署把依赖直接装在宿主机上：Python 版本、JDK 版本、系统动态库、环境变量，全都散落在服务器上。当同一台机器跑多个服务，或者开发、测试、生产由不同的人维护时，环境差异必然变成故障来源。典型症状：开发机是 Ubuntu 22.04、服务器是 CentOS 7，编译出的二进制跑不起来；本地 Node 18、CI 上 Node 16，锁文件解析结果不同；服务器上有人手工升级过 OpenSSL，另一个服务因此挂掉；新人配环境配一整天，还是缺某个 libssl。

Docker 的答案是：把应用和依赖一起打包成镜像，镜像在任何装了 Docker 的机器上以容器形式运行。它解决的不是性能问题，而是交付一致性问题。

二、三个核心概念#

• 镜像 (Image)：只读模板，等价于”类”或”安装包”。它由一层层只读文件系统叠加而成，每层对应 Dockerfile 中的一条构建指令。
• 容器 (Container)：镜像的运行实例，等价于”对象”。启动时在镜像最上层加一个可写层，容器内所有写入都落在可写层，镜像本身永不变。
• 仓库 (Registry)：集中存放和分发镜像的服务，等价于”应用商店”。默认是 Docker Hub，企业内常用 Harbor、云厂商的 ACR、TCR。

1
Dockerfile --docker build--> Image --docker push--> Registry
2
                                     ^                     |
3
                                     |---- docker pull ----|
4
Container <--docker run-- Image <----+

由此可以直接推出几条结论：删容器不影响镜像，删镜像也不影响仓库里的副本；基于同一个镜像可以启动无数个互不干扰的容器；容器内改文件默认不持久，删容器即丢失，这正是数据卷要解决的问题；镜像分层是共享的，本地十个基于 node:20-alpine 的镜像，基础层在磁盘上只存一份。

三、安装与基本配置#

1
sudo apt-get update && sudo apt-get install -y ca-certificates curl gnupg && sudo install -m 0755 -d /etc/apt/keyrings
2
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
3
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
4
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
5
sudo usermod -aG docker $USER   # 免 sudo，需重新登录生效

1
{
2
  "registry-mirrors": [
3
    "https://docker.m.daocloud.io",
4
    "https://dockerproxy.com",
5
    "https://mirror.ccs.tencentyun.com"
6
  ],
7
  "log-driver": "json-file",
8
  "log-opts": { "max-size": "50m", "max-file": "3" }
9
}

1
sudo systemctl daemon-reload && sudo systemctl restart docker

1
docker version && docker info && docker run --rm hello-world   # 版本 / 环境信息 / 冒烟测试

四、镜像操作命令#

1
docker pull nginx:1.27-alpine                    # 不写标签默认 latest，生产禁用
2
docker pull --platform linux/amd64 openjdk:17-slim
3
docker images                                    # -f dangling=true 只看悬空镜像
4
docker history nginx:1.27-alpine                 # 构建历史与每层大小
5
docker rmi nginx:1.27-alpine                     # 删除；image prune -a 清理未使用镜像
6
docker tag myapp:1.0 registry.example.com/team/myapp:1.0   # 不复制数据，只加引用名
7
docker login registry.example.com && docker push registry.example.com/team/myapp:1.0
8
docker inspect nginx:1.27-alpine                 # 完整元数据
9
docker inspect -f '{{json .Config.ExposedPorts}}' nginx:1.27-alpine   # Go 模板抽取字段

导入导出要区分两对命令：save/load 传输镜像（保留分层与标签，用于离线环境），export/import 传输容器文件系统（丢失历史分层，一般只用于制作极简基础镜像）。

1
docker save -o myapp-1.0.tar myapp:1.0 && docker load -i myapp-1.0.tar
2
docker export -o container-fs.tar my-running-container && docker import container-fs.tar myapp:from-container

五、容器生命周期命令#

生命周期是：创建 → 启动 → 运行 → 停止 → 重启 → 删除。多数时候 docker run 一步到位，但排查时每个阶段都用得上。

1
docker run -d --name web nginx:1.27-alpine   # 创建并启动；docker create 只创建不启动
2
docker ps                                    # 运行中；-a 含已退出，-aq 只输出 ID
3
docker start web && docker stop web          # stop 先发 SIGTERM，默认 10 秒后 SIGKILL
4
docker kill web                              # 直接强杀；docker restart 重启
5
docker rm web && docker rm -f web            # -f 强制删除运行中的容器
6
docker container prune                       # 清理已退出的容器
7
docker top web && docker port web && docker diff web   # 进程 / 端口映射 / 文件系统改动

1
docker run -d --name my-api \
2
  -p 8080:80 -v /data/api:/app/data \
3
  -e TZ=Asia/Shanghai \
4
  --restart unless-stopped --network app-net \
5
  --memory 512m --cpus 1.0 \
6
  registry.example.com/team/my-api:1.2.0

1
docker exec -it web sh             # alpine 没有 bash；-u root 可提权进入
2
docker logs -f --tail 100 -t web   # -t 带时间戳，-f 持续跟踪
3
docker stats                       # 实时资源占用，Ctrl+C 退出；--no-stream 只采样一次
4
docker cp web:/etc/nginx/nginx.conf ./nginx.conf.bak   # 双向复制，参数顺序反过来即可

六、Dockerfile 详解#

Dockerfile 是一串指令，每条指令产生一个镜像层。理解”在构建期还是运行期生效”是写好它的前提。

1
FROM node:20.11-alpine3.19              # 固定版本与架构标签，禁止 latest
2
ARG NPM_REGISTRY=https://registry.npmmirror.com   # 仅构建期可见
3
ENV NODE_ENV=production TZ=Asia/Shanghai          # 会写进镜像，运行期可见
4
WORKDIR /app                                      # 自动创建目录
5
COPY --chown=node:node package.json package-lock.json ./
6
COPY --from=builder /app/dist ./dist    # 从多阶段构建的前序阶段复制产物
7
ADD app.tar.gz /app/                    # 额外支持 URL 与自动解压，非必要不用
8
EXPOSE 8080
9
VOLUME ["/app/data"]
10
RUN addgroup -S app && adduser -S app -G app
11
USER app                                # 切换到非 root 用户

1
CMD ["node", "server.js"]              # 单独用时：docker run myimg ls 会绕过应用
2
ENTRYPOINT ["node", "server.js"]       # 单独用时：run 的追加参数会被追加到其后
3
ENTRYPOINT ["node", "server.js"]       # 组合，推荐
4
CMD ["--port", "8080"]                 # 默认参数，命令行传参时整体替换

七、构建镜像#

1
docker build -t myapp:1.0 .                            # 当前目录为上下文
2
docker build -f docker/Dockerfile.prod -t myapp:1.0 .  # 指定 Dockerfile
3
docker build --build-arg NPM_REGISTRY=https://registry.npmmirror.com -t myapp:1.0 .
4
docker build --target builder -t myapp:debug .         # 只构建指定阶段
5
docker build --no-cache -t myapp:1.0 .                 # 强制重建，不走缓存
6
docker buildx build --platform linux/amd64,linux/arm64 -t registry.example.com/team/myapp:1.0 --push .

1
node_modules
2
.git
3
dist
4
.env
5
*.log
6
Dockerfile
7
README.md

1
# 慢：任何文件变动都让后面的层全部失效
2
FROM node:20-alpine
3
WORKDIR /app
4
COPY . .
5
RUN npm ci
6
CMD ["npm", "start"]
7

8
# 快：依赖清单没变就命中缓存，改代码只重建最后一层
9
FROM node:20-alpine
10
WORKDIR /app
11
COPY package.json package-lock.json ./
12
RUN npm ci
13
COPY . .
14
CMD ["npm", "start"]

八、数据持久化#

容器可写层随容器生命周期存亡，删容器即丢数据。持久化有两条路：数据卷 (volume) 与绑定挂载 (bind mount)。

1
docker volume create pgdata
2
docker run -d --name pg -v pgdata:/var/lib/postgresql/data postgres:16-alpine    # 数据卷
3
docker run -d --name web -v /opt/site:/usr/share/nginx/html:ro nginx:1.27-alpine # 绑定挂载，:ro 只读
4
docker run -d --tmpfs /tmp:rw,size=64m nginx:1.27-alpine                         # tmpfs，只在内存

选型结论：生产环境的数据一律用数据卷（生命周期清晰、跨平台一致、便于备份）；开发环境挂载源码或配置文件用绑定挂载（改文件立即生效，无需重建镜像）。只写容器路径不写卷名会创建匿名卷，名字随机、难以管理，应尽量避免。管理命令本身很轻：docker volume ls 列出，docker volume inspect pgdata 看挂载点与使用它的容器，docker volume rm 删除（必须先停止并删除使用它的容器），docker volume prune 清理所有未被使用的卷。

备份与恢复的标准做法是起一个临时容器，把卷和宿主机目录同时挂进去打 tar 包，不依赖宿主机上卷的实际路径：

1
docker run --rm -v pgdata:/data -v "$PWD":/backup alpine:3.20 tar czf /backup/pgdata-$(date +%Y%m%d).tar.gz -C /data .
2
docker run --rm -v pgdata:/data -v "$PWD":/backup alpine:3.20 sh -c "rm -rf /data/* && tar xzf /backup/pgdata-20260911.tar.gz -C /data"

数据库类容器应先保证数据一致：PostgreSQL 用 pg_dump 做逻辑备份更安全，直接打包数据目录属于物理备份，必须在数据库停止或快照一致的前提下执行。

九、网络#

默认 bridge 下的容器只能通过 IP 互访，而 IP 随容器重建变化，因此不可用于服务间调用。自定义网络提供内置 DNS，容器名就是主机名：

1
docker network create --driver bridge app-net          # 也可加 --subnet 172.28.0.0/16
2
docker run -d --name db --network app-net -e POSTGRES_PASSWORD=secret postgres:16-alpine
3
docker run -d --name api --network app-net -p 8080:8080 my-api:1.0
4
docker exec -it api sh -c "nc -zv db 5432"    # 直接用容器名访问数据库
5
docker network connect app-net-2 api          # 把运行中的容器接入另一个网络
6
docker network disconnect app-net api

同一自定义网络内的容器用容器名或网络别名互访；不同网络的容器默认完全隔离。这也是做环境隔离的基础——把生产容器和测试容器放进不同网络。排查时常用下面这些手段：

1
docker run --rm --network app-net nicolaka/netshoot ping -c 2 db   # 临时容器测连通性
2
docker exec -it api cat /etc/resolv.conf                           # 容器内 DNS 配置
3
docker inspect -f '{{json .NetworkSettings.Networks}}' api

十、多阶段构建#

多阶段构建解决”构建时需要的工具链不该出现在运行镜像里”的矛盾：同一个 Dockerfile 里可以有多个 FROM，每个 FROM 开启一个新阶段，阶段之间用 COPY --from= 传递产物。单阶段写法把完整工具链、npm 缓存、devDependencies 和 .git 全部塞进镜像，通常 1GB 以上；改为多阶段后运行镜像仅保留生产依赖与构建产物：

1
FROM node:20.11-alpine3.19 AS builder
2
WORKDIR /app
3
COPY package.json package-lock.json ./
4
RUN npm ci --include=dev && npm cache clean --force
5
COPY . .
6
RUN npm run build
7

8
FROM node:20.11-alpine3.19 AS runner
9
WORKDIR /app
10
ENV NODE_ENV=production TZ=Asia/Shanghai
11
COPY package.json package-lock.json ./
12
RUN npm ci --omit=dev && npm cache clean --force          # 只装生产依赖
13
COPY --from=builder /app/dist ./dist                      # 只复制构建产物
14
RUN addgroup -S nodejs && adduser -S nodejs -G nodejs && chown -R nodejs:nodejs /app
15
USER nodejs
16
EXPOSE 3000
17
CMD ["node", "dist/server.js"]

体积可降到 150MB 左右；换成 distroless 基础镜像后能压到 100MB 以内。Java 应用同理：单阶段的 Maven 构建镜像会把 Maven、本地仓库、JDK 全带进去（通常 800MB 到 1GB），改为 Maven 构建、JRE 运行，并用 Spring Boot 的 layertools 把 fat jar 拆成四层，业务代码改动只让最后一层失效，依赖层几乎总能命中缓存：

1
FROM maven:3.9-eclipse-temurin-17 AS builder
2
WORKDIR /build
3
COPY pom.xml .
4
RUN mvn -B dependency:go-offline                          # 依赖先行，利用层缓存
5
COPY src ./src
6
RUN mvn -B clean package -DskipTests
7
RUN java -Djarmode=layertools -jar target/app.jar extract
8

9
FROM eclipse-temurin:17-jre-alpine AS runner
10
RUN addgroup -S spring && adduser -S spring -G spring
11
WORKDIR /app
12
USER spring:spring
13
COPY --from=builder --chown=spring:spring /build/extracted/dependencies/ ./
14
COPY --from=builder --chown=spring:spring /build/extracted/spring-boot-loader/ ./
15
COPY --from=builder --chown=spring:spring /build/extracted/snapshot-dependencies/ ./
16
COPY --from=builder --chown=spring:spring /build/extracted/application/ ./
17
ENV JAVA_OPTS="-XX:MaxRAMPercentage=75.0 -Duser.timezone=Asia/Shanghai"
18
ENTRYPOINT ["sh", "-c", "exec java $JAVA_OPTS org.springframework.boot.loader.launch.JarLauncher"]

ENTRYPOINT 里的 exec 前缀是必要的，否则 java 进程不是 PID 1，收不到 SIGTERM，优雅停机不会执行。

十一、实战：容器化一个 React (Vite) 应用#

目标是把 Vite 构建的 SPA 打包成 Nginx 静态托管镜像，支持前端路由 history 模式，并暴露健康检查端点。项目根目录下放 Dockerfile、nginx.conf 和 .dockerignore（内容见第七节）。

1
# ---------- 阶段一：构建静态资源 ----------
2
FROM node:20.11-alpine3.19 AS builder
3
WORKDIR /app
4
ARG VITE_API_BASE_URL=/api                 # Vite 只把 VITE_ 前缀的变量内联进产物
5
ENV VITE_API_BASE_URL=$VITE_API_BASE_URL
6
COPY package.json package-lock.json ./
7
RUN npm ci && npm cache clean --force
8
COPY . .
9
RUN npm run build
10

11
# ---------- 阶段二：Nginx 托管 ----------
12
FROM nginx:1.27-alpine AS runner
13
RUN rm -f /etc/nginx/conf.d/default.conf
14
COPY nginx.conf /etc/nginx/conf.d/app.conf
15
COPY --from=builder /app/dist /usr/share/nginx/html
16
# 非 root 用户不能监听 1024 以下端口，容器内改听 8080，对外端口由宿主机决定
17
RUN chown -R nginx:nginx /usr/share/nginx/html /var/cache/nginx /var/log/nginx && touch /tmp/nginx.pid && chown nginx:nginx /tmp/nginx.pid
18
USER nginx
19
EXPOSE 8080
20
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 CMD wget -qO- http://127.0.0.1:8080/healthz || exit 1
21
CMD ["nginx", "-g", "daemon off;"]

nginx.conf：

1
server {
2
    listen       8080;
3
    server_name  _;
4
    root   /usr/share/nginx/html;
5

6
    gzip on;
7
    gzip_comp_level 5;
8
    gzip_types text/plain text/css application/json application/javascript image/svg+xml;
9

10
    location ^~ /assets/ {                 # 带 hash 的资源可长期缓存
11
        expires 1y;
12
        add_header Cache-Control "public, immutable";
13
    }
14
    location = /index.html {               # 不缓存，保证发版后拿到最新资源引用
15
        add_header Cache-Control "no-cache, no-store, must-revalidate";
16
    }
17
    location = /healthz {                  # 健康检查端点
18
        add_header Content-Type text/plain;
19
        return 200 "ok\n";
20
    }
21
    location / {                           # SPA history 模式回退
22
        try_files $uri $uri/ /index.html;
23
    }
24
    location /api/ {                       # 反向代理后端，避免浏览器跨域
25
        proxy_pass         http://backend:8080/;
26
        proxy_set_header   Host              $host;
27
        proxy_set_header   X-Real-IP         $remote_addr;
28
        proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
29
    }
30

31
}

构建、运行与验证：

1
docker build -t my-react-app:1.0 .
2
docker run -d --name my-react-app -p 8080:8080 --restart unless-stopped my-react-app:1.0
3
curl -I http://127.0.0.1:8080/healthz          # 健康检查端点
4
curl -I http://127.0.0.1:8080/some/deep/route  # 验证 history 路由回退

用 Compose 编排前后端，proxy_pass http://backend:8080/ 中的 backend 就是服务名，同一自定义网络内由内置 DNS 解析，不需要写死 IP：

同一套镜像也可以用 Compose 编排，proxy_pass http://backend:8080/ 中的 backend 就是服务名，由内置 DNS 解析，不需要写死 IP：

1
services:
2
  backend:
3
    image: registry.example.com/team/my-api:1.2.0
4
    networks: [app-net]
5
  frontend:
6
    build: { context: ., args: { VITE_API_BASE_URL: /api } }
7
    ports: ["80:8080"]
8
    depends_on:
9
      backend: { condition: service_healthy }
10
    networks: [app-net]
11
networks:
12
  app-net: { driver: bridge }

至于体积收益：同样的应用单阶段打包是 1.1GB（node:20），多阶段换 node:20-alpine 后约 150MB，改成 Nginx 托管静态产物只需 45MB（nginx:1.27-alpine），再裁剪到 distroless 可压到 30MB。

十二、生产最佳实践#

镜像瘦身。 优先用 alpine、slim 或 distroless 基础镜像，distroless 连 shell 都没有，攻击面最小，代价是排障时无法 docker exec sh，只能靠日志与健康检查。nginx:1.27-alpine 只有 45MB 而 nginx:1.27 有 190MB，差距全部来自基础镜像。安装与清理必须放在同一条 RUN 里，否则清理动作落在单独一层而失效，标准写法是 RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl && rm -rf /var/lib/apt/lists/*。

非 root 用户。 默认以 root 运行意味着容器内进程逃逸后直接拥有宿主机 root 权限。基础镜像自带非 root 用户时直接 USER node；否则自己创建（alpine 用 RUN addgroup -S app && adduser -S app -G app，Debian 用 useradd -r -u 10001 -m appuser），再 USER app。运行期也能用 --user 1000:1000 覆盖，但要注意挂载卷的属主，卷属主是 root 时会报权限错误。

固定基础镜像版本。 禁止 FROM node:latest，内容会漂移，今天构建成功明天可能失败。至少固定到次版本（node:20.11.1-alpine3.19），最严格是锁定 digest，形如 FROM node@sha256:7f5c9b3a...，代价是安全更新也不会自动进来，需要配合自动化的依赖升级流程。

分层缓存优化。 依赖清单先行、源码最后复制；不常变的 ENV、ARG 放前面；apt-get install 集中写在一条指令里。CI 中启用 BuildKit 的缓存与 secret 挂载，依赖下载目录可跨构建复用且不会进入镜像层：在 Dockerfile 首行加 # syntax=docker/dockerfile:1.7，把安装命令写成 RUN --mount=type=cache,target=/root/.npm --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci --registry=https://registry.example.com，构建时用 docker build --secret id=npmrc,src=$HOME/.npmrc -t app:1.0 . 传入私服凭证。

健康检查。 --interval 检查间隔、--timeout 单次超时、--start-period 启动宽限期（期内失败不计入 --retries）、--retries 连续失败多少次标记 unhealthy。典型写法 HEALTHCHECK --interval=30s --timeout=3s --start-period=40s --retries=3 CMD curl -fsS http://127.0.0.1:8080/health || exit 1。健康检查只标记状态，Docker 本身不会重启 unhealthy 的容器，需要配合 Compose 的 depends_on: condition: service_healthy 或编排平台的探针来驱动重启与流量摘除。

日志处理。 默认的 json-file 驱动不做轮转，长时间运行会把 /var/lib/docker 撑满磁盘，这是最常见的生产事故。在 daemon.json 中把 log-driver 设为 json-file 并加上 log-opts 的 max-size: 50m 与 max-file: 3 即可限制单容器日志体积。更完整的方案是接 fluentd、gelf 或 syslog 驱动，把日志送到 ELK、Loki 之类的集中式系统。

其他容易忽略的点。 docker stop 默认超时 10 秒，应用优雅关闭更久时应显式 docker stop -t 30。容器内只跑一个前台进程，用 supervisord 塞多进程会带来信号转发和僵尸进程问题，正确做法是拆成多个容器。需要写入的目录声明为 VOLUME 或挂载卷，保持容器无状态才能随时重建。用 --read-only 加 --tmpfs /tmp 运行可显著降低被写入攻击的风险，前提是应用不写文件系统。

十三、常见问题排查#

1
docker ps -a                             # 看 EXIT CODE
2
docker logs --tail 100 容器名
3
docker inspect -f '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}' 容器名
4
docker run -it --entrypoint sh 镜像名    # 覆盖入口进容器查环境

1
docker system df                   # 总览各部分占用，-v 看明细
2
docker system prune                # 安全清理：停止的容器、未使用网络、悬空镜像、构建缓存
3
docker system prune -a --volumes   # 更彻底，含未被使用的镜像与卷
4
docker container prune && docker image prune -a && docker volume prune
5
docker builder prune --keep-storage 10GB

十四、命令速查表#