配置说明

本文档详细说明 HEI FastAPI 的配置文件结构和各项配置参数。

配置文件结构

HEI FastAPI 使用 .env 文件进行配置，通过 pydantic-settings 读取环境变量。

文件	说明	用途
.env	实际配置	项目根目录，不提交到版本控制

配置项说明

应用配置（APP）

APP__NAME=hei-fastapi           # 应用名称
APP__VERSION=1.0.0              # 应用版本
APP__DEBUG=true                 # 调试模式
APP__HOST=0.0.0.0               # 监听地址
APP__PORT=8081                  # 服务端口
APP__UPLOAD_MAX_SIZE=52428800   # 上传最大字节数 (50MB)
APP__IMPORT_MAX_FILE_SIZE_MB=10 # Excel 导入最大文件大小 (MB)
APP__TIMEOUT_KEEP_ALIVE=15      # Keep-Alive 超时 (秒)

数据库配置（DB）

DB__HOST=localhost              # 数据库地址
DB__PORT=3306                   # 数据库端口
DB__USER=root                   # 数据库用户名
DB__PASSWORD=123456             # 数据库密码
DB__DATABASE=hei_data           # 数据库名称
DB__POOL_SIZE=20                # 连接池大小
DB__MAX_OVERFLOW=10             # 最大溢出连接数
DB__POOL_RECYCLE=3600           # 连接回收时间（秒）
DB__POOL_PRE_PING=true          # 连接前 ping 检测
DB__POOL_TIMEOUT=30             # 等待连接超时（秒）
DB__CONNECT_TIMEOUT=10          # 连接超时（秒）
DB__ECHO=false                  # 是否打印 SQL

软删除配置

DB__SOFT_DELETE_ENABLED=true            # 启用软删除
DB__SOFT_DELETE_FIELD=is_deleted        # 软删除字段名
DB__SOFT_DELETE_VALUE_NOT_DELETED=NO    # 未删除标识值
DB__SOFT_DELETE_VALUE_DELETED=YES       # 已删除标识值

软删除全局默认启用。BaseDAO 在查询时自动过滤 is_deleted = 'NO' 的记录，删除时执行软标记（UPDATE）而非物理删除（DELETE）。每个模型通过 is_deleted 字段参与此机制。

Redis 配置（REDIS）

REDIS__HOST=localhost                  # Redis 地址
REDIS__PORT=6379                       # Redis 端口
REDIS__PASSWORD=123456                 # Redis 密码
REDIS__DATABASE=1                      # Redis 数据库索引
REDIS__MAX_CONNECTIONS=200             # 最大连接数
REDIS__SOCKET_CONNECT_TIMEOUT=10       # Socket 连接超时
REDIS__SOCKET_TIMEOUT=30              # Socket 读写超时
REDIS__RETRY_ON_TIMEOUT=true           # 超时自动重试
REDIS__HEALTH_CHECK_INTERVAL=30        # 健康检查间隔（秒）

JWT 配置（JWT）

JWT__SECRET_KEY=your-secret-key         # JWT 密钥（生产环境务必更换）
JWT__ALGORITHM=HS256                    # 加密算法
JWT__EXPIRE_SECONDS=2592000             # Token 有效期，2592000 = 30 天
JWT__TOKEN_NAME=Authorization           # Token Header 名称

JWT Token 签发后同时写入 Redis，实现服务端主动失效（登出）能力。

SM2 国密配置（SM2）

SM2__PRIVATE_KEY=你的SM2私钥            # SM2 私钥（用于解密和签名）
SM2__PUBLIC_KEY=你的SM2公钥             # SM2 公钥（用于加密和验签）

采用 C1C3C2 模式加密，用于登录密码的前端加密传输和后端解密。

CORS 配置（CORS）

CORS__ALLOW_ORIGINS=["*"]              # 允许的域名
CORS__ALLOW_METHODS=["*"]              # 允许的 HTTP 方法
CORS__ALLOW_HEADERS=["*"]              # 允许的请求头
CORS__ALLOW_CREDENTIALS=false          # 是否允许携带凭证

Snowflake 配置（SNOWFLAKE）

SNOWFLAKE__INSTANCE=1                  # 雪花算法实例 ID（分布式部署时不同实例使用不同 ID）

配置加载机制

项目使用 pydantic-settings 的 BaseSettings 读取配置：

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        env_nested_delimiter="__",
        extra="ignore"
    )

    app: AppConfig = AppConfig()
    db: DatabaseConfig = DatabaseConfig()
    redis: RedisConfig = RedisConfig()
    jwt: JWTConfig = JWTConfig()
    sm2: SM2Config = SM2Config()
    cors: CORSConfig = CORSConfig()
    snowflake: SnowflakeConfig = SnowflakeConfig()

配置分隔符

使用 __ 作为嵌套分隔符：

• APP__NAME → settings.app.name
• DB__HOST → settings.db.host
• REDIS__DATABASE → settings.redis.database

配置优先级

配置加载优先级如下（高 → 低）：

1. 系统环境变量（最高优先级）
2. .env 文件
3. 代码中的默认值

使用配置

from config.settings import settings

# 获取应用名称
app_name = settings.app.name

# 获取数据库连接 URL
db_url = settings.db.url

# 获取 Redis 连接 URL
redis_url = settings.redis.url

# 获取 JWT 配置
jwt_secret = settings.jwt.secret_key
jwt_expire = settings.jwt.expire_seconds

生产环境配置建议

1. 更换 JWT 密钥: 使用强随机字符串
2. 更换 SM2 密钥: 生成新的密钥对（运行 core.utils.sm2_crypto_util.gen_keypair()）
3. 使用环境变量: 敏感配置通过系统环境变量传入，不写入文件
4. 关闭调试: 设置 APP__DEBUG=false
5. 调整连接池: 根据并发量调整 DB__POOL_SIZE 和 REDIS__MAX_CONNECTIONS