银河麒麟v10服务器版Docker部署.NET 8 WebAPI教程

银河麒麟v10服务器版Docker部署.NET 8 WebAPI教程

注意：微软目前尚未发布.NET 10版本，本教程使用当前最新的LTS版本.NET 8进行演示。如果未来.NET 10正式发布，部署流程基本类似，只需更新Docker镜像版本即可。

1. 前言

本教程旨在指导用户在银河麒麟v10服务器版上使用Docker容器化技术部署.NET 8 WebAPI应用程序。.NET 8是微软推出的跨平台、高性能的开发框架，结合Docker容器化技术可以实现快速部署、环境隔离、弹性扩展等优势。

1.1 适用环境

• 银河麒麟v10服务器版
• 至少2GB内存
• 至少10GB可用磁盘空间
• 网络连接正常

1.2 .NET 8特性

• 高性能（相比.NET 7提升了5-15%）
• 跨平台支持（Windows、Linux、macOS）
• 统一的开发模型（Web、桌面、移动、云）
• 内置容器支持
• 改进的GC性能
• 增强的AOT编译支持

2. 系统环境准备

2.1 系统更新

# 更新系统软件包到最新版本
sudo yum update -y

2.2 安装必要依赖

# 安装wget、curl等必要工具
sudo yum install -y wget curl vim git

3. Docker安装与配置

3.1 安装Docker

# 安装Docker所需的依赖包
sudo yum install -y yum-utils device-mapper-persistent-data lvm2

# 添加Docker官方软件源
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# 安装Docker CE、CLI和containerd.io
sudo yum install -y docker-ce docker-ce-cli containerd.io

# 启动Docker服务
sudo systemctl start docker

# 设置Docker服务开机自启
sudo systemctl enable docker

# 验证Docker安装是否成功
sudo docker --version

3.2 安装Docker Compose

# 下载Docker Compose二进制文件
curl -L "https://github.com/docker/compose/releases/download/v2.20.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# 赋予执行权限
sudo chmod +x /usr/local/bin/docker-compose

# 创建软链接到系统PATH
sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose

# 验证Docker Compose安装是否成功
docker-compose --version

3.3 配置防火墙

# 启动并启用firewalld服务
sudo systemctl start firewalld
sudo systemctl enable firewalld

# 允许Docker服务通过防火墙
sudo firewall-cmd --permanent --zone=public --add-service=docker

# 允许WebAPI端口(5000/5001)通过防火墙
sudo firewall-cmd --permanent --zone=public --add-port=5000/tcp
sudo firewall-cmd --permanent --zone=public --add-port=5001/tcp

# 重新加载防火墙规则
sudo firewall-cmd --reload

4. .NET 8 WebAPI项目准备

4.1 项目创建方法

方法一：在Windows开发机上创建项目后部署

# 在Windows开发机上打开命令行
# 安装.NET 8 SDK
winget install Microsoft.DotNet.SDK.8

# 创建WebAPI项目
mkdir KylinDotNetWebAPI
cd KylinDotNetWebAPI
dotnet new webapi -n KylinDotNetWebAPI -o .

# 创建.gitignore文件
dotnet new gitignore

# 测试项目运行
dotnet run

# 访问测试：http://localhost:5200/WeatherForecast

方法二：直接在Linux服务器上创建项目

# 在Linux服务器上安装.NET 8 SDK（可选，用于直接在服务器上开发）
# 下载安装脚本
wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x dotnet-install.sh

# 安装.NET 8 SDK
./dotnet-install.sh -c 8.0 --install-dir /usr/share/dotnet

# 添加环境变量
export DOTNET_ROOT=/usr/share/dotnet
export PATH=$PATH:$DOTNET_ROOT:$DOTNET_ROOT/tools

# 创建WebAPI项目
mkdir -p /opt/dotnet/KylinDotNetWebAPI
cd /opt/dotnet/KylinDotNetWebAPI
dotnet new webapi -n KylinDotNetWebAPI -o .

# 测试项目运行
dotnet run

4.2 项目结构

KylinDotNetWebAPI/
├── Controllers/           # API控制器目录
│   └── WeatherForecastController.cs  # 示例控制器
├── Properties/            # 项目属性
│   └── launchSettings.json  # 启动配置
├── appsettings.json       # 应用配置文件
├── appsettings.Development.json  # 开发环境配置
├── Program.cs             # 应用入口点
├── KylinDotNetWebAPI.csproj  # 项目文件
└── .gitignore             # Git忽略文件

5. Docker配置

5.1 创建Dockerfile

在项目根目录创建Dockerfile文件：

# 使用多阶段构建优化镜像大小

# 阶段1：构建阶段
FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine AS build
WORKDIR /src

# 复制项目文件并恢复依赖
COPY ["KylinDotNetWebAPI.csproj", "./"]
RUN dotnet restore "./KylinDotNetWebAPI.csproj"

