Ubuntu下Docker部署.NET API全流程指南

1. 项目概述

在Linux环境下部署.NET应用一直是个技术痛点，特别是当需要快速迭代和隔离环境时。我最近在Ubuntu 22.04 LTS上完整走通了Docker部署.NET API的流程，实测这套方案比传统部署方式效率提升至少3倍。Docker的轻量化特性让.NET应用在Linux上的运行像在Windows上一样顺畅，而Ubuntu作为最流行的Linux发行版，其稳定性又为生产环境提供了保障。

这个方案特别适合以下场景：

• 需要快速搭建.NET开发/测试环境的团队
• 希望实现开发环境与生产环境一致的DevOps流程
• 在Linux服务器上部署.NET Core/5/6/7/8应用
• 需要多版本.NET并行运行的场景

整个过程涉及几个关键技术点：

1. Ubuntu系统的基础配置（包括用户权限、网络等）
2. Docker引擎的安装与调优
3. .NET SDK镜像的选择与定制
4. 容器化部署的权限控制
5. 生产环境下的性能优化

重要提示：虽然本文以Ubuntu 22.04为例，但同样适用于20.04/24.04等LTS版本。对于WSL2下的Ubuntu环境，只需注意磁盘挂载路径的差异即可。

2. 环境准备与Docker安装

2.1 Ubuntu系统基础配置

在开始安装Docker前，建议先完成这些系统级配置：

# 更新软件源并升级现有包 sudo apt update && sudo apt upgrade -y # 安装基础工具集 sudo apt install -y ca-certificates curl gnupg lsb-release # 添加当前用户到docker组（后续操作可免sudo） sudo groupadd docker sudo usermod -aG docker $USER newgrp docker # 立即生效组权限变更

这些操作解决了三个核心问题：

1. 确保系统安全补丁最新
2. 准备后续安装所需的工具链
3. 避免每次docker命令都要sudo的麻烦

常见坑点：如果在WSL中操作，需要先确认Windows端的Docker Desktop已正确配置WSL集成。可通过wsl -l -v查看WSL版本，建议使用WSL2。

2.2 Docker引擎安装详解

官方推荐通过仓库安装而非deb包，这样可以获得自动更新：

# 添加Docker官方GPG密钥 sudo mkdir -p /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg # 设置稳定版仓库 echo \ "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null # 安装Docker引擎 sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

安装后必须进行的调优配置：

# 创建daemon配置文件 sudo tee /etc/docker/daemon.json <<-'EOF' { "exec-opts": ["native.cgroupdriver=systemd"], "log-driver": "json-file", "log-opts": { "max-size": "100m" }, "storage-driver": "overlay2", "registry-mirrors": ["https://registry.cn-hangzhou.aliyuncs.com"] } EOF # 重启服务使配置生效 sudo systemctl enable docker sudo systemctl restart docker

这个配置实现了：

• 使用systemd作为cgroup驱动（兼容性更好）
• 日志轮转防止磁盘爆满
• 国内镜像加速下载
• overlay2存储驱动（性能最优）

验证安装成功的终极测试：

docker run --rm hello-world

如果看到欢迎信息，说明Docker已正确安装。如果遇到"permission denied"错误，请检查用户组配置并确认已执行newgrp docker。

3. .NET环境部署实战

3.1 选择合适的基础镜像

微软官方提供了多个.NET镜像变体，主要区别在于：

• mcr.microsoft.com/dotnet/sdk：包含编译工具（开发用）
• mcr.microsoft.com/dotnet/aspnet：仅运行时（生产用）
• 标签差异：7.0、6.0等指定版本，-alpine为轻量版

对于API项目，推荐使用多阶段构建：

# 第一阶段：构建 FROM mcr.microsoft.com/dotnet/sdk:7.0 AS build WORKDIR /src COPY . . RUN dotnet publish -c Release -o /app # 第二阶段：运行 FROM mcr.microsoft.com/dotnet/aspnet:7.0 WORKDIR /app COPY --from=build /app . ENTRYPOINT ["dotnet", "YourApi.dll"]

这种构建方式可以：

1. 保持最终镜像最小化（仅300MB左右）
2. 避免源代码泄露风险
3. 分离构建依赖与运行依赖

3.2 典型Dockerfile深度解析

以一个实际的ASP.NET Core API项目为例，完整Dockerfile应包含这些关键要素：

