功能地图

本页从产品能力而不是代码目录解释 Sub2API。部署前可以用它判断哪些功能是必需的，哪些功能应先保持关闭。

网关能力

能力	作用	主要依赖
API Key 鉴权	隔离用户与上游凭证	PostgreSQL、Redis 鉴权缓存
多协议入口	兼容 Messages、Responses、Chat、Gemini	协议 Handler 与转换包
模型映射	把客户端模型名映射到上游模型	分组与账号配置
账号池调度	在可用账号中选择最适合的账号	调度快照、Redis、账号状态
粘性会话	同一会话尽量复用账号	Redis TTL 绑定
故障切换	上游失败时更换账号	错误分类、候选排除集
SSE/WS	长连接和增量输出	代理超时、连接池、流式状态机
代理与 TLS 指纹	控制上游出口与握手特征	Proxy、uTLS、连接池隔离

账号管理

管理员可以：

• 手动添加 API Key、OAuth、Setup Token、Bedrock 或 Service Account。
• 通过不同平台的 OAuth 流程创建和重新授权账号。
• 批量导入、批量编辑、同步外部账号源。
• 设置代理、并发、优先级、负载因子和账号倍率。
• 限制模型、请求类型和客户端类型。
• 查看今日使用量、窗口额度、重置时间和健康状态。
• 临时取消调度、自动过期暂停、错误恢复和 token 刷新。

账号功能是整个系统的资源供给侧。账号配置错误往往会表现为大量用户同时失败。

用户与身份

登录方式

项目包含邮箱密码以及多种可选身份提供方：

• GitHub、Google 邮箱 OAuth。
• Linux DO。
• 微信开放平台、公众号或移动应用模式。
• OIDC，可接 Keycloak 等企业身份源。
• 钉钉内部应用。

身份源配置不应一次全部开启。每增加一种登录方式，都要配置回调地址、账号合并规则和邮箱可信策略。

用户控制

• 角色、状态、并发和 RPM。
• 余额与冻结余额。
• 指定可用分组。
• 用户 × 平台日/周/月配额。
• 自定义用户属性和外部身份绑定。
• 通知邮箱、余额提醒和 TOTP。

订阅、余额与支付

系统同时支持余额和订阅两种权益模型：

• 余额：按实际费用持续扣减。
• 订阅：绑定分组，有有效期和日/周/月窗口额度。
• 兑换码：可以发放余额或订阅权益。
• 推广返利：记录邀请与返利转移。

内置支付提供方包括 EasyPay、支付宝、微信支付、Stripe 等。支付功能还涉及提供方实例、负载均衡、限额、订单超时、回调签名和审计日志。

初次部署建议

如果只是团队内部使用，先关闭注册、支付和推广，只配置管理员、用户、账号、分组与 API Key。确认网关稳定后再开启财务功能。

计费能力

支持的计价维度包括：

• 输入和输出 Token。
• Cache creation、cache read、5 分钟/1 小时缓存。
• Priority、Flex 等 service tier。
• 长上下文倍率。
• 图片输入、图片输出和按分辨率价格。
• 视频按分辨率、时长或请求元数据计费。
• 按请求计费与批量图片折扣。

价格数据可以从远程仓库更新，并有本地 fallback 文件和部分硬编码回退。新增模型后应先确认价格是否可解析，再开放给用户。

风控与安全

• Cloudflare Turnstile 注册保护。
• 用户、API Key 状态与 IP 黑白名单。
• 内容审核、命中 hash、封禁与解封。
• 错误响应头过滤和 CSP。
• 上游 URL allowlist 与私网地址限制。
• 代理探测与 TLS 指纹模板。
• TOTP、JWT、登录会话撤销。
• 管理员合规确认和支付审计。

默认配置兼顾自托管灵活性，不等于生产安全基线。部署时必须按生产安全加固收紧。

运维能力

实时状态

• 用户和账号并发。
• 实时流量、QPS、成功率和延迟。
• 账号可用数量、限流和错误状态。
• OpenAI WebSocket 连接池与调度运行指标。
• 用量 worker、平台配额 flusher 等内部队列状态。

历史数据

• 用户与管理员使用记录。
• 错误详情和上游错误归因。
• 小时/日预聚合指标。
• 渠道监控历史与 daily rollup。
• 告警规则、事件和系统日志。

自动任务

• OAuth token 刷新。
• 账号、代理、订阅和订单过期处理。
• 用量与运维数据清理。
• 仪表盘与运维指标聚合。
• 渠道监控和定时账号测试。
• 备份、批量图片 worker 和恢复任务。

功能启用顺序建议

第一阶段：网关可用

1. 管理员与 TOTP。
2. 一个上游账号。
3. 一个分组。
4. 一个测试用户和 API Key。
5. 非流式与流式请求验证。

第二阶段：稳定运行

1. 多账号与代理。
2. 调度、粘性和 failover。
3. 账号测试、渠道监控和告警。
4. PostgreSQL/Redis 备份与恢复。

第三阶段：开放用户

1. 注册与身份源。
2. 分组权限、订阅和配额。
3. 内容审核、IP ACL 和通知。
4. 用户文档与服务条款。

第四阶段：商业能力

1. 支付沙箱和回调验证。
2. 订单对账与幂等测试。
3. 退款、异常订单和客服流程。
4. 财务监控与审计保留策略。