部署 FastAPI 服務:讓求職助理透過 HTTPS 提供服務¶
摘要¶
容器在本機能啟動,只代表本機的依賴與設定足夠。部署還要確認平台 port、正式 DB、migration、秘密與流量切換。本章沿用上一章的 image,以 Render Web Service 執行 FastAPI、Render Postgres 保存資料。
完成後能從 GitHub commit 部署一個有 API key 保護的 HTTPS 服務,完成寫入、讀取與重啟驗收,並從 log 區分 build、應用、DB、網路與設定錯誤。這是單一操作者的求職助理示範;對外開放多人登入前,需把身分與逐筆授權接進 service。
資料基準:2026-10-22。平台介面、方案與限制可能變動,以文末官方文件為準。以下是讀者在自己帳號的操作手冊;本次文章編寫不會建立雲端資源或執行部署。
先選能完成練習的方案¶
本章主流程使用付費 Web Service 的 pre-deploy command,讓 migration 成功後才切換新版,並使用可保留資料的 managed PostgreSQL 方案。選方案前確認費用、備份與連線上限,不把免費試用當作正式資料的保存承諾。
若只試玩,Render Free Web Service 在 15 分鐘沒有 HTTP 或 WebSocket 入站流量後會休眠,下一次請求可能經歷約一分鐘喚醒;這不是固定 latency 保證。Free Postgres 建立後 30 天到期,且不提供備份。免費 web service 沒有 pre-deploy command 與 shell;不能照抄需要這些功能的操作。需要免費練習時,先在可連 DB 的本機以外部 URL 手動執行同一份 migration,再部署單一測試 instance,正式資料另選合適方案。參考 Render Free 限制 與 Deploy steps。
部署流程與連線位置¶
Migration 在新版接流量前,但舊版此時可能還在服務,所以 schema 變更必須和舊版相容。不能先刪掉舊版仍讀取的欄位,再期待無縫切換。
Render 不會把本機的 Compose stack 原樣搬上雲端;app 使用 repo 的 Dockerfile,DB 是獨立 managed service。容器裡的 postgres 名稱只存在於本機 Compose 網路,localhost 仍指向 app 自己。正式 DB 使用平台提供的 internal hostname。詳見 Docker on Render。
第一次部署:按順序填設定¶
先在自己的 GitHub repo 確認以下檔案已選擇性提交,且 git ls-files -- .env 沒有輸出:app/、migrations/(含 SQL)、alembic.ini、requirements.txt、Dockerfile、.dockerignore、測試與 README。不要提交真實履歷、密碼或 .venv。先跑 python -m pytest -q,並用 Docker build 確認依賴能在 Linux image 裡安裝。
- 在 Render Dashboard 選 New → Postgres。設定名稱、區域與方案;本系列選 PostgreSQL 17,以便和本機一致。建立後等待 available,記下 DB 名稱與 internal connection URL;不要把 URL 貼進工單。
- 選 New → Web Service,連結自己的 GitHub repo,選實際要部署的分支,例如
main。Language/Runtime 選 Docker,Dockerfile Path 為./Dockerfile,root directory 為專案根目錄。 - Web Service 與 Postgres 選同一區域與可互通的 workspace private network。平台建議同區服務用 internal URL;本機管理工具用 external URL,兩者可通往同一個 DB,但可達網路不同。
- 在 Web Service 的 Environment 設定下表。先關閉自動部署,讓第一次設定與驗收可控。
- 設 Pre-Deploy Command 為
python -m alembic upgrade head。Docker Command 保留空白,使用 Dockerfile 的CMD;不要另填 native Python 的 build command。 - Health Check Path 設
/ready,再啟動首次部署。依序查看 build、pre-deploy、runtime log 與 deploy status。
| 環境變數 | 應填內容 |
|---|---|
DATABASE_URL |
Render Postgres 的完整 internal URL;第四章 database_url() 會轉成 postgresql+psycopg:// |
APP_API_KEY |
自行產生長隨機秘密,和本機 demo key 不同 |
CORS_ORIGINS |
沒有瀏覽器前端先留空;有前端才填實際 origin,例如 https://frontend.example.com |
PORT |
使用平台注入值;app.start 已讀取,不硬寫成 8000 |
必要時在安全的本機環境用 python -c 'import secrets; print(secrets.token_urlsafe(32))' 產生 key,再存進平台秘密設定;不要寫入 README。持有 key 的操作者能管理所有 user,不能把它公開在瀏覽器程式中。
Render 要求 HTTP server 綁 0.0.0.0 並使用服務 port;目前預設期待 port 10000,但應讀 PORT,不靠記住平台預設值。第五章的 Python 啟動器已符合。平台提供 onrender.com URL,並管理 TLS 憑證與 HTTP→HTTPS 轉向;自訂 domain 要先在平台加入,再依其提示設定 DNS。參考 Web Services、Postgres connection 與 TLS。
外部 DB 連線的 TLS/憑證依平台要求設定,必要時在 URL 加合適的 sslmode;不要為了解掉 SSL error 一律關掉驗證。也不要把外部 URL 的網路存取規則誤當成 internal URL 設定。
部署成功後,必須真的寫入再讀回¶
從 Dashboard 複製實際 service URL,取代下方 YOUR-SERVICE。在自己的 shell 設定正式 APP_API_KEY;不要把秘密貼到公開 log:
export API_BASE='https://YOUR-SERVICE.onrender.com'
curl --fail-with-body --max-time 90 "$API_BASE/health"
curl --fail-with-body --max-time 90 "$API_BASE/ready"
curl -i --max-time 30 "$API_BASE/resumes/1"
前兩者預期 200;第三個沒帶 key,預期 401。健康檢查公開但不顯示 DB URL 或錯誤細節。Render 將 2xx/3xx 視為 healthy,4xx/5xx 為 unhealthy;/ready 在 DB 不可達時回 503,/health 仍可回答程序存活。平台可能依 healthcheck 重啟 instance,因此全 DB 故障不一定靠重啟 app 修得好。參考 Render Health Checks。
新增本機驗收工具 smoke.py,不把憑證寫入檔案。它每次產生不同 email,並儲存回傳 application ID:
import json
import os
import uuid
from pathlib import Path
import httpx
base = os.environ["API_BASE"].rstrip("/")
headers = {"Authorization": f"Bearer {os.environ['APP_API_KEY']}"}
with httpx.Client(base_url=base, headers=headers, timeout=90) as client:
def create(path, body):
response = client.post(path, json=body)
assert response.status_code == 201, (path, response.status_code)
return response.json()
user = create("/users", {"email": f"smoke-{uuid.uuid4().hex}@example.com", "name": "Smoke Test"})
resume = create("/resumes", {"user_id": user["id"], "title": "Demo", "text": "Python SQL"})
job = create("/jobs", {
"user_id": user["id"], "company_name": "Example", "job_title": "Engineer",
"description": "Python SQL AWS Docker",
})
body = {"user_id": user["id"], "resume_id": resume["id"], "job_description_id": job["id"]}
application = create("/applications", body)
assert application["match_score"] == 50.0
assert client.post("/applications", json=body).status_code == 409
stored = client.get(f"/applications/{application['id']}")
assert stored.status_code == 200
assert stored.json()["analysis"]["missing_skills"] == ["aws", "docker"]
Path(".smoke-result.json").write_text(json.dumps({"application_id": application["id"]}))
print("smoke passed; application_id=", application["id"])
把 .smoke-result.json 加入練習 repo 的 .gitignore,再執行 python smoke.py。成功後在 Render 重新啟動或部署同一版本,使用記下的 ID 讀回:
application_id=$(python -c 'import json; print(json.load(open(".smoke-result.json"))["application_id"])')
curl --fail-with-body -H "Authorization: Bearer $APP_API_KEY" "$API_BASE/applications/$application_id"
預期仍回 200 與 50 分,表示資料已跨程序重啟保存。單看 /health 200,無法證明 schema 已建立或資料有提交。
讀 log 時,第一個失敗比最後一行有用¶
| 第一個可信證據 | 能得出的結論 | 下一步 |
|---|---|---|
pip install 找不到指定版本 |
Build 尚未完成,新版 FastAPI 未啟動;舊版可能仍服務 | 查 dependency 名稱、版本、Python/CPU wheel 支援,修依賴檔後重建 |
Started server process 後 import/startup 錯誤 |
新程序曾開始,不代表 ready | 檢查缺 module、必要 env 與 import 路徑 |
DB URL host 是 localhost,connection refused |
很可能設定指錯位置,也可能 DB 未監聽 | 先核對 internal hostname、port、DB 狀態,再看網路 |
password authentication failed |
已接觸 DB,但認證未通過 | 核對 role、秘密輪替、URL encoding,不重寫 router |
relation ... does not exist |
連到的 DB 缺 schema,或連錯 DB/schema | 比對 migration revision、DB 名稱與部署環境 |
| 無偵測到可用 port | app 未正確監聽或尚未啟動 | 查 PORT、0.0.0.0、啟動器與 runtime log |
| curl 正常、瀏覽器跨來源失敗 | 可能是 CORS/preflight;不是 SQL 問題 | 檢查實際 Origin 與允許的 headers/methods |
來源的 psycopg2==99.0.0 是故意錯誤的練習字串,不是可用版本,不能放進依賴檔。「開始 server process」也不能單憑一行證明整個服務部署成功;要對照同一次 deploy 的 commit、build 完成、migration 與 ready 結果。
Runtime log 記錄請求路徑、狀態與必要錯誤代碼即可,不記錄 Authorization、履歷全文或完整 DATABASE_URL。平台設定變更後確認實際新 deploy 使用了該設定,不能把 restart 當作必然套用尚未部署的 environment 更新。
CI 與一次可回復的更新¶
新增 .github/workflows/test.yml 到自己的練習 repo。Action major 版依官方 Python workflow 範例核對;若組織要求供應鏈固定版本,再改用審查過的 commit SHA:
name: test
on: [push, pull_request]
permissions:
contents: read
jobs:
tests:
runs-on: ubuntu-latest
env:
DATABASE_URL: postgresql+psycopg://unused:unused@127.0.0.1/unused
APP_API_KEY: ci-only-not-a-production-key
steps:
- uses: actions/checkout@v6
- uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: pip
- run: python -m pip install -r requirements.txt
- run: python -m pytest -q
- run: docker build -t job-assistant:ci .
這個 CI 只跑以記憶體 override 的 API 測試與 image build;假 DB URL 是為了載入 module,不會拿來執行 migration。它不能證明 PostgreSQL constraints 或正式環境可用,DB 整合仍依第四章實測。參考 GitHub:Building and testing Python。
在 GitHub 讓 test 成為 main 的必要檢查,Render Auto-Deploy 設成 After CI Checks Pass;也確認沒有其他會被 skip 卻應阻擋部署的檢查。接著用一個小文件/API 說明變更走完 branch → commit → PR → merge → deploy,記下實際 commit SHA,再執行 smoke test。CI 通過表示已自動檢查的部分通過;CD 才負責把通過檢查的版本交付到服務。參考 Render automatic deploys。
若新版出現程式錯誤,先暫停自動部署,從 Deploys 選已成功版本 Rollback,再重跑健康與讀取驗收,最後以新的修正/revert commit 修復分支,避免下一次部署把錯版送回去。Render 重用舊 build artifact;不會回復資料庫內容或把 schema 退回去。秘密若因事故被輪替,也不能回復成舊秘密。詳見 Render Rollbacks。
Schema 更新採 expand/contract:先新增允許空值或有相容預設值的欄位,部署可同時讀寫新舊格式的程式,再回填與驗證,最後在確認舊版不再使用後移除舊欄位。大量回填要另排批次,不能塞進長時間鎖表的 deploy transaction。資料庫備份需在獨立測試環境演練還原;有備份檔不等於已證明救得回來。
自我檢核與交付紀錄¶
- [ ] 第一次部署:記下 repo branch、commit SHA、migration
0001、實際 HTTPS URL 與方案。預期沒有.env進版控。 - [ ] 故障題:在測試環境設錯 DB hostname。預期能從 runtime/readiness 503 定位,不回頭改計分函式;修回後恢復。
- [ ] API 題:smoke test 完成四種資源的寫讀、50 分計算與重複申請 409。預期重啟後舊 ID 可讀。
- [ ] 設定題:說出本機、Compose、Render 的 DB host。預期分別是 host 位址、
postgres、平台 internal hostname。 - [ ] 更新題:PR 合併後只部署 CI 通過的 commit。預期 Dashboard 與 GitHub SHA 一致。
- [ ] 回復題:在測試服務回到上一個成功 deploy。預期資料仍在,並能解釋哪種 schema 變更會讓舊程式無法回復。
回到系列總覽核對跨章成果。後續最值得做的擴充是不可變履歷版本與逐筆授權;接 LLM 前,也應把呼叫 timeout、失敗重試、輸出驗證與費用上限各自放在明確邊界。
參考與來源¶
- 原始家教對話:部署 FastAPI 服務(chat3,整理於 2026-10-22);保留五層除錯方法,補上真正部署、驗收、CI 與回復。
- Render:Docker
- Render:Web Services
- Render:Deploy steps
- Render:Postgres connection
- Render:Health Checks
- Render:Free limitations
- Render:Rollbacks
