用 Docker Compose 一次跑起 Python + PostgreSQL 開發環境:新手避坑筆記
剛學 Python 後端時,很多人第一個卡關不是寫程式,而是「環境裝不起來」:本機 Python 版本不合、PostgreSQL 裝了卻連不上、換一部電腦又要重裝一次。Docker Compose 正是為了解決這個痛點而生:用一個 docker-compose.yml,把應用程式與資料庫寫成一份可以重複執行的說明書,任何人一條指令就能跑起同一套環境。本文用一個最小範例,帶你走通第一次部署,並避開三個新手最常踩的坑。
一、最小可用範例:兩行指令跑起服務
先在專案目錄建立 docker-compose.yml,定義 web 與 db 兩個服務:
services:
web:
build: .
ports:
- "8000:8000"
environment:
- DATABASE_URL=postgresql://app:secret@db:5432/appdb
depends_on:
db:
condition: service_healthy
db:
image: postgres:16
environment:
- POSTGRES_USER=app
- POSTGRES_PASSWORD=secret
- POSTGRES_DB=appdb
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app"]
interval: 5s
timeout: 3s
retries: 5
volumes:
pgdata:
接著執行 docker compose up -d --build,再用 docker compose ps 與 docker compose logs -f web 確認服務狀態。能看到 log 順利輸出,就代表環境已經跑起來了。
二、新手最常踩的三個坑
第一,服務還沒準備好就連線。容器狀態是 running,不代表資料庫已經可以接受連線,程式一啟動就連線失敗是很常見的情況。上面範例用 depends_on 搭配 healthcheck,讓 web 等 db 真正就緒才啟動,比單純寫 depends_on 可靠得多。
第二,重啟後資料消失。沒有掛載 volume 的資料庫,容器刪掉資料就跟著消失。範例把 pgdata 命名卷掛到資料目錄,docker compose down 不會清掉資料;但 docker compose down -v 會連卷一起刪除,開發測試時下指令前要先看清楚。
第三,把密碼寫死在設定檔。帳號密碼應該放在 .env 檔案,並把 .env 加入 .gitignore,不要提交到程式碼倉庫。docker-compose.yml 內則用 ${POSTGRES_PASSWORD} 這類變數引用,換環境時只要改 .env,不用改設定檔,也避免金鑰外洩。
三、日常開發的四個常用指令
docker compose up -d 是背景啟動;docker compose logs -f web 是持續看指定服務的 log;docker compose exec db psql -U app -d appdb 可以直接進入資料庫檢查資料表;docker compose down 是停止並移除容器。Linux 上若遇到權限問題,先確認目前帳號是否在 docker 群組,再用 id 與 groups 檢查,不要習慣性全程用 sudo。
四、搭配 AI 工具加速,但要自己驗證
現在不少 AI 助手可以直接幫你生成 docker-compose.yml 或 Dockerfile,入門時確實省下很多查文件的時間。建議流程是:先講清楚需求,例如 Python 版本、資料庫版本與對外埠口,再請 AI 產出設定檔,最後自己逐行檢查 image 版本、volume 掛載與環境變數。AI 寫的設定檔偶爾會用舊版語法或不存在的參數,照單全收就很容易在部署時出錯。
結語
Docker Compose 的核心價值不是「把東西裝進容器」,而是「把環境寫成文件」。一份可以版本控管、可以重複執行的 docker-compose.yml,讓本機、測試機與同事的電腦跑的是同一套環境,出問題時也可以用同一份設定重現與除錯。先從今天的最小範例開始,跑通一次、故意踩一次坑,再把修正寫回設定檔,就是最快的入門方法。
- 点赞
- 收藏
- 关注作者
评论(0)