---
kind: configuration_system
name: 基于环境变量与 Docker Compose 的分层配置体系
category: configuration_system
scope:
    - '**'
source_files:
    - .env.example
    - backend/src/config/loadEnv.js
    - backend/src/config/env.js
    - backend/src/config/database.js
    - backend/src/config/redis.js
    - docker-compose.yml
    - frontend/vite.config.js
---

## 1. 核心系统与工具
该项目采用 **环境变量（Environment Variables）** 作为唯一的配置来源，结合 **`dotenv`** 库进行本地开发时的文件加载，并通过 **Docker Compose** 在部署时注入环境变量。这种模式遵循了 [12-Factor App](https://12factor.net/zh-cn/config) 的配置原则，实现了配置与代码的分离。

- **后端 (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`。