OceanWay 最终方案：直接改造 new-api

历史方案：本页为恢复第一版多仓文档前的快照，不是现行任务或已实现能力。现行入口为平台架构。

版本：OW-ARCH-1.1，2026-09-12。用户在 v1.0 整理期间提出“降低复杂度，直接改造 new-api 更快”。本方案据此收敛为直接二开客户后台，替代 v1.0 首期拆出独立 Core、Edge、Contracts 的工程建议。独立供应网关、统一客户平台、独立产品与 OceanWay 设计风格保持有效。商业数值未确定，服务尚未改造或发布。

直接从官方 new-api 固定源码建设 oceanway-platform，保留用户、Key、定价、充值、余额、用量及 API 接入的已有协作方式；另保留接近官方的 new-api 做供应网关。Core 与 Edge 首期只是后台内部模块，不独立成服务。

1. 最终架构

OceanWay Platform 内部包括身份、Key、商业、账务、模型 API、客户任务和后台权限模块。模型请求在同一服务内完成鉴权、预扣、流式转发与结算，避免先把已有函数调用改造成跨服务协议。流式响应不全量缓冲，数据库事务不贯穿模型生成时间。

产品前端独立发布。Studio、Drama、Commerce 保留自己的项目、画布、剧本、商品与工作流；需要后端时放在各产品仓库，通过平台 API 使用客户与计费能力。所有供应商模型执行目标为经过统一网关；登录、充值、订单和产品编辑数据由各自业务服务处理。

2. 两套 new-api 的区别

两边数据库与数据库账号隔离，不直接读写对方表。客户积分只有 OceanWay Platform 扣减；网关内部配额不作为第二份客户钱包，网关扣额也不能直接等同真实供应成本。

这样确实形成两层调用，但职责明确：外层经营客户，内层执行供应。保留已有链路比先拆服务更少引入网络边界；代价是外层仍需维护自身协议与计量兼容性，不能保证网关新增任何协议后外层自动支持。

3. 最省改造的接入方式

首期不删除 new-api 的渠道模型和整个 Relay 链路。 OceanWay 后台只配置指向内部网关的连接，先利用现有兼容渠道类型打通文本；在客户 Admin 中隐藏供应商、渠道和供应密钥编辑入口。真正的供应商和渠道维护全部留在内层网关。

外层这条“内部网关连接”是后台连接配置，不在外层再维护每个真实供应商或建立平行的供应调度规则。由部署配置或受控内部维护入口管理。客户 Key 在外层验证，向内层发送服务凭据，不透传客户凭据。

先验证实际使用协议，逐项核对模型名、请求字段、响应/流式事件、错误及用量。new-api 的兼容渠道能否承接每一种目标协议必须测试；必要时在外层增加薄的 Gateway Adapter，而不是复制一遍供应商 SDK。

静态核查发现 Relay 已串联定价、预扣、渠道选择与退款，Distribute 同时承担模型权限检查。先保留这些协作关系，可以避免为了“删干净”而重写请求链路。

外层不执行供应商选择；供应侧重试以内部网关为主。需检查外层的自动重试配置及代码，禁止对可能已执行的付费请求盲目再提交。模型权限、授权和客户预算不能因关闭外层供应管理而被移除。

媒体接入采用同样原则：先验证 new-api 现有任务/插件能力与自研媒体网关的提交、查询、取消、结果、用量协议。缺口明确后做最小适配，不将所有媒体协议都已兼容当成方案前提。

4. 仓库与模块组织

首期不新建独立 Core、Edge、Contracts 服务或仓库。API 规范与生成客户端先在 oceanway-platform 内维护版本；需要独立发布时可发布制品，无需先另建仓。旧 Core/Edge/Contracts 工作树原地保留，不恢复旧 TypeScript 实现，不在本轮删除或搬迁。

逻辑上仍是多产品、多仓项目；只收敛共享后台的服务边界。不再把“14 仓”或“15 仓”作为实施目标，实际清单以已有远端和当前职责映射为准。

