Corsair Grafana 插件接入指南：用 API Key 打通 Grafana 观测数据、Loki 日志与 Mimir 集群状态

Corsair Grafana 插件接入指南用 API Key 打通 Grafana 观测数据、Loki 日志与 Mimir 集群状态【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair本指南以 packages/grafana/README.md 为骨架完整讲解corsair-dev/grafana这一 Corsair 官方 Grafana 插件的安装、认证、11 个内置端点、权限配置、错误重试与数据持久化机制并深入源码验证每个端点对应的真实 Grafana API 路径。读完你将能在自己的 Corsair 应用中一键接入 Grafana让 AI Agent 安全地查询公共仪表盘、写入 Loki 日志、检查 Mimir 哈希环状态与 Enterprise 许可证状态。安装与依赖corsair-dev/grafana是 Corsair 生态中的 Grafana 连接插件通过 pnpm 安装pnpm add corsair-dev/grafana从 packages/grafana/package.json 可以看到它声明了两个 peerDependenciescorsair 0.1.0Corsair 核心运行时提供插件上下文、认证、请求、日志等基础设施zod ^4.1.13用于端点输入/输出 schema 的运行时校验。插件使用 TypeScript 编写并以 ESM 形式发布type: module包入口为dist/index.js同时通过exports[.][dev-source]暴露源码路径方便开发调试。安装完成后用corsair核心包中注册插件的方式将其挂载到你的 Corsair 应用中即可。快速接入注册 Grafana 插件在 packages/grafana/index.ts 中插件以工厂函数grafana(options)的形式导出。最小接入方式如下import { grafana } from corsair-dev/grafana; export const grafanaPlugin grafana({ authType: api_key, key: process.env.GRAFANA_SERVICE_ACCOUNT_TOKEN, grafanaUrl: https://example.grafana.net, });GrafanaPluginOptions支持的完整配置项如下类型定义见 packages/grafana/index.ts配置项类型说明authTypeapi_key认证方式当前固定为api_key未传时默认为api_keykeystringGrafana Service Account Token作为 Bearer Token 使用也可不传改由运行时通过corsair auth动态获取grafanaUrlstringGrafana 实例基础 URL例如https://example.grafana.nethooks插件钩子透传给 Corsair 的插件生命周期钩子webhookHooks插件钩子Grafana 插件未定义 webhook保留字段errorHandlersCorsairErrorHandler自定义错误处理器会与插件内置错误处理器合并permissions权限配置控制 AI Agent 可调用的端点使用端点树的点分路径路径非法会触发类型错误在插件内部grafana()工厂把端点组织为嵌套结构logs、health、status、ring、storeGateway、saml、dashboards、jwks并一次性注册了 endpointMeta风险等级与描述、endpointSchemaszod 输入输出校验与错误处理器。插件 ID 与认证配置插件 ID 固定为grafana。值得注意的是一段自定义认证配置packages/grafana/index.tsexport const grafanaAuthConfig { api_key: { account: [grafana_url, org_id] as const, }, } as const satisfies PluginAuthConfig;这意味着通过corsair auth为租户录入凭证时除了 API Key 本身还可以附带grafana_url与org_id两个账户级字段。grafana_url会在每个端点的实现中被读取ctx.keys.get_grafana_url()从而让实例 URL 随租户凭证存储而不是硬编码在插件配置里——这是多租户场景下避免写死 URL 的关键设计。org_id同样被预留为账户字段便于区分不同 Grafana 组织。认证机制API Key 与 Service Account TokenREADME 明确指出本插件认证方式为API key并说明Corsair prompts your tenant for credentials on first use即租户首次使用时 Corsair 会提示录入凭证。从源码keyBuilderpackages/grafana/index.ts可以看到凭证解析的完整逻辑若请求来源为webhook直接返回空字符串Grafana 插件没有 webhook若请求来源为endpoint且插件配置了options.key优先使用配置中的 Service Account Token否则从ctx.keys.get_api_key()读取租户在corsair auth中录入的 API Key读取失败时抛出AuthMissingError(grafana, api_key)提示用户补充凭证。传输安全强制 HTTPS底层客户端 packages/grafana/client.ts 在发起任何请求前都会执行assertHttpsGrafanaBaseUrl剥离 URL 尾部的斜杠、校验 URL 合法性并且只允许https:协议否则直接抛出GrafanaAPIError拒绝将 Bearer Token 发送到非 HTTPS 地址。这是针对令牌泄露风险的一道硬性防线。两种请求通道客户端提供两个底层函数makeGrafanaRequest发送 JSON 请求GET/POST/PUT/DELETE/PATCH自动附加Authorization: Bearer token与Content-Type: application/json用于 health、status 等标准 REST 接口makeGrafanaRawRequest发送原始请求并返回{ content, content_type, status_code }用于返回 HTML 页面或表单编码体的端点如 Mimir ring 状态页、SAML ACS、Loki OTLP 写入POST 时支持自定义contentType。此外GRAFANA_RATE_LIMIT_CONFIGpackages/grafana/client.ts内置了速率限制处理启用重试、最多 3 次、初始退避 1s、指数退避倍数 2并读取Retry-After响应头。端点总览插件共暴露11 个端点覆盖 Grafana 的观测、鉴权与 Mimir 集群运维能力。以下是 README 中的端点速查表操作Operation ID风险描述dashboards.queryPublicgrafana.api.dashboards.queryPublicread查询公共 Grafana 仪表盘上的面板health.getgrafana.api.health.getread检查 Grafana 服务器健康状态与数据库连通性jwks.retrievegrafana.api.jwks.retrieveread获取用于令牌验证的 JWKS 公钥logs.createOtlpgrafana.api.logs.createOtlpwrite通过 OTLP v1 向 Grafana Loki 发送日志ring.getDistributorHaTrackergrafana.api.ring.getDistributorHaTrackerread获取 distributor HA tracker ring 状态ring.getIndexGatewaygrafana.api.ring.getIndexGatewayread获取 index gateway 哈希环状态ring.getOverridesExportergrafana.api.ring.getOverridesExporterread获取 overrides-exporter 哈希环状态ring.getRulergrafana.api.ring.getRulerread获取 Grafana Mimir 的 ruler ring 状态saml.postAcsgrafana.api.saml.postAcswrite处理 SAML Assertion Consumer Service 认证响应status.getgrafana.api.status.getread检查 Grafana Enterprise 许可证可用性storeGateway.getTenantsgrafana.api.storeGateway.getTenantsread列出 store-gateway 存储中拥有块的租户其中read风险端点 9 个、write风险端点 2 个logs.createOtlp与saml.postAcs。风险等级在grafanaEndpointMeta中集中声明packages/grafana/index.tsCorsair 权限系统会据此约束 Agent 行为。所有端点的输入/输出 schema 定义在 packages/grafana/endpoints/types.ts并在 packages/grafana/endpoints/index.ts 中聚合导出。下面按功能域深入每个端点的实现细节与真实 API 路径。dashboards.queryPublic查询公共仪表盘面板对应 Grafana 公共仪表盘 API实现位于 packages/grafana/endpoints/dashboards.ts。输入参数来自DashboardsQueryPublicInputSchema参数类型必填说明access_tokenstring是公共仪表盘的访问令牌panel_idnumber是要查询的面板 IDfrom/tostring是时间范围intervalMsnumber否采样间隔毫秒maxDataPointsnumber否最大数据点数base_url_overridestring否覆盖默认 Grafana 实例 URL实现通过makeGrafanaRawRequest以 POST 方式请求/api/public/dashboards/{access_token}/panels/{panel_id}/querypackages/grafana/endpoints/dashboards.ts并尝试将响应解析为 JSON取results字段若返回的是 HTML 错误页则回退为把原始内容放入message字段。查询成功后结果会以${access_token}-${panel_id}为唯一键 upsert 到数据库的dashboardQueries表并记录grafana.dashboards.queryPublic事件日志。health.get 与 status.get健康与许可证检查两个端点都调用 JSON 通道实现在 packages/grafana/endpoints/health.tshealth.get请求/api/health返回{ version, commit, database, enterpriseCommit }等字段用于判断 Grafana 服务器与底层数据库是否健康status.get请求/api/licensing/check通过raw.hasLicense true或licenseExpiry Date.now() / 1000计算license_available布尔值用于判断 Enterprise 许可证是否有效。两者的结果都会写入healthStatus表status.get在已有记录上合并licenseAvailable字段便于后续审计与状态追溯。logs.createOtlp向 Loki 写入 OTLP 日志这是本插件唯一的日志写入端点实现于 packages/grafana/endpoints/logs.ts。它通过原始请求通道 POST/otlp/v1/logs请求体为 OTLP 的resourceLogs结构ResourceLog → ScopeLog → LogRecord每层 schema 见 packages/grafana/endpoints/types.ts。成功2xx后插件会将日志记录扁平化持久化把 resource attributes 展平为字符串键值对、提取scope.name与scope.version、以body.stringValue优先存储日志正文否则 JSON 序列化整个 body并用crypto.randomUUID()生成唯一 ID 写入logs表。ring.* 与 storeGateway.getTenantsMimir 集群状态四个ring.*端点与storeGateway.getTenants面向 Grafana Mimir 的哈希环运维场景实现见 packages/grafana/endpoints/ring.ts全部通过原始请求通道返回 HTML 页面端点请求路径数据落库 keyring.getDistributorHaTracker/distributor/ha-trackerdistributor-ha-trackerring.getIndexGateway/index-gateway/ringindex-gatewayring.getOverridesExporter/overrides-exporter/ringoverrides-exporterring.getRuler/ruler/ringrulerstoreGateway.getTenants/store-gateway/tenantsstore-gateway-tenants响应中html_content或content连同content_type、status_code一起写入ringStatus表。这类端点让 Agent 能快速巡检 Mimir 各组件哈希环的健康状态、租户块分布等信息是监控告警类 Agent 的高价值能力。saml.postAcs处理 SAML 认证响应write风险端点实现于 packages/grafana/endpoints/auth.ts。输入为saml_response必填与relay_state可选。实现将参数编码为application/x-www-form-urlencoded表单POST 到/login/saml/acspackages/grafana/endpoints/auth.ts。返回结果会判断是否 302 重定向并尝试从返回内容中正则提取meta ... url...形式的跳转地址作为location。每次处理都会以saml-${saml_response 前 16 位}为稳定 session ID 写入samlSessions表。jwks.retrieve获取令牌验证公钥同样实现于 packages/grafana/endpoints/auth.ts该端点按顺序探测三个已知 JWKS 路径直到拿到 200 响应为止/api/signing-keys/jwks/.well-known/jwks.json/api/jwks拿到 JSON 后解析出keys数组JWKS 中每个 key 的Key密钥材料、Use、Algorithm、Certificates等字段会展开存入jwksKeys表。这为验证 Grafana 签发的令牌提供了公钥获取通道。权限配置限制 Agent 可调用的端点插件通过permissions选项控制 AI Agent 的调用边界类型定义明确指出Overrides use dot-notation paths from the Grafana endpoint tree — invalid paths are type errors。由于权限路径是类型化的写错端点路径会在编译期直接报错而不是留到运行时。示例grafana({ key: process.env.GRAFANA_SERVICE_ACCOUNT_TOKEN, permissions: { // 只允许读取健康状态禁止写入 health.get: true, logs.createOtlp: false, }, });结合 endpointMeta 中的风险等级packages/grafana/index.ts可以实现默认只读、按需开放写操作的精细化授权策略降低 Agent 误操作风险。错误处理与重试策略插件内置了一套完整的错误处理器定义在 packages/grafana/error-handlers.ts覆盖六类场景错误类型匹配条件处理策略RATE_LIMIT_ERRORHTTP 429 或消息含 rate_limited/ratelimited/429最多重试 5 次优先采用Retry-After头AUTH_ERRORHTTP 401 或 unauthorized/invalid token/token expired 等不重试提示检查 Service Account TokenPERMISSION_ERRORHTTP 403 或 forbidden/permission denied 等不重试NOT_FOUND_ERRORHTTP 404 或 not found不重试NETWORK_ERROR消息含 network/connection/ECONNREFUSED/ETIMEDOUT 等最多重试 3 次DEFAULT兜底匹配一切不重试记录 unhandled error开发者可以通过grafana({ errorHandlers })传入自定义处理器插件会在构造时用{ ...errorHandlers, ...options.errorHandlers }合并packages/grafana/index.ts自定义项覆盖同名内置项。数据持久化插件内置的数据库表插件的 schema 定义在 packages/grafana/schema/database.ts包含 6 张表对应的 zod schema表用途主要字段healthStatus健康与许可证状态version、commit、database、licenseAvailable、checkedAtlogsLoki 摄入的日志记录timeUnixNano、severityText、body、traceId、spanId、resource、scopedashboardQueries公共仪表盘查询历史accessToken、panelId、from、to、results、queriedAtringStatusMimir 哈希环状态快照content、contentType、statusCode、fetchedAtjwksKeysJWKS 公钥记录use、algorithm、certificates、keyMaterialsamlSessionsSAML ACS 处理记录statusCode、location、message、successful所有表均以.loose()声明允许保存 Grafana 返回的未知扩展字段。端点在成功时通过ctx.db.xxx.upsertByEntityId写入失败时仅返回错误而不会污染历史数据——这种成功才落库的约定保证了数据库里只保留有效观测记录。测试与验证插件提供了基于 Jest 的测试见 packages/grafana/api.test.ts 与 packages/grafana/client.test.ts。api.test.ts是针对真实 Grafana 实例的集成测试依赖以下环境变量GRAFANA_BEARER_TOKENService Account TokenGRAFANA_URLGrafana 实例地址GRAFANA_PUBLIC_DASHBOARD_ACCESS_TOKEN/GRAFANA_PUBLIC_DASHBOARD_PANEL_ID公共仪表盘测试令牌与面板 ID可选。测试逐一调用 11 个端点并用GrafanaEndpointOutputSchemas.*校验返回结构与声明类型一致client.test.ts则覆盖客户端请求构造与 HTTPS 校验逻辑。本地可通过pnpm test运行见 packages/grafana/package.json。Webhooks 与许可证README 明确说明 Grafana 插件无 webhook 触发No webhooks。源码中grafanaWebhooksNested为空对象、pluginWebhookMatcher恒返回falsepackages/grafana/index.tskeyBuilder对 webhook 来源直接返回空字符串。因此本插件仅需处理出站 API 调用无需配置入站 webhook 接收地址。插件遵循Apache-2.0开源许可发布配置元数据displayName、description见 packages/grafana/plugin-docs.yaml可用于在 Corsair Hub 中展示。总结corsair-dev/grafana以极简的接入方式一条pnpm add 一个grafana()工厂调用为 Corsair 应用补全了 Grafana 观测能力读取健康与许可证状态、查询公共仪表盘、向 Loki 写入 OTLP 日志、巡检 Mimir 哈希环、处理 SAML 与 JWKS 令牌流程。其强制的 HTTPS 传输、类型化权限路径、内置错误重试与成功才落库的持久化约定使它适合作为多租户 AI Agent 的 Grafana 数据网关相关实现均可继续在 packages/grafana 目录下深入阅读。【免费下载链接】corsairConnect your users to their apps项目地址: https://gitcode.com/GitHub_Trending/corsa/corsair创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考