> 特别说明：源码、JDK、MySQL、Redis等安装或存放路径禁止包含中文、空格、特殊字符等

## 一 项目结构

```text
yunzhupaas_scheduletask
    ├── yunzhupaas-scheduletask-client - 调度客户端配置模块
    ├── yunzhupaas-scheduletask-model- 实体模型模块
    ├── xxl-job-admin - 调度服务端
    └── xxl-job-core - 调度服务端核心模块
```

## 二 环境要求

### 2.1 开发环境

| 类目 | 版本说明或建议           |
| --- |------------------|
| 硬件 | 开发电脑建议使用I3及以上CPU，16G及以上内存  |
| 操作系统 | Windows 10/11，MacOS |
| JDK | 默认使用JDK 21，兼容JDK 8/11、JDK17（需调整部分代码），推荐使用 `OpenJDK`，如 `Liberica JDK`、`Eclipse Temurin`、`Alibaba Dragonwell`、`BiSheng` 等发行版； |
| Maven | 依赖管理工具，推荐使用 `3.6.3` 及以上版本  |
| Redis | 数据缓存，推荐使用 `5.0` 及以上版本 |
| 数据库 | 兼容 `MySQL 5.7.x/8.x`、`SQLServer 2012+`、`Oracle 11g`、`PostgreSQL 12+`、`达梦数据库(DM8)`、`人大金仓数据库(KingbaseES_V8R6)` |
| IDE   | 代码集成开发环境，推荐使用 `IDEA2024` 及以上版本，兼容 `Eclipse`、 `Spring Tool Suite` 等IDE工具 |

### 2.2 运行环境

> 服务端运行环境，适用于测试或生产环境

| 类目 | 版本说明或建议                               |
| --- |-----------------------------------------------|
| 服务器配置 | 建议至少在 4C/16G/50G 的机器配置下运行；|
| 操作系统 | 建议使用 `Windows Server 2019` 及以上版本或主流 `Linux` 发行版本，推荐使用 `Linux` 环境；兼容 `统信UOS`，`OpenEuler`，`麒麟服务器版` 等信创环境；    |
| JRE | 默认使用JRE 21，兼容JRE 8/11、JRE17（需调整部分代码）；推荐使用 `OpenJDK`，如 `Liberica JDK`、`Eclipse Temurin`、`Alibaba Dragonwell`、`BiSheng` 等发行版；   |
| Redis | 数据缓存，推荐使用 `5.0` 及以上版本 |
| 数据库 | 兼容 `MySQL 5.7.x/8.x`、`SQLServer 2012+`、`Oracle 11g`、`PostgreSQL 12+`、`达梦数据库(DM8)`、`人大金仓数据库(KingbaseES_V8R6)` |

## 三 关联项目

> 为以下项目提供基础依赖

| 项目 | 分支 |  说明 |
| --- | --- | --- |
| yunzhupaas-common  | v5.2.x-stable | Java基础依赖项目源码 |
| yunzhupaas-java-boot | v5.2.x-stable | Java单体后端项目源码 |
| yunzhupaas-java-cloud | v5.2.x-stable | Java微服务后端项目源码 |

## 四 使用方式

> 本项目为任务调度的基础依赖和服务端，<br/>作为客户端依赖时需要上传到私服或使用本地安装的方式引用该项目，<br/>作为服务端时需要单独部署

### 4.1 作为客户端依赖

#### 4.1.1 前置条件

##### 4.1.1.1 本地安装yunzhupaas-common-core

IDEA中打开 `yunzhupaas-common` 项目， 双击右侧 `Maven` 中 `yunzhupaas-common` > `yunzhupaas-boot-common` > `yunzhupaas-common-core` > `Lifecycle` > `install`，将 `yunzhupaas-common-core` 包安装至本地

##### 4.1.1.2 本地安装dependencies

IDEA中打开 `yunzhupaas-common` 项目，双击右侧 `Maven` 中 `yunzhupaas-common` > `yunzhupaas-dependencies` > `Lifecycle` > `install`，将 `yunzhupaas-dependencies` 包安装至本地

#### 4.1.2 本地安装

在IDEA中，双击右侧 `Maven` 中 `yunzhupaas-scheduletask-starter` > `Lifecycle` > `install`，将 `yunzhupaas-scheduletask-client` 包安装至本地

#### 4.1.3 私服发布
> 若无Maven私服，忽略本节内容

##### 4.1.3.1 配置Maven

打开Maven安装目录中的 `conf/setttings.xml`，

在 `<servers></servers>` 节点增加 `<server></server>` ，如下所示:

```xml
  <!-- 发布版 -->
  <server>
    <id>maven-releases</id>
    <username>admin（账号，结合私服配置设置）</username>
    <password>123456（密码，结合私服配置设置）</password>
  </server>
```

##### 4.1.3.2 配置项目

> 注意：pom.xml里 `<id>` 和 setting.xml 配置里 `<id>` 对应。

IDEA打开 `yunzhupaas-common` 项目, 修改 `yunzhupaas-dependencies/pom.xml` 文件中私服配置

