客户中心
网站
简体中文
← 知识库

在 VPS 上部署 LiteLLM 私有模型 API 网关

LiteLLM 为应用提供通向受支持模型服务商的统一网关。它可提供稳定的模型别名,避免后端变更时逐一修改客户端。此精简示例不使用数据库,通过主密钥认证,并将请求转发至私有 Ollama 模型。

目标环境: Ubuntu Server 24.04 LTS、x86-64、SSH 和 sudo 账户。文档审核日期:2026 年 11 月 15 日。命令尚未在 Ubuntu 上完成端到端测试。

开始之前

小型本地模型评估可预留约 2 个 vCPU、4 GB 内存和 10 GB 磁盘;更大模型需要更多资源。调用外部推理的网关可能需要更少模型内存。此方案不包含数据库支持的虚拟密钥、预算或开销追踪,不能声称它能强制限制费用。

这些资源数值仅为小规模评估的规划估算,不是性能保证或套餐规格。VPS/VDS 不代表包含 GPU。下单前请检查可用内存、存储和其他资源。

全新 Ubuntu 可使用以下软件包。如果 Docker 已从其他仓库安装,请保留并先检查兼容性,不要混用 Docker CE 和 docker.io 软件包。使用 Compose v2;缺少软件包时,请检查是否启用 Ubuntu Universe。

sudo apt update
sudo apt install -y docker.io docker-compose-v2 curl openssl
sudo systemctl enable --now docker
sudo docker compose version

所有示例仅将端口发布到服务器的 127.0.0.1。请从本机通过 SSH 隧道访问,无需域名。不要将这些端口开放到互联网。容器内部监听 0.0.0.0 不会改变宿主机端口仅绑定回环地址的事实。

以下项目均为全新安装。不要对现有部署重新执行密钥生成步骤。

1. 定义网关和模型别名

创建私有密钥文件,按示例保存 config.yaml 与 compose.yaml。后端仅能在此 Compose 网络内访问。网关只开放本地端口 4000。

umask 077
mkdir -p ~/ai-litellm
cd ~/ai-litellm
printf 'LITELLM_MASTER_KEY=sk-%s\n' "$(openssl rand -hex 32)" > .env
model_list:
  - model_name: local-small
    litellm_params:
      model: ollama_chat/qwen2.5:0.5b
      api_base: http://ollama:11434
general_settings:
  master_key: os.environ/LITELLM_MASTER_KEY
services:
  ollama:
    image: ollama/ollama:latest
    restart: unless-stopped
    environment:
      OLLAMA_NUM_PARALLEL: "1"
      OLLAMA_CONTEXT_LENGTH: "2048"
    volumes:
      - models:/root/.ollama
  gateway:
    image: docker.litellm.ai/berriai/litellm:latest
    restart: unless-stopped
    env_file: .env
    command: ["--config", "/app/config.yaml", "--port", "4000"]
    ports:
      - "127.0.0.1:4000:4000"
    volumes:
      - ./config.yaml:/app/config.yaml:ro
    depends_on:
      - ollama
volumes:
  models:

2. 启动并验证授权

在 VPS 上运行以下命令。第一个请求故意不带密钥,应返回 HTTP 401。模型加载后,获授权请求应返回包含生成结果的 JSON。如果无认证请求成功,请停止服务并修正网关配置,再使用真实提示词。

sudo docker compose up -d
sudo docker compose exec ollama ollama pull qwen2.5:0.5b
curl -s -o /dev/null -w '%{http_code}
' http://127.0.0.1:4000/v1/models
set -a
. ./.env
set +a
curl --fail-with-body --max-time 180 http://127.0.0.1:4000/v1/chat/completions   -H "Authorization: Bearer $LITELLM_MASTER_KEY"   -H 'Content-Type: application/json'   -d '{"model":"local-small","messages":[{"role":"user","content":"Say hello in five words."}],"max_tokens":80}'
unset LITELLM_MASTER_KEY

3. 连接客户端并规划下一阶段

在本机使用 SSH 隧道,基础 URL 为 http://127.0.0.1:4000/v1,模型为 local-small。主密钥由运维人员保管,不要分发给多个不受信任的用户。团队使用时,应加入受支持的数据库虚拟密钥配置、检查每个密钥的范围,并单独保护管理端点。外部服务商的额度必须在其平台设置;无数据库网关不能可靠限制预算。请备份配置和 .env;以后添加数据库时,也要制作一致性备份。

ssh -N -L 127.0.0.1:4000:127.0.0.1:4000 YOUR_USER@YOUR_SERVER_IP

更新与恢复

升级前停止应用以制作一致性备份,将数据和密钥保留在 VPS 之外,并在独立实例测试恢复。示例中的浮动镜像标签用于初期评估;长期使用前请固定已审核的版本或摘要。可通过 sudo docker image inspect IMAGE_NAME --format '{{json .RepoDigests}}' 记录当前摘要。不要在未检查兼容性时无人值守升级,也不要用 down -v 删除持久卷。

启动失败时,请检查 sudo docker compose ps、近期日志、剩余磁盘和内存。不要分享包含密钥、提示词或个人数据的日志。目录权限出错时,应核对预期 UID/GID 与所有权,不要授予 777。共享访问前请配置 HTTPS、认证和请求限制。

相关部署