一、项目介绍

Sub2API（AI API Gateway Platform for Subscription Quota Distribution）是一个强大的 AI 接口分发与管理系统。它的核心作用是将你手中的多种大模型订阅账号（如 Claude、OpenAI、Gemini、Antigravity 等）统一接入，转化为标准的 API 接口对外提供调用。

核心功能与优势

1. 多账号负载均衡：将多个上游账号汇聚成资源池，自动调度，避免单账号触发风控或频控。
2. 统一 API 格式：对外提供统一的 OpenAI 兼容接口或原生 Anthropic 接口，下游客户端无需关心上游实际调用的是什么账号。
3. 配额与计费管理：可生成多个分发 API Key，为每个 Key 设置额度、有效期、并发和速率限制，适合团队共享或小规模分发。
4. 安全与鉴权：自带完善的鉴权体系，支持 2FA 双因素认证，保护你的上游账号安全。
5. 技术栈：采用 Go 1.25+ 与 Gin 框架作为后端，Vue 3 + Vite 构建前端，前后端打包为单体二进制文件，性能极高，占用极小。

适用场景

• 个人手里有多个 Claude/OpenAI 订阅账号，希望在各个客户端（如 ChatBox, Claude Code, OpenCode 等）统一调用。
• 小团队内部共享 AI 算力，需要分配额度和权限。
• 将不同的开源模型（通过 Ollama 等）包装成 OpenAI 兼容格式供下游使用。

---

二、服务器选购指南

因为 Sub2API 需要转发 Claude、OpenAI 等海外 AI 服务的请求，强烈建议购买海外 VPS，具体原因不用多讲。这里我选择国内知名小厂雨云的云服务器，价格实惠。官网：雨云

2. 配置要求

Sub2API 本身是 Go 编写的二进制，非常轻量，加上 PostgreSQL 和 Redis，最低配置即可流畅运行：

• CPU：1 核
• 内存：1 GB
• 硬盘：20 GB SSD
• 系统：linux，我以ubuntu作为演示
• 网络：需确保服务器 IP 未被 OpenAI/Claude 封锁（购买后可 ping 或用 curl 测试 api.openai.com）。这里我以日本一区为例。

3. 购买后准备

购买服务器后，使用 SSH 工具（如 Xshell, Termius, 或系统自带终端）登录服务器，我这里用mobaxterm。
注意登录时输入密码的时候不会显示。

三、环境准备与依赖安装（PostgreSQL + Redis）

Sub2API 需要 PostgreSQL 和 Redis 作为数据存储与缓存。我们通过 apt 包管理器一次性安装。

1. 更新系统并安装依赖

登录服务器后，执行以下命令更新软件包并安装 PostgreSQL 与 Redis：

apt update
apt install -y curl tar postgresql redis-server

这样就ok了。

2. 配置 PostgreSQL

默认安装的 PostgreSQL 会自带一个名为 postgres 的超级用户和同名数据库。
执行以下命令设置密码（将 your_pg_password 替换为你自己的强密码并记下，不要直接复制！！！）：

sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'your_pg_password';"

3. 配置 Redis

编辑 Redis 配置文件，开启密码验证。执行以下命令自动替换配置：

sed -i 's/^# requirepass foobared/requirepass your_redis_password/' /etc/redis/redis.conf

(将 your_redis_password 替换为你自己的强密码并记下，不要直接复制！！！)

4. 启动并设置开机自启

确保数据库和缓存服务正在运行，并设为开机启动：

systemctl enable --now postgresql redis-server
systemctl status postgresql redis-server # 确保都显示 active (running)

这样就ok了

---

四、一键脚本部署 Sub2API

官方提供了 install.sh 脚本来简化二进制部署流程。该脚本会自动下载程序、注册系统服务。

1. 下载并执行脚本

在终端运行：

curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh -o install.sh
chmod +x install.sh
./install.sh

2. 脚本交互说明

脚本运行过程中会提示你输入配置，按以下建议操作：

• 语言选择：输入 1 选择中文。
  
• 服务器监听地址：直接回车，保持默认的 0.0.0.0。这表示监听所有网卡，外网才能通过 IP 访问。切勿填 127.0.0.1。
• 服务器端口：直接回车，保持默认的 8080（或填你自定义的端口，如 3000）。

脚本会自动完成以下工作：

• 下载最新的 Sub2API 二进制文件到 /opt/sub2api/。
• 创建 sub2api 系统用户。
• 写入 systemd 服务单元文件。

3. 启动 Sub2API

脚本执行完毕后，手动启动服务并设置开机自启：

systemctl enable --now sub2api
systemctl status sub2api

如果看到 active (running)，说明程序已成功启动。可以按 q 键退出状态查看。

---

五、放行端口（直接 IP 访问）

由于我们不使用 Nginx 反向代理，直接通过 IP:8080 访问，所以对于阿里云等大厂要放行端口。

六、Web 端初始化（Setup Wizard）

现在，在本地电脑的浏览器地址栏输入：
http://你的服务器公网IP:8080
首次访问会进入初始化向导。按照前面的免建库配置，按以下信息填写：

1. 数据库配置

• Host：127.0.0.1
• Port：5432
• Database：postgres （直接填 PostgreSQL 自带的默认库）
• User：postgres （直接填默认超级用户）
• Password：你在第三步设置的 your_pg_password
  

2. Redis 配置

• Host：127.0.0.1
• Port：6379
• Password：你在第三步设置的 your_redis_password

3. 管理员账号

设置你的登录邮箱和密码（建议使用复杂密码，后续在后台可开启 2FA 双因素认证）。
填写完成后点击提交。Sub2API 会自动连接数据库并在 postgres 库中创建所需的表结构，随后页面会跳转到登录界面。

---

七、后台配置与 API 分发使用

使用刚才设置的管理员账号登录后台，即可开始使用。最新版本的需要合规承诺。按照要求统登入就ok。

这里可以走新手教程，按照教程登入账户即可。

八、日常运维与升级

Sub2API 已注册为系统服务，日常管理非常简单。

服务管理命令

# 查看服务状态
systemctl status sub2api
# 停止服务
systemctl stop sub2api
# 启动服务
systemctl start sub2api
# 重启服务（修改配置后需执行）
systemctl restart sub2api
# 查看实时运行日志（排错必备）
journalctl -u sub2api -f

版本升级与卸载

官方脚本自带了升级和卸载功能。保留之前的 install.sh 文件，执行以下命令：

# 升级到最新版本（会自动备份旧文件并替换二进制）
./install.sh upgrade
# 列出所有可用版本
./install.sh list-versions
# 卸载 Sub2API（不会删除数据库数据）
./install.sh uninstall

至此，一台通过 IP 直接访问、免建库的 Sub2API 网关就部署完成了，你可以随时在后台添加更多账号和分发 Key。