agentic_huge_data_base / wiki
页面 Open WebUI · 3.4 反向代理设置·DeepWiki 中文全文译文
DeepWiki 中文译文 / Open WebUI / 3.4

3.4 · 反向代理设置（Reverse Proxy Setup）

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节3.4 状态全文译文 模块系统架构、接口与服务契约、认证、权限与安全、测试、发布与运维
项目要点页2.5 参考项目 项目章节目录Open WebUI DeepWiki 原始章节Reverse Proxy Setup 上一章3.3 下一章3.5
源码线索
  • README.md
  • TROUBLESHOOTING.md
  • backend/dev.sh
  • backend/start.sh
  • src/lib/apis/images/index.ts
  • src/lib/components/chat/Settings/About.svelte
  • src/lib/components/playground/Images.svelte
  • src/lib/constants.ts
  • static/manifest.json
  • start.sh
模块标签
  • 系统架构
  • 接口与服务契约
  • 认证、权限与安全
  • 测试、发布与运维
  • 界面与交互

中文译文

反向代理设置（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/3.4-reverse-proxy-setup
翻译时间：2026-06-09T16:07:47.082Z
翻译模型：deepseek-chat
原文字符数：8502
项目：Open WebUI (open-webui)

---

反向代理设置

相关源文件

以下文件用于生成此 Wiki 页面：

  • .env.example
  • Dockerfile
  • LICENSE
  • README.md
  • TROUBLESHOOTING.md
  • backend/dev.sh
  • backend/start.sh
  • backend/start_windows.bat
  • src/lib/apis/images/index.ts
  • src/lib/components/chat/Settings/About.svelte
  • src/lib/components/playground/Images.svelte
  • src/lib/constants.ts
  • src/routes/(app)/playground/images/+page.svelte/playground/images/+page.svelte)
  • static/manifest.json

本文档提供配置反向代理（nginx、Apache、Caddy）以在生产环境中提供 Open WebUI 服务的技术指导。涵盖代理设置、标头转发、WebSocket 支持、TLS 终止以及受信任标头身份验证。

---

概述

Open WebUI 是一个基于 FastAPI 的应用程序，需要特定的反向代理配置来处理其 REST API、实时 WebSocket 和静态前端资源的混合架构。后端充当网关，通过 OLLAMA_BASE_URL 将请求转发到 Ollama 等推理引擎 TROUBLESHOOTING.md:7-9。

需要代理协调的关键组件：

  • REST API：用于聊天、用户管理和 RAG 的标准 HTTP 端点。
  • WebSocket：通过 Socket.IO 实现流式传输和协作的实时通信 README.md:71-73。
  • 静态资源：通过 Node.js 构建的 SvelteKit 前端文件 Dockerfile:27-43，由 FastAPI 应用程序提供服务。
  • 受信任身份验证：通过请求标头实现 SSO 集成，支持 LDAP 和 SCIM 2.0 README.md:65-67。

---

应用架构与数据流

下图展示了从客户端通过反向代理进入 FastAPI 实体空间的流程。

请求流向代码实体
graph TD
    subgraph "External_Network" ["外部网络"]
        Client["客户端浏览器"]
    end

    subgraph "Reverse_Proxy" ["反向代理 (Nginx/Apache/Caddy)"]
        RP["反向代理层"]
    end

    subgraph "FastAPI_Application" ["FastAPI 应用程序 (open_webui.main:app)"]
        M_Auth["AuthMiddleware"]
        M_CORS["CORSMiddleware"]

        Router_Ollama["/ollama 代理路由器"]
        Router_API["/api/v1 路由器"]

        Static["SPAStaticFiles"]
    end

    subgraph "Realtime_Layer" ["实时层 (Socket.IO)"]
        SIO["Socket.IO 服务器"]
    end

    Client --> RP
    RP -->|"HTTP/REST"| M_CORS
    RP -->|"Upgrade: websocket"| SIO

    M_CORS --> M_Auth

    M_Auth --> Router_Ollama
    M_Auth --> Router_API
    M_Auth --> Static

    Router_Ollama -->|"转发到"| Ollama["Ollama API (OLLAMA_BASE_URL)"]

来源： TROUBLESHOOTING.md:7-9、.env.example:1-3、backend/start.sh:83-87、src/lib/constants.ts:6-14

---

标头配置

标准代理标头

后端依赖 FORWARDED_ALLOW_IPS 来信任来自代理的标头 .env.example:17-18。默认情况下，start.sh 和 start_windows.bat 使用 --forwarded-allow-ips 标志配置 uvicorn，以允许来自代理的转发 IP backend/start.sh:83-87、backend/start_windows.bat:50-50。

