用：從開發(fā)環(huán)境到服務(wù)器的完整指南)
把Python Web應(yīng)用從開發(fā)環(huán)境搬到服務(wù)器是很多初學(xué)者邁不過去的一道坎。開發(fā)的時候用Flask自帶服務(wù)器跑得飛起真到了上線這天什么Python版本不一致、依賴裝不上、端口被占用、進程一關(guān)服務(wù)就掛……各種問題全冒出來了。這篇文章要解決的問題就是如何用Docker把Python應(yīng)用打包成標準鏡像配合Nginx做反向代理穩(wěn)定地跑在云服務(wù)器上。這套方案適用于Flask、FastAPI、Django等主流Python Web框架也適用于想要規(guī)范部署流程、減少環(huán)境踩坑的開發(fā)者。我會從方案選型講起再到環(huán)境準備、容器化改造、Nginx配置、完整實操流程和問題排查覆蓋一套可以直接照著做的部署路徑。1. 部署方案總體拆解1.1 為什么選Docker Nginx而不是直接在服務(wù)器上裸跑很多人一開始會想服務(wù)器上直接裝Python然后把代碼clone上去python app.py不就能跑了嗎確實能跑但只適合臨時演示。裸跑會踩這幾個痛點開發(fā)機是Windows或macOS服務(wù)器是Ubuntu或CentOSPython版本、底層依賴庫存在差異本地能啟動的項目服務(wù)器上一跑就報錯。一臺服務(wù)器上如果跑多個Python應(yīng)用依賴之間容易互相沖突。你升了一個庫的版本另一個應(yīng)用掛了排查起來非常頭疼。進程管理是個大坑。用nohup python app.py 方式啟動SSH一斷開、進程崩了、服務(wù)器重啟了服務(wù)就沒了還得手動去拉起。升級回滾困難。代碼改了一版改出問題了想退回上一版裸跑環(huán)境根本沒做版本管理。Docker把這些痛點一網(wǎng)打盡。鏡像就是打包好的運行環(huán)境里面固化了Python版本、依賴庫、啟動命令無論推到哪臺服務(wù)器跑起來的結(jié)果都一樣。容器之間相互隔離多應(yīng)用共存不沖突。鏡像用tag做版本管理回滾只是換一個鏡像標簽的事。配合restart: always策略容器崩了自動拉起服務(wù)器重啟也會自動恢復(fù)。那為什么還要加個Nginx因為Docker解決的是“應(yīng)用怎么跑”的問題Nginx解決的是“流量怎么進”的問題。你的Python容器默認監(jiān)聽某個端口比如8000如果直接用http://服務(wù)器IP:8000訪問會遇到幾個麻煩一是端口暴露得太多如果一個服務(wù)器上跑三個應(yīng)用總不能讓用戶記住三個帶端口的地址二是80/443端口是Web服務(wù)的默認入口讓用戶敲端口訪問非常不專業(yè)三是Nginx能做負載均衡、靜態(tài)文件加速、HTTPS證書終結(jié)這些事性能和安全層面都比直接把Python服務(wù)暴露到公網(wǎng)更靠譜。所以最終架構(gòu)是Nginx在容器里監(jiān)聽80/443端口接收所有外部請求再按規(guī)則轉(zhuǎn)發(fā)到內(nèi)部的Python應(yīng)用容器。1.2 整體架構(gòu)與請求鏈路先看最簡單的一臺服務(wù)器上的部署結(jié)構(gòu)瀏覽器 │ ▼ Nginx 容器監(jiān)聽 80/443 端口 │ proxy_pass 轉(zhuǎn)發(fā)到內(nèi)網(wǎng)地址 ▼ Python 應(yīng)用容器Gunicorn 監(jiān)聽 8000 端口跑 Flask/Django/FastAPI │ ▼ 數(shù)據(jù)庫容器MySQL/PostgreSQL/Redis這里有一個關(guān)鍵點Nginx容器和Python容器應(yīng)該在同一個Docker網(wǎng)絡(luò)中它們之間通過服務(wù)名互相訪問不需要把Python的8000端口暴露到宿主機上。這樣外部流量只能通過Nginx進入安全性和規(guī)范性都更好。我用一個生活化類比來解釋這套架構(gòu)Docker容器就像一個個小房子應(yīng)用在房子里跑有自己的小環(huán)境Nginx是小區(qū)門口的保安亭所有訪客先到保安亭登記保安再告訴訪客去幾棟幾單元。沒有保安亭訪客就得直接跑到每個房子門口敲門既混亂又不安全。這套架構(gòu)說起來簡單但真正落地的時候有很多細節(jié)要注意Docker版本怎么裝、鏡像加速怎么配、Dockerfile怎么寫才科學(xué)、Nginx反代需要設(shè)置哪些請求頭、靜態(tài)文件怎么處理、數(shù)據(jù)庫連接怎么管理等。下面逐個拆解。2. 部署前的服務(wù)器與環(huán)境準備2.1 服務(wù)器選型與基礎(chǔ)初始化部署這套方案服務(wù)器的配置不用太高。個人項目、小流量Web應(yīng)用2核4G的云服務(wù)器完全夠用。操作系統(tǒng)建議選Ubuntu 22.04 LTS或Debian 12這兩者在Docker的支持上最省心社區(qū)資料也多。服務(wù)器到手后先做兩個基礎(chǔ)動作。第一是更新系統(tǒng)軟件包sudo apt update sudo apt upgrade -y第二是創(chuàng)建非root用戶用于日常操作。我一直建議不要直接用root跑業(yè)務(wù)萬一某個操作出錯影響面太大。創(chuàng)建一個叫deploy的用戶并加入sudo組sudo useradd -m -s /bin/bash deploy sudo usermod -aG sudo deploy sudo passwd deploy之后用這個用戶登錄服務(wù)器操作Docker相關(guān)的命令需要加sudo。如果你實在嫌麻煩直接把當前用戶加入docker組可以免sudo執(zhí)行docker命令sudo usermod -aG docker deploy改完組要重新登錄一次才生效。2.2 安裝Docker與Docker ComposeDocker的安裝路徑有兩條一是用官方腳本一把梭二是用apt源安裝。我推薦用官方腳本省事版本也新curl -fsSL https://get.docker.com | bash -s docker安裝完成后驗證一下sudo docker version sudo docker compose version如果你拿到的是舊教程里面寫的是docker-compose帶橫杠命令那是舊版Compose的語法?，F(xiàn)在主流版本是Docker Compose v2直接用docker compose空格調(diào)用。如果系統(tǒng)提示找不到compose命令多半是Docker版本比較老升級一下即可。國內(nèi)服務(wù)器有一個極度影響體驗的問題拉取Docker Hub鏡像慢到懷疑人生。解決辦法是配置鏡像加速器。編輯/etc/docker/daemon.json{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com ] }保存后重啟Dockersudo systemctl restart docker配置完加速器后拉鏡像的速度會明顯提升。這里順帶提一個熱搜里很多人踩的坑在Windows上安裝Docker Desktop時提示virtualization support not detected說明電腦的CPU虛擬化沒有開啟需要進BIOS打開Intel VT-x或AMD SVM。這個細節(jié)在后續(xù)“常見問題”章節(jié)會展開說。2.3 基礎(chǔ)網(wǎng)絡(luò)與端口規(guī)劃部署前先想清楚端口怎么規(guī)劃。通常占用這幾個端口80HTTP入口由Nginx容器占用。443HTTPS入口由Nginx容器占用。3306、6379如果MySQL、Redis也在Docker里跑這些端口通常只對內(nèi)部網(wǎng)絡(luò)開放不需要映射到宿主機。如果為了本地調(diào)試方便要映射建議只綁定到127.0.0.1。怎么理解“只對內(nèi)開放”在做端口映射的時候3306:3306和127.0.0.1:3306:3306的區(qū)別在于前者所有網(wǎng)絡(luò)接口都能訪問相當于把數(shù)據(jù)庫暴露到公網(wǎng)非常危險后者只有服務(wù)器本機localhost能訪問外部請求到不了。云服務(wù)商控制臺的安全組也要放行80、443端口。安全組是云服務(wù)器的第一道防火墻在ECS/CVM控制臺的“安全組”規(guī)則里添加入方向規(guī)則端口填80/443來源填寫0.0.0.0/0。這一步漏了的話服務(wù)器的防火墻無論怎么配外面都訪問不到。3. Python項目容器化改造3.1 代碼層面需要做哪些調(diào)整容器化不是把代碼扔進Docker就完事了有些習(xí)慣得先改過來。第一所有配置必須在代碼外部化。什么是外部化就是DEBUGTrue、SECRET_KEYxxxxx、DATABASE_URLmysql://...這些值不能硬編碼在代碼文件里要從環(huán)境變量讀取。比如Flask項目里配置寫成import os DEBUG os.getenv(DEBUG, false).lower() true SECRET_KEY os.getenv(SECRET_KEY, please-change-me) DATABASE_URL os.getenv(DATABASE_URL, sqlite:///app.db)為什么要這么做因為同一個鏡像可能部署到測試環(huán)境和生產(chǎn)環(huán)境代碼完全一樣只是環(huán)境變量不同。Docker本身就支持在啟動容器時注入環(huán)境變量用環(huán)境變量管理配置是容器化部署的基本功。第二明確Python依賴。項目根目錄放一份requirements.txt盡量鎖定大版本號或精確版本號。別偷懶寫一堆不帶版本號的依賴這次裝和下次裝可能依賴版本就漂移了正好砸中“開發(fā)環(huán)境能跑、線上環(huán)境跑不起來”的老問題。推薦用pip freeze requirements.txt生成當前環(huán)境的依賴列表或者手動整理核心依賴。第三確認Web框架的啟動方式。開發(fā)時用Flask自帶的app.run()或Django的runserver可以生產(chǎn)環(huán)境必須換成異步WSGI服務(wù)器最常用的是Gunicorn。后面會專門講。3.2 編寫一個科學(xué)的Dockerfile以Flask項目為例項目的目錄結(jié)構(gòu)大概是myapp/ ├── app/ │ ├── __init__.py │ └── views.py ├── requirements.txt ├── Dockerfile ├── .dockerignore ├── nginx/ │ └── default.conf └── docker-compose.ymlDockerfile的內(nèi)容FROM python:3.11-slim WORKDIR /app ENV PYTHONDONTWRITEBYTECODE1 \ PYTHONUNBUFFERED1 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple COPY . . EXPOSE 8000 CMD [gunicorn, --bind, 0.0.0.0:8000, --workers, 3, app:app]逐行解釋一下關(guān)鍵點python:3.11-slimslim版本體積小包含運行Python所需的最小環(huán)境。盡量別用帶-alpine的版本雖然體積更小但某些依賴庫需要編譯容易出問題。PYTHONDONTWRITEBYTECODE1不生成__pycache__減少鏡像里的垃圾文件。PYTHONUNBUFFERED1日志不緩沖實時輸出到標準輸出方便用docker logs看日志。pip install -i https://pypi.tuna.tsinghua.edu.cn/simple國內(nèi)服務(wù)器裝PyPI依賴用清華鏡像速度差距非常大不用鏡像可能等十幾分鐘用了鏡像一分鐘內(nèi)裝完。CMD里用的是Gunicorn而不是python app.py。Gunicorn是多進程WSGI服務(wù)器能利用多核CPU并發(fā)能力遠超開發(fā)服務(wù)器。--workers 3表示開3個工作進程一般按“CPU核心數(shù) × 2 1”估算。如果服務(wù)器是2核5個worker比較合適我這里寫3是為了保守看實際內(nèi)存調(diào)整。另外.dockerignore文件很容易被忽略但非常重要。它的作用是告訴Docker哪些文件不要進入鏡像構(gòu)建上下文。最小內(nèi)容__pycache__/ *.pyc .git/ .env venv/沒有.dockerignoreCOPY . .會把你本地的虛擬環(huán)境、git目錄、日志文件全打進去鏡像又大又慢。3.3 靜態(tài)文件與運行用戶Django項目會用到collectstatic收集靜態(tài)文件Flask項目如果有獨立的前端資源也一樣默認由Python處理。但在生產(chǎn)環(huán)境更好的方案是讓Nginx直接處理靜態(tài)文件不要經(jīng)過Python應(yīng)用。這樣Python容器專注于動態(tài)請求靜態(tài)資源響應(yīng)速度也更快。具體操作是Nginx容器里掛載一份靜態(tài)文件目錄配置里用alias或root指向它。后面Nginx配置部分會給出完整寫法。那靜態(tài)文件怎么進到Nginx容器里的兩個思路一是構(gòu)建時在Nginx鏡像里COPY進去二是用Docker的數(shù)據(jù)卷把宿主機目錄共享給兩個容器。我常用的是后者在Compose里把宿主機的static/目錄同時掛載給Python容器和Nginx容器。還有一個安全細節(jié)容器內(nèi)默認是root用戶跑應(yīng)用如果鏡像被打包分發(fā)root權(quán)限會有安全風(fēng)險?？梢栽贒ockerfile里創(chuàng)建非root用戶并切換RUN addgroup --system app adduser --system --ingroup app app USER app注意如果用了這個配置容器內(nèi)寫文件比如Django的media上傳目錄所在的數(shù)據(jù)卷必須給app用戶寫權(quán)限否則會報Permission denied。3.4 docker-compose.yml 編排三件套docker-compose.yml是整套部署的中樞。我個人習(xí)慣把Nginx、Python應(yīng)用、數(shù)據(jù)庫放到同一個Compose文件里管理用服務(wù)名互相訪問主機映射只暴露Nginx的80端口和數(shù)據(jù)庫的本地端口。一個最簡但完整的編排文件services: web: build: . restart: always env_file: - .env volumes: - static_volume:/app/static expose: - 8000 depends_on: - db nginx: image: nginx:1.25-alpine restart: always ports: - 80:80 volumes: - ./nginx/default.conf:/etc/nginx/conf.d/default.conf - static_volume:/app/static depends_on: - web db: image: mysql:8.0 restart: always env_file: - .env volumes: - mysql_data:/var/lib/mysql expose: - 3306 volumes: static_volume: mysql_data:逐個解釋這里面的設(shè)計意圖web服務(wù)用的是build: .也就是用當前目錄的Dockerfile構(gòu)建鏡像。expose和ports的區(qū)別要分清。expose只在Docker內(nèi)部網(wǎng)絡(luò)中暴露端口宿主機和外部訪問不到ports才會把端口映射到宿主機。web服務(wù)的8000端口只需要讓Nginx容器通過內(nèi)部網(wǎng)絡(luò)訪問所以用expose不用映射到宿主機。nginx服務(wù)把本機的./nginx/default.conf掛載到容器內(nèi)的Nginx配置目錄改配置不用重新構(gòu)建鏡像改完docker compose restart nginx就生效。env_file: .env將環(huán)境變量從文件加載進容器數(shù)據(jù)庫密碼、SECRET_KEY這類敏感信息都放在.env里不進倉庫。depends_on保證啟動順序。但要注意它只保證“先啟動”不保證“可用”。MySQL容器啟動到真正能接受連接還有幾秒到幾十秒的初始化時間Python應(yīng)用如果啟動時立即連數(shù)據(jù)庫可能連不上。這個問題在后面的“常見問題”章節(jié)會提供一個解決方案。.env文件示例SECRET_KEYyour-secret-key DATABASE_URLmysql://myapp:myapp123db:3306/myapp MYSQL_ROOT_PASSWORDroot123 MYSQL_DATABASEmyapp MYSQL_USERmyapp MYSQL_PASSWORDmyapp123有一個地方容易出錯DATABASE_URL里數(shù)據(jù)庫地址寫的是db而不是127.0.0.1。因為在Compose網(wǎng)絡(luò)中服務(wù)名db會被DNS解析到MySQL容器的IP地址。如果你寫成127.0.0.1Python容器訪問的是它自己的回環(huán)地址里面并沒有MySQL在監(jiān)聽必然連接失敗。4. Nginx反向代理配置詳解4.1 反向代理到底在做什么先搞清楚正向代理和反向代理的區(qū)別。正向代理是“替客戶端訪問服務(wù)器”客戶端知道代理的存在訪問被限制的資源時找代理幫忙比如常見的開發(fā)調(diào)試代理。反向代理是“替服務(wù)器接收請求”客戶端不知道代理的存在它訪問的是NginxNginx再轉(zhuǎn)發(fā)給后面的應(yīng)用服務(wù)器。在部署場景里Nginx做的是反向代理。用戶訪問http://你的域名請求到達NginxNginx根據(jù)配置把請求轉(zhuǎn)發(fā)給內(nèi)部網(wǎng)絡(luò)里的Python容器。等Python返回響應(yīng)Nginx再轉(zhuǎn)回給用戶。這個過程對用戶完全透明。加一層Nginx帶來的實際收益有三個統(tǒng)一入口。多個Python應(yīng)用可以共用一個80/443端口用不同域名或不同路徑區(qū)分。安全緩沖。Python應(yīng)用不需要直接暴露公網(wǎng)端口減少被掃描和攻擊的面。性能提升。Nginx的靜態(tài)文件處理能力和并發(fā)連接能力遠強于Python應(yīng)用服務(wù)器靜態(tài)資源交給Nginx能顯著降低應(yīng)用壓力。4.2 一份完整的Nginx站點配置在項目目錄下創(chuàng)建nginx/default.confupstream myapp { server web:8000; } server { listen 80; server_name example.com www.example.com; client_max_body_size 20M; location /static/ { alias /app/static/; expires 7d; access_log off; } location / { proxy_pass http://myapp; 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_connect_timeout 60s; proxy_read_timeout 60s; } }關(guān)鍵點拆解upstream myapp { server web:8000; }定義了上游應(yīng)用服務(wù)器池web是Compose里Python服務(wù)的名稱。如果以后擴展成多實例可以在這里加多行server實現(xiàn)負載均衡。location /static/靜態(tài)文件請求由Nginx直接處理alias /app/static/指向Nginx容器內(nèi)掛載的靜態(tài)文件目錄注意alias后面必須有/。expires 7d給靜態(tài)資源加7天瀏覽器緩存降低服務(wù)器壓力。加了access_log off避免靜態(tài)資源請求刷屏日志。location /其余請求全轉(zhuǎn)發(fā)到Python應(yīng)用。proxy_set_header這幾行必不可少特別是X-Forwarded-For如果缺了它Django/Flask拿到的客戶端IP全是Nginx容器的IP日志里的真實訪客IP就丟了。client_max_body_size 20M允許上傳的最大請求體大小。默認值只有1M如果應(yīng)用有文件上傳功能不調(diào)大會直接413錯誤。關(guān)于proxy_pass http://myapp和proxy_pass http://web:8000的區(qū)別兩種寫法都能用。用upstream的好處是后期可以在Nginx層做更靈活的負載均衡策略比如加權(quán)重、加健康檢查。簡單場景下直接在proxy_pass里寫http://web:8000也行。4.3 啟用HTTPS證書沒有HTTPS現(xiàn)代瀏覽器地址欄會提示不安全而且HTTP明文傳輸時密碼、Cookie都能被截獲。部署完成后強烈建議上HTTPS。最省事的方案是用Certbot自動申請和續(xù)期Let‘s Encrypt免費證書。安裝Certbotsudo apt install certbot python3-certbot-nginx然后執(zhí)行sudo certbot --nginx -d example.com -d www.example.comCertbot會自動識別Nginx配置、自動申請證書、自動改寫配置文件加入SSL相關(guān)設(shè)置還會自動配置HTTP跳轉(zhuǎn)HTTPS。證書90天有效期Certbot會通過systemd定時任務(wù)自動續(xù)期基本不用手動管。如果你用的是云廠商的免費證書流程是去云控制臺申請證書 → 下載Nginx版證書文件 → 上傳到服務(wù)器 → 手動改Nginx配置。手動配置的關(guān)鍵片段server { listen 443 ssl; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com.pem; ssl_certificate_key /etc/nginx/ssl/example.com.key; # 其余配置同HTTP版 } server { listen 80; server_name example.com; return 301 https://$host$request_uri; }注意容器里的Nginx需要把證書文件也掛載進去在Compose的nginx服務(wù)里加一行volumes: - /etc/nginx/ssl:/etc/nginx/ssl:ro5. 完整實操部署流程5.1 代碼上傳與目錄規(guī)劃先把項目代碼傳到服務(wù)器。最推薦的方式是用Git在服務(wù)器上直接clone倉庫。如果項目是私有的需要配置SSH key或者在服務(wù)器上使用帶token的clone地址。沒有Git倉庫的話用scp從本地傳到服務(wù)器也行scp -r ./myapp deploy服務(wù)器IP:/home/deploy/www/傳到服務(wù)器后目錄結(jié)構(gòu)應(yīng)該是/home/deploy/www/myapp/ ├── app/ ├── requirements.txt ├── Dockerfile ├── .dockerignore ├── .env ├── nginx/ │ └── default.conf └── docker-compose.yml注意.env文件里有數(shù)據(jù)庫密碼和SECRET_KEY千萬不要把這個文件提交到Git倉庫。我見過太多把密鑰提交進倉庫導(dǎo)致被爬蟲掃出數(shù)據(jù)庫密碼的案例。建議在Git倉庫中忽略.env傳到服務(wù)器后手動創(chuàng)建。5.2 構(gòu)建并啟動容器進入項目目錄先檢查配置文件語法有沒有問題cd /home/deploy/www/myapp docker compose config這個命令會解析Compose文件并輸出最終的解析結(jié)果。如果報錯說明YAML格式有問題或者服務(wù)定義有誤先修好再往下走。然后構(gòu)建并啟動docker compose up -d --build-d表示后臺運行--build表示構(gòu)建鏡像后啟動。第一次構(gòu)建會比較慢因為要拉基礎(chǔ)鏡像、裝依賴。耐心等待構(gòu)建完成后查看容器狀態(tài)docker compose ps如果所有服務(wù)的狀態(tài)都是Up說明容器已經(jīng)跑起來了。此時在服務(wù)器本地用curl測試一下curl -I http://127.0.0.1如果返回HTTP/1.1 200 OK說明Nginx已經(jīng)正常響應(yīng)。再用完整域名從本地瀏覽器訪問看頁面是否正常。數(shù)據(jù)庫遷移也需要執(zhí)行一次。Django項目docker compose exec web python manage.py migrateFlask項目如果有初始化表結(jié)構(gòu)的命令同理用docker compose exec web進入容器執(zhí)行。5.3 查看日志與排錯容器跑起來了不代表一切正常。查看所有服務(wù)的日志docker compose logs -f只看某個服務(wù)的日志docker compose logs -f web日志是最直接的排錯入口。Python應(yīng)用啟動報錯了、數(shù)據(jù)庫連接失敗了、Nginx轉(zhuǎn)發(fā)超時了都會反映在日志里。日志默認是彩色的-f參數(shù)是持續(xù)跟蹤新日志輸出。生產(chǎn)環(huán)境我一般會把日志接入到集中式日志平臺但個人項目直接用docker compose logs就夠了。5.4 更新與發(fā)布新版本代碼改了要上線最常規(guī)的操作是git pull docker compose up -d --build流程是拉取最新代碼 → 重新構(gòu)建鏡像 → 優(yōu)雅替換容器。Gunicorn默認支持優(yōu)雅重啟正在處理的請求會處理完才結(jié)束進程不會出現(xiàn)請求中斷。如果想零停機更新可以配置deploy.rollback_config或其他藍綠發(fā)布方案但個人項目用上面的簡單方案已經(jīng)足夠穩(wěn)。5.5 數(shù)據(jù)持久化與備份驗證Compose文件里已經(jīng)為MySQL配置了數(shù)據(jù)卷mysql_data數(shù)據(jù)庫數(shù)據(jù)存放在卷里容器刪了重建數(shù)據(jù)不會丟。但這不等于萬事大吉卷里的數(shù)據(jù)如果服務(wù)器磁盤壞了同樣會丟。建議定期備份MySQL數(shù)據(jù)docker compose exec db mysqldump -u root -p myapp backup_$(date %F).sql可以把這條命令加到crontab里每天凌晨備份一次備份文件保留最近7天?；謴?fù)的時候cat backup_2025-01-01.sql | docker compose exec -T db mysql -u root -p myapp一定要親手驗證一次備份文件能正?；謴?fù)。我見過太多人配置了定時備份結(jié)果因為密碼寫錯、命令路徑不對備份文件全是0字節(jié)真正出事的時候才發(fā)現(xiàn)根本沒備份成功。6. 常見問題與排查技巧實錄6.1 502 Bad Gateway這是Nginx部署中最常見的錯誤意思是Nginx無法連接到上游的Python應(yīng)用。排查思路按順序走看web容器是否還在運行docker compose ps如果顯示Exit說明Python應(yīng)用啟動失敗進web容器日志找原因docker compose logs web。確認web容器內(nèi)部端口是否監(jiān)聽了docker compose exec web curl -I http://127.0.0.1:8000。如果容器里沒有curl可以用Python代替docker compose exec web python -c import urllib.request; print(urllib.request.urlopen(http://127.0.0.1:8000).status)。確認Nginx的upstream配置里的服務(wù)名與Compose服務(wù)名一致。配置里寫的是server web:8000Compose服務(wù)名必須是web如果寫錯了或者忘了在同一個網(wǎng)絡(luò)里就會502。確認Nginx配置沒有語法問題docker compose exec nginx nginx -t。多數(shù)情況下問題出在Python應(yīng)用啟動失敗導(dǎo)致容器退出日志里會明確提示是缺依賴、端口被占用還是代碼報錯。6.2 同端口沖突服務(wù)器上已經(jīng)有服務(wù)占用80新部署一個項目啟動Nginx容器時報bind: address already in use說明宿主機80端口已經(jīng)被占用了。這種現(xiàn)象很常見之前用裸機部署過Nginx的、服務(wù)器面板自帶Web服務(wù)的都會占80端口。處理辦法是先看看誰占了端口sudo lsof -i :80如果是系統(tǒng)自帶的Apache或老版本Nginx停掉并禁用開機啟動sudo systemctl stop apache2 sudo systemctl disable apache2如果是另一個Docker容器占用了80端口需要檢查那個容器的端口映射配置改掉其中一個。6.3 靜態(tài)文件全部404頁面能打開但樣式全丟F12看到靜態(tài)資源返回404。核心原因是靜態(tài)文件掛載路徑和Nginx alias路徑對不上。比如Django項目collectstatic后文件在/app/static/Nginx配置里location /static/ { alias /app/static/; }如果 /app/static/ 下沒有文件自然404。排查方法docker compose exec nginx ls -la /app/static/如果目錄為空回Python容器執(zhí)行靜態(tài)文件收集docker compose exec web python manage.py collectstatic --noinput還有一個常見錯誤alias路徑結(jié)尾的/沒寫導(dǎo)致/static/css/style.css請求被映射到/app/staticcss/style.css路徑拼接錯誤。6.4 容器總是自動重啟又立刻退出配置了restart: always后容器啟動失敗會進入無限重啟循環(huán)。用docker compose ps能看到Restarting狀態(tài)。此時要做的不是急著改代碼而是先關(guān)掉自動重啟讓容器停在該停的地方docker compose stop web然后手動前臺啟動直接看報錯docker compose run --rm web這種方式會把Python應(yīng)用的stdout直接打印到終端所有啟動報錯、語法錯誤、ImportError一目了然。6.5 Python容器啟動時連不上MySQL在Compose的depends_on只能保證容器的啟動順序不能保證MySQL就緒。如果Python應(yīng)用啟動時立刻執(zhí)行連庫操作而MySQL還在初始化就會報Cant connect to MySQL server。我常用的解決方式是在啟動命令前加一個等待腳本用sh -c組合命令實現(xiàn)。Compose里web服務(wù)的命令改成command: sh -c echo Waiting for db... while ! nc -z db 3306; do sleep 1; done echo db is ready gunicorn --bind 0.0.0.0:8000 app:app 如果Python基礎(chǔ)鏡像里沒有nc命令可以用Python實現(xiàn)同樣的等待邏輯command: sh -c python -c \import socket, time; s socket.socket(); while True: try: s.connect((db, 3306)); break except Exception: time.sleep(1)\ gunicorn --bind 0.0.0.0:8000 app:app 這種方式比直接依賴depends_on可靠得多。不過從設(shè)計上考慮更優(yōu)雅的姿勢是應(yīng)用在啟動時做重試邏輯比如Django的連接池和Retry機制但小項目先跑起來更重要。6.6 Windows上Docker Desktop啟動失敗搜索熱詞里好幾個都和這個有關(guān)virtualization support not detected docker desktop failed to start。這個問題本質(zhì)是Windows的虛擬化功能沒開啟。確認路徑任務(wù)管理器 → 性能 → CPU看“虛擬化”是否顯示“已啟用”。如果顯示“已禁用”重啟電腦進BIOS/UEFI設(shè)置找到Intel VT-x或AMD SVM設(shè)為Enabled。重啟后確認Windows功能里Hyper-V和Windows 虛擬機監(jiān)控程序平臺是勾選狀態(tài)。另外Docker Desktop在舊版Windows 10上需要WSL2支持。建議直接去Docker官網(wǎng)下載最新版Docker Desktop安裝包會自動處理WSL2的啟用流程。裝完如果是新裝的系統(tǒng)先重啟一次再啟動Docker Desktop成功率會高很多。6.7 常見問題速查表現(xiàn)象可能原因快速處理502 Bad GatewayPython容器掛了或網(wǎng)絡(luò)不通查看web容器狀態(tài)和日志靜態(tài)資源404alias路徑不對或未執(zhí)行collectstatic檢查掛載路徑并收集靜態(tài)文件80端口被占用其他服務(wù)占用host端口停掉占用服務(wù)或換端口映射容器無限重啟Python啟動即崩潰用docker compose run --rm web前臺查看報錯數(shù)據(jù)庫連接失敗MySQL未就緒或地址寫錯把URL地址改為服務(wù)名db并加等待腳本單文件上傳超過1M報413Nginx默認body限制太小調(diào)大client_max_body_size真實客戶端IP丟失缺少X-Forwarded-For頭檢查proxy_set_header配置6.8 部署完成后還需要做的小事容器全部跑通之后有三件小事容易被忽略但很重要。第一在云控制臺配置安全組時只開放必要的端口。SSH端口22可以改成非默認端口或者限制來源IP數(shù)據(jù)庫端口3306絕不要對外開放。安全組寧可少開不要多開不開端口并不影響Docker內(nèi)部網(wǎng)絡(luò)的通信。第二為Nginx配置基礎(chǔ)安全響應(yīng)頭。在Nginx配置的server塊里加幾行add_header X-Frame-Options SAMEORIGIN always; add_header X-Content-Type-Options nosniff always; add_header Referrer-Policy strict-origin-when-cross-origin always;這些響應(yīng)頭能防點擊劫持、MIME嗅探等基礎(chǔ)Web攻擊。Django項目的話強烈建議把SECURE_PROXY_SSL_HEADER (HTTP_X_FORWARDED_PROTO, https)寫進配置配合Nginx的X-Forwarded-Proto頭讓Django知道當前請求是通過HTTPS來的否則Django會一直認為自己處于不安全連接中可能引發(fā)重定向死循環(huán)。第三確認服務(wù)器的時區(qū)和系統(tǒng)時間準確。容器日志時間如果差8小時排查問題時會非常難受。設(shè)置時區(qū)sudo timedatectl set-timezone Asia/Shanghai容器內(nèi)的時區(qū)如果是UTC可以在Compose的web服務(wù)里加一個環(huán)境變量environment: - TZAsia/Shanghai7. 幾個提高運維效率的小技巧7.1 用別名精簡Docker命令docker compose命令天天敲太長了。在~/.bashrc里加幾個別名alias dcdocker compose alias dcpsdocker compose ps alias dclogdocker compose logs -f alias dcbuilddocker compose up -d --build alias dcedocker compose exec保存后source ~/.bashrc生效。之后dclog web就能查看web服務(wù)日志效率高很多。7.2 容器里改代碼即時生效開發(fā)環(huán)境聯(lián)調(diào)時每次改代碼都要重建鏡像挺痛苦的。如果在Compose的web服務(wù)里掛載了源碼目錄volumes: - .:/app那么修改宿主機代碼后容器內(nèi)部同步變化。配合Gunicorn的--reload參數(shù)代碼改動后自動重啟服務(wù)。這個方案只建議開發(fā)環(huán)境用生產(chǎn)環(huán)境千萬要關(guān)掉否則代碼文件被意外改動會影響線上服務(wù)。7.3 定期清理無用鏡像迭代幾輪之后服務(wù)器上會堆滿舊的鏡像和懸空鏡像。一條命令清理docker system prune -af-a刪除所有未使用的鏡像-f跳過確認。注意它會刪除所有沒有被容器使用的鏡像執(zhí)行前先看一下docker image ls的輸出別誤刪了要用的鏡像。7.4 不要讓Docker容器跑在壞習(xí)慣上有幾個壞習(xí)慣一定要改容器內(nèi)不要用apt install裝一堆東西。容器是臨時的任何手動安裝的包在容器重建后都會丟失。正確做法是把安裝步驟寫進Dockerfile。不要往容器里傳密碼。密鑰、密碼通過環(huán)境變量或密鑰管理服務(wù)傳入不要寫進代碼或鏡像。不要把數(shù)據(jù)庫數(shù)據(jù)放在容器可寫層。MySQL的/var/lib/mysql必須掛載數(shù)據(jù)卷否則容器一刪數(shù)據(jù)全沒了。8. 一次完整的部署實戰(zhàn)記錄從零走一遍完整流程這是我實際部署一個Flask博客應(yīng)用的記錄按這個流程操作基本不會卡殼。第一步本地代碼整理。確認項目結(jié)構(gòu)干凈刪掉虛擬環(huán)境、緩存文件寫出requirements.txt加上.dockerignore。第二步準備服務(wù)器。Ubuntu 22.042核4G。執(zhí)行系統(tǒng)更新安裝Docker和Compose配置鏡像加速器創(chuàng)建普通用戶并加入docker組。第三步上傳代碼。用Git的方式服務(wù)器上git clone項目倉庫。創(chuàng)建一個.env文件寫入數(shù)據(jù)庫密碼、SECRET_KEY等環(huán)境變量。第四步構(gòu)建啟動。執(zhí)行docker compose up -d --build觀察構(gòu)建日志確認依賴安裝成功。構(gòu)建完成后docker compose ps確認三個服務(wù)都在運行。第五步初始化數(shù)據(jù)庫。執(zhí)行docker compose exec web python manage.py migrate確認遷移成功。第六步配置HTTPS。先確保域名解析到服務(wù)器IP然后執(zhí)行certbot --nginx -d example.com按提示完成申請。程序會自動修改Nginx配置并重載。第七步全鏈路驗證。瀏覽器訪問域名確認首頁能打開登錄后臺確認數(shù)據(jù)庫讀寫正常上傳一張圖片確認靜態(tài)文件處理和Nginx body大小配置正常查看docker compose logs web確認沒有報錯。整個過程大概20分鐘前兩次做可能踩坑花一兩個小時熟悉之后速度會快很多。在實際操作中我自己的體會是部署這件事80%的問題都出在“環(huán)境差異”上Docker解決的就是這部分問題但依然有20%的問題出在“配置細節(jié)”上比如網(wǎng)絡(luò)、路徑、權(quán)限這些只能靠經(jīng)驗和日志來積累。所以遇到問題不要慌先看日志再按網(wǎng)絡(luò)通路一層一層排查絕大多數(shù)問題都能定位。如果這篇文章能幫你把第一次部署順利跑通那就算沒白寫。 Docker+Nginx部署Python Web應(yīng)用：從開發(fā)環(huán)境到服務(wù)器的完整指南
把Python Web應(yīng)用從開發(fā)環(huán)境搬到服務(wù)器是很多初學(xué)者邁不過去的一道坎。開發(fā)的時候用Flask自帶服務(wù)器跑得飛起真到了上線這天什么Python版本不一致、依賴裝不上、端口被占用、進程一關(guān)服務(wù)就掛……各種問題全冒出來了。這篇文章要解決的問題就是如何用Docker把Python應(yīng)用打包成標準鏡像配合Nginx做反向代理穩(wěn)定地跑在云服務(wù)器上。這套方案適用于Flask、FastAPI、Django等主流Python Web框架也適用于想要規(guī)范部署流程、減少環(huán)境踩坑的開發(fā)者。我會從方案選型講起再到環(huán)境準備、容器化改造、Nginx配置、完整實操流程和問題排查覆蓋一套可以直接照著做的部署路徑。1. 部署方案總體拆解1.1 為什么選Docker Nginx而不是直接在服務(wù)器上裸跑很多人一開始會想服務(wù)器上直接裝Python然后把代碼clone上去python app.py不就能跑了嗎確實能跑但只適合臨時演示。裸跑會踩這幾個痛點開發(fā)機是Windows或macOS服務(wù)器是Ubuntu或CentOSPython版本、底層依賴庫存在差異本地能啟動的項目服務(wù)器上一跑就報錯。一臺服務(wù)器上如果跑多個Python應(yīng)用依賴之間容易互相沖突。你升了一個庫的版本另一個應(yīng)用掛了排查起來非常頭疼。進程管理是個大坑。用nohup python app.py 方式啟動SSH一斷開、進程崩了、服務(wù)器重啟了服務(wù)就沒了還得手動去拉起。升級回滾困難。代碼改了一版改出問題了想退回上一版裸跑環(huán)境根本沒做版本管理。Docker把這些痛點一網(wǎng)打盡。鏡像就是打包好的運行環(huán)境里面固化了Python版本、依賴庫、啟動命令無論推到哪臺服務(wù)器跑起來的結(jié)果都一樣。容器之間相互隔離多應(yīng)用共存不沖突。鏡像用tag做版本管理回滾只是換一個鏡像標簽的事。配合restart: always策略容器崩了自動拉起服務(wù)器重啟也會自動恢復(fù)。那為什么還要加個Nginx因為Docker解決的是“應(yīng)用怎么跑”的問題Nginx解決的是“流量怎么進”的問題。你的Python容器默認監(jiān)聽某個端口比如8000如果直接用http://服務(wù)器IP:8000訪問會遇到幾個麻煩一是端口暴露得太多如果一個服務(wù)器上跑三個應(yīng)用總不能讓用戶記住三個帶端口的地址二是80/443端口是Web服務(wù)的默認入口讓用戶敲端口訪問非常不專業(yè)三是Nginx能做負載均衡、靜態(tài)文件加速、HTTPS證書終結(jié)這些事性能和安全層面都比直接把Python服務(wù)暴露到公網(wǎng)更靠譜。所以最終架構(gòu)是Nginx在容器里監(jiān)聽80/443端口接收所有外部請求再按規(guī)則轉(zhuǎn)發(fā)到內(nèi)部的Python應(yīng)用容器。1.2 整體架構(gòu)與請求鏈路先看最簡單的一臺服務(wù)器上的部署結(jié)構(gòu)瀏覽器 │ ▼ Nginx 容器監(jiān)聽 80/443 端口 │ proxy_pass 轉(zhuǎn)發(fā)到內(nèi)網(wǎng)地址 ▼ Python 應(yīng)用容器Gunicorn 監(jiān)聽 8000 端口跑 Flask/Django/FastAPI │ ▼ 數(shù)據(jù)庫容器MySQL/PostgreSQL/Redis這里有一個關(guān)鍵點Nginx容器和Python容器應(yīng)該在同一個Docker網(wǎng)絡(luò)中它們之間通過服務(wù)名互相訪問不需要把Python的8000端口暴露到宿主機上。這樣外部流量只能通過Nginx進入安全性和規(guī)范性都更好。我用一個生活化類比來解釋這套架構(gòu)Docker容器就像一個個小房子應(yīng)用在房子里跑有自己的小環(huán)境Nginx是小區(qū)門口的保安亭所有訪客先到保安亭登記保安再告訴訪客去幾棟幾單元。沒有保安亭訪客就得直接跑到每個房子門口敲門既混亂又不安全。這套架構(gòu)說起來簡單但真正落地的時候有很多細節(jié)要注意Docker版本怎么裝、鏡像加速怎么配、Dockerfile怎么寫才科學(xué)、Nginx反代需要設(shè)置哪些請求頭、靜態(tài)文件怎么處理、數(shù)據(jù)庫連接怎么管理等。下面逐個拆解。2. 部署前的服務(wù)器與環(huán)境準備2.1 服務(wù)器選型與基礎(chǔ)初始化部署這套方案服務(wù)器的配置不用太高。個人項目、小流量Web應(yīng)用2核4G的云服務(wù)器完全夠用。操作系統(tǒng)建議選Ubuntu 22.04 LTS或Debian 12這兩者在Docker的支持上最省心社區(qū)資料也多。服務(wù)器到手后先做兩個基礎(chǔ)動作。第一是更新系統(tǒng)軟件包sudo apt update sudo apt upgrade -y第二是創(chuàng)建非root用戶用于日常操作。我一直建議不要直接用root跑業(yè)務(wù)萬一某個操作出錯影響面太大。創(chuàng)建一個叫deploy的用戶并加入sudo組sudo useradd -m -s /bin/bash deploy sudo usermod -aG sudo deploy sudo passwd deploy之后用這個用戶登錄服務(wù)器操作Docker相關(guān)的命令需要加sudo。如果你實在嫌麻煩直接把當前用戶加入docker組可以免sudo執(zhí)行docker命令sudo usermod -aG docker deploy改完組要重新登錄一次才生效。2.2 安裝Docker與Docker ComposeDocker的安裝路徑有兩條一是用官方腳本一把梭二是用apt源安裝。我推薦用官方腳本省事版本也新curl -fsSL https://get.docker.com | bash -s docker安裝完成后驗證一下sudo docker version sudo docker compose version如果你拿到的是舊教程里面寫的是docker-compose帶橫杠命令那是舊版Compose的語法?，F(xiàn)在主流版本是Docker Compose v2直接用docker compose空格調(diào)用。如果系統(tǒng)提示找不到compose命令多半是Docker版本比較老升級一下即可。國內(nèi)服務(wù)器有一個極度影響體驗的問題拉取Docker Hub鏡像慢到懷疑人生。解決辦法是配置鏡像加速器。編輯/etc/docker/daemon.json{ registry-mirrors: [ https://docker.m.daocloud.io, https://dockerproxy.com ] }保存后重啟Dockersudo systemctl restart docker配置完加速器后拉鏡像的速度會明顯提升。這里順帶提一個熱搜里很多人踩的坑在Windows上安裝Docker Desktop時提示virtualization support not detected說明電腦的CPU虛擬化沒有開啟需要進BIOS打開Intel VT-x或AMD SVM。這個細節(jié)在后續(xù)“常見問題”章節(jié)會展開說。2.3 基礎(chǔ)網(wǎng)絡(luò)與端口規(guī)劃部署前先想清楚端口怎么規(guī)劃。通常占用這幾個端口80HTTP入口由Nginx容器占用。443HTTPS入口由Nginx容器占用。3306、6379如果MySQL、Redis也在Docker里跑這些端口通常只對內(nèi)部網(wǎng)絡(luò)開放不需要映射到宿主機。如果為了本地調(diào)試方便要映射建議只綁定到127.0.0.1。怎么理解“只對內(nèi)開放”在做端口映射的時候3306:3306和127.0.0.1:3306:3306的區(qū)別在于前者所有網(wǎng)絡(luò)接口都能訪問相當于把數(shù)據(jù)庫暴露到公網(wǎng)非常危險后者只有服務(wù)器本機localhost能訪問外部請求到不了。云服務(wù)商控制臺的安全組也要放行80、443端口。安全組是云服務(wù)器的第一道防火墻在ECS/CVM控制臺的“安全組”規(guī)則里添加入方向規(guī)則端口填80/443來源填寫0.0.0.0/0。這一步漏了的話服務(wù)器的防火墻無論怎么配外面都訪問不到。3. Python項目容器化改造3.1 代碼層面需要做哪些調(diào)整容器化不是把代碼扔進Docker就完事了有些習(xí)慣得先改過來。第一所有配置必須在代碼外部化。什么是外部化就是DEBUGTrue、SECRET_KEYxxxxx、DATABASE_URLmysql://...這些值不能硬編碼在代碼文件里要從環(huán)境變量讀取。比如Flask項目里配置寫成import os DEBUG os.getenv(DEBUG, false).lower() true SECRET_KEY os.getenv(SECRET_KEY, please-change-me) DATABASE_URL os.getenv(DATABASE_URL, sqlite:///app.db)為什么要這么做因為同一個鏡像可能部署到測試環(huán)境和生產(chǎn)環(huán)境代碼完全一樣只是環(huán)境變量不同。Docker本身就支持在啟動容器時注入環(huán)境變量用環(huán)境變量管理配置是容器化部署的基本功。第二明確Python依賴。項目根目錄放一份requirements.txt盡量鎖定大版本號或精確版本號。別偷懶寫一堆不帶版本號的依賴這次裝和下次裝可能依賴版本就漂移了正好砸中“開發(fā)環(huán)境能跑、線上環(huán)境跑不起來”的老問題。推薦用pip freeze requirements.txt生成當前環(huán)境的依賴列表或者手動整理核心依賴。第三確認Web框架的啟動方式。開發(fā)時用Flask自帶的app.run()或Django的runserver可以生產(chǎn)環(huán)境必須換成異步WSGI服務(wù)器最常用的是Gunicorn。后面會專門講。3.2 編寫一個科學(xué)的Dockerfile以Flask項目為例項目的目錄結(jié)構(gòu)大概是myapp/ ├── app/ │ ├── __init__.py │ └── views.py ├── requirements.txt ├── Dockerfile ├── .dockerignore ├── nginx/ │ └── default.conf └── docker-compose.ymlDockerfile的內(nèi)容FROM python:3.11-slim WORKDIR /app ENV PYTHONDONTWRITEBYTECODE1 \ PYTHONUNBUFFERED1 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple COPY . . EXPOSE 8000 CMD [gunicorn, --bind, 0.0.0.0:8000, --workers, 3, app:app]逐行解釋一下關(guān)鍵點python:3.11-slimslim版本體積小包含運行Python所需的最小環(huán)境。盡量別用帶-alpine的版本雖然體積更小但某些依賴庫需要編譯容易出問題。PYTHONDONTWRITEBYTECODE1不生成__pycache__減少鏡像里的垃圾文件。PYTHONUNBUFFERED1日志不緩沖實時輸出到標準輸出方便用docker logs看日志。pip install -i https://pypi.tuna.tsinghua.edu.cn/simple國內(nèi)服務(wù)器裝PyPI依賴用清華鏡像速度差距非常大不用鏡像可能等十幾分鐘用了鏡像一分鐘內(nèi)裝完。CMD里用的是Gunicorn而不是python app.py。Gunicorn是多進程WSGI服務(wù)器能利用多核CPU并發(fā)能力遠超開發(fā)服務(wù)器。--workers 3表示開3個工作進程一般按“CPU核心數(shù) × 2 1”估算。如果服務(wù)器是2核5個worker比較合適我這里寫3是為了保守看實際內(nèi)存調(diào)整。另外.dockerignore文件很容易被忽略但非常重要。它的作用是告訴Docker哪些文件不要進入鏡像構(gòu)建上下文。最小內(nèi)容__pycache__/ *.pyc .git/ .env venv/沒有.dockerignoreCOPY . .會把你本地的虛擬環(huán)境、git目錄、日志文件全打進去鏡像又大又慢。3.3 靜態(tài)文件與運行用戶Django項目會用到collectstatic收集靜態(tài)文件Flask項目如果有獨立的前端資源也一樣默認由Python處理。但在生產(chǎn)環(huán)境更好的方案是讓Nginx直接處理靜態(tài)文件不要經(jīng)過Python應(yīng)用。這樣Python容器專注于動態(tài)請求靜態(tài)資源響應(yīng)速度也更快。具體操作是Nginx容器里掛載一份靜態(tài)文件目錄配置里用alias或root指向它。后面Nginx配置部分會給出完整寫法。那靜態(tài)文件怎么進到Nginx容器里的兩個思路一是構(gòu)建時在Nginx鏡像里COPY進去二是用Docker的數(shù)據(jù)卷把宿主機目錄共享給兩個容器。我常用的是后者在Compose里把宿主機的static/目錄同時掛載給Python容器和Nginx容器。還有一個安全細節(jié)容器內(nèi)默認是root用戶跑應(yīng)用如果鏡像被打包分發(fā)root權(quán)限會有安全風(fēng)險?？梢栽贒ockerfile里創(chuàng)建非root用戶并切換RUN addgroup --system app adduser --system --ingroup app app USER app注意如果用了這個配置容器內(nèi)寫文件比如Django的media上傳目錄所在的數(shù)據(jù)卷必須給app用戶寫權(quán)限否則會報Permission denied。3.4 docker-compose.yml 編排三件套docker-compose.yml是整套部署的中樞。我個人習(xí)慣把Nginx、Python應(yīng)用、數(shù)據(jù)庫放到同一個Compose文件里管理用服務(wù)名互相訪問主機映射只暴露Nginx的80端口和數(shù)據(jù)庫的本地端口。一個最簡但完整的編排文件services: web: build: . restart: always env_file: - .env volumes: - static_volume:/app/static expose: - 8000 depends_on: - db nginx: image: nginx:1.25-alpine restart: always ports: - 80:80 volumes: - ./nginx/default.conf:/etc/nginx/conf.d/default.conf - static_volume:/app/static depends_on: - web db: image: mysql:8.0 restart: always env_file: - .env volumes: - mysql_data:/var/lib/mysql expose: - 3306 volumes: static_volume: mysql_data:逐個解釋這里面的設(shè)計意圖web服務(wù)用的是build: .也就是用當前目錄的Dockerfile構(gòu)建鏡像。expose和ports的區(qū)別要分清。expose只在Docker內(nèi)部網(wǎng)絡(luò)中暴露端口宿主機和外部訪問不到ports才會把端口映射到宿主機。web服務(wù)的8000端口只需要讓Nginx容器通過內(nèi)部網(wǎng)絡(luò)訪問所以用expose不用映射到宿主機。nginx服務(wù)把本機的./nginx/default.conf掛載到容器內(nèi)的Nginx配置目錄改配置不用重新構(gòu)建鏡像改完docker compose restart nginx就生效。env_file: .env將環(huán)境變量從文件加載進容器數(shù)據(jù)庫密碼、SECRET_KEY這類敏感信息都放在.env里不進倉庫。depends_on保證啟動順序。但要注意它只保證“先啟動”不保證“可用”。MySQL容器啟動到真正能接受連接還有幾秒到幾十秒的初始化時間Python應(yīng)用如果啟動時立即連數(shù)據(jù)庫可能連不上。這個問題在后面的“常見問題”章節(jié)會提供一個解決方案。.env文件示例SECRET_KEYyour-secret-key DATABASE_URLmysql://myapp:myapp123db:3306/myapp MYSQL_ROOT_PASSWORDroot123 MYSQL_DATABASEmyapp MYSQL_USERmyapp MYSQL_PASSWORDmyapp123有一個地方容易出錯DATABASE_URL里數(shù)據(jù)庫地址寫的是db而不是127.0.0.1。因為在Compose網(wǎng)絡(luò)中服務(wù)名db會被DNS解析到MySQL容器的IP地址。如果你寫成127.0.0.1Python容器訪問的是它自己的回環(huán)地址里面并沒有MySQL在監(jiān)聽必然連接失敗。4. Nginx反向代理配置詳解4.1 反向代理到底在做什么先搞清楚正向代理和反向代理的區(qū)別。正向代理是“替客戶端訪問服務(wù)器”客戶端知道代理的存在訪問被限制的資源時找代理幫忙比如常見的開發(fā)調(diào)試代理。反向代理是“替服務(wù)器接收請求”客戶端不知道代理的存在它訪問的是NginxNginx再轉(zhuǎn)發(fā)給后面的應(yīng)用服務(wù)器。在部署場景里Nginx做的是反向代理。用戶訪問http://你的域名請求到達NginxNginx根據(jù)配置把請求轉(zhuǎn)發(fā)給內(nèi)部網(wǎng)絡(luò)里的Python容器。等Python返回響應(yīng)Nginx再轉(zhuǎn)回給用戶。這個過程對用戶完全透明。加一層Nginx帶來的實際收益有三個統(tǒng)一入口。多個Python應(yīng)用可以共用一個80/443端口用不同域名或不同路徑區(qū)分。安全緩沖。Python應(yīng)用不需要直接暴露公網(wǎng)端口減少被掃描和攻擊的面。性能提升。Nginx的靜態(tài)文件處理能力和并發(fā)連接能力遠強于Python應(yīng)用服務(wù)器靜態(tài)資源交給Nginx能顯著降低應(yīng)用壓力。4.2 一份完整的Nginx站點配置在項目目錄下創(chuàng)建nginx/default.confupstream myapp { server web:8000; } server { listen 80; server_name example.com www.example.com; client_max_body_size 20M; location /static/ { alias /app/static/; expires 7d; access_log off; } location / { proxy_pass http://myapp; 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_connect_timeout 60s; proxy_read_timeout 60s; } }關(guān)鍵點拆解upstream myapp { server web:8000; }定義了上游應(yīng)用服務(wù)器池web是Compose里Python服務(wù)的名稱。如果以后擴展成多實例可以在這里加多行server實現(xiàn)負載均衡。location /static/靜態(tài)文件請求由Nginx直接處理alias /app/static/指向Nginx容器內(nèi)掛載的靜態(tài)文件目錄注意alias后面必須有/。expires 7d給靜態(tài)資源加7天瀏覽器緩存降低服務(wù)器壓力。加了access_log off避免靜態(tài)資源請求刷屏日志。location /其余請求全轉(zhuǎn)發(fā)到Python應(yīng)用。proxy_set_header這幾行必不可少特別是X-Forwarded-For如果缺了它Django/Flask拿到的客戶端IP全是Nginx容器的IP日志里的真實訪客IP就丟了。client_max_body_size 20M允許上傳的最大請求體大小。默認值只有1M如果應(yīng)用有文件上傳功能不調(diào)大會直接413錯誤。關(guān)于proxy_pass http://myapp和proxy_pass http://web:8000的區(qū)別兩種寫法都能用。用upstream的好處是后期可以在Nginx層做更靈活的負載均衡策略比如加權(quán)重、加健康檢查。簡單場景下直接在proxy_pass里寫http://web:8000也行。4.3 啟用HTTPS證書沒有HTTPS現(xiàn)代瀏覽器地址欄會提示不安全而且HTTP明文傳輸時密碼、Cookie都能被截獲。部署完成后強烈建議上HTTPS。最省事的方案是用Certbot自動申請和續(xù)期Let‘s Encrypt免費證書。安裝Certbotsudo apt install certbot python3-certbot-nginx然后執(zhí)行sudo certbot --nginx -d example.com -d www.example.comCertbot會自動識別Nginx配置、自動申請證書、自動改寫配置文件加入SSL相關(guān)設(shè)置還會自動配置HTTP跳轉(zhuǎn)HTTPS。證書90天有效期Certbot會通過systemd定時任務(wù)自動續(xù)期基本不用手動管。如果你用的是云廠商的免費證書流程是去云控制臺申請證書 → 下載Nginx版證書文件 → 上傳到服務(wù)器 → 手動改Nginx配置。手動配置的關(guān)鍵片段server { listen 443 ssl; server_name example.com; ssl_certificate /etc/nginx/ssl/example.com.pem; ssl_certificate_key /etc/nginx/ssl/example.com.key; # 其余配置同HTTP版 } server { listen 80; server_name example.com; return 301 https://$host$request_uri; }注意容器里的Nginx需要把證書文件也掛載進去在Compose的nginx服務(wù)里加一行volumes: - /etc/nginx/ssl:/etc/nginx/ssl:ro5. 完整實操部署流程5.1 代碼上傳與目錄規(guī)劃先把項目代碼傳到服務(wù)器。最推薦的方式是用Git在服務(wù)器上直接clone倉庫。如果項目是私有的需要配置SSH key或者在服務(wù)器上使用帶token的clone地址。沒有Git倉庫的話用scp從本地傳到服務(wù)器也行scp -r ./myapp deploy服務(wù)器IP:/home/deploy/www/傳到服務(wù)器后目錄結(jié)構(gòu)應(yīng)該是/home/deploy/www/myapp/ ├── app/ ├── requirements.txt ├── Dockerfile ├── .dockerignore ├── .env ├── nginx/ │ └── default.conf └── docker-compose.yml注意.env文件里有數(shù)據(jù)庫密碼和SECRET_KEY千萬不要把這個文件提交到Git倉庫。我見過太多把密鑰提交進倉庫導(dǎo)致被爬蟲掃出數(shù)據(jù)庫密碼的案例。建議在Git倉庫中忽略.env傳到服務(wù)器后手動創(chuàng)建。5.2 構(gòu)建并啟動容器進入項目目錄先檢查配置文件語法有沒有問題cd /home/deploy/www/myapp docker compose config這個命令會解析Compose文件并輸出最終的解析結(jié)果。如果報錯說明YAML格式有問題或者服務(wù)定義有誤先修好再往下走。然后構(gòu)建并啟動docker compose up -d --build-d表示后臺運行--build表示構(gòu)建鏡像后啟動。第一次構(gòu)建會比較慢因為要拉基礎(chǔ)鏡像、裝依賴。耐心等待構(gòu)建完成后查看容器狀態(tài)docker compose ps如果所有服務(wù)的狀態(tài)都是Up說明容器已經(jīng)跑起來了。此時在服務(wù)器本地用curl測試一下curl -I http://127.0.0.1如果返回HTTP/1.1 200 OK說明Nginx已經(jīng)正常響應(yīng)。再用完整域名從本地瀏覽器訪問看頁面是否正常。數(shù)據(jù)庫遷移也需要執(zhí)行一次。Django項目docker compose exec web python manage.py migrateFlask項目如果有初始化表結(jié)構(gòu)的命令同理用docker compose exec web進入容器執(zhí)行。5.3 查看日志與排錯容器跑起來了不代表一切正常。查看所有服務(wù)的日志docker compose logs -f只看某個服務(wù)的日志docker compose logs -f web日志是最直接的排錯入口。Python應(yīng)用啟動報錯了、數(shù)據(jù)庫連接失敗了、Nginx轉(zhuǎn)發(fā)超時了都會反映在日志里。日志默認是彩色的-f參數(shù)是持續(xù)跟蹤新日志輸出。生產(chǎn)環(huán)境我一般會把日志接入到集中式日志平臺但個人項目直接用docker compose logs就夠了。5.4 更新與發(fā)布新版本代碼改了要上線最常規(guī)的操作是git pull docker compose up -d --build流程是拉取最新代碼 → 重新構(gòu)建鏡像 → 優(yōu)雅替換容器。Gunicorn默認支持優(yōu)雅重啟正在處理的請求會處理完才結(jié)束進程不會出現(xiàn)請求中斷。如果想零停機更新可以配置deploy.rollback_config或其他藍綠發(fā)布方案但個人項目用上面的簡單方案已經(jīng)足夠穩(wěn)。5.5 數(shù)據(jù)持久化與備份驗證Compose文件里已經(jīng)為MySQL配置了數(shù)據(jù)卷mysql_data數(shù)據(jù)庫數(shù)據(jù)存放在卷里容器刪了重建數(shù)據(jù)不會丟。但這不等于萬事大吉卷里的數(shù)據(jù)如果服務(wù)器磁盤壞了同樣會丟。建議定期備份MySQL數(shù)據(jù)docker compose exec db mysqldump -u root -p myapp backup_$(date %F).sql可以把這條命令加到crontab里每天凌晨備份一次備份文件保留最近7天?；謴?fù)的時候cat backup_2025-01-01.sql | docker compose exec -T db mysql -u root -p myapp一定要親手驗證一次備份文件能正?；謴?fù)。我見過太多人配置了定時備份結(jié)果因為密碼寫錯、命令路徑不對備份文件全是0字節(jié)真正出事的時候才發(fā)現(xiàn)根本沒備份成功。6. 常見問題與排查技巧實錄6.1 502 Bad Gateway這是Nginx部署中最常見的錯誤意思是Nginx無法連接到上游的Python應(yīng)用。排查思路按順序走看web容器是否還在運行docker compose ps如果顯示Exit說明Python應(yīng)用啟動失敗進web容器日志找原因docker compose logs web。確認web容器內(nèi)部端口是否監(jiān)聽了docker compose exec web curl -I http://127.0.0.1:8000。如果容器里沒有curl可以用Python代替docker compose exec web python -c import urllib.request; print(urllib.request.urlopen(http://127.0.0.1:8000).status)。確認Nginx的upstream配置里的服務(wù)名與Compose服務(wù)名一致。配置里寫的是server web:8000Compose服務(wù)名必須是web如果寫錯了或者忘了在同一個網(wǎng)絡(luò)里就會502。確認Nginx配置沒有語法問題docker compose exec nginx nginx -t。多數(shù)情況下問題出在Python應(yīng)用啟動失敗導(dǎo)致容器退出日志里會明確提示是缺依賴、端口被占用還是代碼報錯。6.2 同端口沖突服務(wù)器上已經(jīng)有服務(wù)占用80新部署一個項目啟動Nginx容器時報bind: address already in use說明宿主機80端口已經(jīng)被占用了。這種現(xiàn)象很常見之前用裸機部署過Nginx的、服務(wù)器面板自帶Web服務(wù)的都會占80端口。處理辦法是先看看誰占了端口sudo lsof -i :80如果是系統(tǒng)自帶的Apache或老版本Nginx停掉并禁用開機啟動sudo systemctl stop apache2 sudo systemctl disable apache2如果是另一個Docker容器占用了80端口需要檢查那個容器的端口映射配置改掉其中一個。6.3 靜態(tài)文件全部404頁面能打開但樣式全丟F12看到靜態(tài)資源返回404。核心原因是靜態(tài)文件掛載路徑和Nginx alias路徑對不上。比如Django項目collectstatic后文件在/app/static/Nginx配置里location /static/ { alias /app/static/; }如果 /app/static/ 下沒有文件自然404。排查方法docker compose exec nginx ls -la /app/static/如果目錄為空回Python容器執(zhí)行靜態(tài)文件收集docker compose exec web python manage.py collectstatic --noinput還有一個常見錯誤alias路徑結(jié)尾的/沒寫導(dǎo)致/static/css/style.css請求被映射到/app/staticcss/style.css路徑拼接錯誤。6.4 容器總是自動重啟又立刻退出配置了restart: always后容器啟動失敗會進入無限重啟循環(huán)。用docker compose ps能看到Restarting狀態(tài)。此時要做的不是急著改代碼而是先關(guān)掉自動重啟讓容器停在該停的地方docker compose stop web然后手動前臺啟動直接看報錯docker compose run --rm web這種方式會把Python應(yīng)用的stdout直接打印到終端所有啟動報錯、語法錯誤、ImportError一目了然。6.5 Python容器啟動時連不上MySQL在Compose的depends_on只能保證容器的啟動順序不能保證MySQL就緒。如果Python應(yīng)用啟動時立刻執(zhí)行連庫操作而MySQL還在初始化就會報Cant connect to MySQL server。我常用的解決方式是在啟動命令前加一個等待腳本用sh -c組合命令實現(xiàn)。Compose里web服務(wù)的命令改成command: sh -c echo Waiting for db... while ! nc -z db 3306; do sleep 1; done echo db is ready gunicorn --bind 0.0.0.0:8000 app:app 如果Python基礎(chǔ)鏡像里沒有nc命令可以用Python實現(xiàn)同樣的等待邏輯command: sh -c python -c \import socket, time; s socket.socket(); while True: try: s.connect((db, 3306)); break except Exception: time.sleep(1)\ gunicorn --bind 0.0.0.0:8000 app:app 這種方式比直接依賴depends_on可靠得多。不過從設(shè)計上考慮更優(yōu)雅的姿勢是應(yīng)用在啟動時做重試邏輯比如Django的連接池和Retry機制但小項目先跑起來更重要。6.6 Windows上Docker Desktop啟動失敗搜索熱詞里好幾個都和這個有關(guān)virtualization support not detected docker desktop failed to start。這個問題本質(zhì)是Windows的虛擬化功能沒開啟。確認路徑任務(wù)管理器 → 性能 → CPU看“虛擬化”是否顯示“已啟用”。如果顯示“已禁用”重啟電腦進BIOS/UEFI設(shè)置找到Intel VT-x或AMD SVM設(shè)為Enabled。重啟后確認Windows功能里Hyper-V和Windows 虛擬機監(jiān)控程序平臺是勾選狀態(tài)。另外Docker Desktop在舊版Windows 10上需要WSL2支持。建議直接去Docker官網(wǎng)下載最新版Docker Desktop安裝包會自動處理WSL2的啟用流程。裝完如果是新裝的系統(tǒng)先重啟一次再啟動Docker Desktop成功率會高很多。6.7 常見問題速查表現(xiàn)象可能原因快速處理502 Bad GatewayPython容器掛了或網(wǎng)絡(luò)不通查看web容器狀態(tài)和日志靜態(tài)資源404alias路徑不對或未執(zhí)行collectstatic檢查掛載路徑并收集靜態(tài)文件80端口被占用其他服務(wù)占用host端口停掉占用服務(wù)或換端口映射容器無限重啟Python啟動即崩潰用docker compose run --rm web前臺查看報錯數(shù)據(jù)庫連接失敗MySQL未就緒或地址寫錯把URL地址改為服務(wù)名db并加等待腳本單文件上傳超過1M報413Nginx默認body限制太小調(diào)大client_max_body_size真實客戶端IP丟失缺少X-Forwarded-For頭檢查proxy_set_header配置6.8 部署完成后還需要做的小事容器全部跑通之后有三件小事容易被忽略但很重要。第一在云控制臺配置安全組時只開放必要的端口。SSH端口22可以改成非默認端口或者限制來源IP數(shù)據(jù)庫端口3306絕不要對外開放。安全組寧可少開不要多開不開端口并不影響Docker內(nèi)部網(wǎng)絡(luò)的通信。第二為Nginx配置基礎(chǔ)安全響應(yīng)頭。在Nginx配置的server塊里加幾行add_header X-Frame-Options SAMEORIGIN always; add_header X-Content-Type-Options nosniff always; add_header Referrer-Policy strict-origin-when-cross-origin always;這些響應(yīng)頭能防點擊劫持、MIME嗅探等基礎(chǔ)Web攻擊。Django項目的話強烈建議把SECURE_PROXY_SSL_HEADER (HTTP_X_FORWARDED_PROTO, https)寫進配置配合Nginx的X-Forwarded-Proto頭讓Django知道當前請求是通過HTTPS來的否則Django會一直認為自己處于不安全連接中可能引發(fā)重定向死循環(huán)。第三確認服務(wù)器的時區(qū)和系統(tǒng)時間準確。容器日志時間如果差8小時排查問題時會非常難受。設(shè)置時區(qū)sudo timedatectl set-timezone Asia/Shanghai容器內(nèi)的時區(qū)如果是UTC可以在Compose的web服務(wù)里加一個環(huán)境變量environment: - TZAsia/Shanghai7. 幾個提高運維效率的小技巧7.1 用別名精簡Docker命令docker compose命令天天敲太長了。在~/.bashrc里加幾個別名alias dcdocker compose alias dcpsdocker compose ps alias dclogdocker compose logs -f alias dcbuilddocker compose up -d --build alias dcedocker compose exec保存后source ~/.bashrc生效。之后dclog web就能查看web服務(wù)日志效率高很多。7.2 容器里改代碼即時生效開發(fā)環(huán)境聯(lián)調(diào)時每次改代碼都要重建鏡像挺痛苦的。如果在Compose的web服務(wù)里掛載了源碼目錄volumes: - .:/app那么修改宿主機代碼后容器內(nèi)部同步變化。配合Gunicorn的--reload參數(shù)代碼改動后自動重啟服務(wù)。這個方案只建議開發(fā)環(huán)境用生產(chǎn)環(huán)境千萬要關(guān)掉否則代碼文件被意外改動會影響線上服務(wù)。7.3 定期清理無用鏡像迭代幾輪之后服務(wù)器上會堆滿舊的鏡像和懸空鏡像。一條命令清理docker system prune -af-a刪除所有未使用的鏡像-f跳過確認。注意它會刪除所有沒有被容器使用的鏡像執(zhí)行前先看一下docker image ls的輸出別誤刪了要用的鏡像。7.4 不要讓Docker容器跑在壞習(xí)慣上有幾個壞習(xí)慣一定要改容器內(nèi)不要用apt install裝一堆東西。容器是臨時的任何手動安裝的包在容器重建后都會丟失。正確做法是把安裝步驟寫進Dockerfile。不要往容器里傳密碼。密鑰、密碼通過環(huán)境變量或密鑰管理服務(wù)傳入不要寫進代碼或鏡像。不要把數(shù)據(jù)庫數(shù)據(jù)放在容器可寫層。MySQL的/var/lib/mysql必須掛載數(shù)據(jù)卷否則容器一刪數(shù)據(jù)全沒了。8. 一次完整的部署實戰(zhàn)記錄從零走一遍完整流程這是我實際部署一個Flask博客應(yīng)用的記錄按這個流程操作基本不會卡殼。第一步本地代碼整理。確認項目結(jié)構(gòu)干凈刪掉虛擬環(huán)境、緩存文件寫出requirements.txt加上.dockerignore。第二步準備服務(wù)器。Ubuntu 22.042核4G。執(zhí)行系統(tǒng)更新安裝Docker和Compose配置鏡像加速器創(chuàng)建普通用戶并加入docker組。第三步上傳代碼。用Git的方式服務(wù)器上git clone項目倉庫。創(chuàng)建一個.env文件寫入數(shù)據(jù)庫密碼、SECRET_KEY等環(huán)境變量。第四步構(gòu)建啟動。執(zhí)行docker compose up -d --build觀察構(gòu)建日志確認依賴安裝成功。構(gòu)建完成后docker compose ps確認三個服務(wù)都在運行。第五步初始化數(shù)據(jù)庫。執(zhí)行docker compose exec web python manage.py migrate確認遷移成功。第六步配置HTTPS。先確保域名解析到服務(wù)器IP然后執(zhí)行certbot --nginx -d example.com按提示完成申請。程序會自動修改Nginx配置并重載。第七步全鏈路驗證。瀏覽器訪問域名確認首頁能打開登錄后臺確認數(shù)據(jù)庫讀寫正常上傳一張圖片確認靜態(tài)文件處理和Nginx body大小配置正常查看docker compose logs web確認沒有報錯。整個過程大概20分鐘前兩次做可能踩坑花一兩個小時熟悉之后速度會快很多。在實際操作中我自己的體會是部署這件事80%的問題都出在“環(huán)境差異”上Docker解決的就是這部分問題但依然有20%的問題出在“配置細節(jié)”上比如網(wǎng)絡(luò)、路徑、權(quán)限這些只能靠經(jīng)驗和日志來積累。所以遇到問題不要慌先看日志再按網(wǎng)絡(luò)通路一層一層排查絕大多數(shù)問題都能定位。如果這篇文章能幫你把第一次部署順利跑通那就算沒白寫。