OpenSRE 60+ 集成如何运转：新手看懂目录、注册表与选择器的完整指南

OpenSRE 60+ 集成如何运转：新手看懂目录、注册表与选择器的完整指南

【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre

OpenSRE是一个构建 AI SRE Agent 的开源工具包（The open source toolkit for the AI era），它能连接 Grafana、Datadog、AWS、Sentry、Slack 等 60 多个可观测性与协作平台。这么多集成是如何被统一管理、按需启用的？本文带你拆解 integrations/ 模块下的三大核心组件：目录（Catalog）、注册表（Registry）与选择器（Selectors）的设计思路，无需阅读大量代码即可理解其运转逻辑。

为什么需要一套"集成管理框架"？

当你只连接一个监控系统时，直接写死配置就够了。但 OpenSRE 要同时支持 60+ 平台，而且每个平台还可能有多个实例（比如生产环境和测试环境各有一个 Grafana）。这带来三个问题：

• 📋怎么知道哪些集成可用？—— 需要一个"总目录"
• 🔑怎么把零散配置变成统一格式？—— 需要一个"分类/解析流程"
• 🎯怎么从多个实例里挑出对的那一个？—— 需要一个"选择器"

OpenSRE 的答案就是下面这套三层结构，分别对应 integrations/catalog.py、integrations/registry.py 和 integrations/selectors.py。

第一层：注册表（Registry）——所有集成的"户口本"

打开 integrations/registry.py，你会看到一个叫IntegrationSpec的数据结构，它是每个集成的"户口卡"，记录了：

注册表还有两个巧妙的设计：

1. 所有查询表都是"原地更新"。文件底部的INTEGRATION_SPECS_BY_SERVICE、SUPPORTED_VERIFY_SERVICES等查找表在插件注册后会就地修改而不是整体替换（见 _rebuild_registry）。这样其他模块已经引用的表对象不会失效，避免"插件注册了但查不到"的隐蔽 bug。

2. 插件不能抢注内置名称。第三方包可以通过 register_integration_spec 注册自己的集成，但如果它想占用grafana、k8s这类已被内置集成（含别名）认领的键，注册会直接报错。这防止了插件悄悄"劫持"一个官方集成的配置与验证流程。

第二层：目录（Catalog）——把零散配置"翻译"成统一格式

集成的凭证有两个来源：本地存储文件~/.opensre/integrations.json（由 integrations/store.py 管理）和环境变量。integrations/catalog.py 是对外暴露的门面，把两条来源合并、分类后交给各功能使用。

核心流程由 resolve_effective_integrations 串起四步：

1. 读取：从本地存储与环境变量各自加载集成记录；
2. 合并：merge_local_integrations 按服务名去重，本地存储的条目优先；
3. 分类：classify_integrations 把原始凭证交给各服务的分类器，输出统一的结构化配置；
4. 解析：生成"生效集成（effective integrations）"视图，并标注每条配置来自local env还是local store。

几个值得注意的细节：

• 多实例统一输出：分类结果里，resolved[service]始终是默认（第一个）实例的扁平配置，保证老代码不受影响；当存在多个实例时，会额外挂一个_all_{service}_instances键保存全部实例（见 selectors.py 顶部注释）。
• 健康检查不骗人：configured_integration_health 会区分"存在"和"可用"——比如一个 Hosted MCP 记录只填了 URL 没填 API Token，就会被标记为incomplete，欢迎横幅不会让你误以为它已连通。
• 严格模型兜底：integrations/effective_models.py 用 Pydantic 声明了每个内置集成的字段，拼写错误能在验证阶段被发现；同时extra="allow"保证仓库外注册的插件集成不会被丢弃。

第三层：选择器（Selectors）——从多个实例中精准取数

假设你配置了两个 Grafana 实例：prod（标签env: prod）和staging。当 Agent 调查生产事故时，应该查哪个？integrations/selectors.py 给出了干净的答案，核心是 select_instance：

按名字找 → 按标签找 → 找不到默认就报错，绝不悄悄回退到默认实例。

这个"宁缺毋滥"的设计很关键：如果用户明确指定了prod却查不到，悄悄改用staging会让 Agent 拿错误环境的数据下结论。配套的辅助函数也很克制：

• get_instances：列出某服务的全部实例，单实例时会自动"合成"一个默认项，让调用方无需区分单/多实例两种情况；
• get_instances_by_tag：按标签批量筛选，适合"查所有env: prod实例"这类场景；
• 所有函数永不修改入参，查不到就返回None或[]。

一次完整查询的数据流回顾

把三层串起来，Agent 每次使用某个集成时的路径是：

1. 注册表回答"这个服务名（或别名）对应哪个集成"；
2. 目录回答"它当前的生效配置是什么、来自哪里、有哪些实例"；
3. 选择器回答"具体该用哪个实例的凭证"。

各平台的真实 API 调用逻辑则分散在 integrations/ 下的子目录中，例如 integrations/grafana/、integrations/aws/、integrations/github/，它们都消费上面三层产出的统一配置。

文件导航：想深入阅读从哪里开始

小结：这套设计教我们什么？

• 元数据集中，逻辑分散：注册表只描述"有哪些集成、它们叫什么、什么顺序"，真正的连接逻辑留在各自子模块，新增集成时改动面最小；
• 单一事实来源：~/.opensre/integrations.json与环境变量合并后有且只有一个"生效视图"，欢迎横幅、健康检查、工具调用看到的永远是同一份状态；
• 向后兼容是显式设计：扁平的默认实例视图 + 严格的严格模型 + 只读的存储迁移，让 60+ 集成和插件生态都能平稳演进。

理解了这三层，你就掌握了 OpenSRE 集成体系的骨架——无论是排查"为什么我的集成没生效"，还是给项目贡献一个新集成，都可以从这里出发。🚀

【免费下载链接】opensreBuild your own AI SRE agents. The open source toolkit for the AI era.项目地址: https://gitcode.com/GitHub_Trending/op/opensre