Sub2API 0.2.13

AI API Gateway Platform - 将 AI 订阅配额分发和管理

Important

本版本为 0.2.13：在完整保留 Fork 自有功能的前提下同时追平两条主线 ——
上游 Wei-Shaw/sub2api 的 main（v0.2.13）与 ranxi2001/sub2api 的 production（v2.9.6，批次十 Wei-Shaw#253 – Wei-Shaw#268）。
latest 与 0.2.13 均指向本版本。

版本号与 tag 均沿用上游编号 0.2.13（GoReleaser 强制语义化版本；应用内 parseVersion 只取前三段）。
0.2.13 大于此前的 0.2.12 / 0.2.11 / 0.2.91 / 0.2.10，应用内「检查更新」可正常提示升级。
上一个版本 0.2.12 已先行发布（docs/releases/v0.2.12.md），本版本在其基础上并入 ranxi 批次十与上游 v0.2.13。

Note

本次为 0.2.13（2026-10-02）：新增 Prism OAuth 浏览器桥接、API Key 并发限制与排队生命周期、
鹈鹕测智结果 API，以及上游的 TypeSafe 计费探测修复与 API Key 删除后的用量结算修复。
发布产物为 Docker 镜像（GHCR + Docker Hub 双 registry），Release 零附件（不附带二进制包与重登运行包）。

移植来源

• 来源一：上游 Wei-Shaw/sub2api 分支 main
  • 来源提交：b8dece900（v0.2.13，2026-10-02）；上次移植基准 458b92abd（v0.2.12，本 Fork PR #95）
  • 本次增量（458b92abd..b8dece900）：10 个提交（7 个非合并），7 个文件（+249 / −4）
• 来源二：ranxi2001/sub2api 分支 production（批次十）
  • 来源提交：bf9405e4a（PR Wei-Shaw#253 – Wei-Shaw#268，ranxi release v2.9.6 之后，2026-10-02）；上次移植基准 c2e3e098f（批次九，本 Fork PR #93）
  • 本次增量（c2e3e098f..bf9405e4a）：48 个提交（35 个非合并，含 13 个合并提交），257 个文件（+20350 / −837）
• 本次两条主线合入后，本 Fork 相对 main 净增：215 个文件（+19091 / −522）
• 新增迁移：237_add_api_key_concurrency_limit.sql（api_keys.concurrency_limit，启动时自动执行）
• 版本号：backend/cmd/server/VERSION 为 0.2.13（与上游 v0.2.13 同名）

上游 v0.2.13 增量（本次新增）

• TypeSafe 账号计费探测修复：默认开启上游计费自动探测会导致 TypeSafe API Key 账号创建返回 400，现按平台放行（fix(billing): allow upstream billing probe for TypeSafe API-key accounts）
• API Key 删除后的用量结算：计费完成前 Key 被删除时仍正常结算用量，避免漏账（fix(billing): settle usage when the API key is deleted before billing completes）
• 仓库安全策略：新增 .github/SECURITY.md（私有漏洞报告，含 dev@sub2api.org 兜底邮箱）

ranxi 批次十增量（c2e3e098f..bf9405e4a，PR Wei-Shaw#253 – Wei-Shaw#268，本次新增）

• Prism OAuth 浏览器桥接（Wei-Shaw#260 / Wei-Shaw#264 / Wei-Shaw#265 / Wei-Shaw#267）：新增 prism-adapter/（Python 浏览器适配器 + systemd 单元 + 冒烟脚本）
  与 Go 侧 backend/internal/pkg/prismbridge/、openai_prism_browser.go；
  支持账号测试路由、并发 HTTP 连接、服务端有界会话缓存；WS 会话不落在 Prism 账号上并给出适配器错误说明；
  未启动浏览器时释放账号；OAuth turn 生命周期加护栏。附 docs/PRISM_BRIDGE_RESEARCH_CN.md、docs/prism-oauth-p1-smoke.md 与截图
