LiteLLM Proxy UI 发现端点解析：用 `.well-known/litellm-ui-config` 解决子路径部署下的前端寻址

当 LiteLLM Proxy 被反向代理挂载在域名子路径（如 /litellm）下时，浏览器里的管理后台与代理后端之间往往会出现 URL 前缀错位：前端不知道应该把 API 请求发到哪个 origin、加哪个路径前缀。LiteLLM 在 discovery_endpoints 模块中实现了一组 well-known 风格的"UI 配置发现端点"，用于向前端返回 proxy_base_url 与 server_root_path，让 UI 能够据此拼出访问代理的正确地址。本文将以 litellm/proxy/discovery_endpoints/README.md 为骨架，结合后端路由实现、响应数据模型、前端消费代码与单元测试，完整讲解这一机制的用法、协议与底层原理。

一、要解决的问题：代理部署在域名非根路径时的 URL 错位

按照原文档描述，该模块的核心使命只有一句话：返回代理的 base url 与 server root path，使 UI 能够构造出访问代理的正确 URL。文档明确指出其适用场景是：

This is useful when the proxy is deployed at a different path than the root of the domain.

在典型部署中，LiteLLM Proxy 服务本身运行在 4000 端口，而对外则通过 Nginx、Traefik、Kubernetes Ingress 等反向代理暴露，例如把 https://example.com/litellm/* 统一转发到代理的 4000 端口。此时存在两个问题：

1. 域名层面：管理后台页面与代理 API 可能同源，也可能跨源（NEXT_PUBLIC_BASE_URL 拆分场景），前端需要知道真实的代理 origin；
2. 路径层面：所有 API、Swagger、静态资源都挂在前缀 /litellm 之下，如果前端仍按 / 根路径发请求，就会命中反向代理上不存在的路由，导致 404 或登录态错乱。

LiteLLM 给出的解法，是把"代理怎么被访问"这件事做成一个可被 UI 主动拉取的公开配置，而不是在前端打包时硬编码。

二、整体思路：Action → Result 两步式发现流程

原文档用最简洁的两步描述了这一机制的使用方式：

• Action（动作）：把 /litellm 路径路由到 LiteLLM Proxy（由反向代理或网关完成）；
• Result（结果）：UI 会调用 /litellm/.well-known/litellm-ui-config，从响应中获得 proxy_base_url 与 server_root_path。

换句话说，前端并不需要事先知道自己被部署在哪个前缀下。它只需固定请求一个 well-known 路径，后端即会回告"我的真实访问地址是什么"，前端据此初始化全局 API base URL。这就是为什么文档特意选用 /.well-known/ 前缀——遵循了行业常见的"服务发现"惯例（如同一目录下还存在的 /.well-known/litellm-cli-auth、OAuth 授权端点等发现路由）。

三、代码结构：discovery_endpoints 模块的三个文件

该功能集中放在 litellm/proxy/discovery_endpoints/ 目录下，只有三个文件，职责划分清晰：

文件	职责
README.md	原文档，说明该端点解决什么问题、如何使用
__init__.py	包入口，向外导出 ui_discovery_endpoints_router
ui_discovery_endpoints.py	FastAPI 路由定义与处理函数实现

其中 init.py 只做了一件事：从同目录模块导入 router 并重命名为 ui_discovery_endpoints_router 加入 __all__，供代理主应用挂载。真正的逻辑在 ui_discovery_endpoints.py。

四、路由注册：两条路径指向同一处理函数

在 litellm/proxy/proxy_server.py 中，代理主应用通过 app.include_router(ui_discovery_endpoints_router) 注册该路由。而 ui_discovery_endpoints.py 内部为一个异步处理函数注册了两条 GET 路径：

router: Final = APIRouter()

@router.get("/.well-known/litellm-ui-config", response_model=UiDiscoveryEndpoints)
@router.get("/litellm/.well-known/litellm-ui-config", response_model=UiDiscoveryEndpoints)  # if mounted at root path
async def get_ui_config():
    ...

两条路径共享同一个处理函数与同一个响应模型：

• /.well-known/litellm-ui-config：代理以根路径方式直接暴露时使用的规范地址；
• /litellm/.well-known/litellm-ui-config：对应前端默认请求的地址形态，保证即使代理未配置额外前缀，该固定路径也能命中。