# 复制所有文件并构建
COPY . .
WORKDIR "/src/"
RUN dotnet build "KylinDotNetWebAPI.csproj" -c Release -o /app/build

# 发布应用
RUN dotnet publish "KylinDotNetWebAPI.csproj" -c Release -o /app/publish /p:UseAppHost=false

# 阶段2：运行阶段
FROM mcr.microsoft.com/dotnet/aspnet:8.0-alpine AS base
WORKDIR /app

# 设置时区
ENV TZ=Asia/Shanghai
RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime && echo $TZ > /etc/timezone

# 从构建阶段复制发布文件
COPY --from=build /app/publish .

# 暴露端口（HTTP和HTTPS）
EXPOSE 5000
EXPOSE 5001

# 设置环境变量
ENV ASPNETCORE_URLS=http://+:5000;https://+:5001

# 启动应用
ENTRYPOINT ["dotnet", "KylinDotNetWebAPI.dll"]

5.2 创建.dockerignore文件

在项目根目录创建.dockerignore文件，减少构建上下文大小：

# .NET项目文件
bin/
obj/
*.swp
*.swo
*~

# 日志文件
logs/
*.log

# 测试文件
*Tests*/
*.Tests.csproj

# 环境文件
.env
.env.local
.env.development.local
.env.test.local
.env.production.local

# IDE文件
.idea/
.vscode/
*.suo
*.ntvs*
*.njsproj
*.sln
*.sw?

5.3 创建Docker Compose文件

在项目根目录创建docker-compose.yml文件：

version: '3.8'

services:
  kylin-webapi:
    image: kylin-dotnet-webapi:latest
    container_name: kylin-dotnet-webapi
    restart: always
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - ASPNETCORE_ENVIRONMENT=Production
      - ASPNETCORE_HTTP_PORTS=5000
      - ASPNETCORE_HTTPS_PORTS=5001
      # 配置数据库连接等环境变量
      # - ConnectionStrings__DefaultConnection=Server=db;Database=WebAPIDemo;User=sa;Password=YourStrongPassword123!
    ports:
      - "5000:5000"
      - "5001:5001"
    volumes:
      # 挂载日志目录
      - ./logs:/app/logs
    networks:
      - dotnet-network

# 可选：定义网络（如果需要连接其他服务）
networks:
  dotnet-network:
    driver: bridge

6. 部署与运行

6.1 构建Docker镜像

# 进入项目根目录
cd /opt/dotnet/KylinDotNetWebAPI

# 使用Docker Compose构建镜像
docker-compose build

# 或使用docker命令直接构建
docker build -t kylin-dotnet-webapi:latest .

6.2 运行Docker容器

# 使用Docker Compose运行容器
docker-compose up -d

# 或使用docker命令直接运行
docker run -d \
  --name kylin-dotnet-webapi \
  --restart always \
  -p 5000:5000 \
  -p 5001:5001 \
  -e ASPNETCORE_ENVIRONMENT=Production \
  kylin-dotnet-webapi:latest

6.3 查看容器状态

# 查看容器运行状态
docker-compose ps

# 或使用docker命令
docker ps

# 查看容器日志
docker-compose logs -f

# 或使用docker命令
docker logs -f kylin-dotnet-webapi

7. 服务验证

7.1 本地访问测试

# 使用curl测试API访问
curl http://localhost:5000/WeatherForecast

# 或指定IP访问
curl http://服务器IP:5000/WeatherForecast

7.2 远程访问测试

从浏览器访问：

• HTTP: http://服务器IP:5000/WeatherForecast
• HTTPS: https://服务器IP:5001/WeatherForecast

注意：首次访问HTTPS可能会有证书警告，这是因为使用了自签名证书。在生产环境中应配置有效的SSL证书。

7.3 健康检查

# 检查API健康状态
curl -I http://服务器IP:5000/WeatherForecast

# 期望返回状态码200 OK

8. 配置与优化

8.1 应用配置

应用配置主要通过appsettings.json和环境变量进行管理：

# 查看当前配置文件
cat appsettings.json

修改配置后需要重建镜像并重启容器：

docker-compose up -d --build

8.2 环境变量配置

可以在docker-compose.yml中添加环境变量：

environment:
  - ASPNETCORE_ENVIRONMENT=Production
  - ASPNETCORE_HTTP_PORTS=5000
  - ASPNETCORE_HTTPS_PORTS=5001
  - ConnectionStrings__DefaultConnection=Server=db;Database=WebAPIDemo;User=sa;Password=YourStrongPassword123!
  - Logging__LogLevel__Default=Information

8.3 日志配置

修改appsettings.json配置日志：

"Logging": {
  "LogLevel": {
    "Default": "Information",
    "Microsoft.AspNetCore": "Warning"
  },
  "File": {
    "LogLevel": {
      "Default": "Information"
    },
    "Path": "/app/logs/webapi.log",
    "RollingInterval": "Day"
  }
}

8.4 性能优化

