构建AI网关：自建反向代理实现主流大语言模型本地化调用-平芜编程栈

在实际 AI 应用开发和学习过程中，我们经常需要接触和测试不同的前沿大语言模型，例如 Anthropic 的 Claude、Google 的 Gemini 以及 OpenAI 的 GPT 系列。然而，对于国内开发者而言，直接访问这些模型的官方服务常常会遇到网络限制、地区不支持或付费门槛等问题。这导致许多人在尝试新模型特性、进行技术选型或构建个人 AI 工具时遇到阻碍。

本文将聚焦于一个核心目标：如何在合规且稳定的前提下，为国内的开发者和技术爱好者搭建一个能够体验和调用主流大语言模型（如 Claude、Gemini、GPT）的本地化或代理环境。我们将从技术原理入手，探讨几种可行的技术方案，然后通过具体的配置步骤，指导你构建一个可用的开发测试环境。整个过程将严格遵循软件工程的最佳实践，确保方案的可持续性和可维护性，而非依赖任何临时性或存在风险的“破解”手段。最终，你将获得一个可以用于代码生成、技术问答、文本分析等场景的本地 AI 助手集合。

1. 理解核心挑战与技术选型思路

在开始动手之前，我们必须清晰地认识到当前面临的主要技术挑战，这决定了后续方案的设计。

1.1 主要访问障碍分析

对于 Claude、Gemini 和 GPT 等国外 AI 服务，国内用户通常遇到以下几类问题：

网络限制与地区封锁：这是最普遍的问题。许多服务的 API 端点或 Web 界面直接屏蔽了来自中国大陆的 IP 地址。错误信息通常为 “isn’t currently supported in your country” 或 “failed to sign in”。
账号注册与验证：部分服务（如某些 Claude 版本）对新用户注册有严格限制，或需要海外手机号进行验证。GPT 账号注册也可能因支付方式等问题变得复杂。
客户端兼容性：官方推出的桌面应用（如 Claude Desktop）或 IDE 插件（如 Claude Code）可能在特定网络环境下无法正常连接其后端服务，提示 “this client is no longer supported” 或连接超时。
API 密钥获取与付费：即使是提供了 API 的服务，获取有效的 API Key 也可能需要绑定海外信用卡并面临付费问题。

1.2 可行的技术方案对比

针对以上挑战，在合规前提下，主要有以下几种技术思路：

方案类型	核心原理	优点	缺点	适用场景
反向代理/API 中转服务	在海外或可访问区域部署一个服务器，接收国内请求，转发至官方 API，再将结果返回。	稳定性高，可复用，支持所有官方 API 功能。	需要自有海外服务器，涉及运维成本。	团队开发、需要稳定生产级调用的场景。
使用第三方聚合平台	利用一些平台（需谨慎选择合规、信誉好的）提供的聚合 API，它们已处理好底层访问问题。	开箱即用，无需自建设施。	依赖第三方服务，可能存在速率限制、费用或隐私顾虑。	个人学习、快速原型验证。
本地模型替代	在本地部署开源大模型（如 Llama、Qwen、DeepSeek 等），通过其提供的兼容 OpenAI API 的接口进行调用。	完全本地化，无网络问题，数据隐私性最强。	对本地硬件（GPU）有要求，模型能力可能与顶级闭源模型有差距。	对数据隐私要求极高、或进行特定领域微调的场景。
浏览器插件与本地客户端配置	通过修改浏览器代理设置，或配置本地客户端（如 Claude Desktop）使用自定义代理，使其流量经由可访问的线路。	可直接使用官方 UI，体验完整。	配置较为繁琐，稳定性依赖于代理线路，不适合集成到自有应用中。	个人体验、非编程交互式使用。

对于开发者而言，方案一（自建反向代理）和方案三（本地模型替代）是最具可控性和学习价值的。本文将重点介绍方案一的实现细节，并简要说明如何将本地模型接入同一套调用框架。

2. 环境准备与基础依赖

我们选择自建反向代理方案作为核心实现。这个方案不涉及修改任何官方客户端，而是构建一个属于自己的、符合规范的 API 网关。

