使用规范

一、编写目的

方便用户快速了解和使用CICD管理系统，节省人工辅导成本。

二、适用范围

1、锐明

备注：内部文档，禁止外传

三、产品介绍

3.1、名词解释

序号概要名词说明
1CICD管理系统面向研发、测试、运维等不同角色的综合平台，整合软件开发、测试和部署各阶段的繁琐流程。通过可视化、配置化、一键化操作，实现DevOps持续交付，提高研发效率、降低成本，并支持云环境与客户私有化部署，尽量减少人工干预。
2私有化运维交付系统
针对运维及前线技术支持/专家设计，按环境维度管理客户局点。该系统从 CICD管理系统 获取发布后的中间件或业务组件包，支持安装、升级、变量同步等运维操作，确保产品部署后达到就绪状态
3客户交付系统
集中管理所有客户的部署模型信息，对接开发内部的统一网关和用户中心，与运营平台打通。同时联动 私有化运维交付系统，实现从部署模型配置到日常运维的全流程一站式管理
4OMS
为「Operation and Maintenance System」的缩写, 专职负责部署工作.
OMS = OMS Server + OMSlet
5CDS
为「Customer Delivery System」的缩写, 客户交付系统系统
6cicd-web
CICD管理系统 的前端组件，负责展示及交互。
7cicd-server
CICD管理系统 的后端组件，通过HTTP接口为 cicd-web 提供服务，主要负责基础信息管理，采用Java开发。
8oms-server
被 CICD管理系统 和 私有化运维交付系统 共用。它提供HTTP接口，负责运维部署动作的编排与执行，上游对接 cicd-server 和 custom-server，采用Python开发。
9oms-let
安装在目标机上的轻量级代理，封装Shell脚本、加固系统配置，并负责部分常用软件包的安装。通过HTTP接口接收OMS Server下发的命令，采用Shell脚本开发。
10host-baseline
安装在目标机上, 提供系统级文件, 尽可能屏蔽系统差异. 无运行态, 开发语言: Shell.
11cicd-document-web
CICD管理系统 的帮助文档, 属于前端组件。
12jenkins
专用于 CICD管理系统, 利用其Pipeline Job承接流水线的sonar扫描、编译构建、组装包、发版及代码覆盖率等任务.
13COS
CICD管理系统 中的物料库，使用腾讯云的cos对象存储，统一存放组件包，项目版本包，流水线集成包，证书文件等'.

3.2、解决方案总览

3.2.1、逻辑视图

CICD管理系统 由5个逻辑组件组成，如下:

  1. CICD管理系统: 有单独的web管理界面配套, 云环境下的操作入口。

  2. Jenkins: 负责实际的流水线执行, 输出物料(即包文件)。

  3. 物料库: 统一存放物料(一般为构建好的包文件)。

  4. OMS Server: 运维管理系统的服务端, 单独剥离运行以兼容云环境&客户私有化环境的部署。

  5. Machine XXX: 具体部署业务组件的机器节点, 与OMS Server配套使用。

各逻辑组件的关系如图：

逻辑视图

3.2.2、部署视图

部署视图

3.3、CICD管理系统（单品）介绍

CICD管理系统（单品）作为整个解决方案系统门户，提供可视化、可编排的CI/CD持续交付软件生产线，实现DevOps持续交付高效自动化，缩短应用开发到市场交付周期，提升研发效率。

流水线服务本质上是一个可视化的自动化任务调度平台，需要配合服务器中编译构建、代码检查、测试、部署等服务的自动化任务使用。根据需要的场景，如开发测试环境应用部署、生产环境应用部署等，对这些自动化任务进行自定义编排，一次配置后就可以一键自动化触发调度执行，避免频繁低效的手工操作。

3.3.1、业务流程图

业务流程图

3.3.2、CICD解决方案对接规范

不同项目接入CICD管理系统，一般都需要先根据CICD解决方案规范进行相应的组件改造，对接时开发人员可参考 对接手册.

四、CICD管理系统使用规范

1.所有模块涉及到环境的操作权限时，开发环境只有团队内开发人员有操作权限，SIT、UAT环境只有团队内测试人员有操作权限。

2.流水线管理模块，若一条流水线同时包含了DEV/SIT/UAT环境，只有研发负责人有权限操作。

4.1、流水线管理

4.1.1、流水线管理规范

