Local API Guide

清羽飞扬 API 文档

说明本项目本地 /api 接口的用途、参数和查询方式，方便你调试与二次开发。

数据看板 API 文档
仅覆盖本项目本地 API

如何查询数据？先看这三件事。

1. 这些接口都是当前站点下的本地接口，例如 /api/config、/api/traffic。

2. 接口背后会由服务端使用腾讯云密钥去请求 EdgeOne / Pages 数据，所以浏览器侧不需要直接暴露 SecretId / SecretKey。

3. 最常用的数据入口是 /api/traffic，通过不同 metric 参数获取流量、带宽、请求数、性能、安全与排行数据。

基础信息

站点名称

清羽飞扬流量分析

接口前缀

同域调用，统一使用 /api/*

错误返回

失败时通常返回 { "error": "..." }

服务端依赖

需正确配置 SECRET_ID 与 SECRET_KEY，或在根目录提供 key.txt。

Quick Start

快速查询示例

如果你只是想快速看数据，通常先调用站点列表，再带着 zoneId 查询域名和 traffic 数据。

GET /api/zones
GET /api/hosts?zoneId=zone-xxxx
GET /api/traffic?metric=l7Flow_flux&startTime=2026-05-11T00:00:00Z&endTime=2026-05-11T23:59:59Z&zoneId=zone-xxxx&host=example.com

查询顺序建议：先拿 Zone，再根据 Zone 拿 Host，最后按 metric 请求图表数据。

时间参数：统一传 ISO 时间字符串，和首页看板内部逻辑保持一致。

注意：/api/traffic 的返回结构会随 metric 类型变化，不建议把它当成完全固定的单一 JSON 结构。

Auth & Time

鉴权、时间与通用约定

浏览器侧无需鉴权：所有请求都发往本站 /api/*，腾讯云密钥只在服务端读取。

密钥来源：优先读取环境变量 SECRET_ID 与 SECRET_KEY，缺失时尝试读取根目录 key.txt。

时间格式：建议使用 UTC ISO 字符串，例如 2026-05-11T00:00:00Z。

字段说明
zoneId站点 ID；不传时部分接口会使用 * 或尝试自动发现 Pages Zone。
host域名过滤；传 * 或不传表示不过滤。
interval统计粒度；支持值取决于腾讯云接口，传 auto 时服务端不透传。

Response Shapes

返回结构怎么理解

时序类指标

流量、带宽、请求、性能、安全等通常返回时间序列，前端会按时间轴汇总成趋势图和 KPI。

TOP 排行类指标

国家、状态码、域名、URL 等排行通常在 Data[0].DetailData 中读取 Key/Value。

Pages 接口

Pages 相关接口可能返回字符串形式的 Result，服务端会尝试追加 parsedResult。

/api/config

获取站点名称、图标和备案号等前端展示配置。

GET

请求参数

无。

典型用途

首页和文档页启动时读取品牌信息，并更新标题、图标与备案号展示。

{
  "siteName": "清羽飞扬流量分析",
  "siteIcon": "/favicon.png",
  "icp": "陕ICP备2024028531号"
}

/api/zones

获取当前账号可访问的 Zone 列表，用于填充站点下拉框。

GET

请求参数：无。

查询用途：页面初始化时先读取站点列表，再决定后续的 Host 与指标查询目标。

失败情况：如果密钥缺失，会返回 500 与 error 字段。

GET /api/zones

/api/hosts

根据选中的 Zone 推导可选域名列表，便于查看某个子域名的数据。

GET

请求参数：

  • zoneId：目标站点 ID，建议必传。

返回说明：返回结构里常见 Hosts 数组，每项包含 Host 字段。

前端额外处理：首页会进一步过滤带有 .edgeone. 的默认域名。

GET /api/hosts?zoneId=zone-xxxx

{
  "Hosts": [
    { "Host": "www.example.com" },
    { "Host": "api.example.com" }
  ]
}

/api/traffic

核心数据接口。通过 metric 参数统一查询流量、带宽、请求数、性能、安全和 TOP 排行数据。

GET

常用参数：

  • metric：指标名，必传；不传时默认 l7Flow_flux。
  • startTime / endTime：时间范围；不传时默认最近 24 小时。
  • zoneId：站点 ID；不传时传给腾讯云的 ZoneIds 为 ["*"]。
  • host：域名过滤；仅部分指标支持，安全指标不支持按域名过滤。
  • interval：统计粒度；可选，不传则由腾讯云接口决定。

分流逻辑：服务端会根据 metric 自动选择腾讯云接口：时序 L7、源站拉取、TOP 排行、安全防护或 Edge Functions。

GET /api/traffic?metric=l7Flow_request&startTime=2026-05-11T00:00:00Z&endTime=2026-05-11T23:59:59Z&zoneId=zone-xxxx&host=www.example.com

// 返回为腾讯云原始响应；前端会在浏览器侧转成图表需要的结构。
metric 类型服务端调用host 过滤说明
普通时序DescribeTimingL7AnalysisData支持流量、带宽、请求、响应耗时等基础指标。
源站拉取DescribeTimingL7OriginPullData支持后缀为 _hy 的源站回源类指标。
TOP 排行DescribeTopL7AnalysisData支持国家、区域、状态码、域名、URL、UA 等排行。
安全防护DescribeWebProtectionData不支持CC / 托管规则 / 速率限制等拦截次数。
边缘函数DescribeTimingFunctionAnalysisData支持函数请求数、CPU 耗时等函数分析指标。

Metrics

指标速查表

看板常用指标

  • l7Flow_flux：总流量
  • l7Flow_inFlux / l7Flow_outFlux：请求 / 响应流量
  • l7Flow_bandwidth：总带宽峰值
  • l7Flow_request：请求数
  • l7Flow_avgResponseTime：平均响应耗时
  • l7Flow_avgFirstByteResponseTime：平均首字节耗时

安全与函数指标

  • ccAcl_interceptNum：精准防护拦截
  • ccManage_interceptNum：托管规则拦截
  • ccRate_interceptNum：速率限制拦截
  • function_requestCount：边缘函数请求数
  • function_cpuCostTime：边缘函数 CPU 耗时
排行维度流量 metric请求数 metric
国家l7Flow_outFlux_countryl7Flow_request_country
省份 / 区域l7Flow_outFlux_provincel7Flow_request_province
状态码l7Flow_outFlux_statusCodel7Flow_request_statusCode
域名l7Flow_outFlux_domainl7Flow_request_domain
URLl7Flow_outFlux_urll7Flow_request_url
客户端l7Flow_outFlux_ual7Flow_request_ua

/api/pages/build-count

查询 Pages 构建或部署使用情况。

GET

请求参数：

  • zoneId：可选，不传时服务端会尝试自动发现 default-pages-zone。

内部调用：DescribePagesResources，Interface 为 pages:DescribePagesDeploymentUsage。

返回说明：如果响应中存在 Result 串，服务端会尝试额外解析为 parsedResult 字段。

GET /api/pages/build-count?zoneId=zone-xxxx

{
  "Result": "{...}",
  "parsedResult": { }
}

/api/pages/cloud-function-requests

查询 Pages 云函数请求量统计，适合看某段时间内函数调用表现。

GET

请求参数：

  • zoneId：可选；不传时自动寻找 Pages Zone。
  • startTime：可选；开始时间。
  • endTime：可选；结束时间。

内部调用：DescribePagesResources，Interface 为 pages:DescribePagesFunctionsRequestDataByZone，默认 Interval 为 hour。

GET /api/pages/cloud-function-requests?zoneId=zone-xxxx&startTime=2026-05-01T00:00:00Z&endTime=2026-05-11T23:59:59Z

/api/pages/cloud-function-monthly-stats

查询 Pages 云函数历史或月度统计数据。

GET

请求参数：

  • zoneId：可选；不传时自动寻找 Pages Zone。

内部调用：DescribePagesResources，Interface 为 pages:DescribeHistoryCloudFunctionStats。

适合场景：查看更长周期的云函数用量、历史统计或用于扩展运营面板。

GET /api/pages/cloud-function-monthly-stats?zoneId=zone-xxxx

Troubleshooting

常见问题与排查

返回 Missing credentials

说明服务端没有读到腾讯云密钥。请检查环境变量 SECRET_ID / SECRET_KEY，或确认 key.txt 格式可被读取。

域名下拉为空

/api/hosts 会查询最近 7 天的域名流量排行；如果该 Zone 最近无数据，可能只返回空数组。

安全数据与域名不一致

安全防护接口当前只按 Zone 查询，不支持按 Host 过滤，因此选择单个域名时安全卡片仍可能显示站点级数据。

Pages 数据获取不到

Pages 接口会优先寻找 default-pages-zone。如果账号没有 Pages Zone 或权限不足，会返回 400 / 500 错误。