audio/dashboard
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cacee5f294a215a7b3f0feff568df5431d8ac8b4
dashboard/.qoder/repowiki/zh/content/部署与运维/环境配置.md
T
eafonyang 08da279275 新增项目文档
2026-06-30 14:46:52 +08:00

14 KiB
Raw Blame History

环境配置

**本文引用的文件** - [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)

目录

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

简介

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

项目结构

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

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

图示来源

章节来源

核心组件

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

章节来源

架构总览

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

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

图示来源

详细组件分析

数据库连接配置（MySQL/Sequelize）

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

章节来源

JWT 认证配置

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

章节来源

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 性能

章节来源

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 结尾斜杠处理

章节来源

环境变量加载与环境判断

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

章节来源

Meilisearch 搜索引擎配置

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

章节来源

依赖关系分析

  • 入口应用依赖配置模块与服务模块
  • 配置模块之间低耦合，通过 process.env 解耦
  • Docker Compose 提供环境变量注入与端口映射
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

图示来源

章节来源

性能考虑

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

故障排查指南

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

章节来源

结论

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

附录

不同环境配置差异建议

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

章节来源

敏感信息的安全存储与版本控制策略

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

章节来源

配置验证方法

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

章节来源

常见配置错误与解决办法

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

章节来源

配置模板与示例文件说明

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

章节来源

Reference in New Issue View Git Blame Copy Permalink