Linux 从零部署项目实战指南（三）：实战部署 .NET Web 应用

本系列面向零基础或初中级开发者，手把手教你将一个项目从零部署到 Linux 服务器，并解决过程中遇到的常见问题。

一、前言

前两篇文章我们完成了服务器初始化，搭建了 Nginx + MySQL + Redis 运行环境。现在服务器已经"万事俱备"，只差你的应用了。

本篇目标：将 .NET Web API 项目从源码部署到 Linux 服务器，配置 Nginx 反向代理，用 systemd 管理进程，实现开机自启和自动重启。

二、整体架构

部署完成后，你的应用架构是这样的：

用户请求    │    ▼Nginx（端口 80/443）     ← 反向代理、静态文件、HTTPS    │    ▼.NET Web 应用（端口 5000）  ← 业务逻辑    │    ├── MySQL（端口 3306）   ← 数据持久化    └── Redis（端口 6379）   ← 缓存加速

核心流程：

1. 用户访问 http://你的域名 → Nginx 监听 80 端口
2. Nginx 把请求转发到 http://127.0.0.1:5000（你的 .NET 应用）
3. .NET 应用处理请求，需要时查询 MySQL 或 Redis
4. 响应原路返回给用户

三、在服务器上安装 .NET 运行时

3.1 选择 SDK 还是 Runtime？

生产环境建议：只安装 ASP.NET Core Runtime，编译在本地或 CI 环境完成。

但为了方便在服务器上调试，本教程安装 .NET SDK，这样服务器也可以编译和发布。

3.2 安装 .NET SDK

# 第 1 步：注册 Microsoft 包源wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.debsudo dpkg -i packages-microsoft-prod.debrm packages-microsoft-prod.deb# 第 2 步：更新并安装 .NET SDK 8.0sudo apt updatesudo apt install -y dotnet-sdk-8.0# 第 3 步：验证安装dotnet --version# 输出：8.0.xxxdotnet --list-sdks# 输出：8.0.xxxdotnet --list-runtimes# 输出应包含 Microsoft.AspNetCore.App 8.0.xxx

📌 版本选择建议：.NET 8.0 是当前 LTS（长期支持）版本，支持到 2026 年 11 月。如果安装 .NET 9.0，请将上面命令中的 8.0 替换为 9.0。

3.3 安装 .NET 9.0（可选）

如果需要安装 .NET 9.0：

# 安装 .NET 9.0 SDK（与 8.0 可共存）sudo apt install -y dotnet-sdk-9.0# 验证dotnet --list-sdks# 输出：# 8.0.xxx# 9.0.xxx

四、创建示例项目

为了演示完整的部署流程，我们先在服务器上创建一个 .NET Web API 项目作为示例。如果你有自己的项目，可以跳过这一步，直接看"发布和上传"部分。

4.1 创建项目

# 切换到项目目录cd /home/www/myproject/source# 创建 .NET Web API 项目dotnet new webapi -n MyWebApi --no-https# 进入项目目录cd MyWebApi# 查看项目结构tree -L 2# 输出：# .# ├── MyWebApi.csproj# ├── Program.cs# ├── Properties# │   └── launchSettings.json# ├── appsettings.json# └── appsettings.Development.json

4.2 修改 Program.cs

默认的模板生成的代码可以运行，但我们修改一下，添加一个健康检查接口，方便验证部署是否成功：

# 编辑 Program.csvim Program.cs

将内容替换为：

var builder = WebApplication.CreateBuilder(args);// 添加控制器支持builder.Services.AddControllers();// 添加 CORS（允许跨域请求，开发时有用）builder.Services.AddCors(options =>{    options.AddDefaultPolicy(policy =>    {        policy.AllowAnyOrigin()              .AllowAnyMethod()              .AllowAnyHeader();    });});// 配置 Kestrel 监听端口（从环境变量读取，默认 5000）builder.WebHost.UseUrls($"http://0.0.0.0:{Environment.GetEnvironmentVariable("APP_PORT") ?? "5000"}");var app = builder.Build();app.UseCors();app.MapControllers();// 健康检查接口app.MapGet("/health", () => Results.Ok(new{    status = "healthy",    timestamp = DateTime.UtcNow,    server = Environment.MachineName}));app.Run();

4.3 添加一个测试控制器

