历史 · API、数据与基础设施

历史档案 · 2026-09-11 重构前快照。 本文中的“当前”“已冻结”和实施顺序属于旧基线。新版本以现行总览和实施计划为准。

OceanWay 已采用 14 仓 Polyrepo；其中 oceanway-core 保持模块化运行时，接口、数据和领域所有权必须可独立演进。本章定义各产品与 Core 如何通信、谁能写哪些数据、长任务如何可靠执行，以及故障后如何恢复和对账。

运行拓扑

公共站、各产品 Web、Admin 与 Public API Edge 分别拥有独立 Git 仓库和发布边界；公开 Developer Center 与登录后 Console 则由同一 oceanway-console 仓库和制品承载。ai.oceanway.tech 只提供公开只读内容，登录后 Developer Control 位于 console.oceanway.tech/ai，api.oceanway.tech/v1 只接受机器凭据。各 Surface 通过 oceanway-contracts 的固定版本调用 oceanway-core，不得复制 Core 领域实现，也不得依赖浏览器跨域访问内部服务或数据库。

Admin 普通读取经 Core Operations Query 取得低敏读模型与 Telemetry Reference；只有活跃 Case 下的显式内容展开才使用独立 Authorized Telemetry Query，并要求专用 Audience 的短期 Workload JWT、Core 签发且绑定基础 Query Grant 的 SensitiveDebugGrant 与 fail-closed Audit。两条读取路径、Client、Scope 和网络策略分离，浏览器不直接获得任何 Grant 或访问 Telemetry Store。

接口分层

Product BFF 适合聚合页面数据；公共 API 适合稳定的程序调用；领域模块之间使用明确 Service Contract，不能通过“知道表名”集成。

客户 Webhook 是 OceanWay 向客户系统发布的公开事件，使用 Environment 下 Webhook Endpoint 自己的 WebhookSigningSecretVersion。Provider Callback 是未来可选的 Media Gateway 内部能力，不是独立平台服务；启用时必须使用不同入口、Provider Callback Secret、Schema 和处理身份，不能复用客户 Webhook、DeveloperCredential 或 ProviderCredentialVersion。

开发者入口与控制面

开发者产品固定使用三个相互隔离的入口：

Developer Access Domain 统一拥有 Developer App → Environment → Service Account → DeveloperCredential。Service Account 唯一归属 Environment，DeveloperCredential 唯一归属 Service Account；Console BFF 调用该领域的 Query/Command，不能直接写表或另建资源副本。

console.oceanway.tech/ai 的用量查询固定为 API Surface 视图。充值、购买、订阅、发票和跨产品消费总览调用 Console 的统一 Commerce/Billing 契约；Developer BFF 只能读取授权摘要或生成受控跳转，不能直接写钱包、订单或账本。

Playground 位于 console.oceanway.tech/ai。浏览器使用 Customer Session 调用同源 Developer BFF；BFF 从 Developer Access Domain 取得目标 App、Environment 和 Service Account 的 Access Snapshot，并向 Authorization/Policy Token Issuer 申请短期、单用途的内部执行委托，再进入与 Public API 相同的 Run、计量和计费链路。BFF 不能自行签发 Grant。Playground 不读取、恢复或向浏览器注入长期 DeveloperCredential，api.oceanway.tech 也不因此接受 Customer Session。

请求上下文

所有写请求必须显式携带或从受信凭据解析：

requestId
traceId
correlationId
operationId
actorPrincipalId
executionPrincipalId
authentication  # Contracts 固定的嵌套严格判别联合，kind 决定分支专属引用
callerWorkloadPrincipalId?
tenantKind = organization | personal_space
tenantId
workspaceId
projectId?
billingAccountId?
idempotencyKey
expectedRevision?
clientVersion?

