开源大数据平台 DataLight 开发手册

DataLight 开发手册

本手册将基于参与贡献的进度与问题反馈持续更新，旨在帮助开发者更快地理解应用并参与到本开源项目中。

对于那些需要将一些额外服务对接集成进来的开发者而言，借助该手册可以辅助实现 plugin 开发过程。

一、项目结构

本项目采用统一的开发语言和工具，包括 Gradle、Java、Maven 以及 Bash 等。以下是项目的核心目录结构说明。

- boundivore-datalight
	- datalight-api         -- 所有 API 定义所在的父 Module
        - api-master          		-- Master 进程 API 统一在该 Module 中定义
        - api-third           		-- 第三方服务调用的 API 统一在该 Module 中定义
        - api-worker          		-- Worker 进程 API 统一在该 Module 中定义
    - datalight-common		-- 基础常用工具封装父 Module
        - common-base         		-- REQUEST、PO、常量、枚举等相关内容
        - common-boot         		-- SpringBoot 通用依赖项、通用注入项、配置项等
        - common-cloud        		-- SpringBoot 与 SpringGateway(将来需要可引入) 等共用的依赖与注入等
        - common-exception    		-- 自定义异常封装
    - datalight-orm          -- 数据库 PO 与对应数据库 Service Mapper 封装
    - datalight-plugins      -- 服务组件插件功能父 Module，可用于反射热加载
        - plugins-base        		-- 插件通用封装、统一抽象
        - plugins-flink       		-- FLINK 部署配置与配置联动相关逻辑
        - plugins-hbase       		-- HBASE 部署配置与配置联动相关逻辑
        - plugins-hdfs        		-- HDFS 部署配置与配置联动相关逻辑
        - plugins-hive        		-- HIVE 部署配置与配置联动相关逻辑
        - plugins-kafka       		-- KAFKA 部署配置与配置联动相关逻辑
        - plugins-kubesphere  		-- KUBESPHERE 部署配置与配置联动相关逻辑
        - plugins-monitor     		-- MONITOR 部署配置与配置联动相关逻辑
        - plugins-spark       		-- SPARK 部署配置与配置联动相关逻辑
        - plugins-yarn        		-- YARN 部署配置与配置联动相关逻辑
        - plugins-zkui        		-- ZKUI 部署配置与配置联动相关逻辑
        - plugins-zookeeper   		-- ZOOKEEPER 部署配置与配置联动相关逻辑
        - ...                 		-- 未来支持的更多服务组件时，每新增一个服务，将对应一个该服务的插件 Module
    - datalight-services      	-- Master 与 Worker 主程序父 Module
        - services-master     		-- Master 用于管理各个服务组件、Worker、节点等生命周期管理，API 策略管理等。
        - services-worker     		-- Worker 用于管理当前所在节点的具体执行，接收 Master 指令。
    - datalight-starter-parent  -- 常用工具启动器
        - starter-aigc-qianfan 		-- 百度 AIGC 模型启动器
        - starter-redis       		-- Redis 操作启动器，包括 redis 分布式锁等
        - starter-ssh         		-- Java SSH 启动器封装
        - starter-zookeeper   		-- Zookeeper 启动器封装，主要用于基于 Zookeeper 分布式锁的操作

二、目录结构

2.1 文档与工具类

在本项目中，.documents 中以不同形式的文件记录了项目的相关说明，其中包括文本说明、工具脚本、配置文件等，下面对目录结构进行说明。

注：这部分文档主要用于开发时使用，因此会直接伴随整个项目提交并更新至 Git。

