First commit
This commit is contained in:
shaw
318
README.md
Normal file
318
README.md
Normal file
@@ -0,0 +1,318 @@
|
||||
# Sub2API
|
||||
|
||||
<div align="center">
|
||||
|
||||
[](https://golang.org/)
|
||||
[](https://vuejs.org/)
|
||||
[](https://www.postgresql.org/)
|
||||
[](https://redis.io/)
|
||||
[](https://www.docker.com/)
|
||||
|
||||
**AI API Gateway Platform for Subscription Quota Distribution**
|
||||
|
||||
English | [中文](README_CN.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
# Download and run the installation script
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Method 2: Docker Compose
|
||||
|
||||
Deploy with Docker Compose, including PostgreSQL and Redis containers.
|
||||
|
||||
#### Prerequisites
|
||||
|
||||
- Docker 20.10+
|
||||
- Docker Compose v2+
|
||||
|
||||
#### Installation Steps
|
||||
|
||||
```bash
|
||||
# 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`:**
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Pull latest image and recreate container
|
||||
docker-compose pull
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
#### Useful Commands
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 1. Clone the repository
|
||||
git clone https://github.com/Wei-Shaw/sub2api.git
|
||||
cd sub2api
|
||||
|
||||
# 2. Build backend
|
||||
cd backend
|
||||
go build -o sub2api ./cmd/server
|
||||
|
||||
# 3. Build frontend
|
||||
cd ../frontend
|
||||
npm install
|
||||
npm run build
|
||||
|
||||
# 4. Copy frontend build to backend (for embedding)
|
||||
cp -r dist ../backend/internal/web/
|
||||
|
||||
# 5. Create configuration file
|
||||
cd ../backend
|
||||
cp ../deploy/config.example.yaml ./config.yaml
|
||||
|
||||
# 6. Edit configuration
|
||||
nano config.yaml
|
||||
```
|
||||
|
||||
**Key configuration in `config.yaml`:**
|
||||
|
||||
```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:
|
||||
admin_email: "admin@example.com"
|
||||
admin_password: "admin123"
|
||||
```
|
||||
|
||||
```bash
|
||||
# 7. Run the application
|
||||
./sub2api
|
||||
```
|
||||
|
||||
#### Development Mode
|
||||
|
||||
```bash
|
||||
# Backend (with hot reload)
|
||||
cd backend
|
||||
go run ./cmd/server
|
||||
|
||||
# Frontend (with hot reload)
|
||||
cd frontend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**If you find this project useful, please give it a star!**
|
||||
|
||||
</div>
|
||||
Reference in New Issue
Block a user