这次我们来看一个 .NET 项目从开发到上线的完整实战过程。标题里的“NET10 API网站”指的就是基于 .NET 10 框架开发的 Web API 应用。对于很多 .NET 开发者来说本地开发调试只是第一步如何将 API 服务稳定、高效地部署到 Ubuntu 服务器上并处理好依赖、端口、进程管理这些运维细节才是项目真正能跑起来的关键。这篇文章不讲复杂的架构理论直接聚焦于从发布到部署的实操链路。核心目标就一个让你能参照步骤把一个 .NET 10 的 API 项目成功部署到 Ubuntu 服务器并能通过接口访问。我们会重点关注发布配置、服务器环境准备、服务部署方式以及后续的维护和问题排查。无论你是个人开发者想部署自己的小项目还是团队需要搭建测试环境这套流程都能直接复用。1. 核心能力速览在深入部署细节前我们先快速了解基于 .NET 10 的 API 项目部署到 Ubuntu 服务器的核心要点。能力项说明项目类型基于 .NET 10 的 Web API 应用程序部署目标Ubuntu 服务器通常为 20.04 LTS 或 22.04 LTS发布方式框架依赖FDD或独立SCD发布推荐使用dotnet publish命令运行环境服务器需安装 .NET 运行时FDD模式或无需额外安装SCD模式服务托管可通过 Kestrel 直接运行或使用反向代理如 Nginx 进程管理如 systemd启动方式命令行直接启动、systemd 服务守护、Docker 容器化部署接口能力提供标准的 RESTful API 接口可通过 Swagger/OpenAPI 文档查看适合场景个人项目部署、微服务后端、企业内部系统、API 服务测试环境搭建从表格可以看出部署的核心在于环境匹配和进程管理。.NET 10 的跨平台特性让它在 Linux 上运行良好但如何让它像原生服务一样稳定运行是我们要解决的重点。2. 适用场景与使用边界这个部署流程主要适用于以下场景个人学习与测试将本地开发的 .NET API 部署到云服务器用于演示或功能测试。小型项目上线为创业项目或内部工具提供后端 API 服务。微服务架构中的单个服务在 Linux 服务器集群中部署特定的 .NET 微服务。CI/CD 实践作为持续集成/持续部署流水线的最终部署环节。需要注意的使用边界性能与规模本文介绍的基于 Kestrel systemd/Nginx 的部署方式适用于中小流量场景。对于超高并发需求需要考虑负载均衡、集群化部署和更精细的性能调优。安全性直接暴露 Kestrel 到公网存在风险务必通过 Nginx 等反向代理进行转发并配置防火墙规则。数据与状态部署时需妥善处理数据库连接字符串、API密钥等敏感信息推荐使用环境变量或安全的配置管理方式切勿硬编码在代码中。合规性确保部署的 API 服务内容合法合规不涉及侵权、敏感数据泄露等风险。3. 环境准备与前置条件开始部署前需要确保本地开发环境和目标服务器环境准备就绪。3.1 本地开发环境.NET SDK 10.0用于编译和发布项目。可通过dotnet --version命令验证。完整的 API 项目确保项目在本地能正常运行和调试。发布配置检查appsettings.json或appsettings.Production.json确保生产环境配置如数据库连接字符串、日志级别已正确设置。3.2 目标 Ubuntu 服务器环境操作系统Ubuntu 20.04 LTS 或 22.04 LTS推荐长期支持版本。网络服务器拥有公网 IP 或可在目标网络内访问。确保 SSH 服务已开启。权限拥有一个具有sudo权限的用户账号。基础工具确保已安装curl、wget、git如需从仓库拉取代码、unzip等常用工具。.NET 运行时可选如果采用框架依赖发布FDD服务器必须安装对应版本的 .NET 运行时。如果采用独立发布SCD则无需安装。4. 项目发布与打包部署的第一步是将本地项目发布为可在目标服务器上运行的包。4.1 发布配置检查在项目目录下检查.csproj文件确保运行时标识符Runtime Identifier包含linux-x64以便发布 Linux 版本。PropertyGroup TargetFrameworknet10.0/TargetFramework !-- 添加以下行支持发布到Linux -- RuntimeIdentifierswin-x64;linux-x64/RuntimeIdentifiers /PropertyGroup4.2 执行发布命令打开终端进入项目根目录执行发布命令。这里演示两种常用方式方式一框架依赖发布FDD包体积小# 发布为框架依赖、Linux 64位版本输出到 ./publish 目录 dotnet publish -c Release -r linux-x64 --self-contained false -o ./publish此方式生成的发布包较小但要求服务器安装有对应的 .NET 运行时。方式二独立发布SCD包体积大# 发布为独立、Linux 64位版本输出到 ./publish 目录 dotnet publish -c Release -r linux-x64 --self-contained true -o ./publish此方式会将 .NET 运行时一起打包发布包体积较大约100MB但服务器无需安装 .NET。4.3 打包发布文件发布完成后./publish目录下即为所有运行所需的文件。为了方便上传可以将其压缩。# 在 publish 目录的上一级执行 tar -czvf net10-api-release.tar.gz -C publish .现在你得到了一个名为net10-api-release.tar.gz的压缩包包含了部署所需的一切。5. 服务器环境配置与部署接下来我们将发布包部署到 Ubuntu 服务器并配置运行环境。5.1 上传发布包至服务器使用scp命令或 SFTP 工具如 FileZilla将压缩包上传到服务器。假设服务器 IP 为192.168.1.100用户名为ubuntu。# 在本地终端执行 scp net10-api-release.tar.gz ubuntu192.168.1.100:/home/ubuntu/5.2 服务器端解压与准备通过 SSH 登录服务器进行解压和目录准备。ssh ubuntu192.168.1.100 # 创建应用目录例如 /var/www/net10api sudo mkdir -p /var/www/net10api # 将发布包移动到目标目录并解压 sudo mv /home/ubuntu/net10-api-release.tar.gz /var/www/net10api/ cd /var/www/net10api sudo tar -xzvf net10-api-release.tar.gz # 设置目录权限确保当前用户有读写执行权限这里假设你的用户是 ubuntu sudo chown -R ubuntu:ubuntu /var/www/net10api5.3 安装 .NET 运行时仅框架依赖发布需要如果采用框架依赖发布FDD需要在服务器上安装 .NET 运行时。# 添加 Microsoft 包仓库和安装密钥 wget https://packages.microsoft.com/config/ubuntu/22.04/packages-microsoft-prod.deb -O packages-microsoft-prod.deb sudo dpkg -i packages-microsoft-prod.deb rm packages-microsoft-prod.deb # 更新包列表并安装 .NET 运行时以 .NET 10 为例 sudo apt-get update sudo apt-get install -y dotnet-runtime-10.0 # 验证安装 dotnet --list-runtimes你应该能看到Microsoft.NETCore.App 10.x.x等运行时信息。6. 配置服务进程与反向代理为了让 API 服务在后台稳定运行并能通过域名或 IP 访问我们需要配置进程守护和反向代理。6.1 使用 systemd 守护进程systemd是 Linux 的系统和服务管理器可以确保我们的应用在服务器启动时自动运行并在崩溃后重启。创建 service 文件sudo nano /etc/systemd/system/net10api.service编辑 service 文件内容[Unit] DescriptionNET10 API Service Afternetwork.target [Service] Typeexec # 修改为你的工作目录和启动命令 WorkingDirectory/var/www/net10api ExecStart/usr/bin/dotnet /var/www/net10api/YourApiProject.dll # 如果使用独立发布ExecStart 应为ExecStart/var/www/net10api/YourApiProject Restartalways RestartSec10 KillSignalSIGINT SyslogIdentifiernet10api Userubuntu EnvironmentASPNETCORE_ENVIRONMENTProduction EnvironmentDOTNET_PRINT_TELEMETRY_MESSAGEfalse [Install] WantedBymulti-user.target关键参数说明WorkingDirectory应用的工作目录。ExecStart启动命令。框架依赖发布用dotnet yourapp.dll独立发布直接执行./yourapp。User运行服务的用户确保其对工作目录有权限。Environment设置环境变量ASPNETCORE_ENVIRONMENTProduction至关重要。启用并启动服务# 重新加载 systemd 配置 sudo systemctl daemon-reload # 启用开机自启 sudo systemctl enable net10api.service # 立即启动服务 sudo systemctl start net10api.service # 查看服务状态和日志 sudo systemctl status net10api.service sudo journalctl -u net10api.service -f如果状态显示active (running)并且日志中没有报错说明服务已成功启动。默认情况下Kestrel 会监听http://localhost:5000和https://localhost:5001。6.2 配置 Nginx 反向代理推荐直接通过 5000 端口访问不够友好且 Kestrel 面对公网流量时用 Nginx 作为反向代理可以提供更好的性能、安全性和静态文件服务能力。安装 Nginxsudo apt-get update sudo apt-get install -y nginx配置 Nginx 站点sudo nano /etc/nginx/sites-available/net10api写入以下配置假设你的域名是api.yourdomain.com如果没有域名用服务器 IP 也可server { listen 80; server_name api.yourdomain.com; # 替换为你的域名或服务器IP location / { proxy_pass http://localhost:5000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection keep-alive; proxy_set_header Host $host; proxy_cache_bypass $http_upgrade; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }启用站点并测试配置# 创建软链接以启用站点 sudo ln -s /etc/nginx/sites-available/net10api /etc/nginx/sites-enabled/ # 测试 Nginx 配置语法 sudo nginx -t # 如果显示 syntax is ok则重启 Nginx sudo systemctl restart nginx7. 功能测试与效果验证服务启动并配置好反向代理后需要进行全面的功能测试。7.1 基础连通性测试首先测试服务是否在本地正常运行。# 在服务器上测试本地端口Kestrel curl http://localhost:5000/weatherforecast # 或测试你定义的某个健康检查端点例如 curl http://localhost:5000/health如果返回 JSON 数据或预期的响应说明 Kestrel 服务正常。然后测试 Nginx 反向代理是否工作。# 从服务器本机测试 Nginx 转发的请求 curl http://localhost/api/your-endpoint # 或者从你的本地机器测试确保防火墙开放了80端口 curl http://api.yourdomain.com/api/your-endpoint7.2 API 接口测试使用 Postman、cURL 或浏览器直接访问 API 的 Swagger 文档页面如果项目启用了。Swagger UI访问http://api.yourdomain.com/swagger或http://api.yourdomain.com/swagger/index.html。关键接口调用选择几个核心的 GET、POST 接口进行测试验证业务逻辑是否正确。# 示例测试一个获取数据的 GET 接口 curl -X GET http://api.yourdomain.com/api/products # 示例测试一个提交数据的 POST 接口 curl -X POST http://api.yourdomain.com/api/orders \ -H Content-Type: application/json \ -d {productId: 1, quantity: 5}7.3 性能与稳定性观察查看服务日志持续监控journalctl日志观察是否有错误或警告。sudo journalctl -u net10api.service --since 5 minutes ago -f监控资源占用使用htop或top命令查看dotnet进程的 CPU 和内存占用情况。top -p $(pgrep -f YourApiProject.dll)压力测试可选对于重要服务可以使用ab(Apache Benchmark) 或wrk进行简单的并发测试观察服务响应。sudo apt-get install -y apache2-utils ab -n 1000 -c 50 http://api.yourdomain.com/api/health8. 接口 API 与批量任务集成考虑部署好的 API 服务其价值在于被其他系统调用。这里讨论集成时的关键点。8.1 API 调用示例假设你的 API 有一个处理任务的端点其他服务可以通过 HTTP 客户端调用。# Python 调用示例 (使用 requests 库) import requests import json api_base http://api.yourdomain.com/api headers {Content-Type: application/json} # 调用一个处理接口 def process_item(item_data): url f{api_base}/process try: response requests.post(url, jsonitem_data, headersheaders, timeout30) response.raise_for_status() # 检查HTTP错误 return response.json() except requests.exceptions.RequestException as e: print(fAPI调用失败: {e}) return None # 使用示例 result process_item({id: 123, action: start}) if result: print(f处理结果: {result})8.2 批量任务处理策略如果 API 需要处理批量任务有几种常见策略API 内循环客户端循环调用单个处理接口。简单但网络开销大且一个失败会影响整体。专用批量端点在 API 中设计一个接收任务数组的端点在服务器端进行循环处理。减少了网络往返但可能导致单个请求超时。队列异步处理更健壮的方式。API 接收任务后立即将其放入消息队列如 RabbitMQ、Azure Service Bus、Redis Streams然后由单独的后台工作进程Worker Service从队列中取出并处理。这种方式解耦性好支持重试适合大规模批量任务。.NET 实现可以创建另一个 .NET Worker Service 项目引用相同的业务逻辑库专用于消费队列消息。9. 资源占用与性能观察部署后持续观察资源占用是保证服务稳定的重要环节。9.1 关键监控指标内存RSS.NET 应用启动后内存会逐渐增长并稳定。使用top或htop观察RES列。如果内存持续增长内存泄漏需要排查代码。CPU 使用率在请求处理期间 CPU 使用率会升高。持续高 CPU 可能意味着存在性能瓶颈或死循环。磁盘 I/O如果应用有大量日志写入或文件操作需关注磁盘 IOPS。网络连接使用netstat或ss命令查看应用监听的端口如 5000上的连接数。sudo netstat -tlnp | grep :5000 sudo ss -tlnp | grep :50009.2 日志与诊断.NET Core 内置了丰富的日志和诊断工具。应用日志通过appsettings.Production.json配置日志级别和输出目标文件、控制台等。{ Logging: { LogLevel: { Default: Information, Microsoft.AspNetCore: Warning // 在生产环境降低ASP.NET Core自身日志级别 }, File: { Path: /var/log/net10api/app.log, Append: true, FileSizeLimitBytes: 10485760, // 10MB MaxRollingFiles: 5 } } }Dump 文件分析如果应用崩溃可以生成内存转储文件进行分析。# 安装 dotnet-dump 工具 dotnet tool install -g dotnet-dump # 捕获进程 dump sudo dotnet-dump collect -p PID10. 常见问题与排查方法部署过程中难免会遇到问题下表列出了常见问题及排查思路。问题现象可能原因排查方式解决方案systemctl status显示failed1. 启动命令错误2. 工作目录或文件权限不足3. 依赖的端口被占用4. 应用本身启动报错sudo journalctl -u net10api.service -xe查看详细错误日志。根据日志修正检查ExecStart路径、确保User有权限、更改应用端口、修复代码错误。Nginx 返回 502 Bad Gateway1. 后端 Kestrel 服务未运行2. Nginxproxy_pass地址端口错误3. 防火墙阻止了本地回环访问1.sudo systemctl status net10api2.curl http://localhost:50003. 检查 Nginx 配置中的proxy_pass。1. 启动或重启后端服务。2. 修正 Nginx 配置。3. 检查ufw或iptables规则。API 接口访问超时或无响应1. 应用处理请求过慢或死锁2. 服务器资源CPU/内存耗尽3. 数据库连接失败1. 查看应用日志和top命令。2. 检查数据库连接字符串和状态。1. 优化代码逻辑增加超时设置。2. 扩容服务器资源。3. 检查数据库网络和权限。Swagger 页面能打开但接口调用失败1. CORS跨域策略未配置2. 接口路由错误3. 模型绑定或验证失败1. 浏览器开发者工具查看网络请求错误。2. 查看应用日志中关于请求的详细信息。1. 在Program.cs中正确配置 CORS。2. 检查控制器和 Action 的路由属性。3. 检查客户端发送的数据格式。应用运行一段时间后内存暴涨内存泄漏如未释放的大对象、静态集合持续增长、事件未取消订阅等。1. 定期观察内存趋势。2. 使用dotnet-counters监控 GC 情况。3. 生成内存转储分析。使用性能分析工具如 dotMemory, Visual Studio Diagnostic Tools定位泄漏源修复代码。dotnet命令未找到.NET 运行时或 SDK 未安装或未正确配置 PATH。执行dotnet --info。按照本文第 5.3 节重新安装 .NET 运行时或使用独立发布SCD方式。11. 最佳实践与使用建议为了让部署更稳健遵循以下最佳实践使用配置管理永远不要将连接字符串、API密钥等敏感信息提交到代码仓库。使用appsettings.Production.json不提交、环境变量或专业的密钥管理服务如 Azure Key Vault, AWS Secrets Manager。实现健康检查在 API 项目中添加健康检查端点如/health方便监控系统如 Prometheus或负载均衡器探测服务状态。设置合理的日志生产环境将日志级别设为Warning或Error避免日志过多影响 I/O 性能。同时将日志输出到文件或日志服务如 Serilog Elasticsearch便于集中查询。考虑使用 Docker对于更复杂的环境或需要快速水平扩展的场景使用 Docker 容器化部署是更好的选择。可以编写Dockerfile构建镜像后在任何支持 Docker 的环境中运行环境一致性极高。# 示例 Dockerfile (多阶段构建) FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build WORKDIR /src COPY [YourApiProject.csproj, ./] RUN dotnet restore COPY . . RUN dotnet publish -c Release -o /app/publish FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime WORKDIR /app COPY --frombuild /app/publish . ENTRYPOINT [dotnet, YourApiProject.dll]备份与回滚在更新应用前备份当前的发布目录和数据库。准备好快速回滚到上一个版本的方案。监控与告警除了查看日志建议配置基础的系统监控CPU、内存、磁盘和应用监控请求数、错误率、响应时间。可以使用 Grafana Prometheus 等开源方案。从本地代码到云端服务部署是打通“最后一公里”的关键。这套基于 Ubuntu systemd Nginx 的部署方案平衡了简单性与可靠性适合大多数中小型 .NET API 项目。成功部署后重点就从功能开发转向了稳定性保障和性能优化。建议将上述步骤脚本化并集成到你的 CI/CD 流程中实现一键部署进一步提升效率。如果在部署中遇到上表未覆盖的特定问题多关注应用日志和系统日志它们通常能给出最直接的线索。