运行环境
项目运行环境 更新时间:2024-05-16 17:09:14单机部署
当选择项目导出后,可直接在服务器或本地PC中运行。操作系统支持linux,windows和mac,包括各种国产linux操作系统,比如麒麟系列,统信OS等等。
项目部署时,需要依赖以下环境:
- 【必须】jdk 8或以上 — java基础运行时;
- 【必须】redis:2.8以上 — 项目启动基础依赖;
- 【可选】数据库:mysql 8以上,或postgresql,达梦,oracle (19c+), 不同的数据库,需在项目导出时在配置面板中选择;
- 【可选】nacos:2.3.1 — 微服务注册中心;
以上环境中,jdk和redis是必须的,否则项目无法运行;
数据库是可选的,如果没有用到ivx数据库组件可以不需要,但此时请注意删除config.json中的”database”字段。对于mysql,iVX本身的db操作是可以支持5.7.9以上版本,但由于使用的数据库迁移工具flyway暂时为免费的社区版本,它只支持mysql8.0以上,因此,如果不需要flyway相关功能,或者使用team版本的flyway,也可以使用mysql 5.7.9以上的5.7版本。
nacos也是可选的,仅当应用中有微服务客户端或使用了用户中心之后,才需要配置。同理,如果不需要使用nacos,请在config.json中删除“micro”字段。nacos可以替换成zookeeper, 需要在“micro”中删掉nacos地址,换成zookeeper地址。
docker部署
项目可以选择打包为docker。比如,在默认导入的框架源码中,包含一个docker file:
FROM openjdk:17-jdk-alpine as builder
COPY build/libs/.jar application.jar
RUN java -Djarmode=layertools -jar application.jar extract
FROM openjdk:17-jdk-alpine
COPY —from=builder dependencies/ ./
COPY —from=builder spring-boot-loader/ ./
COPY —from=builder snapshot-dependencies/ ./
COPY —from=builder application/ ./
COPY n.zip resource.jso[n] config.jso[n] ./
ENTRYPOINT [“java”, “org.springframework.boot.loader.JarLauncher”]
在这个docker file中,指定了基于轻量级操作系统alpine linux构建一个应用docker的步骤。通过docker build,可直接将导出的项目打包为docker,在k8s环境中运行。iVX的企业私有部署方案,也提供了基于docker一键推送与部署功能,详见文档。
配置
项目的配置 更新时间:2024-05-16 15:25:51在项目导出之前,可以在应用的菜单栏中侧区域->配置->应用配置->私有部署导出配置 中,修改项目配置:
以下是所有配置项的详细说明:
1、应用信息
应用信息是用于应用导出时的文件命名与播放路径指定,将成为项目代码的一部分。我们可以根据需求来指定,也可以不填直接使用默认值。其中各个字段的意义如下:
- 播放路径:应用的播放路径,比如指定为“/test”, 那么,在本地部署后,项目的播放地址就是 localhost:8000/test, 其中,8000是在【2】端口号中填写的端口;
- 项目包名:比如 com.example.demo, 其中 com.example为当前应用业务代码的主目录,通常为企业域名的反向拼写,demo为项目名称(artifact),为编译jar包时的包名:
- 应用标识:项目中每个应用的名称,即主目录下每个应用的目录名称,以及应用中controller和service文件的前缀:
2、端口(port)
项目运行端口,如在同一台服务器上起多个项目,端口不能重复
3、数据库(database)
数据库配置,如项目中使用了数据库组件,则必须配置。
- 数据库(driver): 本地测试暂时建议使用mysql,系统也支持其他关系型数据库,比如postgres, sql server等;
- 访问地址(addr):数据库访问地址,默认是本地安装的地址,也可以使用云数据库或其他服务器上安装的数据库;
- 登录用户名(user):数据库登录用户名;
- 登录密码(passwd):数据库登录密码;
- 目标库名称(dbName):必填项,目标库名称,注意,iVX应用在部署时,会自动创建与更新表结构,但不会自动创建库,因此这里指定的库,需要预先手动创建好;
4、redis
redis配置,redis是应用运行必备资源,默认使用本地安装的redis,如果配置不正确应用将无法正常启动。
- addr:redis访问地址,默认为本地安装的redis,也可以使用云资源;
- passwd:redis访问密码;
- db:redis中的db,默认0;
5、文件存储配置(oss)
应用中的各种文件存储位置,比如前端js文件,图片资源文件,用户在应用运行时上传的文件等等。默认使用本地文件系统。
- provider:文件存储位置,默认为filesystem,即本地文件系统,目前也额外支持“aliyun”与“minio”
- pathPrefix:文件访问路径前缀,可以为本地文件路径,或线上对象存储服务(比如阿里云oss)的文件访问路径,注意,如果文件配置了cdn,这里需要填cdn访问的文件地址;
————以下配置项,仅在使用云平台对象存储服务时需要指定:————
- endpoint:当选择云存储时,需要指定对象服务访问地址,比如 “oss-cn-hangzhou.aliyuncs.com”;
- accessKeyId:对象存储云平台访问key,可在云平台上查看;
- accessKeySecret:对象存储云平台访问秘钥,可在云平台上查看;
- bucket:对象存储桶名称;
- bucketInPath:存储桶是否通过路径指定,目前仅微软的azure云需要将此项设为true,其他云平台保留默认值false即可;
6、micro
微服务注册中心,如项目中使用了微服务,或使用了用户中心(用户中心与业务应用的通信,依赖微服务),则必须配置,如果没有使用到则可以不配置。
- registry:微服务注册中心地址
- name:微服务名称,可使用默认的nid/gid, 无需修改
以上配置项中,除了【1】应用信息,是嵌入在项目代码中的信息,其他配置存在于项目根目录下的config.json中:
文档反馈
运行
项目的运行 更新时间:2024-05-16 17:10:13完成项目配置,导出项目后,并确保项目依赖的资源可正常访问,项目就可以运行了。我们找到src/main/java/com/example目录下的“DemoApplication.java”, 在VScode或IDEA编辑器中,直接运行它:(注意,com/example和Demo是在上一节应用配置中配置的名称,这里只是用默认名称举个例子)
此时,IDE会完成项目的编译与本地运行。如果没有编译报错或config文件配置问题,项目就可以顺利运行起来,我们通过localhost:端口号/播放路径,就可以在本地预览完整项目了:
特别注意:如果项目中使用了跨项目的微服务,即单应用使用了微服务,或组应用使用了非组内而是全局的微服务,或者,应用绑定了用户中心,那么必须要将微服务的提供应用或者用户中心运行起来之后,当前项目才能运行。否则会由于微服务不存在而启动失败。
除了在IDE里运行,我们也可以使用命令行来运行项目,首先在命令行中切换至项目主目录,然后使用 bash gradlew bootRun 指令,就可以运行项目了。
打包
项目打包 更新时间:2024-04-22 15:24:29项目可打包为jar包或docker镜像。
通过命令行,在项目根目录下运行:bash gradlew bootJar 可生成项目jar包(包生成到当前根目录的 build/libs/中,如果需要更改包生成的位置,可以更改gradle配置,具体可以查询gradle相关文档)。
生成完成后,继续在根目录上运行 java -jar build/libs/demo-0.0.1-SNAPSHOT.jar,即可将项目跑起来。
注意,如果需要在其他目录中运行jar文件,需要将导出文件中的config.json和应用zip文件一起复制到运行目录:
比如,我们新建一个目录,javaTest,然后把jar文件和以上几个静态文件都挪进去:
然后我们cd至这个javaTest目录,直接跑 java -jar demo-0.0.1-SNAPSHOT.jar 就可以运行项目了。
如果当前环境安装了docker,也可以直接在根目录下运行:docker build . -t myapp, 来编译docker镜像。docker镜像编译后,可直接用k8s部署。针对私有部署企业用户,iVX也提供了在编辑器中一键推送镜像的服务。
镜像编译后即可使用docker run -d myapp运行容器,此时容器将基于镜像内的config.json配置启动,运行容器时可重新指定config配置,有两种方式可以指定:
1,通过环境变量CONFIG_JSON : docker run -d -e CONFIG_JSON=’{“port”:80….}’ myapp ,{“port”:80….}表示实际的配置
2,通过挂载配置文件:docker run -d -v /path/to/your/config.json:/config.json myapp ,/path/to/your/config.json表示本地实际config.json文件的位置
推荐使用方式2,特别是当config配置中含有引号或其他特殊字符时,使用方式1出现无法识别命令的概率极高且难以处理。
二次开发
项目二次开发 更新时间:2024-04-22 15:25:58如果需要手动在导出的项目中添加服务或修改服务逻辑,为了确保手动修改的代码与iVX后续导出的代码不冲突,建议使用以下方法:
1、需要手动添加的服务,首先在iVX中创建一个占位服务,并定义好入参、出参;
2、在custom目录下,新建一个服务implements,custom目录是iVX项目导出时默认建的空目录,也可以自己任意新建目录,但不要使用iVX默认的service目录;
3、在服务中,使用@primary 标签,替换掉iVX中原有的服务实现,即可实现自定义服务代码功能;
比如,在这个示例项目中(下载项目工程),我们自定义了服务,使用mybatis来访问数据库,而不是使用系统默认的db方法类。
注意,不建议直接修改iVX默认的service目录下的服务实现,再次导出iVX项目后,会覆盖手动修改的部分。使用以上@primary标签覆盖的方法,可以实现iVX导出的代码与手动修改的代码相互不冲突,在iVX导出代码之后,可上传至git,并通过git进行代码管理。在私有部署的企业系统中,iVX也提供内部git代码一键推送功能。
推送
一键推送与一键部署 更新时间:2024-04-22 15:26:31在私有部署的iVX系统中,支持对接企业内部的k8s容器集群,将iVX应用一键推送至测试与生产环境。
1、配置镜像仓库
首先,从工作台进入镜像仓库,然后在仓库设置界面,配置部署服务地址,这个是iVX在完整系统部署时,会部署的仓库管理后台程序,由于每个企业环境部署结构可能不同,这里需要在镜像仓库中进行配置。然后,可以添加仓库管理员,管理员可以对生产环境的部署请求进行审核。
2、推送应用镜像包
在iVX编辑中完成一个应用开发后,可选择推送部署包,指定应用名称和版本描述后,这个部署包会被推送至镜像仓库。在推送部署包时的过程中,iVX会完成以下工作:
- java源码导出、编译
- docker镜像编译、上传
- 生成helmchart部署包
如果当前应用是一个组应用中的一个子应用,则部署包会包含一个组中所有的应用。在iVX中,一个组应用会被当成一个项目,一个项目对应一个容器。
这一步的常见问题:
1、java源码可能出现编译出现编译失败问题
由于线上预览环境为代码实时解析模式,没有经过编译,因此在少数一些场景下,可能会出现java源码编译失败,如果编译失败,可以根据编译失败提示,一键定位到问题事件块。如果依然不能解决问题,可以导出源码后手动编译查看。
3、在镜像仓库中部署应用
推送成功后,刷新镜像仓库,可以看到刚刚推送的部署包。
选择一键部署,出现部署配置弹窗:
在部署配置中,可配置以下部分内容:
1、部署环境
可选测试或生产环境。测试或生产环境的地址,是在系统配置中指定的,用户无需在部署时指定。如选择部署至生产环境,则需要通过管理员审核。
2、环境变量
如果在应用中指定了环境变量,那么环境所有的环境变量出现在部署配置中,在部署时进行修改。环境变量的作用是在无需重新导出应用包的情况下修改应用的一些行为。
在编辑器中,环境变量在配置面板中配置:
在公式编辑器默认下拉列表中,可引用环境变量:
3、容器规格与伸缩
选择容器配置,测试环境建议使用1核2G以上的配置,生产环境根据需求选择更高的配置。同时,可以配置伸缩规则,当cpu/内存超过一定量之后自动扩展。
iVX产出的所有应用,都是无本地状态的,即不依赖任何容器本地的持久化数据,因此可以任意伸缩扩展。
4、后台资源配置
即mysql ,redis,文件系统等后台资源的地址,在iVX部署系统时,已存入默认配置,这一项通常不用修改,但如果需要临时调整资源,或测试新的资源,可以对这些资源地址进行手动修改。注意,如果资源配置设置有误,或新配置的资源无法连接,会导致容器无法正常运行。
各项配置完成,选择一键部署后,将启动k8s容器,自动出现容器状态界面:
可查看当前容器日志:
4、应用更新与回滚
应用更新与回滚的流程和新部署流程完全一致,在一键部署界面中,可选择不同的版本进行部署:另选版本进行部署之后,在新的容器启动之前,旧的容器不会被销毁,应用依旧可以正常访问。
5、日志与监控
iVX后台的日志功能,可接入各种云服务,或本地部署的日志服务。除了在容器日志中查看实时日志,还可以在日志服务中对历史日志进行查看和分析。6、取消部署
针对已经部署的应用,可以取消部署,取消部署后,k8s中的服务、路由等各种应用相关资源会一起销毁。已取消部署的应用,可以进一步选择移除部署包。