使用 llama-cpp-python 的 server 模块配置 OpenAI 兼容 API 的 CORS 与鉴权

llama-cpp-python 的 server 模块（通过 python -m llama_cpp.server 或 llama-server 命令启动）本身提供了一个 OpenAI 兼容的 HTTP 接口，CORS 和鉴权都可以通过启动参数直接配置，不需要额外写中间层。但要注意：这些参数在不同版本里的默认行为和命名可能略有差异，配置后应当用实际请求验证，而不是只依赖文档印象。

可使用 `--cors` 指定允许跨域来源，启用 `--api-key` 后所有 /v1 接口都需要 Bearer Token 才能访问。建议只对明确的前端来源开放 CORS，不要使用 * 作为默认值；API key 应放在启动参数或环境变量中，避免写进进程列表。验证时分别测试带/不带 Origin 和 Authorization 的请求，确认响应头与状态码符合预期。

1. 确认启动方式与基础命令

llama-cpp-python 的 server 模块通常以两种方式启动：直接运行模块，或使用同名的命令行入口。先确定你安装的是哪个版本、是否能打印帮助信息，再继续配置。

# 方式一：作为 Python 模块启动
python -m llama_cpp.server `--model` /path/to/model.gguf `--host` 127.0.0.1 `--port` 8080

# 方式二：若安装后带有 llama-server 命令
llama-server `--model` /path/to/model.gguf `--host` 127.0.0.1 `--port` 8080

建议先用一条不带 CORS 和鉴权的命令启动，确认模型能加载、/v1/models 能返回列表，再逐步加参数。这样可以隔离问题：如果后面请求出错，能判断是模型加载问题还是访问控制配置问题。

2. 配置 CORS

CORS 控制浏览器环境下的跨域请求。若 API 只给后端服务调用，不需要开启 CORS；只有在前端页面（如本地 Web 工具）直接调用时才需要配置。

python -m llama_cpp.server `--model` /path/to/model.gguf `--cors` "https://example.com,http://localhost:8000"

要注意 `--cors` 参数接受逗号分隔的多个来源，不需要加尾随斜杠。启用后，服务器会为符合条件的预检请求（OPTIONS）以及实际请求返回 Access-Control-Allow-Origin 响应头。验证方式：在浏览器控制台或 curl 中携带 Origin 头请求 /v1/models，检查响应头里是否包含你配置的来源。禁止来源的请求可能跨域失败，但服务器本身不一定会拒绝该请求，浏览器会拦截响应，所以不能用 curl 直接判断“允许”或“拒绝”，要模拟浏览器行为。

风险边界：临时调试时可用 `--cors` "*" 放开所有来源，但不要用于公网服务。另外，如果前端还需要携带 Authorization 头，服务器可能还需要处理预检请求中的 Access-Control-Allow-Headers，llama-cpp-python 通常会自动处理，但不同版本行为不完全一致，需要实际验证。

3. 配置 API Key 鉴权

server 模块支持用 `--api-key` 参数启用 Bearer Token 鉴权。启用后，所有与模型推理相关的接口（如 /v1/chat/completions、/v1/completions）都必须携带有效 Token，否则返回 401。

使用 llama-cpp-python 的 server 模块配置 OpenAI 兼容 API 的 CORS 与鉴权

python -m llama_cpp.server `--model` /path/to/model.gguf `--api-key` "sk-your-secret-key"

更推荐的做法是使用环境变量，避免密钥出现在 ps 命令的输出里。具体做法因系统而异：在 Linux/macOS 的 shell 中可以这样启动：

LLAMA_API_KEY="sk-your-secret-key" python -m llama_cpp.server `--model` /path/to/model.gguf `--api-key` "$LLAMA_API_KEY"

不过不同版本对 `--api-key` 的支持和命名可能不同，某些版本可能使用 `--key` 或配置文件字段。启动前先执行 python -m llama_cpp.server `--help`，确认真实参数名。验证方式：不带 Authorization 头请求 /v1/chat/completions，应返回 401；带 Authorization: Bearer sk-your-secret-key 后应能正常返回。

这里要特别提醒：llama-cpp-python 的 API key 鉴权主要控制 HTTP 层的访问，它不会加密传输内容。如果服务暴露在公网，应当同时启用 HTTPS，或在前面加反向代理。否则密钥和请求内容都会被明文截获。

4. 推荐的完整启动示例

综合 CORS 和鉴权后，最小可用的启动命令如下。先用本机访问验证功能，再决定是否开放到局域网或公网。

# 允许本机调试域名和实际前端域名
python -m llama_cpp.server \
  `--model` /home/user/models/qwen2.5-7b-instruct-q4_k_m.gguf \
  `--host` 0.0.0.0 \
  `--port` 8080 \
  `--cors` "http://localhost:5173,https://chat.example.com" \
  `--api-key` "sk-put-a-real-random-string-here"

这里的 `--host` 0.0.0.0 表示监听所有网卡。如果只在服务器本机调用，建议改成 127.0.0.1；如果必须被其他机器访问，还需要结合防火墙限制来源 IP，不要把端口直接暴露给整个公网。

5. 快速验证清单

不带 Origin 头请求 /v1/models，确认服务正常返回 JSON。
带允许的 Origin 头请求，确认响应包含预期的 Access-Control-Allow-Origin 值。
带不允许的 Origin 头请求，用浏览器或 JS 端观察是否被拦截；curl 看不出浏览器拦截效果。
不带 Authorization 头请求 /v1/chat/completions，确认返回 401。
带正确的 Authorization: Bearer <your-key> 请求，确认返回 200 并输出正常内容。
检查启动日志中是否有异常报错，例如 CORS 参数解析失败或密钥为空。

以上步骤可以覆盖绝大多数本地开发和小规模部署场景。如果生产环境需要更细粒度的权限控制（例如按用户限流、不同 key 不同模型），llama-cpp-python 自带的参数通常不够用，这时应当在其前置接入 Nginx、Caddy 或专门的身份网关，由网关完成鉴权和跨域策略，再转发给 llama server。