Etherpad-Lite 在子目录部署时管理员面板加载问题的分析与解决方案

问题背景

Etherpad-Lite 是一款开源的实时协作编辑器，许多用户选择将其部署在Nginx反向代理后的子目录中。然而在最新版本(v2.0.3)中，当通过子目录(如/pad)访问时，主编辑器功能正常，但管理员面板却无法正确加载资源文件。

问题现象

管理员面板的静态资源(JS/CSS文件)请求路径错误地指向了Web根目录(/admin/assets/...)，而非预期的子目录路径(/pad/admin/assets/...)。这导致Nginx无法正确重写请求路径，最终返回404错误。

技术分析

深入分析后发现，问题的根源在于管理员面板作为一个独立的Vite项目构建时，其构建配置中的base选项被设置为绝对路径(指向根目录)。这种配置在子目录部署场景下会导致以下问题：

1. 资源路径解析错误：Vite构建生成的资源引用路径不会自动包含子目录前缀
2. 路径重写失效：Nginx的反向代理规则无法捕获错误的资源请求路径
3. 前后端路径不一致：管理员面板的前端路由与后端API路径不匹配

解决方案比较

经过技术评估，我们提出了几种可能的解决方案：

方案一：使用Vite实验性功能

利用Vite提供的实验性功能，动态调整构建时的base路径。这是最理想的解决方案，但存在以下考虑：

• 需要修改构建配置
• 依赖Vite的实验性功能，可能存在稳定性风险
• 需要全面测试不同部署场景

方案二：运行时路径重写

在Express中间件中动态重写资源路径，根据请求头中的子目录信息自动调整。这种方案：

• 实现简单快速
• 不依赖构建工具的特殊功能
• 但会增加运行时开销

方案三：配置化解决方案

在设置文件中增加子目录配置项，让用户明确指定部署路径。这种方案：

• 对用户友好
• 配置明确
• 但需要修改现有架构

推荐解决方案

综合考虑稳定性、实现复杂度和用户体验，我们最终选择了结合方案二和方案三的混合方案：

1. 通过X-Proxy-Path请求头传递子目录信息
2. 在Express中间件中动态重写资源路径
3. 提供清晰的文档说明配置方法

配置示例

对于Nginx用户，需要在配置中添加以下规则：

location /pad/ {
    rewrite ^/pad/?(.*) /$1 break;
    proxy_pass http://localhost:9001;
    proxy_set_header X-Proxy-Path "/pad";
}

注意事项

1. 确保管理员面板已正确构建
2. 检查请求头是否被正确传递
3. 验证所有功能链接(包括从管理员面板打开的编辑器链接)是否包含子目录前缀

总结

Etherpad-Lite在子目录部署场景下的管理员面板问题，本质上是前后端路径解析不一致导致的。通过动态路径重写和明确的配置指引，我们既保持了系统的灵活性，又解决了实际部署中的痛点。这一解决方案已在最新版本中得到验证，为用户提供了更稳定的子目录部署体验。