3d617de577
将仓储层/基础设施改为 Ent + 原生 SQL 执行路径，并移除 AutoMigrate 与 GORM 依赖。 重构内容包括： - 仓储层改用 Ent/SQL（含 usage_log/account 等复杂查询），统一错误映射 - 基础设施与 setup 初始化切换为 Ent + SQL migrations - 集成测试与 fixtures 迁移到 Ent 事务模型 - 清理遗留 GORM 模型/依赖，补充迁移与文档说明 - 增加根目录 Makefile 便于前后端编译 测试： - go test -tags unit ./... - go test -tags integration ./...
339 lines
7.3 KiB
Markdown
339 lines
7.3 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
|
|
```
|
|
|
|
---
|
|
|
|
## 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>
|