戰(zhàn)：Python異步ASGI服務(wù)器的核心原理與部署優(yōu)化)
我以前剛接觸Python異步Web開(kāi)發(fā)的時(shí)候最頭疼的一件事就是代碼寫好了卻不知道該拿什么去跑它。Flask時(shí)代有Werkzeug自帶的開(kāi)發(fā)服務(wù)器Django有runserver可一旦切到FastAPI、Starlette這類異步框架很多人第一反應(yīng)還是用Flask那套思維去找內(nèi)置服務(wù)器結(jié)果跑起來(lái)各種別扭性能也上不去。直到我用上Uvicorn才發(fā)現(xiàn)之前缺的不是框架而是一個(gè)真正理解異步的ASGI服務(wù)器。這個(gè)項(xiàng)目標(biāo)題雖然寫的是“入門教程”但我打算直接把它當(dāng)做一個(gè)完整的上手指南來(lái)寫從為什么需要它、它是怎么工作的到實(shí)際怎么跑、怎么調(diào)優(yōu)、怎么避坑一次說(shuō)清楚。適合剛開(kāi)始接觸FastAPI或任何ASGI框架的開(kāi)發(fā)者也適合那些已經(jīng)在用但只停留在uvicorn main:app --reload這一條命令、想深入了解參數(shù)和部署細(xì)節(jié)的人。1. Uvicorn到底是什么從WSGI到ASGI的關(guān)鍵一躍1.1 同步時(shí)代的老大哥WSGI為什么在異步時(shí)代不夠用很多人知道WSGI這個(gè)詞但未必真的理解它和Uvicorn之間的關(guān)系。簡(jiǎn)單說(shuō)WSGI是Python Web應(yīng)用和服務(wù)器之間的一個(gè)標(biāo)準(zhǔn)接口定義了服務(wù)器怎么把請(qǐng)求交給應(yīng)用、應(yīng)用怎么把響應(yīng)還給服務(wù)器。Flask、Django這些傳統(tǒng)框架都是基于WSGI構(gòu)建的對(duì)應(yīng)的服務(wù)器有Gunicorn、uWSGI等等。這套體系在同步請(qǐng)求的場(chǎng)景下非常成熟穩(wěn)定但它有一個(gè)致命短板它是一個(gè)同步的調(diào)用模型。一個(gè)請(qǐng)求進(jìn)來(lái)服務(wù)器調(diào)用一次應(yīng)用的可調(diào)用對(duì)象應(yīng)用執(zhí)行完再返回結(jié)果整個(gè)過(guò)程是一錘子買賣。這個(gè)模型在請(qǐng)求量小、每個(gè)請(qǐng)求處理時(shí)間短的場(chǎng)景下沒(méi)什么問(wèn)題但一旦遇到長(zhǎng)連接、WebSocket、流式響應(yīng)這類需求就非常別扭。更關(guān)鍵的是它限制了一個(gè)進(jìn)程里同時(shí)處理并發(fā)請(qǐng)求的能力。雖然可以通過(guò)多進(jìn)程、多線程來(lái)堆并發(fā)但線程切換開(kāi)銷大而且Python的GIL會(huì)讓多線程在CPU密集任務(wù)上吃大虧。1.2 ASGI帶來(lái)的異步接口革命ASGI的全稱是Asynchronous Server Gateway Interface可以理解成WSGI的異步升級(jí)版。它在設(shè)計(jì)上引入了ASGI Scope的概念把HTTP請(qǐng)求、WebSocket連接、生命周期事件等統(tǒng)統(tǒng)統(tǒng)一成一種作用域scope然后通過(guò)異步調(diào)用方式處理。這意味著服務(wù)器可以在等待I/O的時(shí)候去干別的事情而不是干等著。換句話說(shuō)ASGI讓Python Web應(yīng)用真正具備了原生異步并發(fā)的能力你可以在一個(gè)進(jìn)程里同時(shí)處理成千上萬(wàn)個(gè)慢請(qǐng)求、長(zhǎng)連接、WebSocket消息。Uvicorn就是ASGI協(xié)議的一個(gè)具體實(shí)現(xiàn)。除了它市面上還有Hypercorn、Daphne等ASGI服務(wù)器但Uvicorn是目前最主流的很大程度上是因?yàn)樗讓佑昧藆vloop和httptools這兩個(gè)高性能組件速度非?？臁６褾astAPI官方推薦搭配Uvicorn所以它的生態(tài)和文檔也最完善。1.3 Uvicorn在技術(shù)棧中的定位Uvicorn本身不負(fù)責(zé)業(yè)務(wù)邏輯它只是一個(gè)服務(wù)器進(jìn)程負(fù)責(zé)接收網(wǎng)絡(luò)請(qǐng)求、解析HTTP協(xié)議、把請(qǐng)求轉(zhuǎn)給ASGI應(yīng)用然后把應(yīng)用返回的內(nèi)容再發(fā)回客戶端。它的定位有點(diǎn)像交通樞紐外面來(lái)的車HTTP請(qǐng)求先到這里它再調(diào)度給里面的人應(yīng)用處理處理完再原路送回。你完全可以在不寫任何應(yīng)用代碼的情況下單獨(dú)啟動(dòng)Uvicorn它只是等待請(qǐng)求返回404之類的默認(rèn)響應(yīng)但因?yàn)槿鄙賹?shí)際的應(yīng)用對(duì)象它不會(huì)給你任何業(yè)務(wù)功能。在實(shí)際項(xiàng)目中通常的做法是FastAPI或Starlette寫業(yè)務(wù)邏輯Uvicorn作為服務(wù)器跑起來(lái)兩者通過(guò)ASGI協(xié)議對(duì)接。如果還想上更高并發(fā)往往會(huì)在Uvicorn前面再放一個(gè)Nginx做反向代理、負(fù)載均衡甚至在Uvicorn前面掛一個(gè)類似Gunicorn的工具來(lái)管理進(jìn)程。這個(gè)分層關(guān)系理清楚之后你排查問(wèn)題的時(shí)候思路就會(huì)清晰很多出錯(cuò)了到底是框架的問(wèn)題、代碼的問(wèn)題還是服務(wù)器配置的問(wèn)題。2. 核心設(shè)計(jì)拆解Uvicorn的性能到底從哪里來(lái)2.1 uvloop比默認(rèn)事件循環(huán)更快的秘密Python的asyncio自帶一個(gè)事件循環(huán)在大多數(shù)情況下已經(jīng)夠用了但Uvicorn默認(rèn)會(huì)優(yōu)先使用uvloop來(lái)替換它。uvloop是一個(gè)基于libuv的Cython實(shí)現(xiàn)libuv是Node.js底層的異步I/O庫(kù)經(jīng)過(guò)大量真實(shí)場(chǎng)景的考驗(yàn)性能和穩(wěn)定性都很出色。uvloop把很多核心事件循環(huán)的操作從Python層面下沉到了C層面減少了Python解釋器的開(kāi)銷所以在處理大量并發(fā)連接時(shí)它的優(yōu)勢(shì)非常明顯。你以為這只是微小的速度差異實(shí)際上在高并發(fā)場(chǎng)景下uvloop能讓每個(gè)連接的處理開(kāi)銷降低不少。雖然具體數(shù)字取決于機(jī)器和場(chǎng)景但很多性能測(cè)試?yán)颱vicorn的吞吐量都明顯高于使用默認(rèn)事件循環(huán)的服務(wù)器。這也是為什么很多性能評(píng)測(cè)里Uvicorn能跑出漂亮數(shù)據(jù)的原因之一。2.2 httptools更快的HTTP解析器除了事件循環(huán)Uvicorn還用了httptools這個(gè)庫(kù)來(lái)做HTTP協(xié)議的解析。HTTP報(bào)文解析是服務(wù)器最基礎(chǔ)也最高頻的操作如果解析器效率低整個(gè)服務(wù)的響應(yīng)速度都會(huì)被拖累。httptools是從Node.js里的http-parser移植過(guò)來(lái)的C庫(kù)專門針對(duì)HTTP請(qǐng)求的頭部、方法、URL、狀態(tài)碼等做了高度優(yōu)化。這意味著什么舉個(gè)生活化的例子默認(rèn)解析器相當(dāng)于用自己把快遞一件件打開(kāi)、分類、登記httptools則像一條流水線每個(gè)包裹一上來(lái)就能快速拆解分揀。雖然你肉眼感覺(jué)不到單個(gè)請(qǐng)求的差異但在大量請(qǐng)求并發(fā)涌入時(shí)解析速度快就代表了更短的響應(yīng)延遲和更高的吞吐量。Uvicorn還支持HTTP/1.1和WebSocket這部分解析也都是走h(yuǎn)ttptools的效率很高。2.3 單進(jìn)程、多進(jìn)程與事件循環(huán)的配合Uvicorn有三種啟動(dòng)模式單進(jìn)程、多進(jìn)程、以及基于--workers的多worker模式。默認(rèn)情況下Uvicorn只啟動(dòng)一個(gè)進(jìn)程內(nèi)部跑一個(gè)事件循環(huán)。這個(gè)模式下所有的并發(fā)都靠異步事件循環(huán)支撐適合開(kāi)發(fā)調(diào)試和請(qǐng)求量不大的服務(wù)。生產(chǎn)環(huán)境想提升并發(fā)能力可以增加worker數(shù)量也就是多個(gè)獨(dú)立進(jìn)程每個(gè)進(jìn)程有自己獨(dú)立的事件循環(huán)對(duì)應(yīng)不同的CPU核心。這里有個(gè)重要的點(diǎn)Uvicorn的多worker模式并不是自己維護(hù)進(jìn)程池的復(fù)雜系統(tǒng)它底層其實(shí)是繼承了multiprocessing的能力每個(gè)worker都是一個(gè)獨(dú)立的Python進(jìn)程之間不共享內(nèi)存。這也意味著如果你用了一個(gè)全局變量或者進(jìn)程內(nèi)緩存不同worker之間的數(shù)據(jù)是不互通的這個(gè)后面我再詳細(xì)講坑。注意在Docker容器里如果設(shè)置了--workers一定要保證容器有足夠的CPU資源不然多個(gè)worker會(huì)爭(zhēng)搶CPU性能反而下降。有些環(huán)境里還需要關(guān)心文件描述符限制連接數(shù)很大的話默認(rèn)1024可能不夠。3. 安裝與基礎(chǔ)啟動(dòng)從零把服務(wù)跑起來(lái)3.1 安裝Uvicorn標(biāo)準(zhǔn)版還是全功能版安裝Uvicorn非常簡(jiǎn)單pip直接裝就行。但這里有個(gè)小細(xì)節(jié)很多人沒(méi)注意Uvicorn有兩個(gè)安裝模式標(biāo)準(zhǔn)安裝和全功能安裝。標(biāo)準(zhǔn)安裝就是直接pip install uvicorn它會(huì)帶一些核心依賴、簡(jiǎn)單實(shí)用的功能。全功能安裝則是pip install uvicorn[standard]這個(gè)會(huì)額外裝上uvloop、httptools、websockets、watchfiles等一堆東西。其中websockets是用來(lái)支持WebSocket功能的watchfiles是給--reload熱加載用的。簡(jiǎn)單說(shuō)標(biāo)準(zhǔn)版能用但用的是Python默認(rèn)事件循環(huán)且不支持WebSocket全功能版才真正發(fā)揮Uvicorn的性能優(yōu)勢(shì)。我不建議省這一步。直接在項(xiàng)目初始化的時(shí)候用pip install uvicorn[standard]這并不復(fù)雜但能省掉后面很多“為什么我的Uvicorn不支持WebSocket”“為什么性能評(píng)測(cè)數(shù)據(jù)差那么多”之類的問(wèn)題。3.2 第一個(gè)命令localhost:8000跑起來(lái)裝好之后最簡(jiǎn)單的驗(yàn)證方式是在終端里敲uvicorn --version看到版本號(hào)就說(shuō)明安裝沒(méi)問(wèn)題。接著你需要有一個(gè)ASGI應(yīng)用。這里先給一個(gè)最小的Starlette或FastAPI示例# app.py from fastapi import FastAPI app FastAPI() app.get(/) async def read_root(): return {message: hello uvicorn}然后運(yùn)行uvicorn app:app --host 0.0.0.0 --port 8000看到INFO: Uvicorn running on http://0.0.0.0:8000就說(shuō)明啟動(dòng)成功了。這里面app:app的含義是文件app.py里的變量名app。如果你文件叫main.py應(yīng)用對(duì)象叫application那就是main:application。這個(gè)格式很多人第一次會(huì)搞混記住了其實(shí)很簡(jiǎn)單。3.3 --reload熱加載與開(kāi)發(fā)模式的關(guān)鍵參數(shù)開(kāi)發(fā)階段用得最多的就是--reload它可以監(jiān)聽(tīng)代碼文件變化一有改動(dòng)就自動(dòng)重啟服務(wù)。這個(gè)功能在調(diào)試時(shí)候特別方便不用手動(dòng)按CtrlC再啟動(dòng)。實(shí)現(xiàn)原理就是watchfiles庫(kù)監(jiān)控文件系統(tǒng)的變化事件檢測(cè)到變化后重啟整個(gè)worker進(jìn)程。不過(guò)要注意--reload本身是有代價(jià)的它需要額外啟動(dòng)一個(gè)監(jiān)控進(jìn)程來(lái)觀察文件變化這個(gè)進(jìn)程不參與請(qǐng)求處理。所以生產(chǎn)環(huán)境絕對(duì)不要加--reload因?yàn)橐坏┪募腥魏巫兓热缛罩緦懭?、臨時(shí)文件寫入都可能觸發(fā)重啟造成服務(wù)閃斷。我見(jiàn)過(guò)有人上線的時(shí)候忘了去掉這個(gè)參數(shù)導(dǎo)致服務(wù)每隔幾分鐘就重啟一次所有在線用戶全部掉線血淚教訓(xùn)。常用開(kāi)發(fā)命令uvicorn app:app --reload --host 127.0.0.1 --port 8000這里--host 127.0.0.1表示只允許本機(jī)訪問(wèn)安全性更高如果你需要局域網(wǎng)內(nèi)其他設(shè)備調(diào)試才用--host 0.0.0.0。另外還有一個(gè)--port參數(shù)指定端口默認(rèn)就是8000所以不寫也可以。4. 實(shí)操用Uvicorn把FastAPI服務(wù)真正跑起來(lái)4.1 寫一個(gè)帶異步邏輯的示例服務(wù)光跑通還不夠我們要實(shí)際體會(huì)一下Uvicorn對(duì)異步IO的處理方式。先寫一個(gè)稍微豐富點(diǎn)的示例包含異步接口和耗時(shí)操作# app.py import asyncio from fastapi import FastAPI app FastAPI() app.get(/hello) async def hello(): await asyncio.sleep(0.1) return {msg: hello} app.get(/io-bound) async def io_bound_sim(): # 模擬IO密集型操作比如訪問(wèn)數(shù)據(jù)庫(kù)、調(diào)用第三方API await asyncio.sleep(2) return {msg: done after 2s}兩個(gè)接口都用了異步方式尤其IO密集型的接口在異步事件循環(huán)下同一個(gè)進(jìn)程可以同時(shí)處理很多個(gè)這樣的請(qǐng)求而不會(huì)互相阻塞。這就是Uvicorn的核心價(jià)值。4.2 開(kāi)發(fā)模式下觀察熱加載行為在真實(shí)項(xiàng)目中你會(huì)頻繁修改代碼。開(kāi)著--reload啟動(dòng)之后每當(dāng)你保存文件終端上會(huì)輸出類似INFO: Started reloader process [xxxxx]和INFO: Started server process [xxxxx]的信息。這說(shuō)明reloader檢測(cè)到了文件變化正在重啟worker。這里有個(gè)實(shí)用技巧如果你改了代碼但reload沒(méi)反應(yīng)不要急著重裝先確認(rèn)你修改的文件是否在監(jiān)控范圍內(nèi)。Uvicorn默認(rèn)監(jiān)聽(tīng)當(dāng)前工作目錄如果你的代碼文件放在別的目錄或者用包管理工具安裝了項(xiàng)目但是路徑不對(duì)它可能監(jiān)聽(tīng)不到。另外要看你的文件是不是被某些編輯器以臨時(shí)文件的方式保存比如Vim的swap文件如果觸發(fā)了替換邏輯導(dǎo)致reload反而重啟失敗這種情況偶爾也有。4.3 生產(chǎn)模式啟動(dòng)多進(jìn)程與日志關(guān)閉生產(chǎn)環(huán)境不追求熱加載追求穩(wěn)定性、并發(fā)和運(yùn)維友好。一個(gè)比較典型的啟動(dòng)命令是uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4這會(huì)啟動(dòng)4個(gè)worker進(jìn)程每個(gè)都給到一部分并發(fā)能力。這里有個(gè)矛盾點(diǎn)需要解釋Uvicorn在--workers大于1的時(shí)候reloader和workers是不兼容的所以兩個(gè)參數(shù)不能同時(shí)用。如果你既想多進(jìn)程又想熱加載那只能在開(kāi)發(fā)環(huán)境用單worker的reload模式生產(chǎn)環(huán)境用多worker。還有一個(gè)常見(jiàn)選擇日志。Uvicorn啟動(dòng)后會(huì)輸出訪問(wèn)日志、錯(cuò)誤日志等。在后臺(tái)守護(hù)進(jìn)程或者容器環(huán)境里你可能不想讓它輸出到終端過(guò)多可以用--log-level warning降低輸出級(jí)別。生產(chǎn)環(huán)境想記錄訪問(wèn)日志通常建議通過(guò)Nginx來(lái)記錄應(yīng)用層只保留錯(cuò)誤級(jí)別的日志避免重復(fù)記錄造成日志膨脹。5. 進(jìn)階Uvicorn在生產(chǎn)環(huán)境部署中的關(guān)鍵配置5.1 worker數(shù)量怎么選別盲目跟風(fēng)很多教程會(huì)說(shuō)worker數(shù)等于CPU核心數(shù)或2倍核心數(shù)。這個(gè)說(shuō)法太粗糙了實(shí)際要分場(chǎng)景。如果你的服務(wù)是IO密集型在那等數(shù)據(jù)庫(kù)返回、調(diào)外部APIworker數(shù)可以高于CPU核心數(shù)因?yàn)榇蟛糠謺r(shí)間都阻塞在IO上CPU并不是瓶頸。如果是CPU密集型圖像處理、復(fù)雜計(jì)算worker數(shù)一般等于或小于核心數(shù)否則多個(gè)worker互相搶CPU反而降低整體效率。我自己的經(jīng)驗(yàn)是先在測(cè)試環(huán)境壓測(cè)從單worker起步逐步加worker觀察QPS和響應(yīng)延遲的變化。當(dāng)加worker之后QPS沒(méi)有明顯提升說(shuō)明CPU已經(jīng)飽和或者瓶頸在別處比如數(shù)據(jù)庫(kù)連接池、帶寬這時(shí)候繼續(xù)加worker只是浪費(fèi)內(nèi)存。還有一點(diǎn)每個(gè)worker都會(huì)復(fù)制一份應(yīng)用對(duì)象所以如果你啟動(dòng)時(shí)加載了很大的模型或者緩存內(nèi)存開(kāi)銷會(huì)線性增長(zhǎng)控制好worker數(shù)量非常重要。5.2 生命周期管理優(yōu)雅關(guān)閉與慢請(qǐng)求處理Uvicorn支持優(yōu)雅關(guān)閉你發(fā)一個(gè)SIGINTCtrlC或SIGTERM信號(hào)時(shí)它會(huì)停止接收新連接并等待當(dāng)前正在處理中的請(qǐng)求完成后再退出。這個(gè)機(jī)制對(duì)線上服務(wù)非常重要防止你在發(fā)版的時(shí)候把正在跑了一半的請(qǐng)求直接掐斷。默認(rèn)情況下Uvicorn等待的時(shí)間并不是無(wú)限長(zhǎng)它有一個(gè)超時(shí)機(jī)制。比如某些請(qǐng)求特別慢幾十秒甚至幾分鐘如果你想在關(guān)閉時(shí)給它更長(zhǎng)的時(shí)間可以通過(guò)--timeout-graceful-shutdown參數(shù)來(lái)設(shè)置單位是秒。這個(gè)參數(shù)有些Uvicorn版本才支持用之前建議先確認(rèn)版本。另外推薦在部署腳本里先發(fā)SIGTERM信號(hào)然后等待一段時(shí)間再確認(rèn)進(jìn)程是否退出如果超時(shí)再?gòu)?qiáng)殺。比如在systemd服務(wù)里配置TimeoutStopSec30給足優(yōu)雅關(guān)閉的時(shí)間。5.3 與反向代理配合Nginx和Uvicorn的分工生產(chǎn)環(huán)境很少讓Uvicorn直接面對(duì)公網(wǎng)。常規(guī)做法是前面掛NginxUvicorn監(jiān)聽(tīng)一個(gè)本機(jī)端口比如8001Nginx監(jiān)聽(tīng)80/443對(duì)外提供服務(wù)。這樣做的原因有三個(gè)一是Nginx處理靜態(tài)文件、請(qǐng)求頭、Gzip壓縮等能力更強(qiáng)二是Nginx可以做負(fù)載均衡把請(qǐng)求分發(fā)到多個(gè)Uvicorn實(shí)例或多臺(tái)服務(wù)器三是安全上多一層保護(hù)隱藏后端端口。Nginx里一個(gè)簡(jiǎn)易的配置大概是server { listen 80; location / { proxy_pass http://127.0.0.1:8001; 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; } }要注意的是一旦加上反向代理Uvicorn的訪問(wèn)日志里記錄的IP基本都是127.0.0.1因?yàn)槟憧吹降氖荖ginx轉(zhuǎn)發(fā)過(guò)來(lái)的請(qǐng)求這就是為什么我們要設(shè)置X-Forwarded-For頭。FastAPI里可以通過(guò)request.client.host拿到真實(shí)IP前提是中間代理配置正確。如果沒(méi)有正確透?jìng)魉杏脩鬒P會(huì)被當(dāng)成一個(gè)IP這在做限流或用戶分析時(shí)會(huì)有大問(wèn)題。另外HTTP長(zhǎng)連接和WebSocket在Nginx后面也要特殊配置proxy_http_version 1.1、Upgrade和Connection頭否則WebSocket連接會(huì)經(jīng)常斷開(kāi)。6. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄6.1 端口占用導(dǎo)致無(wú)法啟動(dòng)啟動(dòng)Uvicorn時(shí)報(bào)[Errno 98] Address already in use這是最典型的問(wèn)題。通常是你上一次的服務(wù)沒(méi)關(guān)掉或者端口被其他進(jìn)程占用了。解決方式分幾步先確認(rèn)是誰(shuí)占用了端口Linux下用lsof -i :8000 # 或 netstat -tlnp | grep 8000找到PID之后確認(rèn)這是不是你要?dú)⒌舻倪M(jìn)程再kill -9 PID。不要一看到端口占用就殺進(jìn)程先確認(rèn)一下免得誤殺別的服務(wù)。還有一種情況是你自己剛才啟動(dòng)的reload模式服務(wù)因?yàn)榻K端窗口沒(méi)關(guān)進(jìn)程還在后臺(tái)。如果你用的是或者nohup方式啟動(dòng)記得用ps aux | grep uvicorn看一下殘留進(jìn)程。6.2 --reload不生效或頻繁重啟熱加載失效是比較頭疼的問(wèn)題。先確認(rèn)安裝的是不是標(biāo)準(zhǔn)安裝因?yàn)閞eload依賴watchfiles標(biāo)準(zhǔn)安裝已經(jīng)包含了。如果還是不行檢查以下幾點(diǎn)你修改的代碼文件是否在啟動(dòng)目錄下。啟動(dòng)命令里是否用了--reload-dir指定錯(cuò)誤目錄。編輯器保存時(shí)是否生成了臨時(shí)文件導(dǎo)致監(jiān)控混亂。如果遇到頻繁重啟多半是監(jiān)控目錄里某些文件反復(fù)變化比如日志文件、緩存文件。解決辦法是把這些目錄排除掉uvicorn app:app --reload --reload-exclude logs/* --reload-exclude *.pyc這樣能保證只有真正改代碼的時(shí)候才重啟那些臨時(shí)文件不會(huì)干擾監(jiān)控。6.3 多worker模式下全局狀態(tài)不同步這個(gè)問(wèn)題很多人踩過(guò)坑。在單進(jìn)程模式里你可能習(xí)慣用一個(gè)全局字典做緩存或者用一個(gè)全局變量存儲(chǔ)用戶在線狀態(tài)。一旦切到--workers 4每個(gè)worker進(jìn)程都是獨(dú)立解釋器全局變量互不相通。這就導(dǎo)致A worker寫入的緩存B worker讀不到表現(xiàn)就是“明明更新了數(shù)據(jù)但請(qǐng)求有時(shí)候拿到舊的”。解決方案一般有三條路本地緩存不用全局變量改用Redis之類的分布式存儲(chǔ)只做只讀性質(zhì)的全局配置不依賴寫入或者干脆用單worker同步模式但如果并發(fā)要求高單worker又不夠。我個(gè)人建議如果你的服務(wù)以后一定要擴(kuò)展并發(fā)從一開(kāi)始就不要設(shè)計(jì)進(jìn)程內(nèi)可變?nèi)譅顟B(tài)養(yǎng)成用外部存儲(chǔ)的習(xí)慣后面會(huì)少很多麻煩。6.4 慢請(qǐng)求導(dǎo)致事件循環(huán)阻塞Uvicorn是異步的但如果你的業(yè)務(wù)代碼里有同步阻塞的操作比如用requests.get()做同步HTTP調(diào)用、CPU密集的循環(huán)、大量數(shù)據(jù)庫(kù)同步查詢這些操作都會(huì)阻塞事件循環(huán)導(dǎo)致整個(gè)進(jìn)程卡住其他請(qǐng)求全部排隊(duì)等待。注意這個(gè)坑極其隱蔽單個(gè)請(qǐng)求慢一點(diǎn)可能不明顯但一旦并發(fā)上來(lái)一個(gè)阻塞操作就能讓整個(gè)服務(wù)雪崩。解決方式有兩種模式一是把阻塞操作改成異步操作比如用httpx.AsyncClient替代requests用異步數(shù)據(jù)庫(kù)驅(qū)動(dòng)二是如果實(shí)在無(wú)法異步化用run_in_executor把它丟到線程池里執(zhí)行。FastAPI里同步路徑操作會(huì)自動(dòng)跑在線程池所以在FastAPI中寫好同步接口其實(shí)問(wèn)題不大但在純Starlette或自定義ASGI應(yīng)用里你就要自己注意了。6.5 大并發(fā)下的文件描述符受限當(dāng)你把連接數(shù)調(diào)到很高時(shí)可能會(huì)遇到Too many open files錯(cuò)誤。這是Linux文件描述符上限導(dǎo)致的。臨時(shí)提高當(dāng)前shell的限制ulimit -n 65535但這個(gè)是臨時(shí)的重啟失效。要永久修改需要改/etc/security/limits.conf給對(duì)應(yīng)的用戶加上nofile限制。這個(gè)細(xì)節(jié)在運(yùn)維同學(xué)那里是基本功但開(kāi)發(fā)者自己在服務(wù)器上跑Uvicorn時(shí)很容易忽略。如果想徹底點(diǎn)Uvicorn還支持通過(guò)--backlog控制內(nèi)核中等待接受的連接隊(duì)列長(zhǎng)度一般默認(rèn)是2048高并發(fā)場(chǎng)景建議調(diào)高。這里有個(gè)前提你的Linux內(nèi)核參數(shù)net.core.somaxconn也得跟著調(diào)高否則Uvicorn設(shè)置的值超過(guò)內(nèi)核上限會(huì)被截?cái)唷?. 基于個(gè)人經(jīng)驗(yàn)的一個(gè)小總結(jié)用了Uvicorn這么久我自己最大的體會(huì)是它確實(shí)把Python服務(wù)端的性能上限抬高了一個(gè)臺(tái)階但前提是你真的理解了什么場(chǎng)景下它才能發(fā)揮優(yōu)勢(shì)。就拿FastAPI來(lái)說(shuō)框架層面給你封裝好了很多異步優(yōu)化但你寫代碼時(shí)用了一個(gè)同步requests性能一樣拉胯。工具永遠(yuǎn)只是能力的一半另一半在你的代碼習(xí)慣里。最后分享一個(gè)小技巧調(diào)試Uvicorn底層行為的時(shí)候可以用--log-level debug啟動(dòng)能看到請(qǐng)求的完整生命周期日志包括請(qǐng)求進(jìn)來(lái)、事件循環(huán)處理、響應(yīng)返回的每個(gè)環(huán)節(jié)。這個(gè)模式下信息量非常大新手容易被淹沒(méi)但排查疑難問(wèn)題的時(shí)候真的管用。比如你懷疑某個(gè)請(qǐng)求超時(shí)debug日志會(huì)告訴你時(shí)間花在了哪一步。還有一個(gè)比--reload更直接的調(diào)試方法在代碼里加if __name__ __main__:的入口然后直接用uvicorn.run來(lái)啟動(dòng)應(yīng)用這樣所有參數(shù)都可以寫進(jìn)代碼里版本管理和團(tuán)隊(duì)協(xié)作都方便。尤其是項(xiàng)目配置多的時(shí)候命令行參數(shù)記不全不如直接固化到代碼里誰(shuí)拿到這個(gè)項(xiàng)目都能一鍵跑起來(lái)。希望這篇教程能幫你少走一些彎路把Uvicorn真正用順手。 Uvicorn入門到實(shí)戰(zhàn)：Python異步ASGI服務(wù)器的核心原理與部署優(yōu)化
我以前剛接觸Python異步Web開(kāi)發(fā)的時(shí)候最頭疼的一件事就是代碼寫好了卻不知道該拿什么去跑它。Flask時(shí)代有Werkzeug自帶的開(kāi)發(fā)服務(wù)器Django有runserver可一旦切到FastAPI、Starlette這類異步框架很多人第一反應(yīng)還是用Flask那套思維去找內(nèi)置服務(wù)器結(jié)果跑起來(lái)各種別扭性能也上不去。直到我用上Uvicorn才發(fā)現(xiàn)之前缺的不是框架而是一個(gè)真正理解異步的ASGI服務(wù)器。這個(gè)項(xiàng)目標(biāo)題雖然寫的是“入門教程”但我打算直接把它當(dāng)做一個(gè)完整的上手指南來(lái)寫從為什么需要它、它是怎么工作的到實(shí)際怎么跑、怎么調(diào)優(yōu)、怎么避坑一次說(shuō)清楚。適合剛開(kāi)始接觸FastAPI或任何ASGI框架的開(kāi)發(fā)者也適合那些已經(jīng)在用但只停留在uvicorn main:app --reload這一條命令、想深入了解參數(shù)和部署細(xì)節(jié)的人。1. Uvicorn到底是什么從WSGI到ASGI的關(guān)鍵一躍1.1 同步時(shí)代的老大哥WSGI為什么在異步時(shí)代不夠用很多人知道WSGI這個(gè)詞但未必真的理解它和Uvicorn之間的關(guān)系。簡(jiǎn)單說(shuō)WSGI是Python Web應(yīng)用和服務(wù)器之間的一個(gè)標(biāo)準(zhǔn)接口定義了服務(wù)器怎么把請(qǐng)求交給應(yīng)用、應(yīng)用怎么把響應(yīng)還給服務(wù)器。Flask、Django這些傳統(tǒng)框架都是基于WSGI構(gòu)建的對(duì)應(yīng)的服務(wù)器有Gunicorn、uWSGI等等。這套體系在同步請(qǐng)求的場(chǎng)景下非常成熟穩(wěn)定但它有一個(gè)致命短板它是一個(gè)同步的調(diào)用模型。一個(gè)請(qǐng)求進(jìn)來(lái)服務(wù)器調(diào)用一次應(yīng)用的可調(diào)用對(duì)象應(yīng)用執(zhí)行完再返回結(jié)果整個(gè)過(guò)程是一錘子買賣。這個(gè)模型在請(qǐng)求量小、每個(gè)請(qǐng)求處理時(shí)間短的場(chǎng)景下沒(méi)什么問(wèn)題但一旦遇到長(zhǎng)連接、WebSocket、流式響應(yīng)這類需求就非常別扭。更關(guān)鍵的是它限制了一個(gè)進(jìn)程里同時(shí)處理并發(fā)請(qǐng)求的能力。雖然可以通過(guò)多進(jìn)程、多線程來(lái)堆并發(fā)但線程切換開(kāi)銷大而且Python的GIL會(huì)讓多線程在CPU密集任務(wù)上吃大虧。1.2 ASGI帶來(lái)的異步接口革命ASGI的全稱是Asynchronous Server Gateway Interface可以理解成WSGI的異步升級(jí)版。它在設(shè)計(jì)上引入了ASGI Scope的概念把HTTP請(qǐng)求、WebSocket連接、生命周期事件等統(tǒng)統(tǒng)統(tǒng)一成一種作用域scope然后通過(guò)異步調(diào)用方式處理。這意味著服務(wù)器可以在等待I/O的時(shí)候去干別的事情而不是干等著。換句話說(shuō)ASGI讓Python Web應(yīng)用真正具備了原生異步并發(fā)的能力你可以在一個(gè)進(jìn)程里同時(shí)處理成千上萬(wàn)個(gè)慢請(qǐng)求、長(zhǎng)連接、WebSocket消息。Uvicorn就是ASGI協(xié)議的一個(gè)具體實(shí)現(xiàn)。除了它市面上還有Hypercorn、Daphne等ASGI服務(wù)器但Uvicorn是目前最主流的很大程度上是因?yàn)樗讓佑昧藆vloop和httptools這兩個(gè)高性能組件速度非?？臁６褾astAPI官方推薦搭配Uvicorn所以它的生態(tài)和文檔也最完善。1.3 Uvicorn在技術(shù)棧中的定位Uvicorn本身不負(fù)責(zé)業(yè)務(wù)邏輯它只是一個(gè)服務(wù)器進(jìn)程負(fù)責(zé)接收網(wǎng)絡(luò)請(qǐng)求、解析HTTP協(xié)議、把請(qǐng)求轉(zhuǎn)給ASGI應(yīng)用然后把應(yīng)用返回的內(nèi)容再發(fā)回客戶端。它的定位有點(diǎn)像交通樞紐外面來(lái)的車HTTP請(qǐng)求先到這里它再調(diào)度給里面的人應(yīng)用處理處理完再原路送回。你完全可以在不寫任何應(yīng)用代碼的情況下單獨(dú)啟動(dòng)Uvicorn它只是等待請(qǐng)求返回404之類的默認(rèn)響應(yīng)但因?yàn)槿鄙賹?shí)際的應(yīng)用對(duì)象它不會(huì)給你任何業(yè)務(wù)功能。在實(shí)際項(xiàng)目中通常的做法是FastAPI或Starlette寫業(yè)務(wù)邏輯Uvicorn作為服務(wù)器跑起來(lái)兩者通過(guò)ASGI協(xié)議對(duì)接。如果還想上更高并發(fā)往往會(huì)在Uvicorn前面再放一個(gè)Nginx做反向代理、負(fù)載均衡甚至在Uvicorn前面掛一個(gè)類似Gunicorn的工具來(lái)管理進(jìn)程。這個(gè)分層關(guān)系理清楚之后你排查問(wèn)題的時(shí)候思路就會(huì)清晰很多出錯(cuò)了到底是框架的問(wèn)題、代碼的問(wèn)題還是服務(wù)器配置的問(wèn)題。2. 核心設(shè)計(jì)拆解Uvicorn的性能到底從哪里來(lái)2.1 uvloop比默認(rèn)事件循環(huán)更快的秘密Python的asyncio自帶一個(gè)事件循環(huán)在大多數(shù)情況下已經(jīng)夠用了但Uvicorn默認(rèn)會(huì)優(yōu)先使用uvloop來(lái)替換它。uvloop是一個(gè)基于libuv的Cython實(shí)現(xiàn)libuv是Node.js底層的異步I/O庫(kù)經(jīng)過(guò)大量真實(shí)場(chǎng)景的考驗(yàn)性能和穩(wěn)定性都很出色。uvloop把很多核心事件循環(huán)的操作從Python層面下沉到了C層面減少了Python解釋器的開(kāi)銷所以在處理大量并發(fā)連接時(shí)它的優(yōu)勢(shì)非常明顯。你以為這只是微小的速度差異實(shí)際上在高并發(fā)場(chǎng)景下uvloop能讓每個(gè)連接的處理開(kāi)銷降低不少。雖然具體數(shù)字取決于機(jī)器和場(chǎng)景但很多性能測(cè)試?yán)颱vicorn的吞吐量都明顯高于使用默認(rèn)事件循環(huán)的服務(wù)器。這也是為什么很多性能評(píng)測(cè)里Uvicorn能跑出漂亮數(shù)據(jù)的原因之一。2.2 httptools更快的HTTP解析器除了事件循環(huán)Uvicorn還用了httptools這個(gè)庫(kù)來(lái)做HTTP協(xié)議的解析。HTTP報(bào)文解析是服務(wù)器最基礎(chǔ)也最高頻的操作如果解析器效率低整個(gè)服務(wù)的響應(yīng)速度都會(huì)被拖累。httptools是從Node.js里的http-parser移植過(guò)來(lái)的C庫(kù)專門針對(duì)HTTP請(qǐng)求的頭部、方法、URL、狀態(tài)碼等做了高度優(yōu)化。這意味著什么舉個(gè)生活化的例子默認(rèn)解析器相當(dāng)于用自己把快遞一件件打開(kāi)、分類、登記httptools則像一條流水線每個(gè)包裹一上來(lái)就能快速拆解分揀。雖然你肉眼感覺(jué)不到單個(gè)請(qǐng)求的差異但在大量請(qǐng)求并發(fā)涌入時(shí)解析速度快就代表了更短的響應(yīng)延遲和更高的吞吐量。Uvicorn還支持HTTP/1.1和WebSocket這部分解析也都是走h(yuǎn)ttptools的效率很高。2.3 單進(jìn)程、多進(jìn)程與事件循環(huán)的配合Uvicorn有三種啟動(dòng)模式單進(jìn)程、多進(jìn)程、以及基于--workers的多worker模式。默認(rèn)情況下Uvicorn只啟動(dòng)一個(gè)進(jìn)程內(nèi)部跑一個(gè)事件循環(huán)。這個(gè)模式下所有的并發(fā)都靠異步事件循環(huán)支撐適合開(kāi)發(fā)調(diào)試和請(qǐng)求量不大的服務(wù)。生產(chǎn)環(huán)境想提升并發(fā)能力可以增加worker數(shù)量也就是多個(gè)獨(dú)立進(jìn)程每個(gè)進(jìn)程有自己獨(dú)立的事件循環(huán)對(duì)應(yīng)不同的CPU核心。這里有個(gè)重要的點(diǎn)Uvicorn的多worker模式并不是自己維護(hù)進(jìn)程池的復(fù)雜系統(tǒng)它底層其實(shí)是繼承了multiprocessing的能力每個(gè)worker都是一個(gè)獨(dú)立的Python進(jìn)程之間不共享內(nèi)存。這也意味著如果你用了一個(gè)全局變量或者進(jìn)程內(nèi)緩存不同worker之間的數(shù)據(jù)是不互通的這個(gè)后面我再詳細(xì)講坑。注意在Docker容器里如果設(shè)置了--workers一定要保證容器有足夠的CPU資源不然多個(gè)worker會(huì)爭(zhēng)搶CPU性能反而下降。有些環(huán)境里還需要關(guān)心文件描述符限制連接數(shù)很大的話默認(rèn)1024可能不夠。3. 安裝與基礎(chǔ)啟動(dòng)從零把服務(wù)跑起來(lái)3.1 安裝Uvicorn標(biāo)準(zhǔn)版還是全功能版安裝Uvicorn非常簡(jiǎn)單pip直接裝就行。但這里有個(gè)小細(xì)節(jié)很多人沒(méi)注意Uvicorn有兩個(gè)安裝模式標(biāo)準(zhǔn)安裝和全功能安裝。標(biāo)準(zhǔn)安裝就是直接pip install uvicorn它會(huì)帶一些核心依賴、簡(jiǎn)單實(shí)用的功能。全功能安裝則是pip install uvicorn[standard]這個(gè)會(huì)額外裝上uvloop、httptools、websockets、watchfiles等一堆東西。其中websockets是用來(lái)支持WebSocket功能的watchfiles是給--reload熱加載用的。簡(jiǎn)單說(shuō)標(biāo)準(zhǔn)版能用但用的是Python默認(rèn)事件循環(huán)且不支持WebSocket全功能版才真正發(fā)揮Uvicorn的性能優(yōu)勢(shì)。我不建議省這一步。直接在項(xiàng)目初始化的時(shí)候用pip install uvicorn[standard]這并不復(fù)雜但能省掉后面很多“為什么我的Uvicorn不支持WebSocket”“為什么性能評(píng)測(cè)數(shù)據(jù)差那么多”之類的問(wèn)題。3.2 第一個(gè)命令localhost:8000跑起來(lái)裝好之后最簡(jiǎn)單的驗(yàn)證方式是在終端里敲uvicorn --version看到版本號(hào)就說(shuō)明安裝沒(méi)問(wèn)題。接著你需要有一個(gè)ASGI應(yīng)用。這里先給一個(gè)最小的Starlette或FastAPI示例# app.py from fastapi import FastAPI app FastAPI() app.get(/) async def read_root(): return {message: hello uvicorn}然后運(yùn)行uvicorn app:app --host 0.0.0.0 --port 8000看到INFO: Uvicorn running on http://0.0.0.0:8000就說(shuō)明啟動(dòng)成功了。這里面app:app的含義是文件app.py里的變量名app。如果你文件叫main.py應(yīng)用對(duì)象叫application那就是main:application。這個(gè)格式很多人第一次會(huì)搞混記住了其實(shí)很簡(jiǎn)單。3.3 --reload熱加載與開(kāi)發(fā)模式的關(guān)鍵參數(shù)開(kāi)發(fā)階段用得最多的就是--reload它可以監(jiān)聽(tīng)代碼文件變化一有改動(dòng)就自動(dòng)重啟服務(wù)。這個(gè)功能在調(diào)試時(shí)候特別方便不用手動(dòng)按CtrlC再啟動(dòng)。實(shí)現(xiàn)原理就是watchfiles庫(kù)監(jiān)控文件系統(tǒng)的變化事件檢測(cè)到變化后重啟整個(gè)worker進(jìn)程。不過(guò)要注意--reload本身是有代價(jià)的它需要額外啟動(dòng)一個(gè)監(jiān)控進(jìn)程來(lái)觀察文件變化這個(gè)進(jìn)程不參與請(qǐng)求處理。所以生產(chǎn)環(huán)境絕對(duì)不要加--reload因?yàn)橐坏┪募腥魏巫兓热缛罩緦懭?、臨時(shí)文件寫入都可能觸發(fā)重啟造成服務(wù)閃斷。我見(jiàn)過(guò)有人上線的時(shí)候忘了去掉這個(gè)參數(shù)導(dǎo)致服務(wù)每隔幾分鐘就重啟一次所有在線用戶全部掉線血淚教訓(xùn)。常用開(kāi)發(fā)命令uvicorn app:app --reload --host 127.0.0.1 --port 8000這里--host 127.0.0.1表示只允許本機(jī)訪問(wèn)安全性更高如果你需要局域網(wǎng)內(nèi)其他設(shè)備調(diào)試才用--host 0.0.0.0。另外還有一個(gè)--port參數(shù)指定端口默認(rèn)就是8000所以不寫也可以。4. 實(shí)操用Uvicorn把FastAPI服務(wù)真正跑起來(lái)4.1 寫一個(gè)帶異步邏輯的示例服務(wù)光跑通還不夠我們要實(shí)際體會(huì)一下Uvicorn對(duì)異步IO的處理方式。先寫一個(gè)稍微豐富點(diǎn)的示例包含異步接口和耗時(shí)操作# app.py import asyncio from fastapi import FastAPI app FastAPI() app.get(/hello) async def hello(): await asyncio.sleep(0.1) return {msg: hello} app.get(/io-bound) async def io_bound_sim(): # 模擬IO密集型操作比如訪問(wèn)數(shù)據(jù)庫(kù)、調(diào)用第三方API await asyncio.sleep(2) return {msg: done after 2s}兩個(gè)接口都用了異步方式尤其IO密集型的接口在異步事件循環(huán)下同一個(gè)進(jìn)程可以同時(shí)處理很多個(gè)這樣的請(qǐng)求而不會(huì)互相阻塞。這就是Uvicorn的核心價(jià)值。4.2 開(kāi)發(fā)模式下觀察熱加載行為在真實(shí)項(xiàng)目中你會(huì)頻繁修改代碼。開(kāi)著--reload啟動(dòng)之后每當(dāng)你保存文件終端上會(huì)輸出類似INFO: Started reloader process [xxxxx]和INFO: Started server process [xxxxx]的信息。這說(shuō)明reloader檢測(cè)到了文件變化正在重啟worker。這里有個(gè)實(shí)用技巧如果你改了代碼但reload沒(méi)反應(yīng)不要急著重裝先確認(rèn)你修改的文件是否在監(jiān)控范圍內(nèi)。Uvicorn默認(rèn)監(jiān)聽(tīng)當(dāng)前工作目錄如果你的代碼文件放在別的目錄或者用包管理工具安裝了項(xiàng)目但是路徑不對(duì)它可能監(jiān)聽(tīng)不到。另外要看你的文件是不是被某些編輯器以臨時(shí)文件的方式保存比如Vim的swap文件如果觸發(fā)了替換邏輯導(dǎo)致reload反而重啟失敗這種情況偶爾也有。4.3 生產(chǎn)模式啟動(dòng)多進(jìn)程與日志關(guān)閉生產(chǎn)環(huán)境不追求熱加載追求穩(wěn)定性、并發(fā)和運(yùn)維友好。一個(gè)比較典型的啟動(dòng)命令是uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4這會(huì)啟動(dòng)4個(gè)worker進(jìn)程每個(gè)都給到一部分并發(fā)能力。這里有個(gè)矛盾點(diǎn)需要解釋Uvicorn在--workers大于1的時(shí)候reloader和workers是不兼容的所以兩個(gè)參數(shù)不能同時(shí)用。如果你既想多進(jìn)程又想熱加載那只能在開(kāi)發(fā)環(huán)境用單worker的reload模式生產(chǎn)環(huán)境用多worker。還有一個(gè)常見(jiàn)選擇日志。Uvicorn啟動(dòng)后會(huì)輸出訪問(wèn)日志、錯(cuò)誤日志等。在后臺(tái)守護(hù)進(jìn)程或者容器環(huán)境里你可能不想讓它輸出到終端過(guò)多可以用--log-level warning降低輸出級(jí)別。生產(chǎn)環(huán)境想記錄訪問(wèn)日志通常建議通過(guò)Nginx來(lái)記錄應(yīng)用層只保留錯(cuò)誤級(jí)別的日志避免重復(fù)記錄造成日志膨脹。5. 進(jìn)階Uvicorn在生產(chǎn)環(huán)境部署中的關(guān)鍵配置5.1 worker數(shù)量怎么選別盲目跟風(fēng)很多教程會(huì)說(shuō)worker數(shù)等于CPU核心數(shù)或2倍核心數(shù)。這個(gè)說(shuō)法太粗糙了實(shí)際要分場(chǎng)景。如果你的服務(wù)是IO密集型在那等數(shù)據(jù)庫(kù)返回、調(diào)外部APIworker數(shù)可以高于CPU核心數(shù)因?yàn)榇蟛糠謺r(shí)間都阻塞在IO上CPU并不是瓶頸。如果是CPU密集型圖像處理、復(fù)雜計(jì)算worker數(shù)一般等于或小于核心數(shù)否則多個(gè)worker互相搶CPU反而降低整體效率。我自己的經(jīng)驗(yàn)是先在測(cè)試環(huán)境壓測(cè)從單worker起步逐步加worker觀察QPS和響應(yīng)延遲的變化。當(dāng)加worker之后QPS沒(méi)有明顯提升說(shuō)明CPU已經(jīng)飽和或者瓶頸在別處比如數(shù)據(jù)庫(kù)連接池、帶寬這時(shí)候繼續(xù)加worker只是浪費(fèi)內(nèi)存。還有一點(diǎn)每個(gè)worker都會(huì)復(fù)制一份應(yīng)用對(duì)象所以如果你啟動(dòng)時(shí)加載了很大的模型或者緩存內(nèi)存開(kāi)銷會(huì)線性增長(zhǎng)控制好worker數(shù)量非常重要。5.2 生命周期管理優(yōu)雅關(guān)閉與慢請(qǐng)求處理Uvicorn支持優(yōu)雅關(guān)閉你發(fā)一個(gè)SIGINTCtrlC或SIGTERM信號(hào)時(shí)它會(huì)停止接收新連接并等待當(dāng)前正在處理中的請(qǐng)求完成后再退出。這個(gè)機(jī)制對(duì)線上服務(wù)非常重要防止你在發(fā)版的時(shí)候把正在跑了一半的請(qǐng)求直接掐斷。默認(rèn)情況下Uvicorn等待的時(shí)間并不是無(wú)限長(zhǎng)它有一個(gè)超時(shí)機(jī)制。比如某些請(qǐng)求特別慢幾十秒甚至幾分鐘如果你想在關(guān)閉時(shí)給它更長(zhǎng)的時(shí)間可以通過(guò)--timeout-graceful-shutdown參數(shù)來(lái)設(shè)置單位是秒。這個(gè)參數(shù)有些Uvicorn版本才支持用之前建議先確認(rèn)版本。另外推薦在部署腳本里先發(fā)SIGTERM信號(hào)然后等待一段時(shí)間再確認(rèn)進(jìn)程是否退出如果超時(shí)再?gòu)?qiáng)殺。比如在systemd服務(wù)里配置TimeoutStopSec30給足優(yōu)雅關(guān)閉的時(shí)間。5.3 與反向代理配合Nginx和Uvicorn的分工生產(chǎn)環(huán)境很少讓Uvicorn直接面對(duì)公網(wǎng)。常規(guī)做法是前面掛NginxUvicorn監(jiān)聽(tīng)一個(gè)本機(jī)端口比如8001Nginx監(jiān)聽(tīng)80/443對(duì)外提供服務(wù)。這樣做的原因有三個(gè)一是Nginx處理靜態(tài)文件、請(qǐng)求頭、Gzip壓縮等能力更強(qiáng)二是Nginx可以做負(fù)載均衡把請(qǐng)求分發(fā)到多個(gè)Uvicorn實(shí)例或多臺(tái)服務(wù)器三是安全上多一層保護(hù)隱藏后端端口。Nginx里一個(gè)簡(jiǎn)易的配置大概是server { listen 80; location / { proxy_pass http://127.0.0.1:8001; 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; } }要注意的是一旦加上反向代理Uvicorn的訪問(wèn)日志里記錄的IP基本都是127.0.0.1因?yàn)槟憧吹降氖荖ginx轉(zhuǎn)發(fā)過(guò)來(lái)的請(qǐng)求這就是為什么我們要設(shè)置X-Forwarded-For頭。FastAPI里可以通過(guò)request.client.host拿到真實(shí)IP前提是中間代理配置正確。如果沒(méi)有正確透?jìng)魉杏脩鬒P會(huì)被當(dāng)成一個(gè)IP這在做限流或用戶分析時(shí)會(huì)有大問(wèn)題。另外HTTP長(zhǎng)連接和WebSocket在Nginx后面也要特殊配置proxy_http_version 1.1、Upgrade和Connection頭否則WebSocket連接會(huì)經(jīng)常斷開(kāi)。6. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄6.1 端口占用導(dǎo)致無(wú)法啟動(dòng)啟動(dòng)Uvicorn時(shí)報(bào)[Errno 98] Address already in use這是最典型的問(wèn)題。通常是你上一次的服務(wù)沒(méi)關(guān)掉或者端口被其他進(jìn)程占用了。解決方式分幾步先確認(rèn)是誰(shuí)占用了端口Linux下用lsof -i :8000 # 或 netstat -tlnp | grep 8000找到PID之后確認(rèn)這是不是你要?dú)⒌舻倪M(jìn)程再kill -9 PID。不要一看到端口占用就殺進(jìn)程先確認(rèn)一下免得誤殺別的服務(wù)。還有一種情況是你自己剛才啟動(dòng)的reload模式服務(wù)因?yàn)榻K端窗口沒(méi)關(guān)進(jìn)程還在后臺(tái)。如果你用的是或者nohup方式啟動(dòng)記得用ps aux | grep uvicorn看一下殘留進(jìn)程。6.2 --reload不生效或頻繁重啟熱加載失效是比較頭疼的問(wèn)題。先確認(rèn)安裝的是不是標(biāo)準(zhǔn)安裝因?yàn)閞eload依賴watchfiles標(biāo)準(zhǔn)安裝已經(jīng)包含了。如果還是不行檢查以下幾點(diǎn)你修改的代碼文件是否在啟動(dòng)目錄下。啟動(dòng)命令里是否用了--reload-dir指定錯(cuò)誤目錄。編輯器保存時(shí)是否生成了臨時(shí)文件導(dǎo)致監(jiān)控混亂。如果遇到頻繁重啟多半是監(jiān)控目錄里某些文件反復(fù)變化比如日志文件、緩存文件。解決辦法是把這些目錄排除掉uvicorn app:app --reload --reload-exclude logs/* --reload-exclude *.pyc這樣能保證只有真正改代碼的時(shí)候才重啟那些臨時(shí)文件不會(huì)干擾監(jiān)控。6.3 多worker模式下全局狀態(tài)不同步這個(gè)問(wèn)題很多人踩過(guò)坑。在單進(jìn)程模式里你可能習(xí)慣用一個(gè)全局字典做緩存或者用一個(gè)全局變量存儲(chǔ)用戶在線狀態(tài)。一旦切到--workers 4每個(gè)worker進(jìn)程都是獨(dú)立解釋器全局變量互不相通。這就導(dǎo)致A worker寫入的緩存B worker讀不到表現(xiàn)就是“明明更新了數(shù)據(jù)但請(qǐng)求有時(shí)候拿到舊的”。解決方案一般有三條路本地緩存不用全局變量改用Redis之類的分布式存儲(chǔ)只做只讀性質(zhì)的全局配置不依賴寫入或者干脆用單worker同步模式但如果并發(fā)要求高單worker又不夠。我個(gè)人建議如果你的服務(wù)以后一定要擴(kuò)展并發(fā)從一開(kāi)始就不要設(shè)計(jì)進(jìn)程內(nèi)可變?nèi)譅顟B(tài)養(yǎng)成用外部存儲(chǔ)的習(xí)慣后面會(huì)少很多麻煩。6.4 慢請(qǐng)求導(dǎo)致事件循環(huán)阻塞Uvicorn是異步的但如果你的業(yè)務(wù)代碼里有同步阻塞的操作比如用requests.get()做同步HTTP調(diào)用、CPU密集的循環(huán)、大量數(shù)據(jù)庫(kù)同步查詢這些操作都會(huì)阻塞事件循環(huán)導(dǎo)致整個(gè)進(jìn)程卡住其他請(qǐng)求全部排隊(duì)等待。注意這個(gè)坑極其隱蔽單個(gè)請(qǐng)求慢一點(diǎn)可能不明顯但一旦并發(fā)上來(lái)一個(gè)阻塞操作就能讓整個(gè)服務(wù)雪崩。解決方式有兩種模式一是把阻塞操作改成異步操作比如用httpx.AsyncClient替代requests用異步數(shù)據(jù)庫(kù)驅(qū)動(dòng)二是如果實(shí)在無(wú)法異步化用run_in_executor把它丟到線程池里執(zhí)行。FastAPI里同步路徑操作會(huì)自動(dòng)跑在線程池所以在FastAPI中寫好同步接口其實(shí)問(wèn)題不大但在純Starlette或自定義ASGI應(yīng)用里你就要自己注意了。6.5 大并發(fā)下的文件描述符受限當(dāng)你把連接數(shù)調(diào)到很高時(shí)可能會(huì)遇到Too many open files錯(cuò)誤。這是Linux文件描述符上限導(dǎo)致的。臨時(shí)提高當(dāng)前shell的限制ulimit -n 65535但這個(gè)是臨時(shí)的重啟失效。要永久修改需要改/etc/security/limits.conf給對(duì)應(yīng)的用戶加上nofile限制。這個(gè)細(xì)節(jié)在運(yùn)維同學(xué)那里是基本功但開(kāi)發(fā)者自己在服務(wù)器上跑Uvicorn時(shí)很容易忽略。如果想徹底點(diǎn)Uvicorn還支持通過(guò)--backlog控制內(nèi)核中等待接受的連接隊(duì)列長(zhǎng)度一般默認(rèn)是2048高并發(fā)場(chǎng)景建議調(diào)高。這里有個(gè)前提你的Linux內(nèi)核參數(shù)net.core.somaxconn也得跟著調(diào)高否則Uvicorn設(shè)置的值超過(guò)內(nèi)核上限會(huì)被截?cái)唷?. 基于個(gè)人經(jīng)驗(yàn)的一個(gè)小總結(jié)用了Uvicorn這么久我自己最大的體會(huì)是它確實(shí)把Python服務(wù)端的性能上限抬高了一個(gè)臺(tái)階但前提是你真的理解了什么場(chǎng)景下它才能發(fā)揮優(yōu)勢(shì)。就拿FastAPI來(lái)說(shuō)框架層面給你封裝好了很多異步優(yōu)化但你寫代碼時(shí)用了一個(gè)同步requests性能一樣拉胯。工具永遠(yuǎn)只是能力的一半另一半在你的代碼習(xí)慣里。最后分享一個(gè)小技巧調(diào)試Uvicorn底層行為的時(shí)候可以用--log-level debug啟動(dòng)能看到請(qǐng)求的完整生命周期日志包括請(qǐng)求進(jìn)來(lái)、事件循環(huán)處理、響應(yīng)返回的每個(gè)環(huán)節(jié)。這個(gè)模式下信息量非常大新手容易被淹沒(méi)但排查疑難問(wèn)題的時(shí)候真的管用。比如你懷疑某個(gè)請(qǐng)求超時(shí)debug日志會(huì)告訴你時(shí)間花在了哪一步。還有一個(gè)比--reload更直接的調(diào)試方法在代碼里加if __name__ __main__:的入口然后直接用uvicorn.run來(lái)啟動(dòng)應(yīng)用這樣所有參數(shù)都可以寫進(jìn)代碼里版本管理和團(tuán)隊(duì)協(xié)作都方便。尤其是項(xiàng)目配置多的時(shí)候命令行參數(shù)記不全不如直接固化到代碼里誰(shuí)拿到這個(gè)項(xiàng)目都能一鍵跑起來(lái)。希望這篇教程能幫你少走一些彎路把Uvicorn真正用順手。