一、架构概览

text

Claude Desktop (Windows)
    ↓ http://127.0.0.1:4000
Windows 端口转发 (netsh portproxy)
    ↓ 转发到 192.168.0.66:4000
LiteLLM (Ubuntu)
    ↓ http://192.168.0.66:8090/v1
llama.cpp (Ubuntu)
    ↓
Qwen 模型 (4×3090)

关键设计：

• Claude Desktop 强制要求 Gateway URL 使用 https 或 http://127.0.0.1（不允许局域网 IP）

• 通过 Windows 端口转发将 127.0.0.1:4000 → 192.168.0.66:4000，使 Claude Desktop 能以 HTTP 访问

• LiteLLM 运行在 HTTP 模式，无需自签名证书

• 完全禁用 LiteLLM 数据库计费模块，消除无关错误

---

二、环境要求

Ubuntu 服务器 (192.168.0.66)

• Ubuntu 25.10 / 其他 Linux 发行版

• NVIDIA 4×3090 GPU + 384GB RAM

• CUDA 已安装

• Python 3.13+（已测试 3.13）

• llama.cpp 源码（已编译 CUDA 版）

Windows 客户端

• Windows 10/11 或 Windows Server

• Claude Desktop App（从官网下载 exe 安装程序，非 Store 版）

• 管理员权限（用于端口转发）

• 网络互通（能 ping 通 Ubuntu 服务器）

---

三、Ubuntu 服务器端部署

3.1 编译并启动 llama.cpp

bash

# 克隆并编译
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
mkdir build && cd build
cmake .. -DGGML_CUDA=ON -DGGML_CUDA_F16=ON -DCMAKE_CUDA_ARCHITECTURES="86"
make -j $(nproc)

# 启动 server（4×3090 优化参数）
./server \
  -m /path/to/your/model.gguf \
  --host 0.0.0.0 \
  --port 8090 \
  -ngl 99 \
  -c 32768 \
  --batch-size 512 \
  --threads 64 \
  --gpu-split-mode layer

验证：

bash

curl http://192.168.0.66:8090/v1/models

3.2 创建 Python 虚拟环境并安装 LiteLLM

bash

mkdir -p ~/claude-gateway
cd ~/claude-gateway
python3.13 -m venv litellm-env
source litellm-env/bin/activate
pip install --upgrade pip
pip install litellm==1.89.0   # 或最新稳定版

3.3 配置 LiteLLM

创建配置文件 ~/claude-gateway/litellm_config.yaml：

yaml

model_list:
  - model_name: claude-3.5-sonnet
    litellm_params:
      model: openai/你的模型名称（与 llama.cpp 中返回的 id 一致）
      api_base: http://192.168.0.66:8090/v1
      api_key: dummy

general_settings:
  master_key: sk-shande-4x3090
  disable_spend_logs: true
  disable_prisma: true
  # 不要写 database_url

注意：model 字段中的 openai/ 前缀表示 LiteLLM 使用 OpenAI 兼容协议转发。模型名必须与 curl http://192.168.0.66:8090/v1/models 返回的 id 完全一致。

3.4 启动 LiteLLM（HTTP 模式，禁用数据库）

bash

# 确保未设置 DATABASE_URL 环境变量
unset DATABASE_URL

# 启动
litellm --config ~/claude-gateway/litellm_config.yaml \
  --port 4000 \
  --host 0.0.0.0 \
  --drop_params

验证：

bash

curl http://192.168.0.66:4000/v1/models -H "Authorization: Bearer sk-shande-4x3090"

应返回模型列表（id 为 claude-3.5-sonnet）。

---

四、Windows 客户端配置

4.1 配置端口转发（以管理员身份运行 CMD）

cmd

netsh interface portproxy add v4tov4 listenport=4000 listenaddress=127.0.0.1 connectport=4000 connectaddress=192.168.0.66

验证转发：

cmd

curl http://127.0.0.1:4000/v1/models -H "Authorization: Bearer sk-shande-4x3090"

4.2 配置 Claude Desktop

找到配置文件：

• 如果是从官网下载的 exe 安装版：C:\Users\你的用户名\AppData\Local\AnthropicClaude\claude_desktop_config.json

• 如果是 Store 版：在 %APPDATA%\Claude\ 或 %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\ 下，但建议用 exe 版。

编辑配置文件，添加 gateway 配置：

json

{
  "gateway": {
    "baseUrl": "http://127.0.0.1:4000",
    "apiKey": "sk-shande-4x3090",
    "authScheme": "bearer"
  }
}

