管理员平台与运维控制面

OceanWay 管理员平台不是服务器日志查看器，也不是把用户、模型、账单和 Gateway 管理页拼在一起。它是一套以业务执行链为中心的内部控制面：从一个用户可提供的 Request ID 出发，定位身份、预算、Run、网关、Provider、资产和账务事实，判断影响范围，执行受控处置，并留下可复核证据。

本章定义 admin.oceanway.tech 的产品定位、身份边界、运行数据契约、页面结构、处置权限与交付顺序。具体模型执行状态见调度、执行与模型网关池，账务事实见钱包与商业系统，客户与内部权限边界见权限、安全与治理。

正式决策

产品边界与仓库边界不要求同时拆分。首期可以由同一个 Next.js 服务按 Host 分流；只有安全隔离、团队边界、容量或独立发布节奏形成真实需求时，才把 Admin BFF、Operational Read Model 或 Telemetry 服务物理拆出。

当前实现基线与处置

现有后台已经拥有可复用的业务骨架，但尚未形成平台级运维控制面：

迁移不是简单改域名。以下当前做法只能作为过渡：普通用户 Session 加 role=admin、大粒度 system.manage/generation.manage、可以删除的“日志”、孤立的人工补录按钮，以及通过页面各自查询数据后由管理员自行拼接因果关系。

两类管理员必须分离

企业 Owner、Organization Admin、Billing Admin 和 Security Admin 不是 OceanWay 内部管理员。OceanWay 客服也不能因为能够搜索客户账户，就自动获得 Prompt、媒体原件、Provider Secret 或账务修改权限。

管理员角色基线

“全权限管理员”只用于受控 Break-glass，不是日常岗位。Incident Commander 是协调责任，不是权限叠加器。

目标控制面拓扑

Admin Query BFF 只聚合经过授权的读模型和 Telemetry 引用。Admin Command Gateway 只接受明确的领域命令；它不能执行任意 SQL、任意 HTTP 转发或绕过 Text/Media Gateway 的状态机。

一条可还原的业务执行链

管理员需要同时看到关系图与真实时间轴。标准业务顺序是：

Public Request
→ Identity / Policy Decision
→ Quote / Billing Reservation
→ Run / RunStep / Execution Attempt
→ Gateway Dispatch
→ Text Gateway Invocation 或 Media Gateway Task
→ Provider Attempt / Observation
→ Result Fetch / Validation / AssetVersion
→ Usage Fact / Settlement / Release / Refund
→ Product Binding / Customer Webhook

账务预占发生在外部调度前；结算发生在可信 Usage 或正式输出确认后。页面不能为了画出一条直线而改变真实因果顺序。某一环没有可信事实时显示“未知/未观测”，不能按时间接近、相同模型或相似 Prompt 猜测关联。

ID 与关联契约

长任务不能让一个 traceId 承担所有身份语义：

规则：

• OceanWay 在调用私有网关前固定 correlationId + operationId + executionAttemptId。
• 网关接收标准 traceparent 和不透明 OceanWay Operation Reference，自行产生 gatewayTaskId/providerAttemptId。
• Provider 不支持 Trace 透传时，由 Gateway 保存本地映射；不得伪造 Provider 已支持 Trace。
• Poll、未来 Callback、队列恢复和人工命令通常形成新的 Trace，通过 Span Link、correlationId 和稳定领域 ID 关联原操作。
• Asset 登记保存来源 RunStep、Execution Attempt、Gateway Task 和可用的 Provider Attempt 引用。
• Reservation 保存 operationId 与价格快照；结算关联可信 Meter/Usage Fact。
• Public Request ID 只能通过授权查询解析到内部 ID，不能用连续编号或可猜测 URL 暴露跨租户信息。

运维读模型

Operational Read Model 是可重建的跨域投影，不是新的万能事实库。它至少提供：

