新增项目文档

2026-06-30 14:46:52 +08:00
parent cac5bef5a7
commit 08da279275
79 changed files with 20860 additions and 0 deletions
@@ -0,0 +1,14 @@
+schema_version: 1
+module_path: configuration_system
+title: 基于环境变量与 Docker Compose 的分层配置体系
+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
+depends_on: []
+related_to: []
@@ -0,0 +1,48 @@
+## 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`。