vLLM 跨域 (CORS) 完整解决方案

5次阅读

报错特征：浏览器 Access‑Control‑Allow‑Origin 跨域错误。原因：vLLM 默认后端服务调用，浏览器直接请求会被 CORS 拦截。

方案 1：启动参数开启（推荐，vLLM ≥0.4.0）vLLM

开发环境（允许全部跨域）

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --allowed-origins '["*"]' \
  --allowed-methods '["*"]' \
  --allowed-headers '["*"]'

生产环境（指定前端域名白名单，安全）

python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000 \
  --allowed-origins '["http://localhost:5173","https://your-web.com"]' \
  --allowed-methods '["GET","POST","OPTIONS"]' \
  --allowed-headers '["*"]' \
  --allow-credentials

⚠️参数注意：--allowed‑origins 必须是 JSON 数组字符串，用单引号包裹外层，内部双引号域名，不能直接写逗号分割字符串 "a,b"vLLM

方案 2：Nginx 反向代理添加跨域头（生产最优）

不修改 vLLM，在网关层处理跨域，适合多服务统一管理、加 HTTPS 场景

server {
    listen 80;
    server_name api.your‑llm.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X‑Real‑IP $remote_addr;

        # CORS配置
        add_header Access‑Control‑Allow‑Origin "http://localhost:5173";
        add_header Access‑Control‑Allow‑Methods "GET,POST,OPTIONS";
        add_header Access‑Control‑Allow‑Headers "*";
        add_header Access‑Control‑Allow‑Credentials true;

        if ($request_method = 'OPTIONS') {
            return 204;
        }
    }
}

方案 3：源码打补丁（老版本 < 0.4.0 无原生参数）

修改 vllm/entrypoints/openai/api_server.py，FastAPI 实例后加入 CORS 中间件：

from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

修改完成后重装 vllm 生效。