CubePath 于2026年10月23日通过官方邮件介绍旗下 GraphQL API 监控功能,支持用户通过统一接口查询 VPS、独立服务器、负载均衡器、Kubernetes 集群及其他云计算资源的运行指标。该功能已于2026年9月17日正式开放,此次邮件重点介绍如何使用 GraphQL API 构建自定义服务器监控面板和资源统计报表。
通过 GraphQL API,用户可以在一次请求中获取多台服务器的监控信息,包括 CPU使用率、内存占用、磁盘I/O、网络流量及月带宽使用量,不再需要为每项指标分别请求不同的监控接口。
值得注意的是,CubePath 原有的 REST 监控指标接口已于2026年9月23日退役,GraphQL API 成为新的监控数据查询接口。
CubePath 是一家提供 VPS、独立服务器、云计算及网络基础设施服务的海外主机商,支持通过管理控制台、REST API和GraphQL API管理或查询不同类型的云资源。

官方网站:
GraphQL API官方文档:
https://cubepath.com/docs/products/settings/graphql-api
官方更新说明:
https://cubepath.com/changelog/graphql-api
一、CubePath GraphQL API支持哪些功能?
CubePath GraphQL API 是一个只读监控接口,主要用于获取服务器运行指标、资源健康状况及带宽统计。
| 资源类型 | 支持查询的数据 |
|---|---|
| VPS云服务器 | CPU、内存、磁盘I/O、网络流量、月带宽用量 |
| VPS可用性组 | 平均CPU使用率、总内存、服务器数量 |
| 独立服务器 | 网络流量、数据包速率、带宽统计、BMC传感器 |
| IP Transit | 网络端口流量、数据包速率 |
| 负载均衡器 | 活跃连接数、新建连接速率、流量及带宽 |
| NAT网关 | 入站与出站流量、月带宽用量 |
| Kubernetes | 集群健康状况、节点资源、Pod状态、API延迟 |
| 带宽资源统计 | 按位置、项目、产品或服务统计带宽 |
GraphQL 的主要优势是允许用户自行选择需要返回的字段,并在一个请求中获取多个资源的相关数据。
需要说明的是,GraphQL API 主要用于读取指标。创建、修改、删除 VPS 等资源管理操作,仍需通过 CubePath REST API 或其他受支持的管理接口完成。
二、如何创建CubePath API Token?
首先访问 CubePath 用户控制台:
登录后进入:
Organization → Tokens → Create Token
创建新的 API Token,并根据监控用途选择权限。
建议关闭 Full access,只开启必要的只读权限。
常见权限如下:
| 监控对象 | API Token权限 |
|---|---|
| VPS | vps |
| 独立服务器 | baremetal |
| IP Transit | network |
| 负载均衡器 | loadbalancer |
| NAT网关 | nat_gateway |
| Kubernetes | kubernetes |
例如,如果只需要监控 VPS CPU、内存和流量,选择 vps 即可。
创建令牌时,还可以设置 Allowed IPs,将 Token 的访问来源限定为监控服务器的公网IP。
注意:API Token 创建后仅显示一次,建议立即妥善保存,不要公开在网页、GitHub仓库或服务器日志中。
三、GraphQL API接口地址与认证方式
CubePath GraphQL API 接口地址:
https://api.cubepath.com/graphql
请求方式:POST
Content-Type:application/json
官方支持两种认证方式:
方式一:Authorization Bearer
Authorization: Bearer YOUR_API_TOKEN
方式二:X-API-Key
X-API-Key: YOUR_API_TOKEN
其中 YOUR_API_TOKEN 需要替换为自己的访问令牌。
GraphQL API 虽然通过 POST 请求提交查询,但官方明确说明,使用 API Token 调用这个只读接口时,不需要额外添加 X-Requested-With 请求头。
四、使用curl查询VPS列表
Linux用户可以直接在服务器终端使用 curl 调用 GraphQL API。
首先创建环境变量,用于保存 API Token:
export CUBEPATH_API_TOKEN='YOUR_API_TOKEN'
随后执行:
curl -X POST /
https://api.cubepath.com/graphql /
-H "Content-Type: application/json" /
-H "Authorization: Bearer $CUBEPATH_API_TOKEN" /
-d '{"query":"{ vpsList { id name } }"}'
该查询会返回当前账户有权限访问的 VPS 列表。
其中:
- id:VPS服务器唯一ID。
- name:服务器名称。
- vpsList:查询VPS列表的GraphQL字段。
记录对应的 VPS ID,后续即可通过该 ID 查询服务器监控数据。
官方规定,vpsList 单次最多返回200台服务器。如果账户中存在大量服务器,需要根据实际支持的查询条件规划数据获取方式。
五、查询VPS CPU、内存和月流量
获得 VPS ID 后,可以进一步查询服务器最近6小时的CPU和内存监控记录。
GraphQL查询示例如下:
query Overview($id: ID!) {
vps(id: $id) {
name
metrics(
range: H6
metrics: [CPU_USAGE, MEMORY_USAGE]
) {
step
series {
name
unit
points {
ts
value
}
}
}
bandwidthUsage {
inBytes
outBytes
totalBytes
}
}
}
上述查询主要包括:
- CPU_USAGE:CPU使用率。
- MEMORY_USAGE:内存使用率。
- H6:最近6小时的监控数据。
- step:采样间隔,单位为秒。
- ts:Unix时间戳,采用UTC时间。
- value:对应时间点的监控数值。
- inBytes:进入服务器的流量字节数。
- outBytes:离开服务器的流量字节数。
- totalBytes:总流量字节数。
直接使用curl执行
下面提供包含服务器ID变量的完整请求示例。
curl -X POST /
https://api.cubepath.com/graphql /
-H "Content-Type: application/json" /
-H "Authorization: Bearer $CUBEPATH_API_TOKEN" /
-d '{
"query": "query($id: ID!) { vps(id: $id) { name metrics(range: H6, metrics: [CPU_USAGE, MEMORY_USAGE]) { step series { name unit points { ts value } } } bandwidthUsage { inBytes outBytes totalBytes } } }",
"variables": {
"id": "1234"
}
}'
其中1234只是示例ID,实际使用时需要替换为自己账户中的 VPS ID。
成功执行后,接口会返回 JSON 数据。
例如,官方文档中的 CPU 监控数据示例包含:
{
"name": "cpu_usage",
"unit": "RATIO",
"points": [
{
"ts": 1759406400,
"value": 0.42
}
]
}
这里的0.42代表42%的CPU使用率。
需要注意,不同监控指标的数据单位可能不同。只有 unit 为 RATIO 的比例数据才应按比例转换为百分比;字节、速率、温度等指标应按照其各自的单位处理。
CubePath 也支持磁盘I/O及网络使用情况查询。开发者可以通过已认证的 GraphQL Schema Introspection 查询接口的可用类型、字段和指标枚举,避免直接猜测参数名称。
六、GraphQL API支持哪些时间范围?
CubePath GraphQL API 提供8种常用的监控时间窗口。
| 参数 | 监控范围 |
|---|---|
| H1 | 最近1小时 |
| H3 | 最近3小时 |
| H6 | 最近6小时 |
| H12 | 最近12小时 |
| H24 | 最近24小时 |
| D3 | 最近3天 |
| D7 | 最近7天 |
| D30 | 最近30天 |
未设置 range 参数时,默认查询最近1小时的数据。
不同时间范围对应不同的采样粒度。例如,查询最近1小时可能返回较高密度的监控数据,而查询最近30天则会使用更大的时间聚合间隔。
官方介绍,30天监控图表通常只返回约300个数据点,从而减少响应体积。
因此,排查短时间内的CPU异常或网络流量波动时,建议选择H1、H3等较短时间范围;制作长期运行趋势报表时,可以选择D7或D30。
七、如何查询指定月份的服务器流量?
CubePath GraphQL API 支持使用 bandwidthUsage 查询指定月份的流量消耗情况。
例如:
query MonthlyUsage($id: ID!) {
vps(id: $id) {
name
bandwidthUsage(month: "2026-09") {
inBytes
outBytes
totalBytes
}
}
}
这里的2026-09代表查询2026年9月的月度流量。
如果不提供 month 参数,接口默认查询当前月份截至查询时的流量。
月份必须采用 YYYY-MM 格式,并按UTC自然月统计。
对于需要管理多台VPS的用户,可以定期获取月流量数据,结合套餐配额建立带宽用量报表。不过,具体流量配额及超额计费规则仍需以对应产品说明为准。
八、GraphQL API的请求限制
CubePath 官方公布了接口频率、查询规模和复杂度限制。
| 限制类型 | 官方限制 |
|---|---|
| 单Token请求频率 | 每分钟600次 |
| 单次数据点数量 | 约24,000个 |
| 最大查询深度 | 6层 |
| 最大别名数量 | 15个 |
| 最大查询Token数 | 2,000 |
| VPS列表单次返回 | 最多200台 |
| 批量操作数组 | 不支持 |
需要注意,GraphQL 在一次请求中可以包含多个资源字段,但并不支持通过批量操作数组提交多个独立操作。
当请求频率超过限制时,接口可能返回 HTTP 429,并通过 Retry-After 响应头提示重试等待时间。
对于监控程序,建议按照实际需求设置合理采集周期,并实现缓存及错误重试机制。
常见错误代码
| 错误代码 | 说明 |
|---|---|
| UNAUTHENTICATED | Token缺失或无效 |
| FORBIDDEN | 缺少权限或资源被暂停 |
| NOT_FOUND | 资源不存在或不属于当前组织 |
| BAD_USER_INPUT | 参数错误或查询字段无效 |
| METRICS_UNAVAILABLE | 监控指标暂时不可用 |
| QUERY_TOO_COMPLEX | 查询复杂度超出限制 |
特别需要注意,GraphQL 请求即使返回 HTTP 200,也不一定代表所有字段查询成功。
部分字段失败时,响应可能同时包含 data 和 errors。因此,开发监控程序时不仅需要检查HTTP状态码,还应检查返回JSON中的 errors 字段。
对于临时不可用的监控数据,应保留其异常或未知状态,避免将缺失数据直接当作CPU使用率为0或流量为0。
九、如何将CubePath监控数据接入Grafana?
Grafana 是常见的服务器监控及数据可视化平台,可以用于展示CPU、内存、磁盘和网络流量等时序指标。
CubePath GraphQL API 支持通过标准接口读取监控数据,因此可以配合 Grafana 或其他可视化工具构建自定义面板。
基本接入流程如下:
- 登录CubePath控制台,创建具有只读权限的API Token。
- 使用curl或自建程序调用GraphQL接口。
- 查询目标VPS的CPU、内存、磁盘和网络指标。
- 提取返回数据中的时间戳、数值及单位。
- 将监控数据写入Grafana支持的时序数据库,或通过兼容插件查询。
- 在Grafana中配置CPU、内存、网络及月流量统计图表。
- 根据需要设置监控阈值和异常告警。
例如,可以创建CPU使用率、内存使用率、网络流量、磁盘I/O以及月流量统计等面板,集中查看多台VPS的运行情况。
需要说明的是,CubePath并未在上述GraphQL API文档中提供开箱即用的Grafana原生数据源。用户需要根据所选Grafana版本、数据源插件和数据存储方案,自行完成认证、数据转换及面板配置。
对于不希望自行开发监控程序的用户,CubePath控制台也提供服务器运行指标图表及相关云监控告警功能。
总结
CubePath GraphQL API 为VPS、独立服务器、Kubernetes、负载均衡及其他云基础设施提供统一的只读监控数据查询入口。
相较于分别请求多个监控接口,GraphQL 可以一次查询多个资源,只返回所需字段,适合多服务器集中管理、带宽统计、基础设施监控及自定义报表等场景。
对于普通VPS用户,可以通过curl快速获取CPU、内存及月流量信息;对于需要长期统计的运维人员,则可以结合Grafana或自建监控面板,实现更灵活的服务器资源可视化管理。




















