Ctrlk
註冊/登入
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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. 相關技術文檔

參考連結

PreviousGPU 算力硬體規劃NextText to SQL

Last updated

Was this helpful?