进阶 docs.openwebui.com 2026-10-22 19:22:27 · 24 阅读

第2章 Open WebUI 第2章:技术参考指南(环境变量、API 与 HTTPS 配置)

第2章 参考指南

涵盖每个配置项、API 端点及设置选项的技术细节。Open WebUI 具有高度可配置性。本节是环境变量、API 端点、网络架构、反向代理配置及生产环境监控的权威参考。无论是微调单一设置,还是设计多节点部署方案,请从这里开始。

⚙️ 环境变量配置 集中管理 Open WebUI 启动时读取的所有标志、路径和密钥。 超过 200 个环境变量控制着身份验证、模型路由、存储、日志记录等核心功能。了解 ConfigVar 的行为机制,排查被忽略的设置,并快速定位所需的特定变量。 🔐 认证与注册:ENABLE_SIGNUP, ENABLE_LOGIN_FORM, WEBUI_ADMIN_EMAIL, OIDC/LDAP/SCIM 🤖 模型连接:Ollama, OpenAI, 直接流水线 URL, 超时设置, 负载均衡 💾 存储与数据库:SQLite, PostgreSQL, S3/GCS/Azure Blob, Redis 📊 日志与审计:GLOBAL_LOG_LEVEL, JSON 日志, 审计日志级别与路径 🧠 RAG 与检索:分块大小, 重叠度, 嵌入引擎, 重排序, 向量数据库选择

浏览所有环境变量 →

🔌 API 端点 提供 OpenAI 兼容和 Anthropic 兼容的 API,此外还支持 RAG、文件管理及 Ollama 代理路由。 Open WebUI 暴露了一整套基于 Bearer 令牌或 JWT 认证的 REST API。你可以使用与 Web UI 相同的端点来构建自动化流程、聊天机器人及自定义集成。 💬 对话补全:POST /api/chat/completions,兼容 OpenAI 🔮 Anthropic 消息:POST /api/v1/messages,支持 Anthropic SDK 和 Claude Code 🦙 Ollama 代理:/ollama/api/*,直通原生 Ollama 端点 📄 文件与知识库:上传文件,构建知识集合,通过 RAG 进行查询 🔧 过滤器(入口/流式/出口):为每个请求提供入口、流式及出口钩子

探索 API →

🤖 服务端工具调用 发送提示词,由 Open WebUI 在服务器端执行工具,并返回最终答案。 此功能支持让模型调用内置工具、工作区工具、MCP 服务器及 Open Terminal,且基于当前用户的权限在服务器端运行。支持流式与非流式响应,可选择是否保存聊天记录,最终生成可复用的脚本。 🔁 完整智能体循环:多轮原生工具调用,从聊天记录中读取结果 ⚡ 单请求模式:一次 HTTP 调用,返回一个补全结果,工具结果已应用 🧭 逐字段说明:chat_id, id, session_id, tool_ids, terminal_id, features

在服务端运行工具 →

🔒 HTTPS 配置 使用 Nginx、Caddy 或 HAProxy 在 Open WebUI 前端终止 TLS。 提供逐步的反向代理配置指南,助你通过 HTTPS 保护部署环境。每份指南均包含证书处理、WebSocket 支持及经过生产环境验证的设置。 🟢 Nginx:完整配置,支持 SSL 终止、WebSocket 代理及头部设置 ⚡ Caddy:极小配置实现自动 HTTPS 🔄 HAProxy:企业级负载均衡与 TLS 卸载 ☁️ Cloudflare Tunnel:无需开放端口即可安全暴露 Open WebUI 🔒 Tailscale:跨设备私有加密访问,不对外暴露公网 🧪 ngrok:用于开发测试的即时 HTTPS 隧道

配置 HTTPS →

🔑 API 密钥 为脚本、机器人及集成提供对 Open WebUI 的编程访问权限。 生成个人访问令牌,允许外部代码调用与 Web UI 相同的端点。每个密钥继承创建者的用户权限。 🔐 Bearer 令牌认证:标准 Authorization: Bearer 头部,兼容任意 HTTP 客户端 🛡️ 用户范围限定:密钥继承你的角色与组权限 🚫 端点限制:可选限制密钥可访问的 API 路由

设置 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 特定网络行为的相同拓扑

查看网络拓扑图 →

*该内容仅供信息参考,不构成任何保证、担保或合同承诺。Open WebUI 按“现状”提供。请参阅许可证了解适用条款。*

评论 (0)