# Token Plan Share

**Repository Path**: yqxs/token-plan-share

## Basic Information

- **Project Name**: Token Plan Share
- **Description**: AI API 代理中转平台，集中管理各厂商 AI 套餐/Token，为用户提供统一的 API 入口。
- **Primary Language**: Unknown
- **License**: MPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-09
- **Last Updated**: 2026-06-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PlanShare

AI API 代理中转平台，集中管理各厂商 AI 套餐/Token，为用户提供统一的 API 入口。

## 功能

- **API 代理转发**：兼容 OpenAI (`/v1/chat/completions`) 和 Anthropic (`/v1/messages`) 规范接口
- **SSE 流式响应**：完整透传上游流式输出
- **Token 配额管理**：按用户-套餐维度统计和限制 Token 用量，支持按月/按天重置
- **上游 Key 池化**：多个 API Key 轮询分发，401/403 自动失效切换
- **管理后台**：用户管理、套餐管理、上游配置、使用记录、API 密钥管理

## 技术栈

- **后端**: Flask + SQLAlchemy + Flask-Login + Flask-Migrate
- **数据库**: SQLite
- **前端**: Jinja2 模板 + HTMX + Tailwind CSS
- **部署**: Waitress WSGI 服务器

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 初始化数据库

```bash
# 创建初始数据库迁移
python -m flask db upgrade
```

### 3. 创建管理员账户

```bash
python init_admin.py --email admin@example.com --password yourpassword
```

### 4. 启动服务

```bash
python run.py
```

服务默认运行在 `http://127.0.0.1:5012`

## 配置

复制 `.env.example` 为 `.env` 并修改配置：

```env
SECRET_KEY=your-random-secret-key
FLASK_APP=app.py
DATABASE_URL=sqlite:///instance/planshare.db
```

## 管理后台

访问 `http://127.0.0.1:5012/admin/` 登录管理后台。

### 配置流程

1. **上游配置** → 添加上游套餐（base_url、接口规范、模型列表、API Key 池）
2. **套餐管理** → 创建本方套餐（关联上游、设置 Token 配额、可见模型）
3. **用户管理** → 创建用户并分配套餐
4. **API 密钥管理** → 为用户生成 API Key

## API 使用

用户使用生成的 API Key 调用代理接口：

### OpenAI 兼容接口

```bash
curl -X POST http://127.0.0.1:5012/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ps-xxxxxxxxxxxx" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}],
    "stream": true
  }'
```

### Anthropic 兼容接口

```bash
curl -X POST http://127.0.0.1:5012/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: ps-xxxxxxxxxxxx" \
  -d '{
    "model": "qwen3.7-max",
    "messages": [{"role": "user", "content": "Hello"}],
    "max_tokens": 100,
    "stream": true
  }'
```

### 鉴权方式

| Header | 适用场景 |
|--------|----------|
| `Authorization: Bearer ps-xxx` | OpenAI SDK, curl, 通用客户端 |
| `X-Api-Key: ps-xxx` | Vercel AI SDK, OpenCode 等 |

## 项目结构

```
planshare/
├── app.py                  # Flask 应用入口
├── config.py               # 配置
├── extensions.py           # 数据库、登录、迁移扩展
├── run.py                  # Waitress 启动脚本
├── init_admin.py           # 创建管理员脚本
├── requirements.txt        # Python 依赖
│
├── models/                 # 数据模型
│   ├── user.py             # 用户模型
│   ├── api_key.py          # API 密钥模型
│   ├── plan.py             # 套餐、上游套餐、密钥池、用户用量
│   └── usage_log.py        # 使用记录
│
├── routes/                 # 路由
│   ├── api.py              # 用户 API 代理接口
│   ├── admin.py            # 管理后台页面
│   └── admin_api.py        # 管理后台 API
│
├── services/               # 业务逻辑
│   ├── api_key_service.py  # API 密钥生成/验证
│   ├── auth_service.py     # 鉴权中间件
│   ├── proxy_service.py    # 代理转发（流式/非流式）
│   ├── quota_service.py    # 配额管理
│   ├── key_rotation_service.py  # 上游 Key 轮询
│   ├── usage_service.py    # 使用记录
│   └── user_service.py     # 用户管理
│
├── templates/admin/        # 管理后台模板
│   ├── base.html           # 基础布局
│   ├── login.html          # 登录页
│   ├── dashboard.html      # 仪表盘
│   ├── users.html          # 用户管理
│   ├── user_detail.html    # 用户详情
│   ├── plans.html          # 套餐管理
│   ├── upstream.html       # 上游配置
│   ├── api_keys.html       # API 密钥管理
│   └── logs.html           # 使用记录
│
├── static/css/             # 静态资源
└── migrations/             # 数据库迁移
```

## 数据模型

```
users ────────┬── api_keys (用户 API Key)
              ├── current_plan_id → plans
              └── user_plan_usage (配额使用)

plans ────────┬── upstream_plan_id → upstream_plans
              ├── display_models (可见模型)
              └── token_quota / quota_period

upstream_plans ─── upstream_api_keys (上游 Key 池)
                 ├── base_url (直接使用，不拼接)
                 └── models (可用模型列表)

usage_logs (详细使用记录，含 token 统计、重试次数)
```

## 生产部署

```bash
# 使用 Waitress
python run.py

# 或使用 Gunicorn (Linux)
gunicorn -w 4 -b 0.0.0.0:5012 app:create_app()
```

建议在反向代理（如 Nginx）后部署，并配置 HTTPS。

## License

MIT