OperationSummary
  request / correlation / operation
  actor / organization / workspace / project
  product / surface / capability
  run / step / execution attempt
  gateway pool / deployment / gateway task
  provider attempt summary
  asset persistence summary
  billing reservation / settlement summary
  current error / alert / incident / reconciliation links
  latest trustworthy boundary

它由领域 Outbox 和 Text/Media Gateway 的规范化 Observation 更新。控制面不读取 Gateway 私有表，也不复制 Provider Credential、完整请求、原始媒体或用户账本。读模型滞后时页面同时显示投影水位和源事实更新时间，不能把“尚未同步”误判成“业务不存在”。

统一错误模型

错误不能只保存 status + message。每个 ErrorOccurrence 至少包含：

errorId
occurredAt / observedAt
service / layer / domain / phase
code / severity
certainty
retryDisposition
compensationDisposition
sanitizedMessage
errorFingerprint
causeErrorId?
requestId / traceId / correlationId / operationId
runId / runStepId / executionAttemptId
gatewayPoolId / gatewayDeploymentId / gatewayTaskId / providerAttemptId
logicalModelId / modelDeploymentId / provider / configRevision
assetVersionId? / reservationId? / meterEventId?

错误层级

稳定层级至少覆盖：

edge
identity_policy
billing_preflight
execution
gateway_dispatch
gateway_protocol
provider
poll_reconciliation
result_fetch
media_validation
asset_persistence
billing_settlement
customer_webhook
mcp
internal_worker

未来启用 Provider Callback 后，可以增加 provider_callback，但不能提前把它写成当前主链路能力。

提交确定性

certainty 是判断能否重试的关键字段：

rejected_before_dispatch
not_submitted
submitted
provider_accepted
unknown

• rejected_before_dispatch/not_submitted 可以依据同一 Operation 的安全语义恢复。
• submitted/provider_accepted 只能继续查询、取回结果或等待终态。
• unknown 必须进入 Reconciliation，禁止自动换 Gateway、Supply 或 Provider 重发。
• 用户主动“再次生成”创建新的业务 Attempt，不能覆盖旧错误或复用旧经济身份。

错误内容分层

Error Fingerprint 由稳定低敏字段组成，例如层级、规范化错误码、Pool、Deployment、Provider、模型部署、协议阶段和脱敏函数位置。完整错误正文、Request ID、用户 ID、Prompt 或 Provider 动态任务号不能参与指纹，否则每次错误都会被错误地分成新组。

Error、Alert 与 Incident 的关系

Error Occurrence
→ Error Fingerprint Group
→ SLO / Rule Evaluation
→ Alert Instance
→ Incident（存在实际或高风险客户影响时）
→ Mitigation / Recovery
→ Reconciliation Cases
→ Postmortem / Follow-up

• 一次错误不必产生告警。
• 相同 Fingerprint 的错误按受影响产品、Pool、Deployment、组织数和时间窗聚合。
• Alert 是需要值班确认的信号，不等于已经发生客户事故。
• Incident 是有人负责、需要协同处置和沟通的影响事件。
• Incident 关闭前必须扫描受影响的 Run、Asset、Reservation 和 Webhook，不能只看成功率恢复。

Logs、Metrics、Trace、业务事实与 Audit

结构化日志

普通日志使用结构化字段，至少包含服务、环境、版本、时间、严重度、规范化错误码和可用的 Trace/Correlation 引用。不得记录：

• Prompt、System Prompt、内部规划和完整模型输出；
• 图片、视频、音频、Base64 和文档正文；
• API Key、Cookie、Session、Authorization Header；
• Provider Credential、Callback Secret、支付凭据；
• 长效或短期签名 URL；
• 未脱敏的 Provider 错误页和完整 Callback Payload；
• 不必要的用户邮箱、手机号或支付信息。

Telemetry 写入失败不能阻塞正常模型调用。确需保存原始 Provider 证据时，只能进入加密、限时、Case-scoped 的受限存储，并在普通日志中保存不可逆 Digest 和受控引用。