```xml
<distributionManagement>
    <repository>
        <id>maven-releases</id>
        <name>maven-releases</name>
        <url>http://nexus.yunzhupaas.com/repository/maven-releases/</url>
    </repository>
</distributionManagement>
```

##### 4.1.3.3 发布到私服

在IDEA中，双击右侧 `Maven` 中 `yunzhupaas-scheduletask-starter` > `Lifecycle` > `deploy` 发布至私服。

### 4.2 作为服务端

#### 4.2.1 项目配置

##### 4.2.1.1 调整运行端口
> 根据实际需求调整

打开编辑 `xxl-job-admin/src/main/resources/application.yml`，第 19 行

```yaml
  port: 30020
```

##### 4.2.1.2 指定环境配置

打开编辑 `xxl-job-admin/src/main/resources/application.yml`，第 25 行

环境说明：

- `application-dev.yml` 开发环境(默认)
- `application-preview.yml` 预生产环境
- `application-test.yml` 测试环境
- `application-prod.yml` 生产环境

> 以开发环境为例，根据实际需求修改

```yaml
# application.yml第 6 行,可选值：dev(开发环境-默认)、test(测试环境)、preview(预生产环境)、prod(生产环境)
active: dev
```

#### 4.2.1 数据源配置

打开 `xxl-job-admin/src/main/resources/application-dev.yml` 修改数据源，配置示例如下：

##### 4.2.1.1 MySQL数据库

```yaml
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/yunzhupaas_xxljob?useUnicode=true&characterEncoding=utf-8&allowMultiQueries=true&serverTimezone=GMT%2B8&useSSL=false
    username: root
    password: 123456
    driver-class-name: com.mysql.cj.jdbc.Driver
```

##### 4.2.1.2 SQLServer数据库

```yaml
  datasource:
    url: jdbc:sqlserver://127.0.0.1:1433;SelectMethod=cursor;Databasename=yunzhupaas_xxljob
    username: sa
    password: 123456
    driver-class-name: com.microsoft.sqlserver.jdbc.SQLServerDriver
```

##### 4.2.1.3 Oracle数据库

```yaml
  datasource:
    url: jdbc:oracle:thin:@127.0.0.1:1521:orcl
    username: YUNZHUPAAS_XXLJOB
    password: dbpasswd
    driver-class-name: oracle.jdbc.OracleDriver
```

##### 4.2.1.4 PostgreSQL数据库

```yaml
  datasource:
    url: jdbc:postgresql://127.0.0.1:5432/yunzhupaas_xxljob
    username: dbuser
    password: dbpasswd
    driver-class-name: org.postgresql.Driver
```

##### 4.2.1.5 达梦dm8数据库

```yaml
  datasource:
    url: jdbc:dm://127.0.0.1:5236/YUNZHUPAAS_XXLJOB?yunzhupaasDateTimeBehavior=convertToNull&useUnicode=true&characterEncoding=utf-8
    username: dbuser
    password: dbpasswd
    driver-class-name: dm.jdbc.driver.DmDriver
```

##### 4.2.1.6 人大金仓KingbaseES数据库

```yaml
  datasource:
    url: jdbc:kingbase8://127.0.0.1:54321/yunzhupaas_xxljob
    username: dbuser
    password: dbpasswd
    driver-class-name: com.kingbase8.Driver
```

#### 4.2.2 打包部署

在IDEA中，在左侧 `Project` 中，右击 `yunzhupaas-scheduletask` > `xxl-job-admin` > `pom.xml` 并选择 `Add as Maven Project` 将 `xxl-job-admin` 转为 Maven 项目，然后双击右侧 `Maven` 中 `xxl-job-admin` > `Lifecycle` > `package`， 将 `/xxl-job-admin/target/xxl-job-admin-5.0.0-RELEASE.jar` 上传至服务器部署即可。

#### 4.2.3 关联项目配置

配置如下所示

```yaml
# ===================== 任务调度配置 =====================
xxl:
  job:
    accessToken: '432e62f3b488bc861d91b0e274e850cc'
    i18n: zh_CN
    logretentiondays: 30
    triggerpool:
      fast:
        max: 200
      slow:
        max: 100
    admin:
      # xxl-job服务端地址
      addresses: http://127.0.0.1:30020/xxl-job-admin/
    executor:
      address: ''
      appname: xxl-job-executor-sample1
      ip: ''
      logpath: /data/applogs/xxl-job/jobhandler
      logretentiondays: 30
      port: 9999
```

##### 4.2.3.1 yunzhupaas-java-boot项目

IDEA打开 `yunzhupaas-java-boot` 项目, 编辑 `yunzhupaas-admin/src/main/resources/application-x.yml` 文件( `application-x.yml` 为环境配置，如 `application-dev.yml` )

##### 4.2.3.2 yunzhupaas-java-cloud项目

登录 `Nacos` 控制台，依次点击 `配置管理` >  `配置列表` > `develop`，编辑 `datasource-scheduletask.yaml`。