# 使用Alpine版进一步减小镜像体积 FROM mcr.microsoft.com/dotnet/sdk:7.0-alpine AS build # 安装必要的构建工具（如git用于私有nuget包） RUN apk add --no-cache git # 优化nuget包恢复层 WORKDIR /src COPY ["YourApi/YourApi.csproj", "YourApi/"] RUN dotnet restore "YourApi/YourApi.csproj" # 复制源码并构建 COPY . . RUN dotnet build -c Release --no-restore RUN dotnet publish -c Release -o /app --no-build # 运行时镜像 FROM mcr.microsoft.com/dotnet/aspnet:7.0-alpine WORKDIR /app # 设置时区（中国时区） RUN apk add --no-cache tzdata && \ cp /usr/share/zoneinfo/Asia/Shanghai /etc/localtime && \ echo "Asia/Shanghai" > /etc/timezone # 从构建阶段复制结果 COPY --from=build /app . # 健康检查 HEALTHCHECK --interval=30s --timeout=3s \ CMD curl -f http://localhost:5000/health || exit 1 # 设置非root用户运行 RUN adduser -D appuser && chown -R appuser /app USER appuser ENTRYPOINT ["dotnet", "YourApi.dll"]

这个配置解决了生产环境的几个关键问题：

• 镜像体积从1GB+优化到约150MB
• 正确处理中国时区
• 符合安全最佳实践（非root运行）
• 内置健康检查便于监控
• 分层构建加速后续编译

3.3 容器网络与端口配置

.NET Core默认监听5000(HTTP)和5001(HTTPS)端口，在Docker中需要正确映射：

# 开发环境运行（端口映射+挂载源码） docker run -d -p 8080:80 -p 4430:443 \ -v $(pwd):/app \ -e ASPNETCORE_ENVIRONMENT=Development \ --name myapi your-api-image # 生产环境运行（只读文件系统） docker run -d -p 80:80 -p 443:443 \ --read-only \ -v /app/logs \ -e ASPNETCORE_ENVIRONMENT=Production \ --name myapi-prod your-api-image

关键参数说明：

• -p：主机端口:容器端口映射
• -v：挂载卷（开发时挂载源码，生产时挂载日志）
• --read-only：增强安全性（需配合tmpfs或volume）
• -e：设置环境变量

对于HTTPS支持，需要在Dockerfile中额外配置：

# 在运行时镜像中添加证书 FROM mcr.microsoft.com/dotnet/aspnet:7.0 COPY --from=build /app /app COPY ./certificates /usr/local/share/ca-certificates/ RUN update-ca-certificates

4. 生产环境优化指南

4.1 性能调优参数

在docker run时添加这些参数可以显著提升.NET性能：

docker run -d \ --cpus=2 \ # 限制CPU核心数 --memory=1g \ # 限制内存 --pids-limit=200 \ # 防止fork炸弹 --ulimit nofile=1024:4096 \ # 文件描述符限制 -e COMPlus_ReadyToRun=1 \ # 启用AOT编译 -e COMPlus_TieredCompilation=1 \ # 分层编译 -e DOTNET_SYSTEM_GLOBALIZATION_INVARIANT=1 \ # 禁用全球化 your-api-image

这些环境变量的作用：

• ReadyToRun：提前编译减少JIT时间
• TieredCompilation：优化长期运行的性能
• GlobalizationInvariant：节省约30MB内存（如果不需要本地化）

4.2 日志与监控方案

推荐使用以下组合实现生产级监控：

1. 标准输出日志 + ELK

   // Program.cs中配置 builder.Logging.AddConsole();

2. 健康检查端点

   app.MapHealthChecks("/health");

3. Prometheus监控

   // 安装nuget包: prometheus-net.AspNetCore app.UseMetricServer(); app.UseHttpMetrics();

对应的Docker Compose配置示例：

version: '3.8' services: api: image: your-api-image ports: - "80:80" deploy: resources: limits: cpus: '2' memory: 1G healthcheck: test: ["CMD", "curl", "-f", "http://localhost/health"] interval: 30s timeout: 5s retries: 3 prometheus: image: prom/prometheus ports: - "9090:9090" volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml grafana: image: grafana/grafana ports: - "3000:3000"

4.3 常见问题排错手册

问题1：容器启动后立即退出

• 检查项：

  docker logs <container_id> docker inspect <container_id> | grep -i status

• 解决方案：
  • 确保Dockerfile中有ENTRYPOINT或CMD
  • 检查应用是否监听正确端口（默认5000）

问题2：数据库连接失败

• 典型错误：

  "Connection refused" 或 "Unable to connect to SQL Server"

