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

### 參考連結

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maiagent.ai/tech/platform-development/celery-periodic-tasks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.