ValueError: Invalid scheme in CORS_ALLOW_ORIGIN: ”. Only ‘http’ and ‘https’ and

快速结论：该报错在 Open WebUI 中将环境变量 CORS_ALLOW_ORIGIN 设置为空字符串时触发。优先排查：不要将 CORS_ALLOW_ORIGIN 设为空字符串，如需禁用 CORS 应移除该环境变量或设置为 *。

问题场景

用户使用 Pip 安装 Open WebUI v0.10.2，在 Ubuntu 24.04 上启动服务时，因环境变量 CORS_ALLOW_ORIGIN 被设置为空字符串而崩溃。Issue 中用户试图通过空字符串来禁用 CORS（即不发送 CORS 头），但该用法不受支持。

报错原文

╭───────────────────── Traceback (most recent call last) ──────────────────────╮
│ /root/.local/share/uv/tools/open-webui/lib/python3.11/site-packages/open_web │
│ ui/__init__.py:73 in serve                                                   │
│                                                                              │
│    70 │   │   │   os.environ['USE_CUDA_DOCKER'] = 'false'                    │
│    71 │   │   │   os.environ['LD_LIBRARY_PATH'] = ':'.join(LD_LIBRARY_PATH)  │
│    72 │                                                                      │
│ ❱  73 │   import open_webui.main  # noqa: F401                               │
│    74 │   from open_webui.env import UVICORN_WORKERS  # Import the workers   │
│       setting                                                                │
│    75 │                                                                      │
│    76 │   # On Windows, uvicorn's default loop factory hardcodes             │
│       ProactorEventLoop,                                                     │
│                                                                              │
│ /root/.local/share/uv/tools/open-webui/lib/python3.11/site-packages/open_web │
│ ui/main.py:43 in <module>                                                    │
│                                                                              │
│     40 )                                                                     │
│     41 from starsessions.stores.redis import RedisStore                      │
│     42                                                                       │
│ ❱   43 from open_webui.config import (                                       │
│     44 │   BYPASS_ADMIN_ACCESS_CONTROL,                                      │
│     45 │   CACHE_DIR,                                                        │
...

（注：报错原文中的关键信息为 ValueError: Invalid scheme in CORS_ALLOW_ORIGIN: ''. Only 'http' and 'https' and，完整回溯因篇幅截断，但核心错误原因已明确。）

原因分析

Open WebUI 的 CORS_ALLOW_ORIGIN 配置在启动时对传入值进行 scheme 校验（仅允许 http 或 https 协议）。当设置为空字符串 '' 时，校验逻辑无法通过，抛出 ValueError。Issue 中项目维护者确认：空字符串不是一个受支持的配置值。

用户试图通过空字符串来完全禁用 CORS 功能，但该功能未被设计为支持此用法。

环境排查

Open WebUI 版本：v0.10.2（Issue 报告时使用的版本，建议升级至最新版）
Python 版本：通过 uv 工具管理，Python 3.11（报错栈路径所示）
操作系统：Ubuntu 24.04
安装方式：Pip Install（非 Docker）

解决步骤

确认当前 CORS_ALLOW_ORIGIN 的值：
检查启动环境变量或 .env 文件中是否将 CORS_ALLOW_ORIGIN 设置为空字符串（如 CORS_ALLOW_ORIGIN=""）。
移除环境变量以恢复默认行为（全允许）：
如果您的目标仅是让服务正常运行，删除 CORS_ALLOW_ORIGIN 环境变量即可。默认值等同于 *（允许所有来源）。
若要限制 CORS 来源（推荐安全做法）：
根据 Issue 中维护者的建议（以及 Open WebUI 加固文档 Hardening Guide），将 CORS_ALLOW_ORIGIN 设置为具体的来源 URL，例如：
```
CORS_ALLOW_ORIGIN=https://chat.yourcompany.com
```
如果需要完全禁用 CORS（不发送跨域头）：
注意：以 Issue 讨论结论，Open WebUI 的 CORS_ALLOW_ORIGIN 当前设计不支持“禁用 CORS”功能。可优先尝试以下替代方案：
- 将 CORS_ALLOW_ORIGIN 设置为 *（全允许），然后通过反向代理（如 Nginx、Caddy）来限制实际请求来源；
- 或者将 CORS_ALLOW_ORIGIN 设置为和自身相同的域名（虽然维护者指出这不属于真正的 CORS 场景）。
已知 Issue #8998 和 #14181 也讨论了相关安全默认值问题，但当前版本（截至 Issue 关闭的 2026-07-20）尚未支持直接通过空字符串禁用 CORS。

验证方法

启动 Open WebUI，观察控制台是否仍出现 ValueError: Invalid scheme in CORS_ALLOW_ORIGIN: '' 报错。若正常启动，通过浏览器开发者工具（F12 > Network > 任意请求）检查响应头中 Access-Control-Allow-Origin 字段是否按预期返回。