跳轉到

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:

.git
.venv
__pycache__
*.py[cod]
.pytest_cache
.env
.env.*
!.env.example
*.log
resume.txt
job.txt

新增 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,只放本機教學值;這些已公開的示範值不能用於部署:

POSTGRES_PASSWORD=local-demo-change-me
APP_API_KEY=local-demo-operator-key-change-me

本機複製後自行換成長隨機值;教學 DB password 請先用 URL-safe 的字母與數字,因為下面會把它插入連線 URL:

cp .env.example .env

新增 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 配置:本機用 127.0.0.1:8000 呼叫 app,app 在 Compose 網路內用 postgres:5432 連資料庫,資料存在 pgdata volume

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,再測試持久化:

docker compose restart app
docker compose down
docker compose up -d

重開後用原 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 服務。

參考與來源