环境部署

码匠君2023/5/17大约 18 分钟SASSpring Authorization ServerDante Cloud微服务领域驱动DDDSpring BootSpring CloudSpring SecuritySpring Cloud AlibabaSpring Cloud TencentOAuth2.1NacosSkywalkingSentinelSeata

声明

部署是了解本项目和微服务的第一步，建议第一次部署一定严格按照文档描述进行操作，保证系统可以正常运行之后，并且对现有内容有了一定认识之后，在按照自己的进行修改或变更。

提示

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

序号	设施	说明
1	Nacos	分布式版本使用的 Nacos 作为配置中心和服务发现中心，所以需要安装 Nacos。不管本地运行还是 Docker，K8S 环境都需要。
2	Redis	运行的必须组件，分布式版本，单体版本；本地运行还是还是 Docker，K8S 环境都需。
3	Kafka	运行的必须组件，分布式版本，单体版本；本地运行还是还是 Docker，K8S 环境都需要。（虽然本系统使用的是 spring cloud bus 同时兼容 RabbitMQ 和 Kafka，由于使用 Debezium 来支持工作流，ElasticSearch 数据同步，所以如果没有特殊的使用需求还是建议使用 Kafka）。
4	PostgreSQL 数据库	建议使用最新版，其它版本也可以运行个人多年项目经验，感觉 PostgreSQL 更好用和顺手，所以默认数据为 PostgreSQL。基础代码都是使用 spring data jpa（Mybatis Plus 也支持），所以其它数据库也支持，修改一下配置就行。
5	MySQL 数据库	Nacos 运行需要依赖数据库，长久运行需要依赖于 MySQL（目前 Nacos 不支持其它数据库，虽说 Nacos RoadMap 有多数据库支持，不知道什么时候开发完成）。本地运行为了省事，也可以用 Nacos 的内置数据库，这样减少本地运行资源占用。

设施	当前版本	说明
Nodejs	>=12.0.0	运行前端 Vue 工程必须依赖，如果不需要运行前端可以忽略，
Pnpm	latest	前端包管理工具，Npm、PNPM 或其它工具也都可以，推荐使用 Yarn

[二]后端运行

警告

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

确保相关基础设施组件正确安装和运行的含义：不仅是指相关组件已经可以运行，还包括可以正常连接、访问或操作。

例如：Kafka，在软件安装完成之后，可以结合自己的部署方式和部署架构，找一个自己熟悉的可视化工具进行连接测试。连接测试成功之后，再进行后续操作。

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

提示

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

[1]检出代码创建工程

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

提示

不建议直接从 Gitee 或 Github 上，以 下载 ZIP 的方式获取代码。因为代码中集成了 git 信息打包工具，依赖于工程中的 .git 目录，用于查看 git 版本信息，相关信息也可在 Spring Boot Admin 中查看。直接以 ZIP 方式下载代码，可能会因找不到 .git 目录而导致编译出错。

[2]创建数据库

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


// 以下要分步，一条一条地执行，不要全部复制，一把全部执行。一定要注意每个语句结尾要以“;”结束。
CREATE USER herodotus WITH PASSWORD 'herodotus';
CREATE DATABASE herodotus OWNER herodotus;
GRANT ALL PRIVILEGES ON DATABASE herodotus TO herodotus;

说明

这里不管是用户名，用户密码还是数据库名均使用 herodotus 是为了方便，请根据自己实际情况修改。
这里没有进行分库（即：所有的服务使用同一个数据库），如不满足需求，请在整体部署完成并且可以正常运行后，再结合自己的实际情况修改。
以上是均是以 PostgreSQL 作为默认数据库进行说明。
Linux 环境下在命令行中，以管理员账号登录 PostgreSQL数据库

提示

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

[3]创建或导入 Nacos 配置

提示

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

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

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

访问 Nacos 后台管理，默认本机地址，使用默认账号nacos/nacos登录。
在 Nacos 后台中，在 配置管理 --> 配置列表 功能中，点击添加按钮，手动添加所有配置文件，操作如下图所示：

注意

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

提示

本项目所有Nacos配置，均是采用yaml格式。如需使用其它格式请自行修改
Dante Cloud 3.X 版本下，相关配置移动到 ${project_home}/configurations/backup/alibaba 目录下

