本文档面向集群使用方，提供通过 Transwarp Manager（TOS） REST API 检测集群整体健康状态与服务健康状态的接口说明与调用示例，可作为运维监控、巡检脚本集成的参考。

示例环境：Manager 地址 http://172.18.131.171:8180（请替换为您的实际 Manager 地址）

一、前置说明

1.1 认证方式

所有业务接口均需先登录获取会话 Cookie（JSESSIONID），后续请求通过 -b cookies.txt 携带。会话过期（返回 401/403）时重新登录即可。

1.2 通用约定

• 所有接口基础路径：http://<Manager_IP>:8180
• 请求头：accept: */*；涉及请求体的接口需 Content-Type: application/json
• 返回格式：JSON（少数路径型接口返回纯文本）
• 时间戳字段均为毫秒级 Unix 时间戳

1.3 登录获取 Cookie

curl -X POST 'http://172.18.131.171:8180/api/users/login' \
  -H 'accept: */*' \
  -H 'Content-Type: application/json' \
  -d '{
    "userName": "lj_111",
    "userPassword": "123456",
    "captcha": "string",
    "twoStepCode": "string"
  }' \
  -c cookies.txt

请将 userName / userPassword 替换为您的实际账号。

返回示例：

{
  "userName": "lj_111",
  "roles": [{"roleName": "admin", "source": "ROLE", "sourceName": null}],
  "permissions": [{"type": "ADMIN", "resId": -1}],
  "isAdmin": true
}

登录成功后，cookies.txt 将用于后续所有示例。

二、集群整体健康状态检测

2.1 获取集群列表

用途： 获取 Manager 管理的集群及其 ID（后续接口需用到 clusterId）。

curl -s 'http://172.18.131.171:8180/api/clusters' -b cookies.txt

返回示例：

[
  {"id": 1, "name": "KV（测试完记得恢复）"}
]

2.2 集群状态（健康检查与告警）★

用途： 获取集群级的健康检查项与告警项，是判断集群整体健康最直接的接口。每一项包含标题、类型、状态、描述及告警等级。

curl -s 'http://172.18.131.171:8180/api/clusters/1/states' -b cookies.txt

返回示例：

[
  {
    "title": "节点网络延迟/丢包比例过高",
    "type": "AQUILA_ALERT",
    "status": "WARNING",
    "description": "节点kv1访问其他节点的网络延迟检测包超时比例超过33.33%",
    "href": "https://kv1:8666/#/home/alertList?id=6c49526223fa72a1",
    "aquilaLevel": "L3",
    "aquilaUrgency": "一般",
    "aquilaPriority": "定期观察",
    "aquilaPri": 3
  }
]

字段说明：

判定逻辑：返回数组为空或所有项 status=HEALTHY，则集群整体健康；存在 WARNING/DOWN 项则需关注。

2.3 集群统计信息

用途： 获取集群服务总数与节点总数，用于概览规模。

curl -s 'http://172.18.131.171:8180/api/clusters/1/statistics' -b cookies.txt

返回示例：

{"servicesNum": 29, "nodesNum": 4}

2.4 集群告警汇总 ★

用途： 获取集群当前告警的汇总计数与最近告警列表，配合 2.2 用于集群健康评估。

curl -s 'http://172.18.131.171:8180/api/alerts/aquila/summary' -b cookies.txt

返回示例：

{
  "criticalCount": 3,
  "warningCount": 0,
  "unknownCount": 0,
  "recent": [
    {
      "severity": "CRITICAL",
      "timestamp": 1784193939959,
      "title": "POD starwarp/starwarp-console-server-... 在过去5分钟内重启了1次。",
      "contextStr": ""
    },
    {
      "severity": "CRITICAL",
      "timestamp": 1783983859680,
      "title": "节点kv1访问其他节点的网络延迟检测包超时比例超过33.33%",
      "contextStr": "KV（测试完记得恢复）/kv1"
    }
  ]
}

字段说明：

相关接口：

# 告警总数
curl -s 'http://172.18.131.171:8180/api/alerts/aquila/count' -b cookies.txt
# 返回：{"count": 10000}

# 告警明细列表
curl -s 'http://172.18.131.171:8180/api/alerts/aquila' -b cookies.txt

2.5 节点在线状态

用途： 获取所有节点的在线状态与基础资源信息，节点离线会影响集群健康。

curl -s 'http://172.18.131.171:8180/api/nodes' -b cookies.txt

返回示例（单节点）：

