环境配置

DoraCMS 采用基于 .env 文件的环境变量配置方案，支持多环境配置和灵活的配置管理。

概览

DoraCMS 的配置系统分为三层：

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

这种分层设计的优势：

✅ 环境隔离 - 开发、测试、生产环境独立配置
✅ 安全性高 - 敏感信息通过环境变量管理，不提交到代码仓库
✅ 灵活配置 - 支持默认值、类型转换、数组配置
✅ 易于部署 - Docker、PM2、Kubernetes 等都可轻松适配

快速开始

1. 创建配置文件

复制环境配置模板：

bash

# 复制配置文件
cp server/env.example server/.env

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

2. 基础配置

编辑 .env 文件，配置基本信息：

bash

# 运行环境
NODE_ENV=development

# 服务端口
PORT=8080
HOSTNAME=127.0.0.1

# 数据库类型
DATABASE_TYPE=mongodb

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

# 应用密钥（必须修改）
APP_KEYS=your_app_secret_key
SESSION_SECRET=doracms_secret

3. 启动应用

bash

cd server
npm install
npm run dev

配置文件详解

环境变量文件优先级

DoraCMS 支持多个环境配置文件，按以下优先级加载：

.env.${NODE_ENV}.local （最高优先级）
   ↓
.env.${NODE_ENV}
   ↓
.env.local
   ↓
.env （最低优先级）

示例：

bash

# 开发环境
.env.development.local  # 本地开发配置（不提交到 Git）
.env.development        # 开发环境通用配置

# 生产环境
.env.production.local   # 生产环境本地配置
.env.production         # 生产环境通用配置

# 通用配置
.env.local             # 本地通用配置（不提交到 Git）
.env                   # 默认配置

配置项说明

服务器基础配置

配置项	类型	默认值	说明
`NODE_ENV`	String	development	运行环境：`development`/`production`
`PORT`	Number	8080	HTTP 服务端口
`HOSTNAME`	String	127.0.0.1	服务监听地址，`0.0.0.0` 表示所有接口
`EGG_WORKERS`	Number	1	Worker 进程数量，建议设置为 CPU 核心数

示例：

bash

# 开发环境
NODE_ENV=development
PORT=8080
HOSTNAME=127.0.0.1
EGG_WORKERS=1

# 生产环境
NODE_ENV=production
PORT=8080
HOSTNAME=0.0.0.0
EGG_WORKERS=4  # 4核服务器

Worker 进程数量建议

单核服务器：1-2 个 Worker
双核服务器：2-4 个 Worker
四核及以上：CPU 核心数
Docker 环境建议：EGG_WORKERS=1（由容器编排工具管理实例数）

安全配置

配置项	类型	必填	说明
`APP_KEYS`	String	是	应用密钥，用于 Cookie 签名
`SESSION_SECRET`	String	是	Session 会话密钥
`AUTH_COOKIE_NAME`	String	否	认证 Cookie 名称，默认 `doracms`
`ENCRYPT_KEY`	String	否	数据加密密钥，默认 `dora`
`JWT_SECRET`	String	是	JWT Token 签名密钥
`JWT_EXPIRES_IN`	String	否	JWT 过期时间，默认 `30d`

生成强随机密钥：

bash

# 方法1：使用 Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

# 方法2：使用 OpenSSL
openssl rand -hex 32

# 方法3：在线生成
# 访问：https://www.random.org/strings/

配置示例：

bash

# ⚠️ 生产环境必须修改为强随机字符串
APP_KEYS=f3a8b7c9d2e1f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9
SESSION_SECRET=a9b8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8
JWT_SECRET=c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2
JWT_EXPIRES_IN=30d

# 其他加密配置
AUTH_COOKIE_NAME=doracms
ENCRYPT_KEY=your_custom_encrypt_key

安全警告

生产环境必须修改默认密钥！ 使用默认密钥会导致严重的安全风险：

Session 被伪造
Cookie 被劫持
Token 被破解
数据被篡改

缓存配置

配置项	类型	默认值	说明
`CACHE_TYPE`	String	memory	缓存类型：`memory` 或 `redis`
`CACHE_DEFAULT_TTL`	Number	3600	缓存默认过期时间（秒）
`MEMORY_CACHE_MAX_SIZE`	Number	1000	内存缓存最大条目数

内存缓存配置（单机模式）：

bash

# 适用于小型项目、开发环境
CACHE_TYPE=memory
CACHE_DEFAULT_TTL=3600
MEMORY_CACHE_MAX_SIZE=1000

Redis 缓存配置（推荐生产环境）：

bash

# 适用于生产环境、集群部署
CACHE_TYPE=redis
CACHE_DEFAULT_TTL=7200

# Redis 连接配置
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=your_redis_password
REDIS_DB=0

缓存选择建议