标头用途示例值
X-Forwarded-For客户端 IP 追踪$proxy_add_x_forwarded_for
X-Forwarded-Proto协议检测 (HTTP/HTTPS)https
Host保留原始主机$host
受信任身份验证标头

Open WebUI 通过信任代理提供的标头来支持 SSO。这对于通过 SCIM 2.0 进行企业级用户和组配置至关重要 README.md:65-67。

  • WEBUI_AUTH_TRUSTED_EMAIL_HEADER：用户电子邮件的标头键。
  • WEBUI_AUTH_TRUSTED_NAME_HEADER：用户姓名的标头键。

---

反向代理实现示例

Nginx 配置

Nginx 必须配置为处理 RAG 文档的大文件上传以及 AI 推理的长时间超时。Open WebUI 默认响应生成超时为 5 分钟 TROUBLESHOOTING.md:21-23。

location / {
    proxy_pass http://127.0.0.1:8080;

    # 标准标头
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;

    # WebSocket 支持 (Socket.IO 必需)
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    # 必须关闭缓冲以支持流式 AI 响应
    proxy_buffering off;
    proxy_cache off;

    # 长 LLM 生成任务的超时时间 (应用默认 5 分钟)
    proxy_read_timeout 600s;
    client_max_body_size 100M;
}

来源： TROUBLESHOOTING.md:21-23、backend/start.sh:23-24

Apache 配置

Apache 需要 mod_proxy_wstunnel 模块来支持实时功能。

<VirtualHost *:443>
    ServerName openwebui.example.com

    ProxyPreserveHost On
    ProxyRequests Off

    # WebSocket 路由
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} =websocket [NC]
    RewriteRule /(.*)           ws://localhost:8080/$1 [P,L]

    ProxyPass / http://localhost:8080/
    ProxyPassReverse / http://localhost:8080/

    # 转发协议
    RequestHeader set X-Forwarded-Proto "https"
</VirtualHost>

---

WebSocket 与实时通信

Socket.IO 服务器处理关键的交互任务。在分布式部署中，需要 Redis 后端来同步多个节点间的事件，以实现水平扩展 README.md:71-73。

WebSocket 实体映射
graph LR
    subgraph "Client_Space" ["客户端空间"]
        Client["Socket.IO 客户端 (浏览器)"]
    end

    subgraph "Code_Entity_Space" ["代码实体空间"]
        SIO_App["Socket.IO 服务器"]
        Redis_Sync["基于 Redis 的会话管理"]

        Event_Chat["'chat' 事件处理器"]
        Capability_Search["web_search 能力"]
    end

    Client -->|"ws://host/socket.io/"| SIO_App
    SIO_App --> Event_Chat
    SIO_App --> Capability_Search
    SIO_App <--> Redis_Sync

来源： src/lib/constants.ts:100-111、README.md:71-73、backend/start.sh:83-87

---

安全与会话管理

CORS 配置

CORS_ALLOW_ORIGIN 环境变量控制哪些源可以访问 API backend/dev.sh:1-1。在生产环境中，应将其设置为特定域名而非 *，以防止未经授权的跨域请求 .env.example:13-14。

密钥管理

后端需要 WEBUI_SECRET_KEY。如果未通过环境变量提供，启动脚本会生成一个随机的 12 字节 base64 字符串，并将其存储在 .webui_secret_key 文件中 backend/start.sh:25-36、backend/start_windows.bat:32-45。在多节点代理设置中，此密钥必须在所有实例中保持一致，以允许会话持久化。

端口与主机绑定

默认情况下，应用程序绑定到 0.0.0.0 的 8080 端口 backend/start.sh:23-24。如果与代理运行在同一主机上，可以通过 HOST 环境变量将其限制为 127.0.0.1 backend/start_windows.bat:26-26。

来源： backend/start.sh:23-36、backend/start_windows.bat:26-45、.env.example:13-14

---

静态资源优化

Open WebUI 提供基于 SvelteKit 的单页应用程序 (SPA)。

  • 构建过程：在 Docker 构建阶段，前端通过 npm run build 构建为静态资源 Dockerfile:27-43。
  • 版本追踪：客户端在"关于"设置中显示 WEBUI_VERSION 和 WEBUI_BUILD_HASH src/lib/components/chat/Settings/About.svelte:4-6、src/lib/constants.ts:18-19。
  • 路由：后端从 PORT（默认 8080）提供这些资源 backend/start.sh:23-24。代理应确保根据需要缓存静态文件请求（例如 /static/ 中的文件），尽管 SPA 在内部处理大部分路由。

来源： Dockerfile:27-43、src/lib/components/chat/Settings/About.svelte:59-61、src/lib/constants.ts:18-19