dashboard/.qoder/repowiki/knowledge/zh/后端环境变量与配置加载体系/后端环境变量与配置加载体系.md

kind, name, category, scope, source_files

kind	name	category	scope	source_files
configuration_system	后端环境变量与配置加载体系	configuration_system	**	backend/src/config/loadEnv.js backend/src/config/env.js backend/src/config/database.js backend/src/config/redis.js backend/src/config/logger.js backend/src/app.js .env.example docker-compose.yml

系统概览

本仓库采用「根目录 .env + 启动时 dotenv 注入 + 各模块按需读取 process.env」的轻量级配置方案，未引入集中式配置中心或类型化配置库。所有运行时参数均通过环境变量提供，由 Node.js 进程在启动阶段加载。

关键文件与职责

• backend/src/config/loadEnv.js：应用入口最先执行，从仓库根目录解析并加载 .env（仅本地开发存在；Docker 部署时由 compose env_file 注入，容器内无该文件则跳过）。
• backend/src/config/env.js：统一环境判断工具，基于 APP_ENV 导出 isDevelopment / isProduction 布尔值供其他模块使用。
• backend/src/app.js：Express 入口，先 require('./config/loadEnv') 再初始化数据库、路由、监听端口等。
• backend/src/config/database.js：Sequelize 实例，连接 MySQL，默认值 audio/root/root123，开发模式开启 SQL 日志。
• backend/src/config/redis.js：ioredis 单例工厂 getEqCacheRedis()，按 REDIS_EQ_DB 选择独立 DB，带错误回调与超时重试。
• backend/src/config/logger.js：winston 双通道（Console + File），固定输出到 backend/logs/app.log。
• .env.example：完整的环境变量清单与注释，作为部署模板。
• docker-compose.yml：通过 env_file: .env 与 environment 覆盖 PORT=8000、APP_ENV=${APP_ENV:-production}，并将宿主机 /data/projects/source 挂载进容器。

架构与约定

1. 加载顺序：app.js → loadEnv（dotenv）→ 各 config/* 模块读 process.env → 业务层直接使用。
2. 环境区分：仅依赖 APP_ENV 两个取值（development / production），没有多环境配置文件分支。
3. 默认值策略：每个配置项在读取处给出合理默认值（如数据库 localhost:3306/audio/root/root123、Redis 127.0.0.1:6379/db=1、端口 8083），保证本地开箱即用。
4. 密钥与敏感信息：JWT secret、数据库密码、AWS 凭据、Meilisearch API Key 全部走环境变量，.env 被 .gitignore 排除。
5. 外部服务解耦：MySQL、Redis、S3、Meilisearch、Curve API 等均以独立环境变量命名空间暴露，新增依赖只需在 .env.example 补充条目并在对应 config 中读取。
6. 前端侧：前端为纯静态产物，不直接读取 .env；构建期由 Vite 注入 import.meta.env.*，但当前代码未见前端配置模块，前端通过相对路径请求后端 API。

开发者应遵循的规则

• 新增配置项必须在 .env.example 中声明并附带注释说明用途与默认值。
• 所有配置读取必须放在 backend/src/config/* 子模块中，禁止在业务路由或服务里直接散落 process.env 调用。
• 对数值型配置使用 parseInt(..., 10) 显式转换，避免字符串拼接导致类型错误。
• 生产环境一律通过 Docker Compose env_file 或编排平台注入环境变量，不得将真实 .env 提交至仓库。
• 如需新增外部依赖（新数据库、消息队列等），仿照 database.js / redis.js 的模式创建独立配置模块并导出单例。