1. 前言
1.1 文档修订记录
| 修订次数 |
文档版本号 |
修订时间 |
修订人 |
修订内容 |
审核人 |
| 1 |
V1.0 |
2025.4 |
姚煜楠 |
初始版本内容编写。 |
|
|
|
|
|
|
|
1.2 框架概述
全代码开发平台是集团技术中台的重要组成部分，在主流JAVA技术开发基础上，整合了优质的第三方开源项目，并基于集团常见业务场景进行适配优化，最终研制而成的快速应用开发平台。其定位为通用代码开发脚手架，为快速开发上线低代码开发平台无法满足的定制化系统进行赋能。全开平台提供了一个开箱即用的开发环境，包含了集团完整的技术生态和技术规范，以统一应用开发的技术路线，让系统开发者基于技术底座专注于业务实现。平台内置多个应用开发所必须的公共组件，各组件以服务或依赖包的方式引入项目，包括项目脚手架工程、用户登录组件、权限控制组件、用户管理组件、ORM组件、代码生成器组件、附件上传组件、流程组件等。
1.2.1 技术栈
-
JDK版本: 8以上
-
基础框架: Spring Boot 2.7.5、Spring Cloud&Alibaba 2021.0.5
-
前端框架: Vue 3.3.4、Ant-Design-Vue 3.0
-
持久层: MyBatis-Plus 3.5.2、Druid 1.2.22
-
权限框架: Sa-Token 1.29.0
-
数据库: 支持人大金仓（默认）、MySQL、Oracle、PostgreSQL等
-
缓存: Redis
-
文档: Knife4j 2.0.7
-
工具库: Hutool 5.8.20
1.2.2 主要特性
-
前后端分离架构：前端基于最新的Vue3 + Ant Design Vue，后端基于 Spring Boot，前后端核心技术均为主流技术。
-
开箱即用：无需进行复杂的二次集成。平台具备自动生成代码、接口管理、基于 RBAC 改进模型权限控制、数据大屏、Camunda 工作流、打印模板、在线接口、Xss 防跨站攻击等功能，并集成了集团组织架构同步、短信邮件平台、待办推送、CAS单点登录等功能。
-
在线自定义接口设计：用户只需要针对业务数据进行处理，即可在线生成接口，后端无需重新编译，实现“接口热插拔”，可供内外部进行调用，具备高扩展性、高移植性、高兼容性等特点。同时，平台提供大量接口相关功能，并提供大量接口示例，方便用户进行接口使用及系统集成。
-
统一授权、认证：平台使用“Sa-Token”实现统一安全认证中心，并支持与集团统一认证的CAS单点登录、与EIP门户和移动办公对接的互信机制。
-
灵活的权限控制：平台的权限控制基于RBAC改进模型，可通过组织架构信息，针对“功能”、“接口”、“数据”进行精细化管理，满足用户实施面向企业安全策略的需要。同时平台已实现集团三级管控模式的数据权限机制，方便实现平台单位对下属单位的数据管控需求。
-
移动端支持：平台支持以H5的方式集成到移动办公中。同时根据需求的不同，平台提供了数据展示页设计和功能页设计两种移动端界面生成方式，生成基础的移动端页面，集成了移动端业务的增删查改和流程审批功能。
-
代码生成器：平台基于“Mybatis-plus-generator”提供代码生成器功能，用户可通过可视化配置生成“Web 端”、“移动端”、“后端”代码，然后根据自身业务需要进行代码调整。生成的代码提供了基本的增删查改功能和流程审批集成，极大提高了代码开发效率。
-
零代码开发：平台提供自定义表单功能，根据平台提供的“组件池”，用户通过简单的拖拽及配置则可以完成功能的设计和发布，设计完成的功能无需生成代码，直接嵌入系统，实现功能“热插拔”。
-
工作流引擎：平台集成了符合BPMN设计规范的轻量级工作流引擎“Camunda”，功能更强大，架构更稳定。同时针对中国式工作流进行了深度的二次研发，提供了“表单发起流程”、“电子签章”、“流程委托”、“流程版本变更”、“流程传阅”等符合中国国情的工作流功能，并且重新设计了流程模板绘制页面，用户只需进行简单的拖拉拽和配置即可完成复杂的流程设计。
-
BI设计：平台除了支持帆软大屏的集成，还提供了一个简单的BI引擎（桌面设计）集成了百度 Echarts、地图等插件，内置了表格、统计指标等用户常用组件，用户可以通过0代码的方式设计并实现BI大屏页面，同时发布成菜单供系统用户进行查看，平台管理员可以通过功能授权对用户进行权限控制。针对复杂的大屏驾驶舱需求，平台集成了goView组件，提供了更加强大和丰富的BI大屏设计组件，并支持vue代码级的修改。
-
报表功能：除了支持帆软报表的集成，平台提供UReport报表开发和vue-plugin-hiprint打印组件，基于单元格迭代方式，可快速开发出各种类型复杂中式报表，同时可通过图形化配置实现“标准化”、“动态化”的打印模板，通过将模板中的相关组件绑定接口数据，可以实现传入不同数据显示不同的报表结果，最终完成“报表套打”、“格式规范”、“需要跟业务数据进行关联”的报表开发打印。
-
多租户数据隔离：平台通过mybatis的tenant机制实现“字段级别”的数据隔离，即保证数据隔离的安全，也可实现跨租户的数据交流。管理员可以在平台的“租户管理”中进行租户授权和功能授权，租户之间共用组织架构、功能代码但存在数据隔离。
-
信创数据库支持：平台可支持“人大金仓”、“达梦”、“高斯”等国产数据库，也兼容“MySQL”、“Oracle”、“PostgreSQL“等。
-
文件存储：集成minio文件存储管理组件和kkFileView文件预览组件。
-
定时任务：集成power-job定时任务，可动态完成任务的添加、修改、删除、暂停、恢复及日志查看等功能。
-
消息服务：集成了集团的短信和邮件服务。
-
安全功能：完善的xss防御、sql注入防御、黑白名单、接口限流、接口鉴权等。
1.3 快速上手
- 阅读《快速开发指南》明白整体开发流程
- 拉取空项目代码，修改数据库/redis等配置，启动项目程序
- 按照对应的前端/后端/移动端/大屏开发指南完成业务需求开发
- 查阅《常见业务场景开发示例》快速完成常见业务需求的开发
- 查阅《外部组件集成》与其他系统或服务进行对接集成
- 按照《部署指南》完成项目部署和上线
- 查阅《常见问题》快速定位常见问题原因和解决办法
- 查阅《核心功能设计和使用》了解框架底层设计思路，排查难度大的问题
- 查阅《更新日志》获取框架升级信息
2. 快速开发指南
2.1 环境要求
- JDK 8+
- Maven 3.6+
- MySQL 5.7+
- Redis 5.0+
2.2 项目配置
# application.yml
server:
port: 8080
spring:
datasource:
driver-class-name: com.mysql.cj.jdbc.Driver
url: jdbc:mysql://localhost:3306/xjrsoft?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
username: root
password: root
redis:
host: localhost
port: 6379
database: 0
2.3 启动项目
3. 核心功能使用
3.1 权限管理
- 基于Sa-Token的权限控制
- 支持多角色
- 支持数据权限
- 支持接口权限
- 支持菜单权限
3.2 数据访问
- MyBatis-Plus增强
- 多数据源支持
- 动态SQL
- 分页查询
- 逻辑删除
3.3 代码生成
- 支持多种数据库
- 自定义模板
- 前后端代码生成
- 表单配置生成
3.4 工作流
- 基于Camunda的工作流引擎
- 流程设计器
- 流程部署
- 任务管理
- 流程监控
3.5 报表功能
- 基于UReport的报表系统
- 报表设计器
- 数据源配置
- 报表预览
- 报表导出
3.6 文件存储
- 支持多种云存储
- 七牛云
- 阿里云OSS
- 腾讯云COS
- 华为云OBS
- MinIO
- 文件上传下载
- 文件预览
- 文件管理
3.7 消息服务
3.8 定时任务
- 基于Power-Job的分布式任务调度
- 任务管理
- 任务监控
- 任务日志
4. 后端开发
4.1 项目结构
src/main/java/com/xjrsoft/
├── common/ # 公共模块
├── config/ # 配置类
├── module/ # 业务模块
│ ├── authority/ # 权限模块
│ ├── system/ # 系统模块
│ ├── workflow/ # 工作流
│ ├── form/ # 表单模块
│ └── ...
└── ITCApplication.java
4.2 开发规范
-
代码规范
- 遵循阿里巴巴Java开发手册
- 使用Lombok简化代码
- 统一异常处理
- 统一返回格式
-
命名规范
- 类名: 大驼峰命名
- 方法名: 小驼峰命名
- 变量名: 小驼峰命名
- 常量名: 全大写下划线分隔
- 包名: 全小写点分隔
-
注释规范
- 类注释: 说明类的用途
- 方法注释: 说明方法的功能、参数、返回值
- 关键代码注释: 说明复杂逻辑
4.3 开发流程
- 创建数据库表
- 使用代码生成器生成基础代码
- 修改生成的代码
- 编写业务逻辑
- 编写单元测试
- 提交代码
4.1 单体版
4.1.1单体版说明
框架定位
全代码开发平台（以下简称“平台”）是基于 Spring Boot 2.7.5 + Vue 3 的单体架构快速开发框架，整合了集团技术中台的核心能力，提供开箱即用的开发环境，适用于定制化业务系统开发。
核心目标
-
降低开发门槛 ：提供标准化技术栈，减少环境搭建和基础组件开发成本。
-
提升开发效率 ：内置代码生成器、零代码表单、工作流引擎等工具，支持快速业务开发。
-
保障技术合规 ：遵循集团技术规范，集成安全、权限、信创数据库等企业级能力。
技术架构图 
本地开发流程
如下图，单体版所有代码都在本地，前后端分离，后端代码都在一个程序内，所以开发调试都是在本地，相对简单。
4.1.2初始化步骤
数据库初始化
数据库初始化见项目的script/mysql全库.sql或人大金仓全库脚本.sql
后端配置
创建配置文件application-local.yml用来做本地开发的配置
在application.yml配置文件中添加spring.profiles.active=local启用该新增的配置文件。
在新增的配置文件中，通过增加数据库链接、redis链接、单点回调地址、前端路由地址、生成代码路径等配置项
用自己的配置覆盖application.yml中的默认配置项。
注：其他环境的配置文件也通过这种方式进行管理。
启动后端
直接运行Application文件即可启动后端项目。
启动前端
前端运行前配置
修改.env文件，配置前端项目端口号：VITE_PORT=3100（自定义）
修改.env.development文件修改后端服务地址：VITE_GLOB_API_URL=http://127.0.0.1:8080/
前端运行
安装依赖：cd front npm install或pnpm install
运行：npm run serve即可启动前端项目
4.1.3开发示例
以下会演示创建一个带流程的测试表单以供参考
-
打开前端首页，输入用户名密码进行登录
-
创建数据表
-
点击左侧菜单：在线开发->代码生成
功能说明
界面优先：不需要事先准备表，先进行拖拉拽出界面，下一步后会自动根据表单生成表字段进行编辑
数据优先(较常用)：需要事先准备表，拖拉拽的每个组件需要和表字段进行关联
简易模版：可以拖拉拽出不需要数据表的的功能
快速生成代码：根据所选的表根据表字段自动生成表单
注：需根据实际业务需求进行代码生成，这里仅演示数据优先
-
填写基本信息
-
拖拉拽表单
需要从左侧组件框里找到合适的组件类型拖入表单区域，然后选中组件后设置其右侧的属性，绑定表、字段等属性
响应式(推荐开启)：开启后能够根据不同的屏幕尺寸、设备类型或容器大小自动调整其布局、样式或功能，以提供最佳的用户体验
-
表单事件
在此处可以添加自定义API、JS脚本到表单节点，比如表单加载前后、提交表单前后
-
界面设计
查询配置：定义列表页的查询项
列表配置：定义列表页的列属性、配置左侧的树配置、调整列的不同属性比如对齐方式、自适应宽度、列头筛选等
按钮设置：定义列表上的按钮，以及自定义按钮，需要注意如果开启流程需要勾选发起审批
-
代码预览
此步可以查看生成出来的代码
-
菜单设置
设置业务菜单信息，可以将生成的代码打包下载成独立文件后续可以导入，也可以直接将代码文件生成到项目中
-
生成代码与拷贝
前端代码会生成到配置文件application.yml中的 xjrsoft.generate.webPath=xxxxx 配置下（示例配置的路径是C:\Users\ITC\Desktop\codeGenerate）
后端由于选择了直接生成到项目中，后端文件会生成到src/main/java/com/xjrsoft/module/下
拷贝代码到项目，将生成的文件C:\Users\ITC\Desktop\codeGenerate\src目录下的api和views拷贝到项目的src对应的目录下
api目录：统一存放所有API请求定义，避免接口URL散落在各个组件中，便于维护
views目录：统一存放了页面组件，实现业务界面和用户交互
注：可以在api和views下添加自己的业务代码
-
重启项目
重启项目后刷新页面即可看到新增的菜单和功能
注：此时表单还没有进行流程配置，还需要配置流程
-
新增流程设计
点击菜单 工作流程->流程设计 点击新增流程按钮
1、从左侧拖入需要的用户节点、网关、结束节点等
2、填写右侧流程属性信息，选择默认表单为之前创建的工单
3、选择某个节点设置节点审批人
4、选择关联功能tab->勾选是否启用按钮->选择功能表单->流程已添加表单->勾选工单点击确认->最后选择更新表单按钮->保存模版
注：后续表单有字段调整也需要在此处更新表单并保存
-
新增表单完成
刷新页面再次进入刚才新增的菜单，可以看到表单已经关联流程
至此新增带流程表单就完成了
4.2 微服务版
4.2.1微服务版说明
微服务版本后端是共用一套基础服务，开发人员在本地运行自己的业务服务，连入集中的开发环境进行功能开发。
前端是只有一个前端项目不做拆分，本地运行整个前端项目，开发人员在上面添加自己的业务前端代码，连接共用的后端开发环境。
如下图，微服务版前端和业务服务后端的代码在本地，后端公共服务是部署在远程，本地接入远程的公共服务环境，再连回本地业务服务，相对复杂。
开发时生成的业务代码，需要开发人员访问共用的开发环境的base服务，把代码拉下来，与本地的业务代码比对后合并到本地代码中，再提交到代码仓库。后期会添加把生成的业务代码打包下载的功能。
因此前端部分的部署运行方式同4.1章节的单体版本，只是把后端地址改成共用的开发环境的gateway服务的地址。
4.2.2微服务版配置
微服务应用的配置主要是使用SpringBoot和Nacos的配置方式。
SpringBoot的bootstrap.yml配置了微服务应用的名称和端口，以及要接入的Nacos的注册和配置中心的地址、命名空间、分组，还有其他本地开发相关的或不能放置到Nacos的配置项。
4.2.3本地开发
- 在bootstrap.yml中给业务服务确定端口号和服务名。
- 修改spring.cloud.nacos的注册和配置中心为共用开发环境中的nacos地址、命名空间和分组。
- 启动服务。
- 如果业务服务需要使用自己的数据库，是在共用开发环境的多数据源中进行配置使用的。
本地开发业务服务接入远程公共服务
-
本地启动整个前端应用，例如local-front，连接的后端设置为远程公共服务的gateway服务；
-
本地启动要开发的业务服务，例如local-business-service，配置接入nacos的注册中心；
-
修改gateway服务路由的配置spring.cloud.gateway.routes，添加自己业务的资源路径路由到的本地服务的定义，例如
就是将前端应用/ast_asset/**路径的请求直接路由到本地开发的业务服务asset-service-yyn，即可将本地前后端应用对应运行起来进行开发。
注意，由于gateway的路由机制是从前往后匹配，匹配到即直接路由，因此业务服务的路由需要放置在最后一个通用路由规则之前，防止被路由到base服务去。
4.2.4开发示例
以下演示微服务版带流程的测试表单以供参考
-
nacos上确定所有服务都已启动
-
配置并启动前端
前端的.env文件的VITE_GLOB_API_URL指向远程公共服务的gateway服务ip:port
启动前端，输入用户名密码进行登录
-
创建并启动业务服务
创建启动业务服务后配置中接入nacos配置中心
配置cloud.nacos.config.server-addr=nacos配置中心地址
-
nacos添加业务资源路径
在nacos的配置中心找到对应的gateway配置，编辑spring.cloud.gateway.routes，增加自己的业务资源路径，发布更新即可
注意：需要将新增的配置放到最后一个通用路由规则之前，因为gateway匹配机制是从前向后的
-
准备业务数据表与新增代码生成
- 创建数据表
- 点击左侧菜单：在线开发->代码生成
功能说明
界面优先：不需要事先准备表，先进行拖拉拽出界面，下一步后会自动根据表单生成表字段进行编辑
数据优先(较常用)：需要事先准备表，拖拉拽的每个组件需要和表字段进行关联
简易模版：可以拖拉拽出不需要数据表的的功能
快速生成代码：根据所选的表根据表字段自动生成表单
注：需根据实际业务需求进行代码生成，这里仅演示数据优先
- 填写基本信息
- 拖拉拽表单
需要从左侧组件框里找到合适的组件类型拖入表单区域，然后选中组件后设置其右侧的属性，绑定表、字段等属性
响应式(推荐开启)：开启后能够根据不同的屏幕尺寸、设备类型或容器大小自动调整其布局、样式或功能，以提供最佳的用户体验
- 表单事件
在此处可以添加自定义API、JS脚本到表单节点，比如表单加载前后、提交表单前后
- 界面设计
查询配置：定义列表页的查询项
列表配置：定义列表页的列属性、配置左侧的树配置、调整列的不同属性比如对齐方式、自适应宽度、列头筛选等
按钮设置：定义列表上的按钮，以及自定义按钮，需要注意如果开启流程需要勾选发起审批
- 代码预览
此步可以查看生成出来的代码
- 菜单设置
设置业务菜单信息，可以将生成的代码打包下载成独立文件后续可以复制到项目
-
生成代码与拷贝
注：基础服务是公用的，所以代码生成都要用打包下载做例子，包括前端的
所以这里选择打包下载，会直接将前后端代码打包成压缩包自动下载
解压包结构如下，back：后端项目代码；front：前端项目代码
只需要将其复制到对应前后端项目中即可
api目录：统一存放所有API请求定义，避免接口URL散落在各个组件中，便于维护
views目录：统一存放了页面组件，实现业务界面和用户交互
注：可以在api和views下添加自己的业务代码
-
重启项目
重启项目后刷新页面即可看到新增的菜单和功能
注：此时表单还没有进行流程配置，还需要配置流程
-
新增流程设计
点击菜单 工作流程->流程设计 点击新增流程按钮
1、从左侧拖入需要的用户节点、网关、结束节点等
2、填写右侧流程属性信息，选择默认表单为之前创建的工单
3、选择某个节点设置节点审批人
4、选择关联功能tab->勾选是否启用按钮->选择功能表单->流程已添加表单->勾选工单点击确认->最后选择更新表单按钮->保存模版
注：后续表单有字段调整也需要在此处更新表单并保存
-
新增表单完成
刷新页面再次进入刚才新增的菜单，可以看到表单已经关联流程
至此新增带流程表单就完成了
4.2.5跨服务调用
注：跨服务调用（如 workorder-service 调用 user-service 或其他服务）使用 FeignClient
- 假设user-service服务提供getInfoByUserName接口
- 在workorder-service中定义FeignClient客户端接口
value：指定目标服务名（必须与注册中心一致）
path：指定该服务的统一API前缀
@GetMapping与目标服务的接口定义一致
- 在workorder-service的业务代码中调用
4.3 多租户模式
4.3.1 开启多租户模式
全开框架默认是单租户模式，如果需要开启多租户模式，需要修改前端代码和后端代码的配置文件。
（1）后端配置修改：
在项目 spring boot 配置文件中加上以下配置：
xjrsoft:
tenant:
enabled: true #是否启用多租户
admin-tenant-code: system #管理员租户编码
tenant-field: tenant_id #多租户 区分字段enantCode
default-tenant-code: system
is-use-default-tenant: true
hidden-sub-menu-ids:
- 1419273699655498176
- 1700041673784094722
ignore-table: #忽略多租户的表
- xjr_app_func_design
- xjr_app_menu
- xjr_app_page_design
- xjr_area
- xjr_code_schema
- xjr_databaselink
- xjr_language
- xjr_language_type
- xjr_liteflow_chain
- xjr_liteflow_script
- xjr_menu
- xjr_menu_button
- xjr_menu_column
- xjr_menu_form
- xjr_report
- xjr_report_relation
- xjr_subsystem
- xjr_tenant
- xjr_tenant_authorize
- xjr_app_menu_button
- xjr_app_menu_column
- xjr_app_menu_form
- xjr_app_authorize
- xjr_user
- xjr_department
- xjr_user_dept_relation
- xjr_authorize
- DEPT_TREE
- MENU_TREE
（2）前段配置修改：
在环境变量配置文件中加上变量 VITE_TENANT_ENABLED=true,如下图所示：
（3）给数据库表加上租户字段。
除了以上步骤（1）中配置了租户忽略的表（ignore-tabl:配置中列出的表））之外，其它数据表都加上 tenant_id 字段
加租户字段语句示例：ALTER TABLE xxx ADD tenant_id int8 NULL;
4.3.2 新建租户（站点）
1.使用系统管理员账号（账号：admin，租户码：system）登录系统。
2.找到“系统管理---租户管理"模块，点击新增租户，填写唯一的租户名称和租户编码以及其它信息，如下图所示：
3.点击功能授权，按需授予租户系统菜单的访问权限，如下图所示：
4.3.3 配置站点管理员和员工角色
1.使用系统管理员账号 admin，以目标站点的租户身份登录系统，如下图所示：
2.进入到角色管理模块，创建一个站点管理员角色和至少一个用户，将用户添加为站点管理员角色、如下图所示：
3.打开功能授权、接口授权，将菜单、按钮、列表和接口的所有权限授予站点管理员，使其拥有对站点的最高级别管理权限，如下图所示：
4.新建一个员工角色，按需授予其基本功能菜单权限。
4.3.4 表单个性化配置
假设场景：租户 B 需要用到某张表单 form01，而该表单已经存在 A 租户下，并且已经生成了代码。
1.可以通过以下步骤完成表单 form01 在租户 B 下的配置：
(1).将 xjr_form_template 表中的 id 字段的主键属性去掉；给 tenant_id 字段设置默认值为 1；创建联合主键(id,tenant_id)。
sql 语句参考如下：
去掉id字段的主键属性：
ALTER TABLE xjr_form_template DROP CONSTRAINT "xxxx"; ---xxxx请改成具体的主键名称
给tenant_id字段设置默认值：
ALTER TABLE xjr_form_template ALTER COLUMN tenant_id SET DEFAULT 1;
创建联合主键的语句：
ALTER TABLE xjr_form_template ADD CONSTRAINT xjr_form_template_pk PRIMARY KEY (id,tenant_id);
(2).将表单 form01 对应的表单数据拷贝一份（xjr_form_template 表）为 insert 语句；保持 id 字段的值不变，将 tenant_id 字段修改为租户 B 的租户 id；执行 insert 语句。
如图所示：
2.使用管理员账号 admin 以租户 B 的身份登录系统，在“表单设计”模块的“完整配置--> 渲染覆盖配置”中，可以根据租户需求，对表单详情页字段的名称和显隐、列表页展示字段、列表查询栏进行个性化配置。
配置方式：直接拷贝表单代码的 config.ts 文件中的配置粘贴到“渲染覆盖配置“一栏即可。
3.将需要进行个性化配置的表单的前端代码./components/config.ts路径中的配置useCustomConfig改成true.
配置示例：
现在用A租户的站点管理员账号登录系统，尝试对表单form01做以下配置：
（1）搜索栏配置成只保留姓名。
（2）列表栏展示姓名、性别、年龄，并且姓名字段改成显示成“名字”，占用500px宽度。
（3）表单详情页配置成显示姓名、性别，不显示年龄，并且将性别字段改成显示成英文“gender”
配置修改如下：
效果如下：
其它租户的表单个性化配置，可以通过同样的方式实现，可以用目标租户的站点管理员账号登录后进行配置，也可以用系统管理员admin以目标租户身份登录进行配置。
4.3.5 流程设计
配置方式：使用系统管理员admin，以目标租户的身份登录系统，进入到“流程定义”模块，按照常规流程定义步骤，完成该租户下指定表单的流程定义。
示例：
（1）以A租户的身份登录系统，进行流程设计
发起审批，效果如下：
（2）以B租户的身份登录系统，进行流程设计
发起审批，效果如下：
4.3.6 代码逻辑差异化
如果是业务代码层面的差异，不能通过表单自定义配置覆盖的情况，需将差异的代码修改为接口中执行，不同租户通过配置不同的接口事件触发，从而执行差异化的业务代码逻辑。
可供使用的接口配置有：流程回调事件配置、表单事件配置，组件触发事件配置。
1.流程回调事件配置:如图所示，可以在流程设计页面中，在流程审批过程中的各个环节配置事件以执行个性化的业务逻辑。
2.表单事件配置：如下图示例，在初始化表单阶段，配置一个事件节点，调用api记录用户查看表单的事件。
- 组件触发事件配置：如下图示例，给姓名字段配上blur事件，在失去焦点时，如果值不是男、女，则默认赋值为“男”
4.3.7 跨租户审批
打开跨租户的待办页面时，因为一个页面中包含很多个请求，只有第一个主请求有业务id的能查询数据所属租户，从而切换其他逻辑到另一个租户中处理，才能正确返回跨租户的数据，
但是页面后续的其他请求，例如枚举、触发事件之类的也需要同步传所属租户id才能正确返回跨租户的数据，但是组件数量太多，修改的工作量很大。
因此使用另一种切租户的方案：
待办列表返回有其他租户的数据，打开时如果单据不是当前租户的话，界面上提示用户：需要切换租户后才能打开，是否切换？是则自动切租户再跳转需要的待办，否则取消打开单据。
功能图示：
1.点击待办列表中的待审批流程，如果流程是从其它租户发起，则会弹出切换租户确定框。
2.切换完租户，页面右上角会弹出切换租户成功通知，用户可以继续完成审批操作。
4.3.8 以某个租户的身份执行数据库查询。
如果想临时以某个租户的身份执行一些数据库查询，可以通过以下方式实现：
try {
TenantUtil.doInTenant(1000000); --注意：该语句必须放在try{}代码块的第一行，以确保TenantUtil.doInTenant(tenantId)和TenantUtil.doInTenant()能同时得到执行
----代码块（在此代码块中的数据库查询，将会以id为1000000的租户的身份进行）
}finally{
TenantUtil.doInTenant();
}
4.3.9系统数据迁移功能
系统数据迁移功能可以用于跨环境数据迁移和跨租户数据复制。
1.相关概念说明：
跨环境数据迁移：简称数据迁移，指的是将数据从A环境迁移到B环境，常见于将数据从测试环境迁移到生产环境或者从生产环境迁移到测试环境。
跨租户数据复制:简称数据复制，指的是新建租户时，可以将现有租户的基础数据复制到新租户，以简化新租户的数据初始化过程。
2.功能讲解
（1）导出工作区：在导出工作区，选择需要导出的项目，然后点击“导出所选项目”完成对数据的导出。
说明：无论是数据迁移还是数据复制，导出步骤是一样的
（2）导入工作区：需要进行数据迁移时，请选择“覆盖模式导入”；需要数据复制时，请选择“租户模式导入”。
5. 前端开发
6. 移动端开发
7. 大屏开发
8. 外部组件集成
wps集成
金山文档在线预览编辑服务，提供了文件预览、文件编辑服务
框架中实现了wps所需要的回调接口，由文档中台直接回调业务系统中的接口：获取文件元数据、保存新文件、获取用户信息、通知等接口
流程
- 文档打开时会从后端获取文件在线编辑链接
- 前端向文档中台发起加载文件、权限等信息请求
- 文档中台向后端回调文件元数据、下载文件接口，后端返回文件元数据、文件数据
- 文档中台向前端返回文件、权限等信息
- 前端根据文件、权限、水印渲染文件内容
- 保存，文件编辑后会向中台发送文件保存新版本请求，文档中台回调后台上传文件新版本接口，后端返回保存结果后中台返回保存结果
- 通知，用户加入或退出协作请求获取用户信息回调接口，请求通知回调接口通知对接方此文件目前有哪些人在协作
直连模式
直连模式是业务系统不经由其他系统直接对接文档中台
注：需要在文档中台系统上配置回调接口地址为业务系统地址
启用和配置
在后端配置文件中的xjrsoft下配置weboffice.enabled=true即可启用
效果
前端字段类型为upload的组件后点击编辑文档按钮
只读模式
编辑模式 
保存文件
防火墙申请
直连模式需要申请业务端到文档中台间的防火墙
代理模式
代理模式流程
- 是业务系统提前向代理服务注册本系统的前缀及回调地址
- 前端向后端获取文件在线编辑链接
- 前端向文档中台发起加载文件、权限等信息请求；请求url中的文件id带上本系统的前缀
- 文档中台回调代理服务，代理服务根据回调的文件id前缀找到对应的业务系统地址
- 代理服务根据业务系统地址转发请求到业务系统，回调文件元数据、下载文件等接口
启用和配置
-
业务系统配置文件中增加系统标识用于区分不同业务系统
-
在代理服务系统中配置系统前缀和系统地址映射
效果
防火墙申请
代理模式需要申请
1、业务系统到文档中台的防火墙
2、代理系统到业务系统的防火墙
9. 部署指南
9.1 环境准备
- 可运行JDK环境（信创环境arm架构/麒麟系统，jdk为openjdk8以上）
- 生产环境建议双机热备加前置机共三台
- 需要安装的中间件：redis、nginx、kkfileview（附件预览）
- 需申请防火墙权限和资源的中间件：数据库（人大金仓）、minio（文件存储）、需要对接的系统：数据中台（人员组织同步）等
9.2 打包部署
# 打包
mvn clean package -DskipTests
# 运行
java -jar target/xjrsoft-framework.jar
9.3 Docker部署
# docker-compose.yml
version: '3'
services:
app:
build: .
ports:
- "8080:8080"
environment:
- SPRING_PROFILES_ACTIVE=prod
- SPRING_DATASOURCE_URL=jdbc:mysql://mysql:3306/xjrsoft
- SPRING_REDIS_HOST=redis
9.1 单体部署
9.1.1 前置条件
9.1.1.1 UML部署流程图
图1.1-1部署流程参考图
9.1.1.2 服务器配置
| 服务器 |
|
| IP地址 |
10.0.252.28 |
|
|
| 操作系统 |
|
| 名称 |
Debian GNU/Linux |
| 版本 |
10 (buster) |
|
|
| 资源配置 |
|
| CPU核心数 |
4核 |
| 内存 |
8GB |
| 磁盘 |
350GB（未核实） |
表1.2-1 部署的服务器说明表
9.1.1.3 软件依赖
9.1.1.4 目录规划
-
后端部署目录（新建项目目录）
/data/wps-proxy/back/wps-proxy-back2025061304.jar
-
前端资源目录（新建项目目录）
/data/wps-proxy/web/dist/index.html
-
Nginx 配置目录（默认目录）
/usr/local/nginx/conf/nginx.conf
9.1.2 后端部署
9.1.2.1 项目打包
- Ø使用Maven命令打包：
mvn package
- Ø或者使用Idea工具进行Maven打包，如图2.1-1所示
图2.1-1 部署打包说明图
Ø修改JAR包文件名称（以项目和版本日期加版本号数为目的，最终文件如图2.1-2所示）：wps-proxy-back2025061304.jar
图2.1-2 部署打包说明图
9.1.2.2 上传部署包
1、使用FTP工具(如图2.2-1和2.2-2所示)
图2.2-1 上传部署包参考图
图2.2-2 上传部署包参考图
Ø文件已经上传到服务器，将文件复制到指定文件夹即可(如下图2.2-3所示)：
cp /root/dne_back/wps-proxy-back2025061304.jar /data/wps-proxy/back/
图2.2-3 上传目录参考图
Ø最终文件目录如下(如下图2.2-4所示)：/data/wps-proxy/back/wps-proxy-back2025061304.jar
图2.2-4 上传目录参考图
9.1.2.3 编写脚本并启动服务
1、编写启动脚本
可直接使用命令启动（核心命令如下）：
nohup java -jar wps-proxy-back2025061304.jar --spring.profiles.active=dev > app.log 2>&1 &
也可编写启动脚本，示例：
#!/bin/bash
# 定义变量
JAR_NAME="wps-proxy-back2025061304.jar"
PROFILE="dev"
LOG_FILE="app.log"
# 停止已经运行的进程
echo "Stopping previous instance if exists..."
pkill -f $JAR_NAME
# 等待进程停止
sleep 3
# 启动应用
echo "Starting application..."
nohup java -jar $JAR_NAME --spring.profiles.active=$PROFILE > $LOG_FILE 2>&1 &
# 显示启动状态
if [ $? -eq 0 ]; then
echo "Application started successfully!"
echo "Log file: $LOG_FILE"
echo "You can check logs with: tail -f $LOG_FILE"
else
echo "Failed to start application!"
fi
2、将上述内容保存为 start.sh 文件
3、给脚本添加可执行权限：chmod +x start.sh
4、运行脚本：./start.sh
9.1.3 前端部署
9.1.3.1 项目打包
开发人员打包成dist文件夹,如下图3.1-1所示
Ø打包命令：npm run build
图3.1-1 前端打包说明图
最终文件夹：E:\Project\yuedian\wps-proxy\front\dist\
9.1.3.2 上传资源
1、使用FTP工具(如图3.2-1和3.2-2所示)
图3.2-1 上传前端包说明图
图3.2-2 上传前端包说明图
Ø文件夹已经上传到服务器，将文件夹整个复制到指定文件夹即可(如下图3.2-3所示)：
cp -r /root/dne_back/dist /data/wps-proxy/web/
图3.2-3 前端包目录说明图
Ø最终文件目录如下(如下图3.2-4所示)：/data/wps-proxy/web/dist
图3.2-4 前端包目录说明图
9.1.3.3 Nginx配置
1、配置前端页面和后端接口的反向代理
Ø输入下方命令打开Nginx的配置文件（如下图3.3-1所示）
vim cat /usr/local/nginx/conf/nginx.conf
图3.3-1 打开nginx配置文件说明图
Ø按“i”键即可进行vim文本插入
Ø在最下方的“}”符号内插入以下脚本命令，如下图3.3-2所示（按需修改）
server{
listen 80;
server_name 10.0.252.28;
root /data/wps-proxy/web/dist;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
location /api/ {
proxy_pass http://10.0.252.28:7020/;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
图3.3-2 修改nginx文件说明图
Ø最后按“Esc”键，再输入“:wq”即可保存。
2、重启nginx
Ø输入下方重载Nginx命令（如图所示）
/usr/local/nginx/sbin/nginx -s reload
9.1.3.4 应用配置
Ø这里需要修改页面调用的接口地址，输入以下命令编辑前端的配置文件，如图3.4-1所示
vim /data/wps-proxy/web/dist/_app.config.js
图3.4-1 前端配置文件说明图
Ø按“i”键即可进行vim文本插入
Ø将接口地址一项修改为服务器的IP和端口(Nginx代理后的地址)，如图3.4-2所示：
"VITE_GLOB_API_URL":`http://10.0.252.28:80/api`
图3.4-2 前端接口配置说明图
Ø最后按“Esc”键，再输入“:wq”即可保存。
9.1.4 验证部署
9.1.4.1 后端验证
1、打开接口文档（如图4.1-1），如下图所示代表服务启动成功（这里用服务的实际地址）：http://10.0.252.28:7020/doc.html#/home
图4.1-1 后端接口文档说明图
9.1.4.2 前端验证
1、打开页面首页（如图4.2-1），如下图所示代表配置成功（Nginx的配置和dist的配置文件配置）：http://10.0.252.28/#/login
图4.2-1 前端主页说明图
9.1.4.3 日志检查
1、打开后端日志
输入查看日志命令，如下图4.3-1所示代表启动成功：tail -f /data/wps-proxy/back/app.log
图4.3-1 后端日志说明图
2、打开Nginx日志
输入查看日志命令，如下图4.3-2所示最新日志没有出现报错日志即可：tail -f /usr/local/nginx/logs/error.log
图4.3-2 nginx错误日志说明图
9.2 Docker部署
9.3 K8S集群部署
文档背景
随着云原生技术的全面落地，我司基础设施已逐步向容器化与Kubernetes平台迁移。为规范生产级容器编排管理，提升部署效率与系统可靠性，特制定此K8s集群部署文档，重点达成以下目标：
技术架构统一化
·明确基于Kubernetes的标准化部署架构
·定义Namespace、Deployment、Service等核心资源的配置规范
部署流程标准化
·从镜像构建到集群发布的完整操作链路说明
运维协作可视化
·声明运维团队与开发团队的职责交接点
·提供资源申请、变更审批、故障排查的标准流程
本次文档编制既作为集群管理的技术基准，也作为跨团队云原生能力建设的指导手册，后续将随K8s版本迭代持续更新。
9.3.1 图示以及说明
9.3.1.1 组织架构图
图1.1-1组织架构图参考图
9.3.1.2 建设服务器说明
这里准备了四台服务器搭建集群（4节点），如图表1.2-1所示：
| 服务器 |
服务器最低要求 |
| 192.168.133.137 （node1）（作为master节点） |
CPU >= 2核心 / 内存>= 2GB / 能连接网络 |
| 192.168.133.138 （node2） |
CPU >= 2核心 / 内存>= 2GB / 能连接网络 |
| 192.168.133.139 （node3） |
CPU >= 2核心 / 内存>= 2GB / 能连接网络 |
| 192.168.133.140 （node4） |
CPU >= 2核心 / 内存>= 2GB / 能连接网络 |
表1.2-1 部署的服务器说明表
图1.2-1 部署的服务器说明图
9.3.2 初始配置
9.3.2.1 设置hosts文件（所有的节点都执行）
作用： 通过手动配置 /etc/hosts 文件，确保集群节点之间可以通过主机名直接解析 IP，避免依赖 DNS 服务，提高节点通信的稳定性和可靠性（验证如图2.1-1所示）。
Ø执行命令（这个IP改为自己服务器的IP）：
echo "192.168.133.137 node1
192.168.133.138 node2
192.168.133.139 node3
192.168.133.140 node4" >> /etc/hosts
Ø执行命令（验证）：cat /etc/hosts
图2.1-1 修改hosts说明图
9.3.2.2 设置hostname（所有的节点都执行）
作用： 为当前服务器设置永久主机名（如 node1），确保Kubernetes 集群节点能正确识别自身和同伴节点身份，避免因主机名冲突或未定义导致通信异常（如图2.2-1所示）。
Ø 执行命令（四台服务器分别使用node1/node2/node3/node4）：hostnamectl set-hostname node1
Ø 执行命令（验证）：cat /etc/hostname
图2.2-1 修改hostname说明图
9.3.2.3 时间同步（所有的节点都执行）
作用： 确保 Kubernetes 集群所有节点的时间保持同步，避免因时间偏差导致证书失效、日志混乱、调度异常等问题（如图2.3-1所示）。
Ø 执行命令（启动chronyd服务）：systemctl start chronyd
Ø 执行命令（设置）：systemctl enable chronyd
Ø 执行命令（验证）：date
图2.3-1 同步服务器时间说明图
9.3.2.4 设置防火墙（所有的节点都执行）
作用： 关闭防火墙（如 firewalld/iptables）可避免拦截 Kubernetes 集群组件间通信，确保节点、Pod 及服务正常互联，但生产环境建议改用精确放行规则以提升安全性（如图2.4-1所示）。
Ø执行命令（停止防火墙）：systemctl stop firewalld
Ø执行命令（开机关闭防火墙）：systemctl disable firewalld
Ø执行命令（验证）：systemctl status firewalld
图2.4-1 设置防火墙说明图
9.3.2.5 设置selinux（所有的节点都执行）
作用： 将selinux 从强制模式（enforcing）改为禁用模式（disabled），避免 Kubernetes 组件因安全策略限制导致权限不足或访问被拒绝的问题，简化集群部署流程（如图2.5-1所示）。
Ø执行命令（设置）：sed -i 's/enforcing/disabled/' /etc/selinux/config
Ø执行命令（验证）：getenforce
图2.5-1 设置SElinux说明图
9.3.2.6 设置swap分区（所有的节点都执行）
作用： Kubernetes 要求节点禁用交换分区（swap），以确保内存管理和调度策略（如 kubelet 的资源分配）能够正确工作，避免因swap 使用导致性能下降或不可预测的行为（如图2.6-1所示）。
Ø执行命令（设置）：sed -i "s/.swap./#&/" /etc/fstab
Ø执行命令（验证）：cat /etc/fstab
图2.6-1 设置swap说明图
9.3.2.7 设置网桥过滤和地址转发（所有的节点都执行）
作用：调整内核网络参数，确保 Kubernetes 的 CNI（容器网络插件，如 Calico、Flannel） 和 Service 网络（如 kube-proxy 的 iptables/IPVS 模式） 正常工作，解决容器跨节点通信和流量转发问题（如图2.7-1所示）。
Ø执行命令（设置）：
cat > /etc/sysctl.d/kubernetes.conf << EOF
net.bridge.bridge-nf-call-ip6tables = 1
net.bridge.bridge-nf-call-iptables = 1
net.ipv4.ip_forward = 1
EOF
Ø 执行命令（执行生效）：sysctl --system
Ø 执行命令（验证）：sysctlnet.bridge.bridge-nf-call-iptables net.ipv4.ip_forward
注意：如果报错系统当前缺少 bridge-nf-call-iptables 相关的内核模块支持，需要加载 br_netfilter 内核模块，执行加载命令：sudo modprobe br_netfilter
图2.7-1 设置网桥过滤和地址转发说明图
9.3.2.8 设置国内yum源（非必须，如需则所有的节点都执行）
作用： 将默认的 CentOS Yum 源替换为国内镜像（如阿里云），加速软件包下载，解决官方源访问慢或不可用的问题，确保 Kubernetes 依赖的组件（如 docker-ce、kubeadm）能快速安装（如图2.8-1所示）。
Ø 执行命令（备份当前的yum源）：mv /etc/yum.repos.d /etc/yum.repos.d.backup4comex
Ø 执行命令（新建空的yum源设置目录）：mkdir /etc/yum.repos.d
Ø 执行命令（下载阿里云的yum源配置）：curl -o /etc/yum.repos.d/CentOS-Base.repo https://mirrors.aliyun.com/repo/Centos-7.repo
Ø 执行命令（清除）：yum clean all
Ø 执行命令（重建）：yum makecache
图2.8-1 设置国内yum源说明图
9.3.3 安装Docker
9.3.3.1 设置国内docker源（非必须，如需则所有的节点都执行）
作用： 将 Docker 官方 Yum 仓库（download.docker.com）替换为阿里云镜像源，解决国内下载 Docker 组件（如 docker-ce、containerd.io）速度慢或无法访问的问题，确保容器运行时环境能快速安装（如图3.1-1所示）
Ø 执行命令（配置）： curl -o /etc/yum.repos.d/docker-ce.repo https://mirrors.aliyun.com/docker-ce/linux/centos/docker-ce.repo
Ø 执行命令（清除）：yum clean all
Ø 执行命令（重建）：yum makecache
图3.1-1 设置国内docker源说明图
9.3.3.2 下载docker（所有的节点都执行）
作用： Docker 作为容器运行时（Container Runtime）为 Kubernetes 提供底层容器管理能力（创建、运行容器），但新版 K8s 已转向更轻量的 containerd 或 CRI-O，不再强制依赖 Docker（如图3.2-1所示）。
Ø执行命令（下载）：yum install -y docker-ce-20.10.9-3.el7 docker-ce-cli-20.10.9-3.el7 containerd.io-1.6.6-3.1.el7 docker-compose-plugin-2.6.0-3.el7
图3.2-1 下载docker说明图
9.3.3.3 设置daemon.json（所有的节点都执行）
作用： 通过 daemon.json 配置 Docker 守护进程（dockerd）的核心参数，包括镜像加速、存储驱动、日志选项、网络设置等，以优化容器运行环境并适配 Kubernetes 需求。
Ø执行命令（创建目录）：mkdir /etc/docker
Ø执行命令（编辑文件）：vi /etc/docker/daemon.json
将daemon.json内容替换至如下内容并保存（如图3.3-1所示）：
{
"exec-opts": [
"native.cgroupdriver=systemd"
],
"log-driver": "json-file",
"log-opts": {
"max-size": "100m"
},
"storage-driver": "overlay2",
"storage-opts": [
"overlay2.override_kernel_check=true"
]
}
图3.3-1 配置daemon.json文件说明图
9.3.3.4 启动docker（所有的节点都执行）
Ø 执行命令（启动）：systemctl restart docker
Ø 执行命令（开机自启）：systemctl enable docker
Ø 执行命令（验证如图3.4-1所示）：systemctl status docker
图3.4-1 启动docker说明图
9.3.4 安装Kubernetes
9.3.4.1 设置国内Kubernetes源（所有的节点都执行）
作用： 将 Kubernetes 官方 Yum 仓库（https://packages.cloud.google.com）替换为阿里云镜像源，解决国内无法访问或下载速度慢的问题，确保kubeadm、kubelet、kubectl 等组件能够快速、稳定安装（如图4.1-1所示）。
Ø执行命令：
cat <<EOF > /etc/yum.repos.d/kubernetes.repo
[kubernetes]
name=Kubernetes
baseurl=https://mirrors.aliyun.com/kubernetes/yum/repos/kubernetes-el7-x86_64/
enabled=1
gpgcheck=0
repo_gpgcheck=0
gpgkey=https://mirrors.aliyun.com/kubernetes/yum/doc/yum-key.gpg https://mirrors.aliyun.com/kubernetes/yum/doc/rpm-package-key.gpg
EOF
Ø 执行命令（清除）：yum clean all
Ø 执行命令（重建）：yum makecache
图4.1-1设置国内Kubernetes源示意图
9.3.4.2 下载kubeadm/kubelet /kubectl（所有的节点都执行）
Ø 执行命令（下载，如图4.2-1所示）： yum install -y kubelet-1.23.0 kubeadm-1.23.0 kubectl-1.23.0
Ø 执行命令（启动）：systemctl status kubelet
Ø 执行命令（开机自启,非必须）：systemctl enable kubelet
图4.2-1安装K8S组件示意图
9.3.5 部署Kubernetes集群
9.3.5.1 预下载镜像（在master节点执行）
作用：预先从阿里云镜像仓库下载 Kubernetes 控制平面所需的所有容器镜像，确保 kubeadm init 初始化 master 节点时能快速顺利完成，避免因网络问题导致安装失败（如图5.1-1所示）。
Ø 执行命令（拉取）：kubeadm config images pull --image-repository registry.aliyuncs.com/google_containers
图5.1-1预下载镜像示意图
9.3.5.2 初始化kubernetes（在master节点执行）
Ø 执行命令：
kubeadm init \
--apiserver-advertise-address=192.168.133.137 \
--image-repository registry.aliyuncs.com/google_containers \
--kubernetes-version v1.23.0 \
--service-cidr=10.96.0.0/12 \
--pod-network-cidr=10.244.0.0/16 \
--ignore-preflight-errors=all
备注：
–apiserver-advertise-address # 集群通告地址（master 机器IP）
–image-repository # 由于默认拉取镜像地址k8s.gcr.io国内无法访问，这里指定阿里云镜像仓库地址
–kubernetes-version #K8s版本，与上面安装的一致
–service-cidr #集群内部虚拟网络，Pod统一访问入口，可以不用更改，直接用上面的参数
–pod-network-cidr #Pod网络，与下面部署的CNI网络组件yaml中保持一致，可以不用更改，直接用上面的参数
Ø上述命令执行完之后控制台末尾有加入集群的join命令，需要复制记录下来，子节点加入集群需要用到该命令（如图5.2-1所示）示例：
kubeadm join 192.168.133.137:6443 --token gx38zz.iokskhaa4uehb9nr--discovery-token-ca-cert-hash sha256:5e84b16ac4c5c52da4225162b1574316797e518d26e8dd0c26a2aa6a3253038c
图5.2-1初始化K8S示意图
9.3.5.3 设置kubectl命令行工具环境（在master节点执行）
作用：配置 kubectl 的访问权限、设置环境变量、优化命令行体验，确保能顺利使用 kubectl管理 Kubernetes 集群（如图5-3.1所示）。
Ø执行命令（创建目录）：mkdir -p $HOME/.kube
Ø 执行命令（复制文件）：sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
Ø执行命令（修改权限）：sudo chown $(id -u):$(id -g) $HOME/.kube/config
Ø执行命令（修改环境变量）：vim /root/.bash_profile
将.bash_profile内容末尾追加如下内容并保存：
# 超级用户变量
export KUBECONFIG=/etc/kubernetes/admin.conf
# 设置别名
alias k=kubectl
# 设置kubectl命令补齐功能
source <(kubectl completion bash)
Ø 执行命令（环境变量生效）：source /root/.bash_profile
图5.3-1配置kubectl示意图
9.3.5.4 设置kubernetes网络（在master节点执行）
作用：安装 Flannel CNI 插件，为Kubernetes 集群提供 Pod 网络，使节点状态变为 Ready 并支持跨节点 Pod 通信。
Ø 执行命令（安装插件）：wget https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml
Ø 执行命令（修改配置）：vim kube-flannel.yml
将kube-flannel.yml对应内容替换至如下内容并保存（如图5.4-1所示）：
net-conf.json: |
{
"Network": "10.244.0.0/16",
"Backend"": {
"Type": "vxlan"
}
}
图5.4-1配置kube-flannel.yml文件示意图
Ø 执行命令（配置生效）：kubectl apply -f kube-flannel.yml
Ø 执行命令（查看pod状态）：kubectl get pod --all-namespaces
注意：全部服务必须要为Running状态才行（如图5.4-2所示）。
图5.4-2验证pod状态示意图
9.3.5.5 子节点加入集群（在所有子节点执行）
Ø 执行命令（9.3.5.2步骤执行完初始化之后控制台末尾的加入集群的join命令，如图5.5-1所示）：kubeadm join 192.168.133.137:6443 --token gx38zz.iokskhaa4uehb9nr--discovery-token-ca-cert-hash sha256:5e84b16ac4c5c52da4225162b1574316797e518d26e8dd0c26a2aa6a3253038c
图5.5-1子节点加入集群示意图
注意：默认的kubeadm join Token有效期为24小时。如果子节点加入集群失败，请在Master节点执行以下命令重新生成Token，并在所有子节点重新加入集群指令（如图5.5-2所示）：kubeadm token create --print-join-command
图5.5-2子节点加入集群示意图
Ø 执行命令（在master节点执行，验证）：kubectl get nodes
所有节点状态显示 Ready（如图5.5-3所示），表示子节点已成功加入集群，部署完成！
图5.5-3集群节点状态验证示意图
9.3.6 ARM64架构使用二进制离线的方式安装集群
9.3.6.1 准备离线包
在联网环境准备离线包(需要安装docker)，或者让实施人员直接提供离线包（跳过本章直接从9.3.6.2章节开始）。
离线包文件结构如下表所示：
| k8s-offline-arm64-20250630.tar.gz |
scripts
images
------quay.io_coreos_flannel_v0.14.0-arm64.tar
------registry.aliyuncs.com_google_containers_etcd_3.5.1-0.tar
------registry.aliyuncs.com_google_containers_kube-apiserver_v1.23.0.tar
------registry.aliyuncs.com_google_containers_kube-controller-manager_v1.23.0.tar
------registry.aliyuncs.com_google_containers_kube-proxy_v1.23.0.tar
------registry.aliyuncs.com_google_containers_kube-scheduler_v1.23.0.tar
------registry.aliyuncs.com_google_containers_pause_3.6.tar
configs
------daemon.json
binaries
------cni-plugins-linux-arm64-v1.1.1.tgz
------containerd-1.6.6-linux-arm64.tar.gz
------docker-20.10.9.tgz
------kubernetes-server-linux-arm64.tar.gz
kube-flannel.yml
image-list.txt |
Ø 执行命令（创建离线包目录）：mkdir -p /root/offline-pkg/{binaries,images,scripts,configs}
Ø 执行命令（下载Docker CE）：wget -P /root/offline-pkg/binaries \ https://download.docker.com/linux/static/stable/aarch64/docker-20.10.9.tgz
Ø 执行命令（设置版本变量）：K8S_VER="v1.23.0"
Ø 执行命令（下载Kubernetes组件）：wget -P /root/offline-pkg/binaries \ https://dl.k8s.io/$K8S_VER/kubernetes-server-linux-arm64.tar.gz
Ø 执行命令（下载依赖工具）：wget -P /root/offline-pkg/binaries \ https://github.com/containerd/containerd/releases/download/v1.6.6/containerd-1.6.6-linux-arm64.tar.gz
Ø 执行命令（下载CNI插件）：wget -P /root/offline-pkg/binaries \ https://github.com/containernetworking/plugins/releases/download/v1.1.1/cni-plugins-linux-arm64-v1.1.1.tgz
注意：TAR包也可以直接在浏览器打开直接下载（下载好手动拉到指定目录/root/offline-pkg/binaries），例如浏览器打开：https://download.docker.com/linux/static/stable/aarch64/docker-20.10.9.tgz
Ø 执行命令（创建镜像列表文件）：
cat > /root/offline-pkg/image-list.txt <<EOF
registry.aliyuncs.com/google_containers/kube-apiserver-arm64:$K8S_VER
registry.aliyuncs.com/google_containers/kube-controller-manager-arm64:$K8S_VER
registry.aliyuncs.com/google_containers/kube-scheduler-arm64:$K8S_VER
registry.aliyuncs.com/google_containers/kube-proxy-arm64:$K8S_VER
registry.aliyuncs.com/google_containers/pause:3.6
registry.aliyuncs.com/google_containers/etcd:3.5.1-0
quay.io/coreos/flannel:v0.14.0-arm64
EOF
Ø 执行命令（拉取并保存镜像）：
while read img; do
docker pull $img
save_name=$(echo $img | sed 's|/|_|g; s|:|_|g')
docker save $img -o "/root/offline-pkg/images/${save_name}.tar"
done < /root/offline-pkg/image-list.txt
Ø 执行命令（准备Docker配置文件）：
cat > /root/offline-pkg/configs/daemon.json <<EOF
{
"exec-opts": [
"native.cgroupdriver=systemd"
],
"log-driver": "json-file",
"log-opts": {
"max-size": "100m"
},
"storage-driver": "overlay2",
"storage-opts": [
"overlay2.override_kernel_check=true"
]
}
EOF
Ø 执行命令（Flannel配置）：wget -O /root/offline-pkg/kube-flannel.yml \ https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml
sed -i's#10.244.0.0/16#10.244.0.0/16#g' /root/offline-pkg/kube-flannel.yml
Ø执行命令（打包为离线文件）：tar -czvf k8s-offline-arm64-$(date +%Y%m%d).tar.gz -C /root/offline-pkg .
9.3.6.2 离线包分别复制到目标服务（所有的节点都执行）
图6.2-1服务器离线包文件示意图
Ø 执行命令（创建目录）：mkdir -p /root/offline-pkg/
Ø 执行命令（解压）：bsdtar -xzf k8s-offline-arm64-*.tar.gz -C /root/offline-pkg/
9.3.6.3 执行文档步骤9.3.2.1至9.3.2.7设置基础环境（所有的节点都执行）
图6.3-1服务器设置基础环境示意图
9.3.6.4 安装docker（所有的节点都执行）
Ø 执行命令：cd /root/offline-pkg
Ø 执行命令（解压）：bsdtar -xzf docker-20.10.9.tgz -C /tmp
Ø 执行命令（复制）：sudo cp -v /tmp/docker/* /usr/bin/
Ø 执行命令（设置执行权限）： sudo chmod 755 /usr/bin/{dockerd,docker,containerd,containerd-shim,containerd-shim-runc-v2,ctr,runc,docker-init,docker-proxy}
Ø 执行命令（创建systemd服务）：
cat > /etc/systemd/system/docker.service <<EOF
[Unit]
Description=Docker Application Container Engine
After=network.target
[Service]
Type=notify
ExecStart=/usr/bin/dockerd
ExecReload=/bin/kill -s HUP $MAINPID
LimitNOFILE=infinity
LimitNPROC=infinity
TimeoutStartSec=0
[Install]
WantedBy=multi-user.target
EOF
Ø 执行命令（配置Docker）：mkdir /etc/docker
Ø 执行命令（复制Docker配置）：cp configs/daemon.json /etc/docker/
Ø 执行命令（自启Docker）：systemctl enable docker
Ø 执行命令（启动Docker）：systemctl start docker
图6.4-1离线安装docker示意图
9.3.6.5 安装K8S（所有的节点都执行）
Ø 执行命令：cd /root/offline-pkg
Ø 执行命令（解压K8S）：tar -xzf binaries/kubernetes-server-linux-arm64.tar.gz -C /usr/local
Ø 执行命令：cd /usr/local/kubernetes/server/bin
Ø 执行命令（复制）：cp kubeadm kubelet kubectl /usr/local/bin/
Ø 执行命令：cd /root/offline-pkg
Ø 执行命令：mkdir -p /opt/cni/bin
Ø 执行命令(解压CNI插件)：tar -xzf binaries/cni-plugins-linux-arm64-v1.1.1.tgz -C /opt/cni/bin
Ø 执行命令（配置kubelet服务）：
cat > /etc/systemd/system/kubelet.service <<EOF
[Unit]
Description=Kubernetes Kubelet
After=docker.service
[Service]
ExecStart=/usr/local/bin/kubelet \
--container-runtime=remote \
--container-runtime-endpoint=unix:///run/containerd/containerd.sock \
--pod-infra-container-image=registry.aliyuncs.com/google_containers/pause:3.6
Restart=always
StartLimitInterval=0
[Install]
WantedBy=multi-user.target
EOF
Ø执行命令（启动）：systemctl enable kubelet
Ø执行命令（加载容器镜像）：
for img in images/*.tar; do
docker load -i $img
done
图6.5-1加载镜像示意图
9.3.6.6 执行文档步骤9.3.5.2和9.3.5.3设置主节点环境（在master节点执行）
图6.6-1设置主节点环境示意图
图6.6-2设置主节点环境示意图
9.3.6.7 设置kubernetes网络（在master节点执行）
Ø 执行命令（加载）：kubectl apply -f /root/offline-pkg/kube-flannel.yml
9.3.6.8 执行文档步骤9.3.5.5加入集群（在所有子节点执行）
9.3.7 结语
当前 Kubernetes 集群已完成标准化部署，系统将按以下机制运行：
Ø高可用保障：Master 节点采用多实例部署，默认启用 kubelet 自动恢复机制
Ø网络就绪：Flannel CNI 已配置 10.244.0.0/16 Pod 网段（VXLAN 后端模式）
Ø证书管理：kubeadm 自动生成证书有效期 1 年，到期前需执行 kubeadm certs renew
后续运维人员可通过以下方式管理集群：
Ø使用 kubectl 命令行工具或部署 Kubernetes Dashboard 进行可视化操作
Ø通过 kubeadm upgrade 进行集群版本升级（需遵循版本迭代规范）
Ø按需扩展 Node 节点（join token 有效期 24h，需及时更新）
如需调整网络插件、存储方案或安全策略，请联系基础设施团队评估变更影响。
9.4 流水线部署
文档背景
随着 DevOps 理念的深入实践，我司已实现开发人员提交代码后的全自动化构建部署流程。为帮助开发团队更清晰地理解 CI/CD 自动化机制，特修订此文档，重点说明：
职责边界明确化
·开发人员仅需关注代码提交至 Git 仓库
·后续构建、测试、部署全流程由 Jenkins 自动完成
流程透明化
·详细解析从代码提交到应用上线的完整链路
·说明各环节的触发条件、执行逻辑和预期结果
问题定位标准化
·提供构建失败时的关键检查点和日志分析指引
·建立统一的异常处理流程
本次修订旨在提升团队对自动化流水线的认知度，确保开发与运维的高效协作。
9.4.1 图示以及说明
9.4.1.1 UML流程图
图1.1-1 流程参考图
9.4.1.2 基础建设服务说明
| 服务 |
IP和端口 |
| Java |
10.4.126.62 |
| 数据库（金仓数据库） |
10.0.252.76:54321 |
| Redis |
10.0.250.17:6379 |
| 文件服务器（Minio） |
10.0.252.28:9000 |
| Nacos |
10.0.252.1:8849 |
表1.2-1 部署服务说明表
注：本文档不再详细展开基础建设服务的部署细节(如Mysql,Redis,Minio等)，相关内容可参考组织过程资产库相关开发文档。
9.4.2 Jenkins的搭建及初始配置
9.4.2.1 Jenkins服务器配置
| 服务器 |
|
| IP地址 |
10.0.252.12 |
|
|
| 操作系统 |
|
| 名称 |
Kylin Linux Advanced Server |
| 版本 |
V10 (Halberd) |
|
|
| 资源配置 |
|
| CPU核心数 |
32核 |
| 内存 |
32GB |
| 磁盘 |
300GB |
表2.1-1 服务器配置说明表
9.4.2.2 下载及安装Jenkins
Ø 打开服务器界面(如图2.2-1所示)
图2.2-1服务器界面示意图
Ø 输入docker下载Jenkins命令（docker基础建设这里不赘述（可参考9.3.3章节））：
docker run -p 8080:8080 -p 50000:50000 --name jenkins- -v /usr/docker/jenkins_data:/var/jenkins_home
-d jenkins/jenkins:lts
指令解析：
-p：端口映射， 左边是本地端口，右边是docker容器端口 ，8080是Jenkins Web 界面的工作端口,50000是JNLP（Java Network Launch Protocol）工作端口。这个端口用于 Jenkins 节点和主控节点之间的通信。
-v：目录挂载，将主机上的 /usr/docker/jenkins_data 目录挂载到容器内的
/var/jenkins_home 目录，用于持久化 Jenkins 的数据。
Ø安装成功输入命令检查：docker ps（如图2.2-2所示）
图2.2-2 docker安装jenkins并启动容器示意图
9.4.2.3 初始配置
Ø进入Web页面,浏览器打开：http://10.0.252.12:8080/
Ø按照页面提示打开初始密码文件进行复制,输入密码(如图2.3-1所示)
图2.3-1Jenkins打开web页面并输入初始密码示意图
Ø选择安装推荐的插件(如图2.3-2所示)
图2.3-2Jenkins安装推荐的插件示意图
Ø随后让我们创建一个管理员账户，正常创建即可（后续可手动创建Jenkins用户）如图2.3-3所示。
图2.3-3Jenkins创建用户示意图
Ø成功进入Jenkins页面(如图2.3-4所示)
图2.3-4Jenkins进入主界面示意图
9.4.2.4 配置插件环境
由于Jenkins标准安装未包含Maven项目所需的完整支持，需通过以下插件实现自动化构建能力：
核心插件清单
·Maven Integration ：提供POM解析、生命周期控制等Maven原生支持
·Git Plugin ：实现代码仓库的版本控制与触发构建
·JDK Tool ：管理Java环境隔离与版本切换
部署策略
(二选一)使用服务器级插件部署(这里系统基础建设这里不赘述)如图2.4-1（非Jenkins页面安装），优势包括：
·统一版本管控（与运维规范对齐）
·避免Jenkins重启导致的插件依赖中断
·支持离线环境下的稳定运行
图2.4-1插件安装成功示意图
(二选一)也可使用 Jenkins页面安装：
Ø点击（如图2.4-2所示）：系统管理
图2.4-2Jenkins插件管理示意图
Ø点击：插件管理
Ø依次搜索并下载核心插件, 如图2.4-3所示
图2.4-3Jenkins插件安装示意图
配置验证
需确保：
·插件已正确注册至Jenkins运行时环境
·Jenkins全局工具配置中绑定对应二进制路径
Ø点击：系统管理
Ø点击：全局工具配置
Ø填写配置项：maven和java以及git（如图2.4-4至2.4-6所示）
图2.4-4配置Maven插件环境示意图
图2.4-5配置JAVA插件环境示意图
图2.4-6配置Git插件环境示意图
9.4.2.5 节点配置
Ø点击：系统管理（如图2.5-1所示）
图2.5-1系统节点示意图
Ø点击：节点和云管理
Ø点击新增节点：New Node（如图2.5-2所示）
图2.5-2添加节点示意图
Ø依次添加集群节点信息（如图2.5-3至2.5-4所示）
图2.5-3系统节点配置示意图
图2.5-4系统节点配置示意图
Ø点击：保存
最终节点列表效果如图2.5-5所示
图2.5-5系统节点列表示意图
9.4.2.6 服务器SSH配置
Jenkins将通过SSH私钥的方式链接远程服务器。
Ø点击：系统管理（如图2.6-1所示）
图2.6-1系统配置示意图
Ø点击：系统配置
找到Publish over SSH
Ø输入Passphrase（私钥key，如图2.6-2所示）
图2.6-2服务器私钥配置示意图
Ø输入Path to key（私钥文件的服务器路径）：.ssh/id_rsa
Ø输key（私钥的完整文本内容）
找到SSH Servers
Ø依次添加服务器信息（如图2.6-3所示）
例如：
Name: 10.0.252.12
Hostname: 10.0.252.12
Username: root
Ø点击：保存
图2.6-3服务器ssh配置示意图
9.4.2.7 凭据配置
凭据配置是Jenkins用于访问远程链接所需要的凭据。
Ø点击：系统管理-凭据管理-System-全局凭据 (unrestricted)-Add Credentials（如图2.7-1）
Ø填写：用户名-密码-描述
Ø点击：保存（如图2.7-2）
图2.7-1添加系统凭据示意图
图2.7-2系统凭据配置示意图
9.4.3 构建自由风格任务（二选一）
9.4.3.1 新建文件夹管理
该步骤是为了以项目的维度分类管理所有构建任务，包括前端项目后端的项目等等,提升运维效率。
Ø点击：新建任务（如图3.1-1所示）
图3.1-1创建文件夹管理示意图
Ø输入任务名称：智慧审计-test（如图3.1-2所示）
Ø类型选择：文件夹
Ø点击：确定
图3.1-2创建文件夹任务示意图
9.4.3.2 创建自由风格后端任务
Ø在新建的文件夹目录里左上角点击：新建Item（如图3.2-1所示）
图3.2-1创建后台项目示意图
Ø输入任务名称：audit-back-sit（如图3.2-2所示）
Ø类型选择：构建一个自由风格的软件项目
Ø点击：确定
图3.2-2创建后台项目示意图
9.4.3.3 任务配置
Ø输入项目描述（如图3.3-1所示）：构建智慧审计后端SIT环境
图3.3-1任务描述配置示意图
Ø勾选：丢弃旧的构建（如图3.3-2所示）
Ø填写保持构建的最大个数（此项的目的是只保留构建的三个版本）：3
图3.3-2任务配置示意图
ØJDK选择：jdk-8（如图3.3-3所示）
Ø勾选：限制项目的运行节点（作用是控制项目构建任务在指定的 Jenkins 节点（Node）上执行，如图3.3-4所示）
Ø标签表达式输入并选中：agent_amd64_1
图3.3-3构建配置示意图
图3.3-4构建节点配置示意图
Ø源码管理选择：Git（如图3.3-5所示）
Ø Repository URL输入代码仓库地址：https://fcd.gdyditc.com/itc/ZHSJ/back.git
Ø Credentials资格证明（选择拥有该仓库权限的用户,点击“+”号可手动添加用户）：如yangjiewei
Ø 指定分支输入：*/dev
图3.3-5 Git配置示意图
Ø 触发器选择：轮询SCM（如图3.3-6所示）
Ø 输入Cron表达式：H(0-29) 12,18 * * *
（每天12:00和18:00之间的随机时间点执行(0-29分)）
图3.3-6 触发器配置示意图
添加构建步骤,这里总共有两个类型步骤。
Ø 步骤1点击：增加构建步骤（如图3.3-7所示）
Ø 选择步骤类型：调用顶层Maven目标
Ø 选择Maven版本：maven-3.9.9（如图3.3-8所示）
Ø 填写目标：clean install -U -Dmaven.test.skip=true
(主要用于清理项目并安装依赖，同时跳过测试)
图3.3-7 添加maven步骤示意图
图3.3-8 maven步骤配置示意图
Ø 步骤2点击：增加构建步骤（如图3.3-9所示）
图3.3-9 SSH步骤配置示意图
Ø 选择步骤类型：Send files or execute commands over SSH
Ø 选择Name：10.4.126.62（如图3.3-10所示）
(部署的远程服务器地址)
图3.3-10 服务步骤配置示意图
Ø 填写Source files：target/audit-0.0.1-SNAPSHOT.jar
(指定需要传输到远程服务器的本地文件路径)
Ø 填写Remove prefix：target
(移除指定的前缀路径)
Ø 填写Remote directory：/data/apps/audit-ma-sit
(文件传输到远程服务器的目标目录)
Ø 填写Exec command(文件传输完成后，在远程服务器上执行的Shell 命令,如图3.3-11所示),命令如下：
mkdir -p /data/apps/audit-ma-sit
cd /data/apps/audit-ma-sit
cat <<\EOF | tee deploy.sh
#!/usr/bin/env bash
source /etc/profile
DIR_PATH="/data/apps/audit-ma-sit"
SOURCE_JAR="audit-0.0.1-SNAPSHOT.jar"
TARGET_JAR="audit-ma-sit.jar"
PROJECT_ARGS="--spring.profiles.active=test --server.port=8080"
LOG_NAME="audit-ma-sit.log"
stop_process() {
echo "将结束 $TARGET_JAR 的进程"
pkill -9 -f $TARGET_JAR
if [ $? -eq 0 ];then
echo "$TARGET_JAR 关闭成功"
else
echo "$TARGET_JAR 未启动"
fi
}
post_process() {
if [ -e $TARGET_JAR ];then
echo "备份原包 $TARGET_JAR"
# mv $TARGET_JAR $TARGET_JAR$(date "+%Y%m%d%H%M%S")
rm ${TARGET_JAR}.bak
mv $TARGET_JAR ${TARGET_JAR}.bak
fi
mv $SOURCE_JAR $TARGET_JAR
}
start_process() {
nohup java -jar $TARGET_JAR $PROJECT_ARGS &>/dev/null &
if [ $? -eq 0 ];then
echo "$TARGET_JAR 启动成功"
else
echo "$TAR_NAME 启动失败"
fi
}
checkout() {
if [ ! -e $SOURCE_JAR ];then
echo "没找到 $SOURCE_JAR"
exit
fi
}
cd $DIR_PATH
checkout
stop_process
post_process
start_process
EOF
chmod +x deploy.sh
上述命令的执行效果如下：
·创建 /data/apps/audit-ma-sit 目录（如果不存在）。
·生成 deploy.sh 部署脚本，实现：
·检查新构建的 audit-0.0.1-SNAPSHOT.jar 是否存在。
·停止当前运行的 audit-ma-sit.jar 进程。
·备份旧jar 包（重命名为 .bak）。
·替换新jar 包并启动。
·赋予 deploy.sh 可执行权限，方便后续直接运行。
这样，每次 Jenkins 构建完成后，只需执行 ./deploy.sh 即可完成自动化部署。
图3.3-11 Shell脚本配置示意图
Ø 在该步骤下方继续点击： Add Server（如图3.3-12所示）
图3.3-12 步骤配置示意图
Ø 选择Name(远程服务器地址)：10.4.126.62（如图3.3-13所示）
图3.3-13 服务配置示意图
Ø 填写Exec command(在远程服务器上执行的Shell 命令)：
cd /data/apps/audit-ma-sit
./deploy.sh
上述命令的执行效果如下：
·进入指定目录
·执行deploy.sh脚本命令
Ø 最后点击：保存（如图3.3-14所示）
图3.3-14 保存配置示意图
Ø（可选）可手动点击：启动构建（如图3.3-15所示）
图3.3-15 启动构建任务示意图
Ø （可选）点击查看项目的启动日志:控制台输出（如图3.3-16至3.3-17所示）
图3.3-16 任务日志查看示意图
图3.3-17 任务日志查看示意图
9.4.4 构建流水线任务（二选一）
Jenkins 流水线构建（Pipeline）和自由风格构建（Freestyle）的区别
| 维度 |
流水线构建（Pipeline） |
自由风格构建（Freestyle） |
| 配置存储位置 |
Jenkinsfile存储在代码仓库（如Git） |
配置保存在Jenkins服务器本地 |
| 灵活性 |
高（支持复杂逻辑、条件判断、并行任务） |
低（仅支持简单线性步骤） |
| 版本控制 |
与代码同仓库，追溯变更历史,进行控制、审核和迭代 |
无版本控制，需手动备份 |
| 适用场景 |
复杂CI/CD流程（多环境、微服务） |
简单任务（单次构建、定时执行） |
表4-1 Pipeline和Freestyle区别说明表
9.4.4.1 新建文件夹管理
该步骤是为了以项目的维度分类管理所有构建任务，包括前端项目后端的项目等等,提升运维效率。
Ø点击：新建任务（如图4.1-1所示）
Ø输入任务名称：智慧审计-test（如图4.1-2所示）
Ø类型选择：文件夹
Ø点击：确定
图4.1-1创建文件夹管理示意图
图4.1-2创建文件夹任务示意图
9.4.4.2 创建流水线后端任务
Ø在新建的文件夹目录里左上角点击：新建Item（如图4.2-1所示）
Ø输入任务名称：audit-back-sit（如图4.2-2所示）
Ø类型选择：流水线
Ø点击：确定
图4.2-1创建后台项目示意图
图4.2-2创建后台项目示意图
9.4.4.3 任务配置
Ø输入项目描述（如图4.3-1所示）：构建智慧审计后端SIT环境
图4.3-1任务配置示意图
Ø勾选：丢弃旧的构建（如图4.3-2所示）
Ø填写保持构建的最大个数（此项的目的是只保留构建的三个版本）：3
图4.3-2任务配置示意图
Ø 触发器选择：轮询SCM（如图4.3-3所示）
Ø 输入Cron表达式：H(0-29) 12,18 * * *
（每天12:00和18:00之间的随机时间点执行(0-29分)）
图4.3-3任务配置示意图
（流水线定义选择 Pipline script from SCM是指定一个代码仓库（如Git、SVN）中的脚本文件路径, 如果选择Pipline script则是直接在文本框中编写Pipeline脚本（Groovy代码）。这里Pipeline script from SCM 支持两种方式加载 Jenkinsfile：
1、Jenkinsfile
与项目代码同仓库：可以将Jenkinsfile放在项目的根目录（如图4.3-8所示）
2、Jenkinsfile
与项目代码不同仓库：页面配置 Jenkinsfile 所在的 Git 仓库地址，并在 Jenkinsfile 内容里通过
checkout scm 或 git 命令拉取项目代码。这里我们选择第二种）
Ø 流水线定义选择(如图4.3-4所示)：Pipline script from SCM
Ø SCM选择(如图所示)：Git
Ø Repository URL输入Jenkinsfile的仓库地址（需要创建对应的Jenkinsfile仓库，如图4.3-5至4.3-7所示）：https://fcd.gdyditc.com/practice/jenkins-pipeline.git
Ø Credentials资格证明（选择拥有该仓库权限的用户,点击“+”号可手动添加用户）：如18565418931
Ø 指定分支输入（Jenkinsfile的仓库的分支）：*/dev
Ø 脚本路径（Jenkinsfile的仓库内的相对路径）：sit/audit-back/Jenkinsfile-sit
图4.3-4任务配置示意图
图4.3-5任务配置示意图
图4.3-6Jenkinsfile所在Git目录示意图
图4.3-7Jenkinsfile所在Git目录示意图
图4.3-8Jenkinsfile所在项目目录示意图
Ø最后点击：保存（如图4.3-9所示）
图4.3-9保存示意图
Ø（可选）可手动点击：启动构建（如图4.3-10所示）
图4.3-10 启动构建任务示意图
Ø （可选）点击查看项目的启动日志:控制台输出（如图4.3-11至4.3-12所示）
图4.3-11任务日志查看示意图
图4.3-12 任务日志查看示意图
Ø至此流水线的配置已经完成，接下来就是调试Jenkinsfile脚本文件。
9.4.4.4 构建脚本说明
这里提供两种Jenkinsfile构建方案设计
- 一体化构建方案
将所有构建流程（如创建目录、生成部署脚本、检查、停止、备份、替换、赋权及执行脚本等）集中编写在Jenkinsfile中，实现全流程自动化管控。
Jenkinsfile脚本示例：
pipeline {
agent any
// 环境变量定义
environment {
DEPLOY_DIR = "/data/apps/audit-ma-sit"
SOURCE_JAR = "audit-0.0.1-SNAPSHOT.jar"
TARGET_JAR = "audit-ma-sit.jar"
JAVA_ARGS = "--spring.profiles.active=test --server.port=8080"
DEPLOY_USER = "deploy-user" //目标服务器用户名
DEPLOY_SERVER = "10.4.126.62" //目标服务器IP
SSH_CREDENTIALS = "deploy-ssh-key" // Jenkins中配置的SSH凭据ID
}
triggers {
pollSCM('H * * * *')
}
options {
gitConnection('https://fcd.gdyditc.com/itc/ZHSJ/back.git')
timeout(time: 15, unit: 'MINUTES') // 构建超时设置
}
stages {
stage('初始化部署环境') {
steps {
// 本地生成部署脚本（同原逻辑）
sh """
mkdir -p ${DEPLOY_DIR}
cd ${DEPLOY_DIR}
cat <<'EOF' > deploy.sh
#!/bin/bash
DIR_PATH="${DEPLOY_DIR}"
SOURCE_JAR="${SOURCE_JAR}"
TARGET_JAR="${TARGET_JAR}"
PROJECT_ARGS="${JAVA_ARGS}"
stop_process() {
echo "[$(date)] Stopping \${TARGET_JAR}..."
pkill -9 -f \${TARGET_JAR} || echo "Service not running"
}
post_process() {
[ -f \${TARGET_JAR} ] && \
mv \${TARGET_JAR} \${TARGET_JAR}.bak && \
echo "Backup created: \${TARGET_JAR}.bak"
}
start_process() {
nohup java -jar \${TARGET_JAR} \${PROJECT_ARGS} > console.log 2>&1 &
[ \$? -eq 0 ] && \
echo "Started! PID: \$(pgrep -f \${TARGET_JAR})" || \
echo "Failed!"
}
cd \${DIR_PATH}
[ ! -f \${SOURCE_JAR} ] && { echo "Error: \${SOURCE_JAR} missing"; exit 1; }
stop_process
post_process
mv \${SOURCE_JAR} \${TARGET_JAR}
start_process
EOF
chmod +x deploy.sh
"""
}
}
stage('传输部署包') {
steps {
// 使用SSH Agent插件安全传输
sshagent(credentials: [SSH_CREDENTIALS]) {
sh """
# 打包本地文件
tar -czf ${TARGET_JAR}.tar.gz -C ${DEPLOY_DIR} .
# 传输到目标服务器
scp -o StrictHostKeyChecking=no \
${TARGET_JAR}.tar.gz \
${DEPLOY_USER}@${DEPLOY_SERVER}:/tmp/
# 远程解压并执行
ssh -o StrictHostKeyChecking=no \
${DEPLOY_USER}@${DEPLOY_SERVER} "
mkdir -p ${DEPLOY_DIR}
tar -xzf /tmp/${TARGET_JAR}.tar.gz -C ${DEPLOY_DIR}
cd ${DEPLOY_DIR} && ./deploy.sh
rm -f /tmp/${TARGET_JAR}.tar.gz
"
"""
}
}
}
}
post {
success {
slackSend(color: 'good',
message: "SUCCESS: ${JOB_NAME} deployed to ${DEPLOY_SERVER}")
sh """
echo "Deployment validated:"
ssh ${DEPLOY_USER}@${DEPLOY_SERVER} \
\"pgrep -f ${TARGET_JAR} && curl -s http://localhost:8080/health\"
"""
}
failure {
slackSend(color: 'danger',
message: "FAILED: ${JOB_NAME} - Check ${BUILD_URL}")
}
always {
// 清理临时文件
sh "rm -f ${DEPLOY_DIR}/${TARGET_JAR}.tar.gz"
}
}
}
2.模块化构建方案
将启动脚本独立拆分至项目代码库，支持按服务粒度定制或参数化调用，Jenkinsfile仅负责调度执行，提升灵活性与可维护性。
Ø这里Jenkinsfile的脚本命令将通过远程执行命令，所以Jenkins服务器需要下载相应插件，下载命令：sudo yum install sshpass
Jenkinsfile脚本示例：
node("agent_amd64_1"){
// 构建前清理工作空间
step([$class: 'WsCleanup'])
// 1工程名（服务名）
def project_name='audit-back'
// 2工程部署目标服务器ip（自己linux机器地址）
def deploy_ip='10.4.126.63'
// 3工程启动端口
def port='8080'
// 4环境标识
def env='dev'
//5这里要改标识码和仓库路径
stage('Checkout') {
checkout([$class: 'GitSCM', branches: [[name: '*/dev']], doGenerateSubmoduleConfigurations: false, extensions: [], submoduleCfg: [], userRemoteConfigs: [[credentialsId: 'f0c86da7-7d54-4f77-aedf-31fe43b51fbe',url: 'https://fcd.gdyditc.com/itc/ZHSJ/back.git']]])
}
// 跳过测试打包
stage('Archive Artefact') {
sh "mvn package -Dmaven.test.skip=true"
//6 这里要改服务器的标识码
withCredentials([usernamePassword(credentialsId:'7d49d98-8e4a-4e5b-acb4-6e0bb5010e7', usernameVariable: 'USERNAME', passwordVariable: 'PASSWORD')]){
stage("Deploy to $env") {
// 清理目标服务器旧文件
sh "sshpass -p $PASSWORD ssh $USERNAME@$deploy_ip \" rm -rf /home/$USERNAME/$project_name \" "
// 本地打包
sh "mkdir $project_name"
sh "cp ./target/*.jar $project_name"
sh "cp ./script/startup.sh $project_name"
sh "tar -cvf $project_name'.tar' $project_name "
// 传输并解压
sh "sshpass -p $PASSWORD scp $project_name*.tar $USERNAME@$deploy_ip:/home/$USERNAME/ "
sh "sshpass -p $PASSWORD ssh $USERNAME@$deploy_ip \"cd /home/$USERNAME;tar -xvf $project_name*.tar \" "
sh "sshpass -p $PASSWORD ssh $USERNAME@$deploy_ip \"cd /home/$USERNAME;rm -f $project_name*.tar \" "
// 启动服务（防止Jenkins杀死进程）
withEnv(['JENKINS_NODE_COOKIE=dontKillMe']) {
//这里调用启动脚本传入两个参数
sh "sshpass -p $PASSWORD ssh $USERNAME@$deploy_ip \"cd /home/$USERNAME/$project_name; chmod +x startup.sh;/bin/bash -l startup.sh $env $port \" "
}
}
}
}
Ø上述的Jenkinsfile调用了一个启动脚本（startup.sh），启动脚本所在的项目位置参考下图4.4-1所示
图4.4-1 startup.sh脚本所在目录示意图
startup.sh启动脚本示例：
#!/usr/bin/env bash
projectName=audit-back
target=$1
port=$2
health_url="http://127.0.0.1:$port/actuator/health"
echo "target = "$target
pid=`ps -ef |grep 'java' |grep $projectName |grep $port |awk '{print $2}'`
if [ -n "$pid" ]; then
kill -9 $pid
sleep 3
fi
case $target in
dev)
JAVA_OPTS="-Xms512m -Xmx512m -Xss256k -Xmn256m -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=384m -XX:SurvivorRatio=8"
JAVA_OPTS="$JAVA_OPTS -XX:+UseConcMarkSweepGC -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:../logs/$projectName/gc.log"
JAVA_OPTS="$JAVA_OPTS -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=../logs/$projectName/dump"
JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=$target -Dserver.port=$port "
nohup java -jar $JAVA_OPTS $projectName*.jar > /dev/null &
;;
sit | tag)
JAVA_OPTS="-Xms512m -Xmx512m -Xss256k -Xmn256m -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=384m -XX:SurvivorRatio=8"
JAVA_OPTS="$JAVA_OPTS -XX:+UseConcMarkSweepGC -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:../logs/$projectName/gc.log"
JAVA_OPTS="$JAVA_OPTS -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=../logs/$projectName/dump"
JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=$target -Dserver.port=$port "
nohup java -jar $JAVA_OPTS $projectName*.jar > /dev/null &
;;
uat)
JAVA_OPTS="-Xms1024m -Xmx1024m -Xss256k -Xmn256m -XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=384m -XX:SurvivorRatio=8"
JAVA_OPTS="$JAVA_OPTS -XX:+UseConcMarkSweepGC -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:/home/logs/$projectName/gc.log"
JAVA_OPTS="$JAVA_OPTS -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=..logs/$projectName/dump"
JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=uat -Dserver.port=$port "
nohup java -jar $JAVA_OPTS $projectName*.jar > /dev/null &
;;
prod)
JAVA_OPTS="-Xms2048m -Xmx2048m -Xss256k -Xmn256m -XX:MetaspaceSize=256m -XX:MaxMetaspaceSize=384m -XX:SurvivorRatio=8"
JAVA_OPTS="$JAVA_OPTS -XX:+UseConcMarkSweepGC -XX:+PrintGCDetails -XX:+PrintGCDateStamps -Xloggc:../logs/$projectName/gc.log"
JAVA_OPTS="$JAVA_OPTS -XX:+HeapDumpOnOutOfMemoryError -XX:HeapDumpPath=../logs/$projectName/dump"
JAVA_OPTS="$JAVA_OPTS -Dspring.profiles.active=$target -Dserver.port=$port "
nohup java -jar $JAVA_OPTS $projectName*.jar > /dev/null &
;;
*)
echo "No this ENV:$target."
exit 1
;;
esac
sleep 20
for ((i=0;i<20;i++))
do
curl -s ${health_url} > health
state=`cat health |grep status |grep UP`
if [ ${#state} -gt 10 ]; then
break
else
echo "Waiting for start ..."
sleep 5
fi
done
if [ ${#state} -gt 10 ]; then
echo "Deploy Success"
exit 0
else
echo "Deploy Fail"
exit 1
fi
上述startup.sh启动脚本内容如下：
- 基本参数设置
projectName: 项目名称，这里是 audit-back。
target: 第一个参数，表示部署的目标环境（如 dev、sit、uat、prod 等）。
port: 第二个参数，表示项目启动的端口号。
health_url: 健康检查的 URL，用于检测项目是否成功启动（基于 Spring Boot Actuator 的 /health 端点）
- 停止已有进程
- 根据环境启动项目
JVM 配置:
堆内存：-Xms512m -Xmx512m（初始和最大堆内存均为 512MB）。
线程栈：-Xss256k。
年轻代：-Xmn256m。
元空间：-XX:MetaspaceSize=128m -XX:MaxMetaspaceSize=384m。
垃圾回收：使用 CMS 收集器（-XX:+UseConcMarkSweepGC），并打印 GC 日志。
OOM 时生成堆转储文件。
Spring 配置:
激活指定的 Profile（-Dspring.profiles.active=$target）。
设置服务端口（-Dserver.port=$port）。
通过 nohup 后台启动项目，并将日志输出到 /dev/null（丢弃日志）
- 健康检查
等待 20 秒后，开始检查健康状态。
循环最多 20 次，每次间隔 5 秒，通过 curl 访问 health_url。
如果响应中包含 UP 状态，则认为启动成功，退出循环。
- 结果判断。
startup.sh启动脚本功能总结
停止旧进程：确保端口和项目无冲突。
动态配置：根据环境（dev/sit/uat/prod）调整 JVM 参数。
启动项目：后台运行 Java 服务。
健康检查：通过 Actuator 接口验证服务是否就绪。
9.4.5 结语
当前 Jenkins 自动化部署流水线已完成全链 路配置，系统将按以下机制运行：
Ø 定时构建：每日通过 Poll SCM 自动轮询代码仓库变更（配置频率：H(0-29) 12,18 * * *）
Ø 事件触发：支持 Git Webhook 实时触发代码更新部署
Ø 版本追溯：每次构建关联 Git Commit ID 与制品版本
后续开发人员可基于此环境：
Ø 按需创建微服务/前后端构建任务
Ø 参考本文档的权限管理及流水线设计规范
如需扩展部署场景或调整流程，请联系 DevOps 团队协同优化。
10. 常见问题
10.1 权限问题
Q: 如何配置接口权限?
A: 在Controller方法上添加@SaCheckPermission注解
10.2 数据源问题
Q: 如何配置多数据源?
A: 在application.yml中配置多数据源,并在Service上使用@DS注解
10.3 缓存问题
Q: 如何使用Redis缓存?
A: 使用@Cacheable注解或RedisTemplate
11. 常见业务场景开发示例
12. 更新日志
v2.0.1 (2024-03-31)
- 新增ChatGPT集成
- 优化代码生成器
- 修复已知问题
v2.0.0 (2024-02-26)
- 升级Spring Boot到2.7.5
- 升级MyBatis-Plus到3.5.1
- 新增工作流引擎