1.19.冰刀：部署

冰缩寒流，川凝冻霭，前回鹭渚冬晚。燕阁红炉，驼峰翠釜，曾忆花柔酒软。――刘天游《氐州第一》

    本篇为实战总结帖，主要用于多个项目同时运行时的统一文档，目前Zero上已经运行了几个比较重量级的项目，本文主要针对几个平台从环境搭建、开发、运行、测试到部署进行基于实战的讲解，以Step-By-Step的方式让开发人员能更加流畅搭建Zero的企业实战开发环境。本文内容和原始教程中的内容略微有些出入，是因为引用了更多Zero Extension中的模块来辅助开发，所以此文算是Zero Core和Zero Extension的交叉参考教程。

「壹」开发环境

1.1. 环境介绍

1.1.1. 基础环境

    最新的依赖库版本如下：

1.1.2. 特殊说明

基础环境部分

可选扩展部分

  • 如果使用了动态建模 （zero-atom）功能，则需要根据您的数据库下载相关依赖库：https://github.com/silentbalanceyh/vertx-zero/tree/master/vertx-pin/zero-vista ，若是其他类型数据库需参考内置源代码自己写一套基础插件。

  • 集成部分的ElasticSearch、Neo4j、Camunda、Redis根据您自身项目情况而定。

  • 动态建模/动态路由功能根据您自身项目情况而定。

  • Zero的基础版本是支持微服务和K8S（Istio）的，而此功能受限于目前项目，处于实验性版本阶段，需启用vertx-istio项目。

1.1.3. 脚手架数据

    本教程假设您的基本环境如下：

    注：可选部分根据您搭建环境过程中选择的zero extension模块进行相关定义，最新版的模块化会自动化部署相关模块已经环境内容，详细部分参考后续章节，从0.8.1 的版本开始，zero extension扩展模块引入了OOB——Out Of Box开箱即用的配置数据，若您启用了OOB功能，即使您的系统内没有任何内容，这些配置数据都会跟随本教程的发布流程进入到您的主库中。

1.1.4. 默认登录

  • 默认账号：falcon（开发者）

  • 默认密码：11111111

1.2. zero主框架

    如果您不关注最新版的功能，直接使用0.8.1版本，则可跳过该步骤，由于zero本身是一个跟着项目成长很迅速的项目，所以在1.0 版本发布之前，个人推荐紧跟最新版本走。虽然最新版本是X-SNAPSHOT，基础功能已经经过了生产环境验证，所以该版本是可靠的；再者，最新版本会包含一部分重用性极高的新功能，如0.9.0-SNAPSHOT中引入的：

  • 文档管理平台（FTP、SSH）

  • 模块化管理平台（License、Modulat）

  • 工作流标准化平台（ITSM、ISO）

  • WebSocket功能（正在开发中，用于提醒）

  • 短信邮件集成

    zero框架导入的操作步骤如下：

  1. 进入目录~/runtime/develop/中，下载vertx-zero代码到环境中：

    # 由于是只读类型，所以可不带access_token的模式拉取开源代码
~/runtime/develop >> git clone https://github.com/silentbalanceyh/vertx-zero.git
# 命令执行后的输出如下
Cloning into 'vertx-zero'...
remote: Enumerating objects: 62003, done.
remote: Counting objects: 100% (17224/17224), done.
remote: Compressing objects: 100% (6252/6252), done.
remote: Total 62003 (delta 8657), reused 16131 (delta 8157), pack-reused 44779
Receiving objects: 100% (62003/62003), 87.48 MiB | 15.39 MiB/s, done.
Resolving deltas: 100% (35166/35166), done.
Updating files: 100% (4850/4850), done.

  2. 下载完成后~/runtime/develop中会有一个vertx-zero目录，使用IDEA导入该目录中的项目：

    • 2.1. 启动IDEA

    • 2.2. 选中下载的vertx-zero目录中的pom.xml文件（自动导入成Maven类型的项目）

    • 2.3. 在弹出的对话框中选择Open as Project（以项目方式打开）

    • 2.4. 如果弹出下边对话框，直接勾选Trust projects in ~/runtime/develop，然后点击Trust Project

    • 2.5. 等待右下角的项目初始化完成

    • 2.6. 若您点开进度条会看到正在执行的后台任务，请等待后台任务全部完成后再执行下一步

  3. 导入完成后，检查IDE中的JDK运行环境是否符合：File -> Project Structure...，推荐11。

    此处注意Language level（语言级别），从zero的0.7.x版本开始，框架引入了Camunda工作流引擎，该引擎最新版本最低要求支持JDK11，基于这一点出发，zero也将JDK从8升级到了11，所以从该版本开始所有的Java环境以11为准。

  4. 打开Terminal终端，使用内置脚本（mvnd环境）编译vertx-zero：

    # zero中内置脚本主要用于快速编译以及增量编译框架，其中内容如下：
# 1）完整编译（常用）                -- zero-compile.sh
# 2）增量编译                       -- zero-compile-increase.sh
# 3）「部分」编译核心框架             -- zero-compile-core.sh
# 4）「部分」编译扩展框架             -- zero-compile-extension.sh
# 5）「部分」编译插件                -- zero-compile-infix.sh
# 
~/runtime/develop/vertx-zero(master) >> ./zero-compile.sh
......
# 最终输出如下
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  45.021 s (Wall Clock)
[INFO] Finished at: 2022-03-27T22:32:07+08:00
[INFO] ------------------------------------------------------------------------

    zero-compile.sh内容如：

    mvnd clean package install -DskipTests=true -Dmaven.javadoc.skip=true -Dmaven.compile.fork=true -T 1C

    上述步骤的编译不会触发zero的测试流程，如果使用mvnd clean package install 方式处理，会触发zero的测试流程，使得整个框架编译的时间拉长，所以不推荐clean package install方式，这种方式仅留给zero的研发人员 使用。编译成功后，您的开发环境Maven库中就安装了最新的zero版本，目前是0.9.0-SNAPSHOT。