Trace

建议的 Span 语义：

http.request
identity.authorize
billing.quote
billing.reserve
run.step
gateway.dispatch
gateway.accept
provider.submit
provider.poll
result.fetch
asset.persist
billing.settle / release / reconcile
customer_webhook.deliver

Trace 采样不能让经济事实丢失。Reservation、Usage、Ledger、未知提交、人工处置和特权动作无论是否采样，都必须进入自己的领域事实或 Audit。

Metrics 与 SLO

Metrics 标签只使用低基数维度，例如 service、region、surface、capability、pool、deployment、model family、provider、status 和 normalized error code。禁止把 userId、organizationId、requestId、traceId、runId 或 upstreamTaskId 放进标签。

首轮指标至少覆盖：

• 请求量、成功率和延迟；
• Text Pool 与 Media Pool 独立健康；
• Provider 429、5xx、超时和未知提交；
• 排队时长、任务停留、Worker Lease 与恢复；
• Provider 成功但结果未取回、Asset 校验与落盘失败；
• 未终态 Reservation 数量、金额和停留时长；
• reconciliation_required 数量、金额与最旧案件；
• Provider Usage、供应成本与 OceanWay Settlement 差异；
• Webhook 延迟、失败和重放；
• Telemetry、Outbox 与 Read Model 的摄取缺口。

SLO、告警阈值、容量和保留期来自客户合同、Provider 公开约束、容量测试和管理员配置。架构文档不写无依据的固定次数、延时或百分比。

运行指挥台

后台首页同时回答“现在是否异常、影响谁、从哪里开始处理”：

• OceanWay Edge、Identity、Billing、Execution、Asset 和 MCP 状态；
• Text Pool、Media Pool、每个 Gateway Deployment 和 Provider 的独立状态；
• 队列、Worker、Lease、未知提交、结果落盘和对账积压；
• 当前 SLO Burn、Open Alerts、Open Incidents；
• 受影响 Surface、Offering、Organization 数量和预计经济影响；
• 最近 Deployment、模型、路由、价格和 Secret 变更；
• Telemetry 与读模型自身的新鲜度。

一个 Provider 异常不能让首页把整个 OceanWay 显示为“全部不可用”。平台健康、产品健康、Pool 健康和单一 Deployment 健康必须分层展示。

全局检索与 Run Explorer

全局检索支持精确输入：

• 用户公开账号 ID、受限邮箱或企业名称；
• Public Request ID、Trace ID、Correlation/Operation ID；
• Run、RunStep、Execution Attempt；
• Gateway Task、Provider Attempt 或上游任务 ID；
• Asset、AssetVersion、Storage Key；
• Reservation、Meter Event、Ledger Entry；
• Alert、Incident、Reconciliation Case。

模糊搜索只能返回获得权限的脱敏摘要；内部 UUID 不得作为用户信息缺失时的回退展示。上游任务 ID、Storage Key 和财务 ID 的查询需要对应职责，不能因为能搜索 Run 就自动扩展权限。

Run Explorer 详情页至少包括：

1. 请求摘要、客户影响和当前可信状态；
2. 身份、组织、Workspace、Project 与付款方；
3. Quote、Reservation 和预算判断；
4. Run、Step、Attempt 与 Execution Manifest Revision；
5. Pool、Gateway Deployment、模型和配置版本；
6. Provider Attempt、Poll/Observation 与提交确定性；
7. Result Fetch、媒体校验、AssetVersion 和产品 Binding；
8. Usage、Settlement、Release、Refund 与 Margin Fact；
9. 规范化错误、关联 Logs/Trace、Alert 和 Incident；
10. 人工命令、审批与 Audit Timeline。

原始 Prompt、参考素材和生成结果默认不展示。需要内容诊断时，必须从具体 Incident 或 Reconciliation Case 申请临时只读访问。

Error Center

Error Center 按 Fingerprint 聚合并展示：

