环境部署

码匠君 ... 2021-10-28 大约 17 分钟

# 环境部署

# 前言

  1. 项目文档中,已经涵盖了工程搭建详细说明、经常会遇到的问题甚至 JDK 环境变量配置等非常基础性的知识。出现问题请先查看文档并自己尝试解决,确实没有解决思路,再把问题场景描述清楚,在群里交流或者提 ISSUE。

  2. 本项目开源一年多的时间以来,总结下来大多数错误都是没有仔细看文档,操作或配置不当,自身基础设施环境差异导致。其它常见问题也已经写在了文档中,所以通过看文档保证顺利运行整套系统是没有问题的。

  3. 不要一看见错误信息就急忙贴出来,毕竟交流群只是 IM 工具,而不是搜索引擎。错误信息并不是洪水猛兽,只要静下心来,认证看看和琢磨一下,往往答案就在这些错误信息里。否则微服务架构也没有必要搭所谓的日志中心了。

  4. 微服务架构涉及的内容本身就多,很多因素比如修改错误、配置遗漏、动到不该动的地方都会导致系统抛出某个错误,反之只看某个错误想要反推出你具体做过哪些修改是很难的。如果能重现问题当然简单,但是不能重现问题,只能根据你的描述进行反向推测,换句话就是猜,是很难解决问题的。https://gitee.com/dromara/dante-cloud/issues/I513L4 这个是比较经典的一个问题分析,看过之后也许会对你有所启发。因此“一句话、一张图”的提问题方式是不受欢迎的,只会浪费时间,都是搞 IT 的成年人应该都懂。所以遇到问题尽可能的提 ISSUE,编写 ISSUE 过程,本身也是帮助自己回顾、审视和思考这个问题过程。

  5. 不要文档也不看,遇到问题不思考也不尝试,就直接贴出来问。正所谓“纸上得来终觉浅,绝知此事要躬行”,什么问题都指望别人告诉你,这样自己不会有提升可能回头就忘了下次遇到还要问。已经有过例子,遇到问题就问,本系统自己搭建过几次,遇到同样的问题或者之前问过的问题还会拿出来问。这对于问问题的人以及回答问题的人来说都是在浪费时间,大家的时间都很宝贵,干点啥都行就是别拿来浪费。

重申

问题不是不可以问,但是要经过自己的琢磨、尝试和思考,这样不仅自己会有收获,也更利于其他人理解以及与其它人交流。如果你问问题只是想偷懒图省事,那么本项目并不适合你。

# 准备工作

# 后端运行所需的基础设施

设施 当前版本 说明
Nacos 2.1.1 分布式版本使用的 Nacos 作为配置中心和服务发现中心,所以需要安装 Nacos。不管本地运行还是 Docker,K8S 环境都需要。
Redis 3.2.100+ 运行的必须组件,分布式版本,单体版本;本地运行还是还是 Docker,K8S 环境都需要
Kafka 2.6.0+ 运行的必须组件,分布式版本,单体版本;本地运行还是还是 Docker,K8S 环境都需要。(虽然本系统使用的是 spring cloud bus 同时兼容 RabbitMQ 和 Kafka,由于使用 Debezium 来支持工作流,ElasticSearch 数据同步,所以如果没有特殊的使用需求还是建议使用 Kafka)
PostgreSQL 数据库 建议使用最新版,其它版本也可以运行 个人多年项目经验,感觉 PostgreSQL 更好用和顺手,所以默认数据为 PostgreSQL。基础代码都是使用 spring data jpa(Mybatis Plus 也支持),所以其它数据库也支持,修改一下配置就行
MySQL 数据库 5.6.5+ Nacos 运行需要依赖数据库,长久运行需要依赖于 MySQL(目前 Nacos 不支持其它数据库,虽说 Nacos RoadMap 有多数据库支持,不知道什么时候开发完成)。本地运行为了省事,也可以用 Nacos 的内置数据库,这样减少本地运行资源占用
ELK 7.0.0 + 日志中心、Skywalking 监控所需基础环境,本地开发运行可以不需要,需要在配置关闭日志收集
  • (1) 后端本地运行所需标准最小环境