从 单元测试 test_ui_discovery_endpoints_both_routes_return_same_data 可以看到，两条路由在同一配置下返回的 JSON 完全一致，验证了它们就是同一逻辑的两个入口别名。

五、响应协议：UiDiscoveryEndpoints 数据模型

端点通过 Pydantic 响应模型约束输出结构，模型定义在 litellm/types/proxy/discovery_endpoints/ui_discovery_endpoints.py：

class UiDiscoveryEndpoints(BaseModel):
    server_root_path: str
    proxy_base_url: str | None
    auto_redirect_to_sso: bool
    admin_ui_disabled: bool
    sso_configured: bool
    hide_default_credentials_hint: bool = False
    is_control_plane: bool = False
    workers: list[WorkerRegistryEntry] = []

各字段的含义与用途如下：

字段	类型	含义	UI 侧用途
server_root_path	str	代理挂载的根路径前缀，未配置时为 ""	前端为所有相对请求补上前缀
proxy_base_url	str | None	代理对外可访问的 base URL，来自 PROXY_BASE_URL 环境变量；为 None 表示同源访问	前端决定 API 请求发往哪个 origin
auto_redirect_to_sso	bool	是否在配置了 SSO 后自动把登录页重定向到 SSO	控制登录页行为
admin_ui_disabled	bool	管理后台是否被禁用（对应 DISABLE_ADMIN_UI）	控制 UI 是否展示后台入口
sso_configured	bool	是否已配置任何 SSO（OAuth / SAML）	决定登录按钮是否以 SSO 形式呈现
hide_default_credentials_hint	bool	是否隐藏登录页上的默认凭据提示卡片	控制登录页展示
is_control_plane	bool	当前实例是否为控制平面（管理 worker）	控制 worker 切换 UI
workers	list	控制平面下已注册的 worker 列表（WorkerRegistryEntry）	支持前端切换目标 worker

对应的 TypeScript 接口 LiteLLMWellKnownUiConfig 与后端模型字段一一对应，前端与后端通过这套协议完成契约对接。

一次真实的响应示例

在单机部署、未开启 SSO 的默认场景下，请求 /.well-known/litellm-ui-config 会得到类似如下的 JSON：

{
  "server_root_path": "",
  "proxy_base_url": null,
  "auto_redirect_to_sso": false,
  "admin_ui_disabled": false,
  "sso_configured": false,
  "hide_default_credentials_hint": false,
  "is_control_plane": false,
  "workers": []
}

当配置了 SERVER_ROOT_PATH=/litellm 后，server_root_path 变为 /litellm；若同时设置了 PROXY_BASE_URL（如 https://proxy.example.com），则 proxy_base_url 返回该值，前端即可拼出 https://proxy.example.com/litellm 作为真实 API 基准地址。

六、源码视角：响应字段是如何一步步计算出来的

get_ui_config 处理函数逻辑完整可见于 ui_discovery_endpoints.py，其计算链条如下。

6.1 server_root_path 与 proxy_base_url 的来源

这两个最核心的字段由 litellm/proxy/utils.py 中的两个工具函数读取环境变量获得：

def get_proxy_base_url() -> str | None:
    """Get the proxy base url from the environment variables."""
    return os.getenv("PROXY_BASE_URL")

def get_server_root_path() -> str:
    """Get the server root path from the environment variables."""
    return os.getenv("SERVER_ROOT_PATH", "")

关键细节是：get_server_root_path() 的默认值是空字符串 "" 而不是 /。从 tests/proxy_unit_tests/test_server_root_path.py 的注释可以看出，返回空串是为了"allow X-Forwarded-Prefix"——在未显式配置前缀时，兼容依赖反向代理注入 X-Forwarded-Prefix 头来自动推导前缀的部署方式。

6.2 auto_redirect_to_sso：双重开关与默认值

auto_redirect_to_sso 并不是一个简单的布尔回传，而是**"SSO 已配置"与"自动重定向开关"两者取与**：

auto_redirect_ui_login_to_sso = (
    os.getenv("AUTO_REDIRECT_UI_LOGIN_TO_SSO", "false").lower() == "true"
    or general_settings.get("auto_redirect_ui_login_to_sso", False) is True
)
...
auto_redirect_to_sso=sso_configured and auto_redirect_ui_login_to_sso,