服务端按入口分别使用 Customer Session、DeveloperCredential、Playground Execution Grant、Delegated Agent Grant 或 Workload Credential，并结合 Membership/Personal Space 所有权与资源归属验证这些值，不能信任浏览器自行声明 Tenant、Service Account 或付款方。tenantKind + tenantId 严格判别 organization | personal_space，不得同时携带 organizationId/personalSpaceId 或为个人请求伪造 Organization。正式 API 的 Actor 和执行主体都是 Service Account；Playground 的 Actor 是 Customer User、执行主体是目标 Service Account；Customer Session 产品 Run 的 Actor=Execution Principal 且只保存稳定 Authentication Assertion Ref；Delegated Agent Run 的 Actor 是授权发起者、Execution Principal 是与 Agent Revision 绑定的 Agent Principal。Service Account 只允许出现在前两个分支；内部 Workload Principal 只描述当前服务 Hop，不覆盖业务 Actor。

requestId 对应一次入口或服务请求，traceId 对应一次分布式调用链，correlationId 连接跨队列、轮询、回调和补偿的长期流程，operationId 固定一次可能产生副作用的逻辑操作。异步消费者和未来 Provider Callback 通常创建新 Trace，并通过 Span Link、Correlation 和稳定领域 ID 关联原流程；不能把数小时任务伪装成一个持续不结束的同步 Span。

响应 Envelope 按信任边界分开，不建立跨全站的通用外壳：

• 面向浏览器的各产品 BFF 保留现有 { code, data, msg } 外壳，只用于 UI Session 驱动的网页交互，不扩张到 Public API 或服务间接口。
• Public API 成功响应平铺业务字段，不包装在 data 中；失败响应使用 OpenAI-style 嵌套 error 对象和顶层 requestId，并由公开 API 版本契约冻结稳定错误码及字段。
• 内部服务接口只使用 oceanway-contracts 发布的版本化 Envelope；不得复用浏览器 BFF 外壳，也不得自行发明未版本化的通用响应。

三类边界均不得返回 Provider 原始 Secret、账号、渠道、堆栈和内部重试策略。内部错误另行记录发生层级、阶段、提交确定性、重试与补偿语义，详细契约见管理员平台与运维控制面。

公共 API 规则

• URL 使用明确版本或兼容版本策略；
• 列表使用有界分页、稳定排序和游标；
• 创建接口接受幂等键并绑定请求指纹；
• 修改资源使用 expectedRevision 或 ETag，防止覆盖并发编辑；
• 长任务返回稳定 runId，通过查询、SSE 或 Webhook 获取状态；
• 媒体读取返回短期签名 URL 或鉴权流，不返回长期对象存储地址；
• 删除返回引用阻塞和影响摘要，不能偷换成归档；
• Deprecated 接口提供迁移文档、观测窗口和停止新调用时间；
• Webhook 使用签名、时间戳、事件 ID、重放保护和幂等消费。

DeveloperCredential 只在 api.oceanway.tech/v1 的 Public API Edge 鉴权，不能转发给私有网关或模型供应商。公开模型 ID 解析到 Model Offering，内部渠道细节保持私有。

长任务协议

规则：

• 创建和查询上游任务是不同动作，轮询超时不能再次调用创建接口；
• Worker 使用租约和幂等 Attempt，实例重启后可以接管；
• 上游状态未知时进入明确的未知/待对账状态，不自动重复外部副作用；
• 同一 OceanWay Attempt 只有一个 Route Binding 与 Route Snapshot；网关内只可沿完全相同路由做经证明安全的协议重试，任何换路由都由 Execution 创建新 Attempt；
• 重试次数、间隔、超时和并发只能来自供应商契约、管理员配置或已有资源保护策略；
• 用户关闭页面不会取消服务端 Run；
• SSE 只是状态投影，断线重放不能重新执行任务；
• 取消必须区分“尚未执行”“上游已接受”“副作用已发生”。

媒体长任务的详细组件与状态边界见调度、执行与模型网关池。Media Gateway以持久 Task/Provider Attempt和 Poller/Reconciler为基础；未来启用 Callback时，内部 Handler必须先持久化去重收据再形成 Observation。Operational Observation只能引用 Availability、Provider Evidence、Binding与 Route的完整内容寻址四元组，不能铸造规范 MeterEvent / ProviderCostFact，也不能直接完成 OceanWay Run、登记正式 Asset或写入用户账本。

数据所有权

即使这些表位于同一个 PostgreSQL Schema，模块也只能通过自己的 Repository 写入。数据库外键、唯一约束和事务保证领域内不变量；跨领域流程使用服务调用、Saga/补偿和事件。

