企业官网建设流程全解析

RelayPulse 是一款企业级 LLM 中转服务可用性监控系统，通过真实 API 调用实时追踪各中转商的服务状态。想在自己的工具里"问一句：这个中转商现在还活着吗？"？只需要掌握它的 3 个公开接口：/api/status（全量状态查询）、/api/status/query（单点/多点状态查询）和/api/status/batch（批量状态查询），再配合board板块过滤参数，就能轻松把可用率、延迟等数据集成到你的脚本、面板或告警系统里。

本文面向新手，全程只需几条curl命令，带你跑通 RelayPulse 状态查询、批量查询与板块过滤的完整实战。

1. 三大接口一览：该用哪一个？

先建立整体印象。RelayPulse 的公开 API 在 internal/api/server.go 中统一注册，核心是下面三个：

怎么选？👇

• 做可视化大屏 / 前端：用/api/status，它返回data+groups双层结构和逐时段时间轴，前端面板正是靠它驱动的（见 frontend/src/hooks/useMonitorData.ts）。
• 脚本里盯一两家：用/api/status/query，URL 参数即可表达，无需构造 JSON。
• 巡检大量服务商：用/api/status/batch，一次请求查 50 组目标，响应精简、只给结论。

先看一眼这些数据最终呈现的样子——这就是/api/status驱动的面板效果：

2. 状态查询实战：GET /api/status

这是功能最全的接口，处理器位于 internal/api/handler.go。一次请求返回{ meta, data, groups }三段：meta是查询元信息（板块计数、缓存模式等），data是监测项列表，groups是多模型分层数据。

常用查询参数速查表

最小可用示例（本地部署默认端口 8080）：

# 近 24 小时全量状态（记得带上 gzip 头，见下文"注意事项"） curl -H "Accept-Encoding: gzip" "http://localhost:8080/api/status?period=24h"

只想看某一家？加上provider：

curl -H "Accept-Encoding: gzip" "http://localhost:8080/api/status?provider=saiai&period=7d"

时间轴怎么读：period=90m时timeline是逐条原始记录；其余周期按 bucket 聚合成可用率序列（构建逻辑见 internal/api/timeline.go）。每个监测项里的current_status给出最新一次探测的status（1=可用、2=降级、0=不可用）、latency（毫秒）与时间戳。

⚠️两个新手高频坑：

1. 必须支持 gzip。/api/status响应较大，服务端强制要求请求头携带Accept-Encoding: gzip，否则直接返回406 NOT_ACCEPTABLE（中间件见 internal/api/server.go）。curl加上-H "Accept-Encoding: gzip"，或用--compressed即可。
2. 响应有缓存。相同参数组合的查询结果会被缓存：90m/24h默认 10 秒、7d/30d默认 60 秒，可通过cache_ttl配置调整（详见 docs/user/config.md）。调试时如果"数据没变"，多半是命中了缓存。

3. 板块过滤实战：board参数怎么用

RelayPulse 用三块"板"管理监测项的生命周期：🔥热板（hot）稳定可用的活跃通道、📊备板（secondary）新上线或观察期通道、❄️冷板（cold）已归档的历史通道。冷板通道会暂停探测，所以查冷板拿到的是"最后状态"而非实时状态。

五种取值各查什么

# 主板（默认）：稳定活跃通道 curl -H "Accept-Encoding: gzip" "http://localhost:8080/api/status?board=hot" # 备板：观察期通道 curl -H "Accept-Encoding: gzip" "http://localhost:8080/api/status?board=secondary" # 冷板：归档通道（已暂停探测） curl -H "Accept-Encoding: gzip" "http://localhost:8080/api/status?board=cold" # active：主板 + 备板（排除冷板） curl -H "Accept-Encoding: gzip" "http://localhost:8080/api/status?board=active" # 全部：不做板块过滤 curl -H "Accept-Encoding: gzip" "http://localhost:8080/api/status?board=all"

过滤逻辑本身很直白：board=active时保留hot/secondary的监测项，其余值则精确匹配（见 internal/api/handler.go）。官方文档中也有完整说明，参见 docs/user/config.md。

