這類項目最值得先看的不是功能列表而是能不能在普通環(huán)境里穩(wěn)定跑起來。一個標(biāo)著“API網(wǎng)站”的項目從發(fā)布到部署到Ubuntu服務(wù)器核心要解決的是把開發(fā)環(huán)境里的代碼、依賴和配置完整、可靠地搬到生產(chǎn)服務(wù)器上并且讓API服務(wù)能持續(xù)對外響應(yīng)。很多人卡在部署這一步不是因為代碼寫錯了而是環(huán)境、權(quán)限、網(wǎng)絡(luò)、進程管理這些環(huán)節(jié)沒理清楚。我建議把部署過程拆成三步環(huán)境準(zhǔn)備、服務(wù)發(fā)布、持續(xù)運行。下面按實際落地順序拆一遍重點不是復(fù)述命令而是解釋每個環(huán)節(jié)為什么做以及做錯了會卡在哪里。1. 先理清項目依賴和服務(wù)器環(huán)境別急著上傳代碼部署失敗最常見的原因是本地開發(fā)環(huán)境和線上服務(wù)器環(huán)境不一致。NET項目這里指.NET Core/.NET 5雖然跨平臺但依賴的運行時版本、系統(tǒng)庫、文件權(quán)限如果對不上啟動就會報錯。1.1 確認(rèn)項目類型和發(fā)布方式首先你得知道自己的項目是什么類型。是傳統(tǒng)的.NET Framework項目只能在Windows上跑還是.NET Core/.NET 5/6/7/8的跨平臺項目如果是前者部署到Ubuntu需要完全不同的方案例如通過Mono這不在常規(guī)“發(fā)布到Ubuntu”的討論范圍內(nèi)。我們默認(rèn)討論的是后者即基于dotnet命令行的跨平臺項目。發(fā)布方式通常有兩種框架依賴發(fā)布 (Framework-dependent deployment, FDD)只發(fā)布你的應(yīng)用代碼和第三方依賴運行時依賴目標(biāo)服務(wù)器上安裝的.NET運行時。發(fā)布包小但要求服務(wù)器上必須安裝對應(yīng)版本的.NET運行時。獨立發(fā)布 (Self-contained deployment, SCD)把.NET運行時和你的應(yīng)用一起打包發(fā)布。發(fā)布包很大通常100MB但服務(wù)器上不需要安裝.NET運行時環(huán)境更干凈。對于服務(wù)器部署我一般更推薦框架依賴發(fā)布。因為服務(wù)器環(huán)境相對固定統(tǒng)一安裝一次運行時后續(xù)部署多個應(yīng)用都受益而且更新運行時也只需一次操作不用每個應(yīng)用都打包一次巨大的運行時。1.2 準(zhǔn)備Ubuntu服務(wù)器環(huán)境拿到一臺新的Ubuntu服務(wù)器比如22.04 LTS或24.04 LTS不要一上來就傳代碼。先做這幾件事1. 系統(tǒng)更新和基礎(chǔ)工具sudo apt update sudo apt upgrade -y sudo apt install -y curl wget gnupg software-properties-common這是標(biāo)準(zhǔn)起手式確保包管理器是最新的并安裝后續(xù)可能用到的工具。2. 安裝.NET運行時或SDK如果你的應(yīng)用是框架依賴發(fā)布服務(wù)器需要安裝對應(yīng)版本的.NET運行時。假設(shè)你的項目是.NET 8安裝命令如下# 添加微軟包倉庫 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運行時如果只需要運行不開發(fā)就裝這個 sudo apt update sudo apt install -y dotnet-runtime-8.0 # 或者安裝SDK包含運行時還允許你編譯 # sudo apt install -y dotnet-sdk-8.0關(guān)鍵點版本號8.0必須和你的項目TargetFramework一致。安裝后用dotnet --info驗證。3. 配置防火墻和端口API服務(wù)需要監(jiān)聽一個端口比如5000或8080。確保服務(wù)器的防火墻如ufw允許該端口。# 查看防火墻狀態(tài) sudo ufw status # 如果沒開可以跳過。如果開了放行端口例如5000 sudo ufw allow 5000/tcp sudo ufw reload更常見的坑是云服務(wù)器如阿里云、騰訊云的安全組規(guī)則。你必須在云服務(wù)商的控制臺里為這臺服務(wù)器的安全組添加入站規(guī)則允許你的API端口和SSH的22端口。4. 準(zhǔn)備應(yīng)用目錄和權(quán)限不要用root用戶直接運行應(yīng)用。創(chuàng)建一個專用用戶和目錄權(quán)限更清晰。# 創(chuàng)建用戶例如叫apiuser sudo adduser --system --no-create-home --group apiuser # 創(chuàng)建應(yīng)用目錄 sudo mkdir -p /var/www/myapi sudo chown -R apiuser:apiuser /var/www/myapi目錄準(zhǔn)備好就可以上傳發(fā)布包了。2. 在本地完成發(fā)布并驗證發(fā)布包很多人直接在服務(wù)器上git clone然后dotnet publish這對于小項目可以但對于依賴復(fù)雜或需要編譯原生組件的項目容易出問題。更穩(wěn)妥的做法是在本地或CI機器上發(fā)布生成完整的發(fā)布包再上傳到服務(wù)器。2.1 本地發(fā)布命令在你的項目根目錄解決方案目錄或項目文件所在目錄執(zhí)行# 框架依賴發(fā)布到 ./publish 目錄 dotnet publish -c Release -o ./publish --framework net8.0 # 如果是獨立發(fā)布加上 -r 參數(shù)例如Linux x64 # dotnet publish -c Release -o ./publish --framework net8.0 -r linux-x64 --self-contained true-c Release使用Release配置編譯優(yōu)化程度更高。-o ./publish指定輸出目錄。--framework net8.0指定目標(biāo)框架必須和項目文件一致。發(fā)布完成后檢查./publish目錄。你應(yīng)該看到你的應(yīng)用主DLL例如MyApi.dllappsettings.json等配置文件wwwroot靜態(tài)文件目錄如果有各種第三方依賴的DLL沒有*.cs源代碼文件2.2 本地快速驗證發(fā)布包可選但推薦在本地你可以切換到publish目錄嘗試運行一下發(fā)布包看是否能獨立啟動。cd ./publish dotnet MyApi.dll # 或者指定URL # dotnet MyApi.dll --urls http://localhost:5000如果本地能跑起來訪問http://localhost:5000/swagger如果用了Swagger或你的API端點能返回數(shù)據(jù)說明發(fā)布包本身是完整的。這一步能提前排除掉因缺少文件或配置錯誤導(dǎo)致的問題。3. 上傳發(fā)布包到服務(wù)器并配置服務(wù)進程發(fā)布包驗證無誤后上傳到服務(wù)器。可以用scp、rsync或者通過CI/CD工具如GitHub Actions, GitLab CI自動傳輸。3.1 上傳文件并設(shè)置權(quán)限假設(shè)你本地發(fā)布包在./publish服務(wù)器目標(biāo)目錄是/var/www/myapi。# 從本地上傳整個目錄 scp -r ./publish/* apiuseryour_server_ip:/var/www/myapi/ # 或者用rsync支持增量更高效 rsync -avz ./publish/ apiuseryour_server_ip:/var/www/myapi/上傳后再次確認(rèn)權(quán)限ssh apiuseryour_server_ip sudo chown -R apiuser:apiuser /var/www/myapi sudo chmod -R 755 /var/www/myapi3.2 使用systemd配置后臺服務(wù)讓API服務(wù)在后臺穩(wěn)定運行并且開機自啟最標(biāo)準(zhǔn)的方式是配置systemd服務(wù)。不要用nohup或screen那些方式不方便管理日志和自動重啟。在服務(wù)器上創(chuàng)建服務(wù)文件sudo nano /etc/systemd/system/myapi.service寫入以下配置根據(jù)你的實際情況調(diào)整[Unit] DescriptionMy NET API Service Afternetwork.target [Service] Typeexec Userapiuser Groupapiuser WorkingDirectory/var/www/myapi ExecStart/usr/bin/dotnet /var/www/myapi/MyApi.dll Restartalways RestartSec10 KillSignalSIGINT SyslogIdentifiermyapi EnvironmentASPNETCORE_ENVIRONMENTProduction EnvironmentDOTNET_PRINT_TELEMETRY_MESSAGEfalse [Install] WantedBymulti-user.target關(guān)鍵參數(shù)解釋User/Group: 用我們創(chuàng)建的專用用戶運行更安全。WorkingDirectory: 應(yīng)用的工作目錄影響配置文件讀取和日志寫入的當(dāng)前路徑。ExecStart: 啟動命令。如果是框架依賴發(fā)布就用/usr/bin/dotnet啟動你的DLL。如果是獨立發(fā)布你的DLL就是可執(zhí)行文件可以直接/var/www/myapi/MyApi。Restartalways: 服務(wù)崩潰后自動重啟提高可用性。Environment: 設(shè)置環(huán)境變量。ASPNETCORE_ENVIRONMENTProduction很重要它會告訴ASP.NET Core使用生產(chǎn)環(huán)境配置例如appsettings.Production.json。DOTNET_PRINT_TELEMETRY_MESSAGEfalse: 禁用.NET遙測信息讓日志更干凈。保存后啟用并啟動服務(wù)sudo systemctl daemon-reload sudo systemctl enable myapi.service sudo systemctl start myapi.service3.3 檢查服務(wù)狀態(tài)和日志服務(wù)啟動后不要假設(shè)它一定在運行。立刻檢查狀態(tài)和日志。# 查看服務(wù)狀態(tài) sudo systemctl status myapi.service # 查看實時日志按CtrlC退出 sudo journalctl -u myapi.service -f # 查看最近100行日志 sudo journalctl -u myapi.service -n 100在日志里你應(yīng)該看到類似這樣的信息Now listening on: http://[::]:5000 Application started. Press CtrlC to shut down. Hosting environment: Production如果看到錯誤比如“端口已被占用”、“找不到依賴”、“配置文件錯誤”日志會給出明確線索。4. 配置反向代理Nginx和域名訪問雖然你的API服務(wù)已經(jīng)在5000端口運行了但直接暴露http://服務(wù)器IP:5000不夠?qū)I(yè)也不安全。通常我們會用Nginx或Apache作為反向代理處理SSL、靜態(tài)文件、負(fù)載均衡等。4.1 安裝和配置Nginx在Ubuntu上安裝Nginxsudo apt install -y nginx為你的API站點創(chuàng)建Nginx配置文件sudo nano /etc/nginx/sites-available/myapi寫入配置假設(shè)你的API跑在5000端口域名是api.yourdomain.comserver { listen 80; server_name api.yourdomain.com; # 改成你的域名或服務(wù)器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_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; # 如果API響應(yīng)較慢可以適當(dāng)調(diào)大超時時間 proxy_read_timeout 300s; proxy_connect_timeout 75s; } # 可選靜態(tài)文件由Nginx直接處理效率更高 location ~ ^/(wwwroot)/ { root /var/www/myapi; expires 1y; add_header Cache-Control public, immutable; } # 可選屏蔽對敏感文件的直接訪問 location ~ /\. { deny all; } }啟用這個站點配置sudo ln -s /etc/nginx/sites-available/myapi /etc/nginx/sites-enabled/ sudo nginx -t # 測試配置語法是否正確 sudo systemctl reload nginx # 重新加載Nginx配置4.2 配置SSLHTTPS現(xiàn)在幾乎所有公開API都要求HTTPS。可以使用Let‘s Encrypt免費證書。# 安裝Certbot sudo apt install -y certbot python3-certbot-nginx # 獲取并安裝證書會自動修改Nginx配置 sudo certbot --nginx -d api.yourdomain.com按照提示操作Certbot會自動配置好HTTPS并設(shè)置自動續(xù)期。之后你的API就可以通過https://api.yourdomain.com訪問了。4.3 驗證反向代理配置完成后訪問你的域名應(yīng)該能看到API的響應(yīng)。同時檢查Nginx日志和你的應(yīng)用日志確認(rèn)請求被正確轉(zhuǎn)發(fā)。# 查看Nginx訪問日志 sudo tail -f /var/log/nginx/access.log # 查看Nginx錯誤日志 sudo tail -f /var/log/nginx/error.log如果遇到502 Bad Gateway錯誤通常意味著Nginx無法連接到后端服務(wù)localhost:5000。請檢查你的API服務(wù)myapi.service是否在運行sudo systemctl status myapi.service你的API是否確實監(jiān)聽在localhost:5000可以在服務(wù)器上執(zhí)行curl http://localhost:5000/health如果你有健康檢查端點測試。防火墻是否阻止了本地回環(huán)接口的通信通常不會但可以檢查。5. 處理部署中的常見問題和進階配置部署上線只是開始要讓服務(wù)穩(wěn)定運行還需要處理一些常見場景和問題。5.1 處理靜態(tài)文件和Swagger UI如果你的API項目包含了Swagger UI訪問/swagger或/swagger/index.html在反向代理后通常能正常訪問。但有時需要確保UseSwagger和UseSwaggerUI中間件在Production環(huán)境下也被啟用或者至少不報錯。在Program.cs中通常會有環(huán)境判斷if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); }在生產(chǎn)環(huán)境你可能也想啟用Swagger給內(nèi)部測試用可以改成// 根據(jù)配置或環(huán)境變量決定是否啟用 if (app.Configuration.GetValuebool(EnableSwagger) || app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); }然后在appsettings.Production.json中配置EnableSwagger: false。對于靜態(tài)文件wwwroot目錄我們在Nginx配置中已經(jīng)做了優(yōu)化由Nginx直接處理比經(jīng)過.NET管道更快。5.2 配置日志和監(jiān)控默認(rèn)的.NET日志會輸出到控制臺被systemd捕獲。為了更好的日志管理可以配置更結(jié)構(gòu)化的日志比如輸出到文件或集成Serilog等庫。一個簡單的方法是修改appsettings.Production.json配置文件日志{ Logging: { LogLevel: { Default: Information, Microsoft.AspNetCore: Warning, Microsoft.EntityFrameworkCore: Warning }, File: { Path: /var/log/myapi/app.log, FileSizeLimitBytes: 10485760, // 10MB RetainedFileCountLimit: 5 } } }同時確保運行服務(wù)的用戶apiuser對日志目錄有寫入權(quán)限sudo mkdir -p /var/log/myapi sudo chown -R apiuser:apiuser /var/log/myapi5.3 處理API錯誤和超時從熱搜詞里看到一些典型的API錯誤比如api error: 400 type must be in [enabled, disabled, auto]這通常是客戶端請求參數(shù)不符合服務(wù)器端驗證規(guī)則。部署后你需要確保輸入驗證在ASP.NET Core中使用[Required]、[Range]、[RegularExpression]等數(shù)據(jù)注解或FluentValidation庫確保傳入?yún)?shù)合法并返回清晰的錯誤信息。全局異常處理使用中間件捕獲未處理的異常返回統(tǒng)一的錯誤格式而不是暴露堆棧信息。超時設(shè)置如果API處理耗時較長如文件上傳、復(fù)雜計算需要調(diào)整Kestrel服務(wù)器、Nginx和客戶端的超時設(shè)置。Kestrel在appsettings.json中配置Kestrel: { Limits: { KeepAliveTimeout: 120, RequestHeadersTimeout: 120 } }。Nginx前面配置中已經(jīng)設(shè)置了proxy_read_timeout 300s;。客戶端根據(jù)調(diào)用方調(diào)整。5.4 更新和回滾流程服務(wù)上線后總需要更新。一個基本的手動更新流程是在本地或CI環(huán)境構(gòu)建新的發(fā)布包。上傳到服務(wù)器的一個臨時目錄例如/var/www/myapi_new。停止當(dāng)前服務(wù)sudo systemctl stop myapi.service。備份當(dāng)前運行目錄sudo mv /var/www/myapi /var/www/myapi_backup_$(date %Y%m%d%H%M%S)。移動新版本到運行目錄sudo mv /var/www/myapi_new /var/www/myapi。確保權(quán)限sudo chown -R apiuser:apiuser /var/www/myapi。啟動服務(wù)sudo systemctl start myapi.service。驗證服務(wù)是否正常通過健康檢查端點或關(guān)鍵API。如果失敗快速回滾停止服務(wù)把備份目錄移回來再啟動。對于更嚴(yán)肅的生產(chǎn)環(huán)境應(yīng)該考慮使用Docker容器化部署或者配置完整的CI/CD流水線例如使用GitHub Actions Docker 服務(wù)器上的watchtower或自己寫的更新腳本。5.5 資源監(jiān)控和告警服務(wù)跑起來后需要關(guān)注資源使用情況。進程狀態(tài)sudo systemctl status myapi.service看是否活躍。資源占用top或htop看CPU和內(nèi)存。.NET應(yīng)用剛啟動時內(nèi)存可能較高JIT編譯運行一段時間后會穩(wěn)定。日志監(jiān)控使用journalctl -u myapi.service -f實時跟蹤或者用logwatch、ELK等工具集中管理。端口監(jiān)聽sudo netstat -tlnp | grep :5000確認(rèn)你的應(yīng)用在監(jiān)聽端口。磁盤空間df -h確保日志或上傳文件不會寫滿磁盤。可以設(shè)置簡單的監(jiān)控腳本定期檢查服務(wù)狀態(tài)失敗時發(fā)送告警郵件、釘釘、企業(yè)微信等。6. 從單機部署到更高可用性考慮以上流程足以讓一個API網(wǎng)站在單臺Ubuntu服務(wù)器上跑起來。但如果流量增大或者對可用性要求更高就需要考慮更多。6.1 使用Docker容器化部署容器化能更好地解決環(huán)境一致性問題。編寫DockerfileFROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base WORKDIR /app EXPOSE 80 EXPOSE 443 FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build WORKDIR /src COPY [MyApi/MyApi.csproj, MyApi/] RUN dotnet restore MyApi/MyApi.csproj COPY . . WORKDIR /src/MyApi RUN dotnet build MyApi.csproj -c Release -o /app/build FROM build AS publish RUN dotnet publish MyApi.csproj -c Release -o /app/publish FROM base AS final WORKDIR /app COPY --frompublish /app/publish . ENTRYPOINT [dotnet, MyApi.dll]然后在服務(wù)器上安裝Docker構(gòu)建鏡像并運行。結(jié)合Docker Compose可以更方便地管理服務(wù)依賴如數(shù)據(jù)庫。6.2 配置負(fù)載均衡和多實例如果單實例性能不足可以在多臺服務(wù)器上部署相同應(yīng)用前面用Nginx或云負(fù)載均衡器做流量分發(fā)。此時需要注意會話狀態(tài) (Session)如果用了內(nèi)存Session需要轉(zhuǎn)移到分布式緩存如Redis。文件上傳上傳的文件需要存儲到共享位置如NFS、云存儲OSS。數(shù)據(jù)庫連接確保數(shù)據(jù)庫連接池配置合理能應(yīng)對多實例連接。6.3 集成到CI/CD流水線手動上傳和更新效率低且易出錯。可以集成GitHub Actions、GitLab CI等工具實現(xiàn)代碼推送后自動構(gòu)建、測試、部署。 一個簡單的GitHub Actions工作流示例.github/workflows/deploy.ymlname: Deploy to Ubuntu Server on: push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup .NET uses: actions/setup-dotnetv4 with: dotnet-version: 8.0.x - name: Publish run: dotnet publish -c Release -o ./publish - name: Deploy to Server uses: appleboy/scp-actionv0.1.4 with: host: ${{ secrets.SERVER_HOST }} username: ${{ secrets.SERVER_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} source: ./publish/* target: /var/www/myapi_new - name: Restart Service on Server uses: appleboy/ssh-actionv1.0.0 with: host: ${{ secrets.SERVER_HOST }} username: ${{ secrets.SERVER_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} script: | sudo systemctl stop myapi.service sudo rm -rf /var/www/myapi_backup sudo mv /var/www/myapi /var/www/myapi_backup sudo mv /var/www/myapi_new /var/www/myapi sudo chown -R apiuser:apiuser /var/www/myapi sudo systemctl start myapi.service這只是一個基礎(chǔ)示例真實場景需要更完善的錯誤處理和回滾機制。部署本身不是一次性的任務(wù)而是一個需要持續(xù)維護和優(yōu)化的過程。從最簡單的單機systemd服務(wù)到容器化、編排、自動化部署每一步都是為了更高的可靠性、可維護性和開發(fā)效率。對于大部分中小型API項目按照本文的systemd Nginx方案已經(jīng)能搭建一個非常穩(wěn)固的生產(chǎn)環(huán)境。關(guān)鍵是把環(huán)境、權(quán)限、進程管理和日志這幾個基礎(chǔ)環(huán)節(jié)做扎實后續(xù)的擴展才會更順利。