自建AI中转站sub2api轻量网关Docker一键部署

为什么需要自建AI中转站

如果你在使用 OpenAI、Claude 等 API 时遇到网络限制、频率限制或想统一管理多个 AI 接口，搭建一个私有中转站是最直接的方案。
sub2api 是一个轻量级网关，能一键将多个 AI 提供商的路由转换为兼容格式。
配合 Docker，你只需要一条命令就能在服务器上跑起来，完全零基础可操作。

准备条件：一台服务器和Docker环境

• 一台 Linux 服务器（推荐 Ubuntu 20.04+ / CentOS 7+），最低配置 1C2G 即可。
• 已经安装好 Docker，如果没有，先执行以下命令安装（以 Ubuntu 为例）：

sudo apt update
sudo apt install docker.io -y
sudo systemctl start docker
sudo systemctl enable docker

• 确认 Docker 版本：docker --version，如果显示 Docker version 20.10+ 就说明环境就绪。

分步操作：一键拉取并运行sub2api容器

不需要写繁琐的配置文件，sub2api 官方提供了可直接运行的 Docker 镜像。
你只需要一行命令即可部署：

docker run -d \
  --name sub2api \
  -p 3000:3000 \
  -e UPSTREAM_URL=https://api.openai.com \
  -e API_KEY=your-api-key-here \
  sub2api/sub2api:latest

命令解读：

• -d：后台运行容器。
• --name sub2api：给容器起个名字方便管理。
• -p 3000:3000：将宿主机的 3000 端口映射到容器内 3000 端口。
• -e UPSTREAM_URL：设置上游 API 地址，你可以换成 https://api.anthropic.com 或其他兼容接口。
• -e API_KEY：设置你自己的 API 密钥（建议单独创建专用 Key）。

如果你想同时代理多个上游，可以多次指定环境变量，或者使用更完整的配置文件。
启动后执行 docker logs sub2api 查看启动日志，看到 Server running on port 3000 就表示成功。

避坑指南：新手最容易犯的四个错误

1. 端口冲突：如果宿主机 3000 端口已被占用，启动会失败。可以先执行 lsof -i :3000 检查，然后更换映射端口，如 -p 3001:3000，并注意防火墙放行新端口。
2. API Key 权限不足：确保你使用的 Key 具有访问上游 API 的权限（例如 OpenAI 的 Key 要开启对应模型）。
3. 镜像拉取失败：国内服务器可能无法直接拉取 Docker Hub 镜像，可以先配置镜像加速器（如阿里云加速器），或更换为 registry.cn-hangzhou.aliyuncs.com/sub2api/sub2api:latest。
4. 环境变量大小写：UPSTREAM_URL 和 API_KEY 必须与示例完全一致，拼写错误会导致容器启动无报错但无法正常代理。

效果验证：模拟一次真实请求

容器运行后，你可以用 curl 测试中转站是否正常工作：

curl http://your-server-ip:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-here" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

如果返回包含 "choices" 的 JSON 数据，说明中转站搭建成功。
你可以将程序中的 API 地址改为 http://your-server-ip:3000/v1，像使用官方接口一样调用。

常见问题 FAQ

Q1：我不懂 Docker，有没有更简单的安装方式？

还可以使用 1Panel 等面板可视化部署，但 Docker 命令行是目前最轻量的方案，本文的命令就是最简化的版本，复制粘贴即可。

Q2：如何添加多个上游模型？

sub2api 支持通过配置文件定义路由，将不同的模型指向不同的上游。
具体配置方法可参考项目文档，但单上游部署已经能满足大多数自用场景。

Q3：容器重启后配置会丢失吗？

是的，如果直接 docker rm 再启动，环境变量需要重新传入。
建议使用 docker-compose 管理，或挂载配置文件。
临时使用的话直接运行命令即可。

如果你在部署中遇到其他问题，建议先检查容器日志 docker logs sub2api 查看错误信息，大部分报错都能在日志里找到原因。
一次完整的自建 AI 中转站部署，从装 Docker 到验证请求，通常不超过 10 分钟。