Gateway Evidence 与 Metering Fact 是两个不同所有权边界。Gateway 负责忠实、不可变地保存 Provider 响应/账单来源及其摘要，向 Core 必填返回 usageEvidenceAvailability + costEvidenceAvailability 严格判别联合，只有 available 分支携带对应 Evidence Ref/Schema Version/Digest Algorithm Version/Digest完整四元组，其他分支禁止全部 Evidence四元字段；Metering 验证 Evidence 与 Execution Attempt 的绑定，规范单位/币种、幂等去重，并通过追加式替代事实处理供应商更正。Gateway、Operational Observation、Telemetry 和 Operations Read Model 都不能成为规范 Fact Writer 或客户结算触发器。

存储职责

PostgreSQL

保存身份、所有权、领域状态、版本元数据、任务、账本、权限、审计索引和 Outbox。在线请求使用按租户、实体、状态、时间窗与分页的定向查询，不读取整表后在 Node.js 筛选。

对象存储

保存图片、视频、音频、文档和导出包。业务只保存稳定 storageKey；读取、下载、外部模型输入和 MCP 传输分别签发短期 URL。删除前检查 Asset Graph 与所有产品引用。

Cache

只缓存可再生的公共配置、目录或派生读模型。Membership、预算、Secret 状态和高风险审批不能依赖长时间缓存。写后读一致性要求明确的页面必须绕过或刷新缓存。

Search

索引资源标题、标签、授权摘要和必要内容。命中结果后再次执行租户和资源权限校验；索引删除滞后不能导致越权读取。

Analytics

保存脱敏、聚合的产品、质量、成本和业务指标，不作为钱包、权限或产品状态事实源。FDE 与案例指标需要保留来源和计算口径。

Secret Store

按用途保存加密 Secret 与轮换状态，不参与普通搜索、备份导出或业务 JSON 快照。DeveloperCredential 只在创建时返回一次 Secret，此后仅保存 Public API Edge 校验所需 Hash；WebhookSigningSecretVersion、MCPConnectionSecret 与 ProviderCredentialVersion 分别由 Developer Access、MCP 和私有 Gateway 的受控 Secret Store 托管。它们不能共享命名空间、Audience、加密材料或读取权限。

Telemetry Stores

Logs、Metrics 和 Trace 通过 OpenTelemetry-compatible Collector 进入专门后端。PostgreSQL 保存稳定运维对象、关联索引、Audit 和外部 Telemetry Reference，不长期承载全量高频日志、时序指标和 Span Payload。Telemetry 失败不能阻塞正常模型请求，也不能导致 Gateway Evidence、规范 MeterEvent/ProviderCostFact、Reservation、Ledger 或任务状态事实丢失。

事件与一致性

领域写入与 Outbox Event 在同一个数据库事务提交。首个实现阶段采用 PostgreSQL Outbox 与 Core 独立 Worker Process Role，不预先引入外部 Broker；投递仍按至少一次语义设计：

• Producer 固定 eventId、aggregateRevision、correlationId、可用的 operationId 和 Schema Version；
• Mandatory Delivery Set 在 Event Append 同事务冻结，避免 Registry 切版或 Dispatcher 崩溃改变同一事件的必达集合；
• Consumer 以 eventId 或业务幂等键去重；
• 失败消费者进入可观测重试或 Dead Letter，不阻塞原领域事务；
• 重放不能重复扣款、发布、发放权益或创建外部对象；
• Schema 变更保持向后兼容或提供版本化消费者；
• Search、通知、分析和任务摘要允许最终一致；
• 账本、所有权、权限与资源 Revision 需要强一致。

Event Envelope/Payload 与已接受的 Observation Source 由数据库约束和最小列权限强制不可变；published_at 只允许按冻结 Delivery Set 单向派生。Delivery Lease、Applied Receipt、Projection Checkpoint、版本化重建和外部 Broker 的引入条件由 ADR-030 与运维事件与读模型统一定义。Checkpoint 使用逐 Delivery/Receipt、未决集合和一致性快照边界，不使用会受提交乱序和回滚空洞影响的全局标量 Position。当前仅有事务内 Outbox 写入，不能写成事件已发布或消费者已应用。