- .documents -------------------------- 文件记录根目录
  - app ------------------------------- 该目录存放 master 与 worker 可运行 jar 包（jar 包不可上传至 git）
    - config -------------------------- master、worker 的 spring、logback 配置文件
  - assistant ------------------------- 初始化节点工具包目录
    - conf ---------------------------- 包括初始化节点的配置文件
    - main ---------------------------- 包括初始化节点的可执行脚本，包括总体执行脚本与单节点执行脚本
    - repo ---------------------------- 包括可选配的离线 yum 包（该目录内容不可上传至 git）
    - scripts ------------------------- 包括不同初始化项对应的脚本
  - bin ------------------------------- 包括master、worker 的生命周期管理脚本，包括启停等
  - conf ------------------------------ 包括节点环境变量配置脚本与服务组件配置脚本
    - env ----------------------------- 节点环境变量配置脚本
    - permission ---------------------- 包括权限配置清单（暂废弃留档）
    - service ------------------------- 包括服务组件生命周期管理配置项（部署，启停，配置等）
    - web ----------------------------- 包括服务组件 UI 配置项
  - docs ------------------------------ 文本文档根目录
    - api ----------------------------- 三方 API 留档目录，可导入 API 工具
      - kube -------------------------- K8S、KUBESPHERE 相关 API
    - assets -------------------------- 资源文件夹（文档中包含的图片引用等）
    - package ------------------------- 服务组件编译打包记录文件夹
      - maven ------------------------- Maven settings.xml 留档文件
      - src-[服务名称]-[服务版本号] ---- 服务组件源码修改记录
  - exporter -------------------------- JMX Exporter 留档记录
    - bin ----------------------------- 启动脚本配置示例
    - conf ---------------------------- JMX 配置文件
    - jar ----------------------------- JMX exporter 可挂载 jar 包
  - node ------------------------------ 节点服役配置根目录
    - conf ---------------------------- 包括生命周期管理配置、节点服役管理配置等
    - scripts ------------------------- 节点服役操作配置脚本、检查节点合法性脚本等
  - orm ------------------------------- 数据库设计根目录
    - dmj ----------------------------- 数据库设计模型
    - query --------------------------- 可能使用到的数据库 SQL 查询语句（调试留档）
    - sql ----------------------------- 数据库模型 SQL 文件
  - plugins --------------------------- 服务组件插件根目录
    - [服务名称] ----------------------- 每一个服务名对应一个文件夹
      - dlc --------------------------- 服务组件编译后的打包文件（.tar.gz，不可上传到 git）
      - jars -------------------------- 包括服务组件插件 jar 包（不可上传到 git）
      - placeholder ------------------- 包括部署前当前服务预配置项配置文件
      - scripts ----------------------- 包括服务组件生命周期管理过程中可能使用到的脚本
      - templated --------------------- 包括服务组件的配置文件模板（不同的服务，该目录下的其他目录和文件可能会不同）
  - scripts --------------------------- 通用脚本文件根目录
    - tools --------------------------- 运维过程中可能使用到的运维脚本留档

2.2 部署目录结构

DataLight 部署目录结构，用于实际的生产环境部署和管理，其中大多数目录与上述 2.1 中的内容相同。

- datalight -------------------------- DataLight 部署根目录
  - app ------------------------------ 同2.1，注意在其中放置编译后的 master、worker jar 包
  - assistant ------------------------ 同2.1
  - bin ------------------------------ 同2.1
  - conf ----------------------------- 同2.1
  - docs ----------------------------- 同2.1
  - exporter ------------------------- 同2.1
  - node ----------------------------- 同2.1
  - orm ------------------------------ 同2.1
  - plugins -------------------------- 同2.1，注意在其下各个服务对应的文件夹的 dlc 目录下放置服务包(.tar.gz) 与 jar 目录下放置 plugin 编译后的插件 jar 文件
  - scripts -------------------------- 同2.1

三、核心配置文件说明

介绍项目中的核心配置文件，包括服务清单配置、服务管理配置、服务 UI 配置以及节点管理配置文件的详细说明。

3.1 服务清单配置文件

定义项目中各服务的清单信息，包括服务名称、类型、优先级及其依赖关系等。

文件名：0-SERVICE-MANIFEST.yaml

