112a2d0866
主要更新： - 更新 go.mod/go.sum 依赖 - 重新生成 Ent ORM 代码 - 更新 Wire 依赖注入配置 - 添加 docker-compose.override.yml 到 .gitignore - 更新 README 文档（Simple Mode 说明和已知问题） - 清理调试日志 - 其他代码优化和格式修复
381 lines
8.8 KiB
Markdown
381 lines
8.8 KiB
Markdown
# 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>
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
```bash
|
|
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 -y
|
|
```
|
|
|
|
---
|
|
|
|
### 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 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`:**
|
|
|
|
```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
|
|
```
|
|
|
|
```bash
|
|
# 6. 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
|
|
```
|
|
|
|
#### Code Generation
|
|
|
|
When editing `backend/ent/schema`, regenerate Ent + Wire:
|
|
|
|
```bash
|
|
cd backend
|
|
go generate ./ent
|
|
go generate ./cmd/server
|
|
```
|
|
|
|
---
|
|
|
|
## Simple Mode
|
|
|
|
Simple Mode is designed for individual developers or internal teams who want quick access without full SaaS features.
|
|
|
|
- Enable: Set environment variable `RUN_MODE=simple`
|
|
- Difference: Hides SaaS-related features and skips billing process
|
|
- Security note: In production, you must also set `SIMPLE_MODE_CONFIRM=true` to allow startup
|
|
|
|
---
|
|
|
|
## Antigravity Support
|
|
|
|
Sub2API supports [Antigravity](https://antigravity.so/) accounts. After authorization, dedicated endpoints are available for Claude and Gemini models.
|
|
|
|
### Dedicated Endpoints
|
|
|
|
| Endpoint | Model |
|
|
|----------|-------|
|
|
| `/antigravity/v1/messages` | Claude models |
|
|
| `/antigravity/v1beta/` | Gemini models |
|
|
|
|
### Claude Code Configuration
|
|
|
|
```bash
|
|
export ANTHROPIC_BASE_URL="http://localhost:8080/antigravity"
|
|
export ANTHROPIC_AUTH_TOKEN="sk-xxx"
|
|
```
|
|
|
|
### Hybrid Scheduling Mode
|
|
|
|
Antigravity accounts support optional **hybrid scheduling**. When enabled, the general endpoints `/v1/messages` and `/v1beta/` will also route requests to Antigravity accounts.
|
|
|
|
> **⚠️ Warning**: Anthropic Claude and Antigravity Claude **cannot be mixed within the same conversation context**. Use groups to isolate them properly.
|
|
|
|
### Known Issues
|
|
|
|
In Claude Code, Plan Mode cannot exit automatically. (Normally when using the native Claude API, after planning is complete, Claude Code will pop up options for users to approve or reject the plan.)
|
|
|
|
**Workaround**: Press `Shift + Tab` to manually exit Plan Mode, then type your response to approve or reject the plan.
|
|
|
|
---
|
|
|
|
## 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>
|