新网关(源码指南)

新网关概览

OneAster 新网关部署提交 f09a2d5 与 Go 构建版本 7ba12de+oneaster.0.1.0 的契约与接口指南。

新网关线上基线与适用范围

本指南依据已部署的 oneaster-gateway 提交 f09a2d5da1c9b6fbfd95ae4246080a8489d44564 编写。2026-11-17 只读核验服务器 current、服务工作目录与源码摘要,部署提交 f09a2d5;GET https://api.oneaster.ai/api/status 实测返回构建版本 7ba12de+oneaster.0.1.0(quota_per_unit 为 1000000,生产 Base URL 为 https://api.oneaster.ai,推理 Base URL 为 https://api.oneaster.ai/v1)。模型可用性、分组倍率及售价由管理员配置,以当前账号与实际环境为准。本站当前接口参考、公开 OpenAPI 和“试一试”均对齐该已部署版本。下载 OpenAPI。

四组接口平面与鉴权边界

第一组是 /v1 标准推理平面,仅接收个人推理 API Key(Authorization: Bearer sk-...,POST /v1/messages 也支持 x-api-key),提供 OpenAI / Anthropic 原生 JSON、SSE、二进制音视频与异步任务接口。/v1 绝不接收登录 access_token 或个人访问令牌(PAT,nap_...),也不启用 /pg 的持久化意图存储;不要把 Idempotency-Key 当成 /v1/chat/completions 的必填头,也不能假定所有 /v1 协议具有通用幂等重放语义。

第二组是 /pg 登录钱包 Playground 平面,仅接收原生登录取得的 access_token(Authorization: Bearer $ONEASTER_ACCESS_TOKEN),直接扣减当前登录账户钱包,强制校验本人归属(user_id 隔离,非本人资源一律返回 404)与受信任浏览器 Origin(禁止跨站凭据 Cookie)。/pg 拒绝推理 API Key(sk-...)与 PAT(nap_...),也不会在后台暗中创建或暴露 API Key。

第三组是 /oneaster/v1 TypeScript 业务与治理服务,成功返回 {data:...},失败返回 {error:{code,message}}。业务接口使用原生登录 access_token(部分接口支持具备对应 scope 的 PAT;其中 /oneaster/v1/task-diagnostics* 仅接受实时登录 access_token,拒绝 PAT 与推理 Key;管理员接口需同时满足实时管理员角色权限)。

第四组是原生 /api 接口,负责登录、注册、MFA、账户安全及底层管理操作,通常返回 {success,message,data},业务失败可能仍返回 HTTP 200。PR #49 增加了 Google 原生 OAuth 登录支持(启动接口 POST /api/oauth/state 与回调接收 POST /api/oauth/google)。Google 登录由前端同源 BFF 为每次流程生成 32 字节随机值的无填充 base64url browser_binding(43 字符;示例占位符须替换,不得复用固定值) 并调用后端获取 authorization_url,使用加密 HttpOnly 流程 Cookie(推荐 __Host-oneaster-google-flow,SameSite=Lax)保存绑定与 state;用户回调到前端 GET /oauth/google 后,BFF 必须先核对流程 Cookie、有效期与 state,再转发 POST /api/oauth/google 完成登录。后端 GET /api/oauth/google 返回 405;授权码不得放进后端 URL 或持久化日志。前端 GET 回调临时接收 code/state,完成验证后应立即重定向到无授权码的本站地址。开启 MFA 的账号返回 require_verification: true,需继续调用 POST /api/user/login/verify 完成二次验证。注意:只读 GET /api/status 中 custom_oauth_providers 当前未列出 Google,代码实现已部署不代表正式登录按钮已上线或真实 Google 联调已通过。

登录钱包 Playground(/pg)持久化意图与恢复(PR #39)

所有 /pg 写接口(POST /pg/chat/completions、/pg/responses、/pg/messages、/pg/images/generations、/pg/images/edits、/pg/videos、/pg/audio/speech、/pg/audio/transcriptions、/pg/audio/translations、/pg/tasks/kie)均支持请求头 Idempotency-Key(1 至 100 位无空格可见 ASCII 字符,推荐客户端在点击发送时生成 UUID v4 并先写入 sessionStorage)。同一 user_id 下所有 /pg 写路由共享幂等命名空间;若对不同方法、路径、查询参数或请求体复用同一 Idempotency-Key,网关返回 409 idempotency_conflict 且不触发推理或扣费。省略 Idempotency-Key 时网关仍向后兼容并生成 X-OneAster-Intent-ID,但若断线前未收到响应头则无法按意图恢复。

/pg 响应头返回 X-OneAster-Intent-ID、X-OneAster-Request-ID、Location: /pg/requests/{request_id}、Cache-Control: private, no-store;命中已完成重放时附加 X-OneAster-Reused: true,命中执行中请求时返回 409 request_in_progress 与 Retry-After: 3。

页面刷新、断线或超时后,客户端应调用 GET /pg/requests/by-intent?intent_id={UUID} 或 GET /pg/requests/{request_id} 恢复,绝不能自动重发 POST。响应体最多保存 4 MiB(4194304 字节)、保留 24 小时,截止时间为 result_expires_at。恢复响应中的 response.body 是字符串:按 response.content_type 解析 JSON 或 SSE,并检查 response.complete;JSON/SSE 不返回 encoding 字段,仅二进制 /pg/audio/speech 返回 response.encoding="base64"。响应过大、未保存或已过期时,GET 仍返回 HTTP 200,result_available=false、response=null,并保留去重与账务状态;不得因此重新生成。再次 POST 同一意图的重放规则不同:已过期返回 409 result_expired,已完成 SSE 返回 409 stream_replay_unavailable,其他无法重放的响应返回 409 result_unavailable。

执行中请求每 10 秒更新心跳;若 running 状态超过 45 秒无心跳,GET 恢复视图返回 status=unknown、retry_allowed=false,不返回 execution_state_unknown 错误字段。billing_state 根据账务证据独立判断,取值 unknown、reserved、settled 或 released;charge_quota 与 reserved_quota 在未确认时为 null,绝不补零。网关未就绪时返回 503 intent_storage_unavailable。

curl --request GET "https://api.oneaster.ai/pg/requests/by-intent?intent_id=00000000-0000-4000-8000-000000000001" \
  --header "Authorization: Bearer $ONEASTER_ACCESS_TOKEN"

文档站“试一试”边界

本站接口参考页中的“试一试”仅面向白名单内的 /v1 个人推理 Key 接口,不接收登录 access_token,不调用 /pg 或 /oneaster/v1,不开放账户、支付或管理写操作,也不在超时或失败后自动重发收费生成请求。Suno POST /v1/tasks/kie 不在试一试执行白名单内。