• API Key 并发限制与有界准入生命周期（Wei-Shaw#263）：Key 级 concurrency_limit 与等待队列（ZSET 等待 + 阶段结束标记 + Live 精确交接栅栏），
  统计口径按批分页且串行读取超过 100 个 ID 的页面；新增迁移 237_add_api_key_concurrency_limit.sql；
  前端密钥页新增并发列、/keys/concurrency 接口与策略只读展示
• 鹈鹕测智结果 API（Wei-Shaw#268）：API Key 可读取测智结果（含缓存类型断言修复、结果缓存）
• Codex 目录与套餐展示（Wei-Shaw#253 等）：生成的模型目录与 API Key 客户端保持兼容，补套餐展示与目录截图
• Grok CLI 版本提升至 1.0.44（Wei-Shaw#258）：对齐官方发布节奏（本 Fork 沿用上游抓包修正的 1.0.46 身份头与 grok-pager 标识）
• 鹈鹕面板明文 HTTP 预览（Wei-Shaw#262 / Wei-Shaw#259）：面板经明文 HTTP 提供时仍渲染预览；WS 准入用例适配
• 其它：fix(ws): isolate downstream write state across response turns（下游写入状态按 turn 隔离）、
  perf: pipeline API key queue statistics and verify upgrade paths、多项 lint / 测试适配

Fork 自有功能（完整保留）

• Codex 292 门票（x-codex-turn-state）打票与注入：独立代理后台打票、住宅 IP 请求覆盖该头，含后台开关、门票状态展示与缺票拦截
• 上游剩余额度探测：账号页可查询上游余额与用量窗口
• 账号代理车道（proxy lanes）：车道级调度、车道粘性绑定与准入并发控制；WS turn 准入沿用车道语义
• 管理员请求采集：按用户 / 上游账户 / 入口分组创建采集任务，默认关闭
• 凭证守护：令牌巡检、自动重登与错误态自愈（默认关闭），重登运行包来源可配置
• 账号质量运维、Excel / BPS 协议、Mihomo 托管 / 动态代理区域、Pelican 定时演练
• 图片创作 / 画布 / Studio Bridge、邮件广播、模型广场（model-square） 等
• 发布流水线：双 registry（GHCR + Docker Hub）推送；Release 零附件

升级说明

• 升级方式：管理后台左上角「检查更新」可一键升级；也可在服务器执行
  curl -sSL https://raw.githubusercontent.com/ziyue67/sub2api/v0.2.13/deploy/install.sh | sudo bash -s -- upgrade。
• 回滚方式：install.sh rollback <version>。
• 也可以使用 Docker 镜像部署：docker pull ghcr.io/ziyue67/sub2api:0.2.13，具体见 部署文档。
• 镜像只提供 linux/amd64 单架构，标签为 0.2.13 / 0.2.13-amd64 / latest（同一镜像）。
• Release 零附件：不附带 sub2api_*.tar.gz / *.zip / checksums.txt；重登运行包仅在手动勾选 publish_reauth_runtime 时上传。
• 数据库迁移：新增 237_add_api_key_concurrency_limit.sql（api_keys.concurrency_limit bigint not null default 0，含非负约束），启动时自动执行。
• Prism 桥接为可选部署：prism-adapter/ 需自行部署（README + systemd 单元），未部署时不启用该路由。
• 请求采集与凭证守护默认关闭，需在「系统设置 > 功能开关」中显式启用。
• 安装脚本与在线更新服务的默认仓库为 ziyue67/sub2api（backend/internal/service/update_service.go、deploy/install.sh）。

验证

