# 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 架構與配置

{% @mermaid/diagram content="flowchart LR
App\["Django 應用程式"]
Beat\["Celery Beat<br/>(排程器)"]
Broker\["Message Broker<br/>(Redis/RabbitMQ)"]
Worker1\["Worker 1"]
Worker2\["Worker 2"]
WorkerN\["Worker N"]
DB\[("資料庫")]

```
App -- "提交任務" --> Broker
Beat -- "定時觸發" --> Broker
Broker -- "分派任務" --> Worker1
Broker -- "分派任務" --> Worker2
Broker -- "分派任務" --> WorkerN
Worker1 -- "讀寫資料" --> DB
Worker2 -- "讀寫資料" --> DB
WorkerN -- "讀寫資料" --> DB" %}
```

### 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 任務執行流程

{% @mermaid/diagram content="sequenceDiagram
participant Beat as Celery Beat
participant Broker as Redis Queue
participant Worker as Celery Worker
participant DB as Database
participant OAuth as OAuth Provider

```
Note over Beat: 每小時觸發一次
Beat->>Broker: 發送刷新任務
Broker->>Worker: 分派任務到可用 Worker

Worker->>DB: 查詢即將過期的 Token<br/>(有效期 < 1 小時)
DB-->>Worker: 返回待刷新 Token 列表

loop 逐一處理 Token
    Worker->>DB: 檢查 Token 是否有客戶端憑證
    alt 有完整憑證
        Worker->>OAuth: 使用 Refresh Token 請求新 Token
        OAuth-->>Worker: 返回新的 Access Token
        Worker->>DB: 更新 Token 資訊
    else 缺少憑證
        Worker->>DB: 標記為舊版 Token,排除處理
    end
end

Worker->>Broker: 回報任務完成" %}
```

### 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 自動刷新機制](https://docs.maiagent.ai/tech/advanced-genai-tech/oauth-integration) - 詳細了解 OAuth Token 刷新邏輯
* [部署架構](https://docs.maiagent.ai/tech/platform-development/architecture) - 了解 Celery 在整體系統架構中的位置

### 參考連結

* [Celery Documentation](https://docs.celeryq.dev/)
* [Django Celery Beat](https://django-celery-beat.readthedocs.io/)
* [Flower - Celery Monitoring Tool](https://flower.readthedocs.io/)