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