Sub2API

AI API Gateway Platform for Subscription Quota Distribution

English | 中文

---

Demo

Try Sub2API online: https://v2.pincc.ai/

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.21+, Gin, GORM
Frontend	Vue 3.4+, Vite 5+, TailwindCSS
Database	PostgreSQL 15+
Cache/Queue	Redis 7+

---

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

Deploy with Docker Compose, including PostgreSQL and Redis containers.

Prerequisites

• Docker 20.10+
• Docker Compose v2+

Installation Steps

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

# 2. Enter the deploy directory
cd deploy

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

# 4. Edit configuration (set your passwords)
nano .env

Required configuration in .env:

# PostgreSQL password (REQUIRED - change this!)
POSTGRES_PASSWORD=your_secure_password_here

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

# Optional: Custom port
SERVER_PORT=8080

# 5. Start all services
docker-compose up -d

# 6. Check status
docker-compose ps

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

Access

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

Upgrade

# Pull latest image and recreate container
docker-compose pull
docker-compose up -d

Useful Commands

# Stop all services
docker-compose down

# Restart
docker-compose restart

# View all logs
docker-compose logs -f

---

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. Build frontend
cd frontend
npm install
npm run build
# Output will be in ../backend/internal/web/dist/

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

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

# 5. 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

# 6. Run the application
./sub2api

Development Mode

# Backend (with hot reload)
cd backend
go run ./cmd/server

# Frontend (with hot reload)
cd frontend
npm run dev

Code Generation

When editing backend/ent/schema, regenerate Ent + Wire:

cd backend
go generate ./ent
go generate ./cmd/server

---

Project Structure

sub2api/
├── backend/                  # Go backend service
│   ├── cmd/server/           # Application entry
│   ├── internal/             # Internal modules
│   │   ├── config/           # Configuration
│   │   ├── model/            # Data models
│   │   ├── service/          # Business logic
│   │   ├── handler/          # HTTP handlers
│   │   └── gateway/          # API gateway core
│   └── resources/            # Static resources
│
├── frontend/                 # Vue 3 frontend
│   └── src/
│       ├── api/              # API calls
│       ├── stores/           # State management
│       ├── views/            # Page components
│       └── components/       # Reusable components
│
└── deploy/                   # Deployment files
    ├── docker-compose.yml    # Docker Compose configuration
    ├── .env.example          # Environment variables for Docker Compose
    ├── config.example.yaml   # Full config file for binary deployment
    └── install.sh            # One-click installation script

License

MIT License

---

If you find this project useful, please give it a star!