环境配置详解
# 环境配置详解
## 配置文件概述
DoraCMS 采用分层配置系统，通过环境变量和配置文件实现灵活的环境管理。
### 配置文件层次
```
.env 文件（环境变量）
↓
config/env.js（环境配置解析）
↓
config/config.default.js（应用配置）
↓
config/config.{env}.js（环境特定配置）
```
### 环境变量优先级
```bash
.env.${NODE_ENV}.local # 最高优先级
.env.${NODE_ENV} # 环境特定配置
.env.local # 本地配置（不提交到版本控制）
.env # 默认配置
```
## 基础环境配置
### 创建配置文件
```bash
# 复制配置模板
cp server/env.example server/.env
# 或使用 Docker 配置
cp docker.env.example .env
```
### 核心配置项
#### 运行环境
```env
# 运行环境：development, production, test
NODE_ENV=development
# 服务器配置
PORT=8080
HOSTNAME=127.0.0.1
# Worker 进程数（生产环境建议设置为 CPU 核心数）
EGG_WORKERS=1
```
#### 应用安全
```env
# 应用密钥（必须修改为随机字符串）
APP_KEYS=your_random_secret_key_32_chars_long
# 会话密钥
SESSION_SECRET=your_session_secret_key
# JWT 密钥
JWT_SECRET=your_jwt_secret_key
```
**生成安全密钥**：
```bash
# 使用 Node.js 生成
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# 使用 OpenSSL 生成
openssl rand -hex 32
# 使用在线工具
# https://www.random.org/strings/
```
## 数据库配置
### MongoDB 配置
```env
# 数据库类型
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 配置
```env
# 数据库类型
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 配置
```env
# 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
```
## 安全配置
### 跨域设置
```env
# 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
```
### 安全策略
```env
# 安全头配置
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
```
## 日志配置
### 日志级别
```env
# 日志级别：DEBUG, INFO, WARN, ERROR
LOG_LEVEL=INFO
# 日志输出目录
LOG_DIR=./logs
# 日志文件大小限制（MB）
LOG_MAX_FILE_SIZE=50
# 日志文件保留天数
LOG_MAX_FILES=30
```
### 日志格式
```env
# 日志格式：json, text
LOG_FORMAT=json
# 是否输出到控制台
LOG_CONSOLE=true
# 是否输出到文件
LOG_FILE=true
```
## 邮件配置
### SMTP 设置
```env
# 邮件服务配置
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
```
### 邮件模板
```env
# 邮件模板路径
MAIL_TEMPLATE_DIR=./app/view/email
# 默认邮件模板
MAIL_DEFAULT_TEMPLATE=default
```
## 文件存储配置
### 本地存储
```env
# 文件上传路径
UPLOAD_PATH=./app/public/uploads
# 静态文件访问路径
STATIC_PATH=/public
# 允许的文件类型
UPLOAD_ALLOWED_TYPES=jpg,jpeg,png,gif,pdf,doc,docx
```
### 云存储配置
#### 阿里云 OSS
```env
# 阿里云 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
```env
# 腾讯云 COS 配置
COS_SECRET_ID=your_secret_id
COS_SECRET_KEY=your_secret_key
COS_REGION=ap-guangzhou
COS_BUCKET=your_bucket_name
```
## 缓存配置
### 内存缓存
```env
# 内存缓存配置
CACHE_MEMORY_MAX=100
CACHE_MEMORY_TTL=3600
```
### Redis 缓存
```env
# Redis 缓存配置
CACHE_REDIS_TTL=3600
CACHE_REDIS_KEY_PREFIX=doracms:cache:
```
## 第三方服务配置
### 搜索引擎
```env
# 百度推送配置
BAIDU_PUSH_TOKEN=your_baidu_push_token
BAIDU_PUSH_SITE=https://your-domain.com
# Google Search Console
GOOGLE_SITE_VERIFICATION=your_verification_code
```
### 社交登录
```env
# 微信登录配置
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
```
### 支付配置
```env
# 微信支付配置
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
```
## 开发环境配置
### 开发模式设置
```env
# 开发环境配置
NODE_ENV=development
DEBUG=true
# 热重载
HOT_RELOAD=true
# 开发工具
DEV_TOOLS=true
# API 文档
API_DOCS_ENABLED=true
```
### 调试配置
```env
# 调试模式
DEBUG_MODE=true
# SQL 查询日志
SQL_DEBUG=true
# 性能监控
PERFORMANCE_MONITOR=true
```
## 生产环境配置
### 性能优化
```env
# 生产环境配置
NODE_ENV=production
DEBUG=false
# 集群模式
EGG_WORKERS=4
# 缓存配置
CACHE_ENABLED=true
CACHE_TTL=3600
# 压缩配置
GZIP_ENABLED=true
```
### 安全加固
```env
# 安全配置
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 配置
```yaml
# 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:
```
### 容器环境变量
```env
# Docker 特定配置
DOCKER_ENV=true
CONTAINER_NAME=doracms-app
# 健康检查
HEALTH_CHECK_ENABLED=true
HEALTH_CHECK_INTERVAL=30s
```
## 配置验证
### 配置检查脚本
```bash
#!/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 "配置检查通过"
```
### 配置测试
```javascript
// 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);
}
});
});
```
## 常见问题
### 配置不生效
**问题**：修改配置后不生效
**解决方案**：
```bash
# 重启应用
pm2 restart doracms
# 或重新启动 Docker 容器
docker-compose restart
```
### 环境变量读取失败
**问题**：环境变量无法读取
**解决方案**：
```bash
# 检查文件路径
ls -la .env
# 检查文件权限
chmod 644 .env
# 检查文件格式（不要有 BOM）
file .env
```
### 数据库连接失败
**问题**：数据库连接配置错误
**解决方案**：
```bash
# 测试 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. **监控告警**：配置关键参数的监控告警