Sndow CMS 在 IIS 环境下如何正确开放 API 接口？

最近有用户反馈，在 IIS 环境下安装 Sndow CMS 后，网站前台和伪静态都可以正常访问，但访问 API 接口时出现 404 或接口无法访问的问题。

其实这类问题大多不是 Sndow CMS 本身的问题，而是 IIS 的 URL Rewrite、PHP FastCGI 或站点重写规则没有正确配置。

一、Sndow CMS 的 API 地址

Sndow CMS 提供了开放 API，可以用于 Vue 主题、小程序、移动端应用以及其他外部客户端。

常用接口示例：

• /api/ping：测试 API 是否正常
• /api/site_info：获取站点信息
• /api/home：获取首页聚合数据
• /api/posts：获取文章列表
• /api/categories：获取分类列表
• /api/tags：获取标签列表

系统的 API 入口文件位于网站根目录：

api.php

正常情况下，访问 /api/posts 时，需要通过服务器重写规则转交给根目录下的 api.php 处理。

二、IIS 环境需要准备什么？

在配置之前，请确认服务器已经完成以下设置：

• 网站可以正常运行 PHP。
• PHP FastCGI 已配置完成。
• 站点根目录指向 Sndow CMS 项目根目录。
• IIS 已安装 URL Rewrite 模块。
• 网站目录允许读取 web.config 配置。

其中最容易被忽略的是 URL Rewrite。如果服务器没有安装该模块，web.config 中的 rewrite 规则不会生效。

三、推荐的 web.config 配置

可以在 Sndow CMS 网站根目录创建或修改 web.config，参考下面的配置：

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <rewrite>
      <rules>

        <!-- API 接口重写 -->
        <rule name="SndowApiRewrite" stopProcessing="true">
          <match url="^api/(.*)$" />
          <action type="Rewrite" url="api.php" appendQueryString="true" />
        </rule>

        <!-- 前台伪静态重写 -->
        <rule name="SndowIndexRewrite" stopProcessing="true">
          <match url="^(.*)$" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          </conditions>
          <action type="Rewrite" url="index.php" appendQueryString="true" />
        </rule>

      </rules>
    </rewrite>
  </system.webServer>
</configuration>

这里需要注意，API 规则要放在前台入口规则之前，否则 /api/posts 可能会先被转交给 index.php，从而无法进入 API 处理流程。

四、配置后如何测试？

配置完成后，可以依次访问以下地址：

https://你的域名/api/ping
https://你的域名/api/site_info
https://你的域名/api/posts

如果接口正常，页面会返回 JSON 数据，而不是 HTML 页面。

还可以使用 API 原始入口进行测试：

https://你的域名/api.php?action=posts

如果 api.php?action=posts 可以访问，但 /api/posts 无法访问，说明 PHP 和 API 本身没有问题，问题集中在 IIS URL Rewrite 配置上。

五、常见错误及排查方法

1. 访问 API 返回 404

优先检查：

• 是否安装 IIS URL Rewrite。
• web.config 是否放在网站根目录。
• API 重写规则是否位于前台重写规则之前。
• 站点是否真的使用了当前这个 web.config。

2. 返回 HTML 页面而不是 JSON

这通常说明请求没有进入 api.php，而是被前台规则转交给了 index.php。

可以先直接测试：

/api.php?action=ping

如果这个地址正常，说明只需要继续检查 API Rewrite 规则。

3. PHP 处理器配置不生效

部分 IIS 配置会在 web.config 中写死 PHP 路径，例如：

D:\BtSoft\php\74\php-cgi.exe

这个路径只适用于特定服务器和 PHP 版本，不能直接复制到所有环境中。不同宝塔版本、PHP 版本和站点配置，PHP 路径可能完全不同。

建议优先使用宝塔或 IIS 管理器配置好的 PHP FastCGI，不要随意复制其他服务器的 PHP 处理器路径。

4. 返回 Missing action

如果访问 /api.php 时返回 Missing action，这不一定是错误，而是因为没有传递接口动作。

正确示例：

/api.php?action=ping
/api.php?action=posts

六、不要忽略安全配置

在开放 API 的同时，也要注意以下安全问题：

• 不要开放数据库配置文件。
• 不要允许访问缓存目录和临时目录。
• 后台接口仍然需要登录态、权限和 CSRF 校验。
• 对外开放的接口应避免返回用户密码、私密配置等敏感字段。
• 如果使用跨域请求，应合理配置允许的来源，不建议永久开放所有域名。

七、总结

在 IIS 环境下，Sndow CMS API 无法访问，通常可以按照下面的顺序排查：

1. 确认 api.php?action=ping 是否正常。
2. 确认 IIS 是否安装 URL Rewrite。
3. 确认 web.config 位于网站根目录。
4. 确认 API Rewrite 规则在前台 Rewrite 规则之前。
5. 确认 PHP FastCGI 配置没有使用错误路径。
6. 最后再测试 /api/ping、/api/posts 等接口。

Sndow CMS 的 API 设计目标，是让主题、小程序和外部客户端都能方便地调用站点内容。只要服务器重写规则配置正确，IIS 环境同样可以稳定使用完整的 API 能力。

如果你在 IIS、Nginx 或 Apache 环境中遇到部署问题，也欢迎到 Sndow CMS 社区发帖交流。