• 排查步骤：
  1. 确认容器网络模式：

     docker network ls docker inspect <container_id> | grep -i network

  2. 如果是bridge模式，确保使用宿主IP而非localhost
  3. 检查防火墙规则：

     sudo ufw status

问题3：性能突然下降

• 诊断命令：

  docker stats <container_id> docker exec -it <container_id> top

• 可能原因：
  • 内存泄漏（检查.NET GC相关指标）
  • 线程死锁（添加DOTNET_DiagnosticPorts环境变量）
  • 磁盘IO瓶颈（考虑使用tmpfs挂载）

问题4：时区不正确

• 解决方案：

  # 在Dockerfile中添加 RUN apk add --no-cache tzdata ENV TZ=Asia/Shanghai

• 验证方法：

  docker exec -it <container_id> date

5. 进阶技巧与安全加固

5.1 多阶段构建优化

对于大型解决方案，可以采用更精细的多阶段构建：

# 阶段1：还原nuget包 FROM mcr.microsoft.com/dotnet/sdk:7.0 AS restore WORKDIR /src COPY ["YourApi/YourApi.csproj", "YourApi/"] COPY ["YourLib/YourLib.csproj", "YourLib/"] RUN dotnet restore "YourApi/YourApi.csproj" # 阶段2：构建 FROM restore AS build COPY . . RUN dotnet build -c Release --no-restore # 阶段3：测试 FROM build AS test RUN dotnet test -c Release --no-build # 阶段4：发布 FROM build AS publish RUN dotnet publish -c Release -o /app --no-build # 阶段5：运行时 FROM mcr.microsoft.com/dotnet/aspnet:7.0 COPY --from=publish /app . ENTRYPOINT ["dotnet", "YourApi.dll"]

这种结构允许：

• 独立缓存nuget还原层（最大程度利用Docker缓存）
• 在CI/CD管道中复用中间阶段
• 分离构建与测试环境

5.2 安全加固措施

生产环境必须实施的安全配置：

1. 非root用户运行

   RUN adduser -D appuser --uid 1000 \ && chown -R appuser /app USER appuser

2. 只读文件系统

   docker run --read-only -v /tmp -v /app/logs ...

3. 资源限制

   # docker-compose.yml中 deploy: resources: limits: cpus: '0.5' memory: 512M

4. 漏洞扫描

   # 安装trivy sudo apt install -y wget apt-transport-https gnupg lsb-release wget -qO - https://aquasecurity.github.io/trivy-repo/deb/public.key | sudo apt-key add - echo deb https://aquasecurity.github.io/trivy-repo/deb $(lsb_release -sc) main | sudo tee -a /etc/apt/sources.list.d/trivy.list sudo apt update sudo apt install -y trivy # 扫描镜像 trivy image your-api-image

5.3 CI/CD集成示例

GitHub Actions自动化部署脚本：

name: Build and Deploy on: push: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Login to Docker Hub uses: docker/login-action@v2 with: username: ${{ secrets.DOCKER_HUB_USERNAME }} password: ${{ secrets.DOCKER_HUB_TOKEN }} - name: Build and push uses: docker/build-push-action@v4 with: push: true tags: yourusername/your-api:latest cache-from: type=gha cache-to: type=gha,mode=max deploy: needs: build runs-on: ubuntu-latest steps: - name: SSH and deploy uses: appleboy/ssh-action@master with: host: ${{ secrets.PRODUCTION_HOST }} username: ${{ secrets.SSH_USERNAME }} key: ${{ secrets.SSH_PRIVATE_KEY }} script: | docker pull yourusername/your-api:latest docker stop live-api || true docker rm live-api || true docker run -d \ --name live-api \ -p 80:80 \ -p 443:443 \ --restart unless-stopped \ yourusername/your-api:latest

这个流水线实现了：

• 自动构建Docker镜像并推送到仓库
• 使用GitHub Actions缓存加速构建
• 通过SSH自动部署到生产服务器
• 零停机更新策略

6. 性能对比与实测数据

为了验证容器化部署的实际效果，我在i7-1165G7/16GB的笔记本上进行了对比测试：

测试使用的API是一个包含JWT认证、EF Core数据库访问和Redis缓存的典型WebAPI。关键发现：

1. 容器化带来的性能损耗<5%（经过优化后）
2. 内存开销主要来自额外的安全隔离层
3. 启动时间差异主要来自镜像层加载

对于CPU密集型运算（如加密操作），容器性能几乎与原生一致。网络IO方面，使用host网络模式可以获得最佳性能：

docker run --network host your-api-image

但要注意这会降低隔离性，仅推荐在受控环境使用。