2026-07-14 18:56:13 +08:00
|
|
|
|
---
|
|
|
|
|
|
kind: configuration_system
|
|
|
|
|
|
name: 后端环境变量与配置加载体系
|
|
|
|
|
|
category: configuration_system
|
|
|
|
|
|
scope:
|
|
|
|
|
|
- '**'
|
|
|
|
|
|
source_files:
|
|
|
|
|
|
- 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
|
2026-07-15 09:58:56 +08:00
|
|
|
|
- .env.example
|
|
|
|
|
|
- docker-compose.yml
|
2026-07-14 18:56:13 +08:00
|
|
|
|
---
|
|
|
|
|
|
|
2026-07-15 09:58:56 +08:00
|
|
|
|
## 系统概览
|
|
|
|
|
|
本仓库采用「根目录 `.env` + 启动时 `dotenv` 注入 + 各模块按需读取 `process.env`」的轻量级配置方案，未引入集中式配置中心或类型化配置库。所有运行时参数均通过环境变量提供，由 Node.js 进程在启动阶段加载。
|
2026-07-14 18:56:13 +08:00
|
|
|
|
|
2026-07-15 09:58:56 +08:00
|
|
|
|
## 关键文件与职责
|
|
|
|
|
|
- `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` 挂载进容器。
|
2026-07-14 18:56:13 +08:00
|
|
|
|
|
2026-07-15 09:58:56 +08:00
|
|
|
|
## 架构与约定
|
|
|
|
|
|
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。
|
2026-07-14 18:56:13 +08:00
|
|
|
|
|
2026-07-15 09:58:56 +08:00
|
|
|
|
## 开发者应遵循的规则
|
|
|
|
|
|
- 新增配置项必须在 `.env.example` 中声明并附带注释说明用途与默认值。
|
|
|
|
|
|
- 所有配置读取必须放在 `backend/src/config/*` 子模块中，禁止在业务路由或服务里直接散落 `process.env` 调用。
|
|
|
|
|
|
- 对数值型配置使用 `parseInt(..., 10)` 显式转换，避免字符串拼接导致类型错误。
|
|
|
|
|
|
- 生产环境一律通过 Docker Compose `env_file` 或编排平台注入环境变量，不得将真实 `.env` 提交至仓库。
|
|
|
|
|
|
- 如需新增外部依赖（新数据库、消息队列等），仿照 `database.js` / `redis.js` 的模式创建独立配置模块并导出单例。
|
