dashboard/.qoder/repowiki/knowledge/zh/基于环境变量与 Docker Compose 的分层配置体系/configuration_system.md

1. 核心系统与工具

该项目采用 环境变量（Environment Variables） 作为唯一的配置来源，结合 dotenv 库进行本地开发时的文件加载，并通过 Docker Compose 在部署时注入环境变量。这种模式遵循了 12-Factor App 的配置原则，实现了配置与代码的分离。

• 后端 (Node.js/Express): 使用 dotenv 加载根目录 .env 文件。
• 前端 (Vue 3/Vite): 依赖 Vite 的默认行为，通过 vite.config.js 中的代理配置处理开发环境 API 路由，生产环境配置通常由构建产物或 Nginx 静态配置决定。
• 编排工具: 使用 docker-compose.yml 统一管理多服务的环境变量注入和端口映射。

2. 关键文件与职责

文件路径	职责描述
/.env & /.env.example	全局配置模板。定义了数据库、Redis、S3、JWT 密钥等所有服务的运行时参数。
/backend/src/config/loadEnv.js	环境加载入口。在后端应用启动初期，自动检测并加载项目根目录的 .env 文件。
/backend/src/config/env.js	环境状态管理。统一导出 APP_ENV、isDevelopment、isProduction 标志，供其他模块判断运行模式。
/backend/src/config/database.js	数据库配置。从环境变量读取 MySQL 连接信息，并根据环境标志决定是否开启 SQL 日志。
/backend/src/config/redis.js	缓存配置。从环境变量读取 Redis 连接信息，实现单例模式的客户端初始化。
/docker-compose.yml	部署配置。通过 env_file 将 .env 注入后端容器，并强制覆盖部分变量（如容器内端口）。
/frontend/vite.config.js	前端开发配置。定义了开发服务器的端口及指向后端的 API 代理规则。

3. 架构设计与分层逻辑

3.1 配置加载流程

1. 初始化阶段: backend/src/app.js 第一行即调用 require('./config/loadEnv')，确保后续所有模块能访问到 process.env。
2. 本地开发: loadEnv.js 检查根目录是否存在 .env，若存在则通过 dotenv.config() 将其载入内存。
3. 容器部署: Docker Compose 通过 env_file: - .env 将变量注入容器。此时容器内可能不存在 .env 文件，但环境变量已由 Docker 守护进程提供。

3.2 环境隔离策略

• 逻辑环境: 通过 APP_ENV 变量区分 development 和 production。该变量控制日志输出级别、数据库同步行为等。
• 物理环境:
  • 本地: 后端监听 8083 端口，前端通过 Vite Proxy 转发请求。
  • Docker: 后端在容器内监听 8000 端口（由 Compose 强制指定），外部映射为 8083；前端由 Nginx 托管，映射为 8082。

3.3 敏感信息管理

• 示例文件: 提供 .env.example 作为模板，避免敏感信息（如 JWT_SECRET, AWS_ACCESS_KEY_ID）直接提交到版本控制系统。
• 默认值保护: 在 database.js 和 redis.js 中为关键配置提供了硬编码的默认值（如 root123），防止因环境变量缺失导致应用崩溃，但在生产环境中应始终通过 .env 覆盖这些默认值。

4. 开发者规范

1. 新增配置项:
   • 必须在 .env.example 中添加对应的键名和说明。
   • 在 backend/src/config/ 下创建或更新对应的配置模块，通过 process.env.VAR_NAME 获取值。
2. 环境判断:
   • 严禁在业务代码中直接读取 process.env.APP_ENV。
   • 必须使用 src/config/env.js 导出的 isDevelopment 或 isProduction 布尔值，以保持逻辑一致性。
3. 端口一致性:
   • 修改后端端口时，需同步更新 .env 中的 PORT、docker-compose.yml 中的 environment 覆盖项以及 ports 映射。
4. 前端代理:
   • 若后端开发端口变更，需同步修改 frontend/vite.config.js 中的 proxy.target。