Celery 週期性任務配置與 OAuth Token 刷新

本文件說明 MaiAgent 平台如何使用 Celery Beat 排程器來執行週期性任務,特別是針對 OAuth Token 自動刷新的實作方式。

1. Celery 在 MaiAgent 的角色

Celery 是一個分散式任務佇列系統,在 MaiAgent 平台中扮演關鍵角色:

任務類型	說明	執行方式
非同步任務	耗時的背景處理工作,如文件解析、向量化	Celery Worker 接收任務並執行
週期性任務	定時執行的維護工作,如 Token 刷新、資料清理	Celery Beat 按排程觸發任務
延遲任務	需要在特定時間執行的任務,如定時發送通知	設定 countdown 或 eta 參數延遲執行
任務鏈	需要依序執行多個步驟的複雜流程	使用 Celery Chain 組合多個任務

常見應用場景:

• 知識庫處理: 文件上傳後的解析、分塊、向量化等耗時操作

• 定期維護: OAuth Token 刷新、過期資料清理、系統健康檢查

• 報表生成: 定期產生使用量統計、對話品質分析等報表

• 通知發送: 批次發送郵件通知、Webhook 回調

---

2. Celery 架構與配置

2.1 核心元件說明

• Celery Beat (排程器): 負責按照設定的排程表觸發週期性任務

• Message Broker (訊息代理): 使用 Redis 或 RabbitMQ 作為任務佇列

• Celery Workers (工作程序): 實際執行任務的工作程序,可水平擴展

• Result Backend (結果儲存): 儲存任務執行結果,通常使用 Redis 或資料庫

2.2 週期性任務配置

MaiAgent 使用 Django Celery Beat 來管理週期性任務:

任務名稱	排程	說明
OAuth Token 刷新	每小時	自動刷新即將過期的 OAuth Token
Session 清理	每天凌晨	清除已過期的使用者 Session

排程表達式類型:

• crontab: 類似 Unix cron 的時間表達式,支援分鐘、小時、星期、月份等

• timedelta: 固定間隔執行,例如每 30 分鐘

• solar: 基於日出日落時間的排程

---

3. OAuth Token 自動刷新任務

3.1 任務執行流程

3.2 查詢優化策略

MaiAgent 實作了多項查詢優化,提升 Token 刷新的效率:

• 過濾舊版 Token: 排除沒有 client_id 和 client_secret 的舊版 Token

• 時間視窗查詢: 僅查詢在未來 1 小時內會過期的 Token

• 批次處理: 一次查詢多個待刷新的 Token,減少資料庫查詢次數

• 錯誤處理: 針對刷新失敗的 Token 記錄詳細錯誤資訊,便於追蹤問題

3.3 錯誤處理機制

Token 刷新過程可能遇到以下錯誤情況:

錯誤類型	可能原因	處理方式
Refresh Token 無效	使用者已撤銷授權或 Token 已過期	標記為需要重新授權,通知使用者
網路逾時	OAuth 服務提供商暫時無法連線	自動重試 3 次,使用指數退避策略
速率限制	超過 OAuth 服務的請求頻率限制	延遲重試,避免被封鎖
客戶端憑證錯誤	client_id 或 client_secret 不正確	記錄錯誤,通知管理員檢查配置

---

4. 任務監控與除錯

4.1 任務狀態監控

MaiAgent 提供多種方式監控 Celery 任務狀態:

• Flower 監控介面: Web 介面即時查看任務執行狀態、Worker 健康度

• 日誌記錄: 詳細記錄每個任務的執行時間、參數和結果

• 指標收集: 整合 Prometheus 收集任務執行指標,如成功率、執行時間等

• 告警機制: 當任務連續失敗或執行時間異常時自動發送告警

4.2 效能優化建議

Worker 池配置:

• 併發數調整: 根據 CPU 核心數和任務類型調整 Worker 併發數

• 佇列分離: 將緊急任務和非緊急任務分配到不同佇列

• 任務優先級: 為關鍵任務設定更高的優先級

任務設計原則:

• 冪等性: 確保任務可以安全地重試,不會產生副作用

• 時效性: 設定合理的任務過期時間,避免執行過期的任務

• 分批處理: 對於大量資料處理,採用分批策略避免記憶體溢出

---

5. MaiAgent Celery 配置的技術優勢

5.1 可靠性與穩定性

• 任務持久化: 任務資訊儲存在 Message Broker,即使系統重啟也不會遺失

• 自動重試: 支援任務失敗後的自動重試機制

• 優雅關閉: Worker 在關閉前會完成正在執行的任務

• 健康檢查: 定期檢查 Worker 和 Beat 的運行狀態

5.2 擴展性與效能

• 水平擴展: 可輕鬆增加 Worker 數量以應對流量增長

• 任務路由: 將不同類型的任務分配到專用的 Worker 池

• 非同步執行: 不阻塞主應用程式,提升系統響應速度

• 批次優化: 智慧批次處理減少資料庫查詢次數

5.3 運維友善性

• 可視化監控: Flower 提供直觀的監控介面

• 詳細日誌: 完整記錄任務執行過程,便於問題排查

• 動態配置: 可在不重啟系統的情況下調整排程表

• 告警整合: 與企業監控系統整合,及時發現異常

---

6. 相關技術文檔

• OAuth 2.0 整合與 Token 自動刷新機制 - 詳細了解 OAuth Token 刷新邏輯

• 部署架構 - 了解 Celery 在整體系統架構中的位置

參考連結

• Celery Documentation

• Django Celery Beat

• Flower - Celery Monitoring Tool