跳轉到

OAuth 與認證主題

本主題涵蓋 Time Compass 支援的四種認證方式：Google OAuth、Moodle 帳密、Gemini API Key，以及系統層級的環境變數管理。

快速開始

1. 你是新使用者，想自己部署 Time Compass？

→ 看 Google Cloud 專案設定

2. 你已設定好憑證，想驗證 OAuth 是否正常？

→ 看 OAuth 驗證流程

3. 你想深入理解 Google OAuth 架構與資料流？

→ 看 Google OAuth 架構參考

4. 你需要設定 Moodle 課程整合？

→ 看 Moodle 驗證架構參考

5. 你想看完整的整合層設計？

→ 看 Integration Layer C4 Model

認證系統概覽

認證系統 用途 設定位置 主要文檔
Google OAuth Calendar、Tasks 讀寫；AI scheduling GOOGLE_CLIENT_ID/SECRET + token.json 架構 | 設定 | 驗證
Moodle 帳密 課程事件爬蟲 MOODLE_ACCOUNT/PASSWORD 架構 | 深度分析
Gemini API Key AI 對話與排程建議 GEMINI_API_KEY ( 或 GOOGLE_API_KEY) 環境變數指南

分層文檔結構

Reference（架構理解層，5-10 分鐘）

適合想瞭解系統設計、資料流、安全邊界的人。

  • Google OAuth 架構參考
  • 兩條授權路徑（Gradio Session / MCP File）
  • 資料流圖與模組責任分工
  • 應用範圍與安全邊界

  • 常見問題診斷表

  • Moodle 驗證架構參考

  • 為什麼 Moodle 不用 Google OAuth？
  • 帳密認證與 OIDC 進階方案
  • Google OAuth 與 Moodle 帳密的區別
  • 升級與替代方案

Tutorial（操作步驟層，20-50 分鐘）

適合第一次設定、需要 step-by-step 指引的人。

  • Google Cloud 專案設定
  • 從零建立 Google Cloud project
  • 啟用 Calendar、Tasks、Gemini API
  • 設定 OAuth 同意畫面與憑證

  • 寫入 .env

  • OAuth 驗證流程

  • Step-by-step 授權驗證
  • 測試讀寫能力（Smoke Test / Functional Test）
  • 常見錯誤與修復（Redirect URI、Token 失效等）

常見工作流

🚀 第一次部署

  1. Google Cloud 專案設定 - 建立憑證
  2. OAuth 驗證流程 - 驗證授權成功
  3. 開始使用 Time Compass

🔄 Token 失效或授權相關問題

  1. 檢查 常見問題診斷表
  2. 按照 OAuth 驗證流程 重新授權

📚 深入瞭解系統

  1. Google OAuth 架構參考 - 資料流、模組設計
  2. Moodle 驗證架構參考 - Moodle 認證機制
  3. Integration Layer C4 Model - 整個整合層的四層架構

🌍 雲端部署或多使用者環境

  1. 讀 Google OAuth 架構參考 > 進階延伸
  2. 考慮 OAuth with database storage 或 Service Account

環境變數速查

所有認證相關的環境變數：

# Google OAuth（必要）
GOOGLE_CLIENT_ID=<client_id>
GOOGLE_CLIENT_SECRET=<client_secret>

# Gemini AI（建議）
GEMINI_API_KEY=<api_key>
# 或
GOOGLE_API_KEY=<api_key>

# Moodle（若需整合課程）
MOODLE_ACCOUNT=<帳號>
MOODLE_PASSWORD=<密碼>

詳細說明見環境變數指南。

相關系統