跳到主要内容
生长的档案
← 返回期刊架
NO.2026-0032026.09.0422 MIN READ

Debian 12 VPS 部署 Groq → LiteLLM → Caddy API 反代全流程

大模型API反代部署

适用环境：Debian GNU/Linux 12 (bookworm)、x86_64 VPS
架构：客户端 → Cloudflare DNS（可选代理）→ Caddy → LiteLLM → Groq API
LiteLLM 负责统一 OpenAI 兼容 API，并为后续增加 OpenAI、Anthropic、Gemini 等上游 API 预留统一入口。

1. 最终架构

Client
  │
  │ https://llm.example.com/v1/...
  ▼
Cloudflare DNS / Proxy（可选）
  │
  ▼
Caddy :443
  │
  ▼
LiteLLM :4000
  │
  ▼
Groq API
https://api.groq.com/openai/v1

建议：

  • LiteLLM 只负责 API 网关、模型映射和统一 OpenAI 兼容接口。
  • Caddy 负责 HTTPS/TLS、域名入口和反向代理。
  • Groq API Key 只保存在 VPS。
  • 客户端只使用 LiteLLM Master Key。
  • 后续增加其他 AI 平台时，只需增加 LiteLLM 的模型配置。

2. 确认系统

cat /etc/os-release

预期：

PRETTY_NAME="Debian GNU/Linux 12 (bookworm)"

确认架构：

uname -m

x86 VPS 通常显示：

x86_64

3. 更新系统并安装基础工具

apt update && apt upgrade -y

安装常用工具：

apt install -y \
  curl \
  wget \
  ca-certificates \
  gnupg \
  lsb-release \
  nano \
  ufw

4. 安装 Docker

添加 Docker 官方仓库：

install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/debian/gpg \
  -o /etc/apt/keyrings/docker.asc

chmod a+r /etc/apt/keyrings/docker.asc

添加仓库：

echo \
  "deb [arch=$(dpkg --print-architecture) \
  signed-by=/etc/apt/keyrings/docker.asc] \
  https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
  | tee /etc/apt/sources.list.d/docker.list > /dev/null

更新：

apt update

安装 Docker：

apt install -y \
  docker-ce \
  docker-ce-cli \
  containerd.io \
  docker-buildx-plugin \
  docker-compose-plugin

验证：

docker --version
docker compose version

启动：

systemctl enable --now docker

5. 为什么使用 Docker 部署 LiteLLM

Docker 的主要优势：

环境隔离

LiteLLM 运行所需的 Python、依赖库和版本全部封装在容器内。

不会污染 Debian 系统 Python 环境。

升级方便

更新镜像：

docker compose pull
docker compose up -d

重建方便

配置出问题时：

docker compose down
docker compose up -d

环境变量管理方便

API Key 可以放在 .env：

GROQ_API_KEY=...

不需要写入配置文件。

需要注意的影响

Docker 会增加少量：

  • 内存占用
  • 磁盘镜像占用
  • 网络层复杂度

对于 API 反代场景，这些开销通常非常小。

6. 创建 LiteLLM 目录

mkdir -p /opt/litellm
cd /opt/litellm

7. 创建 .env

创建：

nano /opt/litellm/.env

填写：

GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

LITELLM_MASTER_KEY=sk-your-random-master-key

生成一个随机 Master Key：

openssl rand -hex 32

然后保存。

限制权限：

chmod 600 /opt/litellm/.env

8. 创建 LiteLLM 配置

创建：

nano /opt/litellm/config.yaml

配置 Groq 模型：

model_list:

  # OpenAI GPT OSS 120B
  - model_name: groq-gpt-oss-120b
    litellm_params:
      model: groq/openai/gpt-oss-120b
      api_key: os.environ/GROQ_API_KEY

  # OpenAI GPT OSS 20B
  - model_name: groq-gpt-oss-20b
    litellm_params:
      model: groq/openai/gpt-oss-20b
      api_key: os.environ/GROQ_API_KEY

  # Qwen 3.8 27B
  - model_name: groq-qwen3.8-27b
    litellm_params:
      model: groq/qwen/qwen3.8-27b
      api_key: os.environ/GROQ_API_KEY

  # Qwen 3.6 27B
  - model_name: groq-qwen3.6-27b
    litellm_params:
      model: groq/qwen/qwen3.6-27b
      api_key: os.environ/GROQ_API_KEY

  # Groq Compound
  - model_name: groq-compound
    litellm_params:
      model: groq/groq/compound
      api_key: os.environ/GROQ_API_KEY

  # Groq Compound Mini
  - model_name: groq-compound-mini
    litellm_params:
      model: groq/groq/compound-mini
      api_key: os.environ/GROQ_API_KEY

