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