快速开始
# DoraCMS 快速安装指南
## 概述
DoraCMS 是一个现代化的企业级内容管理系统，支持多种安装方式。本指南将帮助你快速搭建 DoraCMS 环境。
## 系统要求
### 硬件要求
| 环境 | CPU | 内存 | 硬盘 |
|------|-----|------|------|
| 开发环境 | 2核+ | 4GB+ | 10GB+ |
| 生产环境 | 4核+ | 8GB+ | 50GB+ |
### 软件要求
- **操作系统**：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：
```bash
# 检查 Docker 版本
docker --version
docker-compose --version
# 如果未安装，请访问 https://docs.docker.com/get-docker/
```
### 2. 下载源码
```bash
# 克隆项目
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. 配置环境变量
```bash
# 复制环境配置文件
cp docker.env.example .env
# 编辑配置文件（重要！）
nano .env
```
**必须修改的配置项**：
```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. 启动服务
```bash
# 启动 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. 常用命令
```bash
# 查看服务状态
docker-compose ps
# 查看日志
docker-compose logs -f
# 停止服务
docker-compose down
# 重启服务
docker-compose restart
# 清理数据（谨慎使用）
docker-compose down -v
```
## 本地开发安装
### 1. 环境准备
#### 安装 Node.js
```bash
# 使用 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
```bash
npm install -g pnpm
pnpm --version
```
#### 安装数据库
**MongoDB（推荐）**：
```bash
# 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. 下载和安装
```bash
# 克隆项目
git clone https://github.com/doramart/DoraCMS.git
cd DoraCMS
# 安装依赖
pnpm install
# 复制配置文件
cp server/env.example server/.env
```
### 3. 配置数据库
编辑 `server/.env` 文件：
```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. 启动服务
```bash
# 启动后端 + 用户前端
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. 检查服务状态
```bash
# 检查端口占用
lsof -i :8080
lsof -i :3000
lsof -i :5173
# 检查数据库连接
mongosh --eval "db.version()" # MongoDB
mysql -u root -p -e "SELECT VERSION();" # MariaDB
```
### 2. 访问健康检查
```bash
# 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 被其他程序占用。
**解决**：
```bash
# 查找占用进程
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)
**原因**：挂载目录权限不足。
**解决**：
```bash
sudo chown -R $USER:$USER .
chmod -R 755 .
```
### 数据库连接失败
```bash
# 检查数据库服务状态
# MongoDB
brew services list | grep mongodb
sudo systemctl status mongod
# MariaDB
brew services list | grep mariadb
sudo systemctl status mariadb
```
### 依赖安装失败
```bash
# 清理缓存
pnpm store prune
rm -rf node_modules
pnpm install
# 使用国内镜像
pnpm config set registry https://registry.npmmirror.com
```
### 权限问题
```bash
# 修复文件权限
sudo chown -R $USER:$USER .
chmod -R 755 .
```
## 安全建议
### 生产环境部署
1. **修改默认密码**：更改管理员和数据库密码
2. **配置 HTTPS**：使用 SSL 证书加密传输
3. **防火墙设置**：只开放必要端口
4. **定期备份**：设置自动备份策略
5. **监控告警**：配置系统监控
### 安全配置
```env
# 生产环境配置示例
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
```