1.3. zero插件环境（可选）

    如果您在项目中使用了动态建模功能（启用zero-atom ），此步骤是必须的，动态建模为高级功能，只有在引入主框架的场景下可使用，直接从中心仓库下载的依赖库中并不包含动态建模部分，此功能目前依然处于研发阶段，只有最新版可支持。

    操作步骤如：

  1. 执行Oracle依赖库的安装脚本（动态建模编译必须，运行可根据您的项目情况而定）

    # 进入 infix-oracle 项目目录
~/runtime/develop/vertx-zero(master) » cd vertx-pin/zero-vista/infix-oracle
# 进入 Maven 本地安装目录
~/runtime/develop/vertx-zero/vertx-pin/zero-vista/infix-oracle(master) » cd maven
# 执行安装脚本
~/runtime/develop/vertx-zero/vertx-pin/zero-vista/infix-oracle/maven(master) » ./install-oracle-jar.sh
# 脚本内容如下
# mvn install:install-file \
#     -Dfile=ojdbc7-12.1.0.2.jar \
#     -DgroupId=com.oracle \
#     -DartifactId=ojdbc7 \
#     -Dversion=12.1.0.2 
#     -Dpackaging=jar

    install-oracle-jar.sh的内容如：

     mvn install:install-file \
     -Dfile=ojdbc7-12.1.0.2.jar \         
     -DgroupId=com.oracle \
     -DartifactId=ojdbc7 \
     -Dversion=12.1.0.2 
     -Dpackaging=jar

  2. 在IDEA的Maven窗口中添加新项目：

  3. 导入项目vertx-zero/vertx-pin/zero-vista/（选择pom.xml文件）

  4. 导入项目后直接编译zero-vista：

    ~/runtime/develop/vertx-zero/vertx-pin/zero-vista(master) » mvn clean package install
