Sub2API

<div align="center">

AI API Gateway Platform for Subscription Quota Distribution

English | 中文

</div>

---

Demo

Try Sub2API online: https://demo.sub2api.org/

Demo credentials (shared demo environment; not created automatically for self-hosted installs):

| Email | Password | |-------|----------| | admin@sub2api.com | admin123 |

Overview

Sub2API is an AI API gateway platform designed to distribute and manage API quotas from AI product subscriptions (like Claude Code $200/month). Users can access upstream AI services through platform-generated API Keys, while the platform handles authentication, billing, load balancing, and request forwarding.

Features

• Multi-Account Management - Support multiple upstream account types (OAuth, API Key)
• API Key Distribution - Generate and manage API Keys for users
• Precise Billing - Token-level usage tracking and cost calculation
• Smart Scheduling - Intelligent account selection with sticky sessions
• Concurrency Control - Per-user and per-account concurrency limits
• Rate Limiting - Configurable request and token rate limits
• Admin Dashboard - Web interface for monitoring and management

Tech Stack

| Component | Technology | |-----------|------------| | Backend | Go 1.25.7, Gin, Ent | | Frontend | Vue 3.4+, Vite 5+, TailwindCSS | | Database | PostgreSQL 15+ | | Cache/Queue | Redis 7+ |

---

Documentation

• Dependency Security: docs/dependency-security.md
• Admin Payment Integration API: docs/ADMIN_PAYMENT_INTEGRATION_API.md

---

Deployment

Method 1: Script Installation (Recommended)

One-click installation script that downloads pre-built binaries from GitHub Releases.

Prerequisites

• Linux server (amd64 or arm64)
• PostgreSQL 15+ (installed and running)
• Redis 7+ (installed and running)
• Root privileges

Installation Steps

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

The script will:

1. Detect your system architecture
2. Download the latest release
3. Install binary to /opt/sub2api
4. Create systemd service
5. Configure system user and permissions

Post-Installation

# 1. Start the service
sudo systemctl start sub2api

# 2. Enable auto-start on boot
sudo systemctl enable sub2api

# 3. Open Setup Wizard in browser
# http://YOUR_SERVER_IP:8080

The Setup Wizard will guide you through:

• Database configuration
• Redis configuration
• Admin account creation

Upgrade

You can upgrade directly from the Admin Dashboard by clicking the Check for Updates button in the top-left corner.

The web interface will:

• Check for new versions automatically
• Download and apply updates with one click
• Support rollback if needed

Useful Commands

# Check status
sudo systemctl status sub2api

# View logs
sudo journalctl -u sub2api -f

# Restart service
sudo systemctl restart sub2api

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

---

Method 2: Docker Compose (Recommended)

Deploy with Docker Compose, including PostgreSQL and Redis containers.

Prerequisites

• Docker 20.10+
• Docker Compose v2+

Quick Start (One-Click Deployment)

Use the automated deployment script for easy setup:

# Create deployment directory
mkdir -p sub2api-deploy && cd sub2api-deploy

# Download and run deployment preparation script
curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash

# Start services
docker-compose up -d

# View logs
docker-compose logs -f sub2api

What the script does:

• Downloads docker-compose.local.yml (saved as docker-compose.yml) and .env.example
• Generates secure credentials (JWT_SECRET, TOTP_ENCRYPTION_KEY, POSTGRES_PASSWORD)
• Creates .env file with auto-generated secrets
• Creates data directories (uses local directories for easy backup/migration)
• Displays generated credentials for your reference

Manual Deployment

If you prefer manual setup:

# 1. Clone the repository
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api/deploy

# 2. Copy environment configuration
cp .env.example .env

# 3. Edit configuration (generate secure passwords)
nano .env

Required configuration in .env:

# PostgreSQL password (REQUIRED)
POSTGRES_PASSWORD=your_secure_password_here

# JWT Secret (RECOMMENDED - keeps users logged in after restart)
JWT_SECRET=your_jwt_secret_here

# TOTP Encryption Key (RECOMMENDED - preserves 2FA after restart)
TOTP_ENCRYPTION_KEY=your_totp_key_here

# Optional: Admin account
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=your_admin_password

# Optional: Custom port
SERVER_PORT=8080

Generate secure secrets:

# Generate JWT_SECRET
openssl rand -hex 32

# Generate TOTP_ENCRYPTION_KEY
openssl rand -hex 32

