From b8d4df9230add822825284391c1358726ea3dc4a Mon Sep 17 00:00:00 2001 From: Haitao Pan Date: Fri, 12 Jun 2026 09:44:24 +0800 Subject: [PATCH] docs: rename var to litellm_api_caddy_strict_whitelist and update documentation --- roles/vhosts/litellm/Deployment-Guide.md | 9 +++++++++ roles/vhosts/litellm/Readme.md | 17 ++++++++++++----- roles/vhosts/litellm/defaults/main.yml | 4 ++-- .../litellm/templates/api.svc.plus.caddy.j2 | 2 +- 4 files changed, 24 insertions(+), 8 deletions(-) diff --git a/roles/vhosts/litellm/Deployment-Guide.md b/roles/vhosts/litellm/Deployment-Guide.md index 860e2d4..e6d6b5f 100644 --- a/roles/vhosts/litellm/Deployment-Guide.md +++ b/roles/vhosts/litellm/Deployment-Guide.md @@ -37,6 +37,15 @@ psql "postgresql://litellm:replace-with-strong-password@127.0.0.1:15432/litellm? ansible-playbook -i inventory.ini setup-litellm.yaml --limit jp-xhttp-contabo.svc.plus --vault-password-file ~/.vault_password ``` +**控制网关公网访问行为（严格白名单模式）：** +默认情况下，Caddy 网关是放开所有路径访问的（依赖 LiteLLM 内置 Token 认证）。如果您希望开启**严格白名单模式**（拦截除 `/v1/chat/completions` 等官方兼容路径以外的所有请求），请在部署时通过 `-e` 附加参数开启： +```bash +ansible-playbook -i inventory.ini setup-litellm.yaml \ + --limit jp-xhttp-contabo.svc.plus \ + --vault-password-file ~/.vault_password \ + -e "litellm_api_caddy_strict_whitelist=true" +``` + **第五步：检查服务运行端口** 验证所需的端口是否在监听状态： ```bash diff --git a/roles/vhosts/litellm/Readme.md b/roles/vhosts/litellm/Readme.md index 5c646e8..2a83ede 100644 --- a/roles/vhosts/litellm/Readme.md +++ b/roles/vhosts/litellm/Readme.md @@ -34,15 +34,22 @@ Caddy + LiteLLM Minimal AI API Gateway + PostgreSQL ## 部署说明 -### Caddy 配置 -Caddy 作为唯一公网 HTTPS 入口，执行路径白名单拦截。 -内部映射如下： -- `/ui*` -> `http://127.0.0.1:4000/ui*` (且强制鉴权) +### Caddy 配置与网关模式 +Caddy 作为唯一公网 HTTPS 入口。目前支持两种模式（可通过 `litellm_api_caddy_strict_whitelist` 控制）： + +1. **Permissive 模式（默认，推荐 UI 使用）**： + - 所有的请求直接穿透代理到 LiteLLM 后端，由 LiteLLM 的原生认证（Bearer Token）负责鉴权。前端 Dashboard 可完全顺畅工作。 +2. **Strict Whitelist 模式（Minimal AI API Gateway）**： + - 仅对指定的 AI 模型路径放行，例如 `/v1/chat/completions` 等。 + - 未匹配到的非法路径在 Caddy 层被直接 `404 Not Found` 阻断。 + - 此模式下 Admin UI 的诸多后端接口将被拦截。 + +路径映射规则： +- `/ui*` -> `http://127.0.0.1:4000/ui*` - `/v1/openai/chat/completions` -> `http://127.0.0.1:4000/v1/chat/completions` - `/v1/openai/embeddings` -> `http://127.0.0.1:4000/v1/embeddings` - `/v1/anthropic/messages` -> `http://127.0.0.1:4000/v1/messages` - `/v1/models` -> `http://127.0.0.1:4000/v1/models` -- 未匹配路径返回 `404 Not Found`。 ### LiteLLM config.yaml 配置极致精简，不预设任何模型： diff --git a/roles/vhosts/litellm/defaults/main.yml b/roles/vhosts/litellm/defaults/main.yml index 9330112..42827eb 100644 --- a/roles/vhosts/litellm/defaults/main.yml +++ b/roles/vhosts/litellm/defaults/main.yml @@ -30,8 +30,8 @@ litellm_ui_caddy_fragment_path: "/etc/caddy/conf.d/{{ litellm_ui_domain }}.caddy litellm_caddy_config_enabled: true litellm_enable_basic_auth: false -# When true, proxies all paths (Open Public Access). When false, strictly whitelists AI API paths only. -litellm_api_caddy_public_access: true +# When true, strictly whitelists AI API paths only. When false, proxies all paths (Open Public Access). +litellm_api_caddy_strict_whitelist: false # ============================================================================= diff --git a/roles/vhosts/litellm/templates/api.svc.plus.caddy.j2 b/roles/vhosts/litellm/templates/api.svc.plus.caddy.j2 index afbf21c..917fdf3 100644 --- a/roles/vhosts/litellm/templates/api.svc.plus.caddy.j2 +++ b/roles/vhosts/litellm/templates/api.svc.plus.caddy.j2 @@ -8,7 +8,7 @@ rewrite /v1/openai/embeddings /v1/embeddings rewrite /v1/anthropic/messages /v1/messages -{% if not litellm_api_caddy_public_access %} +{% if litellm_api_caddy_strict_whitelist %} # ------------------------------------------------------------------------ # Minimal AI API Gateway Mode (STRICT WHITELIST) # ------------------------------------------------------------------------