Table of Contents

管理 REST 与 OpenAPI

管理 REST 是 CLI/UI 的同源契约面(206 路由×29 族)——程序集成的首选通道。

OpenAPI 文档

节点运行后自描述:

curl http://127.0.0.1:7901/meta/openapi.json        # OpenAPI 3.1 全量文档
curl http://127.0.0.1:7901/meta/routes              # UI 投影(summary/tags 同源)
  • 契约源 management-api.json 单源派生三层产出(openapi/routes/运行时端点)—— 手写翻译表不存在,漏一行即启动拒绝(fail-fast 防漂移);
  • OpenAPI 3.1 产物自解析自检(构建期机器门:paths≡catalog≡schema≡样例过解析);
  • 第三方客户端直接以标准 OpenAPI 工具链生成——不需要内部 UI 的私有客户端。

请求形态

项 约定
认证 Authorization: Bearer <key>(403 结构化信封——见权限模型)
租户段 路径内嵌:/api/v1/{tenant}/config/list/route?phase=published
写语义 POST=写 draft(无热改旁路);幂等读显式 GET
回执 版本戳 {logicalAddress, generation};清单读=JSON 数组
错误 {code, message, traceId, issues[]}——issues 带 {entityType,key,field,message}

示例(与 CLI 等价):

curl -X POST -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "targets": ["10.0.1.10:8080"] }' \
  http://127.0.0.1:7901/api/v1/default/config/set/cluster/orders
{"logicalAddress":"0000000000000000d800000000000000","generation":0}

curl -H "Authorization: Bearer $KEY" \
  "http://127.0.0.1:7901/api/v1/default/publish/status"

与 CLI 的一致性保证

CLI 命令树 → REST 路径的翻译表在构建期生成并机器对账:有命令必有路由、 有路由必有命令(api-inventory 机器门 68 行起持续扩张口径)。混用两个入口不会 产生行为分叉——同一命令经 CLI 与经 REST 的服务端语义逐字节一致。

SSE 实时面

/api/v1/…/audit/stream、发布进度、events、KV watch 走 SSE(带 Header 鉴权)—— 浏览器 EventSource 与服务端订阅同面。事件语义见可观测。