本地 platform/oceanway-platform 是已建立的官方固定源码工作区，与 text-gateway 共享 Git 元数据；当前不等于独立远端或可运行新平台。启动实现前明确独立分支/远端映射与发布身份，不能因共享 Git 工作树误把客户改造推入供应网关更新线。

5. 技术栈与数据方案

直接沿用已核验 new-api 源码的 Go、Gin、GORM、Redis 技术体系，不为架构整齐引入新后端语言。新客户平台建议主库统一为 PostgreSQL；不同时建设多种数据库部署方案。上游依赖见 固定版本 go.mod。

产品前端采用 React、TypeScript、Rsbuild、TanStack、Tailwind CSS 4、shadcn/Base UI，使用 OceanWay 品牌资源。现有 Docs 工程、已安排原型与媒体服务不在本轮强制改写。依赖和工具链固定经验证的版本，平台与网关不要求每次同步升级。

客户后台保留已有数据结构作为起点，按需求增加价格版本、客户协议价和必要账务记录，不先发明另一套身份与钱包系统。人民币支付订单记录整数分，积分的最小单位与舍入规则明确，金额计算不使用浮点数。Redis 用于缓存、限流与协调，不作为余额或任务的唯一事实源。

初期以后台进程、网关、数据库、Redis、反向代理构成运行环境；本地可用 Compose。只有长任务或恢复工作需要隔离时，才从同仓启动 Worker 进程。生产实例数和高可用布局根据容量与恢复验收决定，不预先引入复杂集群平台。

6. 客户价格与充值

所有客户共享完整的已接入销售目录，受实际模型能力、账户授权和资源限额约束。客户价格和供应路由独立，企业不需要通过单独站点获得协议价。

优先复用 new-api 的价格分组与倍率能力覆盖普通零售和标准企业方案；只有其无法表达的账户级协议价、价格版本和展示细节再扩展。不能把价格分组当作企业成员权限，也不能让网关的供应分组隐式决定客户售价。

本方案推荐按模型和计量维度解析价格：生效的账户协议价 → 账户绑定的价格方案 → 明确的公开基准价。没有完整价格则拒绝付费调用，不默认为免费；不把多套折扣默认相乘。调用开始时保存价格依据，结算按实际用量与该版本进行。

充值套餐决定“人民币实付对应多少积分以及赠送记录”；模型消费决定“用量消耗多少积分”，两者分别配置。具体换算比例、赠送、套餐、生效时间与协议价金额仍待商业定案，不能直接继承 sub2api 或 uumi 的数值作为新平台默认值。

企业首期为专属账户与协议价，不做多人协作；内部团队三人的管理权限另行设计。Admin 展示客户价格与账务，供应维护进入网关后台。

7. 必须验证的计费与故障处理

单体改造降低了 Core/Edge 拆分产生的网络问题，但不会消除后台与网关之间的失败窗口。复用原计费实现后，仍要针对实际使用链路补验证与必要修复：

• 客户预扣、实际消费、释放/退款有持久关联；重复支付回调或重复结算不得重复入账。
• 请求关联平台操作标识与网关请求/任务标识；结果不明时可查询或核对。
• 客户断流、后台崩溃、请求超时不等于供应未执行；不能直接退款后自动重新调用。
• 最终用量缺失进入待核对状态，不能按零或用估算伪装最终账单；网关可查询标识和用量证据是接入验收项。
• 高并发下原子检查和扣减额度；如调用可能超出预留，需要明确输出上限、报价或追加额度规则，不能只靠调用结束后扣费。

不为首期额外建设独立计费服务或消息平台。优先沿用已有账务和任务模块，补持久约束、恢复记录与必要核对任务。是否重构某段实现由失败用例和产品需求决定。

8. Worker 与产品工作流

首期使用 new-api 已有任务能力作为单次供应任务起点；平台保存客户操作、价格和结算关联。后台同仓的任务模块负责轮询、结果关联与补偿，需要时以独立 Worker 进程运行。

