dashboard/.qoder/repowiki/knowledge/zh/基于 .env + docker-compose 的环境配置体系/基于 .env + docker-compose 的环境配置体系.md

kind, name, category, scope, source_files

kind	name	category	scope	source_files
configuration_system	基于 .env + docker-compose 的环境配置体系	configuration_system	**	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 覆盖。