Merge pull request #26 from liuyou2/main

Update dss1.1.0 version document

Author: zqburde

zh_CN/Images/DSS-UserGuide模块设计/1653309535303.png

@@ -0,0 +1,92 @@
+# DSS基于标签的路由转发
+
+## 引言
+
+标签是DSS1.0新引入的概念，在DSS框架中有很多地方使用了标签，作为转发路由的依据。比如在DSS的多环境支持中，每个请求都是带有环境标签的，如DEV、PROD等。这些可以用来确定当前请求是发送给哪个服务，或者当前应该使用哪一个AppConn Instance。
+
+## 标签的格式
+
+route类型标签
+
+```
+labels={"route":"dev"}
+```
+
+Get类型请求
+
+```
+dssurl?labels=dev
+```
+
+上面两种是比较常见的DSS中用于Label的格式
+
+## 基于标签的路由转发
+
+1、服务的转发
+
+服务的转发是指将HTTP请求基于标签的匹配转发给对应的服务实例，当前主要由DSS-GateWay来实现，通过定义DSS-GateWay插件，部署到Linkis-GateWay的lib目录下，就可以实现将DSS的请求转发给DSS的服务实例。
+
+* 直接从请求中获取标签，当前的DSS请求中都包含了类似DEV或者PROD的环境标签，GET类型的请求直接在URl的参数中，POST类型的请求则放在请求的body中，以json的格式进行提交。DSS-GateWay在拦截到发送给DSS的请求后，就会解析请求中带的标签和服务名称。然后根据服务名称和标签，去注册中心如Euraka等查找对应的服务实例，按照匹配规则，当完全匹配服务名时优先发送给该服务实例，有多个同级别的则随机选中一个进行发送。当不能完全匹配时，则发送给匹配相近度最高的服务实例，当完全没有匹配时，则发送给默认的DSS服务实例project。
+  
+```
+object DSSGatewayParser {
+    //DSS的URL提取正则匹配规则，可以参考DSS的前端请求URL进行分析
+  val DSS_HEADER = normalPath(API_URL_PREFIX) + "rest_[a-zA-Z][a-zA-Z_0-9]*/(v\\d+)/dss/"
+  val DSS_URL_REGEX = (DSS_HEADER + "([^/]+)/" + "([^/]+)/.+").r
+  val DSS_URL_DEFAULT_REGEX = (DSS_HEADER + "([^/]+).+").r
+  
+  //该方法主要用于AppConn的应用，如Visualis的url提取
+  val APPCONN_HEADER = normalPath(API_URL_PREFIX) + "rest_[a-zA-Z][a-zA-Z_0-9]*/(v\\d+)/([^/]+)/"
+  val APPCONN_URL_DEFAULT_REGEX = (APPCONN_HEADER + "([^/]+).+").r
+
+}
+```
+
+* RouteLabelParser  在应用中引入Linkis的Label相关的依赖，然后在应用的yaml中定义服务的标签名称，那么在服务启动后，就会带上标签的元数据信息向注册中心注册，这是每个服务在注册中心都是有标签的，也可能存在多个标签的情况。然后在Linkis的GateWay中实现RouteLabelParser，并在GateWay拦截到请求后，在parse中解析出相关的route类型标签列表，再由Linkis-gateway基于标签的转发规则进行请求转发。这个是另外一种基于标签的转发，要求使用Linkis中标签模块。
+
+```
+    <dependency>
+        <groupId>org.apache.linkis</groupId>
+        <artifactId>linkis-instance-label-client</artifactId>
+        <version>${linkis.version}</version>
+    </dependency>
+```
+
+2、AppConn Instance转发
+
+在DSS1.0中使用了AppConn的概念，并替换了原来的AppJoint，以AppConn的方式集成第三方系统。且AppConn最大特点就是能支持多应用实例，每个应用实例都有自己的标签。在数据库中新增一张表dss_appconn_instance的表：
+
+```
+CREATE TABLE `dss_appconn_instance` (
+  `id` int(20) NOT NULL AUTO_INCREMENT COMMENT '主键',
+  `appconn_id` int(20) NOT NULL COMMENT 'appconn的主键',
+  `label` varchar(128) NOT NULL COMMENT '实例的标签',
+  `url` varchar(128) DEFAULT NULL COMMENT '访问第三方的url',
+  `enhance_json` varchar(1024) DEFAULT NULL COMMENT 'json格式的配置',
+  `homepage_uri` varchar(255) DEFAULT NULL COMMENT '主页uri',
+  PRIMARY KEY (`id`)
+) ENGINE=InnoDB AUTO_INCREMENT=66 DEFAULT CHARSET=utf8mb4 COMMENT='dss instance的实例表';
+```
+
+在每个AppConn进行部署的时候，就会在DSS中注册它的的AppConn的Instance信息。并使用上面的数据库表记录该实例对应的标签、访问地址、主页地址、配置信息等。
+
+当每个appConn实例有了标签以后，在DSS的框架中就会在每次和AppConn进行接口交互时，都会根据当前请求的标签信息，查找对应的操作实例对象，再向该对象发送具体的请求。
+
+```
+ //从执行参数中获取标签内容
+ val labels = engineExecutorContext.getProperties.get("labels").toString
+    //根据标签内容和加载的AppConn，获取对应的appconn实例
+    getAppInstanceByLabels(labels, appConn) match {
+      case Some(appInstance) =>
+        val developmentIntegrationStandard = appConn.asInstanceOf[OnlyDevelopmentAppConn].getOrCreateDevelopmentStandard
+        //根据实例信息，从开发规范中获取对应的执行服务
+        val refExecutionService = developmentIntegrationStandard.getRefExecutionService(appInstance)
+```
+
+DSS中标签请使用EnvDSSLabel，包含标签的key和Value。继承自linkis中标签体系GenericLabel。
+
+```
+//构建一个DSS的标签对象，默认的key为：DSSEnv
+DSSLabel envDSSLabel = new EnvDSSLabel(rollbackOrchestratorRequest.getLabels().getRoute());
+```
+