内存缓存：适合单机部署、小流量场景
Redis 缓存：适合集群部署、高并发场景、需要持久化的场景

文件存储配置

配置项	类型	说明
`UPLOAD_PATH`	String	文件上传路径（绝对路径）
`STATIC_PATH`	String	静态资源路径（绝对路径）
`LOG_DIR`	String	日志文件目录（绝对路径）
`LOG_LEVEL`	String	日志级别

配置示例：

bash

# Linux/macOS
UPLOAD_PATH=/var/www/doracms/uploads
STATIC_PATH=/var/www/doracms/static
LOG_DIR=/var/log/doracms
LOG_LEVEL=INFO

# Windows
UPLOAD_PATH=C:/www/doracms/uploads
STATIC_PATH=C:/www/doracms/static
LOG_DIR=C:/logs/doracms
LOG_LEVEL=DEBUG

日志级别说明：

级别	说明	适用场景
`DEBUG`	详细调试信息	开发环境
`INFO`	一般信息	生产环境
`WARN`	警告信息	生产环境
`ERROR`	错误信息	生产环境

路径配置建议

使用绝对路径，避免相对路径导致的问题
确保应用进程有读写权限
生产环境建议使用独立的存储卷或云存储

第三方服务配置

配置项	类型	说明
`CDN_ORIGIN`	String	CDN 域名
`API_DOMAIN`	String	API 接口域名

配置示例：

bash

# 开发环境
CDN_ORIGIN=http://localhost:8080
API_DOMAIN=http://localhost:8080

# 生产环境
CDN_ORIGIN=https://cdn.your-domain.com
API_DOMAIN=https://api.your-domain.com

CORS 和安全配置

配置项	类型	说明
`CORS_ORIGINS`	Array	允许的前端域名（逗号分隔）
`DOMAIN_WHITELIST`	Array	白名单域名（逗号分隔）

配置示例：

bash

# 单个域名
CORS_ORIGINS=https://www.your-domain.com
DOMAIN_WHITELIST=https://www.your-domain.com

# 多个域名（用逗号分隔）
CORS_ORIGINS=https://www.your-domain.com,https://admin.your-domain.com,https://m.your-domain.com
DOMAIN_WHITELIST=www.your-domain.com,admin.your-domain.com,m.your-domain.com

# 开发环境（允许 localhost）
CORS_ORIGINS=http://localhost:8080,http://localhost:9527
DOMAIN_WHITELIST=localhost

CORS 配置注意事项

生产环境不要使用 * 通配符
确保包含所有需要访问的前端域名
协议（http/https）、域名、端口必须完全匹配

环境特定配置

DoraCMS 根据 NODE_ENV 加载不同的配置文件：

开发环境 (config.local.js)

javascript

module.exports = appInfo => {
  const config = {};

  // 开发环境日志级别
  config.logger = {
    level: 'DEBUG',
    consoleLevel: 'DEBUG',
  };

  // 开发环境 CORS（允许所有）
  config.cors = {
    origin: '*',
    allowMethods: 'GET,HEAD,PUT,POST,DELETE,PATCH,OPTIONS',
  };

  // 开发环境静态资源
  config.static = {
    maxAge: 0,  // 不缓存
  };

  return config;
};

生产环境 (config.prod.js)

javascript

module.exports = appInfo => {
  const config = {};

  // 生产环境日志级别
  config.logger = {
    level: 'INFO',
    consoleLevel: 'WARN',
  };

  // 生产环境 CORS（严格限制）
  config.cors = {
    origin: envConfig.CORS.ORIGINS,
    allowMethods: 'GET,HEAD,PUT,POST,DELETE,PATCH,OPTIONS',
    credentials: true,
  };

  // 生产环境静态资源（长缓存）
  config.static = {
    maxAge: 31536000,  // 1年
  };

  // 代理配置
  config.proxy = true;

  return config;
};

中间件配置

DoraCMS 内置了多个中间件，按顺序执行：

javascript

config.middleware = [
  'errorHandler',      // 统一错误处理
  'errorLogger',       // 错误日志记录
  'apiVersionLogger',  // API 版本标识
  'accessLogger',      // 访问日志记录
  'crossHeader',       // 跨域处理
  'compress',          // Gzip 压缩
  'authUserToken',     // 前台用户认证
  'authAdminToken',    // 后台管理员认证
  'spaFallback',       // SPA 路由回退
  'notfoundHandler',   // 404 处理
];

访问日志中间件配置

javascript

config.accessLogger = {
  // 是否启用（建议生产环境开启）
  enabled: true,

  // 排除的路径
  excludePaths: [
    '/health',
    '/ping',
    '/favicon.ico',
  ],

  // 排除的路径模式（正则）
  excludePatterns: [
    /^\/public\//,
    /^\/static\//,
    /\.(css|js|png|jpg)$/i,
  ],

  // 是否只记录慢请求
  logSlowRequests: true,

  // 慢请求阈值（毫秒）
  slowRequestThreshold: 1000,

  // 是否记录请求体
  logRequestBody: false,

  // 采样率（0-1，1表示100%记录）
  samplingRate: 1.0,
};

