参考指南
每个控制项、端点和配置选项背后的技术细节。
Open WebUI 具有高度可配置性。本部分是环境变量、API 端点、网络架构、反向代理设置以及生产监控的官方权威可信源。无论您是在调整单个设置还是构建多节点部署，请从这里开始。
⚙️ 环境变量配置
Open WebUI 在启动时读取的每个标志、路径和机密，均在此处统一汇集。
超过 200 个环境变量控制着身份验证、模型路由、存储、日志记录等。了解 PersistentConfig 的行为，排查被忽略的设置，并找到您所需的具体变量。
| 🔐 身份验证与注册 | ENABLE_SIGNUP, ENABLE_LOGIN_FORM, WEBUI_ADMIN_EMAIL, OIDC/LDAP/SCIM |
| 🤖 模型连接 | Ollama, OpenAI, 直接 pipeline URL, 超时, 负载均衡 |
| 💾 存储与数据库 | SQLite, PostgreSQL, S3/GCS/Azure Blob, Redis |
| 📊 日志记录与审计 | GLOBAL_LOG_LEVEL, JSON 日志记录, 审计日志级别和路径 |
| 🧠 RAG 与检索 | Chunk size, overlap, embedding 引擎, reranking, 向量数据库选择 |
🔌 API 端点
兼容 OpenAI 和 Anthropic 的 API，以及 RAG、文件管理和 Ollama 代理路由。
Open WebUI 提供了完整的 REST API，通过 Bearer tokens 或 JWT 进行身份验证。您可以使用与 Web UI 相同的端点来构建自动化程序、聊天机器人和自定义集成。
| 💬 聊天补全 | POST /api/chat/completions，兼容 OpenAI |
| 🔮 Anthropic 消息 | POST /api/v1/messages，适用于 Anthropic SDK 和 Claude Code |
| 🦙 Ollama 代理 | /ollama/api/*，透传至原生 Ollama 端点 |
| 📄 文件与知识库 | 上传文件，构建知识库集合，通过 RAG 进行查询 |
| 🔧 过滤器 (inlet/stream/outlet) | 针对每个请求的 Inlet, stream 和 outlet 钩子 |
🔒 HTTPS 配置
在 Open WebUI 前端使用 Nginx, Caddy 或 HAProxy 终止 TLS。
使用 HTTPS 保护部署的分步反向代理配置。每份指南均包含证书处理、WebSocket 支持以及生产环境级别的强化设置。
| 🟢 Nginx | 包含 SSL 终止、WebSocket 代理和标头设置的完整配置 |
| ⚡ Caddy | 极简配置的自动 HTTPS |
| 🔄 HAProxy | 支持 TLS 卸载的企业级负载均衡 |
| ☁️ Cloudflare Tunnel | 安全地暴露 Open WebUI，无需开放端口 |
| 🔒 Tailscale | 跨设备的私有加密访问，无公共网络暴露 |
| 🧪 ngrok | 用于开发和测试的即时 HTTPS 隧道 |
🔑 API 密钥
为脚本、机器人和集成提供对 Open WebUI 的程序化访问。
生成个人访问令牌，使外部代码能够调用与 Web UI 相同的端点。每个密钥都会继承创建该密钥的用户的权限。
| 🔐 Bearer 令牌身份验证 | 标准 Authorization: Bearer 标头，适用于任何 HTTP 客户端 |
| 🛡️ 用户作用域限制 | 密钥继承您的角色和组权限 |
| 🚫 端点限制 | 可选地限制密钥可以访问的 API 路由 |
📊 监控
使用 Uptime Kuma, OpenTelemetry, Prometheus 和 Grafana 观察您的部署。
生产监控指南涵盖了健康检查、模型连接性验证、分布式追踪、指标和结构化日志。将其与您现有的可观测性技术栈集成，或从头开始搭建一个全新的可观测性系统。
| ✅ 健康检查 | 使用 Uptime Kuma 进行基础检查、模型连接性检查以及深度健康检查 |
| 📡 OpenTelemetry | 将追踪、指标和日志发送至任何兼容 OTLP 的后端 |
| 📈 仪表板 | 结合 Prometheus + Grafana 实现实时系统和模型指标监控 |
🌐 网络拓扑图
查看 Open WebUI, Ollama 和 Docker 在不同部署拓扑下是如何通信的。
直观的 C4 架构图涵盖了主机网络、Docker Compose 技术栈、独立网络以及特定平台的差异。这对于排查连接问题或规划架构非常有用。
| 🖥️ macOS / Windows | 主机 Ollama, Compose 栈, 独立网络, 主机网络陷阱 |
| 🐧 Linux | 使用 Linux 特定网络行为的相同拓扑 |