在分佈式任務調度場景中，多團隊協作常面臨任務管理接口分散、權限控制複雜、操作審計缺失等問題。ElasticJob作為分佈式任務調度框架，其原生基於ZooKeeper的分佈式協調機制雖能保證任務高可用執行，但缺乏統一的操作入口和細粒度的權限控制。通過API網關集成，可構建統一的任務管理平面，實現認證授權、流量控制和操作審計的一體化管控。

集成架構設計

ElasticJob API網關集成採用分層架構，通過RESTful接口層封裝任務操作能力，結合認證授權中間件實現權限控制，最終通過網關聚合所有接口。核心組件包括：

• RESTful服務層：基於Netty實現的HTTP接口，提供作業啓停、狀態查詢、分片調整等操作，對應源碼實現見restful/目錄。
• 認證授權層：支持Casdoor單點登錄和RBAC權限模型，配置示例見docs/content/user-manual/operation/web-console.cn.md。
• 註冊中心適配層：通過ZooKeeper客户端操作作業元數據，節點結構定義詳見docs/content/features/elastic.cn.md。

核心交互流程

1. 客户端通過網關發起任務操作請求（如啓動作業）
2. 網關驗證JWT令牌並檢查操作權限
3. 轉發請求至RESTful服務處理
4. 服務層更新ZooKeeper註冊中心節點數據
5. 作業實例監聽節點變化並執行相應操作

RESTful API設計與實現

接口規範

RESTful服務採用標準HTTP方法映射資源操作，核心接口定義如下：

實現示例

創建作業控制器需實現RestfulController接口，通過註解定義路由映射：

@ContextPath("/job")
public class JobController implements RestfulController {
    
    @Mapping(method = Http.POST, path = "/{group}/{jobName}")
    public JobPojo createJob(@Param(name = "group", source = ParamSource.PATH) final String group,
                             @Param(name = "jobName", source = ParamSource.PATH) final String jobName,
                             @Param(name = "cron", source = ParamSource.QUERY) final String cron,
                             @RequestBody String description) {
        // 作業創建邏輯實現
    }
}

服務啓動配置通過Netty實現，代碼示例見restful/README.md：

NettyRestfulServiceConfiguration configuration = new NettyRestfulServiceConfiguration(8080);
configuration.addControllerInstance(new JobController());
RestfulService restfulService = new NettyRestfulService(configuration);
restfulService.startup();

認證授權實現

Casdoor集成

通過Casdoor實現單點登錄，需在控制枱配置認證參數，對應文檔docs/content/user-manual/operation/web-console.cn.md。核心配置項包括：

casdoor.endpoint=http://casdoor-server:8000
casdoor.client-id=elasticjob-app
casdoor.client-secret=xxxxx
casdoor.certificate=-----BEGIN CERTIFICATE-----...
casdoor.organization=elasticjob

RBAC權限模型

權限控制通過ZooKeeper節點ACL實現細粒度管控，定義三種角色：

1. 管理員：擁有所有操作權限，對應root用户
2. 運維人員：可執行作業啓停、分片調整等操作
3. 查看人員：僅能查詢作業狀態，無修改權限

權限配置存儲在/elasticjob/namespaces/{namespace}/roles節點，通過API網關攔截器進行權限校驗。

監控與審計

作業狀態監控

通過監聽ZooKeeper臨時節點實現作業服務器存活檢測，節點路徑格式為/jobName/instances/job_instance_id，監聽邏輯見docs/content/user-manual/operation/execution-monitor.cn.md。當節點消失時，觸發告警機制並記錄日誌。

操作審計

API網關記錄所有任務操作日誌，包括操作人、時間、IP地址和操作內容，日誌格式示例：

{
  "timestamp": "2025-10-29T10:15:30Z",
  "operator": "admin",
  "operation": "start_job",
  "resource": "order-process-job",
  "ip": "192.168.1.100",
  "status": "success"
}

審計日誌可通過/audit/logs接口查詢，支持按時間範圍、操作類型等條件篩選。

集成部署指南

環境準備

1. 部署ZooKeeper集羣（推薦3節點）
2. 部署Casdoor服務並配置應用，參考docs/content/user-manual/operation/web-console.cn.md
3. 編譯RESTful服務：mvn clean package -pl restful -am

配置示例

API網關配置文件（application.yml）：

server:
  port: 8080
elasticjob:
  zookeeper:
    server-lists: 127.0.0.1:2181
    namespace: elasticjob-gateway
casdoor:
  endpoint: http://casdoor:8000
  client-id: ${CASDOOR_CLIENT_ID}
  client-secret: ${CASDOOR_CLIENT_SECRET}

啓動命令

java -jar elasticjob-restful-${version}.jar --spring.config.location=file:./application.yml

常見問題處理

權限認證失敗

現象：調用API時返回403 Forbidden
排查步驟：

1. 檢查JWT令牌是否過期
2. 確認用户角色是否包含目標操作權限
3. 核對Casdoor服務是否正常運行

作業狀態同步延遲

現象：API返回狀態與實際不符
原因分析：ZooKeeper節點監聽存在短暫延遲，參考docs/content/features/elastic.cn.md中的分片機制。
解決方法：通過reconcileIntervalMinutes配置調整同步週期，配置項説明見docs/content/user-manual/configuration/java-api.cn.md。

擴展方向

1. 多註冊中心適配：除ZooKeeper外，可擴展支持Nacos、etcd等註冊中心
2. 流量控制：基於令牌桶算法實現API調用限流
3. 灰度發佈：支持作業配置的金絲雀發佈，降低變更風險