错误日志中间件配置

javascript

config.errorLogger = {
  // 是否启用
  enabled: true,

  // 是否记录堆栈
  logStackTrace: true,

  // 是否在严重错误时发送通知
  notifyOnCritical: true,

  // 严重错误的 HTTP 状态码
  criticalStatusCodes: [500, 502, 503, 504],

  // 通知配置
  notification: {
    email: {
      enabled: false,
      recipients: ['admin@example.com'],
    },
    dingtalk: {
      enabled: false,
      webhook: '',
    },
  },
};

配置最佳实践

1. 环境隔离

bash

# 开发环境 .env.development
NODE_ENV=development
PORT=8080
LOG_LEVEL=DEBUG
CACHE_TYPE=memory

# 生产环境 .env.production
NODE_ENV=production
PORT=8080
LOG_LEVEL=INFO
CACHE_TYPE=redis

2. 敏感信息保护

bash

# ✅ 正确：使用环境变量
APP_KEYS=${VAULT_APP_KEYS}
SESSION_SECRET=${VAULT_SESSION_SECRET}

# ❌ 错误：明文硬编码
APP_KEYS=my_secret_key

3. 配置验证

DoraCMS 在生产环境启动时会自动验证必需的环境变量：

javascript

// 必需的环境变量
const REQUIRED_ENV_VARS = [
  'MONGODB_HOST',
  'MONGODB_PORT',
  'MONGODB_DATABASE',
  'APP_KEYS',
  'SESSION_SECRET'
];

// 启动时验证
if (process.env.NODE_ENV === 'production') {
  validateRequiredEnvVars();
}

4. 默认值设置

javascript

// 使用默认值，避免配置缺失
const PORT = process.env.PORT || 8080;
const WORKERS = parseInt(process.env.EGG_WORKERS) || 1;
const CACHE_TYPE = process.env.CACHE_TYPE || 'memory';

5. 类型转换

javascript

// 数字类型
const PORT = parseInt(process.env.PORT) || 8080;
const TTL = parseInt(process.env.CACHE_DEFAULT_TTL) || 3600;

// 布尔类型
const ENABLED = process.env.REPOSITORY_ENABLED === 'true';

// 数组类型
const ORIGINS = process.env.CORS_ORIGINS.split(',').map(s => s.trim());

Docker 环境配置

使用 .env 文件

bash

# 复制配置文件
cp docker.env.example .env

# 修改配置
vim .env

# 启动容器
docker-compose up -d

使用环境变量注入

bash

# 通过命令行传递
docker run -e NODE_ENV=production \
           -e MONGODB_HOST=mongodb \
           -e APP_KEYS=your_keys \
           doracms:latest

# 通过 docker-compose.yml
services:
  app:
    environment:
      - NODE_ENV=production
      - MONGODB_HOST=mongodb
      - APP_KEYS=${APP_KEYS}

配置工具函数

DoraCMS 提供了一系列工具函数简化配置管理：

javascript

const envConfig = require('./config/env');

// 获取字符串配置
const cdnOrigin = envConfig.getEnv('CDN_ORIGIN', 'https://default-cdn.com');

// 获取数字配置
const port = envConfig.getNumberEnv('PORT', 8080);
const workers = envConfig.getNumberEnv('EGG_WORKERS', 1);

// 获取布尔配置
const repositoryEnabled = envConfig.getBoolEnv('REPOSITORY_ENABLED', false);

// 获取数组配置
const corsOrigins = envConfig.getArrayEnv('CORS_ORIGINS', ['http://localhost:8080']);

常见问题

1. 配置不生效怎么办？

检查顺序：

确认 .env 文件位置正确（server/.env）
确认环境变量名称拼写正确
重启应用（环境变量只在启动时加载）
检查配置文件优先级

bash

# 查看加载的配置
npm run dev -- --debug

# 检查环境变量
node -e "console.log(process.env)"

2. 如何切换环境？

bash

# 方法1：修改 NODE_ENV
export NODE_ENV=production
npm start

# 方法2：使用不同的 .env 文件
cp .env.production .env
npm start

# 方法3：使用 cross-env（跨平台）
npx cross-env NODE_ENV=production npm start

3. 如何在代码中访问配置？

javascript

// 在 Controller 中
class HomeController extends Controller {
  async index() {
    const { ctx, config } = this;
    
    // 访问配置
    const cdnOrigin = config.origin;
    const cacheType = config.cache.type;
    
    ctx.body = { cdnOrigin, cacheType };
  }
}

