常见问题解决方案

安装部署问题

Docker 相关问题

问题：Docker 启动失败

症状：

docker-compose up -d
## 容器启动失败或异常退出

解决方案：

查看详细日志：

docker-compose logs -f eggcms-app
docker-compose logs -f mongodb

检查端口占用：


## 检查 8080 端口
lsof -i :8080
netstat -tulpn | grep 8080

杀死占用进程

kill -9 <PID>



3. **重建容器**：
```bash
docker-compose down
docker-compose up -d --build

清理 Docker 缓存：

docker system prune -a
docker volume prune

问题：数据库连接失败

症状：

Database connection failed
MongoError: Authentication failed

解决方案：

检查环境变量：

## 确认 .env 文件中的数据库配置
cat .env | grep -E "(MONGODB|MARIADB)"

验证数据库服务：


## MongoDB
docker-compose exec mongodb mongosh --eval "db.version()"

MariaDB

docker-compose exec mariadb mysql -u root -p -e "SELECT VERSION();"



3. **重置数据库密码**：
```bash
## 停止服务
docker-compose down


## 删除数据卷（注意：会丢失数据）
docker volume rm $(docker volume ls -q | grep -E "(mongodb|mariadb)")


## 重新启动
docker-compose up -d

本地开发问题

问题：依赖安装失败

症状：

pnpm install
## 报错：网络超时、权限错误等

解决方案：

使用国内镜像：

pnpm config set registry https://registry.npmmirror.com
pnpm config set disturl https://npmmirror.com/dist

清理缓存：

pnpm store prune
rm -rf node_modules
rm pnpm-lock.yaml
pnpm install

权限问题：


## macOS/Linux
sudo chown -R $USER:$USER .
chmod -R 755 .

或使用 sudo 安装全局包

sudo pnpm install -g pnpm



#### 问题：Node.js 版本不兼容


**症状**：

Error: The engine "node" is incompatible with this module



**解决方案**：


1. **检查 Node.js 版本**：
```bash
node --version
## 需要 18.20.0 或更高版本

使用 nvm 管理版本：


## 安装 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



3. **更新 npm 和 pnpm**：
```bash
npm install -g npm@latest
npm install -g pnpm@latest

运行时问题

服务启动问题

问题：端口被占用

症状：

Error: listen EADDRINUSE: address already in use :::8080

解决方案：

查找占用进程：


## macOS/Linux
lsof -i :8080
ps aux | grep node

Windows

netstat -ano | findstr :8080 tasklist | findstr node



2. **杀死占用进程**：
```bash
## macOS/Linux
kill -9 <PID>


## Windows
taskkill /PID <PID> /F

修改端口配置：
```
## .env 文件
PORT=8081
```

问题：内存不足

症状：

JavaScript heap out of memory
FATAL ERROR: Ineffective mark-compacts near heap limit

解决方案：

增加 Node.js 内存限制：


## 临时设置
export NODE_OPTIONS="--max-old-space-size=4096"

或在启动命令中设置

node --max-old-space-size=4096 app.js



2. **优化代码和配置**：
```javascript
// 减少内存使用
config.bodyParser = {
  jsonLimit: '1mb',
  formLimit: '1mb',
};

使用 PM2 管理进程：
```
pm2 start ecosystem.config.js
pm2 monit
```

数据库问题

问题：MongoDB 连接超时

症状：

MongoTimeoutError: Server selection timed out after 30000 ms

解决方案：

检查 MongoDB 服务状态：


## macOS
brew services list | grep mongodb

Linux

sudo systemctl status mongod

Docker

docker ps | grep mongo



