ElasticJob-Cloud用户手册-京东云开发者社区

# 使用手册

## 作业开发

ElasticJob-Lite 和 ElasticJob-Cloud 提供统一作业接口，开发者仅需对业务作业进行一次开发，之后可根据不同的配置以及部署至不同环境。

作业开发详情请参见 [ElasticJob-Lite 使用手册](/cn/user-manual/elasticjob-lite/usage/)。

## 作业启动

需定义 `main` 方法并调用 `JobBootstrap.execute()`，例子如下：

```java
public class MyJobDemo {
    
    public static void main(final String[] args) {
        JobBootstrap.execute(new MyJob());
    }
}
```

# 配置手册

ElasticJob-Cloud 提供应用发布及作业注册等 RESTful API， 可通过 curl 操作。

请求 url 前缀为 `/api`

## 鉴权 API

### 获取 AccessToken

url: login

方法：POST

参数类型：application/json

参数列表：

| 属性名                   | 类型    | 是否必填 | 缺省值     | 描述                           |
| ----------------------- |:------- |:------- |:--------- |:----------------------------- |
| username                | String  | 是      |           | API 鉴权用户名                 |
| password                | String  | 是      |           | API 鉴权密码                 |

响应体：

| 属性名                   | 类型      | 描述                           |
| ----------------------- |:-------  |:----------------------------- |
| accessToken             | String   | API 鉴权 token              |

示例：

```bash
curl -H "Content-Type: application/json" -X POST http://elasticjob_cloud_host:8899/api/login -d '{"username": "root", "password": "pwd"}'
```

响应体：

```json
{"accessToken":"some_token"}
```

## 应用 API

### 发布应用

url：app

方法：POST

参数类型：application/json

参数列表：

| 属性名                   | 类型    | 是否必填 | 缺省值     | 描述                           |
| ----------------------- |:------- |:------- |:--------- |:----------------------------- |
| appName                 | String  | 是      |           | 作业应用名称                    |
| appURL                  | String  | 是      |           | 作业应用所在路径                 |
| cpuCount                | double  | 否      | 1         | 作业应用启动所需要的 CPU 数量     |
| memoryMB                | double  | 否      | 128       | 作业应用启动所需要的内存 MB       |
| bootstrapScript         | String  | 是      |           | 启动脚本                        |
| appCacheEnable          | boolean | 否      | true      | 每次执行作业时是否从缓存中读取应用 |
| eventTraceSamplingCount | int     | 否      | 0（不采样）| 常驻作业事件采样率统计条数         |

参数详细说明：

**appName:**

为 ElasticJob-Cloud 的作业应用唯一标识。

**appURL:**

必须提供可以通过网络访问的路径。

**bootstrapScript:**

如：bin\start.sh

**appCacheEnable:**

禁用则每次执行任务均从应用仓库下载应用至本地。

**eventTraceSamplingCount:**

为避免数据量过大，可对频繁调度的常驻作业配置采样率，即作业每执行 N 次，才会记录作业执行及追踪相关数据。

示例：

```bash
curl -l -H "Content-type: application/json" -X POST -d '{"appName":"my_app","appURL":"http://app_host:8080/my-job.tar.gz","cpuCount":0.1,"memoryMB":64.0,"bootstrapScript":"bin/start.sh","appCacheEnable":true,"eventTraceSamplingCount":0}' http://elastic_job_cloud_host:8899/api/app
```

### 修改应用配置

url：app

方法：PUT

参数类型：application/json

参数列表：

| 属性名                   | 类型    | 是否必填 | 缺省值     | 描述                             |
| ----------------------- |:------- |:------- |:--------- |:------------------------------- |
| appName                 | String  | 是      |           | 作业应用名称                     |
| appCacheEnable          | boolean | 是      | true      | 每次执行作业时是否从缓存中读取应用  |
| eventTraceSamplingCount | int     | 否      | 0（不采样）| 常驻作业事件采样率统计条数         |

示例：

```bash
curl -l -H "Content-type: application/json" -X PUT -d '{"appName":"my_app","appCacheEnable":true}' http://elastic_job_cloud_host:8899/api/app
```

## 作业 API

### 注册作业

url：job/register

方法：POST

参数类型：application/json

参数列表：

