安装与部署

环境要求

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

最低要求: Node.js 14.0.0
推荐版本: Node.js 18.20.0+
最新测试: Node.js 20.x

如果你使用的是旧版本，建议使用 nvm 升级：

bash

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 安装 Node.js 18
nvm install 18
nvm use 18
nvm alias default 18

Q: 必须使用 pnpm 吗？可以用 npm 或 yarn 吗？

推荐使用 pnpm: 项目采用 monorepo 架构，pnpm 对 workspace 支持最好
可以使用 npm: 但某些脚本可能需要调整
不推荐 yarn: 兼容性可能有问题

安装 pnpm：

bash

npm install -g pnpm

Q: 支持哪些操作系统？

✅ macOS 10.15+
✅ Ubuntu 18.04+
✅ CentOS 7+
✅ Windows 10+ (推荐使用 WSL2)

Windows 用户建议使用 WSL2 或 Docker。

CLI 工具

Q: 如何安装 DoraCMS CLI？

bash

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

# 使用 npm
npm install -g doracms-cli

# 验证安装
doracms --version

详细使用说明请查看 CLI 工具文档。

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

A: 检查以下几点：

1. 项目名称是否有效

bash

# ✅ 有效的项目名称
doracms create my-project
doracms create my-cms-app

# ❌ 无效的项目名称
doracms create My-Project    # 不能包含大写字母
doracms create my project    # 不能包含空格
doracms create @my/project   # 不能包含特殊字符

2. 目标目录是否已存在

bash

# 删除已存在的目录
rm -rf my-project

# 或使用不同的项目名称
doracms create my-project-v2

3. 网络连接是否正常

bash

# 测试网络
ping registry.npmjs.org

# 使用镜像源
pnpm config set registry https://registry.npmmirror.com

4. Node.js 版本是否符合要求

bash

# 检查版本（需要 >= 18.0.0）
node --version

# 升级 Node.js
nvm install 18
nvm use 18

Q: 如何更新 CLI 到最新版本？

bash

# 使用 pnpm
pnpm update -g doracms-cli

# 使用 npm
npm update -g doracms-cli

# 查看当前版本
doracms --version

Q: CLI 创建的项目如何启动？

bash

cd my-project

# 1. 配置环境变量
nano .env  # 编辑数据库连接等配置

# 2. 安装依赖（如果创建时跳过了）
pnpm install

# 3. 启动项目
pnpm run dev:all      # 完整全栈项目
# 或
pnpm run dev:server   # 纯后端 API
# 或
pnpm run dev          # 用户端项目

Q: 如何在 CLI 创建的项目中添加或删除模块？

编辑 server/config/modules.config.js 文件：

javascript

module.exports = {
  business: {
    // 启用广告模块
    ads: {
      enabled: true,  // 改为 true 启用
      // ...
    },
    // 禁用插件模块
    plugin: {
      enabled: false,  // 改为 false 禁用
      // ...
    },
  },
};

修改后重启应用即可生效。

Q: CLI 支持哪些项目类型？

CLI 支持三种项目类型：

完整全栈项目 (fullstack)
- 包含管理后台、用户中心和后端 API
- 适合企业内部 CMS、学习和演示
纯后端 API (backend-only)
- Headless CMS，只提供 API
- 适合移动应用、小程序后端
前后端分离 - 用户端 (user-separated)
- 包含用户中心和后端 API
- 适合博客、新闻站、社区论坛

详细说明请查看 CLI 工具文档。

Docker 部署

Q: 有完整的 Docker 部署指南吗？

A: 是的，参见 Docker 部署（部署模式、环境变量、Nginx/HTTPS）和运维与排障（健康检查、日志、备份与排障）。FAQ 只保留速查型答案，避免与部署章节重复。

Q: Docker 启动失败如何快速排查？

A: 先看日志、再查端口，必要时重建。更多细节见运维与排障。

bash

docker compose logs -f                    # 查看错误
lsof -i :8080                             # 检查端口占用
docker compose down && docker compose up -d --build

Q: 如何修改默认端口？

A: 在 docker-compose.yml 调整暴露端口，重启后生效。

yaml

services:
  eggcms-app:
    ports:
      - "8080:8080"  # 外部:内部

Q: 如何查看日志/进入容器？

A: 常用命令如下，更多运维命令见运维与排障。

bash

docker compose logs -f eggcms-app
docker compose exec eggcms-app sh

本地开发

Q: 依赖安装失败怎么办？

A: 常见问题：

1. 网络问题

bash

# 使用淘宝镜像
pnpm config set registry https://registry.npmmirror.com

