Table of Contents
18.12 服务端与后台参数配置
服务端 .env 示例：
# 至少32字节，仅存在于服务端环境；用于派生版本密钥封装主密钥
API_ENCRYPTION_MASTER_KEY=replace-with-a-high-entropy-server-secret
# Session 7天、请求时间容差5分钟、版本策略缓存5分钟
API_ENCRYPTION_SESSION_TTL=604800
API_ENCRYPTION_TIMESTAMP_TOLERANCE=300
API_ENCRYPTION_POLICY_CACHE_TTL=300
# H5 先兼容发布，验证完成后改为 true
API_ENCRYPTION_H5_ENABLED=false
API_ENCRYPTION_H5_KEY=0123456789abcdef0123456789abcdef
配置值按 UTF-8 原始字节计算，不会自动执行 Base64 解码。版本握手密钥和 API_ENCRYPTION_H5_KEY 必须恰好 32 字节；API_ENCRYPTION_MASTER_KEY 至少 32 字节，并由服务端 SHA-256 派生为固定 32 字节封装密钥。生产环境应使用密码学安全随机 ASCII 字符，以上可读密钥仅用于本地联调。
APP 后台版本字段：
| 字段 | 说明 |
|---|---|
api_encryption_enabled |
0 兼容明文和密文；1 强制密文 |
api_encryption_key |
当前渠道、平台、构建号专用的 32 字节握手密钥 |
api_encryption_key_configured |
只读布尔值，仅表示是否已经配置，不返回密钥 |
开启强制加密前必须配置有效密钥。编辑时密钥留空表示保留原值；已配置密钥的正式版或已下线版本禁止替换，轮换密钥必须创建新版本。数据库保存的是由主密钥封装后的密文，后台列表、详情和日志均不得返回明文。
浏览器端构建配置中的 H5 Key 必须与服务端 API_ENCRYPTION_H5_KEY 完全一致。H5 Key 最终可被浏览器用户读取，只是统一协议和提高普通抓包、脚本调用门槛，不能作为可靠客户端身份证明。