数据库配置

DoraCMS 支持双数据库架构，可以选择 MongoDB 或 MariaDB 作为数据存储，并支持 Redis 作为缓存层。

概览

DoraCMS 的数据库支持特性：

• 🗄️ 双数据库支持 - MongoDB（文档型）和 MariaDB（关系型）
• 🔄 无缝切换 - 通过 Repository 模式统一数据访问层
• ⚡ Redis 缓存 - 可选的高性能缓存支持
• 🔐 连接池管理 - 自动管理数据库连接
• 🛡️ 安全认证 - 支持用户名密码认证

---

数据库选择

MongoDB vs MariaDB

特性	MongoDB	MariaDB
类型	文档型（NoSQL）	关系型（SQL）
性能	读写性能高	事务性能好
扩展性	水平扩展容易	垂直扩展为主
事务支持	支持（4.0+）	完整的 ACID 事务
查询语言	MongoDB Query Language	标准 SQL
适用场景	文档存储、快速迭代	复杂关系、数据一致性
学习曲线	较简单	需要 SQL 知识

推荐选择：

• 📄 MongoDB：适合快速开发、文档型数据、读多写少场景
• 🔗 MariaDB：适合复杂关系、事务要求高、数据一致性要求高的场景

---

MongoDB 配置

基础配置

在 .env 文件中配置 MongoDB 连接信息：

# MongoDB 数据库配置
MONGODB_HOST=127.0.0.1
MONGODB_PORT=27017
MONGODB_USERNAME=your_username
MONGODB_PASSWORD=your_password
MONGODB_DATABASE=doracms3
MONGODB_AUTH_SOURCE=admin

配置项说明

配置项	类型	默认值	说明
MONGODB_HOST	String	127.0.0.1	MongoDB 服务器地址
MONGODB_PORT	Number	27017	MongoDB 服务端口
MONGODB_USERNAME	String	-	数据库用户名
MONGODB_PASSWORD	String	-	数据库密码
MONGODB_DATABASE	String	doracms3	数据库名称
MONGODB_AUTH_SOURCE	String	admin	认证数据库（用于用户验证）
MONGODB_ROOT_USERNAME	String	admin	Root 用户（仅用于初始化）
MONGODB_ROOT_PASSWORD	String	-	Root 密码（仅用于初始化）

连接字符串

DoraCMS 会自动构建 MongoDB 连接字符串：

// 无认证
mongodb://127.0.0.1:27017/doracms3

// 有认证
mongodb://username:password@127.0.0.1:27017/doracms3?authSource=admin

高级配置

在 config/config.default.js 中可以配置更多选项：

config.mongoose = {
  client: {
    url: envConfig.MONGODB.URL,
    options: {
      useNewUrlParser: true,
      useUnifiedTopology: true,
      // 连接超时（毫秒）
      serverSelectionTimeoutMS: 5000,
      // Socket 超时（毫秒）
      socketTimeoutMS: 45000,
      // 连接池大小
      maxPoolSize: 10,
      minPoolSize: 5,
      // 心跳频率（毫秒）
      heartbeatFrequencyMS: 10000,
    },
  },
};

连接池配置

// 生产环境推荐配置
config.mongoose = {
  client: {
    url: envConfig.MONGODB.URL,
    options: {
      maxPoolSize: 50,        // 最大连接数
      minPoolSize: 10,        // 最小连接数
      maxIdleTimeMS: 30000,   // 空闲连接超时
      waitQueueTimeoutMS: 10000, // 等待连接超时
    },
  },
};

---

MariaDB 配置

基础配置

在 .env 文件中配置 MariaDB 连接信息：

# MariaDB 数据库配置
MARIADB_HOST=127.0.0.1
MARIADB_PORT=3307
MARIADB_DATABASE=doracms3
MARIADB_USERNAME=root
MARIADB_PASSWORD=123456
MARIADB_TABLE_PREFIX=dora_

配置项说明

