DoraCMS前后端分离部署，API接口调试

DoraCMS前后端分离部署的核心是把前端静态文件和后端 API 服务分开运行，再用 Nginx 统一对外提供访问入口。
本文按零基础也能照做的顺序，讲清服务器准备、后端启动、前端打包、Nginx 配置和 API 接口调试，最后给出验证方法，帮你判断部署是否真正成功。

部署前需要确认的环境和目录

DoraCMS 前后端分离版本通常需要 Node.js 运行后端、Nginx 提供静态资源和反向代理、数据库保存数据。
开始前先确认服务器能正常联网，并准备好一个已解析到服务器 IP 的域名。

登录服务器后，用下面命令检查基础环境：

node -v
npm -v
nginx -v
mysql --version

如果 Node.js 未安装，建议使用 nvm 或系统包管理器安装当前维护中的 LTS 版本；
具体版本号以 DoraCMS 官方文档要求为准。
目录规划建议如下：

• 后端代码：/www/wwwroot/doracms-server
• 前端打包产物：/www/wwwroot/doracms-web/dist
• Nginx 站点配置：/etc/nginx/conf.d/doracms.conf

宝塔面板用户可以在“网站”中新建站点，把前端目录指向 dist，再单独配置反向代理。

后端服务启动与数据库连接

进入后端目录，安装依赖并配置数据库连接。
不同版本的 DoraCMS 配置文件位置可能不同，常见为 .env 或 config 目录下的配置文件，请以实际项目为准。

cd /www/wwwroot/doracms-server
npm install

编辑配置文件，填入数据库地址、端口、库名、用户名和密码。
如果后端监听 3000 端口，可以先用开发模式启动，方便观察日志：

npm run dev

看到服务监听端口且无报错后，再使用生产模式或进程管理工具启动。
生产环境推荐用 pm2 保持后台运行：

npm install -g pm2
pm2 start app.js --name doracms-api
pm2 save
pm2 startup

启动后在本机测试后端是否可达：

curl http://127.0.0.1:3000/api

如果返回 JSON 或接口提示，说明后端本身已经跑起来。后端服务必须先于 Nginx 反向代理确认可用，否则前端页面会出现 502。

前端打包与 Nginx 反向代理配置

前端目录通常需要先修改 API 请求地址。
常见做法是在 .env.production 或接口配置文件中把 baseURL 指向你的域名，例如 https://你的域名/api。
改完后执行打包：

cd /www/wwwroot/doracms-web
npm install
npm run build

打包完成后会生成 dist 目录。
接着配置 Nginx，把前端静态文件和后端 API 分开处理：

server {
    listen 80;
    server_name 你的域名;

    root /www/wwwroot/doracms-web/dist;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /api/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

保存后检查配置并重载：

nginx -t
nginx -s reload

注意 proxy_pass 末尾是否带 / 会影响路径拼接。
如果后端接口本身以 /api 开头，代理地址可以写成 http://127.0.0.1:3000，避免出现 /api/api 这类重复路径。

API 接口调试与跨域问题排查

浏览器打开站点后按 F12 进入开发者工具，切到 Network 面板，刷新页面。
重点看接口请求是否返回 200、返回内容是否为 JSON、响应头是否包含正确的跨域信息。

常见现象和处理方式：

• 接口 404：检查 Nginx 的 location /api/ 路径和后端实际路由是否一致，确认 proxy_pass 末尾斜杠写法。
• 接口 502：后端进程没有运行或端口不对，用 pm2 list 和 curl 127.0.0.1:3000 复查。
• 跨域报错：前后端分离时如果前端直接请求后端端口，浏览器会拦截。正确做法是通过 Nginx 同域代理，或在后端配置允许的来源。生产环境不建议长期使用 Access-Control-Allow-Origin: *。
• 返回 HTML 而不是 JSON：说明请求被前端路由接管了，检查 Nginx 的 try_files 和 API 代理优先级，确保 /api/ 规则在 location / 之前匹配。

调试时可以用 curl 直接绕过浏览器验证接口：

curl -i http://你的域名/api/接口路径

如果 curl 正常而浏览器异常，优先排查前端请求地址、跨域和缓存问题。

部署完成后的验证清单

部署完成后，按下面几项逐一确认，能快速判断是否真正可用：

• 访问域名能正常打开前端页面，静态资源加载无 404。
• 浏览器 Network 中 API 请求返回 200，数据能正常渲染。
• 后端日志无数据库连接错误和未捕获异常。
• 重启服务器后，pm2 能自动拉起后端服务。
• 使用手机流量或其他网络访问域名，确认不是本地缓存造成的假象。

能打开页面不代表部署成功，
API 接口能稳定返回数据才算真正完成。 如果后续要加 HTTPS，
建议在 Nginx 中配置证书后，
把前端接口地址同步改成 https:
//，
避免混合内容被浏览器拦截。

常见疑问

DoraCMS 前后端必须分开部署吗？ 前后端分离版本建议分开部署，前端负责页面展示，后端专注接口，便于独立升级和排查问题。

Nginx 配置改完需要重启吗？ 一般用 nginx -s reload 重载即可，不需要直接停止服务。

API 调试工具推荐用什么？ 可以用浏览器开发者工具、curl 或 Postman 类工具，重点对比请求地址、请求头和返回状态码。

部署后样式错乱怎么办？ 先检查前端打包的 publicPath 或静态资源路径是否与 Nginx 根目录一致，再清理浏览器缓存重试。