# 创建 Controllers 目录mkdir -p Controllers# 创建测试控制器vim Controllers/TestController.cs

using Microsoft.AspNetCore.Mvc;namespace MyWebApi.Controllers;[ApiController][Route("api/[controller]")]public class TestController : ControllerBase{/// <summary>/// GET /api/test - 测试接口是否正常/// </summary>    [HttpGet]public IActionResult Get()    {        return Ok(new        {            message = "部署成功！.NET Web API 运行正常 ✅",            time = DateTime.UtcNow,            version = "1.0.0"        });    }/// <summary>/// GET /api/test/echo?msg=hello - 回显测试/// </summary>    [HttpGet("echo")]public IActionResult Echo([FromQuery] string msg = "Hello")    {        return Ok(new { you_said = msg, length = msg.Length });    }}

4.4 本地测试运行

# 还原依赖dotnet restore# 编译项目dotnet build# 运行项目（按 Ctrl+C 停止）dotnet run

打开另一个终端窗口测试：

# 测试健康检查接口curl http://localhost:5000/health# 输出：{"status":"healthy","timestamp":"...","server":"..."}# 测试 API 接口curl http://localhost:5000/api/test# 输出：{"message":"部署成功！.NET Web API 运行正常 ✅","time":"...","version":"1.0.0"}curl http://localhost:5000/api/test/echo?msg=HelloWorld# 输出：{"you_said":"HelloWorld","length":10}

五、发布应用

5.1 发布到指定目录

# 在项目目录中执行cd /home/www/myproject/source/MyWebApi# 发布到部署目录（release 模式，框架依赖部署）dotnet publish -c Release -o /home/www/myproject/publish# 查看发布后的文件ls -la /home/www/myproject/publish/# 应该看到 MyWebApi.dll、appsettings.json 等文件

发布模式说明：

dotnet publish -c Release -o <输出目录>参数说明：  -c Release    # 发布 Release 版本（优化编译）  -o 输出目录    # 指定输出路径发布产物：  MyWebApi.dll          # 主程序集（入口）  MyWebApi.runtimeconfig.json  # 运行时配置  MyWebApi.deps.json    # 依赖清单  appsettings.json      # 配置文件（会复制到输出目录）  MyWebApi.pdb          # 调试符号文件（可选，生产环境可删除）

5.2 配置 appsettings.json

# 编辑生产环境的配置文件vim /home/www/myproject/publish/appsettings.json

{  "Logging": {    "LogLevel": {      "Default": "Information",      "Microsoft.AspNetCore": "Warning"    }  },  "ConnectionStrings": {    "DefaultConnection": "Server=localhost;Port=3306;Database=myproject_db;User=myapp;Password=YourAppPassword2024!;Charset=utf8mb4;"  },  "Redis": {    "Connection": "localhost:6379,password=YourRedisPassword2024!,defaultDatabase=0"  },  "AllowedHosts": "*"}

⚠️ 安全提示：appsettings.json 中包含数据库密码等敏感信息。生产环境更推荐使用环境变量或**用户机密（User Secrets）**来管理敏感配置，这样配置文件不会暴露密码。

5.3 使用环境变量管理敏感配置（推荐）

相比在 appsettings.json 中写死密码，环境变量方式更安全，也方便在不同环境间切换：

# 编辑 deploy 用户的 .bashrcsudo -u deploy vim ~deploy/.bashrc# 在文件末尾添加：export ASPNETCORE_ENVIRONMENT=Productionexport APP_PORT=5000export ConnectionStrings__DefaultConnection="Server=localhost;Port=3306;Database=myproject_db;User=myapp;Password=YourAppPassword2024!;Charset=utf8mb4;"export Redis__Connection="localhost:6379,password=YourRedisPassword2024!,defaultDatabase=0"# 使配置生效source ~deploy/.bashrc

环境变量命名规则：使用 __（双下划线）作为配置路径分隔符。

• • ConnectionStrings__DefaultConnection 对应 appsettings.json 中的 ConnectionStrings:DefaultConnection

5.4 设置目录权限

# 将发布目录所有权交给 deploy 用户sudo chown -R deploy:deploy /home/www/myproject/publish# 设置权限（755 = 所有者可读写执行，其他人可读执行）sudo chmod -R 755 /home/www/myproject/publish# 如果应用需要写文件（如日志、上传），确保相关目录可写sudo chmod -R 775 /home/www/myproject/publish/logssudo chmod -R 775 /home/www/myproject/static/uploads

六、使用 systemd 管理应用进程

6.1 为什么需要 systemd？

直接运行 dotnet MyWebApi.dll 的问题是：

• • 关闭终端后进程就结束了
• • 服务器重启后不会自动启动
• • 进程崩溃了不会自动恢复

systemd 可以解决这些问题，它是 Linux 的标准服务管理器。

6.2 创建 systemd 服务文件

# 创建 .NET 应用的服务文件sudo tee /etc/systemd/system/mywebapi.service << 'EOF'[Unit]Description=MyWebApi - .NET Web ApplicationAfter=network.target mysql.service redis-server.serviceWants=mysql.service redis-server.service[Service]Type=simpleUser=deployWorkingDirectory=/home/www/myproject/publishExecStart=/usr/bin/dotnet /home/www/myproject/publish/MyWebApi.dllRestart=alwaysRestartSec=10# 环境变量（从 appsettings.json 读取改为从环境变量读取，更安全）Environment=ASPNETCORE_ENVIRONMENT=ProductionEnvironment=APP_PORT=5000Environment=ConnectionStrings__DefaultConnection=Server=localhost;Port=3306;Database=myproject_db;User=myapp;Password=YourAppPassword2024!;Charset=utf8mb4;Environment=Redis__Connection=localhost:6379,password=YourRedisPassword2024!,defaultDatabase=0# 资源限制LimitNOFILE=65536LimitNPROC=65536# 日志配置StandardOutput=journalStandardError=journal[Install]WantedBy=multi-user.targetEOF

服务文件关键配置说明：

6.3 启动服务

# 重新加载 systemd 配置（每次修改 .service 文件后都要执行）sudo systemctl daemon-reload# 启动服务sudo systemctl start mywebapi# 设置开机自启sudo systemctl enable mywebapi# 查看服务状态sudo systemctl status mywebapi# 输出应显示：active (running)# 测试应用是否正常运行curl http://localhost:5000/health# 输出：{"status":"healthy","timestamp":"...","server":"..."}curl http://localhost:5000/api/test# 输出：{"message":"部署成功！.NET Web API 运行正常 ✅","time":"...","version":"1.0.0"}

6.4 服务管理命令

# 启动sudo systemctl start mywebapi# 停止sudo systemctl stop mywebapi# 重启sudo systemctl restart mywebapi# 查看状态sudo systemctl status mywebapi# 查看日志（实时）sudo journalctl -u mywebapi -f# 查看最近 100 行日志sudo journalctl -u mywebapi -n 100 --no-pager# 查看今天的所有日志sudo journalctl -u mywebapi --since today# 禁用开机自启sudo systemctl disable mywebapi# 重新加载配置（修改 .service 文件后）sudo systemctl daemon-reload

6.5 测试自动重启功能

# 模拟进程崩溃sudo systemctl status mywebapi    # 先记下 PID# 输出示例：Main PID: 12345# 强制杀死进程sudo kill -9 12345# 立即查看状态，应该看到 systemd 正在重启sudo systemctl status mywebapi# 应该看到：active (running)，且 PID 已变更# 测试服务器重启后是否自动启动sudo reboot# 等服务器重启后重新连接ssh my-server# 检查服务是否自动启动sudo systemctl status mywebapi# 应该显示：active (running)

七、配置 Nginx 反向代理

7.1 更新 Nginx 站点配置

现在应用已经在 5000 端口运行了，但用户更习惯通过 80 端口访问。配置 Nginx 把请求转发到 5000 端口：

# 编辑 Nginx 站点配置sudo tee /etc/nginx/sites-available/myproject << 'EOF'server {    listen 80;    listen [::]:80;    server_name _;    # ========== 日志 ==========    access_log /var/log/nginx/myproject_access.log;    error_log /var/log/nginx/myproject_error.log;    # ========== 静态文件（Nginx 直接处理，不经过 .NET） ==========    location /static/ {        alias /home/www/myproject/static/;        expires 30d;        add_header Cache-Control "public, immutable";    }    location /uploads/ {        alias /home/www/myproject/static/uploads/;        expires 7d;    }    # ========== 反向代理到 .NET 应用 ==========    location / {        proxy_pass http://127.0.0.1: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_connect_timeout 60s;        proxy_send_timeout 60s;        proxy_read_timeout 60s;        # 请求体大小限制（上传文件时需要）        client_max_body_size 100m;    }}EOF# 测试配置sudo nginx -t# 重新加载 Nginxsudo systemctl reload nginx

7.2 通过 Nginx 访问应用

# 通过 80 端口访问（等效于访问 .NET 应用）curl http://localhost/health# 输出：{"status":"healthy","timestamp":"...","server":"..."}curl http://localhost/api/test# 输出：{"message":"部署成功！.NET Web API 运行正常 ✅","time":"...","version":"1.0.0"}

现在，访问 http://你的服务器IP 就能看到你的 .NET 应用了！

八、使用 Git 管理部署（进阶）

手动上传文件到服务器很麻烦，更规范的做法是使用 Git 管理代码，在服务器上拉取最新代码并自动发布。

8.1 在服务器上初始化 Git

# 如果是你自己的项目，从仓库克隆cd /home/www/myproject/sourcegit clone https://github.com/你的用户名/你的项目.git# 如果是之前创建的示例项目，初始化 Gitcd /home/www/myproject/source/MyWebApigit initgit add .git commit -m "初始提交"

8.2 创建部署脚本

每次更新代码后，手动执行编译发布太麻烦。创建一个部署脚本一键完成：

sudo tee /home/www/myproject/deploy.sh << 'EOF'#!/bin/bash# ==========================================# .NET 项目部署脚本# 用法：bash deploy.sh# ==========================================set -e  # 遇到错误立即退出PROJECT_DIR="/home/www/myproject"SOURCE_DIR="$PROJECT_DIR/source"PUBLISH_DIR="$PROJECT_DIR/publish"SERVICE_NAME="mywebapi"echo "========================================"echo "  .NET 项目部署开始：$(date)"echo "========================================"# 步骤 1：拉取最新代码echo "[1/4] 拉取最新代码..."cd $SOURCE_DIR/MyWebApigit pull origin main 2>/dev/null || echo "  (非 Git 仓库，跳过)"# 步骤 2：编译发布echo "[2/4] 编译发布..."dotnet publish -c Release -o $PUBLISH_DIRecho "  ✅ 发布完成"# 步骤 3：设置权限echo "[3/4] 设置权限..."sudo chown -R deploy:deploy $PUBLISH_DIRsudo chmod -R 755 $PUBLISH_DIRecho "  ✅ 权限设置完成"# 步骤 4：重启服务echo "[4/4] 重启服务..."sudo systemctl restart $SERVICE_NAMEecho "  ✅ 服务重启完成"echo "========================================"echo "  ✅ 部署完成：$(date)"echo "========================================"# 验证sleep 2curl -s http://localhost:5000/healthEOF# 给脚本执行权限sudo chmod +x /home/www/myproject/deploy.shsudo chown deploy:deploy /home/www/myproject/deploy.sh

8.3 使用部署脚本

# 以后更新代码只需要两步：# 第 1 步：在本地提交代码并推送git push origin main# 第 2 步：在服务器上执行部署脚本sudo -u deploy bash /home/www/myproject/deploy.sh

8.4 使用 Git Hooks 自动部署（进阶）

如果想让推送代码时自动触发部署，可以配置 Git Hooks：

# 在服务器上创建 post-receive 钩子sudo mkdir -p /home/www/myproject/.git/hookssudo tee /home/www/myproject/.git/hooks/post-receive << 'EOF'#!/bin/bashwhile read oldrev newrev refnamedo    branch=$(git rev-parse --symbolic --abbrev-ref $refname)    if [ "$branch" = "main" ]; then        echo "检测到 main 分支更新，开始部署..."        bash /home/www/myproject/deploy.sh    fidoneEOFsudo chmod +x /home/www/myproject/.git/hooks/post-receive

九、常见问题

❓ Q1：dotnet 命令找不到

错误信息：dotnet: command not found

原因：.NET SDK 未安装或 PATH 环境变量未配置。

解决方案：

# 检查是否安装了 dotnetls -la /usr/share/dotnet/dotnet# 如果文件存在，添加 PATHecho 'export PATH=$PATH:/usr/share/dotnet' >> ~/.bashrcsource ~/.bashrc# 如果文件不存在，重新安装sudo apt install -y dotnet-sdk-8.0

❓ Q2：服务启动失败 "Failed to start MyWebApi"

排查步骤：

# ① 查看详细错误信息sudo journalctl -u mywebapi -n 50 --no-pager# ② 检查 appsettings.json 语法# 尝试手动运行应用，看具体报错sudo -u deploy dotnet /home/www/myproject/publish/MyWebApi.dll# ③ 常见错误：# - 端口被占用：修改 APP_PORT 或停掉占用进程# - 数据库连接失败：检查连接字符串# - 缺少运行时：dotnet --list-runtimes 确认安装了 ASP.NET Core Runtime

❓ Q3：端口被占用 "Address already in use"

# 查看哪个进程占用了 5000 端口sudo ss -tlnp | grep :5000# 如果是旧进程，杀掉它sudo kill -9 进程PID# 或者修改 APP_PORT 换一个端口# 编辑 /etc/systemd/system/mywebapi.service# 修改 Environment=APP_PORT=5001# sudo systemctl daemon-reload && sudo systemctl restart mywebapi

❓ Q4：Nginx 报 502 Bad Gateway

原因：Nginx 无法连接到后端 .NET 应用。

排查步骤：

# ① 检查 .NET 应用是否在运行curl http://localhost:5000/health# ② 如果应用没运行，启动它sudo systemctl start mywebapi# ③ 检查 Nginx 错误日志sudo tail -f /var/log/nginx/error.log# ④ 检查 proxy_pass 地址是否正确# 确认 /etc/nginx/sites-available/myproject 中 proxy_pass 指向的地址和端口正确

❓ Q5：Nginx 报 413 Request Entity Too Large

原因：上传的文件超过了 Nginx 默认的请求体大小限制（1MB）。

解决方案：

# 在 Nginx 配置的 server 或 location 块中添加：client_max_body_size 100m;# 重新加载 Nginxsudo systemctl reload nginx

❓ Q6：修改代码后需要重启服务

# .NET 应用不像 PHP 那样每次请求重新加载# 修改代码后必须重启服务才能生效# 方案一：手动重启sudo systemctl restart mywebapi# 方案二：使用 dotnet watch（开发环境）# 在项目目录中运行dotnet watch run# 方案三：生产环境的"热重载"（谨慎使用）# 在 Program.cs 中添加：builder.WebHost.UseStaticWebAssets();# 然后使用：dotnet watch run --no-hot-reload

❓ Q7：磁盘空间不足导致编译失败

# 清理 NuGet 缓存（可以释放几百 MB 空间）dotnet nuget locals all --clear# 清理临时文件sudo apt cleansudo journalctl --vacuum-time=7d# 查看磁盘占用df -h

十、验证清单

部署完成后，逐项检查确认：

[✅] .NET SDK/Runtime 安装成功（dotnet --version）[✅] 应用发布到 /home/www/myproject/publish[✅] 应用能正常启动（dotnet MyWebApi.dll）[✅] systemd 服务已配置并开机自启[✅] 服务状态 active (running)[✅] 健康检查接口正常（curl /health）[✅] API 接口正常（curl /api/test）[✅] Nginx 反向代理配置正确[✅] 通过 Nginx 访问正常（curl http://localhost/health）[✅] 进程崩溃后自动重启（kill -9 测试）[✅] 部署脚本创建完成

十一、总结

至此，你的 .NET Web 应用已经成功部署到 Linux 服务器上，并且具备了生产环境的可靠性保障！

本文要点回顾：

第三篇：实战部署 .NET Web 应用├── ✅ 安装 .NET SDK 8.0├── ✅ 创建/编译/发布 .NET Web API 项目├── ✅ 配置生产环境变量├── ✅ 使用 systemd 管理进程│   ├── 开机自启（enable）│   ├── 自动重启（Restart=always）│   └── 统一日志管理（journalctl）├── ✅ Nginx 反向代理配置├── ✅ 部署脚本自动化└── ✅ 常见问题排查

下一篇预告：《Linux 从零部署项目实战指南（四）：域名绑定、HTTPS 证书与 CI/CD 自动化》我们将配置域名解析、申请免费 SSL 证书，并搭建 GitHub Actions 自动部署流水线，让代码推送后自动发布到服务器。

如果你在操作过程中遇到任何问题，欢迎在评论区留言交流！

📌 本系列持续更新中，关注 IT在线自学 第一时间获取最新教程。