.....
# 最终输出如下
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for 「vertx-vista」Scaffold Extension 0.9.0-SNAPSHOT:
[INFO] 
[INFO] 「vertx-vista」Scaffold Extension .................... SUCCESS [  1.693 s]
[INFO] Scaffold Plugin: MySQL（infix-mysql） ................ SUCCESS [  6.121 s]
[INFO] Scaffold Plugin: Oracle（infix-oracle） .............. SUCCESS [  3.783 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  12.339 s
[INFO] Finished at: 2022-03-28T05:46:15+08:00
[INFO] ------------------------------------------------------------------------

  5. 如此您就可以直接在项目中使用动态建模的SQL DDL插件了，使用时只需要在pom.xml中引入下边片段即可（根据您使用的数据库选择合适的插件）：

        <!-- MySQL -->
    <dependency>
        <groupId>cn.vertxup</groupId>
        <artifactId>infix-mysql</artifactId>
        <version>${zero.version}</version>
    </dependency>

    <!-- Oracle -->
    <dependency>
        <groupId>cn.vertxup</groupId>
        <artifactId>infix-oracle</artifactId>
        <version>${zero.version}</version>
    </dependency>

    zero中的数据库支持以MySQL和TiDB为主，目前开放的支持的数据库种类基于项目需求。

1.4. GitHub安全设置

注：当您作为协作者Coordinator提交代码时必须此步骤！

    由于Github站点升级，当你作为Coordinator加入到项目开发时，新版本已不推荐使用用户名/密码方式拉取代码，而是需要在您的账号中生成个人的access_token ，拉取项目代码时使用该access_token拉取。

    其操作步骤如下：

  1. 登录您的Github个人账号空间，右上角选择Settings菜单：

  2. 选择左边菜单中最下边的Developer Settings：

  3. 选择左边菜单Personal access tokens，然后点击Generate new token按钮

  4. 勾选好您所需的权限后直接点击Genarate token按钮：

  5. 在结果页记录下您的个人token：

  6. 进入您的项目环境中，执行如下操作步骤进行库关联，先查看目前的远程库版本：

    ~/runtime/develop/vertx-zero(master) » git remote -v
origin  https://github.com/silentbalanceyh/vertx-zero.git (fetch)
origin  https://github.com/silentbalanceyh/vertx-zero.git (push)

  7. 您的远程库名称为origin，执行如下命令：

    ~/runtime/develop/vertx-zero(master) » git remote set-url origin \
    https://<TOKEN>@github.com/silentbalanceyh/vertx-zero.git

    注意上述命令格式，token的位置介于https://和github.com之间，并且以@结尾。

  8. 再次查看您的远程库，库路径已发生改变：

    完成上述步骤之后，基本设置就完成了，当然在后续步骤中您可以直接使用git clone https://<Token>@<Repo>的方式拉取代码，则 6 ~ 8 步骤可省略 ，即下边命令：

git clone https://<TOKEN>@github.com/silentbalanceyh/vertx-zero.git

1.5. 项目后端

    如果从头搭建zero脚手架，使用新建流程，若是导入已经搭建好的项目则使用导入流程。

1.5.1. 新建

    新建项目可直接下载最新的脚手架版本：https://github.com/silentbalanceyh/scaffold-zero，然后根据自身项目修改如下内容：

    其中数据部分需修改Excel数据文件中的内容，这部分教程在配置章节讲解，上述修改部分参考本教程的配置篇来详细修改，一旦搭建好环境后就不用再变更，为一次性操作。

1.5.2. 导入

    导入项目时如果作为Coordinator需更改项目内容，参考《1.4.Github安全设置》先配置个人token，导入的操作步骤执行如下：

为了区分标准脚手架和新项目，从scaffold-zero中下载的项目在此章节为smave名称，从新建到配置完成的部分参考后续各配置章节。

  1. 从仓库下载代码（带token安全下载）：

    git clone https://<Token>@<Repo>
# 截图中以项目名smave为例，但该项目在私库中，所以读者无法直接访问，读者可直接访问自己创建好的Github仓库

  2. 参考《1.3.zero插件环境》直接添加一个新的Maven项目到IDEA环境中，添加完成后效果如：

    注：vertx-zero和smave共存于一个IDEA窗口中。

  3. 打开终端，执行根目录的编译脚本

    ~/runtime/develop/smave(master) » ./build.sh
# build.sh                      （Linux专用）
# build.bat                     （Windows专用）

  4. 编译成功后可以看到如下截图（如此后端基本开发环境就搭建完成了）

1.5.3. 初始化

    Zero脚手架的初始化流程操作步骤如下：

  1. 为了团队协作开发，先在自己本地开发环境中追加如下hosts映射（部署时另外配置）：

    # Mac位置              /private/etc/hosts
# Windows位置          C:/Windows/System32/drivers/etc/hosts
127.0.0.1     ox.server.cn      # 容器专用
127.0.0.1     ox.engine.cn      # 服务专用
127.0.0.1     ox.integration.cn # 集成专用（可选）

  2. 为您的应用创建MySQL数据库账号：

    ~/server$ mysql -u root -p                          # 输入root密码连接到MySQL中
mysql > USE mysql;
mysql > CREATE USER 'smave'@'%' IDENTIFIED BY '<PASSWORD>';
mysql > GRANT all privileges ON *.* TO smave@'%' WITH GRANT OPTION;

  3. 执行数据库建库脚本

    账号密码位于脚本 database-reinit.sh，请自行修改，按第二步创建的账号更改即可，推荐团队开发账号统一。

    ~/runtime/develop/smave/script/database(master) » ./database-reinit.sh
[Zero] 重建数据库成功!

    重建完成后，可以看到空库（文中仅演示了最小配置，不带工作流库、动态库、删除历史备份库，其他库的配置参考后续配置章节处理）：

  4. 执行初始化脚本，zero中的初始化使用liquibase完成，直接运行如下脚本：

    ~/runtime/develop/smave/sv-driver/ix-smave(master*) » ./run-init.sh
# 最终输出如下：
[INFO] ------------------------------------------------------------------------
[INFO] 
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  7.531 s
[INFO] Finished at: 2022-03-28T10:20:04+08:00
[INFO] ------------------------------------------------------------------------

    执行完初始化脚本后可以在数据库看到生成的表结构：

  5. 「重要！」执行下边命令备份最新表结构用于生产发布：

    mysqldump -u root -pxxxx -h localhost --databases DB_SMAVE > src/main/resources/init/initialize.sql

  6. 表创建好过后，执行数据导入专用程序：cn.vertxup.SvLoader

  7. 「重要！」从此处开始，所有直接从IDEA中运行的主程序都必须配置好运行目录，否则无法以正确路径的方式加载数据，该步骤在生产环境中是不需要的，先点击SvLoader的运行配置：

  8. 「重要！」点开运行配置后设置您的主程序的运行目录并保存该配置：

    重要的事情说三遍：

    • 注意第二个红色框，这一步对开发人员十分重要！*

    • 注意第二个红色框，这一步对开发人员十分重要！*

    • 注意第二个红色框，这一步对开发人员十分重要！*

  9. 然后点击运行或调试运行执行数据初始化主程序

    运行完成后可看到如下日志：

    如此，数据初始化就完成了，这个SvLoader可以在您更改了任何/init/oob中的数据过后执行反复初始化操作，属于高频使用的主程序，而本小节的初始化流程 也会在开发过程中反复使用。

1.5.3. 启动

    容器启动流程操作步骤如下：

  1. 初始化完成后，直接运行主程序：cn.vertxup.SvAgent：

  2. 看到如下界面，后端zero容器就启动成功了：

1.6. 项目前端

    如果是自己从头搭建zero-ui脚手架，则使用新建流程，若是导入已经搭建好的项目则使用导入流程。

1.6.1. 新建

    新建zero-ui项目先安装zero的脚本工具：https://www.vertxai.cn/，安装好工具之后直接运行如下命令：

    新建项目后根据自身项目修改如下内容：

1.6.2. 导入/启动

    前端导入使用WebStorm，操作步骤如下：

  1. 从仓库下载代码（带token安全下载）：

    git clone https://<Token>@<Repo>
# 截图中以项目名smave-ui为例，但该项目在私库中，所以读者无法直接访问，读者可直接访问自己创建好的Github仓库

  2. 将代码导入WebStorm或其他前端工具IDE中：

  3. 选中您下载的项目打开

  4. 弹出框中选择

  5. 安装本地依赖库，基于yarn，一次性执行，生产部署之前也需执行

    ~/runtime/develop/smave-ui(master) » ./run-update.sh

    脚本内容如下

    #!/usr/bin/env bash
ncu -u                              # package.json 检查更新
node ./scripts/zrun-package.js      # 自动化版本管理（防止依赖）
rm -rf yarn.lock                    # 删除缓存
yarn install                        # 重新安装依赖

    上述脚本运行完成后可看到如下截图：

  6. 运行启动脚本

    ~/runtime/develop/smave-ui(master*) » ./run-zero.sh
# 由于引入了TypeScript，第一次启动会十分慢，启动过一次后如果依赖包不更改启动速度会很快

    最终运行后可看到如下截图

  7. 从浏览器中打开前端：http://ox.server.cn:PORT/zo/login/index，此处PORT是前端配置的端口号： 如果连接不上后端显示

  8. 使用falcon/11111111登录可进入主界面。

「贰」生产环境准备

2.1. JDK

2.1.1. Open JDK

  1. 直接使用Ubuntu工具安装JDK 11：

    sudo apt install openjdk-11-jdk

    执行过后会有如下截图

  2. 验证Java是否安装成功

    java -version

  3. 最终安装路径：/usr/lib/jvm/java-11-openjdk-amd64，后续设置JAVA_HOME。

2.1.2. ZuLu JDK 11（推荐配置）

  1. 安装Azul APT仓库：

    # install the necessary dependencies
sudo apt-get -q update
sudo apt-get -yq install gnupg curl 

# add Azul's public key
sudo apt-key adv \
--keyserver hkp://keyserver.ubuntu.com:80 \
--recv-keys 0xB1998361219BD9C9

# download and install the package that adds 
# the Azul APT repository to the list of sources 
curl -O https://cdn.azul.com/zulu/bin/zulu-repo_1.0.0-3_all.deb

# install the package
sudo apt-get install ./zulu-repo_1.0.0-3_all.deb

# update the package sources
sudo apt-get update

    执行包安装的截图如下：

  2. 执行命令安装Zulu JDK 11：

    # 标准安装
sudo apt-get install zulu11-jdk

  3. 本地安装Zulu JDK 11：

    # 下载 deb 安装包
wget https://cdn.azul.com/zulu/bin/zulu11.54.25-ca-jdk11.0.14.1-linux_amd64.deb
# 执行本地安装
sudo apt-get install ./zulu11.54.25-ca-jdk11.0.14.1-linux_amd64.deb

    安装截图如：

  4. 检查Java版本

    java -version

  5. 最终安装地址：/usr/lib/jvm/zulu-11-amd64，后续设置JAVA_HOME。

2.2. Git

  1. 直接使用Ubuntu工具安装Git：

    sudo apt install git

  2. 验证Git是否安装完成

    git --version

2.3. Mvnd

  1. 下载安装包：

    wget https://github.com/apache/maven-mvnd/releases/download/0.7.1/mvnd-0.7.1-linux-amd64.zip

    执行截图

  2. 对安装包执行解压：

    unzip mvnd-0.7.1-linux-amd64.zip

  3. 重命名目录

    mvn mvnd-0.7.1-linux-amd64.zip mvnd

2.4. 环境变量

该章节为2.2、2.3的补充章节。

  • Java环境变量

  • Mvnd环境变量

  1. 执行下边命令打开环境变量文件：

    sudo vim /etc/profile

  2. 追加如下片段（按i键编辑）：

    export JAVA_HOME=/usr/lib/jvm/zulu-11-amd64
export MAVEN_HOME=/home/localadmin/software/mvnd
export PATH=$PATH:$MAVEN_HOME/bin:$JAVA_HOME/bin

    截图参考

  3. 编辑完成后执行Esc，使用wq退出vim工具并保存，然后执行下边命令在当前会话中生效

    source /etc/profile

  4. 检查Java和Mvnd

    • Java环境检查：java -version

    • Mvnd环境检查：mvnd -v

2.5. MySQL

  1. 执行命令安装MySQL

    sudo apt install mysql-server

  2. 验证安装好的服务

    sudo systemctl status mysql

  3. 新版本操作系统安装5.7（参考引用中教程先设置，然后执行此步骤的命令）：

    sudo apt install -f mysql-client=5.7* mysql-server=5.7*

  4. 配置root密码

    sudo mysql_secure_installation

  5. 配置mysql

    sudo vim /etc/mysql/mysql.conf.d/mysqld.cnf

    追加下边配置

    # Windows专用，MySQL大小写敏感
lower_case_table_names=2 

# 连接参数设置
max_connections=2048
wait_timeout=1814400

    为了兼容Oracle数据库，zero对数据库的要求是大小写敏感的，且以大写为主，所有SQL关键字、数据库相关的内容都一律使用大写。

  6. 重启MySQL服务

    service mysql restart

  7. 验证MySQL服务和端口

    ps -ef|grep mysql
netstat -an|grep 3306

  8. 连接MySQL

    mysql -u root -p

  9. 创建您的应用所需账号：

    ~/server$ mysql -u root -p # 连接到MySQL中
mysql > USE mysql;
mysql > CREATE USER 'smave'@'%' IDENTIFIED BY '<PASSWORD>';
mysql > GRANT all privileges ON *.* TO smave@'%' WITH GRANT OPTION;

2.6. NodeJs

  1. 下载NodeJs安装包：

    wget https://nodejs.org/dist/v16.14.2/node-v16.14.2-linux-x64.tar.xz

  2. 解压

    tar -xvf ./node-v16.14.2-linux-x64.tar.xz

  3. 重命名目录（为后续方便）：

    mv node-v16.14.2-linux-x64 nodejs

  4. 环境变量配置

    sudo vim /etc/profile

    追加下边内容

    export NODE_HOME=/home/localadmin/software/nodejs
export PATH=$NODE_HOME/bin:$PATH

  5. 保存后执行下边命令让环境生效

    source /etc/profile

  6. 验证环境：

    node -v

  7. 安装yarn，yarn在安装过程请使用全局模式安装-g参数。

    npm install -g yarn

2.7. Zero Ai安装

  1. 执行安装命令

    npm install -g vertx-ai

  2. 检查安装结果：

    ai help

2.8. Httpd

  1. 执行命令安装服务器：

    sudo apt install apache2

  2. 查看服务器运行状态

    sudo systemctl status apache2

  3. 修改端口和根目录

    • 进入默认配置目录/etc/apache2/

      # 进入配置目录
cd /etc/apache2

    • 在文件ports.conf中修改内容

      sudo vim /etc/apache2/ports.conf

      追加下边配置

      NameVirtualHost *:6002
Listen 6002

    • 创建默认目录

      # 此处 xxx 是当前登录用户名
mkdir -P /home/xxx/server
# 权限必须是 755 以上
chmod 755 /home/xxx/server

    • 修改默认配置

      cd sites-available/
cp 000-default.conf 000-default.conf.bak        # 备份
sudo vim 000-default.conf

      修改开始配置以及中间配置（注意此处目录不可使用root账号目录，否则）

      <VirtualHost *:6002>
....
    DocumentRoot: /home/xxx/server
</VirtualHost>

    • 为防止403错误，需要在/etc/apache2/apache2.conf配置文件中追加

      <Directory /home/localadmin/server>
            Options Indexes FollowSymLinks
            AllowOverride All
            Require all granted
</Directory>

      此步骤是因为在配置过程中我们更改了apache2的默认目录，从/var/www/html修改到了/home/localadmin/server中，如果您没有更改默认目录则可忽略这一步。

    • 生产环境部署时，有时候会遇到刷新界面404的问题，该问题解决方案如下：

      # 先启用Linux中的 `mod_rewrite`
sudo a2enmod rewrite

      在您的部署目录下追加.htaccess文件，该文件内容如下：

      <IfModule mod_rewrite.c>
        RewriteEngine On
        RewriteBase /
        RewriteRule ^index\.html$ - [L]
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteRule . /index.html [L]
</IfModule>

  4. 最后重启apache2服务

    sudo systemctl restart apache2

「叄」部署应用

  • 以 smave 为例，基本结构和在线的 scaffold-zero 一致。

3.1. 后端部署

  1. 在后端服务器中追加数据库配置，先添加hosts映射：

    127.0.0.1     ox.server.cn          # 前后端部署在同一台机器时前端使用该记录（开发也使用该记录）
127.0.0.1     ox.engine.cn          # 数据库使用此映射记录
127.0.0.1     ox.integration.cn     # 仅用于集成

  2. （本地打包忽略）下载代码到生产环境

    git clone https://<TOKEN>@github.com/silentbalanceyh/smave

  3. （本地打包忽略）执行下边命令编译打包：

    # vertx-zero，前文提到过
~/runtime/vertx-zero$ git pull
~/runtime/vertx-zero$ ./zero-compile.sh

# smave，编译项目
~/runtime/smave$ git pull
~/runtime/smave$ ./build.sh

  4. （本地打包忽略）查看编译结果

    ll sv-driver/ix-smave/target/

  5. 本地编译后直接跳过 2 ~ 4 步骤，拷贝下边目录到容器启动目录

    # 创建运行目录
mkdir ~/server
# 将打包的内容拷贝到该目录中
# - conf 文件夹         （配置文件位置）
# - lib 依赖库          （jar位置）
# - smave-app.jar       (启动程序)

$ cp -rf \
> runtime/smave/sv-driver/ix-smave/target/smave-app.jar \
> runtime/smave/sv-driver/ix-smave/target/conf \
> runtime/smave/sv-driver/ix-smave/target/lib \
> server/

  6. 查看server目录结构

    ll server

  7. 在server目录中创建启动命令工具和容器启动的脚本

    • 程序更新脚本如下：

      #!/usr/bin/env bash
rm -rf conf lib smave-app.jar
cp -rf ../runtime/smave/sv-driver/ix-smave/target/smave-app.jar \
    ../runtime/smave/sv-driver/ix-smave/target/conf \
    ../runtime/smave/sv-driver/ix-smave/target/lib \
    .
# 保存为 smave-update-whole.sh

      如果您更改了conf部分的配置，请在更新时注意先备份，更新过后再还原，如下截图：

    • 表结构初始化脚本：

      #!/usr/bin/env bash
mysql -u root -P 3306 -h 127.0.0.1 -p < conf/init/initialize.sql
echo "[Zero] 数据库表初始化完成"

    • 命令行启动脚本如下：

      #!/usr/bin/env bash
chmod +x smave-app.jar
java -Djava.io.tmpdir=./tmp \
     -cp conf \
     -jar smave-app.jar config
# 保存为 smave-console.sh

    • 容器启动脚本如：

      #!/usr/bin/env bash
chmod +x smave-app.jar
OX_OPTS="$OX_OPTS -server \
    -Xms8g -Xmx16g -XX:NewRatio=1 \
    -XX:SurvivorRatio=3 -XX:PermSize=256m \
    -XX:MaxPermSize=4g"
# 后台运行
nohup java $OX_OPTS -Djava.io.tmpdir=./tmp -cp conf -jar smave-app.jar start &
# 保存为 smave-server.sh

  8. 更改配置文件

    • 更改跨域配置：

      # 跨域配置更改
vim conf/vertx-jooq.yml

      将最后一行内容更改为（注意域名小写，浏览器会自动转。）：

      origin: "http://hpcs01"

    • 文件管理地址更改：

      # 文件存储目录变更
vim conf/plugin/is/configuration.json

      将内容更改为：

      {
    "storeRoot": "/home/localadmin/server/store"
}

3.2. 数据初始化

    database-reinit.sh脚本在开发章节已经存在，此处不再重复，可以将该部分脚本拷贝到~/server/script/中。

  1. （第一次或表变更）执行数据库初始化

    # 进入script/database目录去初始化
cd script/database
./database-reinit.sql

  2. （第一次或表变更）执行建库操作，开发过程中已经导出了表结构的SQL，直接执行上边的建表的脚本

    # 直接执行
./smave-database.sh

  3. 启动命令行工具

    # 直接执行
./smave-console.sh

  4. 执行命令：r，l导入数据（Zero Ai命令）

    > r
[ μηδέν ]执行命令："r", "（子系统）标准部署工具"
[ μηδέν ] (runtime)------>>>> Sub System: （子系统）标准部署工具
[ μηδέν ][ Production ] 请输入命令，使用 h 可查看帮助文档
> l
......
# 最终输出结果
[ μηδέν ]您的元数据仓库已重置初始化完成！重置结果：true

# 退出命令
# - b：返回上一级菜单（退出子系统）
# - q：退出整个命令行程序

  5. 启动容器：

    # 执行启动命令
./smave-server.sh
~/server$ ./smave-server.sh
~/server$ nohup: appending output to 'nohup.out'

  6. 启动容器后可从日志查看容器启动状态：

    cd ~/server/
cat nohup.out

    最终输出如下：

  7. 同时在logs/目录中可以看到日志清单：

    ll logs/2022-03-28/

    • zero-epic-fabric目录中是核心框架日志

    • zero-epic-extension目录中是扩展框架日志

    • zero-epic-fabric.log是汇总后的日志

  8. 在运行日志中确认两个配置以证明conf目录下的内容已生效

  9. 执行下边命令可看到运行的java进程：

    # 查看运行进程
ps auxg|grep smave-app.jar
# 停止
kill -9 <进程号>

3.3. 前端部署

  1. 下载代码到前端服务器中

    cd ~/runtime/
git clone http://<TOKEN>@github.com/silentbalanceyh/smave-ui.git
# 下载前端代码到本机中

  2. 安装前端依赖库

    ~/runtime$ cd smave-ui
~/runtime/smave-ui$ yarn install
# 等待前端依赖库安装结束（第一次速度很慢）

  3. 由于生产环境的环境变量已经提前设置了，在./env.production文件中，所以安装好依赖库后，前端可直接打包

    # 打包消耗时间会挺长，主要原因是使用了TypeScript做部分数据结构的校验
# 所以最好是在本地打包好了直接把 `build` 目录上传到
~/runtime/smave-ui$ yarn build

  4. 最后将build中的所有内容拷贝到~/server中。

    cp -rf build/* ~/server

  5. 使用浏览器打开，您就可以看到如下界面：

「肆」配置调整

4.1. hosts映射配置

    本章节主要解析几个常用的内置映射域名相关信息，需注意的是此处的域名只是为了团队协作开发，并不是真实存在的域名，zero系统中包含三个核心域名：

    这三个域名映射需要您添加到本地hosts映射中：

# Mac位置              /private/etc/hosts
# Windows位置          C:/Windows/System32/drivers/etc/hosts
127.0.0.1     ox.server.cn      # 容器域名
127.0.0.1     ox.engine.cn      # 服务域名
127.0.0.1     ox.integration.cn # 集成域名（可选）

    三个域名的使用结构图如下：

    特殊说明：

  • 使用域名访问服务可以保证不同的开发人员直接通过调整本地域名映射访问外置服务，主要处理以下几种核心场景：

    • 开发数据库/测试数据库/生产数据库在不改变代码的情况下自由切换。

    • 不同的集成服务在不改变代码的情况下自由切换。

    • 不同开发人员访问这些服务时在不改变代码的情况下自由切换。

  • 一般在生产环境部署时，前端zero ui和后端zero只有在同一台服务器上运行时，不需要更改ox.server.cn的域名配置，通常部署时候我们会采用两台以上的机器分离部署，所以生产部署时会单独配置ox.server.cn。

  • 一般在生产环境部署时，后端zero和所有的集成服务在同一台服务器上运行时，不需要更改ox.integration.cn的域名配置，但往往生产环境部署时这些集成服务和后端zero都是分离的，也会单独配置。

  • 后端zero以及开发工具访问所有数据库时统一使用了ox.engine.cn的域名访问，除非生产环境部署时数据库和后端zero分离，否则不需要更改ox.engine.cn的域名配置。

4.1.1. 服务域名

4.1.1.1. 程序访问

    数据库域名统一在vertx-jooq.yml中配置：

    在脚手架配置中您会看到下边几段配置代码（省掉数据库连接参数）：

jooq:
  # 主库配置
  provider:
    driverClassName: "com.mysql.cj.jdbc.Driver"
    username: root
    password: "xxxx"
    instance: DB_UP
    hostname: "ox.engine.cn"
    jdbcUrl: "jdbc:mysql://ox.engine.cn:3306/DB_UP?...."
  # 历史数据库
  orbit:
    driverClassName: "com.mysql.cj.jdbc.Driver"
    username: root
    password: "xxxx"
    hostname: "ox.engine.cn"
    instance: DB_UP_HIS
    jdbcUrl: "jdbc:mysql://ox.engine.cn:3306/DB_UP_HIS?...."

# 工作流库
workflow:
  name: HOTEL-WORKFLOW-ENGINE
  builtIn:
  # 文件管理工作流
  - workflow/process.file.management/workflow.xlsx
  database:
    driverClassName: "com.mysql.cj.jdbc.Driver"
    username: root
    password: "xxxx"
    instance: DB_UP_WF
    hostname: "ox.engine.cn"
    jdbcUrl: "jdbc:mysql://ox.engine.cn:3306/DB_UP_WF?...."

4.1.1.2. Liquibase访问

    zero中使用使用liquibase执行数据库初始化，它的数据库配置位于文件：

    该配置是一个属性文件，内容通常如：

url=jdbc:mysql://ox.engine.cn:3306/DB_QIANLI?....
driver=com.mysql.cj.jdbc.Driver
username=zero
password=xxxx

4.1.1.3. Jooq代码生成访问

    zero中的Jooq代码生成配置位于领域模型定义的项目中，它的数据库配置位于文件：

    该配置文件是一个XML文件，内容通常如：

    <jdbc>
        <driver>com.mysql.cj.jdbc.Driver</driver>
        <url>
            <![CDATA[ jdbc:mysql://ox.engine.cn:3306/DB_UP?..... ]]>
        </url>
        <username>root</username>
        <password>xxxx</password>
    </jdbc>

4.1.2. 容器域名

4.1.2.1. 跨域CORS

    CORS跨域访问的域名一般位于vertx-jooq.yml配置文件的尾端，其片段如下：

  origin: "http://ox.server.cn:6001"

4.1.2.2. 前端Endpoint

    当您的zero-ui前端访问后端zero容器时，前端的访问配置位于环境变量文件中：

    环境变量文件主要有两个：

  • .env.development：开发环境专用

  • .env.production：生产环境专用

4.1.3. 集成域名

    所有集成域名目前也位于vertx-jooq.yml配置文件中，只是在脚手架项目里被注释掉了，需要使用时直接打开即可：

# ------------------- Redis专用 ----------------------
# redis:
    # host: ox.integration.cn
    # port: 6379
# ------------------- 历史备份专用 ----------------------
# 历史库专用
#trash:
#    keepDay: -1

# ------------------- 全文检索专用 ----------------------
# Es索引库
#elasticsearch:
#    hostname: ox.integration.cn
#    port: 9200
#    scheme: http
#    index: cmdb
#    username: elastic
#    password: zero

# ------------------- 拓扑图专用 ----------------------
# 图引擎库
#neo4j:
#    port: 7687
#    protocol: bolt
#    hostname: ox.integration.cn
#    username: neo4j
#    password: "zero"

    细心的读者已经发现，后端配置所有的域名的位置比较集中：

  • 除开Jooq/Liquibase工具使用的域名需要单独配置，这两个工具主要是开发过程中使用，生产部署时不会使用，可理解成一次性配置，配置好过后不需要更改。

  • 生产部署专用的域名配置全部位于vertx-jooq.yml文件中，这样设计的目的也是为了方便修改以及执行DevOps配置流程。

4.2. Maven项目标识

    本来这个章节是Maven的基础知识，应该是不需要教程就可以过的知识点，但为了照顾初学者，本小节可以帮助您从零开始搭建一个scaffold-zero的脚手架基础项目，在看章节步骤之前，先看看几个项目的作用：

    特殊说明：

  1. 数据访问层？整个项目结构中没有数据访问层是因为zo-domain中的静态领域模型是使用Jooq代码生成工具生成，生成过程中已经带有Dao层的代码，并且在编程过程中，借用zero提供的抽象数据层以及查询引擎，不需要使用任何多余代码就可以完成数据库的底层访问，所以丢弃了传统项目中的数据访问层。

  2. 接口/控制层？整个项目结构中也不存在控制层和接口部分，由于zero以及将上层逻辑全部压缩到一起了，这部分内容根据您项目的复杂度可以有所差异，您也可以自行扩展。

  3. 多启动器？zo-driver中可以包含一个以上的启动器，您可以书写不同种类的main函数作为程序入口，通常：

    • 开发过程中会使用双入口：Loader/Agent，一个负责数据导入，另外一个负责容器启动。

    • 生产部署过程中会使用单入口：Entry，该入口根据不同参数可打开命令行工具和容器，参考前文部署教程。

    Maven标识更改操作步骤如下（附带新建项目步骤）：

  1. 删除下载下来的scaffold-zero中的.git目录，将代码推送到自己的代码仓库中。

  2. 在IDEA中选中项目，点击右键：Refactor -> Rename...，下图中选择最后一个：Rename module and directory

  3. 在弹出框中输入您的主项目标识信息

  4. 在所有子项目中重复步骤 2 ~ 3（合计五次）：

    注：一般在IDEA做rename的时候，Maven的配置并不会随着IDEA发生更改。

  5. 更改所有的POM文件：

  6. POM文件在更改过程中需根据您自己的项目设置

    • 项目本身的三个核心属性：groupId, artifactId, name需酌情更改：

    • 父子结构调整，子项目中（除开从vertx-import继承的项目需调整继承部分：

    • 父子结构调整，父项目中调整module部分

    • name的调整则是为IDE量身打造的，调整过后可以在Maven窗口中看到更改结果

      若窗口无变化点击截图中的刷新按钮看到该改变

  7. 变更完成后，保证编译通过，直接运行根目录：build.bat/build.sh脚本，见到下边截图则您的Maven设置就完成了：

4.3. 数据库

    4.1中已经说明，数据库配置部分主要在vertx-jooq.yml中，其中Camunda, 历史库，主库的配置结构基本一致，如下：

jooq:
  provider:
    driverClassName: "com.mysql.cj.jdbc.Driver"
    username: root
    password: "xxxx"
    instance: DB_UP
    hostname: "ox.engine.cn"
    jdbcUrl: "jdbc:mysql://ox.engine.cn:3306/DB_UP?..."
  # 历史数据库，如果启用逻辑删除则需要使用该库
  orbit:
    driverClassName: "com.mysql.cj.jdbc.Driver"
    username: root
    password: "xxxx"
    hostname: "ox.engine.cn"
    instance: DB_UP_HIS
    jdbcUrl: "jdbc:mysql://ox.engine.cn:3306/DB_UP_HIS?..."

## 工作流配置
workflow:
  name: HOTEL-WORKFLOW-ENGINE
  builtIn:
  # 文件管理工作流
  - workflow/process.file.management/workflow.xlsx
  database:
    driverClassName: "com.mysql.cj.jdbc.Driver"
    username: root
    password: "xxxx"
    instance: DB_UP_WF
    hostname: "ox.engine.cn"
    jdbcUrl: "jdbc:mysql://ox.engine.cn:3306/DB_UP_WF?..."

    需要更改的属性表如下：

    特殊说明：

  1. options配置的内容关联到连接池属性，系统默认使用了HikariDataPool连接池。

  2. category目前系统中支持六种最基本的值

    • MYSQL5

    • MYSQL8

    • MYSQL（旧版专用）

    • ORACLE（旧版专用）

    • ORACLE11

    • ORACLE12

    • （保留）TIDB4

    • （保留）TIDB5

  3. 默认的jdbcUrl中带的MySQL配置参数如下表格：

    serverTimezone=Asia/Shanghai&useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&failOverReadOnly=false&useSSL=false

    数据库的category属性实际并不是数据库访问过程中必须的，最新的JDBC可以根据您提供的driverClassName以及jdbcUrl反向分析数据库类型，而此处的category主要设计如下：

  1. 在执行Jooq持久化过程中为数据库提供更好的Dialect方言以适配不同数据库。

  2. zero在对数据库执行DDL动态建模/动态路由实施过程中，可根据category执行特定的组件选择以处理不同种类数据库的兼容性问题。

    如果您启用了动态建模（zero-atom）功能，则额外的动态数据库会存储在您的X_SOURCE表中，表结构和配置一致，而前端开发中心您可以看到目前四个库的启用禁用情况，如下图只启用了主库，并且可以在该界面更改动态建模库的信息：

4.4. 容器端口

    容器端口的配置主要分两部分：后端端口和前端端口。

  1. 后端端口的配置如下图：

    • 此处的name在微服务环境和云端环境作为节点部署时需要特别注意，单体应用（本教程中）中可根据自己的项目进行设置。

    • host设置成0.0.0.0其含义在于任意IP地址都可访问，不限制主机的运行IP。

    • 此处的port就是您需要配置的端口号，Scaffold的默认端口为6000，Zero框架中的默认端口为6083，此处为了做Demo改成了6086。

  2. 前端端口的配置如下图：

    前端端口号使用NODE的环境变量PORT进行指定，.env.development负责开发环境端口号，.env.production负责生产环境端口号。

  3. 后端配置前端的跨域必须和浏览器中访问的地址一致，一般位于vertx-jooq.yml文件中，如：

        # Cross Domain
    cors:
        credentials: true
        methods:
            - DELETE
            - GET
            - POST
            - PUT
            - OPTIONS
        headers:
            - Authorization
            - Accept
            - Content-Disposition
            - Content-Encoding
            - Content-Length
            - Content-Type
            - X-App-Id
            - X-App-Key
            - X-Sigma
            - X-Lang
            - X-Session-Id
        origin: "http://ox.server.cn:6001"

    其中origin的配置意味着您最终会在浏览器中输入http://ox.server.cn:6001来访问前端程序，而服务端只允许从这个路径的JS请求发生，这样就防止其他模式的脚本攻击，关于跨域更多信息可参考在线的跨域配置相关文档。

  4. 前端跨域的基本环境变量配置如：

    # 访问后端的接口主地址
Z_ENDPOINT=http://ox.server.cn:7000

# 跨域模式的配置
Z_CORS_MODE=cors
Z_CORS_CREDENTIALS=include

  5. 使用前后端分离配置的核心结构图如下：

    • 所以生产部署过程中，对外的两台服务器必须开放对应的端口，如图后端开放7000，前端开放6002。

    • 如果搭建了Nginx的反向代理则可跳过上述步骤。

    • CORS会拦截掉所有请求源非法的请求，这种情况请求本身不会进入到后端应用中。

    • 此处提到的请求主要是JS脚本级的请求，通常应用容器为浏览器，如果是直接使用程序发送请求方法除外。

4.5. 初始化登录账号

    zero脚手架中的初始化登录账号位于启动器中：

    打开该Excel文件：

    主要添加的记录有三张表：

    特别说明：

  1. 密钥是一个64位的随机字符串，可使用Zero Ai命令生成：

    ai str -n <个数，默认1> -l <长度，默认64>

  2. 主键一般是UUID格式，可直接使用Zero Ai命令生成：

    ai uuid -n <个数，默认20>

  3. 密码是MD5的加密格式，可直接使用Zero Ai命令生成（0.3.20版本之后）：

    ai md5 -i <输入字符串>

    如果是MacOs的系统，执行完命令之后可直接使用Cmd + V快捷键粘贴刚刚生成的字符串。

  1. 修改完成后，直接运行Loader程序（前文提到的数据加载程序），默认会加载init/oob中的所有Excel数据文件，可反复加载，加载完成后重新启动容器，则新的账号密码就会生效。

4.6. 租户应用信息

    租户信息在整个zero环境中以sigma为标识，带有租户的系统结构概念图如下：

    特殊说明：

  • 如图所示，每一个彩色小方块表示一个独立的Docker容器，这个容器中可能包含独立数据库、存储、服务也可能多个小方块组合到一起使用，从应用层的数据去标识，每个小方块都拥有一个独立的appId和appKey。

    • appId用于读取基础应用数据

    • appKey用于读取敏感数据

  • 每一种颜色则表示一个租户信息，拥有唯一的sigma值，最终从系统层可以看到，一个租户会有多个应用信息，而此处我们部署的前后端就充当了一个彩色小方块的Docker结构。

    租户信息的区分主要体现在部分信息的数据导入过程：

  1. 如果您要启用Zero中提供的命令行，则需设置如下配置：

    runtime目录中的configuration.json是命令行专用配置，它的内容实际是引用租户文件：

    {
    "stellar": "init/environment.json"
}

  2. 有了上述配置后，您就可以使用如下代码：

    // 直接调用 Ok.ok() 可提取租户信息
return Ok.ok().compose(okA -> {
        // 此处的 okA 表示租户方
        final JtApp app = okA.configApp();
        // 而此处的 okB 表示客户方（客户方即集成方）
        final OkB partyB = okA.partyB(appName);
});

  3. init/environment.json中的存储的数据就是租户的基本数据，格式如：

    {
    "global": {
        "sigma": "xxxxxx",
        "appId": "xxxxxx",
        "appKey": "xxxxxx",
        "language": "cn",
        "active": true,
        "createdBy": "zero-environment",
        "scope": "vie.app.sv"
    },
    "application": {
        "name": "vie.app.ox"
    },
    "integration": {
        "customerB": {
            "name": "partyB",
            "config": "init/integration/partyB.json"
        }
    }
}

    配置中有三个核心节点和租户信息相关，他们的用途分别为：

    • global：该节点提供了当前租户的基本全局信息，用于Excel数据导入过程中的默认值赋予，有了该设置后，Excel数据文件中的数据就不需任何和应用、租户、语言相关的信息，只包含业务数据，最终形成如下结构图：

      即：应用数据包 + environment.json = 租户数据包。

    • application：PartyA专用配置数据，包括（应用数据X_APP，数据库配置X_SOURCE）等。

    • integration：PartyB专用配置数据，主要是集成数据，用于构造Integration类专用。

4.7. 前端配置

    本章节旧事重提，主要用于配置前端环境变量：

4.7.1. 项目名称

    项目的npm名称存储于package.json中，该名称会在ai init命令中直接设置：

{
    "name": "smave-ui",
    "version": "0.1.0",
    "private": true,
}

4.7.2. 远程集成配置

    集成配置环境变量如：

# 该应用使用的语言环境，X-Lang 传入值
Z_LANGUAGE=cn

# 远程容器RESTful访问端
Z_ENDPOINT=http://ox.server.cn:7000

4.7.3. 风格配置

# 主色调处理，该色调会影响整个 Ant Design的主色调
Z_CSS_COLOR=#3457e2

# CSS自定义类名前缀
Z_CSS_PREFIX=zo

# 站点的字体设置：默认是 14px
Z_CSS_FONT=13px

4.7.4. 开发配置

# 打开通用调试日志
Z_DEV_DEBUG=true

# 打开模拟数据专用日志（去后端独立运行前端专用设置）
Z_DEV_MOCK=true

# 打开远程请求专用配置监控请求响应信息
Z_DEV_AJAX=false

# 表单监控专用日志
Z_DEV_FORM=true

# 打开所见即所得的Monitor工具，使用键盘中的 home 拉出工具
Z_DEV_MONITOR=false

4.8. 应用配置

    应用配置在前端和后端必须对应上，前端依旧是环境变量部分：

# 应用名称，对应到 X_APP 中的 NAME 字段
Z_APP=vie.app.zo

# 应用的语言环境，和后端对应
Z_LANGUAGE=cn

# 入口信息，可对接后端的 UI_PAGE 实现动态界面渲染，目前只是用于静态的入口端
# 登录入口端
Z_ENTRY_LOGIN=/login/index
# 管理入口端
Z_ENTRY_ADMIN=/amdin/index

    后端配置位于下边文件中：

    表格中的数据如下

「伍」小结

    本章主要介绍了zero新脚手架的基本配置以及开发环境和生产环境的详细部署流程，根据教程中的内容开发人员可完成如下任务：

  • 搭建项目的开发环境（从零起步以及直接导入）

  • 部署项目到生产环境

Previous1.18.天下：集成Next3.氷る世界（Ψυχρός κόσμος）

Last updated