# 重新安装
rm -rf node_modules
pnpm install

2. 权限问题

bash

# 修改文件权限
sudo chown -R $USER:$USER .

# 重新安装
pnpm install

3. Node 版本不兼容

bash

# 检查 Node 版本
node --version

# 切换版本
nvm use 18

4. 缓存问题

bash

# 清理 pnpm 缓存
pnpm store prune

# 清理所有依赖
pnpm clean
pnpm install

Q: 启动报错 "Cannot find module"？

bash

# 重新安装依赖
pnpm install

# 如果还不行，清理后重装
pnpm clean
pnpm install

Q: 端口被占用怎么办？

macOS/Linux:

bash

# 查找占用端口的进程
lsof -i :8080

# 杀死进程
kill -9 <PID>

Windows:

bash

# 查找占用端口的进程
netstat -ano | findstr :8080

# 杀死进程
taskkill /PID <PID> /F

或修改配置文件:

编辑 server/config/config.local.js:

javascript

config.cluster = {
  listen: {
    port: 7002, // 改为其他端口
    hostname: "127.0.0.1",
  },
};

数据库问题

Q: MongoDB 连接失败？

A: 检查以下几点：

1. MongoDB 是否启动

bash

# macOS
brew services list

# Ubuntu
sudo systemctl status mongodb

# 启动 MongoDB
brew services start mongodb-community  # macOS
sudo systemctl start mongodb            # Linux

2. 检查连接配置

javascript

// server/config/config.local.js
config.mongoose = {
  client: {
    url: "mongodb://127.0.0.1:27017/doracms", // 检查地址和端口
    options: {
      useNewUrlParser: true,
      useUnifiedTopology: true,
    },
  },
};

3. 检查防火墙

bash

# 测试连接
mongosh mongodb://127.0.0.1:27017/doracms

4. 查看 MongoDB 日志

bash

# macOS
tail -f /usr/local/var/log/mongodb/mongo.log

# Linux
tail -f /var/log/mongodb/mongodb.log

Q: MariaDB 连接失败？

1. MariaDB 是否启动

bash

# macOS
brew services list

# Ubuntu
sudo systemctl status mariadb

# 启动 MariaDB
brew services start mariadb      # macOS
sudo systemctl start mariadb     # Linux

2. 检查连接配置

javascript

// server/config/config.local.js
config.sequelize = {
  dialect: "mariadb",
  host: "127.0.0.1",
  port: 3306,
  database: "doracms",
  username: "root",
  password: "your_password", // 检查密码
};

3. 测试连接

bash

mysql -h 127.0.0.1 -u root -p

4. 检查用户权限

sql

-- 创建数据库
CREATE DATABASE doracms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 创建用户并授权
CREATE USER 'doracms'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON doracms.* TO 'doracms'@'localhost';
FLUSH PRIVILEGES;

Q: 数据库初始化失败？

bash

# MongoDB 初始化
pnpm run init:mongo

# MariaDB 初始化
pnpm run init:maria

# 如果失败，查看日志
DEBUG=* pnpm run init:mongo

生产部署

Q: 如何配置生产环境？

1. 创建生产配置文件

javascript

// server/config/config.prod.js
module.exports = () => {
  const config = {};

  // 安全配置
  config.keys = process.env.APP_KEYS || "production-keys-change-me";

  // 数据库配置
  config.mongoose = {
    client: {
      url: process.env.MONGODB_URL,
      options: {
        poolSize: 20,
      },
    },
  };

  // 日志配置
  config.logger = {
    dir: "/var/log/doracms",
    level: "INFO",
  };

  // CORS 配置
  config.cors = {
    origin: "https://your-domain.com",
    credentials: true,
  };

  return config;
};

2. 使用 PM2 管理进程

bash

# 安装 PM2
npm install -g pm2

# 启动应用
cd server
pm2 start app.js --name doracms-server

# 设置开机自启
pm2 startup
pm2 save

# 查看日志
pm2 logs doracms-server

# 重启
pm2 restart doracms-server

3. 配置 Nginx

nginx