• 合并冲突处理（本次两条主线共 26 个文件）：
  • 上游 v0.2.13（faec40680）：无冲突（git merge-tree 干净）。
  • ranxi 批次十（9105f98a0）：人工处理 26 个文件，原则为「Fork 特性优先、两侧语义取并集」：
    • backend/ent/mutation.go：APIKeyMutation 字段取并集（保留 group_routes，并入 concurrency_limit）
    • backend/internal/service/api_key_service.go、internal/handler/api_key_handler.go、internal/repository/api_key_repo.go、
      internal/service/api_key_auth_cache.go、api_key_auth_cache_impl.go：请求结构 / 快照 / 行映射取并集
      （Fork 的多分组路由 GroupRoutes + ranxi 的 ConcurrencyLimit），错误变量保留 Fork 的分组路由错误
    • internal/service/concurrency_service.go、gateway_service.go：AcquireResult / AccountSelectionResult 取并集
      （Fork 的 MaxConcurrency* / AggregateMaxConcurrency* / Lane + ranxi 的 RequestID / AccountRequestID）
    • internal/service/openai_gateway_scheduling.go：newSelectionResult 签名取并集（新增 requestID 形参并写入结果），
      保留 Fork 的 finalizeOpenAISelectionResult 车道语义；admitOpenAIWSTurnForPricing 的账号槽位改用
      TryAcquireAccountOrLaneSlot + 聚合上限参数（只传账号上限会让车道被账号桶限流）
    • internal/handler/openai_gateway_handler.go：BeforeTurn 保留 Fork 的每 turn 定价刷新 + 车道上限重算，
      同时叠加 ranxi 的 Key 排队准入与 turn == 1 提前返回；并发释放统一走 wrapReleaseOnDone
    • internal/server/middleware/api_key_auth.go：skipBilling 取并集（Fork 的 /v1/usage + 模型列表读 + 异步图片轮询，
      ranxi 的 Pelican 展示位读与过期校验）
    • internal/pkg/xai/*、internal/repository/http_upstream_test.go、internal/service/grok_upstream_headers_test.go：
      取 HEAD（上游依据官方交互式 CLI 抓包修正的 1.0.46 身份头 + grok-pager 标识），ranxi 的 1.0.44 / grok-shell 为更旧口径
    • 前端 api/keys.ts、types/index.ts、views/user/KeysView.vue、components/keys/__tests__/UseKeyModal.spec.ts、
      views/user/__tests__/KeysView.spec.ts：取并集（并发列 / 并发快照接口 + Fork 的多分组路由、分页断言与排序用例）
    • README.md：保留 ranxi 重写的正文并补回 Fork 的技术栈表
  • 合并后修正 2 处（编译 / 运行期才暴露）：
    • backend/ent/runtime/runtime.go：ranxi 生成的字段索引不含 Fork 的 group_routes，apikeyFields 索引整体错位，
      init() 在 nil 上断言 panic（所有依赖 ent 运行期的包启动即失败）；按当前 schema 的 Fields() 顺序重排 9 个索引，
      并校验全部 41 个 schema 的索引映射无错位
    • backend/internal/handler/gateway_systemone.go：上游新增的 System One 入口调用本 Fork 的用户槽位签名（需 apiKeyID / keyLimit）
    • backend/internal/handler/openai_gateway_handler_test.go：被拒 turn 的到达判定改为按 response.create 计数
      （本 Fork 中继会转发 session.update 并收到上游 ack，用通道帧数会误判）
• 校验口径：本版本的测试以 CI（GitHub Actions）为准：shell、test（make test-unit + make test-integration）、
  frontend（vue-tsc + 关键 vitest）、golangci-lint、release-helpers、backend-security、frontend-security。
  本地已完成 go build ./...、go vet -tags=unit ./... 与冲突文件的 gofmt 检查。
• 工作树检查：无残留冲突标记（<<<<<<< / >>>>>>>）。
• 发布配置校验：Docker 镜像标签为 0.2.13 / 0.2.13-amd64 / latest（GHCR 与 Docker Hub 同一镜像）；
  发布说明按 docs/releases/v0.2.13.md（与 tag 同名）由 release.yml / sync-fork-release.yml / backfill-release.yml 回写。

---

Docker 镜像（ziyue67/sub2api）

ziyue67/sub2api:latest
ziyue67/sub2api:0.2.13
ghcr.io/ziyue67/sub2api:latest
ghcr.io/ziyue67/sub2api:0.2.13

拉取示例：

docker pull ziyue67/sub2api:0.2.13
docker pull ghcr.io/ziyue67/sub2api:0.2.13

文档

• GitHub Repository
• Deployment Guide