DoraCMS开发文档

主题

CLI 工具 ​

DoraCMS CLI 是一个强大的命令行工具，用于快速创建和配置 DoraCMS 项目。它提供了交互式的项目初始化流程，支持多种项目类型、数据库选择和模块配置。

安装 ​

全局安装（推荐） ​

bash
# 使用 npm
npm install -g doracms-cli

# 使用 pnpm（推荐）
pnpm add -g doracms-cli

# 使用 yarn
yarn global add doracms-cli

验证安装 ​

bash
# 查看版本
doracms --version

# 查看帮助
doracms --help

快速开始 ​

交互式创建项目 ​

最简单的方式是使用交互式命令，CLI 会引导你完成所有配置：

bash
doracms create my-project

CLI 会依次询问：

  1. 项目类型 - 选择适合你的项目模板
  2. 数据库 - MongoDB、MariaDB 或双数据库支持
  3. 包管理器 - pnpm、npm 或 yarn
  4. 示例数据 - 是否包含演示数据
  5. 模块选择 - 选择需要的功能模块
  6. 插件配置 - 是否启用 AI 助手等插件

使用默认配置快速创建 ​

如果你想快速开始，可以使用 --yes 选项跳过所有交互：

bash
doracms create my-project --yes

这将使用以下默认配置：

  • 项目类型：完整全栈项目
  • 数据库：MongoDB
  • 包管理器：pnpm
  • 包含示例数据
  • 启用所有推荐模块

命令详解 ​

create 命令 ​

创建新的 DoraCMS 项目。

bash
doracms create <project-name> [options]

参数 ​

  • <project-name> - 项目名称（必需）

选项 ​

选项简写说明可选值
--template-t项目模板类型fullstack, backend-only, user-separated
--database-d数据库类型mongodb, mariadb, both
--package-manager-p包管理器pnpm, npm, yarn
--skip-install-跳过依赖安装-
--skip-git-跳过 Git 初始化-
--yes-y使用默认配置-

示例 ​

bash
# 创建完整全栈项目，使用 MongoDB
doracms create my-cms --template fullstack --database mongodb

# 创建纯后端 API，使用 MariaDB
doracms create my-api --template backend-only --database mariadb

# 创建用户端项目，跳过依赖安装
doracms create my-blog --template user-separated --skip-install

# 使用默认配置快速创建
doracms create quick-start --yes

项目类型 ​

1. 完整全栈项目 (fullstack) ​

包含管理后台、用户中心和完整后端 API 的全功能项目。

适用场景：

  • 企业内部 CMS 系统
  • 学习和二次开发
  • 完整功能演示

包含内容：

  • ✅ 管理后台（Admin Center）
  • ✅ 用户中心（User Center）
  • ✅ 后端 API（Server）
  • ✅ 所有核心模块
  • ✅ 推荐业务模块

启动命令：

bash
cd my-project
pnpm run dev:all

访问地址：

2. 纯后端 API (backend-only) ​

Headless CMS，只提供 RESTful API，不包含前端应用。

适用场景：

  • 移动应用后端
  • 小程序后端
  • 第三方系统集成
  • 微服务架构

包含内容：

  • ✅ 后端 API（Server）
  • ✅ Swagger API 文档
  • ✅ 核心模块
  • ✅ 可选业务模块

启动命令：

bash
cd my-api
pnpm run dev:server

访问地址：

3. 前后端分离 - 用户端 (user-separated) ​

包含用户中心前端和完整后端 API，适合面向用户的内容展示网站。

适用场景：

  • 博客网站
  • 新闻门户
  • 社区论坛
  • 内容展示平台

包含内容：

  • ✅ 用户中心（User Center）
  • ✅ 后端 API（Server）
  • ✅ 内容管理模块
  • ✅ 评论系统
  • ✅ 邮件通知

启动命令：

bash
cd my-blog
pnpm run dev

访问地址：

模块系统 ​

DoraCMS 采用模块化架构，你可以根据需求灵活选择功能模块。

核心模块（必需） ​

这些模块是系统运行的基础，会自动包含在所有项目中：

模块说明
用户管理前台用户认证和管理
管理员管理后台管理员认证和管理
角色权限角色和权限管理
菜单管理导航菜单配置
系统配置系统配置管理
文件上传文件上传和管理
API KeyAPI Key 管理
邮件通知邮件发送和模板

业务模块（可选） ​

根据项目需求选择：

