DoraCMS 快速安装指南

DoraCMS 快速安装指南

概述

DoraCMS 是一个现代化的企业级内容管理系统，支持多种安装方式。本指南将帮助你快速搭建 DoraCMS 环境。

系统要求

硬件要求

软件要求

• 操作系统：macOS 10.14+、Linux (Ubuntu 18.04+)、Windows 10+
• Node.js：18.20+ 版本
• 数据库：MongoDB 4.4+ 或 MariaDB 10.5+
• Redis：6.0+（可选，推荐生产环境）

安装方式选择

方式一：Docker 一键部署（推荐）

适用场景：快速体验、生产部署 优势：环境隔离、一键启动、易于维护

方式二：本地开发安装

适用场景：开发调试、功能定制 优势：便于调试、代码修改、性能优化

方式三：手动部署

适用场景：自定义环境、特殊需求 优势：完全控制、灵活配置

Docker 快速部署

1. 环境准备

确保已安装 Docker 和 Docker Compose：

## 检查 Docker 版本
docker --version
docker-compose --version


## 如果未安装，请访问 https://docs.docker.com/get-docker/

2. 下载源码

## 克隆项目
git clone https://github.com/doramart/DoraCMS.git
cd DoraCMS


## 或者下载压缩包
wget https://github.com/doramart/DoraCMS/archive/refs/heads/main.zip
unzip main.zip && cd DoraCMS-main

3. 配置环境变量

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


## 编辑配置文件（重要！）
nano .env

必须修改的配置项：

## 应用密钥（必须修改）
APP_KEYS=your_random_secret_key_here
SESSION_SECRET=your_session_secret_here


## 数据库密码（必须修改）
MONGODB_PASSWORD=your_mongodb_password
MARIADB_PASSWORD=your_mariadb_password


## 管理员账号（可选修改）
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your_admin_password

4. 启动服务

## 启动 MongoDB 版本（默认）
docker-compose up -d


## 或启动 MariaDB 版本
docker-compose --profile mariadb up -d


## 查看启动日志
docker-compose logs -f eggcms-app

5. 访问系统

启动成功后，可以通过以下地址访问：

• 前台首页：http://localhost:8080
• 管理后台：http://localhost:8080/admin
• API 接口：http://localhost:8080/api

默认管理员账号：

• 用户名：admin
• 密码：123456（或你在 .env 中设置的密码）

6. 常用命令

## 查看服务状态
docker-compose ps


## 查看日志
docker-compose logs -f


## 停止服务
docker-compose down


## 重启服务
docker-compose restart


## 清理数据（谨慎使用）
docker-compose down -v

本地开发安装

1. 环境准备

安装 Node.js

## 使用 nvm 安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18
nvm use 18


## 或直接下载安装
## https://nodejs.org/

安装 pnpm

npm install -g pnpm
pnpm --version

安装数据库

MongoDB（推荐）：

## macOS
brew tap mongodb/brew
brew install mongodb-community@7.0
brew services start mongodb-community@7.0


## Ubuntu
wget -qO - https://www.mongodb.org/static/pgp/server-7.0.asc | sudo apt-key add -
echo "deb [ arch=amd64,arm64 ] https://repo.mongodb.org/apt/ubuntu focal/mongodb-org/7.0 multiverse" | sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list
sudo apt-get update
sudo apt-get install -y mongodb-org
sudo systemctl start mongod

2. 下载和安装

## 克隆项目
git clone https://github.com/doramart/DoraCMS.git
cd DoraCMS


## 安装依赖
pnpm install


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

3. 配置数据库

编辑 server/.env 文件：

## 数据库配置
DATABASE_TYPE=mongodb
MONGODB_HOST=127.0.0.1
MONGODB_PORT=27017
MONGODB_DATABASE=doracms3
MONGODB_USERNAME=
MONGODB_PASSWORD=


## 应用配置
NODE_ENV=development
PORT=8080
APP_KEYS=your_secret_key

4. 启动服务

## 启动后端 + 用户前端
pnpm dev


## 或启动全部服务（包含管理后台）
pnpm dev:all


## 单独启动服务
pnpm dev:server        # 后端 API (端口 8080)
pnpm dev:user-center    # 用户前端 (端口 3000)
pnpm dev:admin-center   # 管理后台 (端口 5173)

5. 访问系统

• 用户前端：http://localhost:3000
• 管理后台：http://localhost:5173
• 后端 API：http://localhost:8080

验证安装

1. 检查服务状态

## 检查端口占用
lsof -i :8080
lsof -i :3000
lsof -i :5173


## 检查数据库连接
mongosh --eval "db.version()"  # MongoDB
mysql -u root -p -e "SELECT VERSION();"  # MariaDB

2. 访问健康检查

## API 健康检查
curl http://localhost:8080/api/health


## 预期返回
{
  "status": "ok",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "database": "connected"
}

3. 登录管理后台

1. 访问管理后台地址
2. 使用默认账号登录
3. 检查各功能模块是否正常

常见问题

常见报错代码 (Error Codes)

1. EADDRINUSE: address already in use :::8080

原因：端口 8080 被其他程序占用。 解决：

## 查找占用进程
lsof -i :8080
## 杀死进程 (PID为进程ID)
kill -9 <PID>

2. MongooseServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

原因：MongoDB 数据库未启动或连接配置错误。 解决：

• 检查 MongoDB 服务是否运行：docker ps 或 brew services list
• 检查 .env 文件中的 MONGODB_HOST 是否正确（Docker 环境下通常是 mongo 而不是 127.0.0.1）

3. Error: Redis connection to 127.0.0.1:6379 failed

原因：Redis 服务未启动。 解决：

• 生产环境建议开启 Redis。
• 开发环境如果不需要 Redis，可以在 config/config.default.ts 中暂时关闭相关插件，或启动本地 Redis 服务。

4. Permission denied (Docker)

原因：挂载目录权限不足。 解决：

sudo chown -R $USER:$USER .
chmod -R 755 .

数据库连接失败

## 检查数据库服务状态
## MongoDB
brew services list | grep mongodb
sudo systemctl status mongod


## MariaDB
brew services list | grep mariadb
sudo systemctl status mariadb

依赖安装失败

## 清理缓存
pnpm store prune
rm -rf node_modules
pnpm install


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

权限问题

## 修复文件权限
sudo chown -R $USER:$USER .
chmod -R 755 .

安全建议

生产环境部署

1. 修改默认密码：更改管理员和数据库密码
2. 配置 HTTPS：使用 SSL 证书加密传输
3. 防火墙设置：只开放必要端口
4. 定期备份：设置自动备份策略
5. 监控告警：配置系统监控

安全配置

## 生产环境配置示例
NODE_ENV=production
APP_KEYS=complex_random_string_32_chars
SESSION_SECRET=another_complex_random_string


## 限制访问来源
CORS_ORIGINS=https://your-domain.com
DOMAIN_WHITELIST=your-domain.com


## 数据库安全
MONGODB_USERNAME=doracms_user
MONGODB_PASSWORD=complex_password_here