1. 基本概念

1.1 目的

本文档主要介绍金蝶云苍穹轻轨线（CI/CD）融合工具的产品说明，包括：应用场景、产品原理、使用步骤等。旨在方便使用工具的相关架构师、工程师、运维人员快速了解轻轨线（CI/CD）融合工具的工作原理及实现方式，帮助其基于第三方DevOps平台快速实现苍穹CICD。

1.2 应用场景

金蝶云苍穹CICD融合工具的应用场景是为已经具备DevOps平台的苍穹二开客户，在自有平台基础上集成该工具，从而实现自动化苍穹二开打包及部署。

1.3 功能介绍

▲ 轻轨线（CI/CD）融合工具产品原理图

步骤说明：

1 该工具以镜像方式提供，安装后以容器实例方式运行在用户的容器平台；

2 用户基于第三方DevOps平台实现苍穹Jar包构建并将制品存放在相应路径（可以是文件服务器或制品仓库）；

3 调用CI/CD融合工具的接口实现Jar包、元数据、静态资源打包，并存放到目标制品仓库；

4 调用CI/CD融合工具的接口从制品库获取二开包并更新到目标苍穹环境；

5 用户重启苍穹服务。如使用的是苍穹版本不低于V5.0.019及MC版本不低于V5.0.022时，则可以通过接口调用monitor优雅重启；如使用的苍穹版本低于V5.0.019及MC版本低于V5.0.022时，则用户需手动或脚本实现服务重启；

6 继续调用工具更新元数据。

2. 下载安装

服务的下载及安装，请参考文档《轻轨线（CI/CD）融合工具v1.0部署手册》

3. 使用指南

3.1 OMP初始化

3.1.1 初始化admin

服务安装完成后，登录轻轨线（CI/CD）运营管理后台（简称OMP），进行admin账户初始化。OMP有且只有一个用户（admin），用于操作许可、查看日志、密钥获取、token加密等，用户名admin不可变更，用户需初始化登录密码，如下图：

3.1.2 导入许可

轻轨线（CI/CD）融合工具的许可申请可参考社区文档《轻轨线获取并激活许可》，申请流程中所需的“软件特征码”可在OMP的“许可管理”页面查看并复制。

下载完许可后，登录OMP，在“许可管理”页面“导入许可”即可，如下图：

注意：

1 用户在使用时，只需要下载轻轨线（CI/CD）模块即可，如上图中红框所示。

3.2 Jar包构建

源代码构建完成后，需要将jar包再按云编码-应用编码.zip的命名方式（如fi-bos.zip)打包并上传至客户方能够通过URL下载的文件服务器或制品库中，如NEXUS等。

3.3 生成苍穹二开包

3.3.1 CI流水线配置

接下来的步骤是在用户的流水线调用融合工具的API进行二开包构建，把已经构建好的Jar包和元数据、静态资源等合并为一个苍穹标准二开包。将附件一（生成苍穹二开包）中的脚本复制到第三方流水线的节点。该脚本是第三方流水线调用融合工具的逻辑，其中需要传参如下图所示：

重点事项：

1 header中的token参数从融合工具OMP获取，参考步骤3.3.2

2 访问制品仓库/文件服务器（获取Jar包）及git仓库（获取元数据和静态资源）的token需进行加密，加密方法参考文档3.3.3

注意：制品仓库中token需要先对其用户名和密码进行base64编码后，再使用文档中3.3.3部分的方式进行加密

3 上述三个传参模块包括了元数据、静态资源，如没有对应模块，可根据实际情况留空。

3.3.2 获取API的token

为确保调用安全，在请求头需填入融合工具API密钥以确认身份。操作步骤为：【融合工具OMP】-【API密钥管理】页面，点击“新建密钥”会自动生成访问融合工具的API密钥，最多可生成10个，供项目上不同组织分配并使用。

3.3.3 第三方组件token加密

为实现对客户的制品仓库、git仓库、MC第三方应用的安全访问，需对客户第三方组件的token、key进行加密后才能使用，有两种方式进入API加密界面：

操作路径①：登录【融合工具OMP】- 右上角【账户信息】– 【token加密工具】

操作路径②：在【融合工具OMP登录页】- 登录键下方“token加密工具”

在下图所示的界面进行token加密，并将加密后的参数配置在流水线节点。

3.4 部署苍穹二开包

完成了CI流水线配置，接下来进行CD流水线的配置。苍穹CD的脚本配置分为两种情况，“支持monitor优雅重启”和“仅支持容器重启”，我们将分别介绍：

注意：只有当苍穹版本不低于V5.0.019及MC版本不低于V5.0.022时，才能使用苍穹优雅重启；当苍穹及MC不满足版本要求时，由客户手工或添加脚本逻辑实现服务重启。

3.4.1 支持monitor优雅重启的脚本配置

将附件二（更新苍穹）中的脚本复制到CD节点。CD所需的传参如下图所示：