| 属性名                         | 类型       | 是否必填 | 缺省值  | 描述                                               |
| ----------------------------- |:---------- |:------- |:------ |:------------------------------------------------- |
| appName                       | String     | 是      |        | 作业应用名称                                        |
| cpuCount                      | double     | 是      |        | 单片作业所需要的 CPU 数量，最小值为 0.001             |
| memoryMB                      | double     | 是      |        | 单片作业所需要的内存 MB，最小值为 1                   |
| jobExecutionType              | Enum       | 是      |        | 作业执行类型。TRANSIENT 为瞬时作业，DAEMON 为常驻作业 |
| jobName                       | String     | 是      |        | 作业名称                                          |
| cron                          | String     | 否      |        | cron 表达式，用于配置作业触发时间                    |
| shardingTotalCount            | int        | 是      |        | 作业分片总数                                       |
| shardingItemParameters        | String     | 否      |        | 自定义分片参数                                     |
| jobParameter                  | String     | 否      |        | 作业自定义参数                                     |
| failover                      | boolean    | 否      | false  | 是否开启失效转移                                    |
| misfire                       | boolean    | 否      | false  | 是否开启错过任务重新执行                             |
| jobExecutorServiceHandlerType | boolean    | 否      | false  | 作业线程池处理策略                                  |
| jobErrorHandlerType           | boolean    | 否      | false  | 作业错误处理策略                                    |
| description                   | String     | 否      |        | 作业描述信息                                        |
| props                         | Properties | 否      |        | 作业属性配置信息                                     |

使用脚本类型的瞬时作业可直接将脚本上传至 appURL，而无需打成 tar 包。
如果只有单个脚本文件可无需压缩。
如是复杂脚本应用，仍可上传 tar 包，支持各种常见压缩格式。

示例：

```bash
curl -l -H "Content-type: application/json" -X POST -d '{"appName":"my_app","cpuCount":0.1,"memoryMB":64.0,"jobExecutionType":"TRANSIENT","jobName":"my_job","cron":"0/5 * * * * ?","shardingTotalCount":5,"failover":true,"misfire":true}' http://elastic_job_cloud_host:8899/api/job/register
```

### 修改作业配置

url：job/update

方法：PUT

参数类型：application/json

参数：同注册作业

示例：

```bash
curl -l -H "Content-type: application/json" -X PUT -d '{"appName":"my_app","jobName":"my_job","cpuCount":0.1,"memoryMB":64.0,"jobExecutionType":"TRANSIENT","cron":"0/5 * * * * ?","shardingTotalCount":5,"failover":true,"misfire":true}' http://elastic_job_cloud_host:8899/api/job/update
```

### 注销作业

url：job/deregister

方法：DELETE

参数类型：application/json

参数：作业名称

示例：

```bash
curl -l -H "Content-type: application/json" -X DELETE -d 'my_job' http://elastic_job_cloud_host:8899/api/job/deregister
```

### 触发一次作业

url：job/trigger

方法：POST

参数类型：application/json

参数：作业名称

说明：即事件驱动，通过调用 API 而非定时的触发作业。目前仅对瞬时作业生效。

示例：

```bash
curl -l -H "Content-type: application/json" -X POST -d 'my_job' http://elastic_job_cloud_host:8899/api/job/trigger
```
# 运维手册

## 调度器部署步骤

1. 启动 ElasticJob-Cloud-Scheduler 和 Mesos 指定作为注册中心的 ZooKeeper
1. 启动 Mesos Master 和 Mesos Agent
1. 解压 `elasticjob-cloud-scheduler-${version}.tar.gz`
1. 执行 `bin\start.sh` 脚本启动 elasticjob-cloud-scheduler

## 作业部署步骤

1. 确保 ZooKeeper, Mesos Master/Agent 以及 ElasticJob-Cloud-Scheduler 已正确启动
1. 将打包作业的 tar.gz 文件放至网络可访问的位置，如：ftp或http。打包的 tar.gz 文件中 `main` 方法需要调用 ElasticJob-Cloud 提供的 `JobBootstrap.execute` 方法
1. 使用 curl 命令调用 RESTful API 发布应用及注册作业。详情请参见：[配置指南](/cn/user-manual/elasticjob-cloud/configuration)

## 调度器配置步骤

