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 backend/src/config/logger.js docker-compose.yml frontend/.env frontend/.env.prod frontend/.env.test frontend/vite.config.ts

1. 系统概览

本项目采用前后端分离 + Docker Compose 编排的架构，配置系统围绕“环境变量优先、文件兜底”的原则组织：

• 后端（Node.js/Express）：通过 dotenv 从仓库根目录 .env 加载，Docker 部署时由 docker-compose.yml 的 env_file 注入，不覆盖已有环境变量。
• 前端（Vite）：使用 Vite 内置的 loadEnv，按构建模式（development / test / production）分别读取 .env、.env.test、.env.prod，所有 VITE_ 前缀变量在构建期注入到 import.meta.env。
• 容器编排：docker-compose.yml 通过 env_file 和 environment 为后端注入运行时配置，并通过端口映射与 Nginx 静态资源卷完成服务暴露。

2. 关键文件与包

层级	文件	作用
后端入口	backend/src/app.js	首行 require('./config/loadEnv') 触发 .env 加载；集中挂载中间件、路由、启动监听
环境判断	backend/src/config/env.js	基于 APP_ENV 导出 isDevelopment / isProduction 布尔值
环境变量加载	backend/src/config/loadEnv.js	仅当根目录存在 .env 时才调用 dotenv.config，避免覆盖容器注入的环境变量
数据库配置	backend/src/config/database.js	从 DATABASE_* 环境变量构造 Sequelize 实例，开发模式开启 SQL 日志
Redis 缓存	backend/src/config/redis.js	懒初始化 ioredis 客户端，支持密码与多 DB 选择
日志配置	backend/src/config/logger.js	winston 双传输（Console + File），固定输出到 backend/logs/app.log
容器编排	docker-compose.yml	定义 backend/frontend 两个服务，通过 env_file: .env 注入后端配置，固定 PORT=8000
前端基础配置	frontend/.env	应用标题、路由模式、代理开关等通用 Vite 变量
前端生产配置	frontend/.env.prod	指定 VITE_SERVICE_BASE_URL=/api（同域 Nginx 反代）
前端测试配置	frontend/.env.test	指向本地后端 http://localhost:8083/api
Vite 构建脚本	frontend/vite.config.ts	通过 loadEnv(mode, cwd) 读取对应 .env.*，并注入 base、proxy、define 等

3. 架构与设计约定

3.1 后端配置加载顺序

进程启动 → app.js → require('./config/loadEnv')
         → dotenv.config({ path: root/.env })   // 仅当文件存在
         → 各模块直接 process.env.XXX 取值

• 优先级：容器注入环境变量 > .env 文件默认值（process.env.DATABASE_PASSWORD || 'root123'）。
• 环境区分：APP_ENV 决定 isDevelopment / isProduction，用于控制 Sequelize SQL 日志开关等。

3.2 前端配置加载顺序

vite serve/build → loadEnv(mode, cwd)
                 → development: 读取 .env + .env.development
                 → test:        读取 .env + .env.test
                 → production:  读取 .env + .env.prod
                 → 仅 VITE_* 前缀变量注入到 import.meta.env

• 生产构建产物不包含源码，因此 VITE_SERVICE_BASE_URL=/api 通过 Nginx 反向代理到后端 /api，实现同源部署。
• 开发/测试环境通过 VITE_HTTP_PROXY=Y 配合 createViteProxy 将请求转发到 http://localhost:8083。

3.3 容器化配置

• 后端容器内固定 PORT=8000，宿主机映射 8083:8000，与 Nginx proxy_pass http://backend:8000 一致。
• extra_hosts: host.docker.internal:host-gateway 允许容器访问宿主机 MySQL/Redis。
• 前端容器只挂载静态资源与 nginx.conf，无运行时配置。

4. 开发者应遵循的规则

1. 新增后端环境变量：统一以 DATABASE_*、REDIS_*、PORT、APP_ENV 等大写命名，在 backend/src/config/*.js 中提供默认值，并在 docker-compose.yml 的 env_file 或 environment 中声明。
2. 不要修改 loadEnv.js 的加载逻辑：它刻意只在本地存在 .env 时才加载，避免覆盖 Docker 注入的环境变量。
3. 新增前端环境变量：必须以 VITE_ 开头，放在对应环境的 .env.* 文件中；若需跨环境共享，放入根 .env。
4. 生产部署：确保 frontend/.env.prod 的 VITE_SERVICE_BASE_URL 与 Nginx 的反代路径一致（当前为 /api）。
5. 敏感信息：数据库密码、Redis 密码等不要提交到版本库，使用 docker-compose.yml 的 env_file 或宿主机的环境变量注入。
6. 日志位置：后端日志固定写入 backend/logs/app.log，容器内可通过 volume 持久化到宿主机 /data/projects/source。