环境配置详解

环境配置详解

配置文件概述

DoraCMS 采用分层配置系统，通过环境变量和配置文件实现灵活的环境管理。

配置文件层次

.env 文件（环境变量）
    ↓
config/env.js（环境配置解析）
    ↓
config/config.default.js（应用配置）
    ↓
config/config.{env}.js（环境特定配置）

环境变量优先级

.env.${NODE_ENV}.local    # 最高优先级
.env.${NODE_ENV}          # 环境特定配置
.env.local                # 本地配置（不提交到版本控制）
.env                      # 默认配置

基础环境配置

创建配置文件

## 复制配置模板
cp server/env.example server/.env


## 或使用 Docker 配置
cp docker.env.example .env

核心配置项

运行环境

## 运行环境：development, production, test
NODE_ENV=development


## 服务器配置
PORT=8080
HOSTNAME=127.0.0.1


## Worker 进程数（生产环境建议设置为 CPU 核心数）
EGG_WORKERS=1

应用安全

## 应用密钥（必须修改为随机字符串）
APP_KEYS=your_random_secret_key_32_chars_long


## 会话密钥
SESSION_SECRET=your_session_secret_key


## JWT 密钥
JWT_SECRET=your_jwt_secret_key

生成安全密钥：

## 使用 Node.js 生成
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"


## 使用 OpenSSL 生成
openssl rand -hex 32


## 使用在线工具
## https://www.random.org/strings/

数据库配置

MongoDB 配置

## 数据库类型
DATABASE_TYPE=mongodb


## MongoDB 连接配置
MONGODB_HOST=127.0.0.1
MONGODB_PORT=27017
MONGODB_DATABASE=doracms3
MONGODB_USERNAME=your_username
MONGODB_PASSWORD=your_password


## 连接选项
MONGODB_OPTIONS=authSource=admin&retryWrites=true&w=majority


## 连接池配置
MONGODB_MAX_POOL_SIZE=10
MONGODB_MIN_POOL_SIZE=2

MariaDB 配置

## 数据库类型
DATABASE_TYPE=mariadb


## MariaDB 连接配置
MARIADB_HOST=127.0.0.1
MARIADB_PORT=3306
MARIADB_DATABASE=doracms3
MARIADB_USERNAME=your_username
MARIADB_PASSWORD=your_password


## 连接池配置
MARIADB_CONNECTION_LIMIT=10
MARIADB_ACQUIRE_TIMEOUT=60000
MARIADB_TIMEOUT=60000


## 启用 Repository 模式（推荐）
REPOSITORY_ENABLED=true

Redis 配置

## Redis 配置（可选）
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_DB=0


## Redis 连接池
REDIS_MAX_RETRIES_PER_REQUEST=3
REDIS_RETRY_DELAY_ON_FAILURE=100

安全配置

跨域设置

## CORS 允许的源
CORS_ORIGINS=http://localhost:3000,http://localhost:5173,https://your-domain.com


## 域名白名单
DOMAIN_WHITELIST=localhost,127.0.0.1,your-domain.com


## 是否允许携带凭证
CORS_CREDENTIALS=true

安全策略

## 安全头配置
SECURITY_CSP_ENABLED=true
SECURITY_HSTS_ENABLED=true
SECURITY_NOOPEN_ENABLED=true


## 请求限制
RATE_LIMIT_MAX=1000
RATE_LIMIT_DURATION=900000


## 文件上传限制
UPLOAD_MAX_FILE_SIZE=10485760
UPLOAD_MAX_FILES=10

日志配置

日志级别

## 日志级别：DEBUG, INFO, WARN, ERROR
LOG_LEVEL=INFO


## 日志输出目录
LOG_DIR=./logs


## 日志文件大小限制（MB）
LOG_MAX_FILE_SIZE=50


## 日志文件保留天数
LOG_MAX_FILES=30

日志格式

## 日志格式：json, text
LOG_FORMAT=json


## 是否输出到控制台
LOG_CONSOLE=true


## 是否输出到文件
LOG_FILE=true

邮件配置

SMTP 设置

## 邮件服务配置
MAIL_HOST=smtp.qq.com
MAIL_PORT=465
MAIL_SECURE=true
MAIL_USER=your_email@qq.com
MAIL_PASS=your_email_password


## 发件人信息
MAIL_FROM_NAME=DoraCMS
MAIL_FROM_EMAIL=your_email@qq.com

邮件模板

## 邮件模板路径
MAIL_TEMPLATE_DIR=./app/view/email


## 默认邮件模板
MAIL_DEFAULT_TEMPLATE=default

文件存储配置

本地存储

## 文件上传路径
UPLOAD_PATH=./app/public/uploads


## 静态文件访问路径
STATIC_PATH=/public


## 允许的文件类型
UPLOAD_ALLOWED_TYPES=jpg,jpeg,png,gif,pdf,doc,docx

云存储配置

阿里云 OSS

## 阿里云 OSS 配置
OSS_REGION=oss-cn-hangzhou
OSS_ACCESS_KEY_ID=your_access_key_id
OSS_ACCESS_KEY_SECRET=your_access_key_secret
OSS_BUCKET=your_bucket_name
OSS_ENDPOINT=https://oss-cn-hangzhou.aliyuncs.com

腾讯云 COS

## 腾讯云 COS 配置
COS_SECRET_ID=your_secret_id
COS_SECRET_KEY=your_secret_key
COS_REGION=ap-guangzhou
COS_BUCKET=your_bucket_name