即配置了 SSO 但未开启自动重定向时，该字段仍为 false。开关本身支持两种配置方式（环境变量或 config.yaml 的 general_settings），二者任一为 true 即生效。这一点在 test_ui_discovery_endpoints_with_auto_redirect_env_var_overrides_general_settings 等测试中有明确验证。

6.3 admin_ui_disabled 与 hide_default_credentials_hint

• admin_ui_disabled 直接取自环境变量 DISABLE_ADMIN_UI（默认 "false"）；
• hide_default_credentials_hint 与 auto-redirect 类似，支持 LITELLM_HIDE_DEFAULT_CREDENTIALS_HINT 环境变量与 general_settings.hide_default_credentials_hint 两种配置源，任一开启即为 true。

6.4 sso_configured：检测所有已支持的 SSO 通道

sso_configured 由 litellm/proxy/auth/auth_utils.py 的 has_user_setup_sso() 计算。其实现会依次检查以下环境变量是否已被配置：

变量	对应 SSO 通道
MICROSOFT_CLIENT_ID	Microsoft Entra / OAuth
GOOGLE_CLIENT_ID	Google OAuth
GENERIC_CLIENT_ID	通用 OAuth
SAML_IDP_METADATA_URL	SAML IdP 元数据 URL
SAML_IDP_METADATA_XML	SAML IdP 元数据内联 XML

该函数注释明确说明：覆盖 OAuth 与 SAML 两类配置，其设计目的正是服务于 UI discovery 的 sso_configured 字段，使登录按钮在"只要配置了任意受支持的 SSO 路径"（含纯 SAML 场景）时就能启用。

6.5 is_control_plane 与 workers：控制平面场景

当 LiteLLM 以"控制平面 + 多 worker"形态部署时，proxy_config.worker_registry 中会登记已接入的 worker。处理函数据此判断：

is_control_plane: Final = len(proxy_config.worker_registry) > 0
...
workers=proxy_config.worker_registry if is_control_plane else [],

从 test_ui_discovery_endpoints_is_control_plane_true_when_workers_configured 可见，当注册表包含 worker 时，响应会携带 workers 数组（含 worker_id、name、url），前端据此提供 worker 切换能力。

七、前端消费链路：UI 如何用这份配置"校准"自己

发现端点最终服务于 UI。在管理后台前端 ui/litellm-dashboard/src/components/networking.tsx 中，getUiConfig 是唯一的消费入口：

export const getUiConfig = async () => {
  /**Special route to get the proxy base url and server root path */
  const url = defaultProxyBaseUrl
    ? `${defaultProxyBaseUrl}/litellm/.well-known/litellm-ui-config`
    : `/litellm/.well-known/litellm-ui-config`;
  const response = await fetch(url);
  const jsonData: LiteLLMWellKnownUiConfig = await response.json();
  updateServerRootPath(jsonData.server_root_path);
  updateProxyBaseUrl(jsonData.server_root_path, jsonData.proxy_base_url);
  return jsonData;
};

这段代码的意图与后端 README 完全对应：

1. 若前端配置了独立的代理 base（NEXT_PUBLIC_BASE_URL，本地开发等跨源场景），则向该 base 请求 /litellm/.well-known/litellm-ui-config；
2. 否则走同源相对路径 /litellm/.well-known/litellm-ui-config（该路径已由反向代理转发给后端）；
3. 拿到 JSON 后，用 server_root_path 更新全局根路径状态（ui/litellm-dashboard/src/lib/serverRootPath.ts），再用"server_root_path + proxy_base_url"解析出全局 API base。

最终拼装规则集中在 ui/litellm-dashboard/src/lib/http/resolveApiBase.ts：

export const resolveApiBase = ({ explicitBase, serverRootPath }: ApiBaseInputs): string => {
  const base = (explicitBase ?? "").trim().replace(/\/+$/, "");
  const rootPath = normalizeRootPath(serverRootPath);
  if (rootPath === "" || base.endsWith(rootPath)) return base;
  return `${base}${rootPath}`;
};