1.目前测试人员只有本团队流水线的运行、查看权限；

2.添加、编辑、复制流水线需要找团队开发人员操作；

3.删除包含多环境的流水线需要找团队研发负责人操作；

4.建议创建发布流水线时需同时包含DEV-SIT-UAT环境。

4.1.2、流水线运行规范

1.流水线总共分了三层，第一层是总流水线，管理DEV,SIT,UAT三个级别环境，一般在版本要发布前由研发负责人触发运行，构建 release 分支。

2.第二层是环境流水线，可以DEV，SIT，UAT环境分别运行，一般是开发提测，测试每日构建，测试升级UAT验收时使用，SIT、UAT环境只能构建release 分支，DEV环境可选择构建develop或release分支。

3.第三层是组件流水线，以组件维度运行，一般是开发人员自测使用，不建议测试人员单独运行某一个组件流水线，SIT、UAT环境只能构建release 分支，DEV环境可选择构建develop或release分支。

4.1.3、Nacos配置文件说明

1.xxx.application.properties：存放业务组件默认配置信息，每次运行流水线后会全量覆盖，因此不建议在nacos手动修改此配置文件。

2.xxx.base.properties：存放该组件公共变量配置文件，公共变量根据默认配置中的定义自动提取，每次运行流水线后会全量覆盖，因此不建议在nacos手动修改此配置文件。

3.xxx_${ip}.properties：存放组件节点独有配置，如节点公网ip，节点内网ip等，可以在nacos手动修改，每次运行流水线后不覆盖。

4.xxx_update.properties：存放组件在该环境中修改过的配置，如无，则为空，可以在nacos手动修改，每次运行流水线后不覆盖。

4.1.4、JVM文件说明

1.以dcs的JVM文件为例，JVM配置文件路径默认为/iotp/base/dcs/config，每次运行流水线后会全量覆盖，不建议在服务器上手动修改此配置文件。

*说明:
1.建议各项目参考《CICD解决方案对接手册》的4.3.7章节进行对接改造，通过环境变量支持动态配置。

4.1.5、SQL执行说明

1.全新安装时，默认由系统初始化数据库，是/否执行升级SQL字段不生效。

2.运行流水线进行跨版本升级时，可选择是否执行升级SQL。

3.运行流水线进行同版本迭代升级时，是/否执行升级SQL字段不生效，若存在SQL变更，需要人工介入进行手动操作。

4.运行流水线进行版本降级时，是/否执行升级SQL字段不生效，若存在SQL变更，需要人工介入进行手动操作。

说明:

update.sql的文件名构成为update_${组件版本版本号}.sql，若文件名与版本号匹配失败则认为此版本无需执行的sql，跳过此版本。其中P版本sql的版本号为中划线"-"。且后一版本的sql需全量包含前一版本的所有sql文件，否则部署流程将因校验失败流程终止。

业务流程图

4.2、主机管理

4.2.1、主机管理规范

1.添加新主机接入CICD进行部署前需要清理主机环境，保障服务器环境满足CICD接入条件（若不需要保留服务器数据，可找CICD团队成员提供clean_up.sh清理脚本）。

2.复用已接入CICD的主机时，需要统一从CICD管理系统安装&卸载，不能在服务器上清理环境，否则会导致CICD管理系统中的数据不一致，部署时报错信息如下：

主机管理规范图

3.若出现手动清理或操作过服务器环境导致部署失败，可找CICD团队成员协助处理！

4.3、环境管理

4.3.1、中间件环境管理规范

1.所有团队的中间件环境可共用，建议各团队共用中间件环境时提前进行线下沟通。

2.推荐提前添加常用的项目中间件模板，有利于添加中间件环境时进行快速配置。

中间件环境管理规范图

中间件环境管理规范图

4.3.2、MinIO部署规则

关于MinIO安装所涉及的校验规则, 在1.0.6版本中已做调整. 因其本身的安装较为复杂, 需要有一定的背景知识, 故为了保证安装的正确性, 界面化安装的限制规则(对比最早的人工安装MinIO流程)上更为严谨, 详细规则如下:

1.部署模式为单机时, 可选【默认磁盘】或【指定磁盘】：

a.【默认磁盘】为目录 /iotp 所挂载的磁盘；

