Sub2API 完整部署教程：从零搭建 AI API 网关平台

随着 Claude、Gemini、OpenAI 等大模型的快速发展，越来越多开发者开始使用 AI API 构建自己的应用和服务。

当账号数量逐渐增加后，往往会遇到以下问题：

• 多个 API Key 难以统一管理
• 用户权限无法控制
• Token 消耗无法统计
• 无法进行用户计费
• 缺少负载均衡能力
• 上游账号容易被单点打满

Sub2API 正是为了解决这些问题而诞生的一套 AI API 网关系统。

它能够统一管理多个 AI 服务账号，对外提供标准化 API 接口，实现账号调度、流量控制、Token 计费、用户管理等功能，非常适合个人站长、团队以及 AI SaaS 平台使用。

---

一、Sub2API 是什么？

Sub2API 是一套基于 Go 开发的 AI API 网关平台。

通过 Sub2API，可以将多个 AI 服务账号统一接入系统，然后通过平台生成的 API Key 对外提供服务。

整体架构如下：

用户应用
↓
Sub2API
↓
Claude / Gemini / OpenAI 等模型

平台负责完成：

• 用户认证
• API Key 管理
• 请求转发
• Token 统计
• 费用计算
• 并发限制
• 速率限制
• 负载均衡

---

二、核心功能

多账号管理

支持同时管理多个上游账号。

当某个账号达到限额后，系统可自动切换至其他账号继续提供服务。

API Key 分发

支持为不同用户生成独立 API Key。

每个用户都可以拥有独立：

• 调用额度
• 并发限制
• 权限控制

精确计费

支持：

• Prompt Token 统计
• Completion Token 统计
• 成本计算
• 用户余额管理

适合商业化运营场景。

智能调度

支持：

• 自动负载均衡
• 粘性会话
• 故障切换
• 健康检测

有效提升账号利用率。

支付系统

内置支付功能。

支持：

• 支付宝
• 微信支付
• Stripe
• 易支付

用户可自助充值，无需额外部署支付平台。

---

三、部署方式选择

Sub2API 提供三种部署方式：

方式	推荐指数	适用场景
Docker Compose	⭐⭐⭐⭐⭐	生产环境
一键安装脚本	⭐⭐⭐⭐	快速体验
源码编译	⭐⭐⭐	二次开发

对于绝大多数用户而言：

推荐使用 Docker Compose 部署。

原因：

• 安装简单
• 自动创建数据库
• 自动创建 Redis
• 容易升级
• 方便迁移

---

四、服务器配置要求

测试环境

CPU：2核

内存：4GB

硬盘：40GB SSD

生产环境

CPU：4核以上

内存：8GB以上

硬盘：100GB SSD以上

系统推荐：

• Ubuntu 22.04
• Debian 12
• CentOS Stream 9

---

五、安装 Docker 环境

更新系统：

apt update && apt upgrade -y

安装 Docker：

curl -fsSL https://get.docker.com | bash

安装 Compose：

apt install docker-compose-plugin -y

验证安装：

docker -v

docker compose version

出现版本号即表示安装成功。

---

六、Docker 部署 Sub2API

创建部署目录：

mkdir -p /opt/sub2api

cd /opt/sub2api

执行官方部署脚本：

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

脚本会自动完成：

• 下载 Docker 配置文件
• 创建环境变量文件
• 生成数据库密码
• 生成 JWT 密钥
• 创建数据目录

启动服务：

docker compose up -d

查看运行状态：

docker ps

查看日志：

docker compose logs -f sub2api

如果看到服务正常启动，则说明部署成功。

---

七、访问管理后台

浏览器访问：

http://服务器IP:8080

首次登录需要完成初始化配置：

• PostgreSQL 配置
• Redis 配置
• 管理员账号创建

完成后即可进入管理后台。

---

八、Nginx 反向代理配置

生产环境建议使用域名访问。

安装 Nginx：

apt install nginx -y

编辑配置：

nano /etc/nginx/nginx.conf

在 http 模块中添加：

underscores_in_headers on;

这一步非常重要。

否则部分请求头会被 Nginx 丢弃，导致：

• 粘性会话失效
• 多账号调度异常

创建站点配置：

server {
    listen 80;

    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

重载配置：

nginx -t

systemctl reload nginx

---

九、开启 HTTPS

推荐使用 Certbot 免费申请 SSL。

安装：

apt install certbot python3-certbot-nginx -y

申请证书：

certbot --nginx

根据提示输入域名即可完成 HTTPS 配置。

---

十、系统升级

升级镜像：

docker compose pull

重建容器：

docker compose up -d

整个升级过程不会影响数据。

---

十一、数据备份

停止服务：

docker compose down

打包数据：

tar czf sub2api-backup.tar.gz .

恢复时：

tar xzf sub2api-backup.tar.gz

启动服务：

docker compose up -d

即可完成迁移。

---

十二、安全优化建议

生产环境建议配置以下安全措施：

开启 HTTPS

避免 API Key 明文传输。

使用 Cloudflare

推荐开启：

• DDoS 防护
• WAF
• CDN 加速

设置高强度密码

重点保护：

• PostgreSQL
• Redis
• JWT_SECRET

限制管理后台访问

推荐：

• IP 白名单
• VPN
• Zero Trust

定期备份数据

建议每天自动备份：

• PostgreSQL
• Redis
• Docker 数据目录

---

十三、常用运维命令

查看状态：

docker compose ps

查看日志：

docker compose logs -f

重启服务：

docker compose restart

停止服务：

docker compose down

删除所有数据：

docker compose down

rm -rf data postgres_data redis_data

执行删除操作前请务必确认已经完成备份。

---

总结

Sub2API 是一套功能完整的 AI API 网关平台。

它不仅支持多账号调度、API Key 管理、Token 计费、用户管理等核心功能，还集成了支付系统和管理后台，非常适合作为 AI 中转平台、团队内部 AI 网关或商业化 AI SaaS 服务的基础架构。

对于大多数用户而言，推荐使用 Docker Compose 进行部署，并配合 Nginx、HTTPS 和 Cloudflare 构建生产环境，从而获得更好的稳定性、安全性和可扩展性。