即：同源场景下 base 为空、仅保留根路径前缀；若 proxy_base_url 已包含该前缀则不重复拼接。此后所有 API 请求都会自动带上这一基准，从而避免子路径部署下的 404。另外值得注意：若用户在浏览器本地存储（localStorage）中主动选择过 worker URL，updateProxyBaseUrl 会跳过自动覆盖，防止用户的选择被 discovery 结果意外覆盖。

八、实战：把 /litellm 路由到代理后的验证步骤

按照原文档的 Action/Result 两步，完整的接入与验证流程如下。

第 1 步：配置代理的根路径

在启动 LiteLLM Proxy 前设置环境变量（或在进程环境中导出）：

export SERVER_ROOT_PATH="/litellm"   # 可选，告知前端本代理挂载在 /litellm
export PROXY_BASE_URL="https://proxy.example.com"  # 可选，跨源部署时使用

从 proxy_server.py 可以看到，FastAPI 应用在创建时便以 server_root_path 作为 root_path，因此 OpenAPI、Swagger 等都会相应带上前缀；同时 UI 静态资源挂载阶段（proxy_server.py）会把静态文件中硬编码的 /litellm/.well-known/litellm-ui-config 字符串替换为 {server_root_path}/.well-known/litellm-ui-config，保证打包产物与新前缀兼容。

第 2 步：反向代理转发 /litellm

以 Nginx 为例，将 /litellm/ 前缀下的流量转发到代理实例（示意）：

location /litellm/ {
    proxy_pass http://127.0.0.1:4000/;
    proxy_set_header Host $host;
}

第 3 步：启动并用 curl 验证发现端点

启动代理后，从外部按子路径访问发现端点：

curl http://localhost:4000/litellm/.well-known/litellm-ui-config
# 若未配 SERVER_ROOT_PATH / PROXY_BASE_URL，预期：
# {"server_root_path":"","proxy_base_url":null,"auto_redirect_to_sso":false,
#  "admin_ui_disabled":false,"sso_configured":false,
#  "hide_default_credentials_hint":false,"is_control_plane":false,"workers":[]}

配置前缀后再次访问，server_root_path 即返回 /litellm。此时打开管理后台，前端 getUiConfig 会拉取同一地址并完成 base URL 的自动校准，后续请求均带上前缀，登录、模型管理等操作恢复正常。

九、覆盖度极高的单元测试矩阵

该功能在后端有非常完整的测试支撑，集中在 tests/test_litellm/proxy/discovery_endpoints/test_ui_discovery_endpoints.py，测试全部通过 FastAPI TestClient 模拟真实 HTTP 请求，覆盖了以下关键分支：

• 默认配置下的字段取值（server_root_path="/"、proxy_base_url=None）；
• 自定义 server_root_path（如 /litellm）的正确回传；
• PROXY_BASE_URL 设置后 proxy_base_url 的透传；
• SSO 配置与 AUTO_REDIRECT_UI_LOGIN_TO_SSO 开关组合的四种情况（含默认值为 false 的语义）；
• 通过 general_settings（config.yaml）开启 auto-redirect 的等价路径；
• DISABLE_ADMIN_UI、LITELLM_HIDE_DEFAULT_CREDENTIALS_HINT 的环境变量与配置双通道；
• 两条路由返回一致数据；
• 控制平面下 is_control_plane 与 workers 数组的返回逻辑。

此外，路由注册在 proxy_server.py，响应 schema 同时出现在前端生成的 OpenAPI schema 中（get_ui_config__well_known_litellm_ui_config_get），说明该端点已纳入正式的 API 契约管理。

小结

从原文档简短的 Action/Result 描述出发，可以看到 LiteLLM 的 UI 发现端点是一个"小切口、闭环完整"的设计：后端通过两条 well-known 路由输出 proxy_base_url 与 server_root_path，再叠加 SSO、后台禁用、控制平面等运行时状态；前端在启动时主动拉取并据此校准全局 API 基准，最终解决了代理部署在域名子路径时的 URL 寻址问题。对于自建 UI 或二次开发前端接入 LiteLLM Proxy 的开发者而言，/.well-known/litellm-ui-config 是一份稳定、公开、可复用的"代理访问自述"，值得直接参考其协议并按需集成。