// 在 Service 中
class UserService extends Service {
  async getUser() {
    const { config } = this;
    
    // 访问环境配置
    const env = config.env;  // 'production' 或 'development'
    
    // 访问自定义配置
    const maxAge = config.userMaxAge;
  }
}

4. 如何添加自定义配置？

步骤 1：在 .env 中添加

bash

# 自定义配置
MY_CUSTOM_CONFIG=custom_value
MY_API_KEY=your_api_key

步骤 2：在 config/env.js 中解析

javascript

module.exports = {
  // ... 其他配置
  
  CUSTOM: {
    MY_CONFIG: getEnv('MY_CUSTOM_CONFIG'),
    API_KEY: getEnv('MY_API_KEY'),
  },
};

步骤 3：在 config/config.default.js 中使用

javascript

const envConfig = require('./env');

module.exports = appInfo => {
  const config = {};
  
  // 使用自定义配置
  config.myCustomConfig = envConfig.CUSTOM.MY_CONFIG;
  config.myApiKey = envConfig.CUSTOM.API_KEY;
  
  return config;
};

配置检查清单

部署前请检查以下配置项：

安全配置 ✅

[ ] 修改了默认的 APP_KEYS
[ ] 修改了默认的 SESSION_SECRET
[ ] 修改了默认的 JWT_SECRET
[ ] 数据库密码使用强密码
[ ] Redis 密码使用强密码

数据库配置 ✅

[ ] MongoDB 连接信息正确
[ ] MariaDB 连接信息正确（如果使用）
[ ] Redis 连接信息正确（如果使用）
[ ] 数据库用户权限正确

域名和 CORS ✅

[ ] CORS_ORIGINS 包含所有前端域名
[ ] DOMAIN_WHITELIST 配置正确
[ ] CDN_ORIGIN 配置正确
[ ] API_DOMAIN 配置正确

性能配置 ✅

[ ] EGG_WORKERS 设置合理
[ ] 缓存类型选择合理
[ ] 静态资源缓存配置
[ ] 日志级别设置合理

进一步学习

数据库配置 - 数据库连接和配置详解
Repository 模式 - Repository 模式配置
Egg.js 配置 - Egg.js 官方配置文档

小结

DoraCMS 的环境配置系统：

✅ 灵活多样 - 支持多环境、多文件、优先级管理
✅ 安全可靠 - 敏感信息环境变量化、配置验证
✅ 易于维护 - 配置集中管理、工具函数简化操作
✅ 生产就绪 - 内置最佳实践、Docker 友好

通过合理配置环境变量，你可以轻松管理不同环境的应用部署。

环境配置 ​

概览 ​

快速开始 ​

1. 创建配置文件 ​

2. 基础配置 ​

3. 启动应用 ​

配置文件详解 ​

环境变量文件优先级 ​

配置项说明 ​

服务器基础配置 ​

安全配置 ​

缓存配置 ​

文件存储配置 ​

第三方服务配置 ​

CORS 和安全配置 ​

环境特定配置 ​

开发环境 (config.local.js) ​

生产环境 (config.prod.js) ​

中间件配置 ​

访问日志中间件配置 ​

错误日志中间件配置 ​

配置最佳实践 ​

1. 环境隔离 ​

2. 敏感信息保护 ​

3. 配置验证 ​

4. 默认值设置 ​

5. 类型转换 ​

Docker 环境配置 ​

使用 .env 文件 ​

使用环境变量注入 ​

配置工具函数 ​

常见问题 ​

1. 配置不生效怎么办？ ​

2. 如何切换环境？ ​

3. 如何在代码中访问配置？ ​

4. 如何添加自定义配置？ ​

配置检查清单 ​

安全配置 ✅ ​

数据库配置 ✅ ​

域名和 CORS ✅ ​

性能配置 ✅ ​

进一步学习 ​

小结 ​

环境配置

概览

快速开始

1. 创建配置文件

2. 基础配置

3. 启动应用

配置文件详解

环境变量文件优先级

配置项说明

服务器基础配置

安全配置

缓存配置

文件存储配置

第三方服务配置

CORS 和安全配置

环境特定配置

开发环境 (config.local.js)

生产环境 (config.prod.js)

中间件配置

访问日志中间件配置

错误日志中间件配置

配置最佳实践

1. 环境隔离

2. 敏感信息保护

3. 配置验证

4. 默认值设置

5. 类型转换

Docker 环境配置

使用 .env 文件

使用环境变量注入

配置工具函数

常见问题

1. 配置不生效怎么办？

2. 如何切换环境？

3. 如何在代码中访问配置？

4. 如何添加自定义配置？

配置检查清单

安全配置 ✅

数据库配置 ✅

域名和 CORS ✅

性能配置 ✅

进一步学习

小结