zh_CN/Images/DSS-UserGuide模块设计/1653309707841.png

@@ -0,0 +1,82 @@
+# DSS接入调度系统
+
+## 背景
+
+目前应用于大数据领域的批量定时调度系统有很多，如Azkaban、Dophinscheduler、Airflow等，DataSphereStudio(DSS)支持将用户设计好的工作流，发布到不同的调度系统进行调度，当前默认支持了发布到Azkaban。用户在DSS中完成了工作流的DAG设计，包含工作流资源文件加载、工作流参数设置，数据导入、数据质量检查、节点代码编写，可视化报表设计、邮件输出、节点资源文件上传和运行参数设置等操作后，可在DSS中调试执行，验证所有节点的可执行正确后，发布到调度系统 ，由调度系统根据定时任务的配置，定时调度执行。
+
+### 发布方式
+
+DSS集成新的调度系统需要使用AppConn的方式接入，用户需要根据不同调度系统定义对应的XXXSchedulerAppConn, 在SchedulerAppConn中定义了转换集成规范和结构化集成规范。转换集成规范包含DSS工程级别内容和DSS工作流级别内容到第三方调度系统的转换。DSS同调度系统的接入可以分为以下两种：
+
+1、工程级别发布
+
+是指将工程内的所有工作流进行转换，并把转换后的内容统一打包上传给调度系统。主要有ProjectPreConversionRel接口，定义了工程内需要转换的工作流。
+
+2、工作流级别发布
+
+是指按照工作流的粒度进行转换，只打包工作流的内容上传给调度系统。当前DSS的工作流定义都是以Json的方式存储在BML文件中，工作流的元数据信息则存储在数据库中。
+
+
+## 主要步骤
+
+### Parser
+
+JsonToFlowParser   用于将工作流的Json转换成Workflow,Workflow是DSS中操作工作流的标准格式，包含了工作流的节点信息，工作流的边信息、父工作流、子工作流、工作流资源文件、工作流属性文件、工作流创建时间、更新时间、工作流用户、工作流代理用户、工作流的元数据信息如名称、ID、描述、类型、是否根工作流等。这些都是根据Json的内容进行解析，转成DSS可操作的Workflow对象，如AzkabanWorkflow、DolphinSchedulerWorkflow。
+
+### Converter
+
+把DSS的Workflow转成接入调度系统可以识别的工作流, 每个调度系统对于工作流都有自己的定义。如果把DSS工作流的节点转成Azkaban的job格式文件，或者转成DolphinScheduler的task, 也可以反过来转换，将调度系统的工作流转成DSS可以加载和展示的工作流，把工作流的依赖关系，节点的连线转成对应调度系统的依赖。还可在Converter中检查该项目下的工作流节点是否存在重名的节点，如在Azkaban的调度系统中是不允许使用重名节点的。
+
+WorkflowConVerter 定义工作流转换输出目录结构，包括工作流的存储目录、工作流资源文件存储、子工作流存储目录建立等。如Azkaban在工程级别的转换操作中还包括建立项目转换的目录，并根据工程内的工作流情况建立工作流的转换目录。在convertToRel中实现把Workflow转成dolphinSchedulerWorkflow或者SchedulisWorkFlow
+
+NodeConverter 定义节点转换输出内容：如Azkaban的ConvertNode,会把工作流的节点内容转成对应的Job文件内容。包括转换节点的名称、类型、依赖关系、节点的执行命令（依赖linkis-jobtype解析）、节点的配置参数、节点的标签等内容。最终按照Job文件定义的格式进行存储。DolphinScheduler的Converter将DSS中节点转为 DolphinScheduler 中 task，并构建Shell类型Task的执行脚本，将DSS的节点内容转成自定义的dss-dolphinscheduler-client.sh脚本执行所需要的参数。
+
+```--java
+            addLine.accept("LINKIS_TYPE", dssNode.getNodeType());   //工作流节点类型
+            addLine.accept("PROXY_USER", dssNode.getUserProxy());   //代理用户
+            addObjectLine.accept("JOB_COMMAND", dssNode.getJobContent()); //执行命令
+            addObjectLine.accept("JOB_PARAMS", dssNode.getParams());      //节点执行参数
+            addObjectLine.accept("JOB_RESOURCES", dssNode.getResources()); //节点执行资源文件
+            addObjectLine.accept("JOB_SOURCE", sourceMap);                 //节点的source信息
+            addLine.accept("CONTEXT_ID", workflow.getContextID());         //上下文ID
+            addLine.accept("LINKIS_GATEWAY_URL", Configuration.getGateWayURL());  //linkis的gateway地址
+            addLine.accept("RUN_DATE", "${system.biz.date}");                    //运行日期变量
+```
+
+### Tunning
+
+用于完成工程发布前的整体调整操作，在Azkaban的实现 中主要完成了工程的路径设置和工作流的存储路径设置。因为这个时候是可以操作工程=》工作流=》子工作流，便于进行从外到里的设置操作。比如工作流的存储依赖于工程的存储位置，子工作流存储依赖于父工作流的位置。在FlowTuning中完成了子节点计算，自动添加末尾节点。
+
+## 调度AppConn实现
+
+### AbstractSchedulerAppConn
+
+调度AppConn的抽象类，新的调度系统AppConn接入可以直接继承该抽象类，它实现了SchedulerAppConn接口，并继承了AbstractOnlySSOAppConn，打通DSS与调度系统的SSO登录。比如已经集成的DolphinSchedulerAppConn和SchedulisAppConn都是继承了该抽象类。
+
+该抽象类中包含了两种类型的Standard
+
+第一个是ConversionIntegrationStandard，用于支持将DSS编排转换为调度系统的工作流
+
+第二个是SchedulerStructureIntegrationStandard，用于DSS和调度系统的结构化集成规范
+
+### ConversionIntegrationStandard
+
+用于调度系统的转换集成规范，包含用于将DSS编排转成调度系统工作流的DSSToRelConversionService。也预留了接口支持把调度系统的工作流转成DSS的编排
+
+### AbstractSchedulerStructureIntegrationStandard
+
+调度系统组织结构集成规范，专门用于调度系统的组织结构管理，主要包含工程服务和编排服务。
+
+### ProjectService
+
+* 实现了工程的统一创建、更新、删除和查重操作。
+* 用于打通 DSS 工程与接入的第三方应用工具的工程体系，实现工程的协同管理。
+* 如调度系统需要同DSS打通工程体系就需要在结构化集成规范中实现工程服务的所有接口。
+
+### OrchestrationService
+
+编排服务用于调度系统统一编排规范，具有如下作用：
+
+* 统一编排规范，专门用于打通 DSS 与 SchedulerAppConn（调度系统）的编排体系。
+* 例如：打通 DSS 工作流 与 Schedulis 工作流。
+* 请注意，如果对接的 SchedulerAppConn 系统本身不支持管理工作流，则无需实现该接口。

