FastAPI 應用結構與啟動方式：自訂啟動參數（host、port、reload、log‑level）

---

簡介

在開發與部署 FastAPI 時，最常見的第一步就是啟動伺服器。雖然 uvicorn app:app 這樣的單行指令已足以讓程式跑起來，但實務上我們往往需要自行調整 host、port、reload 與 log‑level 等參數，以配合開發環境、測試平台或正式上線的需求。
正確設定這些參數不僅能提升開發效率（如即時重載），也能在生產環境中確保日誌等級恰當、服務只接受內部請求或特定埠號，避免不必要的安全風險。

本篇文章將從概念說明、實作範例、常見陷阱與最佳實踐，完整呈現如何在 FastAPI 中自訂啟動參數，並提供多種應用情境的示範程式碼，讓你從新手快速晉升為能夠自行調校服務的中階開發者。

---

核心概念

1. 為什麼要自訂 host 與 port？

• host 決定了服務綁定的 IP 位址。預設 127.0.0.1 只接受本機請求，若要讓外部設備（如前端、行動裝置）能存取，就需要改成 0.0.0.0 或特定的網路介面 IP。
• port 是服務的入口埠號。開發時常用 8000，但在同一台機器上同時跑多個服務時，就必須改成其他不衝突的埠號（如 8001、8080）。

2. reload：開發模式的即時重載

uvicorn --reload 會在偵測到檔案變動時自動重新啟動伺服器，省去手動重啟的時間。注意：此功能僅建議在開發環境使用，因為在正式環境開啟會增加不必要的資源開銷與安全風險。

3. log-level：控制日誌輸出細節

FastAPI（底層使用 uvicorn）支援多種日誌等級：

等級	說明
critical	只顯示最嚴重的錯誤
error	顯示錯誤與致命例外
warning	顯示警告訊息
info	預設等級，顯示一般資訊
debug	顯示除錯訊息，最冗長

在開發階段常使用 debug，而正式環境則建議使用 info 或 warning，以免把過多資訊寫入日誌檔。

4. 兩種常見的啟動方式

方式	說明
CLI 直接呼叫	uvicorn app:app --host 0.0.0.0 --port 8080 --reload --log-level debug
程式碼內部呼叫	在 if __name__ == "__main__": 區塊使用 uvicorn.run()，可在同一檔案內設定參數，方便在 IDE 中直接執行或加入自訂邏輯。

---

程式碼範例

以下示範 5 個實務中最常見的自訂啟動方式，請依需求挑選使用。

1️⃣ 基本 CLI 呼叫（最簡單）

uvicorn main:app

預設 host=127.0.0.1、port=8000、log-level=info。適合快速測試單一端點。

---

2️⃣ 完整自訂參數的 CLI 呼叫

uvicorn main:app \
    --host 0.0.0.0 \
    --port 8080 \
    --reload \
    --log-level debug

這行指令同時設定了四個參數，開發者可直接在終端機看到即時變更與詳細除錯資訊。

---

3️⃣ 程式碼內部呼叫 uvicorn.run()

# main.py
from fastapi import FastAPI
import uvicorn

app = FastAPI()

@app.get("/ping")
def ping():
    """簡單的健康檢查端點"""
    return {"message": "pong"}

if __name__ == "__main__":
    # 直接在程式內設定啟動參數，方便在 IDE (如 VSCode) 中點擊執行
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8001,
        reload=True,          # 開發時使用
        log_level="debug",    # 顯示詳細日誌
    )

重點：uvicorn.run() 的第一個參數是 "module:app"，必須是字串形式，否則會找不到 FastAPI 實例。

---

4️⃣ 使用 python -m uvicorn 模組方式

python -m uvicorn main:app --host 0.0.0.0 --port 5000

這種寫法等同於直接呼叫 uvicorn 指令，但在某些 CI/CD 環境或容器內部，使用 python -m 可以避免 PATH 找不到執行檔的問題。

---

5️⃣ 在 Dockerfile 中設定啟動參數（實務部署）

# Dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# 使用環境變數讓參數更彈性
ENV HOST=0.0.0.0
ENV PORT=80
ENV LOG_LEVEL=info

CMD ["uvicorn", "main:app", "--host", "$HOST", "--port", "$PORT", "--log-level", "$LOG_LEVEL"]