{
  "id": 4,
  "hostName": "kv1",
  "ipAddress": "172.18.131.171",
  "clusterName": "KV（测试完记得恢复）",
  "rackName": "/default-rack",
  "osName": "CentOS Linux",
  "arch": "x86_64",
  "logicalCoreCount": 16,
  "status": "ONLINE",
  "memTotal": 67386531840,
  "diskCount": 7
}

字段说明：

节点级健康检查项可通过 GET /api/nodes/{nodeId}/states 获取，结构与 2.2 一致。

三、服务健康状态检测

3.1 服务列表（全局健康一览）★

用途： 获取集群全部服务及其健康状态，用于一次性掌握所有服务的健康概况。

curl -s 'http://172.18.131.171:8180/api/services' -b cookies.txt

返回示例（单服务）：

{
  "id": 20,
  "name": "HDFS1",
  "type": "HDFS",
  "version": "transwarp-9.3.3-final",
  "health": "HEALTHY",
  "installed": true,
  "monitored": true,
  "hasStaleConfig": true,
  "toRestart": false,
  "enableKerberos": true
}

关键字段说明：

判定逻辑：遍历返回数组，统计各 health 取值分布即可得到服务健康概览。

快速汇总示例（按健康状态分组）：

curl -s 'http://172.18.131.171:8180/api/services' -b cookies.txt \
  | python -c "import sys,json; \
[print(f\"{s['health']:10s} {s['type']:18s} {s['name']}\") for s in json.load(sys.stdin)]"

3.2 服务详情与健康检查项 ★

用途： 获取单个服务的详情，其中 states 字段为该服务的健康检查项明细（运行检查、就绪检查等）。

curl -s 'http://172.18.131.171:8180/api/services/20' -b cookies.txt

返回示例：

{
  "states": [
    {
      "title": "运行检查",
      "type": "DAEMON_CHECK",
      "status": "HEALTHY",
      "description": "9个角色健康，0个角色不可用，0个角色不健康"
    },
    {
      "title": "就绪检查",
      "type": "VITAL_SIGN_CHECK",
      "status": "HEALTHY",
      "description": "8个角色健康，0个角色不可用，0个角色不健康，0个角色在退役中，0个角色已退役"
    }
  ],
  "id": 20,
  "type": "HDFS",
  "name": "HDFS1",
  "version": "transwarp-9.3.3-final",
  "health": "HEALTHY"
}

字段说明：

states 数组为空或全部 HEALTHY 即代表服务健康；description 中"不可用""不健康"角色计数 > 0 时需进一步用 3.3 定位。

3.3 服务角色健康明细 ★

用途： 当服务存在不健康角色时，定位到具体角色、所在节点、检查结果与详情，是服务健康排障的核心接口。

curl -s 'http://172.18.131.171:8180/api/services/20/rolesHealths' -b cookies.txt

返回示例（单条）：

{
  "roleId": 141,
  "node": "kv2",
  "roleType": "HDFS_DATANODE",
  "roleName": "Data Node",
  "category": "DAEMON_CHECK",
  "categoryTitle": "运行检查",
  "result": "HEALTHY",
  "detail": "kv2节点default命名空间中角色Data Node（hadoop-hdfs-datanode-hdfs1）正在运行：hadoop-hdfs-datanode-hdfs1-56b4cc566c-hsdj4（Running）",
  "checkTime": 1784194139647
}

字段说明：

3.4 服务角色类型与分布（辅助）

用途： 了解服务的角色构成与在各节点的分布，辅助健康评估。

# 服务角色类型
curl -s 'http://172.18.131.171:8180/api/services/20/roleTypes' -b cookies.txt
# 返回：[{"typeName":"HDFS_NAMENODE","friendlyName":"Name Node"}, ...]

# 角色在各节点的分布
curl -s 'http://172.18.131.171:8180/api/services/20/roleDistribution' -b cookies.txt

roleDistribution 返回示例：

{
  "kv1": ["Name Node"],
  "kv2": ["Data Node", "Journal Node", "Name Node"],
  "kv3": ["Data Node", "Journal Node"],
  "kv4": ["Data Node", "Httpfs", "Journal Node"]
}

3.5 单角色健康明细

用途： 按 roleId 查询单个角色的健康检查明细（roleId 可从 3.3 或 GET /api/serviceRoles?serviceId={id} 获取）。

curl -s 'http://172.18.131.171:8180/api/serviceRoles/141/healths' -b cookies.txt

返回结构与 3.3 一致。

四、健康状态取值速查

4.1 服务 / 集群健康状态（health / status）

4.2 角色健康结果（result）

4.3 告警级别（severity / aquilaLevel）