模块说明推荐场景
内容管理文章、分类、标签管理博客、新闻站、内容平台
评论系统用户评论和互动社区、论坛、博客
广告管理广告位和广告内容商业网站、门户站
模板管理主题模板管理多主题网站
Webhook事件通知和集成第三方集成、自动化
插件系统插件管理和扩展可扩展平台

模块推荐策略 ​

CLI 会根据项目类型自动推荐合适的模块组合：

完整全栈项目：

  • ✅ 所有核心模块
  • ✅ 所有业务模块（可选择性禁用）

纯后端 API：

  • ✅ 所有核心模块
  • ✅ 内容管理
  • ✅ Webhook
  • ⚪ 其他模块按需选择

用户端项目：

  • ✅ 所有核心模块
  • ✅ 内容管理
  • ✅ 评论系统
  • ✅ 邮件通知
  • ⚪ 其他模块按需选择

后续调整模块 ​

创建项目后，你可以随时调整模块配置：

  1. 编辑 server/config/modules.config.js 文件
  2. 修改对应模块的 enabled 属性
  3. 重启应用使配置生效
javascript
// server/config/modules.config.js
module.exports = {
  business: {
    // 启用广告模块
    ads: {
      enabled: true,  // 改为 true 启用
      // ...
    },
    // 禁用插件模块
    plugin: {
      enabled: false,  // 改为 false 禁用
      // ...
    },
  },
};

插件配置 ​

AI 助手插件 ​

CLI 支持配置 AI 助手插件，用于内容生成和智能辅助功能。

功能特性：

  • 🤖 AI 内容生成
  • 📝 智能写作辅助
  • 🔍 内容优化建议
  • 🎨 标题和摘要生成

启用方式：

在创建项目时，CLI 会询问是否启用 AI 助手。如果选择启用，会自动：

  • 添加 AI 相关的 Repository（AIModel、AIUsageLog、PromptTemplate）
  • 配置 AI 助手插件
  • 生成相关的数据库表结构

后续配置：

创建项目后，需要在 .env 文件中配置 AI 服务的 API Key：

bash
# AI 助手配置
AI_PROVIDER=openai  # 或其他提供商
AI_API_KEY=your-api-key-here
AI_MODEL=gpt-3.5-turbo

数据库配置 ​

MongoDB ​

特点：

  • 文档型数据库
  • 灵活的数据结构
  • 适合快速开发
  • 性能优秀

配置示例：

bash
# MongoDB 配置
MONGODB_HOST=localhost          # MongoDB 主机地址
MONGODB_PORT=27017              # MongoDB 端口
MONGODB_USERNAME=your_username  # MongoDB 用户名
MONGODB_PASSWORD=your_password  # MongoDB 密码
MONGODB_DATABASE=doracms        # 数据库名称
MONGODB_AUTH_SOURCE=admin       # 认证数据库

MariaDB ​

特点：

  • 关系型数据库
  • 严格的数据结构
  • 事务支持完善
  • 企业级稳定性

配置示例：

bash
# MariaDB 配置
MARIADB_HOST=localhost          # MariaDB 主机地址
MARIADB_PORT=3306               # MariaDB 端口
MARIADB_DATABASE=doracms        # 数据库名称
MARIADB_USERNAME=root           # MariaDB 用户名
MARIADB_PASSWORD=your_password  # MariaDB 密码

双数据库支持 ​

特点：

  • 同时支持 MongoDB 和 MariaDB
  • 可在运行时切换
  • 适合数据库迁移场景

配置示例：

bash
# MongoDB 配置
MONGODB_HOST=localhost
MONGODB_PORT=27017
MONGODB_USERNAME=your_username
MONGODB_PASSWORD=your_password
MONGODB_DATABASE=doracms
MONGODB_AUTH_SOURCE=admin

# MariaDB 配置
MARIADB_HOST=localhost
MARIADB_PORT=3306
MARIADB_DATABASE=doracms
MARIADB_USERNAME=root
MARIADB_PASSWORD=your_password

项目启动 ​

1. 配置环境变量 ​

创建项目后，CLI 会自动生成 .env 文件，包含默认配置。在启动项目前，需要进入 server 目录修改环境变量配置：

bash
cd my-project/server
nano .env  # 或使用其他编辑器

必需配置项：

MongoDB 配置 ​