2.1 服务器与域名准备

你需要准备以下资源：

一台海外 VPS（虚拟专用服务器）：选择位于美国、日本、新加坡等地区的云服务商，如 AWS Lightsail、Google Cloud、DigitalOcean、Vultr 等。配置无需太高，1核1GB内存足以应对个人或小团队的测试流量。确保该 VPS 可以正常访问api.openai.com,api.anthropic.com,generativelanguage.googleapis.com等目标服务的域名。
一个域名（可选但推荐）：拥有自己的域名可以方便地配置 SSL 证书（HTTPS），并且使你的 API 端点更易于管理和记忆。你可以从任何域名注册商处购买。
SSH 客户端：用于连接和管理你的 VPS，如 macOS/Linux 的终端，或 Windows 下的 PuTTY、Windows Terminal。

2.2 服务器基础环境配置

通过 SSH 连接到你的 VPS，执行以下命令进行基础环境配置。

更新系统并安装必要工具：

# 以 Ubuntu 22.04 为例 sudo apt update && sudo apt upgrade -y sudo apt install -y curl wget git vim net-tools

安装 Node.js 环境（我们将使用 Node.js 编写一个简单的转发服务）：

# 使用 NodeSource 安装 LTS 版本的 Node.js curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash - sudo apt install -y nodejs # 验证安装 node --version npm --version

2.3 项目初始化

在服务器上创建一个项目目录：

mkdir ~/ai-proxy && cd ~/ai-proxy npm init -y

安装必要的 npm 包。我们将使用express作为 Web 框架，http-proxy-middleware来创建反向代理，dotenv管理环境变量，cors处理跨域请求。

npm install express http-proxy-middleware dotenv cors

3. 构建多模型 API 反向代理服务

我们的目标是创建一个统一的 API 端点，根据请求路径，将流量转发到对应的官方 API。

3.1 项目结构与核心代码

在项目根目录下创建以下文件：

ai-proxy/ ├── .env ├── .gitignore ├── package.json ├── server.js └── config.js

首先，创建.env文件来存储敏感信息和配置。切记不要将此文件提交到版本控制系统。

# .env # 服务监听端口 PORT=3000 # OpenAI GPT API 配置 (如果你有有效的 API Key) OPENAI_API_KEY=sk-your-openai-api-key-here # OpenAI API 基础URL，通常不需要改，除非你用第三方代理 OPENAI_BASE_URL=https://api.openai.com # Anthropic Claude API 配置 ANTHROPIC_API_KEY=sk-ant-your-claude-api-key-here ANTHROPIC_BASE_URL=https://api.anthropic.com # Google Gemini API 配置 GEMINI_API_KEY=your-gemini-api-key-here # Gemini API 基础URL GEMINI_BASE_URL=https://generativelanguage.googleapis.com # 你的代理服务密钥（用于简单鉴权，防止滥用） PROXY_AUTH_KEY=your-secure-proxy-auth-key

接下来，创建config.js来读取和管理配置：

// config.js require('dotenv').config(); const config = { port: process.env.PORT || 3000, openai: { apiKey: process.env.OPENAI_API_KEY, baseUrl: process.env.OPENAI_BASE_URL || 'https://api.openai.com', }, anthropic: { apiKey: process.env.ANTHROPIC_API_KEY, baseUrl: process.env.ANTHROPIC_BASE_URL || 'https://api.anthropic.com', }, gemini: { apiKey: process.env.GEMINI_API_KEY, baseUrl: process.env.GEMINI_BASE_URL || 'https://generativelanguage.googleapis.com', }, proxyAuthKey: process.env.PROXY_AUTH_KEY, }; // 检查必要配置 if (!config.proxyAuthKey) { console.warn('警告: PROXY_AUTH_KEY 未设置，服务将运行在无鉴权模式，存在安全风险。'); } module.exports = config;

最后，创建核心服务文件server.js：