跨领域操作若包含外部副作用，使用 Saga 记录已完成 Step 和补偿状态，不使用分布式数据库事务假装外部系统可回滚。

队列与租户公平性

Scheduler 至少按以下维度做授权和公平调度：

• Organization / Billing Account；
• Product 与任务类型；
• 交互式、批量、后台和 FDE 优先级；
• 模型 Provider 容量；
• Project、Member、Agent 与 Service Account 预算；
• 已预占成本和并发；
• 企业 SLA（如有）。

限流和队列保护必须来自供应商公开约束、管理员配置或容量测试，禁止用固定重试次数和延时掩盖 Worker、租约或状态机缺陷。

Provider 路由与故障

UUMI/new-api 是 Text Gateway Pool；oceanway-media-gateway 是同级 Media Gateway Pool，并直接连接图片/视频 Provider。两个私有网关只接受 OceanWay Workload Principal 使用的短期 Workload Credential，均不承载终端用户、客户组、DeveloperCredential、公共模型目录、用户售价、钱包、订阅、产品 Run 或正式资产归属。ProviderCredentialVersion 只存在于对应私有网关。完整职责、状态机和迁移方案见调度、执行与模型网关池。

Text/Media Gateway Pools 与 MCP Gateway 隔离供应商差异：

• Logical Model Policy 声明允许的 Deployment 候选；
• RunAdmissionManifest 固定 initial Deployment、Routing Policy Revision、协议和价格快照；每个实际 Deployment 由对应 AttemptExecutionManifest 固定，Gateway 再返回唯一 Route Binding/Route Snapshot；
• 熔断、健康状态和故障切换进入 Trace；
• 数据区域、训练政策和组织白名单优先于成功率；
• 已发生外部副作用或结果未知时禁止盲目切换 Provider 重做；
• Provider 下线不删除历史配置，只停止新请求；
• 供应商成本与 OceanWay 售价分别记录并对账。

可观测性与运维投影

可观测链使用不同标识协同，而不是复用一个万能 traceId：

Request ID
  → 当前入口与服务请求
Trace ID / Span ID
  → 当前同步或异步处理链及延迟
Correlation ID / Operation ID
  → Run、轮询、回调、恢复、补偿和外部副作用
Stable Domain IDs
  → GatewayTask、ProviderAttempt、AssetVersion、Reservation、Ledger 与 Audit

数据面边界：

• Logs：结构化服务诊断；不记录 Prompt、媒体、Secret、Authorization Header 或签名 URL。
• Metrics：延迟、成功率、队列、租约、Pool、Deployment、Provider、成本和租户公平性；标签保持低基数，禁止加入用户和请求 ID。
• Trace：服务调用、Run Step、网关与外部依赖；异步恢复和回调使用新 Trace 与 Span Link。
• Gateway Evidence：不可变 ProviderUsageEvidence / ProviderCostEvidence 与 source ref；它们不是规范计量或客户账务事实。
• Run/Asset/Metering/Billing Fact：业务与经济事实；规范 MeterEvent / ProviderCostFact 只由 Metering 追加，即使 Trace 被采样也必须可靠保存。
• Audit：主体、授权、资源、审批和特权动作的追加式不可变证据，不进入普通日志删除流程。

Operational Read Model 由 oceanway-core Operations 模块通过 Outbox 与私有网关规范化 Observation 构建，并经私有 Query API 供 Admin BFF 使用。它是可重建投影，不是新的事实源；Observation 对 Usage/Cost 只能保留 Gateway Evidence 引用，不能生成 Metering Fact 或触发结算。数据缺失或延迟时必须显示投影版本、进度、完整性、已接受 Observation 范围/健康窗口和“未观测”。Edge Observation 在 Intake 前保持 best-effort，范围和窗口不能证明请求全集完整，请求级完整性只能标为 unknown | not_measurable。Signed Workforce Grant 由 Core Authorization 签发；特权或跨租户查询必须在返回数据前耐久写 Audit，失败时关闭查询。Admin Command Gateway 只调用领域 Service，不直连数据库、Worker 或 Provider。