• 首次与最近发生时间、趋势和代表性脱敏 Trace；
• 影响的产品、Surface、Pool、Deployment、模型、Provider 和配置版本；
• 影响的用户、Organization、Run、Asset 和金额摘要；
• 提交确定性、可重试性和待补偿类型；
• 与最近发布、路由或 Secret 变更的时间相关性；
• 是否已有 Alert、Incident、Runbook 或已知问题；
• 当前 Owner 和下一步动作。

页面只能表达“相关”，不能因为错误恰好出现在发布之后，就自动宣称该发布是根因。

Gateway 与执行运行中心

Text Pool 与 Media Pool 使用同一导航层级，但保留不同运行语义：

Text Gateway 如果尚不能提供可信 Provider Attempt，只显示 Gateway Invocation 和“Provider 未观测”，不能由中央控制面读取 new-api 数据库后猜测。Media Gateway 通过自己的 Task/Attempt Registry 输出规范化 Observation；中央读模型只保存必要摘要和不透明引用。

Alert 与 Incident 中心

Alert 生命周期建议保持简单：

open → acknowledged → mitigating / silenced → resolved

Silence 必须绑定 Owner、原因、范围和有效期；Maintenance Window 与异常静默分开。通知失败本身可观测，告警正文不得包含 Prompt、用户邮箱、Secret 或签名 URL。

Incident 至少记录：

incidentId / severity / status
commander / participants / owners
detectedAt / startedAt / mitigatedAt / resolvedAt
affectedProducts / surfaces / pools / deployments / offerings
affectedOrganizations / runs / assets / billing exposure summary
linkedAlerts / errorGroups / traces / changes / cases
timeline / decisions / mitigations / validation
customerCommunicationStatus
rootCause / followUps / postmortemStatus

Incident Timeline 追加写入；后续修正通过新事件补充，不覆盖旧判断。一次标准处置流程是：

Signal
→ Triage
→ Incident
→ Impact Analysis
→ Minimal Mitigation
→ Metrics Recovery Validation
→ Run / Asset / Billing Scan
→ Reconciliation
→ Customer Communication
→ Postmortem / Follow-up

Reconciliation 工作台

Reconciliation Case 用于执行、资产、Usage 与账务事实不一致的案件，而不是普通失败任务列表。典型案件包括：

• 无法确认 Provider 是否创建任务；
• Provider 成功但 OceanWay 没有取得结果；
• 结果已落盘但 AssetVersion 或 Run 未完成；
• Run 已完成但 Reservation 未结算或未释放；
• Usage 缺失、超出预占或与 Provider 账单不一致；
• Poll 与未来 Callback 报告冲突终态；
• 重复 Provider Attempt、重复资产或疑似重复结算；
• 用户已退款但 Provider 成本已经发生；
• 客户 Webhook 未送达，但业务与账务已经终态。

案件状态：

open
investigating
awaiting_provider
resolution_proposed
approval_required
resolved
rejected

允许的领域命令包括：

• 查询原 Gateway Task，不创建新 Provider 调用；
• 绑定经过证据确认的已有上游任务 ID；
• 重新取回、校验并持久化原结果；
• 重建可再生的读模型或索引；
• 释放原 Reservation；
• 按可信 Meter/Usage Fact 结算；
• 追加退款或平台承担成本分录；
• 重放客户 Webhook；
• 无动作关闭并记录理由。

禁止直接编辑 Gateway Task 状态、AssetVersion、Reservation 或 Ledger 行。账务修复只追加分录，未知提交不通过“重试看看”解决。

Admin Command Gateway

所有带写效果的运维动作通过 Admin Command Gateway：

adminCommandId
commandType / targetType / targetId
actorWorkforcePrincipalId
reason / incidentId? / reconciliationCaseId?
requestedScope / expectedRevision
impactPreview / impactPreviewDigest
idempotencyKey
approvalPolicy / approvalRecords[]
status / outcome / failureCode
createdAt / executedAt / completedAt

