openstatus API 实战指南用 ConnectRPC 将 uptime 监控与状态页写成代码【免费下载链接】openstatus Status page with uptime monitoring API monitoring as code 项目地址: https://gitcode.com/GitHub_Trending/op/openstatusopenstatus 提供了一套类型化、基于 JSON-over-HTTP 的公共 API底层由 ConnectRPC 驱动基地址为https://api.openstatus.dev。Dashboard 上你能执行的每一个操作——创建监控器、管理状态页、发布事故报告、安排维护窗口——都能通过这套 API 以编程方式完成并且共享同一个工作区、同一份审计日志和同一把 API Key。读完本文你将掌握 API 的认证方式、核心服务与 RPC 结构、典型调用示例以及它和 MCP 服务器之间的取舍可以直接在 CI/CD、脚本与自建集成中把监控即代码落地。从 Dashboard 到 APIopenstatus 公共 API 全景openstatus 公共 API 是ConnectRPCConnect 协议之上的类型化 JSON-over-HTTP 层。这意味着它遵循 schema-first 的.proto文件定义仓库中的全部契约位于 packages/proto/api/openstatus请求与响应既可以是 JSON也可以是 protobuf即使读操作也必须使用POST方法所有 RPC 挂在/rpc/*路径前缀下与既有的 REST API 共用同一个 Hono 服务端口。仓库中的 ConnectRPC 规范说明 给出了明确的架构决策仅支持 Connect 协议兼容 HTTP/1.1、仅使用 unary 调用无流式、schema 由 Buf 工具链管理buf.yaml、buf.gen.yaml包命名统一为openstatus.domain.v1例如openstatus.monitor.v1代码生成目标覆盖 TypeScriptbufbuild/protobufconnectrpc/connect与 Go。服务端的实际挂载实现在 apps/server/src/routes/rpc/index.ts 中所有/rpc/*请求先剥掉/rpc前缀再匹配 Connect 路由表中的 handler最后通过universalServerRequestFromFetch/universalServerResponseToFetch完成 Fetch API 与 Connect 通用消息的互转。当前已注册到 Connect 路由表的服务见 apps/server/src/routes/rpc/router.ts包括服务职责MonitorService监控器 CRUD 与运维操作HTTP/TCP/DNS/ICMP/gRPC 五种类型StatusPageService状态页、组件、组件分组、订阅者与聚合状态查询StatusReportService事故/状态报告的完整生命周期MaintenanceService维护窗口的排期管理NotificationService通知渠道管理PrivateLocationService私有节点管理HealthService健康检查所有请求会依次经过五层拦截器errorInterceptor错误映射为 ConnectError→loggingInterceptor请求/响应日志→authInterceptorAPI Key 校验与工作区上下文注入→validationInterceptor基于 protovalidate 的消息校验→trackingInterceptor成功事件埋点。认证x-openstatus-key头与 API TokenAPI 的认证方式非常简单把 API Key 放在x-openstatus-key请求头中Key 在Settings → API Tokens中生成形如x-openstatus-key: os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx服务端凭据提取的源码在 apps/server/src/libs/middlewares/credentials.ts优先读取x-openstatus-key头其次才尝试Authorization: Bearer tokenx-openstatus-key优先级更高两者并存时以 header 为准。Key 的典型前缀为os_另有sa_前缀表示超级管理员 Token可借助x-workspace-id元数据头指定目标工作区详见 ConnectRPC 规范说明。API Key 本身的管理创建、吊销、列出也通过 Dashboard 的 tRPC 路由暴露实现在 packages/api/src/router/apiKey.ts创建时返回一次性明文 TokenUI 展示一次后即丢弃吊销与查询分别调用 services 层的revokeApiKey与listApiKeys。在服务端每一次 API 调用的工作区身份都由authInterceptor从凭据推断并在 apps/server/src/routes/rpc/adapter.ts 中携带apiKey.id进入服务上下文——这意味着 API 发起的变更会在审计日志中追溯到具体的 Key。第一个请求列出所有监控器文档给出的最小可运行示例注意 shell 变量$OPENSTATUS_API_KEY需提前导出curl https://api.openstatus.dev/rpc/openstatus.v1.MonitorService/ListMonitors \ -X POST \ -H Content-Type: application/json \ -H x-openstatus-key: $OPENSTATUS_API_KEY \ -d {}几点说明路径约定Connect RPC 路径由「包名 服务名 方法名」组成。按仓库中openstatus.domain.v1的包命名见 monitor/v1/service.proto 的package openstatus.monitor.v1MonitorService 的规范完整路径为/rpc/openstatus.monitor.v1.MonitorService/ListMonitors生成的 TypeScript 服务定义在 packages/proto/gen/ts/openstatus/monitor/v1/service_pb.ts。请求参数ListMonitorsRequest支持两个可选分页字段——limit1100默认 50与offset≥0默认 0。响应结构ListMonitorsResponse按协议类型分组返回http_monitors、tcp_monitors、dns_monitors、icmp_monitors、grpc_monitors并附带total_size表示全部类型的监控器总数。幂等标记ListMonitors在 proto 中声明了idempotency_level NO_SIDE_EFFECTS表明它是纯读操作可安全重试。监控器管理五种协议类型的 CRUD 与运维操作全部 RPC 一览MonitorService是 API 中最核心的服务定义于 monitor/v1/service.protoRPC说明CreateHTTPMonitor/CreateTCPMonitor/CreateDNSMonitor/CreateICMPMonitor/CreateGRPCMonitor创建对应类型的监控器UpdateHTTPMonitor/UpdateTCPMonitor/UpdateDNSMonitor/UpdateICMPMonitor/UpdateGRPCMonitor部分更新monitor字段全部可选TriggerMonitor在所有已配置区域立即触发一次检查受合成检查配额限流DeleteMonitor删除监控器ListMonitors分页列出工作区全部监控器GetMonitor按 ID 读取单个监控器通过MonitorConfigoneof 返回类型化配置GetMonitorStatus返回各区域的实时状态GetMonitorSummary返回聚合指标延迟分位数、成功/降级/失败计数ListMonitorHTTPResponseLogs/GetMonitorHTTPResponseLog查询 14 天窗口内的 HTTP 响应日志MonitorConfig使用 oneof 将http、tcp、dns、icmp、grpc五种配置合为一体GetMonitor的返回即这一结构。HTTPMonitor 配置字段详解HTTP 监控器的核心字段定义于 http_monitor.proto字段约束可直接作为参数校验依据字段类型/约束说明namestring1256监控器名称必填urlstring12048须为合法 URI目标地址必填periodicity枚举检查周期见下方枚举method枚举HTTP 方法默认GETbodystring请求体POST/PUT/PATCH 等场景timeoutint640120000 ms超时时间默认 45000degraded_atint640120000 ms判定为「降级」的延迟阈值retryint64010重试次数默认 3follow_redirectsbool是否跟随重定向默认 trueheaders数组最多 20 项自定义请求头key/valuestatus_code_assertions/body_assertions/header_assertions数组各自最多 10 项状态码/响应体/响应头断言类型见 assertions.protodescriptionstring最大 1024描述activebool是否立即开始检查默认 falsepublicbool是否公开可见默认 falseregions数组最多 28 项执行检查的地理区域open_telemetry对象OTEL 导出配置endpoint 最多 20 个自定义头status枚举当前运行状态只读private_location_idsstring 数组关联的私有节点 ID只读相关枚举定义于 monitor.protoPeriodicityPERIODICITY_30S、PERIODICITY_1M、PERIODICITY_5M、PERIODICITY_10M、PERIODICITY_30M、PERIODICITY_1HHTTPMethodGET、POST、HEAD、PUT、PATCH、DELETE、TRACE、CONNECT、OPTIONSMonitorStatusACTIVE、DEGRADED、ERRORRegion覆盖 Fly.ioAMS/ARN/BOM/CDG/DFW/EWR/FRA/GRU/IAD/JNB/LAX/LHR/NRT/ORD/SJC/SIN/SYD/YYZ、KoyebFRA/PAR/SFO/SIN/TYO/WAS与 RailwayUS_WEST2/US_EAST4/EUROPE_WEST4/ASIA_SOUTHEAST1共 28 个区域。创建 HTTP 监控器的示例curl https://api.openstatus.dev/rpc/openstatus.monitor.v1.MonitorService/CreateHTTPMonitor \ -X POST \ -H Content-Type: application/json \ -H x-openstatus-key: $OPENSTATUS_API_KEY \ -d { monitor: { name: Production API Health Check, url: https://api.example.com/health, periodicity: PERIODICITY_1M, method: HTTP_METHOD_GET, timeout: 45000, retry: 3, headers: [{ key: Authorization, value: Bearer token123 }], regions: [REGION_FLY_IAD, REGION_FLY_FRA], active: true } }创建成功后返回带 ID 的HTTPMonitorUpdateHTTPMonitor以id 可选的monitor字段实现部分更新TriggerMonitor立即在所有配置区域跑一次真实检查proto 中注明受 synthetic-checks 配额限流适合验证配置或排障。聚合指标与响应日志GetMonitorSummarytime_range支持TIME_RANGE_1D/TIME_RANGE_7D/TIME_RANGE_14D可按区域过滤最多 28 项。返回total_successful/total_degraded/total_failed计数、p50/p75/p90/p95/p99延迟分位数毫秒以及last_ping_at时间戳。ListMonitorHTTPResponseLogs分页查询 14 天窗口内的响应日志每条记录含latency、status_code、request_statusSUCCESS/ERROR/DEGRADED、region、triggerCRON 或 API 触发、cron_timestamp与timestamp。GetMonitorHTTPResponseLog返回单次检查的完整详情包括HTTPResponseLogTiming五段耗时dns/connect/tls/ttfb/transfer、脱敏后的响应头headers、错误信息与序列化的断言配置assertions是定位慢请求与断言失败的最有力工具。状态页管理从建页到组件、分组与订阅StatusPageService定义于 status_page/v1/service.proto是 API 中 RPC 最丰富的服务可分为四组页面 CRUDCreateStatusPage、GetStatusPage、ListStatusPages分页limit 1100 默认 50、UpdateStatusPage、DeleteStatusPage。创建状态页的核心字段与校验规则CreateStatusPageRequest字段约束说明title1256页面标题必填slug正则^[a-z0-9](?:-[a-z0-9])*$URL 友好别名小写字母数字加连字符必填description最大 1024描述homepage_url/contact_urlURL主页与联系页default_locale/locales枚举默认语言与启用语言custom_domain最大 256自定义域名theme枚举视觉主题默认SYSTEMaccess_type枚举访问控制默认PUBLICpassword1256当access_type PASSWORD_PROTECTED时必填auth_email_domains数组当access_type AUTHENTICATED时使用的邮箱域名白名单allowed_ip_ranges字符串当access_type IP_RESTRICTED时必填逗号分隔的 IPv4 CIDRallow_indexbool是否允许搜索引擎收录默认 truecustom_theme对象按模式覆盖 CSS 变量仅接受受支持变量名需要 custom-theme 套餐组件与分组AddMonitorComponent把监控器挂到状态页name缺省取监控器名、AddStaticComponent纯静态组件需name、RemoveComponent、UpdateComponent、GetPageComponent、CreateComponentGroup/DeleteComponentGroup/UpdateComponentGroup分组支持default_open控制默认展开。订阅者这里有两种互补的订阅 RPC选哪个取决于谁发起的订阅SubscribeToPage终端用户自助订阅带双重 opt-in 验证——系统发送验证邮件用户确认后订阅才生效若该邮箱曾退订则复用原有记录重新激活而非重复创建。CreatePageSubscription运营方代建订阅免验证立即生效适用于已在线下确认同意的伙伴/厂商场景支持 email 与 webhook 渠道Slack/Discord 的 webhook URL 按前缀自动识别 payload 风格也可附带自定义头仍会生成管理 Token 供对方通过/manage/{token}与/unsubscribe/{token}自助管理。另有UnsubscribeFromPage按 email 或订阅者 ID与ListSubscribers支持include_unsubscribed。内容与聚合状态GetStatusPageContent按id需认证、限定工作区或slug公开访问要求页面access_type PUBLIC返回页面完整内容——含组件、分组、进行中的状态报告与已排期维护。GetOverallStatus返回聚合状态与各组件状态聚合优先级为degraded进行中的状态报告 maintenance进行中的维护窗口 operational。GetStatusPageOverview一次认证调用取回页面、富配置、组件、分组、报告、维护与计算出的状态。GetPageComponentDailySummary按天返回ok/degraded/error/count桶并合并事件时间线最多 45 天是渲染状态条与 uptime 日历的单一事实来源同样支持 id 与 slug 两种访问路径。事故报告与维护窗口把故障响应写成代码状态报告Status ReportStatusReportService定义于 status_report/v1/service.proto其生命周期状态枚举在 status_report.proto 中INVESTIGATING→IDENTIFIED→MONITORING→RESOLVED。主要 RPCCreateStatusReport、GetStatusReport含完整更新时间线、ListStatusReports、UpdateStatusReport、DeleteStatusReport、AddStatusReportUpdate。创建事故报告的示例notify为 true 时将通过邮件通知页面订阅者curl https://api.openstatus.dev/rpc/openstatus.status_report.v1.StatusReportService/CreateStatusReport \ -X POST \ -H Content-Type: application/json \ -H x-openstatus-key: $OPENSTATUS_API_KEY \ -d { title: API Degradation Investigation, status: STATUS_REPORT_STATUS_INVESTIGATING, message: We are investigating reports of increased API latency., date: 2024-03-15T10:30:00Z, page_id: pg_xxxxxxxx, notify: true }date必须为 RFC 3339 格式正则校验^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[-]\d{2}:\d{2})$。AddStatusReportUpdate在追加时间线条目的同时把报告推进到指定状态component_impacts字段PAGE_COMPONENT_IMPACT_DEGRADED_PERFORMANCE/PARTIAL_OUTAGE/MAJOR_OUTAGE等允许为每个组件声明受影响程度。维护窗口MaintenanceMaintenanceService定义于 maintenance/v1/service.protoCreateMaintenance、GetMaintenance、ListMaintenances、UpdateMaintenance、DeleteMaintenance。curl https://api.openstatus.dev/rpc/openstatus.maintenance.v1.MaintenanceService/CreateMaintenance \ -X POST \ -H Content-Type: application/json \ -H x-openstatus-key: $OPENSTATUS_API_KEY \ -d { title: Database Migration, message: Scheduled maintenance for the primary database., from: 2024-03-01T02:00:00Z, to: 2024-03-01T06:00:00Z, page_id: pg_xxxxxxxx }from/to均为必填的 RFC 3339 时间维护窗口会以maintenance状态参与GetOverallStatus的聚合优先级计算。其他服务通知、私有节点与健康检查NotificationServicenotification/v1/service.proto通知渠道 CRUD另有SendTestNotification发送测试通知与CheckNotificationLimit检查渠道配额。PrivateLocationServiceprivate_location/v1/service.proto私有节点的创建、查询、列表、更新与删除用于在自有基础设施中运行探针。HealthServicehealth/v1/health.proto提供Check健康检查 RPC。Schema 与 SDKOpenAPI 描述文件机器可读的 API 描述位于https://api.openstatus.dev/openapi同时提供/openapi.yaml、/openapi.json与/openapi-v1.json三种形式。服务端实现在 apps/server/src/routes/openapi.ts文档公开、无需认证并带有Access-Control-Allow-Origin: *与Cache-Control: public, max-age3600方便浏览器端与 Agent 直接抓取。Node SDKopenstatus/sdk-node可从 jsr.io 获取提供类型化客户端省去手写 curl。Terraform Provider官方工具链见 openstatus.dev 的 tooling 页面支持以声明式资源管理监控器等对象。类型化客户端源码本仓库已生成 TypeScript 客户端见 packages/proto/gen/ts可供自建集成直接参考调用签名。错误处理Connect 层统一使用标准错误码并携带 GoogleErrorInfo结构化详情依据 ConnectRPC 规范说明错误码典型场景NOT_FOUND监控器/状态页 ID 不存在INVALID_ARGUMENT参数未通过 protovalidate 校验如 slug 非法、limit 越界PERMISSION_DENIED凭据无权限访问目标资源UNAUTHENTICATED缺少或错误的x-openstatus-keyRESOURCE_EXHAUSTED触发限流或配额如TriggerMonitor的合成检查配额INTERNAL/UNAVAILABLE服务端内部错误或暂不可用ErrorInfo的domain为openstatus.comreason为机器可读的错误原因如MONITOR_NOT_FOUNDmetadata中携带requestId、resourceId等上下文便于日志关联与排障。所有纯读 RPC 都声明了NO_SIDE_EFFECTS幂等级别可安全重试变更类 RPC 则被完整写入工作区审计日志可通过apiKey.id追溯到具体凭据。API 还是 MCP何时选择openstatus 同时提供两条自动化通路选型取决于使用场景MCP 的完整说明见 openstatus-mcp Skill 文档场景推荐原因程序化集成、CI/CD、定时脚本、自建系统API以x-openstatus-key头认证POST JSON 即可无额外依赖同一个 Key 同时可用于 CLI、REST API 与 Terraform provider聊天形态的 AI 客户端Claude、Cursor、Codex 等MCP 服务器https://api.openstatus.dev/mcp支持 OAuthPKCE与 API Key 两种凭据按工作区与读写范围授权提供list_*/get_*与变更工具适合对话式查询与发布操作两者的数据面完全一致同样的工作区、同样的审计日志、同样的底层服务。对多数工程化场景直接调用 API 更加可控——一条 curl、一个 Node SDK 调用即可完成监控器创建、事故发布或维护排期让整个监控与状态管理流程真正成为代码的一部分。【免费下载链接】openstatus Status page with uptime monitoring API monitoring as code 项目地址: https://gitcode.com/GitHub_Trending/op/openstatus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 openstatus API 实战指南：用 ConnectRPC 将 uptime 监控与状态页写成代码
openstatus API 实战指南用 ConnectRPC 将 uptime 监控与状态页写成代码【免费下载链接】openstatus Status page with uptime monitoring API monitoring as code 项目地址: https://gitcode.com/GitHub_Trending/op/openstatusopenstatus 提供了一套类型化、基于 JSON-over-HTTP 的公共 API底层由 ConnectRPC 驱动基地址为https://api.openstatus.dev。Dashboard 上你能执行的每一个操作——创建监控器、管理状态页、发布事故报告、安排维护窗口——都能通过这套 API 以编程方式完成并且共享同一个工作区、同一份审计日志和同一把 API Key。读完本文你将掌握 API 的认证方式、核心服务与 RPC 结构、典型调用示例以及它和 MCP 服务器之间的取舍可以直接在 CI/CD、脚本与自建集成中把监控即代码落地。从 Dashboard 到 APIopenstatus 公共 API 全景openstatus 公共 API 是ConnectRPCConnect 协议之上的类型化 JSON-over-HTTP 层。这意味着它遵循 schema-first 的.proto文件定义仓库中的全部契约位于 packages/proto/api/openstatus请求与响应既可以是 JSON也可以是 protobuf即使读操作也必须使用POST方法所有 RPC 挂在/rpc/*路径前缀下与既有的 REST API 共用同一个 Hono 服务端口。仓库中的 ConnectRPC 规范说明 给出了明确的架构决策仅支持 Connect 协议兼容 HTTP/1.1、仅使用 unary 调用无流式、schema 由 Buf 工具链管理buf.yaml、buf.gen.yaml包命名统一为openstatus.domain.v1例如openstatus.monitor.v1代码生成目标覆盖 TypeScriptbufbuild/protobufconnectrpc/connect与 Go。服务端的实际挂载实现在 apps/server/src/routes/rpc/index.ts 中所有/rpc/*请求先剥掉/rpc前缀再匹配 Connect 路由表中的 handler最后通过universalServerRequestFromFetch/universalServerResponseToFetch完成 Fetch API 与 Connect 通用消息的互转。当前已注册到 Connect 路由表的服务见 apps/server/src/routes/rpc/router.ts包括服务职责MonitorService监控器 CRUD 与运维操作HTTP/TCP/DNS/ICMP/gRPC 五种类型StatusPageService状态页、组件、组件分组、订阅者与聚合状态查询StatusReportService事故/状态报告的完整生命周期MaintenanceService维护窗口的排期管理NotificationService通知渠道管理PrivateLocationService私有节点管理HealthService健康检查所有请求会依次经过五层拦截器errorInterceptor错误映射为 ConnectError→loggingInterceptor请求/响应日志→authInterceptorAPI Key 校验与工作区上下文注入→validationInterceptor基于 protovalidate 的消息校验→trackingInterceptor成功事件埋点。认证x-openstatus-key头与 API TokenAPI 的认证方式非常简单把 API Key 放在x-openstatus-key请求头中Key 在Settings → API Tokens中生成形如x-openstatus-key: os_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx服务端凭据提取的源码在 apps/server/src/libs/middlewares/credentials.ts优先读取x-openstatus-key头其次才尝试Authorization: Bearer tokenx-openstatus-key优先级更高两者并存时以 header 为准。Key 的典型前缀为os_另有sa_前缀表示超级管理员 Token可借助x-workspace-id元数据头指定目标工作区详见 ConnectRPC 规范说明。API Key 本身的管理创建、吊销、列出也通过 Dashboard 的 tRPC 路由暴露实现在 packages/api/src/router/apiKey.ts创建时返回一次性明文 TokenUI 展示一次后即丢弃吊销与查询分别调用 services 层的revokeApiKey与listApiKeys。在服务端每一次 API 调用的工作区身份都由authInterceptor从凭据推断并在 apps/server/src/routes/rpc/adapter.ts 中携带apiKey.id进入服务上下文——这意味着 API 发起的变更会在审计日志中追溯到具体的 Key。第一个请求列出所有监控器文档给出的最小可运行示例注意 shell 变量$OPENSTATUS_API_KEY需提前导出curl https://api.openstatus.dev/rpc/openstatus.v1.MonitorService/ListMonitors \ -X POST \ -H Content-Type: application/json \ -H x-openstatus-key: $OPENSTATUS_API_KEY \ -d {}几点说明路径约定Connect RPC 路径由「包名 服务名 方法名」组成。按仓库中openstatus.domain.v1的包命名见 monitor/v1/service.proto 的package openstatus.monitor.v1MonitorService 的规范完整路径为/rpc/openstatus.monitor.v1.MonitorService/ListMonitors生成的 TypeScript 服务定义在 packages/proto/gen/ts/openstatus/monitor/v1/service_pb.ts。请求参数ListMonitorsRequest支持两个可选分页字段——limit1100默认 50与offset≥0默认 0。响应结构ListMonitorsResponse按协议类型分组返回http_monitors、tcp_monitors、dns_monitors、icmp_monitors、grpc_monitors并附带total_size表示全部类型的监控器总数。幂等标记ListMonitors在 proto 中声明了idempotency_level NO_SIDE_EFFECTS表明它是纯读操作可安全重试。监控器管理五种协议类型的 CRUD 与运维操作全部 RPC 一览MonitorService是 API 中最核心的服务定义于 monitor/v1/service.protoRPC说明CreateHTTPMonitor/CreateTCPMonitor/CreateDNSMonitor/CreateICMPMonitor/CreateGRPCMonitor创建对应类型的监控器UpdateHTTPMonitor/UpdateTCPMonitor/UpdateDNSMonitor/UpdateICMPMonitor/UpdateGRPCMonitor部分更新monitor字段全部可选TriggerMonitor在所有已配置区域立即触发一次检查受合成检查配额限流DeleteMonitor删除监控器ListMonitors分页列出工作区全部监控器GetMonitor按 ID 读取单个监控器通过MonitorConfigoneof 返回类型化配置GetMonitorStatus返回各区域的实时状态GetMonitorSummary返回聚合指标延迟分位数、成功/降级/失败计数ListMonitorHTTPResponseLogs/GetMonitorHTTPResponseLog查询 14 天窗口内的 HTTP 响应日志MonitorConfig使用 oneof 将http、tcp、dns、icmp、grpc五种配置合为一体GetMonitor的返回即这一结构。HTTPMonitor 配置字段详解HTTP 监控器的核心字段定义于 http_monitor.proto字段约束可直接作为参数校验依据字段类型/约束说明namestring1256监控器名称必填urlstring12048须为合法 URI目标地址必填periodicity枚举检查周期见下方枚举method枚举HTTP 方法默认GETbodystring请求体POST/PUT/PATCH 等场景timeoutint640120000 ms超时时间默认 45000degraded_atint640120000 ms判定为「降级」的延迟阈值retryint64010重试次数默认 3follow_redirectsbool是否跟随重定向默认 trueheaders数组最多 20 项自定义请求头key/valuestatus_code_assertions/body_assertions/header_assertions数组各自最多 10 项状态码/响应体/响应头断言类型见 assertions.protodescriptionstring最大 1024描述activebool是否立即开始检查默认 falsepublicbool是否公开可见默认 falseregions数组最多 28 项执行检查的地理区域open_telemetry对象OTEL 导出配置endpoint 最多 20 个自定义头status枚举当前运行状态只读private_location_idsstring 数组关联的私有节点 ID只读相关枚举定义于 monitor.protoPeriodicityPERIODICITY_30S、PERIODICITY_1M、PERIODICITY_5M、PERIODICITY_10M、PERIODICITY_30M、PERIODICITY_1HHTTPMethodGET、POST、HEAD、PUT、PATCH、DELETE、TRACE、CONNECT、OPTIONSMonitorStatusACTIVE、DEGRADED、ERRORRegion覆盖 Fly.ioAMS/ARN/BOM/CDG/DFW/EWR/FRA/GRU/IAD/JNB/LAX/LHR/NRT/ORD/SJC/SIN/SYD/YYZ、KoyebFRA/PAR/SFO/SIN/TYO/WAS与 RailwayUS_WEST2/US_EAST4/EUROPE_WEST4/ASIA_SOUTHEAST1共 28 个区域。创建 HTTP 监控器的示例curl https://api.openstatus.dev/rpc/openstatus.monitor.v1.MonitorService/CreateHTTPMonitor \ -X POST \ -H Content-Type: application/json \ -H x-openstatus-key: $OPENSTATUS_API_KEY \ -d { monitor: { name: Production API Health Check, url: https://api.example.com/health, periodicity: PERIODICITY_1M, method: HTTP_METHOD_GET, timeout: 45000, retry: 3, headers: [{ key: Authorization, value: Bearer token123 }], regions: [REGION_FLY_IAD, REGION_FLY_FRA], active: true } }创建成功后返回带 ID 的HTTPMonitorUpdateHTTPMonitor以id 可选的monitor字段实现部分更新TriggerMonitor立即在所有配置区域跑一次真实检查proto 中注明受 synthetic-checks 配额限流适合验证配置或排障。聚合指标与响应日志GetMonitorSummarytime_range支持TIME_RANGE_1D/TIME_RANGE_7D/TIME_RANGE_14D可按区域过滤最多 28 项。返回total_successful/total_degraded/total_failed计数、p50/p75/p90/p95/p99延迟分位数毫秒以及last_ping_at时间戳。ListMonitorHTTPResponseLogs分页查询 14 天窗口内的响应日志每条记录含latency、status_code、request_statusSUCCESS/ERROR/DEGRADED、region、triggerCRON 或 API 触发、cron_timestamp与timestamp。GetMonitorHTTPResponseLog返回单次检查的完整详情包括HTTPResponseLogTiming五段耗时dns/connect/tls/ttfb/transfer、脱敏后的响应头headers、错误信息与序列化的断言配置assertions是定位慢请求与断言失败的最有力工具。状态页管理从建页到组件、分组与订阅StatusPageService定义于 status_page/v1/service.proto是 API 中 RPC 最丰富的服务可分为四组页面 CRUDCreateStatusPage、GetStatusPage、ListStatusPages分页limit 1100 默认 50、UpdateStatusPage、DeleteStatusPage。创建状态页的核心字段与校验规则CreateStatusPageRequest字段约束说明title1256页面标题必填slug正则^[a-z0-9](?:-[a-z0-9])*$URL 友好别名小写字母数字加连字符必填description最大 1024描述homepage_url/contact_urlURL主页与联系页default_locale/locales枚举默认语言与启用语言custom_domain最大 256自定义域名theme枚举视觉主题默认SYSTEMaccess_type枚举访问控制默认PUBLICpassword1256当access_type PASSWORD_PROTECTED时必填auth_email_domains数组当access_type AUTHENTICATED时使用的邮箱域名白名单allowed_ip_ranges字符串当access_type IP_RESTRICTED时必填逗号分隔的 IPv4 CIDRallow_indexbool是否允许搜索引擎收录默认 truecustom_theme对象按模式覆盖 CSS 变量仅接受受支持变量名需要 custom-theme 套餐组件与分组AddMonitorComponent把监控器挂到状态页name缺省取监控器名、AddStaticComponent纯静态组件需name、RemoveComponent、UpdateComponent、GetPageComponent、CreateComponentGroup/DeleteComponentGroup/UpdateComponentGroup分组支持default_open控制默认展开。订阅者这里有两种互补的订阅 RPC选哪个取决于谁发起的订阅SubscribeToPage终端用户自助订阅带双重 opt-in 验证——系统发送验证邮件用户确认后订阅才生效若该邮箱曾退订则复用原有记录重新激活而非重复创建。CreatePageSubscription运营方代建订阅免验证立即生效适用于已在线下确认同意的伙伴/厂商场景支持 email 与 webhook 渠道Slack/Discord 的 webhook URL 按前缀自动识别 payload 风格也可附带自定义头仍会生成管理 Token 供对方通过/manage/{token}与/unsubscribe/{token}自助管理。另有UnsubscribeFromPage按 email 或订阅者 ID与ListSubscribers支持include_unsubscribed。内容与聚合状态GetStatusPageContent按id需认证、限定工作区或slug公开访问要求页面access_type PUBLIC返回页面完整内容——含组件、分组、进行中的状态报告与已排期维护。GetOverallStatus返回聚合状态与各组件状态聚合优先级为degraded进行中的状态报告 maintenance进行中的维护窗口 operational。GetStatusPageOverview一次认证调用取回页面、富配置、组件、分组、报告、维护与计算出的状态。GetPageComponentDailySummary按天返回ok/degraded/error/count桶并合并事件时间线最多 45 天是渲染状态条与 uptime 日历的单一事实来源同样支持 id 与 slug 两种访问路径。事故报告与维护窗口把故障响应写成代码状态报告Status ReportStatusReportService定义于 status_report/v1/service.proto其生命周期状态枚举在 status_report.proto 中INVESTIGATING→IDENTIFIED→MONITORING→RESOLVED。主要 RPCCreateStatusReport、GetStatusReport含完整更新时间线、ListStatusReports、UpdateStatusReport、DeleteStatusReport、AddStatusReportUpdate。创建事故报告的示例notify为 true 时将通过邮件通知页面订阅者curl https://api.openstatus.dev/rpc/openstatus.status_report.v1.StatusReportService/CreateStatusReport \ -X POST \ -H Content-Type: application/json \ -H x-openstatus-key: $OPENSTATUS_API_KEY \ -d { title: API Degradation Investigation, status: STATUS_REPORT_STATUS_INVESTIGATING, message: We are investigating reports of increased API latency., date: 2024-03-15T10:30:00Z, page_id: pg_xxxxxxxx, notify: true }date必须为 RFC 3339 格式正则校验^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[-]\d{2}:\d{2})$。AddStatusReportUpdate在追加时间线条目的同时把报告推进到指定状态component_impacts字段PAGE_COMPONENT_IMPACT_DEGRADED_PERFORMANCE/PARTIAL_OUTAGE/MAJOR_OUTAGE等允许为每个组件声明受影响程度。维护窗口MaintenanceMaintenanceService定义于 maintenance/v1/service.protoCreateMaintenance、GetMaintenance、ListMaintenances、UpdateMaintenance、DeleteMaintenance。curl https://api.openstatus.dev/rpc/openstatus.maintenance.v1.MaintenanceService/CreateMaintenance \ -X POST \ -H Content-Type: application/json \ -H x-openstatus-key: $OPENSTATUS_API_KEY \ -d { title: Database Migration, message: Scheduled maintenance for the primary database., from: 2024-03-01T02:00:00Z, to: 2024-03-01T06:00:00Z, page_id: pg_xxxxxxxx }from/to均为必填的 RFC 3339 时间维护窗口会以maintenance状态参与GetOverallStatus的聚合优先级计算。其他服务通知、私有节点与健康检查NotificationServicenotification/v1/service.proto通知渠道 CRUD另有SendTestNotification发送测试通知与CheckNotificationLimit检查渠道配额。PrivateLocationServiceprivate_location/v1/service.proto私有节点的创建、查询、列表、更新与删除用于在自有基础设施中运行探针。HealthServicehealth/v1/health.proto提供Check健康检查 RPC。Schema 与 SDKOpenAPI 描述文件机器可读的 API 描述位于https://api.openstatus.dev/openapi同时提供/openapi.yaml、/openapi.json与/openapi-v1.json三种形式。服务端实现在 apps/server/src/routes/openapi.ts文档公开、无需认证并带有Access-Control-Allow-Origin: *与Cache-Control: public, max-age3600方便浏览器端与 Agent 直接抓取。Node SDKopenstatus/sdk-node可从 jsr.io 获取提供类型化客户端省去手写 curl。Terraform Provider官方工具链见 openstatus.dev 的 tooling 页面支持以声明式资源管理监控器等对象。类型化客户端源码本仓库已生成 TypeScript 客户端见 packages/proto/gen/ts可供自建集成直接参考调用签名。错误处理Connect 层统一使用标准错误码并携带 GoogleErrorInfo结构化详情依据 ConnectRPC 规范说明错误码典型场景NOT_FOUND监控器/状态页 ID 不存在INVALID_ARGUMENT参数未通过 protovalidate 校验如 slug 非法、limit 越界PERMISSION_DENIED凭据无权限访问目标资源UNAUTHENTICATED缺少或错误的x-openstatus-keyRESOURCE_EXHAUSTED触发限流或配额如TriggerMonitor的合成检查配额INTERNAL/UNAVAILABLE服务端内部错误或暂不可用ErrorInfo的domain为openstatus.comreason为机器可读的错误原因如MONITOR_NOT_FOUNDmetadata中携带requestId、resourceId等上下文便于日志关联与排障。所有纯读 RPC 都声明了NO_SIDE_EFFECTS幂等级别可安全重试变更类 RPC 则被完整写入工作区审计日志可通过apiKey.id追溯到具体凭据。API 还是 MCP何时选择openstatus 同时提供两条自动化通路选型取决于使用场景MCP 的完整说明见 openstatus-mcp Skill 文档场景推荐原因程序化集成、CI/CD、定时脚本、自建系统API以x-openstatus-key头认证POST JSON 即可无额外依赖同一个 Key 同时可用于 CLI、REST API 与 Terraform provider聊天形态的 AI 客户端Claude、Cursor、Codex 等MCP 服务器https://api.openstatus.dev/mcp支持 OAuthPKCE与 API Key 两种凭据按工作区与读写范围授权提供list_*/get_*与变更工具适合对话式查询与发布操作两者的数据面完全一致同样的工作区、同样的审计日志、同样的底层服务。对多数工程化场景直接调用 API 更加可控——一条 curl、一个 Node SDK 调用即可完成监控器创建、事故发布或维护排期让整个监控与状态管理流程真正成为代码的一部分。【免费下载链接】openstatus Status page with uptime monitoring API monitoring as code 项目地址: https://gitcode.com/GitHub_Trending/op/openstatus创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考