---
kind: configuration_system
name: 基于 .env + docker-compose 的环境配置体系
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
    - .env.example
    - docker-compose.yml
    - frontend_v2/.env
    - frontend_v2/.env.prod
    - frontend_v2/vite.config.ts
---

## 系统概览
本仓库采用“环境变量优先”的轻量配置方案：后端通过 `dotenv` 加载根目录 `.env`，Docker 部署时由 `docker-compose.yml` 的 `env_file` 注入；前端使用 Vite 的 `loadEnv` 按构建模式（dev/prod）加载对应 `.env.*`。所有运行时参数（数据库、Redis、S3、OTA、JWT 等）均通过环境变量驱动，无集中式配置文件。

## 核心文件与职责
- `backend/src/config/loadEnv.js` — 启动入口最先执行，从项目根目录加载 `.env`，容器内不存在该文件则跳过，避免覆盖 compose 注入的环境变量。
- `backend/src/config/env.js` — 统一暴露 `APP_ENV`、`isDevelopment`、`isProduction`，供各模块判断运行环境。
- `backend/src/config/database.js` — 基于 `process.env.DATABASE_*` 初始化 Sequelize，开发环境开启 SQL 日志。
- `backend/src/config/redis.js` — 基于 `REDIS_*` 环境变量懒创建 ioredis 客户端，仅用于 EQ 缓存。
- `backend/src/config/logger.js` — winston 输出到 `backend/logs/app.log` 与 stdout，便于 Docker 收集。
- `backend/src/app.js` — 应用入口，先 `require('./config/loadEnv')`，再读取 `PORT` 监听。
- `docker-compose.yml` — 通过 `env_file: .env` 注入全部后端配置，并固定容器内 `PORT=8000`、`APP_ENV=production`。
- `.env.example` — 完整的环境变量清单与默认值，作为部署参考。
- `frontend_v2/.env` / `.env.prod` — Vite 前缀为 `VITE_` 的前端构建期配置，prod 下 `VITE_SERVICE_BASE_URL=/api` 配合 Nginx 反向代理。
- `frontend_v2/vite.config.ts` — 通过 `loadEnv(mode, cwd)` 读取当前模式的 `.env*`，注入 `base`、proxy、sourcemap 等。

## 架构与约定
1. **单点加载**：后端仅在 `app.js` 首行 `require('./config/loadEnv')`，保证 dotenv 在其它模块读取 `process.env` 之前生效。
2. **环境变量命名规范**：
   - 后端：`DATABASE_*`、`REDIS_*`、`AWS_*`、`MEILISEARCH_*`、`JWT_SECRET`、`PORT`、`APP_ENV` 等。
   - 前端：全部以 `VITE_` 开头，由 Vite 编译期注入到 `import.meta.env`。
3. **环境区分**：`APP_ENV` 控制后端行为（SQL 日志开关），`VITE_SOURCE_MAP`、`VITE_HTTP_PROXY` 等控制前端构建/开发行为。
4. **Docker 注入优先级**：compose 的 `environment:` 字段会覆盖 `.env` 中的同名变量（如 `PORT=8000`、`APP_ENV=${APP_ENV:-production}`）。
5. **服务间通信**：生产环境前端通过 Nginx `/api` 代理到后端 8000 端口，无需硬编码后端地址。

## 开发者应遵循的规则
- 新增环境变量时同步更新 `.env.example`，并在相关模块中提供合理默认值。
- 敏感信息（`JWT_SECRET`、`AWS_SECRET_ACCESS_KEY`、`REDIS_PASSWORD` 等）不得提交到仓库，仅保留占位示例。
- 后端模块一律通过 `process.env.XXX || 'default'` 读取，禁止直接引用外部 JSON/YAML 配置文件。
- 前端新增配置必须以 `VITE_` 前缀声明，并通过 `vite.config.ts` 的 `loadEnv` 或业务代码中的 `import.meta.env` 访问。
- 本地调试时修改根目录 `.env`；容器化部署时通过 `docker-compose.yml` 的 `environment:` 或外部 `.env` 覆盖。