说明：

左侧：

groq-gpt-oss-20b

是客户端看到的统一模型名称。

右侧：

groq/openai/gpt-oss-20b

是 LiteLLM 调用 Groq 时使用的 provider/model 标识。

9. 创建 Docker Compose

创建：

nano /opt/litellm/docker-compose.yml

内容：

services:
  litellm:
    image: ghcr.io/berriai/litellm:main-latest
    container_name: litellm

    restart: unless-stopped

    env_file:
      - .env

    volumes:
      - ./config.yaml:/app/config.yaml:ro

    # 使用 VPS 宿主机网络
    network_mode: host

    command:
      - "--config"
      - "/app/config.yaml"

启动：

cd /opt/litellm
docker compose up -d

查看：

docker compose ps

日志：

docker logs -f litellm

正常情况下会看到：

Uvicorn running on http://0.0.0.0:4000

10. 验证 LiteLLM 本地服务

确认端口：

ss -ltnp | grep ':4000'

访问首页：

curl -I http://127.0.0.1:4000/

获取模型：

set -a
source /opt/litellm/.env
set +a

curl http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

测试 Chat Completions：

curl http://127.0.0.1:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -d '{
    "model": "groq-gpt-oss-20b",
    "messages": [
      {
        "role": "user",
        "content": "Reply with OK"
      }
    ],
    "max_tokens": 100
  }'

预期：

{
  "choices": [
    {
      "message": {
        "content": "OK"
      }
    }
  ]
}

11. Groq API Key 故障排查

如果 LiteLLM 返回：

Invalid API Key

首先确认 VPS 当前环境变量：

printf '%s' "$GROQ_API_KEY" | sha256sum

检查 .env：

grep '^GROQ_API_KEY=' /opt/litellm/.env \
  | cut -d= -f2- \
  | tr -d '\r\n' \
  | sha256sum

检查容器：

docker exec litellm sh -c 'printf "%s" "$GROQ_API_KEY"' \
  | sha256sum

如果 .env 和容器一致，但宿主机不同，通常说明当前 Shell 中使用的是旧环境变量。

重新加载：

cd /opt/litellm
set -a
source .env
set +a

直接测试 Groq：

curl -i https://api.groq.com/openai/v1/models \
  -H "Authorization: Bearer $GROQ_API_KEY"

如果返回：

HTTP/2 200

说明 Key 本身有效。

如果容器需要验证：

docker exec litellm python -c '
import os
import httpx

r = httpx.get(
    "https://api.groq.com/openai/v1/models",
    headers={
        "Authorization": "Bearer " + os.environ["GROQ_API_KEY"]
    },
    timeout=30
)

print("STATUS:", r.status_code)
print("BODY:", r.text[:500])
'

12. 安装 Caddy

安装：

apt install -y caddy

启动：

systemctl enable --now caddy

查看：

systemctl status caddy --no-pager

13. 配置 Caddy 反向代理

编辑：

nano /etc/caddy/Caddyfile

建议最终配置类似：

llm.example.com {
    reverse_proxy 127.0.0.1:4000
}

将：

llm.example.com

替换成实际域名，例如：

llm.1463298.xyz

完整示例：

llm.1463298.xyz {
    reverse_proxy 127.0.0.1:4000
}

Caddy 会自动：

  • 监听 HTTPS
  • 申请证书
  • 自动续期
  • HTTP 自动跳转 HTTPS

格式化：

caddy fmt --overwrite /etc/caddy/Caddyfile

验证：

caddy validate --config /etc/caddy/Caddyfile

重载：

systemctl reload caddy

14. 如果 Caddy 报 443 被占用

检查：

ss -ltnp | grep -E ':80|:443'

如果看到其他程序占用：

*:443

Caddy 无法监听 HTTPS。

例如：

xray
nginx
apache2

都可能占用 443。

需要修改对应服务端口，或者停止对应服务。

再次检查：

ss -ltnp | grep -E ':80|:443'

理想状态：

*:80   caddy
*:443  caddy

然后：

systemctl reload caddy

15. Cloudflare DNS 配置

在 Cloudflare 创建：

Type: A
Name: llm
Content: VPS IPv4

例如：

llm.1463298.xyz

是否开启橙云？

灰云

DNS only

客户端直接访问 VPS。

优点：

  • 链路简单
  • 适合 API
  • 没有 Cloudflare Proxy 的请求限制影响

橙云

Proxied

客户端 → Cloudflare → VPS。

优点：

  • 隐藏 VPS IP
  • 获得 Cloudflare 网络保护
  • 可使用部分 Cloudflare 安全能力

