Docker 化:把求職助理與 PostgreSQL 放進可重建的環境¶
摘要¶
本機裝了 psycopg,容器卻出現 ModuleNotFoundError,原因通常是兩個 Python 環境不同。Image 封裝檔案與依賴,container 才是實際執行的程序環境。本章把已接 PostgreSQL 的 API包進 image,以 Compose 啟動 app 與 postgres。
完成後能解釋 Dockerfile 每一行、區分 host 與容器網路、保存資料、執行 migration,並依 log 判斷啟動失敗的位置。資料基準:2026-10-22。使用 Docker Compose plugin 的 docker compose 指令,不依賴舊版 docker-compose 或頂層 version: 欄位。
Image 不等於正在執行的 container¶
docker pull 只下載 image。docker run 由 image 建立 container 並啟動主程序;主程序結束,container 就停止。停止後仍可查看 log 與 exit code,直到 container 被刪除。Image layers 固定,但 tag 可以重新指向另一個 image;python:3.12-slim 仍會隨修補版本更新。需要精確重現時記錄 image digest,並定期更新與重驗,不是永遠停在舊 image。
Linux container 共用 Linux kernel;Docker Desktop 透過 Linux VM 提供這層環境,並非每個 container 都有自己的完整作業系統核心。CPU 架構、秘密、外部 DB 與網路仍需另外確認。
docker version
docker compose version
docker pull python:3.12-slim
docker image ls
docker run --rm python:3.12-slim python --version
最後一行執行完就退出,這是正常行為;--rm 會自動移除該次 container。參考 Docker container 概念。
先做能讀取 PORT 的啟動器¶
新增 app/start.py,供本機 container 與下一章平台部署共用:
import os
import uvicorn
if __name__ == "__main__":
uvicorn.run("app.main:app", host="0.0.0.0", port=int(os.getenv("PORT", "8000")))
0.0.0.0 表示監聽容器內所有介面;它不是給瀏覽器連線的目的地址。容器內若只綁 127.0.0.1,即使做 port mapping,外面仍連不到。正式執行不帶 --reload。
新增 .dockerignore,避免把開發環境、Git 歷史與秘密送進 build context:
新增 Dockerfile:
FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
WORKDIR /app
COPY requirements.txt ./requirements.txt
RUN python -m pip install --no-cache-dir -r requirements.txt
RUN groupadd --system app && useradd --system --gid app --home-dir /app app
COPY --chown=app:app app ./app
COPY --chown=app:app migrations ./migrations
COPY --chown=app:app alembic.ini ./alembic.ini
USER app
EXPOSE 8000
CMD ["python", "-m", "app.start"]
| 指令 | 用途與邊界 |
|---|---|
FROM |
選定 Python 3.12 的 slim 基礎檔案環境;不是最新版本宣告 |
ENV |
不寫 pyc、讓 stdout/stderr 即時輸出;不放秘密 |
WORKDIR |
後續相對路徑與啟動目錄固定為 /app |
第一個 COPY |
只先複製依賴檔,讓程式改動較容易重用安裝快取 |
RUN pip install |
在 build 階段安裝到 image;host 的 venv 不會帶入 |
RUN groupadd... |
建立專用系統帳號;此行在 build 時仍以 root 執行 |
後續 COPY |
僅帶入執行與 migration 所需內容,包含 SQL revision 檔 |
USER |
runtime 用非 root 帳號 |
EXPOSE |
記錄預期 port,不會替 host 開 port,也不會改 Uvicorn port |
CMD |
以 exec form 執行主程序;Python 啟動器讀 runtime 的 PORT |
CMD ["uvicorn", "...", "--port", "$PORT"] 不會展開環境變數,因為 exec form 沒有 shell。這裡讓 Python 自己讀環境,避免把 shell 字串處理混進啟動流程。詳見 Dockerfile reference。
requirements.txt 是第四章安裝後產生的版本快照,包含 psycopg binary wheel。若在與 image 不同的平台產生,仍需在目標 image 實際 build 與測試;不應盲目把已汙染的全域環境 freeze 進來。此入門 image 也包含教學測試依賴,之後確有體積需求再拆 runtime/dev 依賴。
Compose:兩個 service、一個持久化 volume¶
新增 .env.example,只放本機教學值;這些已公開的示範值不能用於部署:
本機複製後自行換成長隨機值;教學 DB password 請先用 URL-safe 的字母與數字,因為下面會把它插入連線 URL:
新增 compose.yaml:
name: job-assistant
services:
postgres:
image: postgres:17
environment:
POSTGRES_USER: job_assistant
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
POSTGRES_DB: job_assistant
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U job_assistant -d job_assistant"]
interval: 5s
timeout: 3s
retries: 12
restart: unless-stopped
app:
build: .
image: job-assistant:local
environment:
DATABASE_URL: postgresql+psycopg://job_assistant:${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}@postgres:5432/job_assistant
APP_API_KEY: ${APP_API_KEY:?set APP_API_KEY}
PORT: "8000"
CORS_ORIGINS: ""
ports:
- "127.0.0.1:8000:8000"
depends_on:
postgres:
condition: service_healthy
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/ready', timeout=3).close()"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
restart: unless-stopped
volumes:
pgdata:
Compose 自動建網路,app 用 service name postgres 找 DB;app 的 localhost 是 app 自己。兩個容器互連用容器 port 5432,不需把 DB port 發布到 host。host 呼叫 API 則用 127.0.0.1:8000,映射只綁本機,適合練習。參考 Compose networking。
若第四章尚未有本機 PostgreSQL,可暫時替 postgres 加 ports: ["127.0.0.1:5432:5432"],只啟動 postgres,讓 host 上的 Python 用 127.0.0.1:5432 連它;若該 port 已被占用,就映射 5433:5432 並同步改 host URL。回到全容器模式後移除 DB 的 port 映射。
.env 供 Compose 插值,並不自動把所有欄位放進 container;environment 明確傳遞指定值。shell 中同名變數可能覆蓋 .env,從上一章留下的 DATABASE_URL 不會改掉此處明寫的容器 URL,但 APP_API_KEY、POSTGRES_PASSWORD 會影響插值。必要時先 unset APP_API_KEY POSTGRES_PASSWORD,再以 .env 為準。不要分享 docker compose config 的完整展開內容,裡面可能有秘密。參考 Compose environment variables。
這裡用環境變數簡化本機教學;可讀 Docker 管理介面的人仍可能查看它們。正式服務要用平台秘密管理與權限控管;Docker build 的 ARG/ENV、image layer 都不適合保存秘密。
volume 路徑固定對應 PostgreSQL 17 的 image;PostgreSQL 18 以後官方 image 的資料路徑安排有變,不要只換 tag 就沿用這份設定。初始化帳密只在空資料目錄生效;改 .env 不會替既有 DB 改密碼。詳見 Postgres official image。
分開 build、migration 與啟動¶
先停止 host 上的 Uvicorn,避免 port 8000 衝突,再執行:
docker compose build app
docker compose up -d postgres
docker compose ps
docker compose run --rm app python -m alembic upgrade head
docker compose up -d app
docker compose ps
curl -i http://127.0.0.1:8000/ready
docker compose logs --tail=50 app
等 postgres 顯示 healthy 再做 migration;若仍在初始化,先檢查 postgres logs,完成後再執行。depends_on 一般只控制啟動順序,加 service_healthy 才等待 healthcheck;它不保證 DB 以後永不斷線,也不會在 DB 重新啟動時自動替應用重試所有 SQL。參考 Compose startup order。
docker compose run --rm app ... 使用 app 的 image/環境,覆寫其 CMD,完成後刪除此一次性 container;不發布 app 的 service ports。migration 不放進 Dockerfile,因為 build 不應連 production DB,也不放在每個 worker 同時執行的啟動鉤子。
用第三章的 curl 或 /docs 再建立四種資源。要用 .env 的 key 時,在自己的 shell 安全地載入相同值;不要用「產生新 key」取代它。記下 application ID,再測試持久化:
重開後用原 key 讀回 application,預期仍在。down 預設保留 named volume;down -v 會刪除此 stack 的 named volume,不能當作日常重啟。volume 也不是備份,備份需另做匯出與還原演練。
遇到故障,先定位再進容器¶
| 症狀 | 先查哪裡 | 可執行檢查 |
|---|---|---|
| Docker daemon 連不上 | Host/Docker | docker version,確認 Engine 已啟動 |
pip install 失敗 |
Build/dependency | docker compose build app 的第一個錯誤,核對依賴與平台 |
ModuleNotFoundError |
Image 內容、import 路徑 | docker compose run --rm --no-deps app python -c 'import psycopg; import app.main' |
| app 容器立即退出 | 主程序/設定 | docker compose ps -a、docker compose logs --tail=80 app |
Connection refused |
host、port、DB readiness | docker compose ps、postgres logs、app 的 DB host 是否為 postgres |
| host 連不到 API | bind 與 port mapping | docker compose port app 8000,Uvicorn 是否綁 0.0.0.0 |
| env 未讀到 | runtime 設定 | 下方只印存在與否的檢查 |
| 換密碼後認證失敗 | volume 既有資料 | 核對初始化與改密碼流程,不刪 volume 猜答案 |
docker compose run --rm --no-deps app python -c 'import os; print({k: bool(os.getenv(k)) for k in ["DATABASE_URL", "APP_API_KEY", "PORT"]})'
docker compose exec postgres pg_isready -U job_assistant -d job_assistant
docker compose exec app id
最後一行預期是非 root 帳號。若 app 根本啟不來,exec 無法進入;用 run --rm --no-deps 啟動一次性診斷程序。修好依賴後要 rebuild 並 recreate,只在舊 container 裡 pip install 的變更不會成為下一次部署的 image。
自我檢核¶
- [ ] 解釋
COPY與RUN發生在 build,CMD發生在 runtime。預期能指出哪一步需要重新 build。 - [ ] 把 app URL 的 host 暫改為
localhost。預期/ready回 503,修回postgres後恢復;只在本機練習。 - [ ] 暫時移除
APP_API_KEY的傳遞。預期啟動失敗或 Compose 必填檢查先失敗,不會使用內建預設秘密。 - [ ] 重新建立 app container。預期資料保留,因為 DB 在 postgres 的 named volume。
- [ ] 對 Dockerfile 每一行說出用途。預期知道
EXPOSE不開 host port、JSON CMD 不展開$PORT。
下一步:部署 FastAPI 服務。
參考與來源¶
- 原始家教對話:Docker 化(chat2,整理於 2026-10-22);補齊 container、完整 Dockerfile、Compose 與具體故障檢查。
- Dockerfile reference
- Docker:Build context 與 .dockerignore
- Docker Compose:Networking
- Docker Compose:Startup order
- Docker:Volumes
- Postgres official image
