添加 uipro，更新 wiki

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

@@ -0,0 +1,47 @@
+---
+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，避免启动期崩溃。