安装指南

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

1. 环境准备

1.1 Python 安装

HEI FastAPI 使用 Python 3.13+ 编译和运行，请确保已安装 Python 3.13 或更高版本。

python --version
# 输出应包含 "3.13" 或更高版本

1.2 MySQL 安装

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

1.3 Redis 安装

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

2. 获取源码

从 Gitee 克隆

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

从 GitHub 克隆

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

3. 创建虚拟环境

Linux/Mac

python -m venv venv
source venv/bin/activate

Windows

python -m venv venv
venv\Scripts\activate

4. 安装依赖

pip install -r requirements.txt

5. 数据库初始化

5.1 创建数据库

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

5.2 执行 SQL 脚本

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

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

6. 修改配置文件

6.1 配置文件

项目使用项目根目录的 .env 文件进行配置，通过 pydantic-settings 读取：

# 应用配置
APP__NAME=hei-fastapi
APP__PORT=8081

# 数据库配置
DB__HOST=localhost
DB__PORT=3306
DB__USER=root
DB__PASSWORD=123456
DB__DATABASE=hei_data

# Redis 配置
REDIS__HOST=localhost
REDIS__PORT=6379
REDIS__PASSWORD=123456

# JWT 配置
JWT__SECRET_KEY=your-jwt-secret-key

# SM2 配置
SM2__PRIVATE_KEY=your-sm2-private-key
SM2__PUBLIC_KEY=your-sm2-public-key

6.2 什么是 SM2 国密算法

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

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

SM2 加密模式

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

生成 SM2 密钥对

运行以下 Python 代码生成新的密钥对：

from core.utils import sm2_crypto_util as sm2

# 生成密钥对
private_key, public_key = sm2.gen_keypair()

print(f"Private Key: {private_key}")
print(f"Public Key: {public_key}")

安全注意事项

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

7. 启动项目

方式一：直接启动

python main.py

方式二：Uvicorn 启动

uvicorn main:app --host 0.0.0.0 --port 8081 --reload

方式三：生产环境启动

uvicorn main:app --host 0.0.0.0 --port 8081 --workers 4

8. 验证安装

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

服务	地址	说明
后端服务	http://localhost:8081	健康检查 + API 文档
API 文档	http://localhost:8081/docs	Swagger UI
ReDoc	http://localhost:8081/redoc	ReDoc 文档

9. 常见问题

端口占用

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

APP__PORT=自定义端口

依赖安装失败

使用国内镜像源：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

数据库连接失败

检查 MySQL 服务是否启动，以及用户名密码是否正确。