Nacos >= 1.1.0 (推荐使用最新版Nacos)
Redis >= 3.0.0
Kafka >= 2.6.0 (目前Kafka运行还需要依赖Zookeeper)
PostgreSQL >= 10
1
2
3
4
  • (2) 开发环境
IDEA 或 Eclipse (推荐IDEA)
JDK >= 1.8 (系统兼容Java 8,11,17,推荐1.8版本。因 1.8.0_211 之前的版本有较大差异,使用版本建议 > 1.8.0_211,最好直接使用最新版本或 1.8.0_3XX, )
Maven >= 1.3 (推荐使用最新版Nacos)
Git 使用最新版
1
2
3
4
  • (3) 环境配置

参见:本地开发环境搭建

# 前端运行所需的基础设施

设施 当前版本 说明
Nodejs >=12.0.0 运行前端 Vue 工程必须依赖,如果不需要运行前端可以忽略,
Yarn 1.22.19 前端包管理工具,Npm、PNPM 或其它工具也都可以, 推荐使用 Yarn
Vscode 或 WebStorm latest 前端开发 IDE 工具
  • (1) 前端端本地运行所需标准最小环境
Nodejs >= 12.0.0 (12.0.0 是 Vite 支持最低版本,考虑到部分组件的兼容性,建议安装 Nodejs 最新稳定版本)
Yarn >= 1.22.10 (Yarn2 目前会有很多问题,劣势太多不建议使用)
1
2
  • (2) 开发环境
Visual Studio Code (Vscode)或其它 (推荐Vscode)
1
  • (3) 环境配置

参见:本地开发环境搭建

# 后端运行

注意

开展以下各项工作以前,请确保 Git,数据库,Redis,Nacos,Kafka,ELK 套件已经正确安装和运行。

确保相关基础设施组件正确安装和运行的含义,不仅是指相关组件已经可以运行,还包括可以正常连接、访问或操作。例如:Kafka,在软件安装完成之后,可以结合自己的部署方式和部署架构,找一个自己熟悉的可视化工具进行连接测试。连接测试成功之后,再进行后续操作。

微服务架构与单体架构最大的不同点之一就是涉及的基础设施较多,任何一个点出问题都会导致系统运行异常。连通性测试未通过之前,不要急于部署系统。很多朋友就是急于部署,折腾一圈下来发现系统运行不正常,又花费大量的时间和精力排查代码、交流群里面咨询、发 ISSUE,后来发现是某项基础设施组件单独用工具访问都联不通。

如果急于部署只是为了看看界面长个什么样子,尝个鲜。建议直接部署单体版,搭个数据库和 Nodejs 环境即可,省时省力快捷。

说明

如果觉得安装 Nacos,Kafka,ELK 比较麻烦,建议使用容器进行安装,参见章节:容器化部署。数据库和 Redis 还是建议本地安装。

声明:部署是了解本项目和微服务的第一步,建议一定要在系统可以正常运行之后再进行修改。如果你完全可以掌控微服务并且对本项目有所了解,只要遵从 Apache 2.0 开源协议,可以随意修改代码;如果你还不足以掌控微服务并且是初次接触本项目,最好按照文档说明进行操作,不要随意进行修改。在不懂的情况下进行大量修改,搞不定了就以“一句话、一张图”的方式来问问题,这就是在浪费时间。大家都是搞 IT 的成年人应该都懂。

# [1]检出代码创建工程

IDEA 菜单 File -> New -> Project From Version Control..., 在弹出框中输入本工程 Git 地址:https://gitee.com/dromara/dante-cloud.git (opens new window),然后设置放置目录,点击 OK 即可

# [2]创建数据库

进入PostgreSQLSQL Shell(psql) (在 Windows 的菜单中可以找到),使用超级管理员账号和密码登录进入数据库,执行以下脚本:

CREATE USER herodotus WITH PASSWORD 'herodotus';
CREATE DATABASE herodotus OWNER herodotus;
GRANT ALL PRIVILEGES ON DATABASE herodotus TO herodotus;
1
2
3

警告