1. 启用AOT编译（.NET 7+支持）：

   • 修改项目文件添加AOT配置
   • 更新Dockerfile使用AOT编译

2. 使用性能监控：

   • 集成App Metrics
   • 配置Prometheus + Grafana监控

9. 开机自启动配置

9.1 容器级自启动

在docker-compose.yml中已配置restart: always，确保容器在退出或Docker服务重启时自动重启。

9.2 系统级自启动

确保Docker服务已设置开机自启：

# 验证Docker服务开机自启设置
sudo systemctl is-enabled docker

# 如果未启用，执行以下命令
sudo systemctl enable docker

9.3 配置Docker Compose服务开机自启

创建systemd服务单元来管理.NET WebAPI的Docker Compose服务：

# 创建systemd服务文件
cat > /etc/systemd/system/kylin-dotnet-webapi.service << EOF
[Unit]
Description=Kylin .NET 8 WebAPI Docker Service
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/opt/dotnet/KylinDotNetWebAPI
ExecStart=/usr/local/bin/docker-compose up -d
ExecStop=/usr/local/bin/docker-compose down
TimeoutStartSec=0

[Install]
WantedBy=multi-user.target
EOF

启用并启动该服务：

# 重新加载systemd配置
sudo systemctl daemon-reload

# 启用服务开机自启
sudo systemctl enable kylin-dotnet-webapi

# 启动服务
sudo systemctl start kylin-dotnet-webapi

# 验证服务状态
sudo systemctl status kylin-dotnet-webapi

10. 常见问题与故障排除

10.1 端口被占用

# 检查端口占用情况
sudo netstat -tuln | grep 5000
sudo netstat -tuln | grep 5001

# 或使用lsof命令
sudo lsof -i :5000

# 停止占用端口的进程
sudo kill -9 <PID>

10.2 容器启动失败

# 查看详细日志
docker-compose logs -f

# 或查看Docker事件
docker events --since 1h

10.3 API访问返回500错误

# 检查应用日志
docker exec -it kylin-dotnet-webapi cat /app/logs/webapi.log

# 或实时查看日志
docker exec -it kylin-dotnet-webapi tail -f /app/logs/webapi.log

10.4 依赖项问题

确保所有NuGet包都已正确恢复和构建：

# 在项目目录中执行
dotnet restore
dotnet build

10.5 数据库连接问题

# 检查数据库连接字符串配置
# 验证数据库服务是否正常运行
# 检查网络连接是否正常

11. 高级功能

11.1 HTTPS配置

11.1.1 使用自签名证书

# 生成自签名证书
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# 转换为pfx格式
export password=YourCertificatePassword123!
openssl pkcs12 -export -out certificate.pfx -inkey key.pem -in cert.pem -passout pass:$password

11.1.2 配置HTTPS

在docker-compose.yml中挂载证书：

volumes:
  - ./certificate.pfx:/app/certificate.pfx
environment:
  - ASPNETCORE_Kestrel__Certificates__Default__Password=YourCertificatePassword123!
  - ASPNETCORE_Kestrel__Certificates__Default__Path=/app/certificate.pfx

11.2 集成数据库

以MySQL为例，修改docker-compose.yml添加数据库服务：

services:
  kylin-webapi:
    # ... 现有配置
    depends_on:
      - mysql

  mysql:
    image: mysql:8.0
    container_name: mysql
    restart: always
    environment:
      - MYSQL_ROOT_PASSWORD=YourRootPassword123!
      - MYSQL_DATABASE=WebAPIDemo
      - MYSQL_USER=webapi
      - MYSQL_PASSWORD=YourStrongPassword123!
    ports:
      - "3306:3306"
    volumes:
      - mysql-data:/var/lib/mysql
    networks:
      - dotnet-network

volumes:
  mysql-data:

11.3 使用Nginx反向代理

配置Nginx作为API的反向代理：

# 创建Nginx配置文件
cat > /opt/docker/nginx/conf/conf.d/webapi.example.com.conf << EOF
server {
    listen 80;
    server_name webapi.example.com;
    
    location / {
        proxy_pass http://服务器IP:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        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_cache_bypass $http_upgrade;
    }
}
EOF

12. 总结

本教程详细介绍了在银河麒麟v10服务器版上使用Docker部署.NET 8 WebAPI的完整过程，包括：

1. 系统环境准备和依赖安装
2. Docker和Docker Compose的安装与配置
3. .NET 8 WebAPI项目的创建方法
4. Dockerfile和docker-compose.yml的编写
5. 服务的构建、运行和验证
6. 配置优化和性能调优
7. 开机自启动设置
8. 常见问题的故障排除
9. 高级功能扩展

通过Docker部署.NET 8 WebAPI，您可以快速搭建一个高性能、跨平台的API服务，同时享受容器化带来的环境隔离、快速部署和弹性扩展等优势。

13. 参考资料

• .NET 8官方文档
• Docker官方文档
• 银河麒麟v10服务器版官方文档
• ASP.NET Core WebAPI文档