建立: 2026年8月19日 22:12:03
更新: 2026年8月19日 23:33:02
作者: Charles
System Component & Deployment Architecture¶
學習目標¶
完成本章節後，你將能夠：
- 辨識 DCKA 網站的 Client、Delivery、Runtime 與 Data 元件。
- 說明 GitHub Pages、Cloud Run、Gemini 與 Firestore 的部署位置。
- 區分 Runtime Data Flow 與 Build／Deploy Control Flow。
閱讀方式
實線代表使用者操作時的 Runtime Data Flow；虛線代表建置、部署、密鑰注入與版本發布等 Control Flow。
主要元件與責任¶
| 區域 | 元件 | 主要責任 |
|---|---|---|
| Client & Developer | VS Code、Git、uv、Browser | 編輯內容、執行建置及使用網站 |
| GitHub Control Plane | main、GitHub Actions、Pages Artifact |
保存原始碼、執行前後端部署、保存靜態網站產物 |
| Static Delivery | GitHub Pages | 提供 HTML、CSS、JavaScript、圖片與 content.json |
| Serverless Runtime | Cloud Run、FastAPI、Uvicorn | 驗證 Request、保管 API Key、呼叫 Gemini、記錄問答 |
| External AI | Gemini API | 根據文件上下文與對話內容產生回答 |
| Persistent Data | Cloud Firestore | 保存匿名問答、模型、延遲、狀態與時間戳 |
Build／Deploy Control Flow¶
- 開發者將
main推送至 GitHub；網站與後端依各自的 path filter 啟動不同 Workflow。 - Pages Workflow 將 MkDocs 產物上傳為 Pages Artifact，再由
deploy-pages發布。 - Backend Workflow 取得 GitHub OIDC Token，經 WIF impersonate
github-actions-deployer，不讀取長效 GCP JSON Key。 gcloud run deploy --source backend指定dcka-cloud-build執行 Container Build，並指定dcka-chatbot-runtime作為 Cloud Run Runtime Identity。- Artifact Registry 保存建置 Image；Cloud Run 建立 Revision 並切換 Traffic。
| Service Account | 執行平面 | 權限／責任 |
|---|---|---|
github-actions-deployer |
Deployment Control Plane | roles/run.sourceDeveloper、roles/serviceusage.serviceUsageConsumer，並只對 Build／Runtime SA 使用 roles/iam.serviceAccountUser |
dcka-cloud-build |
Build Plane | roles/run.builder |
dcka-chatbot-runtime |
Runtime／Data Plane | roles/datastore.user |
Frontend Runtime Flow¶
- 使用者從 GitHub Pages 取得靜態網站資源。
- Browser 使用
sessionStorage保存 Chat History 與匿名session_id。 - 使用者送出問題時，Browser 只以 HTTPS 傳送 History、Message 與 Session ID 至 Cloud Run
/api/chat。
Backend Runtime Flow¶
- Cloud Run HTTPS Ingress 將 Request 交給 FastAPI，CORS 只接受 GitHub Pages 與 localhost Origin。
- Backend 套用 1 MiB body、Pydantic extra-field rejection 與每來源 20 次／分鐘的 instance-local rate limit；Browser 無法傳入
system_instruction。 - Cloud Run 按需從 GitHub Pages 下載
content.json，每個 instance 快取一小時；更新失敗時可沿用 stale cache。 - Backend 以固定回答規則和教材內容組合 System Instruction，再由同步 FastAPI endpoint 在 worker thread 呼叫鎖定版本的
google-genaiSDK。 - Backend 先回傳回答或一般化錯誤，再由
BackgroundTasks遮罩並寫入 Firestore。
State Ownership¶
| State | 保存位置 | 生命週期 |
|---|---|---|
session_id、Chat History |
Browser sessionStorage |
同一個 Browser 分頁工作階段 |
| 教材上下文 | Cloud Run Instance Memory | 按需載入；預設一小時 Cache，可在更新失敗時沿用舊內容 |
| API Runtime | Cloud Run Instance | Stateless，不保證 Instance 持續存在 |
| 問答紀錄 | Firestore chat_logs |
Persistent；預設 90 天並由 expires_at TTL 管理 |
Current-state Security Boundary
/api/chat 仍是匿名公開入口，沒有登入或 API Authentication；現已具備 Backend-owned System Prompt、extra-field rejection、exact-origin CORS、輸入上限、instance-local rate limiting、一般化錯誤與 ACTIVE 的 Firestore 90 天 TTL。後端部署以 GitHub OIDC／WIF 取得短效憑證，Build 與 Runtime 各使用專用 Service Account。若要跨 Cloud Run instances 套用全域配額，仍需 Cloud Armor、API Gateway 或集中式 rate-limit store。
部署驗證
2026-08-19 已確認 revision dcka-chatbot-backend-00007-p7b 使用 dcka-chatbot-runtime、承接 100% Traffic；GitHub Pages、Cloud Run、Backend-owned Prompt、教材快取、CORS、Gemini 與 Firestore 端到端流程皆正常。