重点说明：

1 融合工具API的获取方式与CI流水线相同，参考3.3.2；

2 第三方组件的token加密方式，参考3.3.3；

3 “package_name”为升级的补丁包名称，如没指定默认填“auto”，即更新最新的补丁包；

4 “graceful_restart”参数控制苍穹服务重启方式，只有当苍穹及MC版本不低于V5.0.020时，才能使用苍穹优雅重启，填入参数“true”；

5 苍穹环境的相关参数获取方式如下：

COSMIC_DATACENTER_ID：mc中的数据中心ID，通过mc系统查看，操作路径：【租户列表】→ 【租户】→ 【数据中心】。

COSMIC_CLUSTER_ID：mc中的集群ID。

MC_TRD_APPID：mc中第三方应用ID。

MC_TRD_KEY：mc中的第三方应用key，首次进入时点击刷新图标即能看到数据；如果没有看到此界面，则需要更新mc的内核和版本。

注意：

1、点击[刷新]后，需要点击[保存]按钮，key才能保存成功；

2、MC第三方应用页面交互不同版本可能略微不一致，如果看到多种认证方式或者访问策略，请选择“摘要认证”获取相关的认证秘钥，点击查看配置详情。

直接获取第三方应用key

选择摘要认证获取第三方应用key

选择摘要认证获取第三方应用key

配置完成后运行即可实现苍穹CD。

3.4.2 仅支持容器重启的脚本配置

当用户的苍穹版本低于V5.0.019及mc的版本低于V5.0.022时，无法执行优雅重启，只能在执行完Jar包更新后，手工重启服务，或由用户实现服务自动重启，然后再增加流水线节点更新元数据。

节点一：附件二（更新苍穹）中的脚本复制到CD节点，并替换参数；

节点二：用户实现服务重启；

节点三：附件三（更新元数据）中的脚本复制到CD节点，并替换参数。

与monitor优雅重启的参数配置及获取途径基本相同，可参考文档的3.4.1部分，唯一的区别在于当采用容器重启的方式时，参数“graceful_restart”填入“false”。配置完成后即可运行。

3.5 日志查看

可通过界面查看接口调用情况，操作路径：登录OMP -【接口调用日志】- “查看详情”或“运行日志”

3.6 操作审计

如需查看admin账户的历史操作，可登录管理后台，在“操作审计”页面查询，如下图：

4. 附件

附件一：生成苍穹二开包

echo "融合工具-生成苍穹二开包"

host=http://172.17.1.125:32528

api=/api/generate_package

http_code=`curl -s -o response.txt -w"%{http_code}" $host/ajax$api \

--header 'Token: LtbBbQ5ast/uHEkHUIXFeVkNy7w0Ncx/79Kgfs9I+aw=' \

--header 'Content-Type: application/json' \

--data   '{

   "repo": {

       "type":"basic_auth",

       "token": "iBzXcGTYuZZoVUORPn5SrQ+OXzQomncAqSZ0TIqfSudSNqkv",

       "download_jars": [

           "http://172.17.6.209:31532/repository/test_ci_l-f64318d552f64a599329df313bdad985/app/4.0.004.0/app-v1-202303201630.1.zip",

           "http://172.17.6.209:31532/repository/test_ci_l-f64318d552f64a599329df313bdad985/app/4.0.004.0/app-v1-202303201640.2.zip"

       ],

       "upload_url": "http://172.17.6.209:31532/service/rest/v1/components?repository=test_ci_l-f64318d552f64a599329df313bdad985",

       "upload_package_path": "/path",

       "service_name":"abtest"

   },

   "metadata": {

       "cosmic_version": "5.0.11",

       "git_url": "http://172.17.6.212:31896/10000/10000/d5b9c1389b26473e8d0763b7aff7f876/demo.git",

       "branch": "master",

       "token": "uwX9Z1G4oNhMXn6HIhli7geoXkScC8560dKZ3qLdtV085b5b",

       "apps": [

           {

               "app_id": "scmc-pm",

               "metadata_path": "demo/fi/app01/datamodels/metadata",

               "dbscripts_path": "demo/fi/app01/dbscripts"

           }

       ]

   }

}'`

if [ $http_code != "200" ]; then

   echo "http_code: $http_code"

   cat response.txt

   exit 1

fi

resp=`cat response.txt` && log_id=${resp:19:32} && api_uuid=${resp:65:32}

while(true);do

 sleep 5

 http_code=`curl -o log.txt -w"%{http_code}" -XGET "$host/ajax/api/run_log?workspace=$log_id&api_uuid=$api_uuid&simple=true&api=$api"`

 if [ $http_code != "200" ]; then

   echo "read log fail, http_code: $http_code"

   exit 1

 fi

 run_status=`cat log.txt | sed 's/\"//g'`

 if [[ $run_status == "success" ]]; then

   echo "upgrade success."

   break

 elif [[ $run_status == "error" ]]; then

   log=`curl -XGET "$host/ajax/api/run_log?workspace=$log_id&api_uuid=$api_uuid"`

   echo "upgrade failed, please check more log"

   exit 1

 elif [[ $run_status == "running" ]]; then

   echo "Patch upgrading, please wait!"

 else

   echo "run status err $run_status"

   exit 1

 fi  