对于普通 API 反代，两种都可以。

如果使用橙云，需要确认你的 API 流量符合 Cloudflare 当前计划和代理规则。

16. Cloudflare SSL/TLS

建议：

SSL/TLS encryption mode:
Full (strict)

Full (strict) 的含义：

Cloudflare → VPS 之间也必须使用有效 TLS。

这里的 TLS 设置通常是域名/Zone 级别配置，不只是顶级域名。

Caddy 自动申请的公开证书可以满足严格模式。

不要使用：

Flexible

因为 Flexible 会导致 Cloudflare 到源站可能使用 HTTP，并容易造成重定向或安全问题。

17. UFW 防火墙

先查看：

ufw status

如果启用 UFW，放行 SSH：

ufw allow 22/tcp

放行 HTTP：

ufw allow 80/tcp

放行 HTTPS：

ufw allow 443/tcp

如果你的其他服务需要端口，例如：

ufw allow 30635/tcp
ufw allow 23116/tcp

启用：

ufw enable

查看：

ufw status numbered

注意：

LiteLLM 使用了：

4000

如果 Caddy 和 LiteLLM 在同一 VPS，并且 LiteLLM 只作为 Caddy 后端，通常不建议对公网开放 4000。

18. 验证 HTTPS

curl -I https://llm.example.com

正常可能看到：

HTTP/2 200
server: uvicorn
via: 1.1 Caddy

获取模型：

curl https://llm.example.com/v1/models \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

测试模型：

curl https://llm.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -d '{
    "model": "groq-gpt-oss-20b",
    "messages": [
      {
        "role": "user",
        "content": "Reply with OK"
      }
    ]
  }'

如果返回：

{
  "choices": [
    {
      "message": {
        "content": "OK"
      }
    }
  ]
}

说明完整链路已经成功：

Client
  ↓
HTTPS Domain
  ↓
Caddy
  ↓
LiteLLM
  ↓
Groq

19. 常用运维命令

进入目录：

cd /opt/litellm

查看状态：

docker compose ps

查看日志：

docker logs -f litellm

重启：

docker compose restart

配置修改后重建：

docker compose up -d --force-recreate

停止：

docker compose down

更新 LiteLLM：

docker compose pull
docker compose up -d

查看 Caddy：

systemctl status caddy --no-pager

重载 Caddy：

systemctl reload caddy

查看 Caddy 日志：

journalctl -u caddy -f

20. 后续增加其他 AI 平台

LiteLLM 的优势是后续可以继续增加：

  • OpenAI
  • Anthropic
  • Google Gemini
  • DeepSeek
  • OpenRouter
  • Azure OpenAI
  • 其他 OpenAI Compatible API

最终客户端保持统一：

https://llm.example.com/v1

只需要在 LiteLLM 中增加新的：

model_name

和对应 provider 配置即可。

例如客户端始终调用：

/v1/chat/completions

切换模型：

{
  "model": "your-model-name"
}

不需要让客户端分别处理每个平台的 API 地址和认证方式。

21. 最终检查清单

LiteLLM

docker compose ps

应为：

Up

4000 端口

ss -ltnp | grep ':4000'

Caddy

systemctl status caddy --no-pager

应为：

active (running)

80 / 443

ss -ltnp | grep -E ':80|:443'

通常应由 Caddy 监听。

本地 API

curl http://127.0.0.1:4000/v1/models \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

公网 API

curl https://llm.example.com/v1/models \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY"

模型调用

curl https://llm.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_MASTER_KEY" \
  -d '{
    "model": "groq-gpt-oss-20b",
    "messages": [
      {
        "role": "user",
        "content": "Reply with OK"
      }
    ]
  }'

22. 当前推荐架构总结

Internet
    │
    ▼
Cloudflare
    │
    ▼
Caddy :443
    │
    ▼
LiteLLM :4000
    │
    ├── Groq
    ├── OpenAI（未来）
    ├── Gemini（未来）
    ├── Anthropic（未来）
    └── 其他 API（未来）

这是一个适合低负载、多 AI Provider、统一 OpenAI 兼容 API 的部署方案。

建议后续进一步完善：

  1. LiteLLM 不直接暴露公网 4000。
  2. 为不同客户端创建独立 API Key。
  3. 增加速率限制。
  4. 定期更新 Docker 镜像。
  5. 备份 /opt/litellm/config.yaml。
  6. 不要把 .env 上传到 GitHub。
  7. Cloudflare 使用 Full (strict)。

COMMENTS / 评论

评论系统尚未开放。你可以通过 来访登记 直接与我联系。