sub2api · Coding Plan API Gateway

sub2api 是一个极致轻量的真实 API 分发网关：你在服务端配置自己的上游 Coding/API Plan，然后给其他用户发放独立 API token。用户通过 OpenAI 兼容接口调用你的网关，网关校验 token、额度和模型白名单，再用你的服务端上游 Key 转发请求。

重要：如果你的 “Coding Plan” 只是网页端订阅、没有合法 API Key 或不允许共享/转售，就不能安全地转换成 API。本项目只代理你在服务端配置的真实 API 上游。

已实现

• 管理员网页面板：创建、暂停、启用、删除、充值用户 token
• 用户 API token：sk-sub2api_ 前缀，明文只显示一次
• 服务端安全存储：只保存 token SHA-256 哈希，不保存明文 token
• OpenAI 兼容接口：POST /v1/chat/completions
• 模型列表接口：GET /v1/models
• 配额扣减：读取上游 response.usage.total_tokens 后扣减 remaining
• 模型白名单：每个用户 token 可单独限制模型，支持 *
• 数据落盘：data/tokens.json 和 data/usage.jsonl
• 零业务依赖：只需要 Node.js 18+，不需要数据库和 Express

目录结构

D:/sub2api
├─ index.html                    # 管理网页构建产物，由 src/ 打包生成
├─ package.json                  # 启动、构建、检查脚本
├─ .env.example                  # 服务端配置模板
├─ .gitignore                    # 忽略真实密钥和运行数据
├─ data/
│  └─ .gitkeep                   # 运行后生成 tokens.json / usage.jsonl
├─ src/
│  ├─ server.js                  # 真实 API 网关服务端
│  ├─ index.html                 # 管理页面结构源码
│  ├─ styles.css                 # 管理页面样式源码
│  └─ app.js                     # 管理页面前端逻辑源码
├─ scripts/
│  ├─ build-static.mjs           # 将 src/index/css/js 打包为根目录 index.html
│  └─ check.mjs                  # 检查关键源码和构建产物
└─ docs/
   ├─ architecture.md            # 网关架构说明
   ├─ gateway-contract.md        # 用户/管理员 API 契约
   └─ deploy.md                  # 部署说明

快速开始

1. 配置 .env

复制配置模板：

copy .env.example .env

修改至少这几项：

ADMIN_TOKEN=换成足够长的管理员密码
UPSTREAM_BASE_URL=https://api.openai.com/v1
UPSTREAM_API_KEY=你的真实上游 API Key
UPSTREAM_DEFAULT_MODEL=gpt-5.4-mini

2. 启动网关

npm start

默认地址：

http://localhost:8787

打开网页后输入 ADMIN_TOKEN，即可创建用户 token。

3. 用户调用你的网关

把生成的 sk-sub2api_xxx 发给用户。用户调用：

curl http://localhost:8787/v1/chat/completions \
  -H "Authorization: Bearer sk-sub2api_xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.4-mini","messages":[{"role":"user","content":"hello"}]}'

成功响应会透传上游结果，并附加：

x-sub2api-token-id: 用户 token id
x-sub2api-used-tokens: 本次扣减 tokens
x-sub2api-remaining: 扣减后的剩余额度

管理接口

所有管理接口需要：

x-admin-token: <ADMIN_TOKEN>

常用接口：

GET    /api/health
GET    /api/admin/tokens
POST   /api/admin/tokens
PATCH  /api/admin/tokens/:id
DELETE /api/admin/tokens/:id
POST   /api/admin/tokens/:id/recharge
POST   /api/admin/tokens/:id/usage
GET    /api/admin/export
POST   /api/admin/import

用户接口

GET  /v1/models
POST /v1/chat/completions

开发命令

重新构建管理页面：

npm run build

检查源码和构建产物：

npm run check

启动服务：

npm start

安全边界

• 不要把 UPSTREAM_API_KEY 发给用户。
• 不要把 .env、data/tokens.json、data/usage.jsonl 提交到仓库。
• 管理员 token 必须足够长，公网部署必须开启 HTTPS。
• 当前默认禁用 stream: true，因为流式响应需要额外解析 usage 才能准确扣费。
• 如果并发和用户量变大，建议把 JSON 文件存储替换为 SQLite/PostgreSQL。