如果文件已有其他内容，按 JSON 格式合并。

4.3 重启 Claude Desktop

完全退出 Claude Desktop（系统托盘右键 → 退出），再重新打开。

---

五、测试与验证

1. 测试 LiteLLM 直接调用（Windows CMD）：

   cmd

   curl http://127.0.0.1:4000/v1/chat/completions -H "Content-Type: application/json" -H "Authorization: Bearer sk-shande-4x3090" -d "{\"model\": \"claude-3.5-sonnet\", \"messages\": [{\"role\": \"user\", \"content\": \"你好\"}], \"max_tokens\": 50}"

2. 测试 Claude Desktop：在 Claude Desktop 输入框中发送任意消息，若返回模型回复则完全成功。

3. 检查 LiteLLM 日志：应显示 POST /v1/messages 请求，无数据库相关错误。

---

六、后台运行与开机自启

Ubuntu 端使用 tmux（推荐）

bash

# 启动 llama.cpp
tmux new -s llama
cd ~/claude-gateway/llama.cpp/build/bin
./server -m /path/to/model.gguf --host 0.0.0.0 --port 8090 -ngl 99 -c 32768 --batch-size 512 --threads 64 --gpu-split-mode layer

# 按 Ctrl+B D 退出，服务保持运行

# 启动 LiteLLM
tmux new -s litellm
cd ~/claude-gateway
source litellm-env/bin/activate
unset DATABASE_URL
litellm --config ./litellm_config.yaml --port 4000 --host 0.0.0.0 --drop_params

或使用 nohup

bash

nohup ./server ... > llama.log 2>&1 &
cd ~/claude-gateway
source litellm-env/bin/activate
nohup litellm --config ./litellm_config.yaml --port 4000 --host 0.0.0.0 --drop_params > litellm.log 2>&1 &

Windows 端口转发持久化

重启 Windows 后转发规则会丢失，可创建开机脚本（批处理）：

cmd

netsh interface portproxy add v4tov4 listenport=4000 listenaddress=127.0.0.1 connectport=4000 connectaddress=192.168.0.66

将其放入 启动 文件夹或使用任务计划程序。

---

七、常见问题与解决方案

7.1 LiteLLM 报 Prisma/Spend 错误

原因：数据库计费模块未完全关闭。
解决：

• 确保 unset DATABASE_URL 后启动

• 配置文件中包含 disable_spend_logs: true 和 disable_prisma: true

• 删除 litellm.db 文件（如果存在）

7.2 Claude Desktop 报 ERR_CONNECTION_REFUSED

原因：端口转发未生效或 LiteLLM 未启动。
检查：

cmd

curl http://127.0.0.1:4000/v1/models -H "Authorization: Bearer sk-shande-4x3090"

若不通，检查 LiteLLM 是否在运行，端口转发是否配置正确。

7.3 模型名不匹配

Claude Desktop 要求模型名与 LiteLLM 返回的 id 一致。在配置文件中指定 model_name: claude-3.5-sonnet，并确保 Claude Desktop 的 inferenceModels 中也使用相同名称。

7.4 模型推理慢

• 检查 llama.cpp 的 -ngl 参数是否充分利用 GPU

• 增大 --batch-size 和 --threads

• 确认 4 张 GPU 均被使用（nvidia-smi）

---

八、最终工作状态

组件	状态	备注
llama.cpp	正常	端口 8090，HTTP
LiteLLM	正常	端口 4000，HTTP，无数据库
Windows 端口转发	正常	127.0.0.1:4000 → 192.168.0.66:4000
Claude Desktop	正常	Gateway URL: http://127.0.0.1:4000
消息往返	成功	已测试中文回复

---

九、附录：完整命令速查

Ubuntu 端

bash

# 启动 llama.cpp
cd ~/claude-gateway/llama.cpp/build/bin
./server -m /path/to/model.gguf --host 0.0.0.0 --port 8090 -ngl 99 -c 32768 --batch-size 512 --threads 64 --gpu-split-mode layer

# 启动 LiteLLM
cd ~/claude-gateway
source litellm-env/bin/activate
unset DATABASE_URL
litellm --config ~/claude-gateway/litellm_config.yaml --port 4000 --host 0.0.0.0 --drop_params

Windows 端

cmd

# 端口转发
netsh interface portproxy add v4tov4 listenport=4000 listenaddress=127.0.0.1 connectport=4000 connectaddress=192.168.0.66

# 测试
curl http://127.0.0.1:4000/v1/models -H "Authorization: Bearer sk-shande-4x3090"

---

结束😊。