Admin API

Nantian Gateway 控制面暴露一个 HTTP REST Admin API，用于运行时诊断、配置检查和运维查询。所有端点均通过控制面的 HTTP 监听器（默认端口 18081）提供。

认证模型

认证级别	行为
`none`	无需认证。供健康探针和 Kubernetes 存活/就绪检查使用。
`bearer-when-configured`	如果在控制面配置中设置了 Admin API Token，请求必须包含 `Authorization: Bearer <token>` 头。如果未配置 Token，该端点即为开放状态。

端点参考

健康探针

Method	Path	Auth	描述
`GET`	`/livez`	`none`	存活检查。进程存活时返回 `200 OK`。
`GET`	`/readyz`	`none`	就绪检查。控制面完成初始资源同步后返回 `200 OK`，否则返回 `503`。

诊断端点

Method	Path	Auth	描述
`GET`	`/v1/summary`	`bearer-when-configured`	集群配置概览：Listener、Route、Backend 和 Node 数量统计
`GET`	`/v1/dashboard/capabilities`	`bearer-when-configured`	向 Dashboard UI 暴露的功能特性开关
`GET`	`/v1/snapshot-sync`	`bearer-when-configured`	所有数据面节点的快照同步状态
`GET`	`/v1/snapshot`	`bearer-when-configured`	当前推送至各数据面的完整 IR 快照内容
`GET`	`/v1/listeners`	`bearer-when-configured`	列举所有 Listener
`GET`	`/v1/listeners/{name}`	`bearer-when-configured`	查看指定 Listener 详情
`GET`	`/v1/routes`	`bearer-when-configured`	列举所有 Route（HTTP、gRPC、TCP、UDP、TLS）
`GET`	`/v1/routes/{kind}/{namespace}/{name}`	`bearer-when-configured`	查看指定 Route 详情
`GET`	`/v1/backends`	`bearer-when-configured`	列举所有 Backend 集群
`GET`	`/v1/backends/{namespace}/{name}`	`bearer-when-configured`	查看指定 Backend 集群详情
`GET`	`/v1/nodes`	`bearer-when-configured`	列举所有已连接的数据面节点
`GET`	`/v1/nodes/{nodeId}`	`bearer-when-configured`	查看指定数据面节点详情
`GET`	`/v1/infrastructure`	`bearer-when-configured`	基础设施状态（Deployment、Service、Pod 信息）
`GET`	`/v1/service-catalog`	`bearer-when-configured`	服务目录列表
`GET`	`/v1/namespaces`	`bearer-when-configured`	列举已知命名空间
`GET`	`/v1/resource-kinds`	`bearer-when-configured`	列举可用的资源类型
`GET`	`/v1/topology`	`bearer-when-configured`	Gateway、Route 和 Backend 的拓扑视图
`GET`	`/v1/dataplanes`	`bearer-when-configured`	列举数据面实例
`GET`	`/v1/dataplanes/{nodeId}/summary`	`bearer-when-configured`	查看指定数据面实例的摘要信息

资源 CRUD

Method	Path	Auth	描述
`GET`	`/v1/resources`	`bearer-when-configured`	列举所有受管理资源
`POST`	`/v1/resources`	`bearer-when-configured`	创建或更新受管理资源
`GET`	`/v1/resources/{kind}/{namespace}/{name}`	`bearer-when-configured`	按 kind、namespace 和 name 获取指定资源
`PUT`	`/v1/resources/{kind}/{namespace}/{name}`	`bearer-when-configured`	更新指定资源
`DELETE`	`/v1/resources/{kind}/{namespace}/{name}`	`bearer-when-configured`	删除指定资源

Chatbot

Method	Path	Auth	描述
`GET`	`/v1/chatbot/config`	`bearer-when-configured`	获取 Chatbot 配置
`PUT`	`/v1/chatbot/config`	`bearer-when-configured`	更新 Chatbot 配置
`POST`	`/v1/chatbot/chat`	`bearer-when-configured`	发送聊天消息。响应格式为 `text/event-stream`（SSE）。

指标代理

Method	Path	Auth	描述
`GET`	`/v1/metrics/config`	`bearer-when-configured`	获取指标后端配置
`PUT`	`/v1/metrics/config`	`bearer-when-configured`	更新指标后端配置
`POST`	`/v1/metrics/query`	`bearer-when-configured`	执行即时 PromQL 查询
`POST`	`/v1/metrics/query_range`	`bearer-when-configured`	执行范围 PromQL 查询

AI 网关

Method	Path	Auth	描述
`GET`	`/v1/ai/overview`	`bearer-when-configured`	AI 网关概览（模型、提供商、请求量）
`GET`	`/v1/ai/services`	`bearer-when-configured`	列举已配置的 AI 后端服务
`GET`	`/v1/ai/token-usage`	`bearer-when-configured`	Token 用量统计
`GET`	`/v1/ai/traces`	`bearer-when-configured`	AI 请求追踪
`GET`	`/v1/ai/cost`	`bearer-when-configured`	各 AI 提供商成本分析

使用示例

健康检查

# 存活检查
curl -s -o /dev/null -w "%{http_code}" http://controlplane:18081/livez
# → 200

# 就绪检查（初始同步完成前可能返回 503）
curl -s http://controlplane:18081/readyz
# → 200 OK（或 503，如果尚未就绪）

配置查看

# 集群概览
curl http://controlplane:18081/v1/summary

# 所有网关的所有 Route
curl http://controlplane:18081/v1/routes

# 指定 HTTPRoute 详情
curl http://controlplane:18081/v1/routes/httproute/default/my-app-route

# Backend 集群详情
curl http://controlplane:18081/v1/backends/default/backend-svc

# 数据面节点状态
curl http://controlplane:18081/v1/nodes

快照同步检查

# 查看哪些节点已同步、哪些存在差异
curl http://controlplane:18081/v1/snapshot-sync

资源管理

# 列举所有受管理资源
curl http://controlplane:18081/v1/resources

# 获取指定资源
curl http://controlplane:18081/v1/resources/httproute/default/my-app-route

# 创建或更新资源
curl -X POST http://controlplane:18081/v1/resources \
  -H "Content-Type: application/json" \
  -d '{"apiVersion":"gateway.networking.k8s.io/v1","kind":"HTTPRoute",...}'

# 删除资源
curl -X DELETE http://controlplane:18081/v1/resources/httproute/default/my-app-route

指标查询

# 即时查询
curl -X POST http://controlplane:18081/v1/metrics/query \
  -H "Content-Type: application/json" \
  -d '{"query":"up"}'

# 过去一小时的范围查询
curl -X POST http://controlplane:18081/v1/metrics/query_range \
  -H "Content-Type: application/json" \
  -d '{"query":"rate(http_requests_total[5m])","start":"2025-01-01T00:00:00Z","end":"2025-01-01T01:00:00Z","step":"30s"}'

AI 网关

# 概览
curl http://controlplane:18081/v1/ai/overview

# Token 用量
curl http://controlplane:18081/v1/ai/token-usage

带认证的请求

当配置了 Admin Token 时，需在 Authorization 头中附带 Token：

curl -H "Authorization: Bearer ${ADMIN_TOKEN}" http://controlplane:18081/v1/summary

下一步

Gateway API 资源 — 驱动网关配置的 Kubernetes 资源
xDS 协议 — 控制面与数据面之间的通信协议
故障排查 — 常见诊断工作流