缓存配置

内存缓存

## 内存缓存配置
CACHE_MEMORY_MAX=100
CACHE_MEMORY_TTL=3600

Redis 缓存

## Redis 缓存配置
CACHE_REDIS_TTL=3600
CACHE_REDIS_KEY_PREFIX=doracms:cache:

第三方服务配置

搜索引擎

## 百度推送配置
BAIDU_PUSH_TOKEN=your_baidu_push_token
BAIDU_PUSH_SITE=https://your-domain.com


## Google Search Console
GOOGLE_SITE_VERIFICATION=your_verification_code

社交登录

## 微信登录配置
WECHAT_APP_ID=your_wechat_app_id
WECHAT_APP_SECRET=your_wechat_app_secret


## QQ 登录配置
QQ_APP_ID=your_qq_app_id
QQ_APP_KEY=your_qq_app_key

支付配置

## 微信支付配置
WECHAT_PAY_APP_ID=your_wechat_pay_app_id
WECHAT_PAY_MCH_ID=your_mch_id
WECHAT_PAY_KEY=your_pay_key


## 支付宝配置
ALIPAY_APP_ID=your_alipay_app_id
ALIPAY_PRIVATE_KEY=your_private_key
ALIPAY_PUBLIC_KEY=your_public_key

开发环境配置

开发模式设置

## 开发环境配置
NODE_ENV=development
DEBUG=true


## 热重载
HOT_RELOAD=true


## 开发工具
DEV_TOOLS=true


## API 文档
API_DOCS_ENABLED=true

调试配置

## 调试模式
DEBUG_MODE=true


## SQL 查询日志
SQL_DEBUG=true


## 性能监控
PERFORMANCE_MONITOR=true

生产环境配置

性能优化

## 生产环境配置
NODE_ENV=production
DEBUG=false


## 集群模式
EGG_WORKERS=4


## 缓存配置
CACHE_ENABLED=true
CACHE_TTL=3600


## 压缩配置
GZIP_ENABLED=true

安全加固

## 安全配置
SECURITY_ENABLED=true
HTTPS_ONLY=true


## 访问限制
IP_WHITELIST=your_admin_ip
ADMIN_PATH_PREFIX=/admin


## 会话安全
SESSION_SECURE=true
SESSION_HTTP_ONLY=true

Docker 环境配置

Docker Compose 配置

## docker-compose.yml
version: '3.8'
services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      - NODE_ENV=production
      - DATABASE_TYPE=mongodb
      - MONGODB_HOST=mongodb
    env_file:
      - .env
    depends_on:
      - mongodb
      - redis


  mongodb:
    image: mongo:7.0
    environment:
      - MONGO_INITDB_ROOT_USERNAME=${MONGODB_USERNAME}
      - MONGO_INITDB_ROOT_PASSWORD=${MONGODB_PASSWORD}
    volumes:
      - mongodb_data:/data/db


  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data


volumes:
  mongodb_data:
  redis_data:

容器环境变量

## Docker 特定配置
DOCKER_ENV=true
CONTAINER_NAME=doracms-app


## 健康检查
HEALTH_CHECK_ENABLED=true
HEALTH_CHECK_INTERVAL=30s

配置验证

配置检查脚本

#!/bin/bash
## check-config.sh


echo "检查配置文件..."


## 检查必需的环境变量
required_vars=(
  "NODE_ENV"
  "APP_KEYS"
  "DATABASE_TYPE"
)


for var in "${required_vars[@]}"; do
  if [ -z "${!var}" ]; then
    echo "错误: 环境变量 $var 未设置"
    exit 1
  fi
done


echo "配置检查通过"

配置测试

// test/config.test.js
const assert = require('assert');
const config = require('../config/config.default');


describe('配置测试', () => {
  it('应该有必需的配置项', () => {
    assert(config.keys);
    assert(config.database);
    assert(config.security);
  });


  it('数据库配置应该正确', () => {
    if (config.database.type === 'mongodb') {
      assert(config.database.mongodb);
      assert(config.database.mongodb.host);
    }
  });
});

常见问题

配置不生效

问题：修改配置后不生效

解决方案：

## 重启应用
pm2 restart doracms


## 或重新启动 Docker 容器
docker-compose restart

环境变量读取失败

问题：环境变量无法读取

解决方案：

## 检查文件路径
ls -la .env


## 检查文件权限
chmod 644 .env


## 检查文件格式（不要有 BOM）
file .env

数据库连接失败

问题：数据库连接配置错误

解决方案：

## 测试 MongoDB 连接
mongosh "mongodb://username:password@host:port/database"


## 测试 MariaDB 连接
mysql -h host -P port -u username -p database

配置最佳实践

安全建议

1. 敏感信息：不要将密码等敏感信息提交到版本控制
2. 密钥管理：使用强随机密钥，定期更换
3. 权限控制：限制配置文件的访问权限
4. 环境隔离：不同环境使用不同的配置

性能优化

1. 连接池：合理配置数据库连接池大小
2. 缓存策略：根据业务需求配置缓存
3. 日志级别：生产环境使用适当的日志级别
4. 资源限制：设置合理的资源使用限制

维护建议

1. 配置备份：定期备份配置文件
2. 版本管理：使用版本控制管理配置变更
3. 文档更新：及时更新配置文档
4. 监控告警：配置关键参数的监控告警