b.【指定磁盘】需要满足磁盘数量必须是1或者大于等于4，同时指定的磁盘必须是空盘，当磁盘中存在任何文件时, 均不满足安装条件。

2.部署模式为集群时, 仅可选择【指定磁盘】：

a.机器数量必须是1或大于等于4台；

b.每台机器的磁盘数量必须是1或者大于等于4，同时指定的磁盘必须是空盘，当磁盘中存在任何文件时, 均不满足安装条件。

*说明:

1.无论单机or集群方式, 当选择【指定磁盘】时, 因会校验挂载的磁盘必须是空盘，因此界面获取的磁盘列表中会自动过滤如下目录所挂载的磁盘："/"、"/boot"。

2.界面上卸载MinIO后, 仅会卸载程序，不会删除minio存储的文件， 因此若相同机器在界面卸载后需要 再次安装，必须在安装前人工介入进行如下数据清理：

a.迁移需要保留是minio文件后，删除“/iotp/data/env/minio”目录下的所有文件，参考如下：

cd /iotp/data/env/minio ll -a data/ #检查文件夹下的文件存在的文件 rm -rf data/* #minio若配置了多个磁盘，需要依次操作多个数据目录data1、data2... rm -rf data/.minio.sys #指定删除minio服务启动后生成的隐藏文件夹 rm -rf data/.writable-check-XXX.tmp #指定删除minio服务启动后生成的隐藏文件 ll -a data/ #检查文件夹下的文件是否已全部清理

b.取消磁盘挂载，参考如下：

df -h umount /dev/vdb #minio配置了多个磁盘的环境，都需要取消挂载

c.删除服务器上的配置文件/etc/fstab中的磁盘挂载配置信息

MinIO图

4.3.3、OCI配置规范

使用CICD管理系统配置OCI时，上传的config.ini文件中的pem文件路径需要提前修改为“”/iotp/cloud_config/oci/${pem文件名称} ，如下：

OCI图

4.3.4、业务环境管理规范

1.业务环境由各团队独立管理，每个团队关联组件时只能选择本团队组件。

2.剔除业务环境中已关联的组件时，需要提前在环境管理->集群管理模块，找到对应环境的组件卸载后，才能剔除组件。

3.删除业务环境时，会同时删除业务环境下的网络配置信息。

4.集群业务环境，不同主机上的组件版本必须保持一致，不允许同一个环境的组件存在多个版本，因此建议集群环境在修改环境的关联组件时，可选择主机后点击“批量关联组件”按钮去修改业务环境的项目组件关联关系。

4.4、环境变量

4.4.1、环境变量配置规范

为支持环境变量共有属性复用，环境变量支持两种写法： 1.直接填写环境变量值，cicd部署过程中将直接取值使用，如：

环境变量配置规范图

2.通过变量表达式引用其他环境变量，实现环境变量复用，使用场景和表达式支持用法如下：

变量表达式规则：变量表达式整体通过f""修饰，以f""为标识作为是否是变量表达式的依据。在f""中支持直接写变量值，也支持通过${}去修饰一个变量名，解析时会将${}中字符串作为一个变量名在同等级的变量中寻找同名变量并做值替换。

作用域应用场景环境变量配置变量表达式处理后的变量值
环境变量引用其他环境变量f“${cicd_variable}”cicd_variable1=streamax_value
仅变量值的表达式写法f“cicd_value”cicd_variable2=cicd_value
变量值与环境变量混用f"http://${cicd_variable}:${cicd_variable2}"cicd_variable3=http://streamax_value:cicd_value
传递型环境变量f"http:${cicd_variable1}"cicd_variable3=streamax_value

4.5、项目版本管理

4.5.1、项目版本发布规范

1.发布项目版本时选择的流水线必须包含 SIT 级别的环境且包含部署阶段任务，允许有DEV/UAT/PRD级别的环境。

2.项目版本关联的组件版本数量必须与流水线中部署的组件数量保持一致，即目前不支持多个项目共用一条流水线时，只选择发布其中一个项目的场景。

3.流水线所包含的每个环境，最近一次运行记录必须都是成功状态。

4.流水线包含的每个环境最近一次运行成功的记录对应的分支commitId, 必须与git仓库中的commitId保持一致。

5.检查init.sql、update.sql是否正确、完整（因为流水线的同版本升级不会自动执行sql，因此建议开发、测试人员在发布前单独验证发布包的SQL文件）。