从零开始：将.NET 8 WebAPI无缝迁移至Docker的最佳实践
1. 为什么要把.NET 8 WebAPI迁移到Docker？
如果你正在开发.NET 8 WebAPI项目，并且还在用传统方式部署，那你可能错过了Docker带来的巨大便利。我去年接手一个电商项目时，团队里有个新人问："为什么我们要费劲把API迁移到Docker？直接发布到服务器不就行了吗？"这个问题让我意识到，很多.NET开发者其实并不清楚容器化的真正价值。
首先，Docker能解决"在我机器上能跑"这个经典问题。记得有一次，我们花了整整两天排查一个生产环境的问题，最后发现只是因为测试环境的IIS版本不同。用了Docker之后，开发、测试、生产环境完全一致，这类问题再也没出现过。
其次，部署变得超级简单。以前发布一个更新要手动复制文件、配置IIS，现在只需要一条docker-compose命令。上周五下午5点，产品经理突然说要加个紧急功能，我们6点提交代码，6:05就完成了全自动部署，整个过程行云流水。
2. 环境准备：从零搭建Docker开发环境
2.1 安装Docker引擎
在开始之前，我们需要确保开发机上已经安装了Docker。这里有个小技巧：不要直接从Docker官网下载，用Winget（Windows）或Homebrew（Mac）安装会更方便：
# Windows用户 winget install Docker.DockerDesktop # Mac用户 brew install --cask docker安装完成后，别急着开始写代码。我建议先跑个测试容器确认安装成功：
docker run hello-world如果你看到"Hello from Docker!"的欢迎信息，说明安装正确。第一次运行这个命令时，Docker会自动下载镜像，这个过程可能会花几分钟，取决于你的网速。
2.2 配置.NET 8 SDK
虽然我们要用Docker运行应用，但本地开发还是需要.NET SDK。安装.NET 8 SDK时有个坑要注意：如果你之前安装过旧版本，最好先卸载干净。我遇到过因为版本冲突导致的各种奇怪问题。
# 查看已安装的.NET版本 dotnet --list-sdks # 安装.NET 8 SDK dotnet sdk install 8.0安装完成后，创建个测试项目验证一下：
dotnet new webapi -n DockerTestApi cd DockerTestApi dotnet run打开浏览器访问https://localhost:5001/weatherforecast，如果能看到返回的JSON数据，说明环境配置正确。
3. 编写完美的Dockerfile
3.1 基础镜像选择
选择基础镜像就像选房子地基，选错了后面全是坑。微软官方提供了多种.NET镜像，我整理了个对比表格：
| 镜像类型 | 大小 | 适用场景 | 典型命令 |
|---|---|---|---|
| runtime | ~100MB | 仅运行已发布应用 | FROM mcr.microsoft.com/dotnet/runtime:8.0 |
| aspnet | ~200MB | 运行ASP.NET Core应用 | FROM mcr.microsoft.com/dotnet/aspnet:8.0 |
| sdk | ~700MB | 需要编译的场景 | FROM mcr.microsoft.com/dotnet/sdk:8.0 |
对于WebAPI项目，我强烈推荐使用alpine版本的aspnet镜像，它兼顾了小巧和安全：
FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine AS base WORKDIR /app EXPOSE 803.2 多阶段构建技巧
多阶段构建是Dockerfile的精髓所在，它能显著减小最终镜像大小。下面这个模板是我在多个项目中验证过的：
# 第一阶段：构建 FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /src COPY ["MyWebApi/MyWebApi.csproj", "MyWebApi/"] RUN dotnet restore "MyWebApi/MyWebApi.csproj" COPY . . WORKDIR "/src/MyWebApi" RUN dotnet build "MyWebApi.csproj" -c Release -o /app/build # 第二阶段：发布 FROM build AS publish RUN dotnet publish "MyWebApi.csproj" -c Release -o /app/publish # 第三阶段：运行 FROM base AS final WORKDIR /app COPY --from=publish /app/publish . ENTRYPOINT ["dotnet", "MyWebApi.dll"]这个模板有3个关键优化点：
- 分层COPY：先单独复制.csproj文件执行restore，利用Docker缓存加速构建
- 分离构建和发布阶段：避免把编译中间文件打包进最终镜像
- 使用小巧的运行时镜像：最终阶段基于aspnet镜像而非sdk
4. 容器化部署实战
4.1 单容器部署
构建镜像的命令看似简单，但有些参数很有讲究：
docker build -t myapi:latest --pull --no-cache .这里加了两个重要参数：
--pull：确保使用最新的基础镜像--no-cache：避免使用可能过时的缓存层
运行容器时，端口映射有个小技巧：
docker run -d -p 8080:80 --name myapi myapi:latest我建议把容器端口(80)和主机端口(8080)设为不同值，这样可以避免和主机上其他服务冲突。曾经有次部署，因为主机上已经有服务占用了80端口，导致容器启动失败，排查了半天才发现问题。
4.2 使用Docker Compose编排
对于生产环境，我强烈推荐使用docker-compose.yml。下面这个配置是我在多个项目中总结出来的黄金模板：
version: '3.8' services: webapi: image: myapi:latest build: context: . dockerfile: Dockerfile container_name: myapi-prod ports: - "8080:80" environment: - ASPNETCORE_ENVIRONMENT=Production - ASPNETCORE_URLS=http://+:80 volumes: - ./logs:/app/logs restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost/health"] interval: 30s timeout: 10s retries: 3这个配置有几个亮点：
- 内置了健康检查，Kubernetes友好
- 配置了自动重启，应对意外崩溃
- 挂载了日志卷，方便排查问题
- 明确指定了生产环境变量
启动服务只需要一条命令：
docker-compose up -d --build加--build参数可以确保使用最新代码构建镜像，这在持续部署流程中特别有用。
5. 避坑指南：常见问题解决方案
5.1 时区和编码问题
使用alpine镜像时，时区和编码是两个最常见的坑。这是我验证过的解决方案：
# 设置时区（中国标准时间） RUN apk add --no-cache tzdata ENV TZ=Asia/Shanghai # 设置编码 ENV LANG=en_US.UTF-8 ENV LC_ALL=en_US.UTF-8曾经有个项目因为时区问题导致订单时间全部显示错误，加上这两行配置后就解决了。对于中文环境，你可能还需要额外安装中文字体：
RUN apk add --no-cache wqy-zenhei5.2 权限问题
Linux环境下，可执行文件权限是个隐形杀手。我建议在Dockerfile中显式设置权限：
RUN chmod +x /app/YourWebApiName更安全的做法是在构建阶段就设置好权限：
FROM build AS publish RUN dotnet publish "MyWebApi.csproj" -c Release -o /app/publish \ && chmod +x /app/publish/MyWebApi5.3 性能调优
默认配置下，Kestrel可能不是最优的。这是我的调优配置：
{ "Kestrel": { "Limits": { "MaxConcurrentConnections": 100, "MaxConcurrentUpgradedConnections": 100 }, "Endpoints": { "Http": { "Url": "http://*:80" } } } }在Docker环境中，还需要特别注意内存限制。建议在docker-compose中配置：
deploy: resources: limits: cpus: '1' memory: 512M这个配置可以防止单个容器占用过多资源，影响主机稳定性。