项目指南

项目指南面向准备阅读、修改或优化 Sub2API 的开发者，重点回答“这个系统是什么、为什么这样设计、一次请求如何穿过代码”。

它不会把后台按钮操作和故障处置混进架构说明。上线后的账号维护、监控和排障请转到运维指南。

你会建立的系统模型

HTTP/Gin 入口
  → API Key 鉴权与权益检查
  → Group/Channel/Model 路由
  → Account Scheduler
  → 平台 Gateway 与协议转换
  → 上游 HTTP/SSE/WebSocket
  → Usage、Billing、Ops Error
  → PostgreSQL + Redis

推荐阅读路径

快速了解

1. 项目概览
2. 项目架构
3. 核心概念
4. 请求处理链路

准备开发功能

1. 启动、配置与事实来源
2. 代码目录与模块
3. 数据、缓存与一致性
4. 信任边界与安全模型
5. 鉴权与前置检查
6. 调度、粘性与故障切换
7. 协议转换与流式传输
8. 开发与定制入口

准备修改管理后台

1. 前端控制面架构
2. 用户、API Key 与权限
3. 账号状态机与恢复语义
4. 测试与变更验证

准备修改支付或商业化能力

1. 用量、计费与配额
2. 支付与订单子系统
3. 数据、缓存与一致性
4. 信任边界与安全模型

准备做性能优化

1. 后台任务与多实例
2. 用量记录与错误归因
3. 性能优化地图
4. 系统设计审视与演进建议

开发者应该先回答的问题

• 变更属于管理面、数据面还是后台任务？
• 最终事实保存在 YAML、PostgreSQL、Redis 还是进程内存？
• 它修改的是用户权益、路由、上游协议还是计费？
• 热路径是否会新增 DB 查询或 Redis 往返？
• 多实例是否需要锁、缓存失效或 outbox 同步？
• 流式请求在客户端断开时是否释放并发和记账？
• requested/upstream/billing model 是否仍可解释？
• 错误会被归因到 client、provider 还是 platform？
• 改动需要 unit、integration、协议、支付还是多实例验证？

先沿真实请求链定位，再决定抽象和改动范围。

当前设计审视结论

整体上，模块化单体 + PostgreSQL + Redis 仍适合当前系统，不需要为了形式立即拆微服务。更值得优先补强的是：安装状态与认证 Secret 的恢复、liveness/readiness 分离、动态配置跨实例传播、支付履约持久化，以及可执行的 E2E/fake upstream。完整依据和实施顺序见系统设计审视与演进建议。

与另两套指南的关系

• 本地开发、源码构建和镜像发布：源码开发与构建
• 配置、部署和基础设施：部署指南
• 后台资源操作、巡检和 Runbook：运维指南