docker - 4 dockerfile

Dockerfile 是一个 文本格式的配置文件，包含一系列指令（Instruction），用于定义如何构建 Docker 镜像。通过 docker build 命令，Docker 会按指令顺序自动构建镜像，确保镜像构建过程可重复、可维护（“一次编写，到处运行”）。

一、核心概念

• 镜像（Image）：通过 Dockerfile 构建的只读模板，包含运行应用所需的代码、依赖、环境变量、配置等；
• 容器（Container）：镜像的可运行实例（镜像与容器的关系类似“类与对象”）；
• Dockerfile 指令：大小写不敏感，但约定 大写 书写（区分指令与参数），按顺序执行，前一条指令的结果会作为后一条的基础（分层构建）。

二、Dockerfile 基础结构

一个标准的 Dockerfile 包含 4 类核心内容：

1. 基础镜像（必填）：指定构建的基础镜像（如 nginx、dotnet 等）；
2. 环境配置：设置环境变量、工作目录、依赖安装等；
3. 应用部署：复制应用代码/文件到镜像中；
4. 启动命令（必填）：定义容器启动时执行的命令。

三、核心指令详解（按常用程度排序）

指令详解

Dockerfile 指令	说明
FROM	指定基础镜像，用于后续的指令构建。
MAINTAINER	指定Dockerfile的作者/维护者。（已弃用，推荐使用LABEL指令）
LABEL	添加镜像的元数据，使用键值对的形式。
RUN	在构建过程中在镜像中执行命令。
CMD	指定容器创建时的默认命令。（可以被覆盖）
ENTRYPOINT	设置容器创建时的主要命令。（不可被覆盖）
EXPOSE	声明容器运行时监听的特定网络端口。
ENV	在容器内部设置环境变量。
ADD	将文件、目录或远程URL复制到镜像中。
COPY	将文件或目录复制到镜像中。
VOLUME	为容器创建挂载点或声明卷。
WORKDIR	设置后续指令的工作目录。
USER	指定后续指令的用户上下文。
ARG	定义在构建过程中传递给构建器的变量，可使用 "docker build" 命令设置。
ONBUILD	当该镜像被用作另一个构建过程的基础时，添加触发器。
STOPSIGNAL	设置发送给容器以退出的系统调用信号。
HEALTHCHECK	定义周期性检查容器健康状态的命令。
SHELL	覆盖Docker中默认的shell，用于RUN、CMD和ENTRYPOINT指令。

1. FROM（必填）

指定基础镜像（所有指令的起点，必须是 Dockerfile 第一条指令），格式：

FROM <镜像名>:<标签>  # 标签必填（如无特殊需求，避免用 latest）

• 示例：

  FROM nginx:1.25          # 基于 Nginx 1.25 镜像
  FROM mcr.microsoft.com/dotnet/aspnet:8.0  # 基于 .NET 8 运行时镜像
  FROM alpine:3.19         # 基于轻量 Alpine 镜像（适合精简镜像）
  

• 特殊用法（多阶段构建）：

  # 构建阶段（使用 SDK 镜像编译代码）
  FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
  # 运行阶段（使用轻量运行时镜像，仅包含运行依赖）
  FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
  

2. WORKDIR（推荐）

设置容器内的 工作目录（后续 COPY、RUN、CMD 等指令的默认路径），指的是 Docker容器内部的文件系统路径，不是windows或者linux 。
格式：

WORKDIR /app  # 路径不存在会自动创建

• 优势：避免使用 cd 命令（易出错），统一指令执行上下文，示例：

  WORKDIR /app
  COPY ./bin/Release/net8.0/publish/ .  # 等价于 COPY ./bin/... /app/
  

3. COPY（常用）

将 主机文件/目录 复制到镜像的指定路径，格式：

COPY <主机源路径> <镜像目标路径>