zh_CN/Images/DSS-UserGuide模块设计/1653309930194.png

@@ -0,0 +1,53 @@
+# DSS-UserGuide模块设计
+
+### 引言
+
+DSS用户手册模块是DSS1.0新增的功能模块，用于给DSS的用户提供使用指引，里面录入了许多DSS使用过程中遇到的问题和解决方法，也包含了一些功能点使用说明。用户能够自助式的搜索遇到问题相关解决方案。后期也可以用来关联错误码，支持在弹出的错误码后，直接定位到知识库中已经录入的解决方案。guide模块是将文件以html的方式存放在表的字段中，需要解析md文件并转化为html, 由于某些文件存在链接需要跳转，需要另外搭建gitbook用于展示和管理这些文档，为了能够高效同步dss-guide-user模块，采取将gitLab上的文件打包，然后上传解压到gitbook所在服务器的指定目录下，通过guide-user定时扫描指定目录从而达到同步的目的。
+
+## dss_guide主要模块介绍
+
+DSS_Guide模块主要包含了Restful、Service、Dao、Entity的定义。
+
+### GuideGroupService
+
+用来解决GuideGroup的增加、查询、修改、保存、删除等能力，还有具备同步SUMMARY.md的能力。guide模块可以通过解析此文件，然后根据解析出的各级目录在文件中的配置路径，定位到需要读取的文件并向数据库定时写入，从而完成同步，当服务在其他服务器上运行时，为了避免重复安装gitbook，guide模块需要通过配置文件所在服务器ip，然后会自动将文件同步到guide模块所在服务器进行展示。
+
+### GuideContentService
+
+用来处理GuideContent的保存、查询、更新、删除操作。
+
+### GuideChapterService
+
+用来专门处理手册章节的具体内容，包含章节的搜索、基于ID的查询、删除、保存等。
+
+### GuideCatalogService
+
+用来实现知识库的同步、支持批量插入目录内容，并实现对目录结构分类的保存、删除、查询等操作
+
+
+### 核心流程图
+
+![1653309535303.png](../../Images/DSS-UserGuide模块设计/1653309535303.png)
+
+![](../../Images/DSS-UserGuide模块设计/1653309707841.png)
+
+
+### 数据结构
+
+![](../../Images/DSS-UserGuide模块设计/1653309930194.png)
+
+### dss_guide_group
+
+划分dss_guide 的分组，包含group_id、path（访问路径）、title等
+
+### dss_guide_chapter
+
+用来存储dss_guide章节的详细内容，包含catalog_id、title、content、content_html。和dss_guide_catalog的内容进行关联。
+
+### dss_guide_content
+
+用来存储分组后的说明内容，会规划到对应的group下面。包含title、type、content、content_html等
+
+### dss_guide_catalog
+
+用来对dss_guide进行内容分类，相当于知识库的目录结构，具有层级目录关系。