Sub2API 安装与使用教程：AI 订阅账号统一转 API 网关

2026年6月3日 免费资源

Sub2API 是一个面向 AI 订阅账号和 API Key 的网关平台，可以把 Claude、OpenAI、Gemini、Codex、Antigravity 等上游能力统一接入，再通过平台生成的 API Key 对外提供 OpenAI / Claude / Gemini 兼容接口。它适合个人团队做账号池、额度分发、用量统计、并发控制和统一转发。

一、适合什么场景？

  • 手里有多个 Claude、OpenAI、Gemini 或 Codex 相关账号，希望统一管理。
  • 希望给团队成员分发独立 API Key，并限制额度和并发。
  • 想在一个后台里查看调用量、余额、模型使用情况。
  • 需要通过统一 Base URL 接入 Claude Code、Codex CLI、OpenAI 兼容客户端等工具。

二、准备服务器环境

推荐使用 Ubuntu 22.04 / 24.04 或 Debian 12，内存建议 2GB 起步，生产环境建议 4GB 以上。Sub2API 依赖 PostgreSQL 15+ 和 Redis 7+，如果使用 Docker Compose，数据库和 Redis 可以一起拉起。

sudo apt update
sudo apt install -y curl wget git ca-certificates ufw

三、方式一：一键脚本安装

官方提供了一键安装脚本，适合裸机 VPS 部署。脚本会检测架构、下载最新 release、安装到 /opt/sub2api，并创建 systemd 服务。

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

安装完成后启动服务并设置开机自启：

sudo systemctl start sub2api
sudo systemctl enable sub2api
sudo systemctl status sub2api

默认访问地址通常是：

http://你的服务器IP:8080

首次进入后台会进入初始化向导，按提示配置数据库、Redis 和管理员账号即可。

四、方式二：Docker Compose 部署

如果你希望部署更容易迁移，建议使用 Docker Compose。它可以把 Sub2API、PostgreSQL、Redis 一起编排起来。

mkdir -p sub2api-deploy && cd sub2api-deploy
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash
docker compose up -d
docker compose logs -f sub2api

Docker 部署脚本通常会帮你生成 .env 文件和必要密钥。建议保存好生成的管理员密码、数据库密码和 JWT/TOTP 密钥。

五、手动配置 .env 关键项

如果手动部署，至少需要配置数据库密码、JWT 密钥、TOTP 加密密钥和后台管理员账号。

POSTGRES_PASSWORD=your_secure_password_here
JWT_SECRET=your_jwt_secret_here
TOTP_ENCRYPTION_KEY=your_totp_key_here
[email protected]
ADMIN_PASSWORD=your_admin_password
SERVER_PORT=8080

可以用 openssl 生成随机密钥：

openssl rand -hex 32
openssl rand -hex 32
openssl rand -hex 32

六、反向代理配置

生产环境建议使用 Nginx 或 Caddy 反代到 8080 端口，并配置 HTTPS。需要注意：如果用 Nginx 反向代理 Sub2API 并搭配 Codex CLI，多账号粘性会话可能依赖带下划线的请求头，因此建议在 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;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

七、基础使用流程

  • 进入后台，创建管理员账号。
  • 添加上游账号或上游 API Key。
  • 按需要创建分组、倍率、并发限制和速率限制。
  • 为用户生成 API Key。
  • 把 Base URL 和 API Key 填到客户端里。

OpenAI 兼容客户端示例：

curl https://你的域名/v1/chat/completions \
  -H "Authorization: Bearer sk-你的Sub2API-Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [{"role":"user","content":"hello"}]
  }'

八、常用运维命令

# systemd 方式
sudo systemctl status sub2api
sudo journalctl -u sub2api -f
sudo systemctl restart sub2api

# Docker Compose 方式
docker compose ps
docker compose logs -f
docker compose restart
docker compose pull && docker compose up -d

九、安全建议

  • 后台一定要使用强密码，并开启 HTTPS。
  • 不要把管理后台直接裸奔在公网，建议配合 Cloudflare、WAF 或 IP 白名单。
  • API Key 分发给用户后，按用户设置额度和并发限制。
  • 定期备份 PostgreSQL 数据和配置文件。
  • 不要把 .env、config.yaml、数据库密码、JWT_SECRET 上传到公开仓库。

十、总结

Sub2API 更像一个 AI API 网关和账号池管理平台。个人使用可以统一多个订阅账号，团队使用可以做额度分发、计费和访问控制。部署上，个人 VPS 推荐 Docker Compose；已有数据库和 Redis 的服务器可以选择一键脚本或二进制方式。

归档