新增项目文档

2026-06-30 14:46:52 +08:00
parent cac5bef5a7
commit 08da279275
79 changed files with 20860 additions and 0 deletions
@@ -0,0 +1,351 @@
+# 环境配置
+
+<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)