从零开始配置迅睿CMS前后端分离适配完整实操指南

一、前置准备

本次适配基于迅睿CMS 4.5及以上版本，你需要提前完成：

• 部署好迅睿CMS后端站点，PHP版本要求7.3~8.1，可从官方直接下载安装包：https://www.xunruicms.com/download.html
• 准备好独立的前端域名/端口，后端和前端可部署在同一服务器不同域名下，也可跨服务器部署

二、开启API接口与跨域配置

2.1 开启站点API功能

1. 登录迅睿CMS后台，依次点击 系统设置 → 站点配置 → 选择你要适配的站点 → 功能开关

2. 找到 API接口功能 选项，勾选「开启」，点击保存配置。

2.2 配置跨域访问规则

首先在后台配置跨域头，依次点击 系统设置 → 安全设置 → HTTP头设置，在自定义响应头区域添加以下3条配置：

• Header名称：Access-Control-Allow-Origin，值填你的前端完整域名（开发测试阶段可填，生产环境必须替换为实际前端域名）
• Header名称：Access-Control-Allow-Methods，值填GET,POST,OPTIONS
• Header名称：Access-Control-Allow-Headers，值填Content-Type,Authorization

添加完成后点击保存，如果配置后跨域仍然不生效，需要在服务器层面添加配置：

Nginx服务器配置：打开站点的Nginx配置文件，在server块内添加以下代码：

``` add_header Access-Control-Allow-Origin always; add_header Access-Control-Allow-Methods GET,POST,OPTIONS always; add_header Access-Control-Allow-Headers Content-Type,Authorization always; if (!-e $request_filename) { rewrite ^/api/(.)$ /index.php?s=api/$1 last; } ```

添加完成后执行重载命令：systemctl reload nginx 生效。

Apache服务器配置：打开站点根目录的.htaccess文件，添加以下代码：

``` RewriteEngine On RewriteBase / RewriteRule ^api/(.)$ index.php?s=api/$1 [L] Header set Access-Control-Allow-Origin "" Header set Access-Control-Allow-Methods "GET,POST,OPTIONS" Header set Access-Control-Allow-Headers "Content-Type,Authorization" ```

三、关闭默认前端渲染，配置API基础信息

依次点击 系统设置 → 站点配置 → 当前站点 → 域名设置，找到 API接口域名 选项，填写你后端站点的完整域名（比如https://api.yourdomain.com，和后端访问地址一致即可），点击保存。

如果你不需要后端提供前台页面，可以关闭静态生成功能：依次点击 系统 → 系统维护 → 生成静态，关闭静态生成开关即可。

四、配置接口权限与内容输出规则

4.1 创建接口调用权限组

1. 依次点击 系统设置 → API接口 → API权限管理，点击「添加新接口组」

2. 填写接口组名称，比如「前端分离调用组」，然后勾选你需要前端调用的所有接口，常用勾选选项：栏目分类接口、内容列表接口、内容详情接口、碎片接口、搜索接口，如果需要用户体系则额外勾选用户相关接口。

3. 保存后系统会自动生成 AppKey和AppSecret，请妥善保存这两个值，前端调用接口必须使用。

4.2 开启自定义字段API输出

迅睿CMS默认不会输出未开启权限的自定义字段，这是最容易卡壳的步骤，操作如下：

1. 依次点击 内容 → 内容模型管理，选择你要配置的模型（比如文章模型），点击「字段管理」

2. 编辑每一个需要在接口中输出的自定义字段，拉到配置页面最底部，找到 API输出 选项，勾选「开启」，保存配置。所有需要输出的字段都按此操作。

操作完成后，点击后台左上角的「清除缓存」，刷新配置。

五、接口调用测试验证

配置完成后我们可以测试接口是否正常，以调用栏目列表接口为例：

接口地址格式：https://你的后端域名/api/category/index

请求方式：POST，必填参数如下：

• appid：你刚才生成的AppKey
• timestamp：10位秒级时间戳，误差不能超过5分钟
• sign：签名，计算方式为 md5(appid + timestamp + AppSecret)

示例curl测试命令：

``` curl -X POST https://api.yourdomain.com/api/category/index \ -d "appid=你的AppKey×tamp=1698000000&sign=你的计算后签名" ```

如果返回正确的JSON格式栏目数据，说明配置全部成功。如果返回错误，可参考下文排查。

六、常见问题排查

• 跨域请求被拦截：Nginx配置必须添加always参数，否则OPTIONS请求不会返回跨域头；生产环境不要使用，必须填写实际前端域名。
• 接口返回404或不存在：检查伪静态规则是否正确，API权限组是否开启了对应接口，AppKey是否填写错误。
• 返回数据缺少自定义字段：检查对应字段是否开启了API输出开关，清除后台缓存后重新测试。
• 提示签名错误：确认时间戳是10位秒级，不要使用毫秒级时间戳；检查签名拼接顺序是否正确，AppSecret是否填写正确。

对接完成后，前端可按照官方API文档调用所有接口，官方完整API文档地址：https://www.xunruicms.com/doc/apiguide.html