datalight: 
  dlc-version: 1.0.0 # 当前 DLC 版本
  deploy: # 部署行为
    services: # 支持部署的服务列表，下面的每一个 service 都将对应一个 [服务名称].yaml 文件
      - name: MONITOR # 服务名称
        type: BASE # 服务类型，包括：BASE基础服务、STORAGE存储服务、COMPUTE计算服务
        priority: 1 # 服务部署优先级，部署时，将按照优先级顺序部署（数字越小，优先级越高），逆向操作时反之（例如批量关闭）
        desc: '监控与告警基础服务' # 服务描述
        dependencies: [ ] # 当前服务依赖的其他服务
        optional-dependencies: [ ] # 当前服务可选的依赖其他服务
        relatives: [ ] # 当前服务可能会影响到的其他服务
  ...

3.2 服务管理配置文件

定义项目中各服务的清单信息，包括服务名称、类型、优先级及其依赖关系等。

文件名：[服务名称].yaml

以 FLINK 为例，列举主要配置含义

datalight:
  service:
    name: FLINK # 服务名称
    version: 1.19.0 # 服务版本
    tgz: dlc-flink-1.19.0.tar.gz # 服务的 DLC 资源包
    conf-dirs: # 配置文件映射列表
      - service-conf-dir: '{{SERVICE_DIR}}/FLINK/exporter/conf' # 服务部署时需要配置的文件目录
        templated-dir: '{{DATALIGHT_DIR}}/plugins/FLINK/templated/exporter/conf' # 本地配置文件模板目录

      - service-conf-dir: '{{SERVICE_DIR}}/FLINK/bin' # 同上
        templated-dir: '{{DATALIGHT_DIR}}/plugins/FLINK/templated/bin' # 同上

      - service-conf-dir: '{{SERVICE_DIR}}/FLINK/conf' # 同上
        templated-dir: '{{DATALIGHT_DIR}}/plugins/FLINK/templated/conf' # 同上

    config-event-handler-jar: 'plugins-flink-1.0.0.jar' # 当前服务插件 jar 包名称
    config-event-handler-clazz: 'cn.boundivore.dl.plugin.flink.config.event.ConfigEventHandler' # 当前服务插件配置类入口

    initialize: # 当前服务在当前节点的通用初始化步骤
      steps: # 初始化步骤列表，步骤类型包括：COMMON_SCRIPT、SCRIPT、COMMAND 等
        - type: COMMON_SCRIPT # 执行 datalight/scripts 目录下的指定脚本
          name: '清理过期的部署环境'
          shell: 'service-remove.sh' # 脚本名称
          args: [ ] # 脚本参数数组
          interactions: [ ] # 脚本可交互数组
          exits: '0' # 期望脚本退出码，当脚本执行后，满足该退出码，视为执行成功
          timeout: 10000 # 脚本执行超时时间（单位：毫秒）
          sleep: 0 # 脚本执行后等待时间（单位：毫秒）

        - type: COMMON_SCRIPT
          name: '初始化部署服务所需的环境'
          shell: 'service-init-env.sh'
          args: [ ]
          interactions: [ ]
          exits: '0'
          timeout: 60000
          sleep: 0

        - type: JAR # 执行指定 jar 包
          name: '初始化服务配置文件'
          jar: 'plugins-flink-1.0.0.jar' # jar 包名称
          clazz: 'cn.boundivore.dl.plugin.flink.config.ConfigFLINK' # 执行入口
          args: [ ] # JAR 类型的 step，该项暂无效，保持统一，暂留
          interactions: [ ] # JAR 类型的 step，该项暂无效，保持统一，暂留
          exits: '0' # JAR 类型的 step，该项暂无效，保持统一，暂留
          sleep: 0 # 同上

    components: # 可操作的组件列表
      - name: FlinkHistoryServer # 组件名称
        priority: 1 # 在当前服务下，该组件操作的优先级
        max: 1 # 当决定部署该服务时，当前组件整个集群中 最大 部署实例数限制
        min: 1 # 当决定部署该服务时，当前组件整个集群中 最小 部署实例数限制
        mutexes: [ ] # 当前组件与哪些组件互斥，即不可部署同一个节点
        dependencies: [ 'YARNClient' ] # 当前组件与哪些组件依赖，即必须同时在同一节点中存在
        actions:
          - type: DEPLOY # 部署行为
            start-state: DEPLOYING # 执行时组件状态
            success-state: STARTED # 成功时组件状态
            fail-state: SELECTED # 失败时组件状态
            steps: 
              - type: SCRIPT # 默认执行 datalight/plugins/[当前服务名称]/scripts 下的脚本
                name: '检查并初始化 Flink 日志目录'
                shell: 'flink-check-hdfs-dir.sh'
                args: [ ]
                interactions: [ ]
                exits: '0'
                timeout: 60000
                sleep: 0

              - type: SCRIPT
                name: '部署后启动 FlinkHistoryServer'
                shell: 'flink-operation.sh'
                args: [ 'FlinkHistoryServer', 'start' ]
                interactions: [ ]
                exits: '0'
                timeout: 60000
                sleep: 1000

          - type: START
            start-state: STARTING
            success-state: STARTED
            fail-state: STOPPED
            steps:
              - type: SCRIPT
                name: '启动 FlinkHistoryServer'
                shell: 'flink-operation.sh'
                args: [ 'FlinkHistoryServer', 'start' ]
                interactions: [ ]
                exits: '0'
                timeout: 60000
                sleep: 1000

          - type: STOP
            start-state: STOPPING
            success-state: STOPPED
            fail-state: STARTED
            steps:
              - type: SCRIPT
                name: '停止 FlinkHistoryServer'
                shell: 'flink-operation.sh'
                args: [ 'FlinkHistoryServer', 'stop' ]
                interactions: [ ]
                exits: '0'
                timeout: 60000
                sleep: 1000

          - type: RESTART
            start-state: RESTARTING
            success-state: STARTED
            fail-state: STOPPED
            steps:
              - type: SCRIPT
                name: '重启 FlinkHistoryServer'
                shell: 'flink-operation.sh'
                args: [ 'FlinkHistoryServer', 'restart' ]
                interactions: [ ]
                exits: '0'
                timeout: 60000
                sleep: 1000

      - name: FlinkClient
        priority: 2
        max: -1
        min: 0
        mutexes: [ ]
        dependencies: [ ]
        actions:
          - type: DEPLOY
            start-state: DEPLOYING
            success-state: STARTED
            fail-state: SELECTED
            steps:
              - type: COMMAND
                name: '正在完成 FLINKClient 部署'
                shell: 'echo done'
                args: [ ]
                interactions: [ ]
                exits: '0'
                sleep: 0

          - type: START
            start-state: STARTING
            success-state: STARTED
            fail-state: STOPPED
            steps:
              - type: COMMAND
                name: '启动 FLINKClient'
                shell: 'echo done'
                args: [ ]
                interactions: [ ]
                exits: '0'
                timeout: '0'
                sleep: 0

          - type: STOP
            start-state: STOPPING
            success-state: STOPPED
            fail-state: STARTED
            steps:
              - type: COMMAND
                name: '停止 FLINKClient'
                shell: 'echo done'
                args: [ ]
                interactions: [ ]
                exits: '0'
                timeout: '0'
                sleep: 0

          - type: RESTART
            start-state: RESTARTING
            success-state: STARTED
            fail-state: STOPPED
            steps:
              - type: COMMAND
                name: '重启 FLINKClient'
                shell: 'echo done'
                args: [ ]
                interactions: [ ]
                exits: '0'
                timeout: '0'
                sleep: 0

