infrahub-collecting-diagnostics

Infrahub 诊断收集器

概述

当 Infrahub 用户报告问题时，专家 （OpsMill 支持人员或高级工程师）需要一组一致的材料来进行分诊：日志、 配置、版本信息和环境状态。此技能会运行 infrahub-collect， OpsMill 专用的诊断包工具，以生成这组材料。

此技能是围绕二进制文件的指南，而非手工编写的收集器。它不会诊断根本原因， 不会创建 GitHub issue（请改用 infrahub-reporting-issues），也不会修改 Infrahub 状态——infrahub-collect 只会读取数据。

何时使用

在用户提出以下类似问题时触发此技能：

• “Infrahub 出故障了／运行失败／报错了”
• “帮我调试一下”
• “我需要收集日志发给 OpsMill”
• “升级后出了问题”
• “我提出的更改卡住了”
• “UI 一直返回 500 错误”

以下情况不要触发：

• 用户想要提交公开的 GitHub issue （请改用 infrahub-reporting-issues）
• 用户在询问数据相关的运维问题 （例如“X 站点有多少台设备”） （请改用 infrahub-analyzing-data）
• 用户想根据最佳实践审查自己的 schema （请改用 infrahub-auditing-repo）

工作流

按顺序执行以下步骤。两个步骤需要用户确认； 其他步骤均自动执行。

1. 了解问题

如果用户尚未描述问题，请让用户用自己的话说明。暂时不要追问—— 留意产品名称、版本号、错误消息和工作流背景。这些信息有助于确定第 4 步中 要添加哪些 create 标志。

2. 安装并验证

检查二进制文件是否已可用：

infrahub-collect version

如果未安装，请为用户的操作系统／架构安装，然后再次使用 infrahub-collect version （或 infrahub-collect --help）确认。有关确切的安装命令、sudo 和隔离网络 说明，请参阅 rules/install-and-verify.md。

3. 检测环境

infrahub-collect environment detect

如果检测结果不明确（存在多个 Compose 项目， 或使用了非默认的 K8s 命名空间），请运行 infrahub-collect environment list，并使用 --project=<name> 或 --k8s-namespace=<ns> 确定目标环境。 无需 Infrahub API 令牌——此工具会复用 现有的 Docker／kubectl 访问权限。请参阅 rules/deployment-detection.md。

4. 创建诊断包

infrahub-collect create

根据第 1 步中了解的症状添加相应标志—— 性能问题／OOM 问题使用 --benchmark， 数据库操作缓慢／失败时使用 --include-queries， 支持人员要求提供复现材料时使用 --include-backup。完整的症状与标志映射请参阅 rules/create-flags.md。

部署状态不佳时，生成不完整的诊断包是预期情况——create 仍会以 0 退出，并在清单中记录所有收集失败。请原样发送诊断包；不要尝试手动补齐缺失内容。

5. 分享前审核（用户确认）

infrahub-collect 只会屏蔽众所周知的秘密键名 （password／secret／token／key → ********）。它不会清理日志或查询内容，也不会清理存储在其他键名下的秘密信息。 请引导用户检查 bundle/logs/ 和 bundle/server/，查找主机名、IP 地址、客户数据 或存储在非标准键名下的秘密信息，并在分享前取得用户的明确确认。请参阅 rules/review-before-sharing.md。

6. 分享／移交

用户确认诊断包可以安全分享后， 通过支持渠道（Discord、Slack、 电子邮件）发送。如果用户还想提交公开的 GitHub issue，请移交给 infrahub-reporting-issues ——请参阅 rules/cross-link-reporting-issues.md。 如果用户希望在移交给专家之前或取代专家移交，在本地先行分析诊断包 （回溯信息、失败项、已知问题匹配），请继续使用 infrahub-analyzing-diagnostics——此技能只负责收集；分诊由分析器负责。

规则类别

前缀	类别	描述
workflow	工作流	用户确认语义、步骤顺序
install	安装	验证／安装 infrahub-collect 二进制文件
deployment	检测	交由 environment detect/list 处理
create	创建标志	将症状映射到 create 的标志
collection	收集	只读工具，不进行任何修改
bundle	Bundle	磁盘上的 bundle/ 布局（参考）
review	审查	键名掩码的不足；分享前由用户审查
cross-link	交叉链接	移交给 infrahub-reporting-issues

完整索引请参阅 rules/_sections.md。

支持性参考资料

• reference.md — 完整的标志参考、Bundle 布局详情以及环境变量说明。在步骤 2-4 中阅读。
• examples.md — 常见症状类别的端到端演练。
• ../infrahub-common/rules/workflow-information-priority.md -- 优先使用技能内容；遇到确实缺少的信息时（例如删除节点），如何查阅 docs.infrahub.app

反模式

• 运行任何会修改状态的操作。 不要运行 docker compose down，也不要运行 kubectl delete。 infrahub-collect 按设计为只读工具；不要 添加此类命令。
• 不使用二进制文件，而是手动收集信息。 不要手动编写 docker compose logs／kubectl logs 脚本 — infrahub-collect create 已经 覆盖所有服务、副本和日志轮转。
• 跳过分享前审查这一关。 工具只能根据键名进行掩码处理； 无法判断哪些内容对这位特定用户而言属于敏感信息。 只有用户才能批准分享 Bundle。
• 断言根本原因。 此技能生成的是供专家分诊的 Bundle，而非诊断结果。说明收集了哪些内容；由专家得出结论。
• 通过此技能提交 GitHub issue。 这应由 infrahub-reporting-issues 处理。添加交叉链接，不要 重复提交。