可靠投递、投影重建与查询授权见运维事件与读模型；SLO、Alert、Incident、Run Explorer、Error Fingerprint、敏感调试和 Reconciliation 的操作员视图见管理员平台与运维控制面。

备份、恢复与灾备

需要独立保护：

• PostgreSQL 业务库与账本；
• 对象存储 Blob 与引用清单；
• Secret 加密材料与轮换记录；
• 搜索、分析和读模型的可重建策略；
• Provider、DNS、TLS、Webhook 和部署配置。

恢复演练必须验证数据库与 Blob 的引用一致性、账本总额、Run 接管、Webhook 重放、权限撤销和 Secret 可用性。RPO、RTO、多区域和数据驻留根据企业合同与真实容量确定，文档不得提前写入无依据指标。

部署演进

Stage A：十三个活跃仓库与一个历史仓库（已执行）

• Site、Console、Studio、Drama、Commerce、Admin 与 API Edge 各自独立构建和发布；Console 同一制品按 Host 隔离 Developer Center 匿名路由与客户私有路由；
• Core、Contracts、Text/Media Gateway、Docs 与 Infrastructure 各自拥有独立仓库；
• oceanway-developer-center 停止独立开发和部署，完成迁移归零门禁后归档；
• Admin 使用独立 Workforce Session，API Edge 使用独立机器认证和限流；
• 跨仓只依赖固定 Contracts Release 和不可变制品。

Stage B：Core 模块化运行时

• Identity/Tenant、Wallet/Billing、Asset、Run、Agent、MCP 与 Model Control 位于 oceanway-core，保持模块专属 Repository、表、Outbox 与 Command Owner；
• PostgreSQL 与对象存储可以共享基础设施，但产品和 Surface 不直连 Core 数据库；
• 常驻 Worker、Queue、Search/Analytics 读模型可以独立扩容，不因此创建新的领域仓库。

Stage C：容量与故障域演进

• API Edge、Core Worker、读模型与网关按容量独立扩容；Text Gateway Pool 与 Media Gateway Pool 已是同级独立仓库和故障域；
• Media Gateway 的 Task/Attempt Registry、Dispatcher、Poller/Reconciler、结果处理与可选 Callback 仍属于其单一服务仓库；
• 保持稳定 Resource ID、Service Contract、Event Envelope 和 Trace；任何部署拆分必须有双读校验、切流和回滚方案，但不得形成业务双写。

服务化可以由容量、合规和故障隔离驱动；它不会自动触发将 Core 领域继续拆成更多 Git 仓库。

基础设施不变量

• 浏览器不直接访问数据库、内部 Worker 或供应商 Secret。
• ai.oceanway.tech 只提供公开开发者中心；登录后 Developer Control 只在 console.oceanway.tech/ai；公共机器调用只在 api.oceanway.tech/v1。
• Developer Access Domain 统一拥有 Developer App → Environment → Service Account → DeveloperCredential，其他产品和控制面只通过稳定服务契约使用。
• DeveloperCredential 与 Playground Execution Grant 在 Public API Edge 终止，私有网关只接受内部 Workload Credential。
• DeveloperCredential、WebhookSigningSecretVersion、MCPConnectionSecret、ProviderCredentialVersion 与 Workload Credential 不得混用。
• 每个领域只能直接写自己拥有的数据。
• 所有写请求有 Actor、租户上下文、幂等键和可追踪 Request ID。
• 长任务创建、查询、重试、取消和外部副作用语义分离。
• 领域事件至少一次投递，消费者必须幂等。
• 账本、权限、Revision 和资源所有权保持强一致。
• 搜索、分析和通知永远不是业务事实源。
• Logs、Metrics、Trace 和 Operational Read Model 永远不能代替 Run、Gateway、Asset、Billing 与 Audit 事实。
• 管理员查询只读授权投影；所有处置通过幂等领域命令并产生 Audit，不能直接改表。
• 任何自动故障切换都不能突破数据策略、预算或副作用安全边界。
• 备份完成不等于可恢复，必须定期演练。
• SLO、RPO、RTO、并发和超时来自合同、供应商约束与实测数据。