2. **检查网络连接**：
```bash
## 测试连接
telnet localhost 27017
nc -zv localhost 27017

调整连接配置：

MONGODB_OPTIONS=connectTimeoutMS=30000&socketTimeoutMS=30000&serverSelectionTimeoutMS=30000

问题：MariaDB 连接被拒绝

症状：

ER_ACCESS_DENIED_ERROR: Access denied for user 'doracms_user'@'localhost'

解决方案：

检查用户权限：

mysql -u root -p
SELECT User, Host FROM mysql.user WHERE User = 'doracms_user';
SHOW GRANTS FOR 'doracms_user'@'localhost';

重新创建用户：

DROP USER IF EXISTS 'doracms_user'@'localhost';
CREATE USER 'doracms_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON doracms3.* TO 'doracms_user'@'localhost';
FLUSH PRIVILEGES;

检查防火墙设置：

## 确保 3306 端口开放
sudo ufw allow 3306

功能使用问题

文件上传问题

问题：文件上传失败

症状：

上传按钮无响应
上传后显示错误
文件大小超限

解决方案：

检查文件大小限制：

## .env 文件
UPLOAD_MAX_FILE_SIZE=10485760  # 10MB

检查文件类型限制：

UPLOAD_ALLOWED_TYPES=jpg,jpeg,png,gif,pdf,doc,docx

检查上传目录权限：

## 确保上传目录可写
chmod 755 app/public/uploads
chown -R www-data:www-data app/public/uploads

检查 Nginx 配置（如果使用）：
```
## nginx.conf
client_max_body_size 10M;
```

邮件发送问题

问题：邮件发送失败

症状：

Error: Invalid login: 535 Login Fail

解决方案：

检查 SMTP 配置：

MAIL_HOST=smtp.qq.com
MAIL_PORT=465
MAIL_SECURE=true
MAIL_USER=your_email@qq.com
MAIL_PASS=your_authorization_code  # 注意：不是邮箱密码

获取邮箱授权码：
- QQ 邮箱：设置 → 账户 → 开启 SMTP 服务
- 163 邮箱：设置 → 客户端授权密码
- Gmail：应用专用密码

测试邮件发送：

## 使用 telnet 测试 SMTP 连接
telnet smtp.qq.com 465

权限访问问题

问题：管理后台无法访问

症状：

404 页面未找到
403 权限被拒绝
白屏或加载失败

解决方案：

检查路由配置：

// 确认管理后台路由正确配置
app.get('/admin/*', (req, res) => {
res.sendFile(path.join(__dirname, 'admin/index.html'));
});

检查静态文件服务：

// 确认静态文件中间件配置
app.use('/admin', express.static('admin'));

清除浏览器缓存：

## 强制刷新页面
Ctrl + F5 (Windows)
Cmd + Shift + R (Mac)

性能问题

页面加载缓慢

问题：首页加载时间过长

解决方案：

启用缓存：
```
CACHE_ENABLED=true
CACHE_TTL=3600
```

优化数据库查询：

// 添加数据库索引
db.articles.createIndex({ "status": 1, "created_at": -1 });

启用 Gzip 压缩：
```
GZIP_ENABLED=true
```

使用 CDN：
```
CDN_DOMAIN=https://cdn.your-domain.com
```

内存使用过高

问题：服务器内存占用过多

解决方案：

监控内存使用：

## 查看进程内存使用
ps aux --sort=-%mem | head
top -o %MEM

优化数据库连接池：

MONGODB_MAX_POOL_SIZE=5
MARIADB_CONNECTION_LIMIT=5

启用垃圾回收：

node --expose-gc --optimize-for-size app.js

安全问题

安全漏洞防护

问题：防止常见攻击

解决方案：

启用安全头：

SECURITY_CSP_ENABLED=true
SECURITY_HSTS_ENABLED=true

配置防火墙：

## 只开放必要端口
sudo ufw allow 22
sudo ufw allow 80
sudo ufw allow 443
sudo ufw deny 8080  # 不要直接暴露应用端口

定期更新依赖：
```
pnpm audit
pnpm update
```

日志和调试

启用调试模式

## 开发环境
NODE_ENV=development
DEBUG=true
LOG_LEVEL=DEBUG


## 生产环境
NODE_ENV=production
DEBUG=false
LOG_LEVEL=INFO

查看日志

## 应用日志
tail -f logs/app.log


## 错误日志
tail -f logs/error.log


## Docker 日志
docker-compose logs -f eggcms-app

性能分析

## 使用 clinic.js 分析性能
npm install -g clinic
clinic doctor -- node app.js

获取帮助

自助排查步骤

查看错误日志：检查详细的错误信息
搜索文档：在官方文档中搜索相关问题
检查配置：确认配置文件正确
测试环境：在干净环境中重现问题

寻求帮助

如果问题仍未解决，可以：

访问官网：https://www.doracms.net
查看 GitHub Issues：搜索类似问题
加入社区群：获取社区技术支持
提交问题报告：详细描述问题和环境信息

问题报告模板

## 问题描述
简要描述遇到的问题


## 环境信息
- 操作系统：
- Node.js 版本：
- DoraCMS 版本：
- 数据库类型：


## 重现步骤
1. 第一步
2. 第二步
3. 第三步


## 错误信息
粘贴完整的错误日志


## 已尝试的解决方案
描述已经尝试过的解决方法

常见问题解决方案