要分步,一条一条地执行,不要全部复制,一把全部执行。一定要注意每个语句结尾要以“;”结束。

说明

  • 这里不管是用户名,用户密码还是数据库名均使用 herodotus 是为了方便,请根据自己实际情况修改。
  • 这里没有进行分库(即:所有的服务使用同一个数据库),如不满足需求,请在整体部署完成并且可以正常运行后,再结合自己的实际情况修改。
  • 以上是均是以 PostgreSQL 作为默认数据库进行说明。

提示

系统默认使用 PostgreSQL 数据库,如果想要使用其它数据库,建议详细全面阅读本章节,对整体部署过程有了详细了解之后,再来了解如何切换数据库。参阅:更换数据库

提示

Linux 环境下在命令行中,以管理员账号登录 PostgreSQL数据库

# [3]创建或导入 Nacos 配置

提示

在进行以下操作之前,建议对 Nacos 中 Namespace,Group 等基础概念和具体操作先行做一定的了解。【官方文档】 (opens new window)

# 方式一:手动创建 Nacos 配置信息

工程的 ${project_home}/platform/dante-cloud-monitor/resources/configs 目录下,放置着所有需要导入到 Nacos 中的默认配置。开始其它工作之前,需要先在 Nacos 中创建所有配置

  1. 访问 Nacos 后台管理,默认本机地址 (opens new window), 使用默认账号nacos/nacos登录。

  2. Nacos 后台中,在 配置管理 --> 配置列表 功能中,点击添加按钮,手动添加所有配置文件,操作如下图所示:

创建Nacos配置

警告

  • 创建配置之前,请提前规划配置放置的命名空间(Namespace)。默认是放到 Nacos public命名空间中,如果不符合您的需求,可以在新建命名空间之后,再进行配置的创建。
  • ${project_home}/platform/dante-cloud-monitor/resources/configs 目录下,还有一级目录。这级目录的名称,是配置文件对应 Nacos 中的 Group 名称。所以在 Nacos 中新建配置时,一定要注意 Group 的创建和匹配。切勿全部新建到 DEFAULT_GROUP 组下,这样会导致无法正常运行。

提示

本项目所有Nacos配置,均是采用yaml格式。如需使用其它格式请自行修改

# 方式二:批量导入 Nacos 配置

手动方式创建 Nacos 配置,比较繁琐和容易出错。为了使用提升使用的便捷性,在工程 ${project_home}/platform/dante-cloud-monitor/resources/imports 目录下提供可以直接导入的配置包。可以方便的完成导入配置,创建Group等操作。

  1. 访问 Nacos 后台管理,默认本机地址 (opens new window), 使用默认账号nacos/nacos登录。

  2. Nacos 后台中,在 配置管理 --> 配置列表 功能中,点击导入配置按钮,选择配置导入包即可,完成配置文件导入和 Group 的创建,操作如下图所示:

导入Nacos配置

警告

  • 创建配置之前,请提前规划配置放置的命名空间(Namespace)。默认是放到 Nacos public命名空间中,如果不符合您的需求,可以在新建命名空间之后,再进行配置的创建。

# [4]修改 Nacos 配置

上一步所导入的配置参数均是使用默认的、本地化的配置,需要根据自己搭建的基础设施环境,对相关的配置进行修改。

  1. 访问 Nacos 后台管理,默认本机地址 (opens new window), 使用默认账号nacos/nacos登录。

  2. 找到对应的配置文件进行修改。常用的设置在 dante-cloud-environment.yaml 中即可修改完成,如果不满足您实际需求,可再到其它的配置文件中详细修改。

说明

为了方便使用,Dante Cloud 所有的配置采用**“共享式,统一化多环境配置模式”**设计,大多数配置在对应 多环境dante-cloud-environment.yaml 配置中就可以完成修改。例如,您当前使用的是 development 环境,那么在 Nacos 后台管理中,找到 Group 是 developmentdante-cloud-environment.yaml 配置修改。

Dante Cloud 多环境配置设计及使用,参阅:多环境配置

# [5]修改 pom.xml 配置