配置项	类型	默认值	说明
MARIADB_HOST	String	127.0.0.1	MariaDB 服务器地址
MARIADB_PORT	Number	3307	MariaDB 服务端口
MARIADB_USERNAME	String	root	数据库用户名
MARIADB_PASSWORD	String	-	数据库密码
MARIADB_DATABASE	String	doracms3	数据库名称
MARIADB_TABLE_PREFIX	String	dora_	表前缀
MARIADB_ROOT_PASSWORD	String	-	Root 密码（仅用于初始化）

Sequelize 配置

DoraCMS 使用 Sequelize ORM 访问 MariaDB：

config.repository = {
  mariadb: {
    sequelize: {
      dialect: 'mysql',
      host: envConfig.MARIADB.HOST,
      port: envConfig.MARIADB.PORT,
      database: envConfig.MARIADB.DATABASE,
      username: envConfig.MARIADB.USERNAME,
      password: envConfig.MARIADB.PASSWORD,
      
      // 连接池配置
      pool: {
        max: 10,       // 最大连接数
        min: 0,        // 最小连接数
        acquire: 30000, // 获取连接超时（毫秒）
        idle: 10000,   // 空闲连接超时（毫秒）
      },
      
      // 关闭 SQL 日志（生产环境）
      logging: false,
      
      // 时区设置
      timezone: '+08:00',
      
      // 字符集
      define: {
        charset: 'utf8mb4',
        collate: 'utf8mb4_unicode_ci',
      },
    },
    
    // 表前缀
    tablePrefix: envConfig.MARIADB.TABLE_PREFIX,
  },
};

连接池优化

// 高并发场景优化
pool: {
  max: 50,              // 增加最大连接数
  min: 10,              // 保持最小连接
  acquire: 60000,       // 延长获取超时
  idle: 30000,          // 延长空闲超时
  evict: 10000,         // 连接回收间隔
}

// 低并发场景优化
pool: {
  max: 10,
  min: 2,
  acquire: 30000,
  idle: 10000,
}

---

Redis 配置

基础配置

在 .env 文件中配置 Redis 连接信息：

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

配置项说明

配置项	类型	默认值	说明
REDIS_HOST	String	127.0.0.1	Redis 服务器地址
REDIS_PORT	Number	6379	Redis 服务端口
REDIS_PASSWORD	String	-	Redis 密码（可选）
REDIS_DB	Number	0	Redis 数据库编号 (0-15)

启用 Redis 缓存

# 在 .env 中启用 Redis 缓存
CACHE_TYPE=redis
CACHE_DEFAULT_TTL=7200

Redis 配置详解

config.redis = {
  client: {
    port: envConfig.REDIS.PORT,
    host: envConfig.REDIS.HOST,
    password: envConfig.REDIS.PASSWORD || undefined,
    db: envConfig.REDIS.DB,
    
    // 重试策略
    retryStrategy(times) {
      const delay = Math.min(times * 50, 2000);
      return delay;
    },
    
    // 连接超时
    connectTimeout: 10000,
    
    // 命令执行超时
    commandTimeout: 5000,
    
    // 启用离线队列
    enableOfflineQueue: true,
    
    // 启用准备检查
    enableReadyCheck: true,
  },
};

Redis 集群配置

config.redis = {
  client: {
    sentinels: [
      { host: '127.0.0.1', port: 26379 },
      { host: '127.0.0.1', port: 26380 },
      { host: '127.0.0.1', port: 26381 },
    ],
    name: 'mymaster',
    password: envConfig.REDIS.PASSWORD,
    db: envConfig.REDIS.DB,
  },
};

---

数据库切换

切换到 MariaDB

步骤 1：修改配置

# .env
DATABASE_TYPE=mariadb
REPOSITORY_ENABLED=true

步骤 2：配置 MariaDB 连接

MARIADB_HOST=127.0.0.1
MARIADB_PORT=3307
MARIADB_DATABASE=doracms3
MARIADB_USERNAME=root
MARIADB_PASSWORD=123456

步骤 3：数据迁移（可选）

如果需要从 MongoDB 迁移数据到 MariaDB：

# 使用内置迁移工具
npm run migrate:mongo-to-mariadb

切换回 MongoDB

步骤 1：修改配置

# .env
DATABASE_TYPE=mongodb
REPOSITORY_ENABLED=false