# Generate POSTGRES_PASSWORD
openssl rand -hex 32

# 4. Create data directories (for local version)
mkdir -p data postgres_data redis_data

# 5. Start all services
# Option A: Local directory version (recommended - easy migration)
docker-compose -f docker-compose.local.yml up -d

# Option B: Named volumes version (simple setup)
docker-compose up -d

# 6. Check status
docker-compose -f docker-compose.local.yml ps

# 7. View logs
docker-compose -f docker-compose.local.yml logs -f sub2api

Deployment Versions

| Version | Data Storage | Migration | Best For | |---------|-------------|-----------|----------| | docker-compose.local.yml | Local directories | ✅ Easy (tar entire directory) | Production, frequent backups | | docker-compose.yml | Named volumes | ⚠️ Requires docker commands | Simple setup |

Recommendation: Use docker-compose.local.yml (deployed by script) for easier data management.

Access

Open http://YOUR_SERVER_IP:8080 in your browser.

If admin password was auto-generated, find it in logs:

docker-compose -f docker-compose.local.yml logs sub2api | grep "admin password"

Upgrade

# Pull latest image and recreate container
docker-compose -f docker-compose.local.yml pull
docker-compose -f docker-compose.local.yml up -d

Easy Migration (Local Directory Version)

When using docker-compose.local.yml, migrate to a new server easily:

# On source server
docker-compose -f docker-compose.local.yml down
cd ..
tar czf sub2api-complete.tar.gz sub2api-deploy/

# Transfer to new server
scp sub2api-complete.tar.gz user@new-server:/path/

# On new server
tar xzf sub2api-complete.tar.gz
cd sub2api-deploy/
docker-compose -f docker-compose.local.yml up -d

Useful Commands

# Stop all services
docker-compose -f docker-compose.local.yml down

# Restart
docker-compose -f docker-compose.local.yml restart

# View all logs
docker-compose -f docker-compose.local.yml logs -f

# Remove all data (caution!)
docker-compose -f docker-compose.local.yml down
rm -rf data/ postgres_data/ redis_data/

---

Method 3: Build from Source

Build and run from source code for development or customization.

Prerequisites

• Go 1.21+
• Node.js 18+
• PostgreSQL 15+
• Redis 7+

Build Steps

# 1. Clone the repository
git clone https://github.com/Wei-Shaw/sub2api.git
cd sub2api

# 2. Install pnpm (if not already installed)
npm install -g pnpm

# 3. Build frontend
cd frontend
pnpm install
pnpm run build
# Output will be in ../backend/internal/web/dist/

# 4. Build backend with embedded frontend
cd ../backend
go build -tags embed -o sub2api ./cmd/server

# 5. Create configuration file
cp ../deploy/config.example.yaml ./config.yaml

# 6. Edit configuration
nano config.yaml

Note: The -tags embed flag embeds the frontend into the binary. Without this flag, the binary will not serve the frontend UI.

Key configuration in config.yaml:

server:
  host: "0.0.0.0"
  port: 8080
  mode: "release"

database:
  host: "localhost"
  port: 5432
  user: "postgres"
  password: "your_password"
  dbname: "sub2api"

redis:
  host: "localhost"
  port: 6379
  password: ""

jwt:
  secret: "change-this-to-a-secure-random-string"
  expire_hour: 24

default:
  user_concurrency: 5
  user_balance: 0
  api_key_prefix: "sk-"
  rate_multiplier: 1.0

Sora Status (Temporarily Unavailable)

⚠️ Sora-related features are temporarily unavailable due to technical issues in upstream integration and media delivery. Please do not rely on Sora in production at this time. Existing gateway.sora_* configuration keys are reserved and may not take effect until these issues are resolved.

Additional security-related options are available in config.yaml:

• cors.allowed_origins for CORS allowlist
• security.url_allowlist for upstream/pricing/CRS host allowlists
• security.url_allowlist.enabled to disable URL validation (use with caution)
• security.url_allowlist.allow_insecure_http to allow HTTP URLs when validation is disabled
• security.url_allowlist.allow_private_hosts to allow private/local IP addresses
• security.response_headers.enabled to enable configurable response header filtering (disabled uses default allowlist)
• security.csp to control Content-Security-Policy headers
• billing.circuit_breaker to fail closed on billing errors
• server.trusted_proxies to enable X-Forwarded-For parsing
• turnstile.required to require Turnstile in release mode

⚠️ Security Warning: HTTP URL Configuration

When `secur