server {
    listen 80;
    server_name your-domain.com;

    # API 代理
    location /api {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # 前端静态文件
    location / {
        root /path/to/doracms-client/user-center/dist;
        try_files $uri $uri/ /index.html;
    }
}

Q: 生产环境部署建议？

性能优化：

✅ 使用 PM2 cluster 模式
✅ 配置 Nginx 缓存
✅ 启用 Gzip 压缩
✅ CDN 加速静态资源

安全配置：

✅ 配置 HTTPS
✅ 修改默认密钥
✅ 配置防火墙
✅ 定期备份数据

监控告警：

✅ PM2 监控
✅ 日志分析
✅ 性能监控
✅ 错误告警

Q: 如何备份数据？

MongoDB 备份：

bash

# 备份
mongodump --db doracms --out /backup/$(date +%Y%m%d)

# 恢复
mongorestore --db doracms /backup/20240101/doracms

MariaDB 备份：

bash

# 备份
mysqldump -u root -p doracms > backup_$(date +%Y%m%d).sql

# 恢复
mysql -u root -p doracms < backup_20240101.sql

自动备份脚本：

bash

#!/bin/bash
# backup.sh

DATE=$(date +%Y%m%d)
BACKUP_DIR="/backup/$DATE"

mkdir -p $BACKUP_DIR

# 备份 MongoDB
mongodump --db doracms --out $BACKUP_DIR

# 删除 7 天前的备份
find /backup -type d -mtime +7 -exec rm -rf {} \;

添加到 crontab:

bash

# 每天凌晨 2 点备份
0 2 * * * /path/to/backup.sh

常见错误

Q: "EACCES: permission denied"

bash

# 修改文件权限
sudo chown -R $USER:$USER .

# 或使用 sudo（不推荐）
sudo pnpm install

Q: "Maximum call stack size exceeded"

bash

# 增加 Node.js 内存限制
export NODE_OPTIONS="--max-old-space-size=4096"

# 或在启动脚本中设置
node --max-old-space-size=4096 app.js

Q: "connect ETIMEDOUT"

bash

# 检查网络连接
ping registry.npmjs.org

# 使用代理
pnpm config set proxy http://proxy-server:port
pnpm config set https-proxy http://proxy-server:port

# 或使用镜像
pnpm config set registry https://registry.npmmirror.com

获取帮助

如果以上方案都无法解决你的问题：

📖 查看完整文档
🐛 提交 Issue
💬 加入讨论区
📧 发送邮件到 doramart@qq.com

安装与部署 ​

环境要求 ​

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

Q: 必须使用 pnpm 吗？可以用 npm 或 yarn 吗？ ​

Q: 支持哪些操作系统？ ​

CLI 工具 ​

Q: 如何安装 DoraCMS CLI？ ​

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

Q: 如何更新 CLI 到最新版本？ ​

Q: CLI 创建的项目如何启动？ ​

Q: 如何在 CLI 创建的项目中添加或删除模块？ ​

Q: CLI 支持哪些项目类型？ ​

Docker 部署 ​

Q: 有完整的 Docker 部署指南吗？ ​

Q: Docker 启动失败如何快速排查？ ​

Q: 如何修改默认端口？ ​

Q: 如何查看日志/进入容器？ ​

本地开发 ​

Q: 依赖安装失败怎么办？ ​

Q: 启动报错 "Cannot find module"？ ​

Q: 端口被占用怎么办？ ​

数据库问题 ​

Q: MongoDB 连接失败？ ​

Q: MariaDB 连接失败？ ​

Q: 数据库初始化失败？ ​

生产部署 ​

Q: 如何配置生产环境？ ​

Q: 生产环境部署建议？ ​

Q: 如何备份数据？ ​

常见错误 ​

Q: "EACCES: permission denied" ​

Q: "Maximum call stack size exceeded" ​

Q: "connect ETIMEDOUT" ​

获取帮助 ​

安装与部署

环境要求

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

Q: 必须使用 pnpm 吗？可以用 npm 或 yarn 吗？

Q: 支持哪些操作系统？

CLI 工具

Q: 如何安装 DoraCMS CLI？

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

Q: 如何更新 CLI 到最新版本？

Q: CLI 创建的项目如何启动？

Q: 如何在 CLI 创建的项目中添加或删除模块？

Q: CLI 支持哪些项目类型？

Docker 部署

Q: 有完整的 Docker 部署指南吗？

Q: Docker 启动失败如何快速排查？

Q: 如何修改默认端口？

Q: 如何查看日志/进入容器？

本地开发

Q: 依赖安装失败怎么办？

Q: 启动报错 "Cannot find module"？

Q: 端口被占用怎么办？

数据库问题

Q: MongoDB 连接失败？

Q: MariaDB 连接失败？

Q: 数据库初始化失败？

生产部署

Q: 如何配置生产环境？

Q: 生产环境部署建议？

Q: 如何备份数据？

常见错误

Q: "EACCES: permission denied"

Q: "Maximum call stack size exceeded"

Q: "connect ETIMEDOUT"

获取帮助