52 lines
3.0 KiB
Markdown
52 lines
3.0 KiB
Markdown
|
---
|
|||
|
|
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
|
|||
|
|
- .env.example
|
|||
|
|
- backend/src/app.js
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 系统概述
|
|||
|
|
本项目的配置系统基于 Node.js 的 `dotenv` + 进程环境变量（`process.env`）实现，采用「根目录 `.env` 文件 + Docker compose env_file 注入」的双源模式，通过统一的入口在应用启动时完成加载。
|
|||
|
|
|
|||
|
|
## 核心机制
|
|||
|
|
- **统一入口**：`backend/src/app.js` 首行 `require('./config/loadEnv')` 触发配置加载，确保所有后续模块都能读到环境变量。
|
|||
|
|
- **本地开发**：`loadEnv.js` 解析项目根目录 `dashboard/.env`（相对 `__dirname` 向上四层），使用 `dotenv.config({ path })` 注入到 `process.env`；若文件不存在则静默跳过。
|
|||
|
|
- **Docker 部署**：容器内无 `.env` 文件，由 `docker-compose.yml` 的 `env_file` 直接注入环境变量，`fs.existsSync` 判断避免覆盖已有值。
|
|||
|
|
- **环境判断**：`config/env.js` 暴露 `APP_ENV`、`isDevelopment`、`isProduction` 三个常量，供各模块按环境切换行为（如 Sequelize SQL 日志开关）。
|
|||
|
|
|
|||
|
|
## 配置项组织
|
|||
|
|
所有可配置项集中在根级 `.env.example`，按功能域分组注释：
|
|||
|
|
- 数据库：`DATABASE_HOST/PORT/NAME/USER/PASSWORD`
|
|||
|
|
- 应用：`APP_NAME`、`APP_ENV`、`PORT`
|
|||
|
|
- JWT 与初始管理员：`JWT_SECRET`、`DASHBOARD_ADMIN_USERNAME/PASSWORD`
|
|||
|
|
- Meilisearch：`MEILISEARCH_URL/API_KEY/INDEX`
|
|||
|
|
- AWS S3：`AWS_REGION/ACCESS_KEY_ID/SECRET_ACCESS_KEY/S3_OTA_BUCKET/S3_MEASUREMENT_BUCKET`
|
|||
|
|
- OTA URL 与上传目录：`OTA_X8_PUBLIC_BASE`、`OTA_X9_URL_BASE`、`OTA_UPLOAD_DIR`
|
|||
|
|
- Curve API：`CURVE_API_BASE_URL`
|
|||
|
|
- Redis EQ 缓存：`REDIS_HOST/PORT/PASSWORD/EQ_DB`
|
|||
|
|
|
|||
|
|
## 配置消费方式
|
|||
|
|
各模块直接通过 `process.env.XXX || '默认值'` 读取，形成「分散式消费」模式：
|
|||
|
|
- `config/database.js` → MySQL 连接参数
|
|||
|
|
- `config/redis.js` → ioredis 客户端（含密码可选、错误监听）
|
|||
|
|
- `config/logger.js` → winston 输出级别与文件路径
|
|||
|
|
- `services/otaStorage.js` → OTA 包上传目录与 S3 配置
|
|||
|
|
- `services/measurementStorage.js` → 频响测量文件 S3 存储
|
|||
|
|
- `routes/models.js` → Meilisearch 搜索索引
|
|||
|
|
- `services/curveClient.js` → 曲线查询外部 API 基地址
|
|||
|
|
|
|||
|
|
## 设计约定与约束
|
|||
|
|
1. **禁止硬编码敏感信息**：所有密钥、密码、URL 必须来自环境变量，`.env` 已在 `.gitignore` 中排除。
|
|||
|
|
2. **默认值兜底**：每个 `process.env` 读取都提供合理默认值，保证本地开箱即用。
|
|||
|
|
3. **按域拆分配置文件**：数据库、Redis、日志等基础设施各自独立文件，便于扩展新依赖。
|
|||
|
|
4. **Docker 优先**：生产环境推荐通过 compose `env_file` 注入而非挂载 `.env` 文件。
|
|||
|
|
5. **新增配置项流程**：先在 `.env.example` 添加注释说明，再在各消费处补充 `process.env.XXX || default`。
|