• 关键说明：
  • 源路径：相对路径（相对于 docker build 命令的执行目录，即“构建上下文”）；
  • 目标路径：不存在会自动创建；
  • 支持通配符（如 COPY ./src/*.dll /app/）；
• 示例：

  COPY ./appsettings.json /app/  # 复制单个文件
  COPY ./bin/Release/net8.0/publish/ /app/  # 复制目录下所有文件（结尾 / 表示复制目录内容，不含目录本身）
  

4. RUN（常用）

在构建镜像时执行命令（如安装依赖、编译代码），格式：

# shell 格式（类似终端执行命令）
RUN <命令>
# exec 格式（推荐，避免 shell 解析问题，信号传递更友好）
RUN ["可执行文件", "参数1", "参数2"]

• 示例：

  # 安装依赖（Alpine 系统）
  RUN apk add --no-cache curl git
  # 编译 .NET 代码（多命令用 && 连接，减少镜像层数）
  RUN dotnet restore && dotnet build -c Release && dotnet publish -c Release -o /app
  

• 最佳实践：合并多条命令为一条（Docker 镜像是分层存储，每一条 RUN 新增一层，层数过多会导致镜像变大）。

5. CMD（必填）

定义容器 启动时 执行的命令（仅能有一条 CMD，多条则最后一条生效），格式：

# shell 格式
CMD <命令>
# exec 格式（推荐）
CMD ["可执行文件", "参数1", "参数2"]

• 示例：

  # 启动 Nginx（exec 格式）
  CMD ["nginx", "-g", "daemon off;"]
  # 启动 .NET 应用（exec 格式）
  CMD ["dotnet", "MyApp.dll"]
  

• 注意：CMD 可被 docker run 命令后的参数覆盖（如 docker run my-app dotnet MyApp.Debug.dll）。

6. EXPOSE（推荐）

声明容器运行时对外暴露的端口（仅为文档说明，不实际映射端口，映射需通过 docker run -p 或 Compose ports），格式：

EXPOSE <端口号>[/协议]  # 协议默认 TCP

• 示例：

  EXPOSE 80  # TCP 80 端口
  EXPOSE 53/udp  # UDP 53 端口
  

7. ENV（常用）

设置环境变量（构建阶段和运行阶段均生效，可被后续指令引用），格式：

# 单条设置
ENV <键>=<值>
# 多条设置（换行分隔）
ENV <键1>=<值1> \<键2>=<值2>

• 示例：

  ENV ASPNETCORE_ENVIRONMENT=Production \CONNECTION_STRING=server=mysql:3306;database=myapp
  # 后续指令引用
  RUN echo "Environment: $ASPNETCORE_ENVIRONMENT"
  

8. ENTRYPOINT（可选）

定义容器的 入口点（类似 CMD，但不可被 docker run 命令直接覆盖，仅能通过 --entrypoint 参数覆盖），格式：

# exec 格式（推荐）
ENTRYPOINT ["可执行文件", "参数1"]
# shell 格式
ENTRYPOINT <命令>

• 用途：固定容器启动的核心程序（如 dotnet），CMD 仅传递参数，示例：

  ENTRYPOINT ["dotnet"]  # 固定入口点为 dotnet
  CMD ["MyApp.dll"]      # 启动参数（可被覆盖，如 docker run my-app OtherApp.dll）
  

9. VOLUME（可选）

声明容器的 数据卷挂载点（用于持久化数据，避免容器销毁时数据丢失），格式：

VOLUME <容器内路径>  # 或 ["路径1", "路径2"]

• 示例：

  VOLUME /app/data  # 容器内 /app/data 目录会被挂载为数据卷
  

• 注意：VOLUME 仅声明挂载点，实际挂载需通过 docker run -v 或 Compose volumes 指定主机路径/命名卷。

10. USER（可选）

指定容器运行时的用户（默认 root，生产环境推荐使用非 root 用户，提升安全性），格式：

USER <用户名|UID>[:<组名|GID>]

• 示例（.NET 应用）：

  # 创建非 root 用户
  RUN adduser --disabled-password --gecos "" appuser
  # 切换用户
  USER appuser
  # 后续命令和容器运行均使用 appuser
  CMD ["dotnet", "MyApp.dll"]
  

11. LABEL（可选）

为镜像添加元数据标签（如作者、版本、描述），便于镜像管理，格式：

LABEL <键>=<值>
# 多条标签（换行分隔）
LABEL author="dev@example.com" \version="1.0.0" \description="ASP.NET Core API 镜像"

• 查看标签：docker inspect <镜像名>

12. ARG（可选）

定义 构建阶段 的变量（仅在 docker build 时生效，运行阶段不生效），可通过 docker build --build-arg <键>=<值> 传递参数，格式：

# 定义变量（可指定默认值）
ARG <键>[=<默认值>]

• 示例（多环境构建）：

  ARG BUILD_ENV=Release
  # 构建时使用变量
  RUN dotnet publish -c $BUILD_ENV -o /app
  

• 构建命令：docker build --build-arg BUILD_ENV=Debug -t my-app:debug .

四、.NET 应用 Dockerfile 生产环境示例（多阶段构建）

多阶段构建是生产环境的核心最佳实践：构建阶段使用 SDK 镜像编译代码，运行阶段使用轻量运行时镜像，大幅减小最终镜像体积（从数百 MB 压缩到数十 MB）。

完整示例（ASP.NET Core 8.0 API）

# ==================== 构建阶段（Build Stage）====================
# 基于 .NET 8 SDK 镜像（包含编译工具）
FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
# 设置工作目录
WORKDIR /src
# 复制项目文件（.csproj）并还原依赖（利用 Docker 缓存，仅项目文件变更时重新还原）
COPY ["MyApp.Api/MyApp.Api.csproj", "MyApp.Api/"]
COPY ["MyApp.Service/MyApp.Service.csproj", "MyApp.Service/"]
RUN dotnet restore "MyApp.Api/MyApp.Api.csproj"
# 复制所有源代码
COPY . .
# 编译项目（Release 模式）并发布到 /app/publish 目录
RUN dotnet build "MyApp.Api/MyApp.Api.csproj" -c Release -o /app/build
RUN dotnet publish "MyApp.Api/MyApp.Api.csproj" -c Release -o /app/publish# ==================== 运行阶段（Runtime Stage）====================
# 基于 .NET 8 运行时镜像（仅包含运行依赖，轻量）
FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS runtime
# 设置非 root 用户（提升安全性）
RUN adduser --disabled-password --gecos "" appuser
# 环境变量配置
ENV ASPNETCORE_ENVIRONMENT=Production \ASPNETCORE_URLS=http://+:80  # 监听 80 端口
# 暴露端口
EXPOSE 80
# 设置工作目录
WORKDIR /app
# 从构建阶段复制发布文件到运行阶段
COPY --from=build /app/publish .
# 切换非 root 用户
USER appuser
# 启动命令（exec 格式）
ENTRYPOINT ["dotnet", "MyApp.Api.dll"]

构建命令

# 构建镜像（标签：my-app:1.0.0）
docker build -t my-app:1.0.0 .# 运行容器（端口映射 8080:80）
docker run -d -p 8080:80 --name my-api my-app:1.0.0

五、生产环境最佳实践

1. 采用多阶段构建

• 构建阶段：使用 sdk 镜像（如 dotnet/sdk、node:18），仅用于编译、打包；
• 运行阶段：使用轻量镜像（如 dotnet/aspnet、alpine），仅包含运行依赖，减少镜像体积和攻击面。

2. 优化镜像缓存

Docker 构建时会缓存每一层，按以下顺序排列指令，最大化利用缓存：

1. FROM（基础镜像，变更少）；
2. ENV/ARG（环境变量，变更少）；
3. COPY 项目文件（.csproj、package.json 等，变更频率低于源代码）；
4. RUN 还原依赖（仅项目文件变更时重新执行）；
5. COPY 源代码（变更频繁）；
6. RUN 编译/发布（源代码变更时重新执行）。

3. 使用非 root 用户

• 避免容器以 root 权限运行，防止恶意程序篡改主机系统；
• 示例（Alpine 系统）：RUN adduser -D appuser && USER appuser。

4. 精简镜像内容

• 安装依赖后清理缓存（如 apt-get clean、apk add --no-cache）；
• 不包含无用文件（如源代码、编译中间产物、日志文件）。

5. 固定镜像标签

• FROM 指令中指定具体标签（如 dotnet/aspnet:8.0），禁止使用 latest（避免自动拉取新版本导致兼容性问题）。

6. 配置健康检查

通过 HEALTHCHECK 指令（或 Compose healthcheck）确保容器内服务可用：

# 健康检查（每 30 秒检查一次，超时 10 秒，连续 3 次失败标记为不健康）
HEALTHCHECK --interval=30s --timeout=10s --retries=3 \CMD curl -f http://localhost:80/health || exit 1

7. 避免在镜像中存储敏感信息

• 敏感数据（如密码、密钥）通过 ENV 环境变量、Docker Secrets 或外部配置中心注入，不直接写在 Dockerfile 中；
• 示例：ENV DB_PASSWORD_FILE=/run/secrets/db-password（读取密钥文件）。

六、常见问题排查

1. 构建失败：找不到文件

   • 检查 COPY 源路径是否相对于构建上下文（docker build 命令后的 . 表示当前目录为上下文）；
   • 确认文件路径大小写是否匹配（Linux 镜像区分大小写）。

2. 镜像体积过大

   • 未使用多阶段构建（保留了 SDK 镜像的编译工具）；
   • 多条 RUN 指令未合并（新增过多镜像层）；
   • 未清理依赖缓存（如 apt-get update 后未 apt-get clean）。

3. 容器启动失败：权限不足

   • 非 root 用户运行时，容器内工作目录/文件权限不足，需在构建阶段设置权限：

     RUN chown -R appuser:appuser /app  # 授予 appuser 对 /app 目录的权限
     

4. .NET 应用启动后无法访问

   • 未设置 ASPNETCORE_URLS=http://+:80（默认仅监听 localhost，容器外部无法访问）；
   • 未暴露端口（EXPOSE 80）或未映射端口（docker run -p）。

总结

Dockerfile 是构建 Docker 镜像的核心，掌握指令语法和生产环境最佳实践（多阶段构建、非 root 用户、缓存优化、精简镜像）是部署高可用、可维护应用的关键。

对于 .NET 开发者，上述多阶段构建示例可直接适配 ASP.NET Core 6+/8+ 应用，配合 Docker Compose 可实现“镜像构建+多容器编排”的全流程自动化部署，是单机/小型集群生产环境的最优方案。