OpenWebUI项目实现子路径部署的技术方案解析

在Web应用部署场景中，经常需要将应用部署在域名子路径下（如example.com/my_ai_portal）。本文针对OpenWebUI项目如何实现这一需求进行技术解析，重点介绍基于路径替换的解决方案。

技术背景

OpenWebUI作为基于Svelte的前端项目，默认设计为根路径部署。当需要部署在子路径时，会遇到以下典型问题：

1. 前端路由路径硬编码为绝对路径
2. API接口调用路径未考虑前缀
3. 静态资源引用路径需要调整

解决方案核心

通过自动化脚本实现全项目路径替换，主要包含两个技术层面：

1. 路径规则替换系统

脚本内置18种精细匹配规则，覆盖各类场景：

• 前端路由跳转（goto方法调用）
• HTML链接属性（href/src属性）
• 后端路由定义（FastAPI装饰器）
• WebSocket连接路径
• 静态资源引用
• 条件编译路径（开发/生产环境）

示例替换规则：

{
  pattern: `href\\s*=\\s*(['"\`])\\/(?!${BASE_PATH})`, 
  replacement: `href=$1/${BASE_PATH}/`
}

2. Svelte构建配置修改

自动修改svelte.config.js，添加paths.base配置：

paths: {
  base: '/my_ai_portal'
}

实现细节

脚本采用Node.js实现，具有以下技术特性：

1. 智能文件过滤：

• 自动读取.gitignore规则
• 排除图片、字体等二进制文件
• 支持自定义忽略规则

2. 精确匹配替换：

• 行号定位变更位置
• 保留原始引号类型（单/双引号）
• 上下文感知替换（避免误改）

3. 安全机制：

• 支持dry-run预览模式
• 变更内容差异对比
• 错误捕获与日志

使用指南

1. 克隆项目仓库
2. 执行替换脚本：

node prepare_openwebui.js ./open-webui/ --path my_ai_portal

3. 重新构建前端：

npm run build

技术延伸

该方案虽然采用替换方式，但揭示了前端项目子路径部署的通用解决思路：

1. 构建工具配置（webpack/vite/svelte等）
2. 运行时路径前缀注入
3. API网关路径重写

对于长期维护的项目，建议逐步过渡到环境变量配置方案，但本方案在需要快速实现子路径部署时仍具有实用价值。

注意事项

1. 替换后需要完整的前端重新构建
2. 深度链接需要确保Nginx等代理配置正确
3. 版本升级时可能需要重新应用修改