可修改 `conf\elasticjob-cloud-scheduler.properties` 文件变更系统配置。

配置项说明：

| 属性名称                  | 是否必填 | 默认值                     | 描述                                                                                       |
| ------------------------ |:------- |:------------------------- |:------------------------------------------------------------------------------------------ |
| hostname                 | 是      |                           | 服务器真实的 IP 或 hostname，不能是 127.0.0.1 或 localhost                                    |
| user                     | 否      |                           | Mesos framework 使用的用户名称                                                               |
| mesos_url                | 是      | zk://127.0.0.1:2181/mesos | Mesos 所使用的 ZooKeeper 地址                                                                |
| zk_servers               | 是      | 127.0.0.1:2181            | ElasticJob-Cloud 所使用的 ZooKeeper 地址                                                     |
| zk_namespace             | 否      | elasticjob-cloud          | ElasticJob-Cloud 所使用的 ZooKeeper 命名空间                                                  |
| zk_digest                | 否      |                           | ElasticJob-Cloud 所使用的 ZooKeeper 登录凭证                                                  |
| http_port                | 是      | 8899                      | RESTful API 所使用的端口号                                                                    |
| job_state_queue_size     | 是      | 10000                     | 堆积作业最大值, 超过此阀值的堆积作业将直接丢弃。阀值过大可能会导致 ZooKeeper 无响应，应根据实测情况调整 |
| event_trace_rdb_driver   | 否      |                           | 作业事件追踪数据库驱动                                                                         |
| event_trace_rdb_url      | 否      |                           | 作业事件追踪数据库 URL                                                                         |
| event_trace_rdb_username | 否      |                           | 作业事件追踪数据库用户名                                                                       |
| event_trace_rdb_password | 否      |                           | 作业事件追踪数据库密码                                                                         |
| auth_username            | 否      | root                      | API 鉴权用户名                                                                               |
| auth_password            | 否      | pwd                       | API 鉴权密码                                                                                 |

***

* 停止：不提供停止脚本，可直接使用 kill 命令终止进程。

## 介绍

调度器的高可用是通过运行几个指向同一个 ZooKeeper 集群的 ElasticJob-Cloud-Scheduler 实例来实现的。
ZooKeeper 用于在当前主 ElasticJob-Cloud-Scheduler 实例失败的情况下执行领导者选举。
通过至少两个调度器实例来构成集群，集群中只有一个调度器实例提供服务，其他实例处于`待命`状态。
当该实例失败时，集群会选举剩余实例中的一个来继续提供服务。

## 配置

每个 ElasticJob-Cloud-Scheduler 实例必须使用相同的 ZooKeeper 集群。
例如，如果 ZooKeeper 的 Quorum 为 zk://1.2.3.4:2181,2.3.4.5:2181,3.4.5.6:2181/elasticjob-cloud，则 `elasticjob-cloud-scheduler.properties` 中 ZooKeeper 相关配置为：

```properties
# ElasticJob-Cloud's ZooKeeper address
zk_servers=1.2.3.4:2181,2.3.4.5:2181,3.4.5.6:2181

# ElasticJob-Cloud's ZooKeeper namespace
zk_namespace=elasticjob-cloud
```

运维平台内嵌于 elasticjob-cloud-scheduler 的 jar 包中，无需额外启动 WEB 服务器。
可通过修改配置文件中 http_port 参数来调整启动端口,默认端口为 8899，访问地址为 `http://{your_scheduler_ip}:8899`。

## 登录

提供两种账户，管理员及访客，管理员拥有全部操作权限，访客仅拥有察看权限。
默认管理员用户名和密码是 root/root，访客用户名和密码是 guest/guest，可通过 `conf\auth.properties` 修改管理员及访客用户名及密码。

## 功能列表

- 应用管理（发布、修改、查看）
- 作业管理（注册、修改、查看以及删除）
- 作业状态查看（待运行、运行中、待失效转移）
- 作业历史查看（运行轨迹、执行状态、历史仪表盘）

## 设计理念

运维平台采用纯静态 HTML + JavaScript 方式与后台的 RESTful API 交互，通过读取作业注册中心展示作业配置和状态，数据库展现作业运行轨迹及执行状态，或更新作业注册中心数据修改作业配置。