在工程根目录下,找到 pom.xml, 修改对应 profile 中参数。由于使用的多环境,所以在该文件中,需要找到应环境的配置,修改该环境下的对应的配置信息。主要结构如下所示:

<!-- 开发 -->
<profile>
    <id>development</id>
    <activation>
        <activeByDefault>true</activeByDefault>
    </activation>
    <properties>
        <profile.name>development</profile.name>
        <database.type>postgresql</database.type>
        <skip.build.source.package>false</skip.build.source.package>
        <skip.copy.docker.resource>false</skip.copy.docker.resource>
        <skip.build.git.commit.info>false</skip.build.git.commit.info>
        <config.server-addr>127.0.0.1:8848</config.server-addr>
        <config.namespace></config.namespace>
        <discovery.server-addr>127.0.0.1:8848</discovery.server-addr>
        <sentinel.server-addr>127.0.0.1:8858</sentinel.server-addr>
    </properties>
</profile>
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

必须要修改的参数涉及以下几项:

  • config.server-addr:配置中心地址,即 Nacos 服务端地址
  • config.namespace:Nacos 命名空间 ID。如果要使用的是默认的命名空间,该参数不设置任何值。
  • discovery.server-addr:服务发现地址,即 Nacos 服务端地址
  • sentinel.server-addr:Sentinel Dashborad 地址

详细参数说明,参阅:多环境配置

# [6]编译代码

# 编译方式一

用命令行进入到工程代码所在根据目录,通过执行下面命令进行编译

mvn install

或

mvn package
1
2
3
4
5

提示

推荐使用install命令,进行编译。使用该命令编译完成之后,会在Maven本地缓存中,生成响应的包,这样dante-cloud-athena功能就可以直接使用。

警告

在第一次编译的时候,因为在本地缓存缺少相关的包,所以在执行 mvn clean 操作时会提示错误。因此,在第一次编译时只使用 mvn packagemvn install。第一次编译完成之后,就可以使用 mvn clean packagemvn clean install 命令进行编译。IDE 界面操作也是同理。

# 编译方式二

在 IDE 工程中,利用 IDE 提供的界面操作进行编译。

IDEA为例,在右侧Maven Panel中,选择dante-cloud(root)节点,点击 Lifecycle 节点下的install 或者 package 进行编译。参考下图:

输入图片说明

# [7]数据初始化

具体操作方法,参阅:数据初始化

# [8]运行服务模块

说明

各个服务的启动顺序并没有严格的要求,启动的先后顺序并不影响实际的使用,但是部分核心代码逻辑以及组件存在“时机性”问题,启动顺序的不同会略有时机差异性。

如果您对时机性没有要求,那么请忽略启动顺序问题,随意启动。

如果您对时机性有较高要求,那么请详细阅读各个服务对应的备注说明。

  1. UpmsApplication (用户中心服务 必需)
  2. UaaApplication (统一认证服务 必需)
  3. GatewayApplication (服务网关服务 必需)
  4. MonitorApplication (监控中心服务 可选)
  5. BpmnApplication (分布式工作流 可选)

# [9]运行 ELK(可选)

完整运行本套微服务架构,需要搭建 ELK 套件,作为日志中心以及 Skywalking 链路追踪的数据存储介质。

目前已有基础功能尚未涉及到搜索,只有日志中心和链路追踪功能涉及到 Elasticsearch。如果本地开发不要相关功能,就不需要安装和运行ELK套件。

如果已经安装了可运行的 ELK 套件,或者其它组合,请略过该步骤。如果觉得单独安装麻烦,建议以 Docker 的方式安装运行,本系统提供了 docker-compose 安装脚本,参见章节:容器化部署

提示

如果本地不想使用 ELK,那么需要关闭微服务的日志收集功能。

修改你所使用 多环境 对应的 dante-cloud-environment.yaml 配置中的 herodotus.environment.logstash-server-addr 属性的值,将其值设置成 false ,即可关闭日志收集功能,就解除服务对 ELK 的依赖

# [10]运行 Skywalking(可选)