命令执行流程：

1. 重新验证 Workforce Session、职责权限与 JIT Grant；
2. 读取目标当前 Revision 和影响范围；
3. 生成不可变影响预览，危险动作等待审批；
4. 以幂等键调用唯一拥有数据的 Domain Command Service；
5. Domain Service 校验业务不变量并提交事实与 Outbox；
6. 记录 Audit Event 和命令结果；
7. 通过正常查询路径验证结果，不把前端成功提示当作完成证据。

控制面不得提供任意 SQL、任意 Provider 请求、任意文件删除或通用“强制成功”按钮。健康检查也不能偷偷发起付费模型调用；需要合成探测时，必须有独立预算、模型、环境和可识别的 Probe Principal。

敏感调试访问

普通运维默认不读取客户 Prompt、原始媒体和完整输出。确需内容诊断时创建 SensitiveDebugGrant：

grantId
requester / approver
incidentId 或 reconciliationCaseId
organizationId / workspaceId / resourceIds[]
allowedFields / purpose
issuedAt / expiresAt / revokedAt?

规则：最小只读范围、明确理由、限时、审批、不可转授、全 Audit。内容不能复制到普通日志、Alert、Incident Note、工单标题或聊天工具。Break-glass 使用独立流程，并在事后通知、复核和撤销。

后台信息架构

现有后台继续按商业 SaaS 职责分组，不把所有新能力平铺成一条长菜单：

不同岗位进入同一个后台，但首页、默认页面、字段和动作不同。On-call 首先看到运行与 Incident；财务首先看到金额暴露与对账；内容运营不会因为共享后台而加载供应 Secret 或技术 Trace。

数据存储与保留

PostgreSQL 适合保存：

• Operation 关系索引和摘要；
• Error Occurrence 与 Fingerprint；
• Alert Rule/Instance；
• Incident、Timeline 与 Follow-up；
• Reconciliation Case、Evidence Link 与 Resolution；
• Admin Command、Approval 与 Audit；
• Gateway 规范化 Observation 投影；
• Outbox 和摄取水位。

PostgreSQL 不应长期承载全量高频日志、全部 Span Payload、时序 Metrics、完整 Provider Callback、Prompt 或媒体内容。Logs、Metrics 和 Trace 通过 OpenTelemetry-compatible Collector 进入专门后端；PostgreSQL 只保存稳定对象和受控查询引用。

保留期按数据类型、环境、合同、监管和存储配置制定，不在架构中写死天数。Audit、账本和必要 Incident 证据遵循不可变留存；普通 Telemetry 可以按热查询、冷归档和删除策略处理。Legal Hold 会暂停对应证据删除，并记录范围、责任人和解除条件。

从现有 /admin 演进

A0：冻结边界

• 盘点现有 Section、API、权限、人工操作和数据源。
• 明确调用记录、运行事实、Audit 和 Ledger 的不同保留语义。
• 冻结 admin.oceanway.tech、内部管理员与企业客户管理员边界。
• 禁止新增通过直接改表完成的后台操作。

A1：建立独立 Surface

• 继续由现有 OceanWay 应用承载 Admin UI/BFF，按 Host 分流。
• canvas.oceanway.tech/admin 和 ai.oceanway.tech/admin 不提供内部后台。
• 引入 Workforce Client、Host-only Session、MFA 和独立 Audience。
• 当前 role=admin 只作为迁移映射，不作为长期授权模型。

A2：只读诊断控制台

• 冻结 ID、Error Envelope 和 Gateway Observation Contract。
• 将现有生成运维升级为 Run Explorer。
• 增加全局 ID 搜索、Error Fingerprint 和 Text/Media Pool 独立状态。
• 补齐 Audit UI，关联现有调用、资产和财务记录。
• 不开放新的危险写操作。

A3：Alert 与 Incident

