安装指南

本文档提供 HEI Cloud 的详细安装和初始化步骤。

1. 环境准备

1.1 JDK 21 安装

HEI Cloud 使用 Java 21 编译和运行，请确保已安装 JDK 21 或更高版本。

java -version
# 输出应包含 "21" 或更高版本

1.2 Maven 安装

mvn -version
# 输出 Apache Maven 3.6.0 或更高版本

1.3 MySQL 安装

推荐使用 MySQL 8.0+，确保支持 utf8mb4 字符集。

1.4 Redis 安装

推荐使用 Redis 6.0+，需要支持独立的数据库索引。

2. 获取源码

从 Gitee 克隆

git clone https://gitee.com/jiangbyte/hei-cloud.git
cd hei-cloud

从 GitHub 克隆

git clone https://github.com/jiangbyte/hei-cloud.git
cd hei-cloud

3. 数据库初始化

3.1 创建数据库

CREATE DATABASE IF NOT EXISTS hei_data DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;

3.2 执行 SQL 脚本

进入 scripts/sqls/ 目录，执行所有 SQL 脚本：

mysql -u root -p hei_data < scripts/sqls/260603.sql

或使用 MySQL 客户端逐条执行。

4. 修改配置文件

4.1 配置文件结构

项目使用多环境配置文件：

文件	说明	用途
application.yaml	基础配置	框架级别配置，一般不频繁修改
application-local.yaml	本地环境	本地开发环境配置
application-dev.yaml	开发环境	开发团队共享环境

默认激活的环境为 local，通过 application.yaml 中的 spring.profiles.active 控制。

4.2 修改数据库配置

编辑配置文件：

spring:
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://localhost:3306/hei_data?useUnicode=true&characterEncoding=utf-8&useSSL=false&allowMultiQueries=true&allowPublicKeyRetrieval=true&zeroDateTimeBehavior=convertToNull&transformedBitIsBoolean=true&tinyInt1isBit=false
    username: root
    password: 你的数据库密码

4.3 修改 Redis 配置

spring:
  data:
    redis:
      database: 1
      host: localhost
      port: 6379
      password: 你的Redis密码
      timeout: 10s

4.4 修改 SM2 密钥

生产环境请务必更换默认的 SM2 密钥。

什么是 SM2 国密算法

SM2 是中国国家密码管理局发布的椭圆曲线公钥密码算法，属于国家商用密码算法标准。HEI Cloud 使用 SM2 实现登录密码的加密传输：

• 前端: 使用公钥加密密码，确保密码在传输过程中不被窃取
• 后端: 使用私钥解密密码，再通过 BCrypt 验证密码正确性

SM2 加密模式

项目采用 C1C3C2 模式（Cipher Mode = 1），这是国密标准推荐的加密模式：

模式	说明
C1C2C3	旧标准模式，部分老系统使用
C1C3C2	新国标模式，本项目采用

前后端必须使用相同的加密模式，否则解密会失败。

生成 SM2 密钥对

项目提供了密钥生成工具，运行以下命令生成新的密钥对：

cd common/core
mvn exec:java -Dexec.mainClass="io.github.jiangbyte.utils.Sm2CryptoUtil"

或在 IDE 中直接运行 Sm2CryptoUtil.main() 方法。

输出示例：

╔══════════════════════════════════════════════════════════════╗
║              SM2 Key Pair Generation Complete                ║
╚══════════════════════════════════════════════════════════════╝

Private Key (keep secure):
  ba223fdf82c28193d3edae062005c50a7289311b0a7a3fc4647e9643026ee353

Public Key (share with frontend):
  04e53eb03a57dabe64549096bc2d8f7a7e9d0eab24df21641b5bd0ec7674d2c774...

════════════════════════════════════════════════════════════════
Backend Configuration (application.yml):
════════════════════════════════════════════════════════════════
auth:
  sm2:
    private-key: ba223fdf82c28193d3edae062005c50a7289311b0a7a3fc4647e9643026ee353
    public-key: 04e53eb03a57dabe64549096bc2d8f7a7e9d0eab24df21641b5bd0ec7674d2c774...

配置密钥

将生成的密钥配置到配置文件：

auth:
  sm2:
    private-key: 你的SM2私钥
    public-key: 你的SM2公钥

前端配置

前端需要配置相同的公钥，用于加密密码：

VITE_SM2_PUBLIC_KEY=你的SM2公钥

前端加密工具

项目提供了前端加密脚本 scripts/sm2-encrypt.js，可用于测试：

# 安装依赖
npm install sm-crypto

# 加密密码
echo "your_password" | node scripts/sm2-encrypt.js

安全注意事项

1. 私钥保密: 私钥只能存在于后端配置中，绝不能提交到版本控制
2. 公钥可公开: 公钥可以安全地分享给前端
3. 密钥匹配: 前后端必须使用同一对密钥，否则解密会失败
4. 生产环境: 生产环境务必更换默认密钥

5. 编译项目

mvn clean install -DskipTests

6. 启动项目

方式一：Maven 启动

mvn spring-boot:run

方式二：IDE 启动

直接运行启动类的 main 方法。

方式三：打包后启动

mvn clean package -DskipTests
java -jar target/*.jar

7. 验证安装

启动成功后，访问以下地址：

服务	地址	说明
后端服务	http://localhost:8081	健康检查
API 文档	http://localhost:8081/doc.html	Knife4j 接口文档
Druid 监控	http://localhost:8081/druid/	数据库监控（账号: admin/123456）

8. 常见问题

端口占用

如果 8081 端口被占用，在 application.yaml 中修改：

server:
  port: 自定义端口

多环境切换

修改 application.yaml 中的 spring.profiles.active 值：

spring:
  profiles:
    active: dev  # 可选：local / dev / test / prod