// server.js const express = require('express'); const { createProxyMiddleware } = require('http-proxy-middleware'); const cors = require('cors'); const config = require('./config'); const app = express(); // 1. 全局中间件 app.use(cors()); // 允许跨域请求，根据需求可配置具体来源 app.use(express.json()); // 解析 JSON 请求体 // 2. 简易鉴权中间件（可选，但推荐） const authMiddleware = (req, res, next) => { const authKey = req.headers['x-proxy-auth-key']; if (!config.proxyAuthKey || authKey === config.proxyAuthKey) { next(); } else { res.status(401).json({ error: '未授权的访问' }); } }; app.use(authMiddleware); // 3. 健康检查端点 app.get('/health', (req, res) => { res.json({ status: 'ok', service: 'ai-proxy' }); }); // 4. 配置 OpenAI GPT 代理 if (config.openai.apiKey) { app.use('/v1/openai', createProxyMiddleware({ target: config.openai.baseUrl, changeOrigin: true, pathRewrite: { '^/v1/openai': '/v1', // 将 /v1/openai 重写为 /v1 }, headers: { 'Authorization': `Bearer ${config.openai.apiKey}`, }, onProxyReq: (proxyReq, req, res) => { // 可以在这里添加日志或修改请求 console.log(`[OpenAI Proxy] 转发请求到: ${proxyReq.path}`); }, })); console.log('OpenAI GPT 代理已启用，端点: /v1/openai'); } else { console.log('OpenAI GPT 代理未配置 (OPENAI_API_KEY 缺失)'); } // 5. 配置 Anthropic Claude 代理 if (config.anthropic.apiKey) { app.use('/v1/claude', createProxyMiddleware({ target: config.anthropic.baseUrl, changeOrigin: true, pathRewrite: { '^/v1/claude': '/v1', // 将 /v1/claude 重写为 /v1 }, headers: { 'x-api-key': config.anthropic.apiKey, 'anthropic-version': '2023-06-01', // 指定 Claude API 版本 }, })); console.log('Anthropic Claude 代理已启用，端点: /v1/claude'); } else { console.log('Anthropic Claude 代理未配置 (ANTHROPIC_API_KEY 缺失)'); } // 6. 配置 Google Gemini 代理 if (config.gemini.apiKey) { app.use('/v1/gemini', createProxyMiddleware({ target: config.gemini.baseUrl, changeOrigin: true, pathRewrite: (path, req) => { // Gemini API 路径格式特殊，需要处理 const newPath = path.replace('/v1/gemini', ''); // 将 API Key 作为查询参数附加，这是 Gemini API 的要求之一 return `${newPath}?key=${config.gemini.apiKey}`; }, })); console.log('Google Gemini 代理已启用，端点: /v1/gemini'); } else { console.log('Google Gemini 代理未配置 (GEMINI_API_KEY 缺失)'); } // 7. 启动服务 app.listen(config.port, () => { console.log(`AI 代理服务运行在 http://localhost:${config.port}`); console.log(`健康检查: http://localhost:${config.port}/health`); });

3.2 关键配置与原理解释

这段代码构建了一个简单的 Express 服务，其核心是http-proxy-middleware中间件。我们来分解关键部分：

路径重写 (pathRewrite)：这是代理的核心。当你的客户端请求http://你的服务器/v1/openai/chat/completions时，代理中间件会将路径重写为https://api.openai.com/v1/chat/completions，从而实现无缝转发。
请求头注入 (headers)：我们将各自服务所需的 API Key 通过请求头（OpenAI、Claude）或查询参数（Gemini）的方式，在代理层自动添加。这意味着你的客户端代码无需存储和发送这些敏感的 API Key，只需向你的代理服务器发送请求，并附上你自己的代理鉴权密钥即可，大大提升了前端/客户端的安全性。
变更来源 (changeOrigin: true)：这个选项会将代理请求的Host头修改为目标服务器的域名，这对于许多基于域名进行验证的 API 服务是必要的。
简易鉴权 (authMiddleware)：我们添加了一个简单的基于请求头的鉴权机制。客户端需要在请求头中携带X-Proxy-Auth-Key，其值与你设置在.env中的PROXY_AUTH_KEY一致。这可以防止你的代理服务被他人滥用。