步骤 2：配置 MongoDB 连接

MONGODB_HOST=127.0.0.1
MONGODB_PORT=27017
MONGODB_DATABASE=doracms3

---

Repository 模式

什么是 Repository 模式？

Repository 模式是一个数据访问抽象层，它：

• 🔄 统一了 MongoDB 和 MariaDB 的数据访问接口
• 🎯 隔离了业务逻辑和数据存储细节
• 🔀 支持无缝切换数据库

启用 Repository 模式

# .env
REPOSITORY_ENABLED=true

Repository 配置

config.repository = {
  // 数据库类型
  databaseType: envConfig.REPOSITORY.DATABASE_TYPE, // 'mongodb' 或 'mariadb'
  
  // 是否启用 Repository 模式
  enabled: envConfig.REPOSITORY.ENABLED,
  
  // Repository 缓存配置
  cache: {
    enabled: true,
    maxSize: 1000,           // 最大缓存实例数
    ttl: 60 * 60 * 1000,     // 缓存生存时间（1小时）
  },
  
  // 数据转换配置
  transformer: {
    enablePrimaryKeyMapping: true,   // 主键映射（_id <-> id）
    enableTimeFormatting: true,      // 时间格式化
    timeFormat: 'YYYY-MM-DD HH:mm:ss',
    keepOriginalFields: true,        // 保留原始字段（向后兼容）
  },
  
  // 支持的实体列表
  supportedEntities: [
    'SystemConfig',
    'User',
    'Admin',
    'Content',
    // ... 其他实体
  ],
};

---

常见问题

1. MongoDB 连接失败

问题： MongoNetworkError: failed to connect to server

解决方案：

# 1. 检查 MongoDB 是否启动
sudo systemctl status mongod

# 2. 检查端口是否监听
netstat -tuln | grep 27017

# 3. 检查防火墙
sudo ufw allow 27017

# 4. 检查配置文件
cat /etc/mongod.conf

# 5. 查看日志
tail -f /var/log/mongodb/mongod.log

2. MariaDB 认证失败

问题： ER_ACCESS_DENIED_ERROR: Access denied for user

解决方案：

# 1. 重置 root 密码
sudo mysql_secure_installation

# 2. 检查用户权限
mysql -u root -p
SHOW GRANTS FOR 'doracms'@'%';

# 3. 重新授权
GRANT ALL PRIVILEGES ON doracms3.* TO 'doracms'@'%';
FLUSH PRIVILEGES;

3. Redis 连接超时

问题： ReplyError: NOAUTH Authentication required

解决方案：

# 1. 检查 Redis 是否启动
redis-cli ping

# 2. 使用密码连接
redis-cli -a your_password

# 3. 检查配置
cat /etc/redis/redis.conf | grep requirepass

# 4. 禁用保护模式（仅开发环境）
redis-cli CONFIG SET protected-mode no

4. 如何选择数据库？

选择 MongoDB：

• ✅ 文档型数据模型
• ✅ 快速迭代开发
• ✅ 读多写少场景
• ✅ 水平扩展需求

选择 MariaDB：

• ✅ 复杂的关系查询
• ✅ 事务要求高
• ✅ 数据一致性要求高
• ✅ 已有 SQL 经验

---

数据库迁移

MongoDB 到 MariaDB

# 使用内置迁移工具
npm run migrate:mongo-to-mariadb

# 或手动迁移
node scripts/migrate-database.js

MariaDB 到 MongoDB

# 使用内置迁移工具
npm run migrate:mariadb-to-mongo

---

进一步学习

• MongoDB 官方文档
• MariaDB 官方文档
• Redis 官方文档
• Sequelize 文档
• Mongoose 文档

---

小结

DoraCMS 的数据库配置系统：

✅ 双数据库支持 - MongoDB 和 MariaDB 任选
✅ 无缝切换 - 通过 Repository 模式统一接口
✅ 高性能缓存 - Redis 可选支持
✅ 安全可靠 - 完善的认证和权限管理
✅ 易于扩展 - 连接池、索引、查询优化

通过合理配置数据库，你可以构建高性能、高可用的 CMS 系统。