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

351 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 环境配置
<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)
Reference in New Issue View Git Blame Copy Permalink