3.3 服务 UI 配置文件

定义项目中各服务的清单信息，包括服务名称、类型、优先级及其依赖关系等。

文件名：COMPONENT-WEB-UI.yaml

datalight:
  components: # 包含官方 UI 的服务组件列表
    - service: MONITOR # 服务名称
      component: Prometheus # 该服务下组件名称
      port: '9090' # 该组件 UI 端口号
      path: '/graph' # 该组件 UI Path
      button-name-suffix: '-Web UI' # 前端按钮文案展示后缀名

    - service: MONITOR
      component: Grafana
      port: '3000'
      path: '/'
      button-name-suffix: '-Web UI'

    - service: HDFS
      component: NameNode1
      port: '50070'
      path: '/dfshealth.html#tab-overview'
      button-name-suffix: '-Web UI'

...

3.4 节点管理配置文件

定义项目中各服务的清单信息，包括服务名称、类型、优先级及其依赖关系等。

文件名：node-action.yaml

datalight: # 以下为针对节点操作的相关配置
  actions:
    # 关机
    - type: SHUTDOWN
      start-state: STOPPING # 开始执行时节点状态
      success-state: STOPPED # 执行成功时节点状态
      fail-state: STARTED # 执行失败时节点状态
      steps:
        - type: SCRIPT # 默认执行 datalight/node/scripts 下的脚本
          name: '关机节点' # 当前步骤名称
          shell: 'action-shutdown.sh' # 脚本名称
          args: [ ]
          interactions: [ ]
          exits: '0'
          timeout: 60000
          sleep: 0

    # 重启
    - type: RESTART
      start-state: RESTARTING
      success-state: RESTARTING
      fail-state: RESTARTING
      steps:
        - type: SCRIPT
          name: '重启节点'
          shell: 'action-restart.sh'
          args: [ ]
          interactions: [ ]
          exits: '0'
          timeout: 60000
          sleep: 0

    # 探测节点
    - type: DETECT
      start-state: DETECTING
      success-state: ACTIVE
      fail-state: INACTIVE
      steps:
        - type: SCAN
          name: '探测节点 SSH 可用性'
          sleep: 0

        - type: SCAN_RESOURCES
          name: '扫描节点资源'
          shell: "scan-resources.sh"
          args: [ ]
          interactions: [ ]
          exits: '0'
          timeout: 60000
          sleep: 0

    # 初始化检查
    - type: CHECK
      start-state: CHECKING
      success-state: CHECK_OK
      fail-state: CHECK_ERROR
      steps:
        - type: CHECK_ENV
          name: '检查节点环境'
          shell: 'check-env.sh'
          args: [ ]
          interactions: [ ]
          exits: '0'
          timeout: 60000
          sleep: 0

    # 推送安装包
    - type: DISPATCH
      start-state: PUSHING
      success-state: PUSH_OK
      fail-state: PUSH_ERROR
      steps:
        - type: PUSH
          name: '推送安装包'

    # 拉起节点上的 Worker 进程
    - type: START_WORKER
      start-state: STARTING_WORKER
      success-state: START_WORKER_OK
      fail-state: START_WORKER_ERROR
      steps:
        - type: SCRIPT
          name: '启动节点 Worker'
          shell: 'action-master-worker.sh'
          args: [ 'restart', 'worker', '8002' ]
          interactions: [ ]
          exits: '0'
          timeout: 60000
          sleep: 0