💡小技巧：响应里meta.board_counts会返回{hot, secondary, cold}三个计数，meta.boards.enabled告诉你当前部署是否启用了板块功能。写脚本时先读meta，再决定要不要按板块分页拉取，是更稳的做法。

4. 单点查询实战：GET /api/status/query

当脚本只需要"某家的某个通道现在能不能用"时，全量矩阵太重了。/api/status/query专为这种场景设计（实现见 internal/api/status_query_handler.go），返回精简结构：{ as_of, results: [...] }，状态直接是up/down/degraded字符串。

单查：URL 参数三段式

# 查某 provider 的全部服务（provider 必填，service/channel 可选） curl "http://localhost:8080/api/status/query?provider=saiai" # 精确到通道 curl "http://localhost:8080/api/status/query?provider=saiai&service=cc&channel=o"

参数层层收窄：只给provider返回它的全部 service→channel 树；给service就只展开该服务；给channel就精确到通道。查不到时不会整体报错，而是在该条结果里返回错误对象，例如{"code":"NOT_FOUND","message":"provider 不存在"}——其余查询照常返回，非常适合"批量试探"。

判定规则：一个通道下挂了多个模型时，取最差状态作为通道状态（某模型降级则通道降级，某模型宕机则通道 down），实现细节见 internal/api/status_query_handler.go。

多查：q参数最多 20 组

curl "http://localhost:8080/api/status/query?q=saiai/cc&q=elysiver&channel=o" # q 格式为 provider/service/channel，后两段可省略；最多 20 组，超出返回 400

5. 批量查询实战：POST /api/status/batch

GET 版一次 20 组封顶，而巡检脚本往往要一次盯 50 家——这就是POST /api/status/batch存在的意义（实现见 internal/api/status_query_handler.go）。请求体是一个 JSON 数组，每组provider必填：

curl -X POST "http://localhost:8080/api/status/batch" \ -H "Content-Type: application/json" \ -d '{ "queries": [ {"provider": "saiai", "service": "cc"}, {"provider": "elysiver", "service": "cc", "channel": "o"}, {"provider": "xuai"} ] }'

返回结构与/api/status/query完全一致，results数组与你的queries顺序对应。响应里每个通道还带一个board字段，它是通道级活跃度的二值折叠结果：该通道下（排除已禁用项）全部为冷板时返回cold，其余情况一律hot——用来做订阅资格校验非常顺手（注释见 internal/api/status_query_handler.go）。

GET 与 POST 怎么选？🧭

6. 统一错误格式与排错清单

所有 API 共用一套错误信封（定义见 internal/api/api_error.go），HTTP 状态码之外，error对象给出机器可读的code和人类可读的message：

{ "error": { "code": "INVALID_PARAM", "message": "无效的时间范围: 3d", "request_id": "a1b2c3d4" } }

request_id会透传给日志，报障时直接贴它最快。常见错误码对照：

顺手记下两个运维接口：GET /health是存活探针，GET /ready会额外检查数据库连通性——批量任务开始前先打一遍/ready，比拿到 503 再排查省心得多。

7. 进阶：事件流与延伸阅读

• 状态变更事件：GET /api/events?since_id=0&limit=20&types=DOWN,UP可以增量拉取宕机/恢复事件（分页用since_id，实现见 internal/api/events_handler.go），配合GET /api/events/latest拿到最新事件 ID，是搭"断线告警"的原料。
• 配置手册：缓存 TTL、并发查询、板块开关等全部服务端开关，都在 docs/user/config.md 里，改 YAML 即热更新、无需重启。
• 接口实现总入口：internal/api/ 目录下的 query.go 展示了从查询参数到数据库读取、再到 JSON 序列化的完整链路，想深挖性能调优（批量/并发查询回退策略）从这里入手。

总结

三句话回顾 RelayPulse 的 API 核心玩法：

1. 看全景用GET /api/status，配period+board+time_filter自由切窗口与板块；
2. 盯重点用GET /api/status/query，URL 三段式定位到通道级；
3. 跑巡检用POST /api/status/batch，50 组目标一次拿全。

掌握这套状态查询、批量查询与板块过滤的组合拳，RelayPulse 的数据就能无缝融入你的监控大盘、脚本巡检和告警链路 🚀。