# 环境配置

<cite>
**本文引用的文件**
- [backend/src/config/env.js](file://backend/src/config/env.js)
- [backend/src/config/loadEnv.js](file://backend/src/config/loadEnv.js)
- [backend/src/config/database.js](file://backend/src/config/database.js)
- [backend/src/config/redis.js](file://backend/src/config/redis.js)
- [backend/src/utils/jwt.js](file://backend/src/utils/jwt.js)
- [backend/src/services/otaStorage.js](file://backend/src/services/otaStorage.js)
- [backend/src/services/eqCacheStorage.js](file://backend/src/services/eqCacheStorage.js)
- [backend/src/config/logger.js](file://backend/src/config/logger.js)
- [backend/src/app.js](file://backend/src/app.js)
- [backend/package.json](file://backend/package.json)
- [docker-compose.yml](file://docker-compose.yml)
- [DEPLOY.md](file://DEPLOY.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件系统性梳理后端服务的环境配置，覆盖数据库连接、JWT 认证、Redis 缓存、S3 存储等关键模块，并给出开发、测试、生产三类环境的配置差异建议、安全存储与版本控制策略、配置验证方法、常见错误与修复方案，以及配置模板与示例文件说明。

## 项目结构
后端通过入口文件统一加载环境变量与初始化各子系统；配置层按功能拆分，便于独立维护与替换。

```mermaid
graph TB
A["入口应用<br/>backend/src/app.js"] --> B["加载环境变量<br/>backend/src/config/loadEnv.js"]
A --> C["数据库配置<br/>backend/src/config/database.js"]
A --> D["JWT 工具<br/>backend/src/utils/jwt.js"]
A --> E["Redis 客户端<br/>backend/src/config/redis.js"]
A --> F["OTA 存储S3/本地<br/>backend/src/services/otaStorage.js"]
A --> G["EQ 缓存读写<br/>backend/src/services/eqCacheStorage.js"]
A --> H["日志配置<br/>backend/src/config/logger.js"]
A --> I["环境判断<br/>backend/src/config/env.js"]
J["Docker Compose<br/>docker-compose.yml"] --> A
K["部署文档<br/>DEPLOY.md"] --> A
```

图示来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/src/services/eqCacheStorage.js:1-73](file://backend/src/services/eqCacheStorage.js#L1-L73)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [DEPLOY.md:190-204](file://DEPLOY.md#L190-L204)

章节来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)
- [DEPLOY.md:190-204](file://DEPLOY.md#L190-L204)

## 核心组件
- 环境变量加载：统一从项目根目录加载 .env，支持本地与 Docker 两种模式。
- 环境判断：通过 APP_ENV 判断 development/production，影响日志与部分行为。
- 数据库：基于 Sequelize 的 MySQL 连接，支持日志输出与表定义选项。
- JWT：基于 HS256 的签名与校验，支持自定义密钥与过期时间。
- Redis：EQ 缓存专用客户端，支持密码、超时与错误日志。
- S3：OTA 包上传，支持显式凭证与 IAM 角色两种方式。
- 日志：Winston 控制台与文件双通道输出。

章节来源
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)

## 架构总览
下图展示环境变量在系统中的流向与依赖关系。

```mermaid
graph TB
subgraph "运行时"
ENV["环境变量<br/>.env 加载"]
APP["应用入口<br/>src/app.js"]
DB["数据库<br/>Sequelize"]
JWT["JWT 工具"]
RDS["Redis 客户端"]
S3["S3 客户端"]
LOG["日志"]
end
ENV --> APP
APP --> DB
APP --> JWT
APP --> RDS
APP --> S3
APP --> LOG
```

图示来源
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)

## 详细组件分析

### 数据库连接配置（MySQL/Sequelize）
- 关键变量
  - DATABASE_HOST：数据库主机，默认 localhost
  - DATABASE_PORT：数据库端口，默认 3306
  - DATABASE_NAME：数据库名，默认 audio
  - DATABASE_USER：用户名，默认 root
  - DATABASE_PASSWORD：密码，默认 root123
- 行为特征
  - 开发环境启用 SQL 日志打印
  - 冻结表名、禁用时间戳
- 配置验证
  - 启动时尝试同步模型，失败会记录警告但继续运行
- 常见错误
  - 凭据错误：核对 DATABASE_USER/PASSWORD
  - 端口/主机不可达：确认网络连通与防火墙
  - 字符集问题：确保 utf8mb4 支持

章节来源
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/app.js:42-56](file://backend/src/app.js#L42-L56)

### JWT 认证配置
- 关键变量
  - JWT_SECRET：签名密钥（必须在生产环境强制设置）
  - 算法：HS256
  - 过期时间：12 小时
- 安全建议
  - 生产环境务必设置强随机密钥，避免硬编码
  - 密钥长度至少 256 位
- 常见错误
  - 密钥缺失：默认值仅用于开发，生产会失效
  - 过期频繁：检查客户端刷新逻辑与服务端时钟

章节来源
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [DEPLOY.md:39](file://DEPLOY.md#L39)

### Redis 缓存配置（EQ 缓存）
- 关键变量
  - REDIS_HOST：默认 127.0.0.1
  - REDIS_PORT：默认 6379
  - REDIS_PASSWORD：可选
  - REDIS_EQ_DB：默认 1
- 行为特征
  - 单例客户端，带最大重试与连接超时
  - 连接错误通过日志上报
- 常见错误
  - 密码错误：确认 REDIS_PASSWORD 与 ACL 设置
  - DB 选择错误：核对 REDIS_EQ_DB
  - 连接超时：检查网络与 Redis 性能

章节来源
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/eqCacheStorage.js:1-73](file://backend/src/services/eqCacheStorage.js#L1-L73)

### S3 存储配置（OTA 升级包）
- 关键变量
  - AWS_REGION：默认 eu-central-1
  - AWS_ACCESS_KEY_ID：可选（本地开发）
  - AWS_SECRET_ACCESS_KEY：可选（本地开发）
  - AWS_S3_OTA_BUCKET：默认 luxsin-app-bucket
  - OTA_UPLOAD_DIR：X9 本地存储目录（开发默认临时目录，生产默认 /data/projects/source）
  - OTA_X8_PUBLIC_BASE：X8 下载地址前缀
  - OTA_X9_URL_BASE：X9 下载地址前缀
- 行为特征
  - X8：上传至 S3，支持显式凭证或 IAM 角色
  - X9：保存到宿主机卷（/data/projects/source）
- 常见错误
  - S3 权限不足：检查 IAM 角色或凭证
  - 本地目录权限：确认写入权限与磁盘空间
  - 地址拼接异常：核对 OTA_X8_PUBLIC_BASE/OTA_X9_URL_BASE 结尾斜杠处理

章节来源
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [docker-compose.yml:26](file://docker-compose.yml#L26)

### 环境变量加载与环境判断
- 加载策略
  - 本地开发：读取项目根目录 .env
  - Docker：通过 compose env_file 注入，容器内不覆盖已有变量
- 环境常量
  - APP_ENV：development/production
  - isDevelopment/isProduction：用于分支逻辑（如数据库日志）

章节来源
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [docker-compose.yml:13-18](file://docker-compose.yml#L13-L18)

### Meilisearch 搜索引擎配置
- 文档中明确列出变量类别与变量名，但未在后端代码中直接实现对应客户端。
- 建议在实际集成时新增配置模块，遵循现有命名风格与加载方式。

章节来源
- [DEPLOY.md:199](file://DEPLOY.md#L199)

## 依赖关系分析
- 入口应用依赖配置模块与服务模块
- 配置模块之间低耦合，通过 process.env 解耦
- Docker Compose 提供环境变量注入与端口映射

```mermaid
graph LR
APP["app.js"] --> LOADENV["loadEnv.js"]
APP --> DB["database.js"]
APP --> JWTU["jwt.js"]
APP --> REDIS["redis.js"]
APP --> OTAS["otaStorage.js"]
APP --> EQCS["eqCacheStorage.js"]
APP --> LOGF["logger.js"]
DC["docker-compose.yml"] --> APP
```

图示来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [backend/src/config/loadEnv.js:1-15](file://backend/src/config/loadEnv.js#L1-L15)
- [backend/src/config/database.js:1-24](file://backend/src/config/database.js#L1-L24)
- [backend/src/utils/jwt.js:1-28](file://backend/src/utils/jwt.js#L1-L28)
- [backend/src/config/redis.js:1-32](file://backend/src/config/redis.js#L1-L32)
- [backend/src/services/otaStorage.js:1-113](file://backend/src/services/otaStorage.js#L1-L113)
- [backend/src/services/eqCacheStorage.js:1-73](file://backend/src/services/eqCacheStorage.js#L1-L73)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)

章节来源
- [backend/src/app.js:1-60](file://backend/src/app.js#L1-L60)
- [docker-compose.yml:1-46](file://docker-compose.yml#L1-L46)

## 性能考虑
- 数据库
  - 开发环境开启 SQL 日志便于调试，生产关闭以降低开销
  - 合理设置连接池参数（如需扩展）
- Redis
  - 控制最大重试次数与连接超时，避免阻塞请求
  - 使用独立 DB 隔离 EQ 缓存，减少键冲突
- S3
  - 上传前计算 MD5，避免重复上传
  - 生产环境优先使用 IAM 角色，减少凭证泄露风险

## 故障排查指南
- 环境变量不生效
  - Docker：修改 .env 后需重建容器或强制重启
  - 本地：确认根目录 .env 是否存在且格式正确
- 数据库连接失败
  - 核对主机、端口、凭据与字符集
  - 检查防火墙与网络策略
- Redis 连接失败
  - 核对主机、端口、密码与 DB 选择
  - 检查 Redis 服务状态与资源限制
- S3 上传失败
  - 核对区域、桶名与凭证或 IAM 角色
  - 检查网络与对象权限
- 健康检查
  - 访问 /health 确认服务可用
  - 查看容器日志定位具体错误

章节来源
- [DEPLOY.md:245-255](file://DEPLOY.md#L245-L255)
- [backend/src/app.js:31-34](file://backend/src/app.js#L31-L34)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)

## 结论
本项目采用集中式环境变量加载与模块化配置设计，结合 Docker Compose 实现多环境一致性。建议在生产环境严格管理敏感变量，采用 IAM 角色与最小权限原则，并完善配置验证与监控告警机制。

## 附录

### 不同环境配置差异建议
- 开发环境
  - APP_ENV=development
  - 数据库日志开启
  - JWT_SECRET 可使用默认值（仅开发）
  - OTA_UPLOAD_DIR 指向本地临时目录
- 测试环境
  - APP_ENV=production
  - 数据库日志关闭
  - JWT_SECRET 强随机值
  - S3 使用测试账号或角色
- 生产环境
  - APP_ENV=production
  - 所有敏感变量通过环境注入
  - S3 优先 IAM 角色
  - 日志与健康检查完善

章节来源
- [backend/src/config/env.js:1-13](file://backend/src/config/env.js#L1-L13)
- [backend/src/config/database.js:15](file://backend/src/config/database.js#L15)
- [DEPLOY.md:39](file://DEPLOY.md#L39)
- [docker-compose.yml:18](file://docker-compose.yml#L18)

### 敏感信息的安全存储与版本控制策略
- .env 不纳入版本控制，服务器单独维护
- 使用 IAM 角色替代明文凭证（S3）
- 密钥轮换流程：生成新密钥 → 更新 .env → 重启服务 → 废弃旧密钥
- 最小权限原则：仅为需要的功能授予最小权限

章节来源
- [DEPLOY.md:40-41](file://DEPLOY.md#L40-L41)
- [DEPLOY.md:39](file://DEPLOY.md#L39)

### 配置验证方法
- 启动日志：观察数据库同步与服务启动信息
- 健康检查：访问 /health
- 功能测试：登录、查询、上传等关键路径
- 日志审计：关注错误日志与异常堆栈

章节来源
- [backend/src/app.js:42-56](file://backend/src/app.js#L42-L56)
- [backend/src/app.js:31-34](file://backend/src/app.js#L31-L34)
- [backend/src/config/logger.js:1-29](file://backend/src/config/logger.js#L1-L29)

### 常见配置错误与解决办法
- JWT_SECRET 未设置：在生产环境设置强随机密钥
- S3 凭证或权限问题：检查凭证或 IAM 角色策略
- Redis 密码或 DB 错误：核对密码与 DB 编号
- 端口映射冲突：调整宿主机端口或容器端口
- 环境变量未生效：在 Docker 中强制重建容器

章节来源
- [backend/src/utils/jwt.js:3](file://backend/src/utils/jwt.js#L3)
- [backend/src/services/otaStorage.js:77-83](file://backend/src/services/otaStorage.js#L77-L83)
- [backend/src/config/redis.js:20-22](file://backend/src/config/redis.js#L20-L22)
- [DEPLOY.md:245-249](file://DEPLOY.md#L245-L249)

### 配置模板与示例文件说明
- 示例文件位置：项目根目录提供 .env.example（后端 README 中提及）
- 变量分类参考：数据库、应用、认证、搜索、S3、OTA、Redis EQ 等
- 服务器维护：.env 仅在服务器维护，不提交到版本库

章节来源
- [DEPLOY.md:29-34](file://DEPLOY.md#L29-L34)
- [DEPLOY.md:190-204](file://DEPLOY.md#L190-L204)