• 建立 SLO、Alert Rule/Instance、值班 Owner 和 Maintenance Window。
• 建立 Incident、追加式 Timeline、影响分析和客户沟通状态。
• 接入发布、配置、路由和 Secret 变更记录。
• 通过 Admin Command Gateway 开放少量最小缓解动作。

A4：统一对账

• 自动发现未知提交、结果/资产不一致、Reservation 未终态和 Usage 差异。
• 建立 Reconciliation Case、Evidence、Proposal、Approval 和幂等 Resolution。
• 将现有人工补录、退款与结果恢复迁入领域命令。
• Incident 关闭前自动生成受影响对象扫描结果。

A5：规模化运维

• 建设完整 OpenTelemetry Pipeline 与独立 Logs/Metrics/Trace 后端。
• 完善 On-call、SLO/Error Budget、容量、成本和多区域视图。
• 为企业提供受限状态、审计导出和支持案件视图。
• 根据真实团队与故障域决定是否物理拆分 Admin BFF 和 Operational Read Model。

第一阶段验收门禁

• admin.oceanway.tech 不进入客户应用启动器，客户 Session 不能直接获得内部后台会话。
• 企业客户管理员和 OceanWay Workforce 权限模型完全分离。
• 一个 Public Request ID 可以定位到授权范围内的 Run、Gateway、Asset 和 Billing 摘要。
• requestId、traceId、correlationId、operationId 和领域 ID 不再混用。
• Text 与 Media Pool 独立展示健康、Deployment、任务和错误。
• 未观测的 Provider 事实明确显示未知，不按时间或模型猜测。
• Error 记录阶段、提交确定性、重试与补偿语义。
• unknown 提交不能自动重试或跨网关切换。
• Provider 成功、Asset 成功和 Billing 成功是可独立核验的事实。
• Logs/Trace/Metrics 不作为任务或账务事实源。
• 普通 Telemetry 不含 Prompt、Secret、签名 URL 和完整媒体。
• Metrics 不使用用户和请求高基数标签。
• 控制面不直连 Text/Media Gateway 数据库。
• 所有列表按权限、状态、时间窗和分页定向查询。
• 所有运维写操作通过 Domain Command，幂等、有理由、有 Audit。
• 账务修复只追加 Ledger，不覆盖历史。
• 内容调试访问限时、最小、只读并可审计。
• Telemetry 或后台故障不会阻断客户正常模型调用。

不可妥协的规则

1. 内部管理员平台和企业客户管理是两个身份与授权边界。
2. 当前 /admin 是迁移基座，不是目标权限与运维模型的最终形态。
3. 管理员首先通过稳定业务 ID 和事实链排障，而不是在多套日志中猜测。
4. correlationId/operationId 连接长期业务流程，traceId 描述一次调用链；异步边界使用 Span Link。
5. 错误必须表达发生层级、提交确定性、重试和补偿语义。
6. Text Pool 与 Media Pool 独立观测；中央控制面不侵入其私有数据库。
7. Logs、Metrics 和 Trace 是诊断证据，不是 Run、Asset、账本或审计事实源。
8. 普通运维无权读取客户内容和 Secret；调试访问必须 Case-scoped、限时并审计。
9. 运维动作只能通过幂等 Domain Command，不能直接改表、强制改状态或盲目重提。
10. Incident 恢复后必须检查受影响的任务、资产、账务和 Webhook，不能只关闭告警。

非目标

首期不做：

• 为了形式完整立即拆出独立 Admin、Ops、Alert、Incident 和 Trace 微服务；
• 在 PostgreSQL 中自建全量高频日志和时序数据库；
• 用一个“大盘正常”掩盖单个 Pool、Provider 或产品故障；
• 让后台直接调用 Provider、读取 Gateway 数据库或编辑 Ledger 行；
• 把完整 Prompt、媒体和 Provider 原始 Payload复制到 Incident；
• 在没有关联、权限、审计和幂等前开放“一键修复”；
• 允许日常使用永久全权限超级管理员。