完整运行本套微服务架构,需要搭建 ELK 套件,作为日志中心以及Skywalking链路追踪的数据存储介质。正式环境运行建议使用 DockerK8S 的方式运行 Skywalking,并以 Docker 的形式运行服务。

如果已经安装了可运行的 ELK 套件,或者其它组合,请略过该步骤。如果觉得单独安装麻烦,建议以 Docker 的方式安装运行,本系统提供了 docker-compose 安装脚本,参见章节:容器化部署

如果仅是在本地运行调试服务与 Skywalking 的联动,可以在 IDE 中增加参数后,再运行服务即可。

以 IDEA 为例,点开 Edit Configurations...,在对应服务的 VM Options 输入框中添加如下参数即可调试 Skywalking

-javaagent:D:/Workspaces/Java/herodotus-cloud/configurations/docker/context/agent/skywalking-agent-es7-8.6.0.jar=agent.service_name=herodotus-cloud-upms-ability,collector.backend_service=192.168.101.10:11800
1

操作界面如下图所示,IDEA 版本不同配置方式会有差异

输入图片说明

# [11]以 Docker 方式部署(可选)

参见:容器化部署

# [12]运行验证

以上步骤完成之后,工程后端整体搭建部署完成。可以通过运行前端界面进行操作或者用 Postman 调用接口的方式进行验证。

如果界面操作正常,或者接口调用正常,则说明工程已经正确部署。更多验证,参阅:OAuth2 授权标准

# 前端运行

# [1]检出代码

在合适位置上,使用 Git 检出前端工程代码。项目地址 (opens new window)

# [2]修改配置

在前端工程根目录下,找到 .env.development 或者 .env.production 文件。修改其中的参数

参数说明

  • NODE_ENV:当前多环境名称,不用修改
  • VITE_PROJECT:工程名称,名称。通过该参数以动态修改域名以外的地址,以实现单体版等使用同一套操作界面。dante指定是微服务版,其它任意字符串或者空值指定是单体版
  • VITE_PROJECT_NAME:界面显示的系统名称
  • VITE_API_URL:后端服务网关访问地址
  • VITE_SECRET_KEY:前端关键信息 AES 加密秘钥
  • VITE_AUTO_REFRESH_TOKEN:开启自动刷新 Token 机制
  • VITE_MULTI_TENANCY_ID:当前应用租户 ID,需要后台进行租户配置,空值为不启用租户模式。
  • VITE_USE_CRYPTO:是否开启前后端数据加密
  • VITE_OAUTH_CLIENT_ID:OAuth2 密码模式 Client Id。
  • VITE_OAUTH_CLIENT_SECRET:OAuth2 密码模式 Client 密码
  • VITE_OAUTH_GRANT_TYPE:OAuth2 授权模式

注意

VITE_SECRET_KEY 秘钥,并不是本系统前后端数据加密传输使用的秘钥,只是对前端临时存储的关键信息加密的秘钥。

本系统前后端数据加密传输,是基于自主设计的自定义数据传输 Session,实现国密 SM4 加密秘钥的动态生成,加密传输,一人一钥机制。每次使用系统都会动态重新生成,采用 SM2 前后端加密传输,临时存储至前端。缓存时间与 OAuth 2 Token 设置时间相同,正常退出系统后,会清除前端临时存储数据。

并没有绝对安全的加密措施,前后端数据加密传输也仅仅是相对提升安全性。毕竟不管如何处理,前端都要存储一定的关键信息,而且前端是最容易破解的。正式环境使用还是要配合 Https 以及其它安全防护措施。

# [3]前端运行命令

// 进入目录
cd dante-cloud-ui

// 安装依赖
yarn install

// 如果要使用 `.env.development` 中的配置值,使用下面命令
yarn dev

// 如果要使用 `.env.production` 中的配置值,使用下面命令

yarn prod

1
2
3
4
5
6
7
8
9
10
11
12
13

# [4]运行验证

打开浏览器,输入:http://localhost:3000 (opens new window) 默认账户/密码 system/123456

若能正确展示登录页面,并能成功登录,菜单及页面展示正常,则表明环境搭建成功

上次编辑于: 2022年9月23日 11:17
贡献者: 码匠君 , herodotus