Merge pull request #113 from WeBankFinTech/1.0.0

modify visualis doc

Author: jinyangrao

visualis_docs/images/visualis_appconn.jpg

@@ -1,18 +1,35 @@
 > Visualis AppConn安装
 
 ## 1. AppConn安装
-    DSS在编译打包时，会自动编译打包好Visualis AppConn物料包，Visualis AppConn的安装，只涉及到AppConn相关库表的配置。  
-    如果是使用[DSS一键安装全家桶](https://osp-1257653870.cos.ap-guangzhou.myqcloud.com/WeDatasphere/DataSphereStudio/1.0.1/DSS-Linkis%E5%85%A8%E5%AE%B6%E6%A1%B620220223.zip)来部署的服务，可以直接使用其软件包中提供的脚本工具。在一键全家桶部署完成后，可以在dss的安装目录下找到脚本工具，其目录结构和使用说明如下。
+    DSS1.1.0的第三方组件AppConn归属于第三方组件自己维护，所以为了成功安装visualis，并支持DSS工作流，需要拉取visualis1.0.0代码，编译打包AppConn代码。  
+```shell
+# 进入visualis源码项目中
+cd visualis
+
+# 进入visualis-appconn模块
+cd visualis-appconn
+
+mvn clean package -DskipTests=ture
+```
+    如下图visualis.zip包即为visualis-appconn的包。
+![](./../images/visualis_appconn.jpg)
+
+
+    如果是使用[DSS一键安装全家桶](https://github.com/WeBankFinTech/DataSphereStudio-Doc/blob/1.1.0/zh_CN/%E5%AE%89%E8%A3%85%E9%83%A8%E7%BD%B2/DSS%26Linkis%E4%B8%80%E9%94%AE%E9%83%A8%E7%BD%B2%E6%96%87%E6%A1%A3%E5%8D%95%E6%9C%BA%E7%89%88.md)来部署的服务，可以直接使用其软件包中提供的脚本工具。在一键全家桶部署完成后，可以在dss的安装目录下找到脚本工具，其目录结构和使用说明如下。
 ```shell
 # 进入到dss安装的bin目录下
 >> cd dss/bin
 
 # 其中appconn-install.sh就是AppConn安装脚本工具
 >> ls
->> appconn-install.sh  checkEnv.sh  excecuteSQL.sh  install.sh
+>> appconn-install.sh  appconn-refresh.sh  checkEnv.sh  executeSQL.sh  install.sh  start-default-appconn.sh
 ```
-    为了能够安装顺利，首先需要部署完成Visualis服务，确保服务正常启动。Visualis的安装部署可以参考[Visualis安装部署文档](./Visualis_deploy_doc_cn.md)，使用AppConn安装脚本工具时步骤如下：
+    为了能够安装顺利，首先需要部署完成Visualis服务，然后需要把visualis appconn的zip包放置到规定的appconn目录解压。Visualis的安装部署可以参考[Visualis安装部署文档](./Visualis_deploy_doc_cn.md)，visualis appconn zip包放置和AppConn安装脚本工具步骤如下：
 ```shell
+# 把visualis appconn放置到dss-appconns目录下
+rz -ybe ${DSS_INSTALL_HOME}/dss/dss-appconns
+
+
 cd {DSS_INSTALL_HOME}/dss/bin
 
 >> sh appconn-install.sh
@@ -29,3 +46,4 @@ cd {DSS_INSTALL_HOME}/dss/bin
 # 在执行AppConn安装脚本工具后，会插入相关第三方AppConn的配置信息
 ```
     修改完成后需要重启DSS服务。
+    如果是域名的方式访问DSS服务，需要参考[visualis安装部署文档](./Visualis_deploy_doc_cn.md)的第5小节。

visualis_docs/images/visualis_eureka.png

@@ -22,10 +22,11 @@ Visualis编译部署文档
     **在安装linkis后，请确保DSS1.1.0与Linkis1.1.1 基本可用，可在 DSS 前端界面执行 SparkQL 脚本，可正常创建并执行 DSS 工作流。**
 
 ## 1.4. 下载源码包及编译后端
-    Visualis源码安装时，需要下载对应的源码包进行编译，目前Visualis在依赖的DSS 1.0.1版本和Linkis1.1.1版本已经上传到Maven中央仓库，只需Maven配置正常即可拉取相关依赖。
+    Visualis源码安装时，需要下载对应的源码包进行编译，目前Visualis在依赖的Linkis1.1.1版本已经上传到Maven中央仓库，只需Maven配置正常即可拉取相关依赖，**DSS 1.1.0版本正在发布版本，并未上传至Maven中央仓库，需要拉取DSS仓库的1.1.0进行编译，并把依赖安装到本地。**
+
 ```shell
 # 1. 下载源码
-git clone https://github.com/WeDataSphere/Visualis.git
+git clone https://github.com/WeBankFinTech/Visualis.git
 
 # 2. 切换到1.0.0分支
 git checkout 1.0.0
@@ -54,7 +55,7 @@ npm run build # 编译前端包
 
 ## 2. 安装部署
 ## 2.1. 安装后端
-    Visualis使用assembly作为打包插件，在编译完成后，进入到Visualis/assembly/target目录下，可以找到编译完成后的Visualis-server.zip包。
+    Visualis使用assembly作为打包插件，在编译完成后，进入到Visualis/assembly/target目录下，可以找到编译完成后的visualis-server.zip包。
 ````bash
 # 1. 解压安装包
 unzip visualis-server.zip
@@ -69,14 +70,15 @@ visualis-server
     --- lib   # 服务jar包存放位置
     --- logs  # 日志目录
 ```
-    在需要部署的服务器上（也可以是DSS部署的服务器），上传该visualis-server.zip包，解压即完成Visualis安装。
+    在需要部署的服务器上（也可以是DSS部署的服务器），上传该visualis-server.zip包，在需要部署的路径上，解压即可完成Visualis安装。
 
 ## 2.2. 初始化数据库
-    在初始化数据库前，需要注意，由于历史原因Visualis复用了DSS的用户权限体系，即使用了DSS的linkis_user表，所以在部署时，**Visualis需要配置和DSS同一个数据库**，进入到源码的跟目录，找到db文件夹，在链接到对应的数据库后，需要执行以下SQL文件，建立Visualis使用时需用到的表。
+    Visualis的编译包，解压即为安装，并未去执行相关的SQL文件，所以在正常安装步骤中，需要建立一个visualis的数据库，并执行visualis的相关建表语句。
+    相关建表语句可以在源码中找到，进入到源码的根目录，找到db文件夹，连接到对应的数据库后，执行以下SQL文件，建立Visualis使用时需用到的表。
 ```shell
 # 在源码包db目录中找到对应的sql文件
 
-# 连接visualis数据库（和DSS使用同一个库）
+# 连接visualis数据库
 mysql -h 127.0.0.1 -u hadoop -d visualis -P3306 -p
 
 source ${visualis_home}/davinci.sql
@@ -101,73 +103,80 @@ rz -ybe
 # 刷新字体库缓存
 fc-cache –fv
 ```
+    在使用visualis时，调用预览功能或在工作流中执行Display和Dashboard时，如果提示报错：**error while loading shared libraries: libfontconfig.so.1: cannot open shared object file: No such file or directory**，是由于部署visualis的机器缺少相关依赖导致报错，执行**sudo yum -y install fontconfig-devel**安装依赖。
 
-## 2.4 安装前端
-    Visualis当前使用前后端分离的部署方案，完成前端编译后，把前端包放置在nginx前端包安装路径的dss/visualis路径对应的服务器目录下。
-
-```shell
-
-# 配置静态资源根路径（用于配置nginx的root参数）
-cd /data/dss/web
-
-# 在上一步/data/dss/web目录下，配置前端访问url路径地址（没有则需要创建）
-cd dss/visualis
-
-# 上传Visualis前端包
-rz -ybe build.zip
-
-unzip build.zip # 解压前端包
 
-cd build # 进入到解压路径
-
-mv * ./../ # 把静态资源文件移动dss/visualis路径下
-```
+## 2.4 安装前端
 
-    根据上一步前端部署的内容，Visualis的nginx的前端配置可以参考如下：
+    为了更好的说明前端配置，首先给出nginx的配置，visualis的nginx的前端配置和说明：
 ```shell
-# 在nginx配置参考
-# 补充linkis gateway
-
 server {
-    listen       8989; # 访问端口
+    
+    listen  8088;# a. 访问端口
     server_name  localhost;
-    client_max_body_size 100M;
 
-    # ...
-    location /dss/visualis { # 前端访问路径，需要手动创建
-    root   /data/dss/web; # Visualis前端静态资源文件目录，可自由指定
+  location /dss/linkis { # b. linkis管理台的静态文件目录
+    root   /data/dss_linkis/web;
+    autoindex on;
+  }
+  
+  location /dss/visualis { # c. 前端访问路径，需要手动创建
+    root   /data/dss_linkis/web; # d. visualis前端静态资源文件目录，可自由指定
     autoindex off;
   }
 
+  location / { # e. dss静态文件目录
+    root   /data/dss_linkis/web/dist;
+    index  index.html index.html;
+  }
+
   location /ws {
-    proxy_pass http://127.0.0.1:9001; # Linkis gateway地址
+    proxy_pass http://127.0.0.1:9001; # f. linkis gateway地址
     # ...
   }
 
   location /api {
-    proxy_pass http://127.0.0.1:9001; # Linkis gateway地址
+    proxy_pass http://127.0.0.1:9001; # g. linkis gateway地址
     # ...
   }
 }
 ```
-    前端部署配置后，可以重启nginx或者刷新nginx配置sudo nginx -s reload。
+    Visualis当前使用前后端分离的部署方案，即前后端分别打包部署，完成前端编译后，把前端包（前端资源文件）放置在nginx配置的前端资源文件目录下 **（即上述配置 c和d小项）。**
+```shell
+# 配置静态资源根路径（用于配置nginx的root参数，即d小项）
+cd /data/dss_linkis/web
+
+# 在上一步/data/dss_linkis/web目录下，配置前端访问url路径地址（即c小项，没有则需要创建）
+cd dss/visualis
+
+# 上传Visualis前端包
+rz -ybe build.zip
+
+unzip build.zip # 解压前端包
+
+cd build # 进入到解压路径
+
+mv * ./../ # 把静态资源文件移动到c小项dss/visualis路径下
+```
+    前端部署配置后，可以重启nginx或者刷新nginx配置使得上述配置生效**sudo nginx -s reload。**
+
 
 ## 2.5. 修改配置
 
 ### 2.5.1. 修改application.yml
-    在配置application.yml文件中，必须要配置的有1、2、3配置项，其它配置可采用默认值，其中第1项中，需要配置一些部署IP和端口信息，第2项需要配置eureka的信息，第3项中只需要配置数据库的链接信息，**需要配置为DSS同一个数据库**（其它参数可以保持默认值）。
+    在配置application.yml文件中，必须要配置的有1、2、3配置项，其它配置可采用默认值，其中第1项中，需要配置一些部署IP和端口信息，第2项需要配置eureka的信息，第3项中只需要配置数据库的链接信息。（visualis的库可以和dss同库，也可以不同，需部署用户自行抉择）。
 ```yaml
 # ##################################
 # 1. Visualis Service configuration
 # ##################################
 server:
   protocol: http
   address: 127.0.0.1 # server ip address（服务部署的机器IP）
-  port:  9888 # server port（服务部署的端口）
-  url: http://127.0.0.1:8989/dss/visualis # frontend index page full path（前端访问路径）
+  port:  8008 # server port（visualis服务进程端口）
+  url: http://127.0.0.1:8088/dss/visualis # frontend index page full path（前端访问visualis的完整路径）
   access:
     address: 127.0.0.1 # frontend address（前端部署IP）
-    port: 8989 # frontend port（前端部署端口）
+    port: 8088 # frontend port（前端访问端口）
 
 
 # ##################################
@@ -195,8 +204,8 @@ spring:
     allow-bean-definition-overriding: true
   application:
     name: visualis-dev
-  datasource: # 需要配置和DSS同一个数据库
-    url: jdbc:mysql://127.0.0.1:3306/dss?characterEncoding=UTF-8&allowMultiQueries=true # Configuration required
+  datasource:
+    url: jdbc:mysql://127.0.0.1:3306/visualis?characterEncoding=UTF-8&allowMultiQueries=true # Configuration required
     username: hadoop
     password: hadoop
 
@@ -214,7 +223,10 @@ wds.linkis.gateway.url=http://127.0.0.1:9001
 # 其它可以使用默认参数
 # 省略配置
 ```
-    **如果Visualis部署的hadoop集群配置了Kerberos，需要在Visualis的配置文件linkis.properties文件中开启Kerberos，加入配置项：wds.linkis.keytab.enable=true**
+    **如果部署的hadoop集群开启了Kerberos，需要在visualis的配置文件linkis.properties文件中开启Kerberos，加入配置项：**
+```properties
+wds.linkis.keytab.enable=true
+```
 
 ## 3. 启动应用
 
@@ -241,7 +253,15 @@ less logs/linkis.out
 ## 4. AppConn安装
     Visualis服务部署后，需要和DSS应用商店和工作流打通，需要在DSS侧安装对应的AppConn，可参考[VisualisAppConn安装](./Visualis_appconn_install_cn.md)。
 
-## 5. 日志配置（可选）
+## 5. 有关域名访问DSS时Visualis的配置说明（可选）
+    在实际生产中，访问DSS一般使用域名进行访问，读者阅读visualis安装部署文档和appconn的部署文档时会发现，visualis的配置中出现几处前端配置，这些前端配置影响预览功能和邮件报表功能。
+    如果使用域名时，需要注意以下配置：
+1. AppConn安装时，指定visualis appconn的访问ip和端口时，可以先写入一个模拟值，待安装完成后，然后修改dss_appconn_instance表的url字段为域名值，类似: http://dss.bdp.com/ （注意后面的斜杠/，配置时不能遗漏）。
+2. Visualis服务的配置文件application.yml中，指定的前端ip和端口，需要指定为前端nginx服务器的ip和nginx配置的visualis端口。
+
+
+
+## 6. 日志配置（可选）
     在实际的使用场景中，依赖于linkis.out日志输出场景比较不符合规范，日志文件不回滚，长时间运行容易造成生产服务器磁盘容量告警，从而带来生产问题，目前我们可以通过修改日志配置，来优化日志打印，日志配置可以参考如下修改：
 ```properties
 <?xml version="1.0" encoding="UTF-8"?>