BookStack在IIS环境下URL重写规则配置指南

问题背景

在使用BookStack文档管理系统时，部分用户在Windows Server的IIS环境中遇到了绘图保存失败和图片管理器加载异常的问题。这些问题通常表现为：

• 保存绘图时出现"An error occurred uploading the image"错误
• 绘图管理器持续加载无法完成
• 图片选择功能异常
• 开发者工具中显示404或500错误

根本原因分析

经过排查，这些问题主要源于IIS URL重写规则配置不当。许多用户会从网络获取复杂的重写规则，但这些规则可能并不适合BookStack的标准安装场景，特别是当BookStack安装在网站根目录而非子目录时。

解决方案

使用官方推荐的重写规则

BookStack项目本身提供了一个适用于IIS的标准web.config文件，包含基本的URL重写规则。这些规则已经过优化，能够正确处理BookStack的路由请求和静态资源访问。

配置步骤

1. 备份现有配置：在进行任何修改前，备份当前的web.config文件。

2. 使用标准配置：将以下标准配置内容替换到web.config文件中：

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="BookStack Front Controller" stopProcessing="true">
          <match url="^(.*)$" ignoreCase="false" />
          <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/{R:1}" />
        </rule>
      </rules>
    </rewrite>
    <directoryBrowse enabled="false" />
    <defaultDocument>
      <files>
        <clear />
        <add value="index.php" />
      </files>
    </defaultDocument>
  </system.webServer>
</configuration>

3. 验证配置：修改后，测试以下功能是否正常工作：
   • 页面创建和编辑
   • 绘图保存功能
   • 图片上传和管理
   • 静态资源加载

注意事项

1. 子目录安装：如果BookStack安装在子目录中（如/bookstack），则需要调整重写规则，确保URL重写路径正确。

2. 权限设置：确保IIS应用程序池账户对以下目录有写入权限：

   • /public/uploads
   • /storage

3. PHP配置：检查php.ini中的以下设置：

   • upload_max_filesize
   • post_max_size
   • memory_limit

4. MIME类型：确保IIS已配置正确的MIME类型，特别是对于.svg等现代Web格式。

最佳实践建议

1. 保持简单：除非必要，避免使用复杂的重写规则。BookStack的标准路由机制已经处理了大多数URL场景。

2. 分阶段测试：在修改配置后，逐步测试各个功能模块，以便快速定位问题。

3. 监控日志：定期检查BookStack的日志文件，及时发现和解决潜在问题。

4. 环境一致性：尽量保持开发、测试和生产环境的配置一致，减少因环境差异导致的问题。

通过遵循这些指导原则，大多数IIS环境下的BookStack URL重写问题都能得到有效解决，确保系统各项功能正常运行。