1. Sub2API项目概述Sub2API是一款开源的AI API网关平台旨在为开发者提供统一的中转服务支持将Claude、OpenAI、Gemini、Grok等主流AI服务的订阅配额进行集中管理和分发。这个项目由Wei-Shaw团队开发并维护目前在GitHub上获得了31.4k星标和6.4k Fork显示出其在开发者社区中的广泛关注度。作为一个API网关Sub2API的核心功能是作为中间层连接上游AI服务提供商和下游开发者/用户。它解决了以下几个关键问题多账号管理支持同时接入多个上游AI服务账号包括OAuth和API Key两种认证方式配额分配将高额订阅账号的API调用配额合理分配给多个用户成本分摊通过拼车共享模式显著降低单个用户使用高级AI模型的成本统一接口为不同AI服务提供标准化的API接口简化开发者集成工作项目采用LGPL-3.0开源协议这意味着开发者可以自由使用、修改和分发代码但任何修改后的版本也必须保持开源。这种许可方式既保证了项目的开放性又鼓励社区贡献。重要提示使用Sub2API可能违反上游AI服务提供商如Anthropic等的服务条款。开发者需自行评估风险项目作者不承担因使用本项目导致的账号封禁、服务中断等后果。2. 核心功能与技术架构2.1 主要功能特性Sub2API提供了丰富的功能集使其成为一个完整的AI API管理解决方案多账户集成管理支持同时接入Claude、OpenAI、Gemini、Grok等多种AI服务的订阅账号提供OAuth和API Key两种认证方式可设置不同账号的优先级和权重智能API网关功能请求路由与负载均衡自动选择最优的上游账号处理请求会话保持Sticky Session确保同一会话的请求路由到同一上游账号并发控制可配置每个用户和每个账号的并发请求限制速率限制支持基于请求次数和token数量的双重限流机制配额与计费系统精确到token级别的用量统计实时余额计算与扣费支持多种计费模式按量付费、订阅套餐等内置支付系统支持支付宝、微信支付、Stripe等管理与监控可视化仪表盘实时监控API调用情况、账号状态、系统负载等详细的日志记录与审计跟踪告警功能配额不足、账号异常等情况自动通知扩展性功能Webhook支持关键事件可触发自定义回调外部系统集成通过iframe嵌入第三方系统如客服工单系统插件机制支持功能扩展2.2 技术栈与架构设计Sub2API采用现代云原生技术栈构建各组件分工明确后端服务编程语言Go 1.25.7Web框架GinORMEnt任务队列基于Redis实现前端界面框架Vue 3.4构建工具Vite 5UI组件库TailwindCSS状态管理Pinia数据存储主数据库PostgreSQL 15存储用户数据、配置、日志等缓存Redis 7会话管理、速率限制、队列等部署架构客户端 → Nginx → Sub2API应用 → [上游AI服务] ↑ PostgreSQL ↑ Redis这种架构设计使得系统具备良好的水平扩展能力可以通过增加应用实例来应对高并发场景。Redis作为集中式缓存和消息队列确保了多实例间的状态同步。3. 部署与配置指南3.1 环境准备在部署Sub2API前需要准备以下基础设施服务器推荐使用Linux系统x86_64或ARM64架构最低配置2核CPU4GB内存20GB存储生产环境建议4核CPU以上8GB内存以上依赖服务PostgreSQL 15用于主数据存储Redis 7用于缓存和队列Nginx可选作为反向代理网络要求能够访问上游AI服务API可能需要特定网络配置如需公网访问需准备域名和SSL证书3.2 三种部署方式对比Sub2API提供多种部署方案适用于不同场景部署方式适用场景优点缺点迁移难度脚本安装生产环境自动化程度高易于维护需要root权限中等Docker Compose开发/测试/生产隔离性好一键启动需要Docker环境简单源码编译定制开发灵活性最高复杂度高困难3.2.1 脚本安装推荐用于生产这是最简单的部署方式适合大多数生产环境# 执行一键安装脚本 curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash安装脚本会自动完成以下工作检测系统架构并下载对应版本的预编译二进制文件创建系统用户和组设置systemd服务安装到/opt/sub2api目录安装完成后通过systemd管理服务# 启动服务 sudo systemctl start sub2api # 设置开机自启 sudo systemctl enable sub2api # 查看状态 sudo systemctl status sub2api # 查看日志 sudo journalctl -u sub2api -f首次启动后访问http://服务器IP:8080进入设置向导按照指引完成数据库连接配置Redis连接配置管理员账号创建3.2.2 Docker Compose部署对于已经使用Docker的环境这是更便捷的选择# 创建部署目录 mkdir -p sub2api-deploy cd sub2api-deploy # 下载并运行部署准备脚本 curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash # 启动所有服务 docker compose up -d这种部署方式会自动创建以下容器sub2api主应用postgresPostgreSQL数据库redisRedis缓存数据默认保存在本地目录便于备份迁移postgres_data数据库文件redis_dataRedis持久化数据3.2.3 源码编译部署需要定制功能或参与开发的用户可以选择从源码构建# 克隆仓库 git clone https://github.com/Wei-Shaw/sub2api.git cd sub2api # 安装前端依赖并构建 cd frontend npm install -g pnpm pnpm install pnpm run build # 构建后端包含前端资源 cd ../backend go build -tags embed -o sub2api ./cmd/server # 复制配置文件并编辑 cp ../deploy/config.example.yaml ./config.yaml nano config.yaml关键配置项包括数据库连接参数Redis连接参数JWT密钥用于会话安全默认用户并发数API Key前缀费率乘数3.3 反向代理配置在生产环境中建议使用Nginx作为反向代理提供HTTPS支持和负载均衡server { listen 443 ssl; server_name api.yourdomain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; # 必须添加此项否则会丢失带下划线的头部如session_id underscores_in_headers on; location / { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # WebSocket支持 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }配置完成后重启Nginx使更改生效sudo nginx -t # 测试配置 sudo systemctl restart nginx4. 使用与管理实践4.1 管理员操作指南成功部署后管理员可以通过Web界面默认端口8080进行系统管理用户管理创建/编辑/删除用户账号设置用户权限和配额查看用户API使用情况账号管理添加上游AI服务账号设置账号权重和优先级监控账号健康状态处理授权过期等问题系统监控实时API调用统计系统资源使用情况异常请求告警支付配置进入系统设置→支付配置选择支付提供商支付宝、微信支付、Stripe等填写商户ID、API密钥等凭证设置费率如每1000 tokens的价格保存并测试支付流程4.2 API使用示例开发者可以通过Sub2API生成的API Key访问统一接口而不需要直接使用上游服务的密钥。获取API Key登录用户控制台进入API Keys页面点击Create API Key设置名称和权限范围复制生成的Key格式如sk-xxx调用示例Pythonimport openai # 配置Sub2API端点 openai.api_base http://your-sub2api-server/v1 # Sub2API地址 openai.api_key sk-xxx # 从Sub2API获取的API Key # 调用ChatCompletion response openai.ChatCompletion.create( modelgpt-4, messages[ {role: system, content: 你是一个有帮助的助手}, {role: user, content: 解释一下量子计算的基本原理} ] ) print(response.choices[0].message.content)调用示例cURLcurl -X POST \ http://your-sub2api-server/v1/chat/completions \ -H Authorization: Bearer sk-xxx \ -H Content-Type: application/json \ -d { model: claude-2, messages: [ {role: user, content: 你好请介绍一下你自己} ] }4.3 高级配置技巧智能路由配置在config.yaml中可以设置账号选择策略gateway: strategy: weighted-round-robin # 加权轮询 # strategy: least-connections # 最少连接 # strategy: latency-based # 基于延迟 weights: claude-pro: 5 claude-basic: 1自定义限流规则可以为不同用户组设置不同的限流策略rate_limits: default: requests_per_minute: 60 tokens_per_minute: 60000 premium: requests_per_minute: 300 tokens_per_minute: 300000安全加固建议定期轮换JWT_SECRET启用CORS白名单配置IP访问限制启用操作审计日志5. 常见问题与故障排除5.1 部署问题问题1Nginx返回502 Bad Gateway检查Sub2API服务是否正常运行sudo systemctl status sub2api检查Nginx错误日志tail -f /var/log/nginx/error.log确保在Nginx配置中添加了underscores_in_headers on;问题2数据库连接失败检查PostgreSQL是否运行sudo systemctl status postgresql验证连接参数是否正确host, port, username, password检查pg_hba.conf是否允许连接问题3首次登录无法创建管理员账号确保没有预先创建config.yaml文件临时移除现有配置mv config.yaml config.yaml.bak重新启动服务访问设置向导向导完成后恢复原有配置5.2 使用问题问题1API返回401 Unauthorized检查API Key是否正确验证Key是否有访问目标API的权限检查Key是否已过期或被撤销问题2上游账号频繁失效检查是否违反上游服务的使用条款考虑使用住宅IP或降低请求频率配置多个备用账号实现自动切换问题3计费不准确检查config.yaml中的rate_multiplier设置验证上游服务的计费方式如Claude按token计费检查是否有未授权的API调用5.3 性能优化建议数据库优化为常用查询添加索引定期执行VACUUM和ANALYZE考虑读写分离Redis优化启用持久化适当增加maxmemory配置合理的淘汰策略应用层优化启用连接池调整goroutine数量启用响应缓存监控与告警配置Prometheus监控关键指标设置Grafana仪表盘关键异常触发告警如账号失效6. 生态与扩展Sub2API拥有活跃的社区生态围绕核心项目衍生了许多扩展工具和服务官方维护项目sub2api-mobile跨平台移动管理端iOS/Android/WebSub2ApiPay自服务支付系统现已集成到主项目社区贡献项目sub2api-cli命令行管理工具sub2api-prometheus-exporter监控指标导出器sub2api-terraform基础设施即代码部署模板商业服务提供商多家企业基于Sub2API构建了商业化的AI API网关服务提供更稳定的基础设施和专业支持CCTK.AI专注于稳定性和成本效益OpenModel生产级高可用服务ETok.ai一站式AI编程工具平台APIKEY.FUN低成本API访问方案这些服务通常提供更高的可用性SLA保障专业的技术支持企业级功能如发票、合同增值服务如IP隔离、专用线路对于需要更高服务等级的企业用户可以考虑在这些平台注册同时仍然保留自建Sub2API实例作为备用方案。
1. Sub2API项目概述Sub2API是一款开源的AI API网关平台旨在为开发者提供统一的中转服务支持将Claude、OpenAI、Gemini、Grok等主流AI服务的订阅配额进行集中管理和分发。这个项目由Wei-Shaw团队开发并维护目前在GitHub上获得了31.4k星标和6.4k Fork显示出其在开发者社区中的广泛关注度。作为一个API网关Sub2API的核心功能是作为中间层连接上游AI服务提供商和下游开发者/用户。它解决了以下几个关键问题多账号管理支持同时接入多个上游AI服务账号包括OAuth和API Key两种认证方式配额分配将高额订阅账号的API调用配额合理分配给多个用户成本分摊通过拼车共享模式显著降低单个用户使用高级AI模型的成本统一接口为不同AI服务提供标准化的API接口简化开发者集成工作项目采用LGPL-3.0开源协议这意味着开发者可以自由使用、修改和分发代码但任何修改后的版本也必须保持开源。这种许可方式既保证了项目的开放性又鼓励社区贡献。重要提示使用Sub2API可能违反上游AI服务提供商如Anthropic等的服务条款。开发者需自行评估风险项目作者不承担因使用本项目导致的账号封禁、服务中断等后果。2. 核心功能与技术架构2.1 主要功能特性Sub2API提供了丰富的功能集使其成为一个完整的AI API管理解决方案多账户集成管理支持同时接入Claude、OpenAI、Gemini、Grok等多种AI服务的订阅账号提供OAuth和API Key两种认证方式可设置不同账号的优先级和权重智能API网关功能请求路由与负载均衡自动选择最优的上游账号处理请求会话保持Sticky Session确保同一会话的请求路由到同一上游账号并发控制可配置每个用户和每个账号的并发请求限制速率限制支持基于请求次数和token数量的双重限流机制配额与计费系统精确到token级别的用量统计实时余额计算与扣费支持多种计费模式按量付费、订阅套餐等内置支付系统支持支付宝、微信支付、Stripe等管理与监控可视化仪表盘实时监控API调用情况、账号状态、系统负载等详细的日志记录与审计跟踪告警功能配额不足、账号异常等情况自动通知扩展性功能Webhook支持关键事件可触发自定义回调外部系统集成通过iframe嵌入第三方系统如客服工单系统插件机制支持功能扩展2.2 技术栈与架构设计Sub2API采用现代云原生技术栈构建各组件分工明确后端服务编程语言Go 1.25.7Web框架GinORMEnt任务队列基于Redis实现前端界面框架Vue 3.4构建工具Vite 5UI组件库TailwindCSS状态管理Pinia数据存储主数据库PostgreSQL 15存储用户数据、配置、日志等缓存Redis 7会话管理、速率限制、队列等部署架构客户端 → Nginx → Sub2API应用 → [上游AI服务] ↑ PostgreSQL ↑ Redis这种架构设计使得系统具备良好的水平扩展能力可以通过增加应用实例来应对高并发场景。Redis作为集中式缓存和消息队列确保了多实例间的状态同步。3. 部署与配置指南3.1 环境准备在部署Sub2API前需要准备以下基础设施服务器推荐使用Linux系统x86_64或ARM64架构最低配置2核CPU4GB内存20GB存储生产环境建议4核CPU以上8GB内存以上依赖服务PostgreSQL 15用于主数据存储Redis 7用于缓存和队列Nginx可选作为反向代理网络要求能够访问上游AI服务API可能需要特定网络配置如需公网访问需准备域名和SSL证书3.2 三种部署方式对比Sub2API提供多种部署方案适用于不同场景部署方式适用场景优点缺点迁移难度脚本安装生产环境自动化程度高易于维护需要root权限中等Docker Compose开发/测试/生产隔离性好一键启动需要Docker环境简单源码编译定制开发灵活性最高复杂度高困难3.2.1 脚本安装推荐用于生产这是最简单的部署方式适合大多数生产环境# 执行一键安装脚本 curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/install.sh | sudo bash安装脚本会自动完成以下工作检测系统架构并下载对应版本的预编译二进制文件创建系统用户和组设置systemd服务安装到/opt/sub2api目录安装完成后通过systemd管理服务# 启动服务 sudo systemctl start sub2api # 设置开机自启 sudo systemctl enable sub2api # 查看状态 sudo systemctl status sub2api # 查看日志 sudo journalctl -u sub2api -f首次启动后访问http://服务器IP:8080进入设置向导按照指引完成数据库连接配置Redis连接配置管理员账号创建3.2.2 Docker Compose部署对于已经使用Docker的环境这是更便捷的选择# 创建部署目录 mkdir -p sub2api-deploy cd sub2api-deploy # 下载并运行部署准备脚本 curl -sSL https://raw.githubusercontent.com/Wei-Shaw/sub2api/main/deploy/docker-deploy.sh | bash # 启动所有服务 docker compose up -d这种部署方式会自动创建以下容器sub2api主应用postgresPostgreSQL数据库redisRedis缓存数据默认保存在本地目录便于备份迁移postgres_data数据库文件redis_dataRedis持久化数据3.2.3 源码编译部署需要定制功能或参与开发的用户可以选择从源码构建# 克隆仓库 git clone https://github.com/Wei-Shaw/sub2api.git cd sub2api # 安装前端依赖并构建 cd frontend npm install -g pnpm pnpm install pnpm run build # 构建后端包含前端资源 cd ../backend go build -tags embed -o sub2api ./cmd/server # 复制配置文件并编辑 cp ../deploy/config.example.yaml ./config.yaml nano config.yaml关键配置项包括数据库连接参数Redis连接参数JWT密钥用于会话安全默认用户并发数API Key前缀费率乘数3.3 反向代理配置在生产环境中建议使用Nginx作为反向代理提供HTTPS支持和负载均衡server { listen 443 ssl; server_name api.yourdomain.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; # 必须添加此项否则会丢失带下划线的头部如session_id underscores_in_headers on; location / { proxy_pass http://localhost:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # WebSocket支持 proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; } }配置完成后重启Nginx使更改生效sudo nginx -t # 测试配置 sudo systemctl restart nginx4. 使用与管理实践4.1 管理员操作指南成功部署后管理员可以通过Web界面默认端口8080进行系统管理用户管理创建/编辑/删除用户账号设置用户权限和配额查看用户API使用情况账号管理添加上游AI服务账号设置账号权重和优先级监控账号健康状态处理授权过期等问题系统监控实时API调用统计系统资源使用情况异常请求告警支付配置进入系统设置→支付配置选择支付提供商支付宝、微信支付、Stripe等填写商户ID、API密钥等凭证设置费率如每1000 tokens的价格保存并测试支付流程4.2 API使用示例开发者可以通过Sub2API生成的API Key访问统一接口而不需要直接使用上游服务的密钥。获取API Key登录用户控制台进入API Keys页面点击Create API Key设置名称和权限范围复制生成的Key格式如sk-xxx调用示例Pythonimport openai # 配置Sub2API端点 openai.api_base http://your-sub2api-server/v1 # Sub2API地址 openai.api_key sk-xxx # 从Sub2API获取的API Key # 调用ChatCompletion response openai.ChatCompletion.create( modelgpt-4, messages[ {role: system, content: 你是一个有帮助的助手}, {role: user, content: 解释一下量子计算的基本原理} ] ) print(response.choices[0].message.content)调用示例cURLcurl -X POST \ http://your-sub2api-server/v1/chat/completions \ -H Authorization: Bearer sk-xxx \ -H Content-Type: application/json \ -d { model: claude-2, messages: [ {role: user, content: 你好请介绍一下你自己} ] }4.3 高级配置技巧智能路由配置在config.yaml中可以设置账号选择策略gateway: strategy: weighted-round-robin # 加权轮询 # strategy: least-connections # 最少连接 # strategy: latency-based # 基于延迟 weights: claude-pro: 5 claude-basic: 1自定义限流规则可以为不同用户组设置不同的限流策略rate_limits: default: requests_per_minute: 60 tokens_per_minute: 60000 premium: requests_per_minute: 300 tokens_per_minute: 300000安全加固建议定期轮换JWT_SECRET启用CORS白名单配置IP访问限制启用操作审计日志5. 常见问题与故障排除5.1 部署问题问题1Nginx返回502 Bad Gateway检查Sub2API服务是否正常运行sudo systemctl status sub2api检查Nginx错误日志tail -f /var/log/nginx/error.log确保在Nginx配置中添加了underscores_in_headers on;问题2数据库连接失败检查PostgreSQL是否运行sudo systemctl status postgresql验证连接参数是否正确host, port, username, password检查pg_hba.conf是否允许连接问题3首次登录无法创建管理员账号确保没有预先创建config.yaml文件临时移除现有配置mv config.yaml config.yaml.bak重新启动服务访问设置向导向导完成后恢复原有配置5.2 使用问题问题1API返回401 Unauthorized检查API Key是否正确验证Key是否有访问目标API的权限检查Key是否已过期或被撤销问题2上游账号频繁失效检查是否违反上游服务的使用条款考虑使用住宅IP或降低请求频率配置多个备用账号实现自动切换问题3计费不准确检查config.yaml中的rate_multiplier设置验证上游服务的计费方式如Claude按token计费检查是否有未授权的API调用5.3 性能优化建议数据库优化为常用查询添加索引定期执行VACUUM和ANALYZE考虑读写分离Redis优化启用持久化适当增加maxmemory配置合理的淘汰策略应用层优化启用连接池调整goroutine数量启用响应缓存监控与告警配置Prometheus监控关键指标设置Grafana仪表盘关键异常触发告警如账号失效6. 生态与扩展Sub2API拥有活跃的社区生态围绕核心项目衍生了许多扩展工具和服务官方维护项目sub2api-mobile跨平台移动管理端iOS/Android/WebSub2ApiPay自服务支付系统现已集成到主项目社区贡献项目sub2api-cli命令行管理工具sub2api-prometheus-exporter监控指标导出器sub2api-terraform基础设施即代码部署模板商业服务提供商多家企业基于Sub2API构建了商业化的AI API网关服务提供更稳定的基础设施和专业支持CCTK.AI专注于稳定性和成本效益OpenModel生产级高可用服务ETok.ai一站式AI编程工具平台APIKEY.FUN低成本API访问方案这些服务通常提供更高的可用性SLA保障专业的技术支持企业级功能如发票、合同增值服务如IP隔离、专用线路对于需要更高服务等级的企业用户可以考虑在这些平台注册同时仍然保留自建Sub2API实例作为备用方案。
)
