dashboard/.qoder/repowiki/knowledge/zh/环境变量与配置加载体系/环境变量与配置加载体系.md

kind, name, category, scope, source_files

kind	name	category	scope	source_files
configuration_system	环境变量与配置加载体系	configuration_system	**	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
认证	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，避免启动期崩溃。