說明：透過 Docker ENV 變數，我們可以在 docker run -e PORT=8080 時動態調整埠號，無需重新建置映像檔。

---

常見陷阱與最佳實踐

陷阱	說明	解決方案 / 最佳實踐
忘記改 host 為 0.0.0.0	開發時只能本機存取，部署到雲端或 VM 時外部無法連線。	在正式環境 一定 設為 0.0.0.0，或使用環境變數管理。
reload 在生產環境開啟	會持續監控檔案變化，浪費 CPU 與記憶體，且可能暴露檔案系統資訊。	只在 DEBUG 或 development 環境使用 --reload，使用 if os.getenv("ENV") == "development": 來條件化。
日誌等級過低	debug 日誌在正式環境會寫入大量資訊，佔用磁碟且可能洩漏機密。	正式環境統一使用 info 或 warning，並透過 log-config.yaml 進一步設定檔案輪替。
埠號衝突	多個服務同時跑在相同埠號會導致啟動失敗。	使用 docker-compose.yml 或 systemd 服務檔案明確指定不同埠號，或在程式碼中捕捉 OSError 並提示。
硬編碼參數	直接在程式碼寫死 host、port，不易在不同環境切換。	使用 環境變數（os.getenv）或 設定檔（如 pydantic.BaseSettings）統一管理。

小技巧：使用 pydantic.BaseSettings 統一管理

# config.py
from pydantic import BaseSettings

class Settings(BaseSettings):
    host: str = "0.0.0.0"
    port: int = 8000
    reload: bool = False
    log_level: str = "info"

    class Config:
        env_file = ".env"

settings = Settings()

# main.py
import uvicorn
from fastapi import FastAPI
from config import settings

app = FastAPI()

@app.get("/")
def root():
    return {"msg": "Hello FastAPI"}

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host=settings.host,
        port=settings.port,
        reload=settings.reload,
        log_level=settings.log_level,
    )

在 .env 中只需要改一行，即可完成環境切換，不需要改任何程式碼。

---

實際應用場景

1. 本機開發

   • host=127.0.0.1、port=8000、reload=True、log-level=debug
   • 讓前端開發者可快速測試 API，且每次儲存檔案即自動重載。

2. 內部測試環境（Staging）

   • host=0.0.0.0、port=8080、reload=False、log-level=info
   • 透過 Docker Compose 部署，提供 QA 團隊測試，並保留適度的日誌資訊。

3. 正式上線（Production）

   • host=0.0.0.0、port=80（或 443 之後的反向代理）
   • reload=False、log-level=warning，並搭配 Gunicorn + UvicornWorker 以多工作者模式提升併發量。

   gunicorn main:app \
       -k uvicorn.workers.UvicornWorker \
       -b 0.0.0.0:80 \
       --log-level warning \
       --workers 4
   

4. 容器化 CI/CD

   • 在 GitHub Actions 中使用 uvicorn CLI，透過環境變數傳入 HOST、PORT，確保測試腳本不依賴硬編碼。

   steps:
     - name: Run FastAPI tests
       run: |
         uvicorn main:app --host $HOST --port $PORT &
         pytest tests/
       env:
         HOST: 127.0.0.1
         PORT: 8001
   

---

總結

• host、port、reload、log‑level 是 FastAPI 啟動時最常調整的四個參數，分別影響可存取範圍、服務入口、開發便利性與日誌資訊量。
• CLI 方式適合臨時測試或部署腳本；程式碼內部 呼叫則方便在 IDE 中直接執行或加入環境判斷。
• 避免硬編碼，使用環境變數或 pydantic.BaseSettings 讓設定在不同環境間自由切換。
• 開發 時開啟 reload、log-level=debug，正式 環境則關閉 reload、將 log-level 提升至 info 或 warning，以降低資源使用與資訊洩漏風險。
• 結合 Docker、Gunicorn 或 CI/CD，將這些參數以 配置檔 或 環境變數 的方式注入，才能在實際專案中發揮最大的彈性與安全性。

掌握了這些自訂啟動參數的技巧後，你就能在任何開發或部署階段快速調整 FastAPI 服務的行為，讓開發流程更順暢、上線更可靠。祝你在 FastAPI 的旅程中一路順風 🚀。