四、打包方式

描述项目中 Master/Worker 和插件的打包方法，包括所需工具、编译步骤和文件拷贝路径等。

4.1 Master/Worker 打包方式

• 工具

  # Gradle 7.4 +
  # JDK 1.8 +
  

• 编译

  前往 datalight-services 模块根目录执行：

  注：请提前配置好 gradle 环境变量

  gradle bootJar
  

• 拷贝

  编译后的文件存放于下面的路径（示例为相对路径），可自行拷贝至部署目录。

  boundivore-datalight/datalight-services/services-master/build/libs/services-master-x.x.x.jar
  boundivore-datalight/datalight-services/services-master/build/libs/services-worker-x.x.x.jar
  

4.2 Plugins 打包方式

• 工具

  # Gradle 7.4 +
  # JDK 1.8 +
  

• 编译

• 前往 datalight-plugins 模块根目录执行：

  gradle jar
  

• 拷贝

  编译后的文件存放于下面的路径（示例为相对路径），可自行拷贝至部署目录，以 HDFS 为例：

  boundivore-datalight/datalight-plugins/plugins-hdfs/build/libs/plugins-hdfs-1.0.0.jar
  

未来持续研发计划

该部分内容将通过多种形式在讨论群中更新，保持项目的持续发展。

参与开源

如果您对本项目感兴趣，欢迎提供积极的反馈，帮助该项目做的更好。

微信公众号：

QQ 交流群：

微信交流：

开源协议

本项目采用 Apache 2.0 开源协议。有关详细内容，请查看 Apache 2.0 LICENSE。