方式二：批量导入 Nacos 配置

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

访问 Nacos 后台管理，默认本机地址，使用默认账号nacos/nacos登录。
在 Nacos 后台中，在 配置管理 --> 配置列表 功能中，点击导入配置按钮，选择配置导入包即可，完成配置文件导入和 Group 的创建，操作如下图所示：

注意

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

提示

Dante Cloud 3.X 版本下，相关配置移动到 ${project_home}/configurations/backup/alibaba 目录下

[4]修改 Nacos 配置

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

访问 Nacos 后台管理，默认本机地址，使用默认账号nacos/nacos登录。
找到对应的配置文件进行修改。常用的设置在 dante-cloud-environment.yaml 中即可修改完成，如果不满足您实际需求，可再到其它的配置文件中详细修改。

说明

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

Dante Cloud 多环境配置设计及使用，参阅：多环境配置

[5]修改 pom.xml 配置

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

<!-- 开发 -->
<profile>
    <id>development</id>
    <activation>
        <!--默认激活配置-->
        <activeByDefault>true</activeByDefault>
    </activation>
    <properties>
        <!--当前环境-->
        <profile>development</profile>
        <database>postgresql</database>
        <!--基础设施：tencent、alibaba、spring-->
        <facility>alibaba</facility>
        <!--代码构建控制-->
        <!--跳过构建源代码包-->
        <skip.build.source.package>false</skip.build.source.package>
        <!--不copy代码包到docker构建目录-->
        <skip.copy.docker.resource>false</skip.copy.docker.resource>
        <!--不执行git commit 构建-->
        <skip.build.git.commit.info>false</skip.build.git.commit.info>
        <!--Spring Cloud Alibaba配置中心命名空间，用于支持多环境.这里必须使用ID，不能使用名称，默认为空-->
        <alibaba.namespace>2e4f5cf6-2ac8-4fe0-99be-b0562659c120</alibaba.namespace>
        <!--Spring Cloud Alibaba配置中心地址-->
        <alibaba.config.server-addr>192.168.101.10:8848</alibaba.config.server-addr>
        <!--Spring Cloud Alibaba服务发现地址-->
        <alibaba.discovery.server-addr>192.168.101.10:8848</alibaba.discovery.server-addr>
        <alibaba.sentinel.server-addr>192.168.101.10:8858</alibaba.sentinel.server-addr>
        <tencent.polaris.namespace>default</tencent.polaris.namespace>
        <!--Spring Cloud Tencent 配置 【(8091)grpc/tcp，默认注册中心端口;(8090)http/tcp，默认注册中心端口】-->
        <tencent.polaris.server-addr>192.168.101.10:8091</tencent.polaris.server-addr>
        <!--Spring Cloud Tencent Config 配置 【(8093)grpc/tcp，默认配置中心端口】-->
        <tencent.polaris.config-addr>192.168.101.10:8093</tencent.polaris.config-addr>
        <!--Spring Cloud Tencent 本地缓存目录-->
        <tencent.polaris.local.dir>./configurations/configs/tencent/backup/config</tencent.polaris.local.dir>
    </properties>

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

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

详细参数说明，参阅：多环境配置

[6]编译代码

编译方式一

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

mvn install

或

mvn package

提示

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

警告

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

编译方式二

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

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

[7]运行服务模块和创建数据表

核心服务

UpmsApplication （用户中心服务必需）
UaaApplication （统一认证服务必需）
MessageApplication （平台消息服务必需）
OssAbilityApplication （对象存储服务必需）
GatewayApplication （服务网关服务必需）

因 UpmsApplication 服务中包含权限数据汇总和分发机制，所以 UpmsApplication 服务要最先启动。UaaApplication、MessageApplication 和 OssAbilityApplication 服务启动顺序没有硬性要求。GatewayApplication 启动顺序没有硬性要求，建议可以放在最后启动

其它服务

MonitorApplication （监控中心服务可选）
BpmnAbilityApplication （分布式工作流可选）

建议 MonitorApplication 服务在所有服务启动之后，再行启动。

说明

如果之前的配置没问题，同时 UpmsApplication、UaaApplication、MessageApplication、OssAbilityApplication 三个服务均可以正常启动，那么各个服务中涉及的数据表也会自动创建。