产品工作流仍归产品，例如剧本 → 分镜 → 图片 → 视频。每步调用平台，保留依赖、已完成结果和人工选择；共享后台不承担全部创作业务。工作流状态需可恢复，不能只存在浏览器内存或一次 HTTP 进程中。

若现有任务机制不足，先增加 PostgreSQL 持久任务记录、租约与有限重试，不引入通用工作流平台。任务重领不等于再次提交供应请求；上游不支持幂等、且提交结果未知时先核对。多 Worker 更新需校验租约/版本，避免旧执行者覆盖新结果。

9. 前端与统一登录

Console 直接参考 new-api 客户页二次修改，以 OceanWay 风格补齐模型价格、用量、充值与账单细节；Key 掩码旁按钮直接获取完整 Key 并复制，后台校验身份和归属。Admin 聚焦客户、价格、账务和团队审计；供应运维首期继续使用网关原有界面。

Developer 是公开模型、文档与教程门户，登录后的管理跳转 Console。Site 提供品牌与产品入口。Drama、Studio、Commerce 原型用户已安排，本会话不重复派发，也不把安排当成完成。

统一账户由 OceanWay Platform 负责。子站优先复用受控同源 API 代理和集中登录；跨站需要时设计短期、单次、绑定回调目标的会话交接。new-api 已有登录不等于已具备完整子站 SSO，不能把长期凭据放在跳转 URL。具体登录渠道、注册策略和域名仍待确定。

Console Playground 暂不作为底座前置：可后续适配 uumi，也可引导 Studio，沿用用户尚未选择的两个候选。

10. uumi、迁移与升级

保留独立供应网关角色，不立即停用 uumi。先把 uumi 的渠道、供应能力及必要定制列清单，在隔离的近官方实例验证；现有部署可作为过渡供应端。最终复用现有实例还是由干净实例承接，是部署迁移选择，不改变两层职责。

零售和企业最终都进入 OceanWay，sub2api 在完成迁移与对账后退役。迁移逐批核对账户认领、模型映射、实际价格、余额/套餐换算和 Key 策略。旧余额不能直接相加：sub2api 非 1:1 的充值与 uumi 倍率体系需先归一化。已有客户切换并发生新消费后，回退需要对账，不能只恢复旧库抹去消费。

网关独立跟随上游，客户后台按自己的版本演进。升级验证协议、流式、错误、用量、任务和取消行为；新模型仍需外层建立销售价格与回归用例。供应成本和客户账务分别核对，不依赖读取网关数据库来直接扣客户积分。

11. 实施顺序

不等待所有产品页面完成才验证网关连接，也不以“复用了 new-api”代替业务验收。API 规范先随 oceanway-platform 维护，Docs 解释使用方式，coordination 记录任务状态；不要求先经 GitHub Issue。

性能验证区分入口附加延迟、在线流式连接、单账户计费热点、媒体队列及供应延迟。先明确或测出目标负载，再给出实例数量与容量结论。可横向扩容同一后台进程；只有实测证明接入与业务资源争用明显，才考虑独立 Edge。

下一步是 N0 的直接运行与内部网关调用验证，并继续 N1 的 Console/Admin 需求与原型。当前仅完成方案调整，没有初始化新服务、改动生产或迁移客户。

12. 什么时候再拆 Core / Edge

只有出现独立发布需求、流式连接明显影响管理接口、独立团队承担服务，或性能数据证明必须拆分时，再把已清晰划分的内部模块提取。首期不为可能的未来先建设跨服务鉴权、预留、结算与事件接口。

v1.0 的独立 Core/Edge 方案保留为追溯资料，其首期拆分顺序已被本页替代。有关商业数值、登录政策、首发模型、内部角色和目标容量的待定事项继续保留，不据此反复改变客户平台与供应网关的职责。

相关入口：Console 需求 · Admin 需求 · 价格设计 · 接口映射 · 总体实施计划 · 当前进度。