跳到主要内容

Management API

Aidy Gateway 提供了一个独立的 Management API（与网关 API 不同），用于监控和调试网关的运行状态。Management API 默认运行在 :12581 端口（可通过 --management-listen 参数修改）。

危险

🚧 Management API 尚未稳定，接口可能会频繁变更

健康检查端点​

/health​

基本健康检查端点，返回网关的运行状态 —— 当网关运行时始终返回 200。

curl http://localhost:12581/health

响应示例：

{
  "status": "ok"
}

/ready​

就绪检查端点，用于 Kubernetes 等容器编排系统的就绪探针。与 /health 不同，仅当网关存在有效配置时才会返回 ok。

curl http://localhost:12581/ready

响应示例：

{
  "status": "ready"
}

当网关无有效配置时，返回 503.

{
  "error": "no valid config"
}

Prometheus Metrics​

/metrics​

Prometheus 格式的 metrics 端点，提供了丰富的监控指标。

curl http://localhost:12581/metrics

主要指标包括：（TODO）

pprof 调试端点​

工作在 /debug/pprof/ 下，提供标准的 Go pprof 调试功能：

  • /debug/pprof/ - pprof 主页
  • /debug/pprof/cmdline - 命令行参数
  • /debug/pprof/profile - CPU profile
  • /debug/pprof/symbol - 符号表
  • /debug/pprof/trace - 执行追踪
  • /debug/pprof/goroutine - goroutine 信息
  • /debug/pprof/heap - 堆内存信息
  • /debug/pprof/threadcreate - 线程创建信息
  • /debug/pprof/block - 阻塞信息
  • /debug/pprof/mutex - 互斥锁信息
  • /debug/pprof/allocs - 内存分配信息

动态配置端点​

备注

当网关无有效配置时，以下端点都会返回 503

/config/dynamic 查看当前动态配置​

展示当前加载的配置，以 JSON 格式返回，对应配置文件的原始内容。

curl http://localhost:12581/config/dynamic?pretty

响应包含原始的 protobuf 配置内容，以 JSON 格式输出。

/config/dynamic/full 查看 Aidy 解析后的动态配置​

展示当前加载的配置由 Aidy 解析后的内容。

curl http://localhost:12581/config/dynamic/full?pretty

/config/dynamic/last 查看最近一次尝试加载的配置​

返回最近一次尝试加载的配置（可能是正确或错误的配置），包括：

  • timestamp：尝试时间
  • status：success | failed
  • error：错误原因（当 status 为 success 时为空）
  • content_type：配置内容类型
  • content_encoding：文本编码（utf-8 或 base64）
  • content_text：配置内容（当为二进制 protobuf 时以 base64 返回）
curl http://localhost:12581/config/dynamic/last?pretty

当尚未有任何加载尝试时，返回 503（no configs loaded yet）。

POST /config/validate 验证配置是否合法​

验证提供的配置是否符合 Aidy 的配置规范。这个端点可以在部署新配置之前用于验证配置的正确性。

curl -X POST http://localhost:12581/config/validate \
  -H "Content-Type: application/json" \
  -d '{
    "config": {
      "routes": [...],
      "global_plugin_config": {...}
    }
  }'

成功响应示例：

{
  "valid": true
}

失败响应示例：

{
  "valid": false,
  "errors": [
    "global_plugin_config: value is required [required]",
    "route IDs must be unique [config.routes.unique_ids]",
  ]
}

注：Aidy 的配置现已完全利用 protovalidate 进行验证，调用方除了调用该端点外也可选择自行验证配置的合法性。