bash
# =================================
# 数据库配置
# =================================
MONGODB_HOST=localhost          # MongoDB 主机地址
MONGODB_PORT=27017              # MongoDB 端口
MONGODB_USERNAME=your_username  # MongoDB 用户名
MONGODB_PASSWORD=your_password  # MongoDB 密码
MONGODB_DATABASE=doracms        # 数据库名称
MONGODB_AUTH_SOURCE=admin       # 认证数据库

MariaDB 配置 ​

bash
# MariaDB 配置
MARIADB_HOST=localhost          # MariaDB 主机地址
MARIADB_PORT=3306               # MariaDB 端口
MARIADB_DATABASE=doracms        # 数据库名称
MARIADB_USERNAME=root           # MariaDB 用户名
MARIADB_PASSWORD=your_password  # MariaDB 密码

Redis 配置（可选） ​

bash
# Redis 配置（本地开发可选）
REDIS_HOST=localhost            # Redis 主机地址
REDIS_PORT=6379                 # Redis 端口
REDIS_PASSWORD=                 # Redis 密码（如果有）
REDIS_DB=0                      # Redis 数据库编号

其他配置 ​

  • 应用端口（可选）
  • AI 助手配置（如果启用）
  • JWT 密钥等安全配置

注意

请确保在执行 pnpm run dev 之前完成环境变量配置，否则应用将无法正常连接数据库。

2. 安装依赖（如果跳过了） ​

bash
pnpm install

3. 启动开发服务器 ​

根据项目类型选择启动命令：

bash
# 完整全栈项目
pnpm run dev:all

# 纯后端 API
pnpm run dev:server

# 用户端项目
pnpm run dev

4. 访问应用 ​

根据控制台输出的地址访问应用，默认地址：

本地开发 CLI ​

如果你想参与 CLI 工具的开发或测试：

克隆仓库 ​

bash
git clone https://github.com/doramart/doracms.git
cd doracms/packages/cli

安装依赖 ​

bash
pnpm install

开发模式 ​

bash
# 监听文件变化，自动重新构建
pnpm dev

本地测试 ​

bash
# 方式 1: 直接运行（推荐）
node bin/doracms.js create test-project

# 方式 2: 链接到全局
pnpm link --global
doracms create test-project

# 取消链接
pnpm unlink --global

构建 ​

bash
pnpm build

代码检查 ​

bash
# ESLint 检查
pnpm lint

# 代码格式化
pnpm format

# 运行测试
pnpm test

常见问题 ​

Q: 如何更新 CLI？ ​

bash
# npm
npm update -g doracms-cli

# pnpm
pnpm update -g doracms-cli

# yarn
yarn global upgrade doracms-cli

Q: 创建项目失败怎么办？ ​

检查以下几点：

  1. 项目名称是否有效（不能包含特殊字符）
  2. 目标目录是否已存在且不为空
  3. 是否有足够的磁盘空间
  4. 网络连接是否正常（用于安装依赖）
  5. Node.js 版本是否 >= 18.0.0

Q: 如何更改已创建项目的数据库？ ​

编辑 server 目录下的 .env 文件，修改数据库配置。如果从 MongoDB 切换到 MariaDB，需要配置相应的 MariaDB 连接信息：

bash
# MariaDB 配置
MARIADB_HOST=localhost
MARIADB_PORT=3306
MARIADB_DATABASE=doracms
MARIADB_USERNAME=root
MARIADB_PASSWORD=your_password

Q: 如何添加或删除模块？ ​

编辑 server/config/modules.config.js 文件，修改对应模块的 enabled 属性，然后重启应用。

Q: CLI 支持哪些 Node.js 版本？ ​

DoraCMS CLI 要求 Node.js >= 18.0.0。建议使用 LTS 版本。

Q: 可以在现有项目中使用 CLI 吗？ ​

CLI 主要用于创建新项目。如果要在现有项目中添加功能，建议手动配置或参考生成的项目结构。

Q: 如何自定义项目模板？ ​

CLI 的模板位于 packages/cli/templates 目录。你可以：

  1. Fork DoraCMS 仓库
  2. 修改模板文件
  3. 本地构建和测试
  4. 提交 PR 贡献你的模板

获取帮助 ​

命令行帮助 ​

bash
# 查看所有命令
doracms --help

# 查看 create 命令帮助
doracms create --help

# 查看版本
doracms --version

在线资源 ​

社区支持 ​

  • GitHub Issues：报告 Bug 和功能建议
  • GitHub Discussions：技术讨论和问答
  • QQ 群：加入 DoraCMS 开发者社区

下一步 ​