done

附件二：更新苍穹

host=http://172.17.1.125:32528

api=/api/upgrade_cosmic

http_code=`curl -k -s -o response.txt -w"%{http_code}"  -XPOST $host/ajax$api \

--header 'Token: LtbBbQ5ast/uHEkHUIXFeVkNy7w0Ncx/79Kgfs9I+aw=' \

--header 'Content-Type: application/json' \

--data '{

   "repo": {

       "type": "basic_auth",

       "token": "iBzXcGTYuZZoVUORPn5SrQ+OXzQomncAqSZ0TIqfSudSNqkv",

       "service_name": "abtest",

       "download_path": "http://172.17.6.209:31532/repository/test_ci_l-f64318d552f64a599329df313bdad985/path",

       "package_name": "abtest-20230911151423.zip"

   },

   "graceful_restart": false,

   "cosmic_mc_url": "http://172.17.6.210:32030/mc",

   "cosmic_datacenter_id": "1289896065000013824",

   "cosmic_cluster_id": "ierp",

   "mc_trd_appid": "unittest",

   "mc_trd_key": "MYRx3IWBxmTay0rYAxtKDg=="

}'`

if [ $http_code != "200" ]; then

   echo "http_code: $http_code"

   cat response.txt

   exit 1

fi

resp=`cat response.txt` && log_id=${resp:19:32} && api_uuid=${resp:65:32}

while(true);do

 sleep 5

 http_code=`curl -o log.txt -w"%{http_code}" -XGET "$host/ajax/api/run_log?workspace=$log_id&api_uuid=$api_uuid&simple=true&api=$api"`

 if [ $http_code != "200" ]; then

   echo "read log fail, http_code: $http_code"

   exit 1

 fi

 run_status=`cat log.txt | sed 's/\"//g'`

 if [[ $run_status == "success" ]]; then

   echo "upgrade success."

   break

 elif [[ $run_status == "error" ]]; then

   log=`curl -XGET "$host/ajax/api/run_log?workspace=$log_id&api_uuid=$api_uuid&api=$api"`

   echo "upgrade failed, please check more log"

   exit 1

 elif [[ $run_status == "running" ]]; then

   echo "Patch upgrading, please wait!"

 else

   echo "run status err $run_status"

   exit 1

 fi  

done

附件三：更新元数据

host=http://172.17.1.125:32528

api=/api/upgrade_metadata

http_code=`curl -s -o response.txt -w"%{http_code}"  -XPOST $host/ajax$api \

--header 'Token: LtbBbQ5ast/uHEkHUIXFeVkNy7w0Ncx/79Kgfs9I+aw=' \

--header 'Content-Type: application/json' \

--data '{

   "repo": {

       "type": "basic_auth",

       "token": "iBzXcGTYuZZoVUORPn5SrQ+OXzQomncAqSZ0TIqfSudSNqkv",

       "service_name": "abtest",

       "download_path":"http://172.17.6.209:31532/repository/test_ci_l-f64318d552f64a599329df313bdad985/cub/",

       "package_name": "auto"

   },

   "graceful_restart": false,

   "cosmic_mc_url": "http://172.17.6.210:32030/mc",

   "cosmic_datacenter_id": "1289896065000013824",

   "cosmic_cluster_id": "ierp",

   "mc_trd_appid": "unittest",

   "mc_trd_key": "MYRx3IWBxmTay0rYAxtKDg=="

}'`

if [ $http_code != "200" ]; then

   echo "http_code: $http_code"

   cat response.txt

   exit 1

fi

resp=`cat response.txt` && log_id=${resp:19:32} && api_uuid=${resp:65:32}

while(true);do

 sleep 5

 http_code=`curl -o log.txt -w"%{http_code}" -XGET "$host/ajax/api/run_log?workspace=$log_id&api_uuid=$api_uuid&simple=true&api=$api"`

 if [ $http_code != "200" ]; then

   echo "read log fail, http_code: $http_code"

   exit 1

 fi

 run_status=`cat log.txt | sed 's/\"//g'`

 if [[ $run_status == "success" ]]; then

   echo "upgrade success."

   break

 elif [[ $run_status == "error" ]]; then

   log=`curl -XGET "$host/ajax/api/run_log?workspace=$log_id&api_uuid=$api_uuid&api=$api"`

   echo "upgrade failed, please check more log"

   exit 1

 elif [[ $run_status == "running" ]]; then

   echo "Patch upgrading, please wait!"

 else

   echo "run status err $run_status"

   exit 1

 fi  

done