eafonyang
47 lines
3.4 KiB
Markdown
47 lines
3.4 KiB
Markdown
---
|
||
kind: configuration_system
|
||
name: 环境变量与配置加载体系
|
||
category: configuration_system
|
||
scope:
|
||
- '**'
|
||
source_files:
|
||
- backend/src/app.js
|
||
- backend/src/config/loadEnv.js
|
||
- backend/src/config/env.js
|
||
- backend/src/config/database.js
|
||
- backend/src/config/redis.js
|
||
- .env.example
|
||
- docker-compose.yml
|
||
---
|
||
|
||
## 系统概览
|
||
本仓库采用「进程级 .env 文件 + 环境变量」的轻量配置方案，由后端在启动时统一加载，未引入第三方配置中心或 YAML/JSON 配置文件。所有运行时参数通过 `process.env` 注入，开发环境与生产环境通过 `APP_ENV` 区分。
|
||
|
||
## 核心机制
|
||
- **统一入口加载**：`backend/src/app.js` 首行 `require('./config/loadEnv')`，确保应用启动前完成 `.env` 解析。
|
||
- **dotenv 加载策略**：`loadEnv.js` 固定从仓库根目录读取 `.env`（`path.resolve(__dirname, '../../../.env')`），仅在文件存在时调用 `dotenv.config()`；Docker 部署时通过 `docker-compose.yml` 的 `env_file` 注入，容器内无 `.env` 也不会覆盖已存在的环境变量。
|
||
- **环境判断工具**：`config/env.js` 暴露 `APP_ENV`、`isDevelopment`、`isProduction`，供各模块按环境切换行为（如数据库日志开关）。
|
||
|
||
## 配置项分类与约定
|
||
| 类别 | 关键变量 | 默认值 / 说明 |
|
||
|---|---|---|
|
||
| 数据库 | `DATABASE_HOST`, `DATABASE_PORT`, `DATABASE_NAME`, `DATABASE_USER`, `DATABASE_PASSWORD` | MySQL，Sequelize 直连，`dialectOptions.charset='utf8mb4'`，开发模式打印 SQL |
|
||
| 应用 | `APP_NAME`, `APP_ENV`, `PORT` | `APP_ENV=development|production`；本地默认 8083，Docker 内 8000 |
|
||
| 认证 | `JWT_SECRET`, `DASHBOARD_ADMIN_USERNAME`, `DASHBOARD_ADMIN_PASSWORD` | 首次启动自动创建超级管理员 |
|
||
| S3 存储 | `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_S3_OTA_BUCKET`, `AWS_S3_MEASUREMENT_BUCKET` | 正式环境可通过 IAM 角色免 AK/SK 访问 |
|
||
| OTA 地址 | `OTA_X8_PUBLIC_BASE`, `OTA_X9_URL_BASE`, `OTA_UPLOAD_DIR` | X8/X9 升级包基 URL；上传目录仅生产环境需显式配置 |
|
||
| Redis 缓存 | `REDIS_HOST`, `REDIS_PORT`, `REDIS_PASSWORD`, `REDIS_EQ_DB` | ioredis 单例，连接失败记录错误日志 |
|
||
| 外部服务 | `MEILISEARCH_*`, `CURVE_API_BASE_URL` | 搜索与曲线 API 基础地址 |
|
||
|
||
## 架构与约定
|
||
- **单一来源**：`.env.example` 是配置清单，实际 `.env` 不应提交到版本库（已在 `.gitignore` 中忽略）。
|
||
- **分层组织**：`backend/src/config/` 下每个子模块只负责自身依赖的配置读取（database、redis、logger），不互相耦合。
|
||
- **环境变量优先**：所有配置均从 `process.env` 读取，并带合理默认值，保证本地可零配置运行。
|
||
- **Docker 集成**：`docker-compose.yml` 通过 `env_file: [.env]` 和 `environment:` 覆盖端口与环境变量，实现同一份 `.env` 同时驱动本地与容器。
|
||
|
||
## 开发者规则
|
||
1. 新增配置项先在 `.env.example` 中添加注释与默认值，再在对应 `config/*.js` 中读取。
|
||
2. 敏感信息（密码、密钥）一律走环境变量，禁止硬编码或写入代码。
|
||
3. 使用 `APP_ENV` 做环境分支逻辑，不要直接检查主机名或路径。
|
||
4. Docker 部署时通过 compose 的 `environment` 覆盖必要变量，保持 `.env` 最小化。
|
||
5. 若某配置有默认值且允许空值，务必在读取处提供 fallback，避免启动期崩溃。 |