同时，在这个过程中各个服务会扫描自身所有的 REST 接口，将其汇总至 sys_interface 表中。

注意

如果你使用的是 MySQL 数据库，可能存在因 JPA (Hibernate) 适配不同数据库的 Dialect 实现差异，会出现抛出错误信息等问题。一般情况下这不会影响系统运行和部署，而且这个问题也不是作者有能力修改的。所以如果在启动过程中，出现 MySQL 相关错误，不要急着说是系统问题，请查阅本文档相关部分的内容或自行百度进行一定了解。详情参阅：数据初始化

[8]数据库初始化

具体操作方法，参阅：数据初始化

[9]重置缓存

有过项目开发经验，特别是有过数据库数据缓存使用经验的朋友肯定都知道：如果系统中使用了数据库数据缓存，那么直接手动修改数据库的数据，就会导致数据库数据和缓存数据的不一致，而出现系统界面操作或显示，与预期不一致的情况。想要解决这类问题，要么在有条件的情况下清除缓存让缓存再重新生成，要么就只能等待相关查询产生的缓存过期后再次出发查询操作重新生成。

说明缓存这个问题的原因是，本系统中默认也启动了缓存，而且是多级缓存（Caffeine 本地 + Redis 远程）。这就导致一定会出现上面所说的问题，特别是在第一次搭建本系统时，如果某个步骤顺序错误，比如：数据库没有进行初始化，就运行前端界面进行操作，那么就会产生错误的缓存（JPA (Hibernate) 是基于 SQL 语句进行数据缓存的）

警告

所以为了规避因缓存原因而产生让人莫名奇妙的问题，在以上步骤均完成之后（数据库初始化完成之后），一定要按照以下步骤进行缓存重置

停止所有服务
清空 Redis 缓存数据
再次运行所有服务

[10]运行 ELK（可选）

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

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

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

提示

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

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

[11]运行 Skywalking（可选）

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

如果仅是在本地运行调试服务与 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，collector.backend_service=192.168.101.10:11800

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

[12]以 Docker 方式部署（可选）

参见：容器化部署

[13]运行验证

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

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

[三]前端运行

[1]检出代码

在合适位置上，使用 Git 检出前端工程代码。项目地址

[2]修改配置

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

参数说明

NODE_ENV：当前多环境名称，不用修改
VITE_PROJECT：工程名称，名称。通过该参数以动态修改域名以外的地址，以实现单体版等使用同一套操作界面。dante指定是微服务版，其它任意字符串或者空值指定是单体版
VITE_PROJECT_NAME：界面显示的系统名称
VITE_API_URL：后端服务网关访问地址
VITE_WS_URL：后端服务 WebSocket 访问地址
VITE_SECRET_KEY：前端关键信息 SM4 加密秘钥
VITE_AUTO_REFRESH_TOKEN：开启自动刷新 Token 机制
VITE_MULTI_TENANCY_ID：当前应用租户 ID，需要后台进行租户配置，空值为不启用租户模式。
VITE_USE_CRYPTO：是否开启前后端数据加密
VITE_USE_WEBSOCKET：是否开启 WebSocket
VITE_USE_OIDC：是否使用 OpenID Connect（OIDC）协议
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

// 安装依赖
pnpm install

// 可以自己编译一下组件库
pnpm shared:build

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

// 如果要使用 `.env.production` 中的配置值，编译整个项目，则使用下面命令。一般只有在前端进行正式部署时才会用到这个命令
pnpm prod

[4]运行验证

打开浏览器，输入：http://localhost:3000

提示

系统登录默认的账户和密码是：system/123456

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

重申

不要再到交流群里面问系统登录默认的用户名和密码了、不要再口口声声说在文档里 “确实找不到” 用户名和密码！！！

如果连看文档的耐心都没有，个人认为就不合适搞 IT。说找不到用户名密码的，至少是文档不仔细看或懒得看。
不管是因为懒惰、想快还是什么其它原因，觉得文档不值得看，这都是个人的选择，本就无可厚非。但是自己不看，非要去群里问，让别人告诉你，这就是在浪费别人的善意和时间，就是不厚道，也别怪群里没人愿意回复。

贡献者

码匠君