4. 部署、运行与验证

4.1 启动服务与进程管理

在服务器上，进入项目目录，启动服务：

cd ~/ai-proxy node server.js

你应该看到类似以下的输出，表明服务已启动，并且根据你配置的 API Key 启用了相应的代理端点：

AI 代理服务运行在 http://localhost:3000 健康检查: http://localhost:3000/health OpenAI GPT 代理已启用，端点: /v1/openai Anthropic Claude 代理未配置 (ANTHROPIC_API_KEY 缺失) Google Gemini 代理已启用，端点: /v1/gemini

为了让服务在后台持续运行，推荐使用pm2这样的进程管理器。

# 全局安装 pm2 sudo npm install -g pm2 # 使用 pm2 启动服务，并设置进程名 pm2 start server.js --name ai-proxy # 设置开机自启 pm2 startup pm2 save # 查看服务状态和日志 pm2 status ai-proxy pm2 logs ai-proxy

4.2 配置域名与 HTTPS（生产环境必备）

为了通过域名安全访问（HTTPS），你需要配置 Nginx 作为反向代理，并申请 SSL 证书。

安装 Nginx：
```
sudo apt install -y nginx
```

配置 Nginx：编辑/etc/nginx/sites-available/ai-proxy

server { listen 80; server_name your-domain.com; # 替换为你的域名 location / { proxy_pass http://localhost:3000; # 指向我们运行的 Node.js 服务 proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

创建符号链接并测试配置：

sudo ln -s /etc/nginx/sites-available/ai-proxy /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx

申请 SSL 证书：使用 Certbot 免费申请 Let‘s Encrypt 证书。
```
sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.com
```
Certbot 会自动修改 Nginx 配置，启用 HTTPS 并设置自动续期。

4.3 客户端调用验证

服务部署成功后，你可以使用curl命令或任何 HTTP 客户端（如 Postman）进行测试。假设你的域名是https://api.your-domain.com，代理鉴权密钥是my-secret-key-123。

测试健康检查：

curl https://api.your-domain.com/health

预期返回：{"status":"ok","service":"ai-proxy"}

测试 OpenAI GPT 代理（示例调用 chat/completions）：

curl -X POST https://api.your-domain.com/v1/openai/chat/completions \ -H "Content-Type: application/json" \ -H "X-Proxy-Auth-Key: my-secret-key-123" \ -d '{ "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "Hello, world!"}], "max_tokens": 50 }'

如果配置正确，你将收到来自 OpenAI API 的响应。

测试 Google Gemini 代理（示例调用 generateContent）：Gemini API 的路径需要特别注意。根据官方文档，调用generateContent的端点是/v1beta/models/gemini-pro:generateContent。

curl -X POST https://api.your-domain.com/v1/gemini/v1beta/models/gemini-pro:generateContent \ -H "Content-Type: application/json" \ -H "X-Proxy-Auth-Key: my-secret-key-123" \ -d '{ "contents": [{ "parts": [{"text": "Write a story about a magic backpack."}] }] }'

注意，我们的代理配置已经通过pathRewrite函数将 API Key 作为查询参数附加，所以你无需在请求头或数据体中再次添加。

5. 集成到开发环境与常见应用

5.1 在代码中调用你的代理

现在，你可以在任何支持 HTTP 请求的编程语言中，将原本指向官方 API 的地址替换为你的代理地址，并添加鉴权头。

Python 示例 (使用 requests)：

import requests import json PROXY_URL = "https://api.your-domain.com" PROXY_AUTH_KEY = "my-secret-key-123" OPENAI_ENDPOINT = f"{PROXY_URL}/v1/openai/chat/completions" headers = { "Content-Type": "application/json", "X-Proxy-Auth-Key": PROXY_AUTH_KEY } data = { "model": "gpt-3.5-turbo", "messages": [{"role": "user", "content": "用Python写一个快速排序函数。"}], "temperature": 0.7 } response = requests.post(OPENAI_ENDPOINT, headers=headers, json=data) print(response.json())

Node.js / JavaScript 示例 (使用 fetch)：

const PROXY_URL = 'https://api.your-domain.com'; const PROXY_AUTH_KEY = 'my-secret-key-123'; async function callClaudeViaProxy(prompt) { const response = await fetch(`${PROXY_URL}/v1/claude/messages`, { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Proxy-Auth-Key': PROXY_AUTH_KEY, }, body: JSON.stringify({ model: 'claude-3-haiku-20240307', max_tokens: 1024, messages: [{ role: 'user', content: prompt }] }) }); return await response.json(); }

5.2 配置 IDE 插件（如 VS Code 的 Claude Code）

许多 IDE 插件允许你配置自定义的 API 端点。以 Claude Code 插件为例，虽然其官方可能不直接提供设置项，但你可以通过设置系统环境变量HTTPS_PROXY或HTTP_PROXY来让插件流量经过你的代理服务器。然而，这种方法可能不总是有效，因为插件可能使用硬编码的端点。

一个更通用的方法是不使用官方插件，而是寻找支持自定义 API 基址 (Base URL) 的开源替代品，或者使用支持该功能的通用 AI 助手插件。例如，一些基于Continue或Cursor规则的开源插件，通常允许你在设置中指定 API 的完整 URL，这时你就可以填入https://api.your-domain.com/v1/claude。

5.3 处理“地区不支持”的 Web 应用

对于 Gemini 网页版等提示“地区不支持”的服务，上述 API 代理方案是给开发者调用的。对于普通网页访问，技术上可以通过浏览器配置全局代理或使用浏览器插件（如 SwitchyOmega）将特定域名（如*.googleapis.com）的流量指向你的代理服务器。但请注意，这通常违反服务商的使用条款，且配置复杂、稳定性差，不推荐用于生产或重要用途。对于学习和测试，更好的方式是专注于 API 集成。

6. 常见问题排查与优化

在搭建和使用过程中，你可能会遇到以下问题。

6.1 服务启动与连接问题

问题现象	可能原因	检查与解决步骤
`node server.js`报错`Error: Cannot find module ‘xxx’`	依赖未安装或项目路径错误。	1. 在项目根目录执行`npm install`。 2. 检查`package.json`和`node_modules`是否存在。
服务启动成功，但`curl localhost:3000/health`无响应或连接被拒绝。	防火墙阻止了端口访问，或服务未正确监听。	1. 检查服务是否真的在运行：`ps aux
通过域名无法访问，但 IP:端口可以访问。	Nginx 配置错误或域名解析未生效。	1. 检查 Nginx 配置语法：`sudo nginx -t`。 2. 检查 Nginx 错误日志：`sudo tail -f /var/log/nginx/error.log`。 3. 使用`ping your-domain.com`和`dig your-domain.com`检查域名解析是否正确指向服务器 IP。
HTTPS 访问证书错误。	SSL 证书过期或配置不正确。	1. 使用`sudo certbot certificates`检查证书状态。 2. 尝试续期证书：`sudo certbot renew`。 3. 检查 Nginx 配置中`ssl_certificate`和`ssl_certificate_key`路径是否正确。

6.2 API 代理转发失败

问题现象	可能原因	检查与解决步骤
调用代理接口返回`401 Unauthorized`。	代理鉴权密钥未提供或错误。	1. 确认请求头中包含了`X-Proxy-Auth-Key`。 2. 确认其值与服务器`.env`文件中的`PROXY_AUTH_KEY`完全一致。 3. 检查服务器日志，查看鉴权中间件是否打印了拒绝日志。
调用代理接口返回`502 Bad Gateway`或`503 Service Unavailable`。	后端官方 API 服务不可达，或你的 VPS 到官方 API 的网络不通。	1. 在 VPS 上使用`curl`直接测试官方 API 端点（需临时在命令中带上 API Key），看是否能通。 2. 检查服务器日志，看代理中间件是否有错误输出。 3. 可能是官方 API 限流或暂时故障，稍后重试。
请求超时。	网络延迟过高，或请求/响应数据量太大。	1. 在代理配置中增加超时设置（在`createProxyMiddleware`选项中添加`proxyTimeout: 120000`等）。 2. 优化客户端请求，减少`max_tokens`等参数。
Gemini 代理返回`404`或路径错误。	Gemini API 的路径规则特殊，我们的重写逻辑可能不匹配新版本。	1. 查看 Gemini API 官方文档，确认最新的端点路径格式。 2. 修改`server.js`中 Gemini 代理的`pathRewrite`函数逻辑，确保路径转换正确。

6.3 安全与性能优化建议

强化鉴权：目前的简易密钥鉴权适用于个人或小团队。对于公开服务，应考虑使用更安全的方案，如 JWT (JSON Web Tokens) 或 OAuth 2.0。

实施限流：防止 API 被滥用导致超额费用。可以使用express-rate-limit中间件为不同 IP 或用户设置请求频率限制。

npm install express-rate-limit

const rateLimit = require('express-rate-limit'); const limiter = rateLimit({ windowMs: 15 * 60 * 1000, // 15分钟 max: 100 // 每个IP限制100次请求 }); app.use('/v1/', limiter); // 对所有API路由应用限流

添加日志：记录所有请求和响应摘要（注意不要记录敏感信息），便于审计和问题排查。可以使用morgan中间件。
监控与告警：使用pm2的监控功能，或集成外部监控服务（如 UptimeRobot），确保服务在线。设置 API 调用失败或错误率升高的告警。
成本控制：密切关注各官方 API 平台的使用量和费用。为你的代理服务设置预算告警。可以考虑在代理层添加基于令牌（Token）的用量统计和配额管理。

7. 扩展方向：接入本地开源模型

如果你无法获取稳定的海外 API Key，或者对数据隐私有极高要求，接入本地部署的开源模型是一个绝佳的替代方案。许多开源模型提供了与 OpenAI API 兼容的接口。

7.1 使用 Ollama 部署本地模型

Ollama 是一个强大的本地大模型运行框架，它提供了简单的 CLI 和兼容 OpenAI 的 API。

在本地机器或内网服务器上安装 Ollama（参考其官网）。
拉取并运行一个模型，例如 Llama 3.1 或 Qwen 2.5：
```
ollama pull llama3.1:8b ollama run llama3.1:8b
```
Ollama 默认会在http://localhost:11434提供一个兼容 OpenAI 的 API。你可以直接修改我们之前的server.js，为 Ollama 添加一个代理路由，或者更简单地将你的客户端直接指向http://localhost:11434（如果客户端在同一个网络）。

7.2 修改代理服务支持本地模型

在你的server.js中，可以轻松添加一个指向本地 Ollama 的代理：

// 在 server.js 的代理配置部分添加 app.use('/v1/ollama', createProxyMiddleware({ target: 'http://localhost:11434', // Ollama 默认地址 changeOrigin: true, pathRewrite: { '^/v1/ollama': '/v1', // Ollama 使用 /v1 作为 OpenAI 兼容端点 }, // 注意：Ollama 通常不需要 API Key })); console.log('本地 Ollama 代理已启用，端点: /v1/ollama');

现在，你的客户端代码可以通过https://api.your-domain.com/v1/ollama/chat/completions来调用本地模型，其请求格式与调用 OpenAI 完全一致。这实现了对客户端代码的透明切换：只需更改请求的基址（Base URL），即可在云端 GPT 和本地模型之间无缝切换。

通过以上步骤，你构建的不仅仅是一个“访问工具”，而是一个可扩展、可维护的AI 网关微服务。它统一了不同 AI 服务的接入方式，增强了安全性和可控性，为后续集成更多模型、添加监控、实现负载均衡等功能打下了坚实的基础。在实际项目中，你可以根据团队需求，在此基础上进一步封装 SDK、设计更精细的权限模型和计费单元，使其成为一个真正服务于生产的内部 AI 能力平台。