azure-resource-visualizer

概览

什么是 azure-resource-visualizer？

azure-resource-visualizer 是一个聚焦 Azure 的可视化技能，用于分析你的 Azure 资源组，并将其转换为清晰、易读的架构文档。它会检查资源本身、配置和相互关系，然后生成详细的 Mermaid 图和 markdown 文件，描述你的云拓扑结构。

与其手动拼凑虚拟网络、子网、App Services、数据库和安全组件之间的关系，不如使用 azure-resource-visualizer 自动完成发现和制图，让你随时掌握环境的最新结构。

核心能力

• 资源组发现 – 在未指定资源组时，列出并协助你选择 Azure 资源组。
• 深度资源分析 – 分析资源组内资源、其配置和相互依赖关系。
• 关系映射 – 识别并记录计算、网络、数据和安全资源之间的连接关系。
• Mermaid 图生成 – 输出完整且语法正确的 Mermaid 图，可直接用于 markdown、文档站点或 wiki。
• 架构文档生成 – 生成 markdown 页面，可包含清单、高层概要及内嵌图表。

适合哪些人使用？

如果你符合以下身份之一，可以考虑使用 azure-resource-visualizer：

• 云架构师：需要快速生成用于评审和设计文档的可视化架构图。
• 开发者或 DevOps 工程师：想清楚了解某个资源组内服务之间是如何联通的。
• 平台/基础设施工程师：希望在多个订阅和团队之间统一文档标准。
• 安全或运维工程师：需要一张清晰的网络流向和依赖关系图。

它最适合已经在 Azure 上部署了资源、需要洞察、文档或入职材料的场景，而不是仅在纸面上做设计规划的时候。

能解决哪些问题

• 花费大量时间在制图工具中手工绘制 Azure 架构图。
• 难以弄清大型资源组中各资源之间的关系。
• 架构文档长期不更新，与实际部署情况严重不符。
• 缺乏针对每个资源组的统一、可审阅的 markdown 文档。

什么时候适合（或不适合）使用 azure-resource-visualizer

适合使用的场景：

• 你希望对现有 Azure 基础设施进行数据可视化和报告。
• 你需要将 Mermaid 图 集成到 markdown、代码仓库或内部文档门户中。
• 你正在使用 Azure Resource Graph 或 az 来查询资源元数据。

不太适合的场景：

• 你需要一个工具来创建或变更 Azure 资源（本技能仅用于分析和可视化，不负责部署）。
• 你需要成本分析、性能监控或安全扫描——这些都不在本技能的覆盖范围内。
• 你无法访问 Azure 订阅元数据，或无法运行 az / Azure Resource Graph 查询。

使用方式

前置条件

在使用 azure-resource-visualizer 之前，请确保你已具备：

• 一份启用中的 Azure 订阅，并包含一个或多个资源组。
• 有权限访问并查询这些订阅中的资源。
• 已安装并登录 Azure CLI (az)，尤其是当你的环境依赖 CLI 进行资源发现时。
• 如计划使用 Azure Resource Graph 查询，还需要安装 Resource Graph CLI 扩展：
  • az extension add --name resource-graph

满足这些前置条件后，本技能（或使用该技能的 agent）就能列出资源组并检查资源及其关系。

安装 azure-resource-visualizer 技能

要从 microsoft/azure-skills 仓库中添加 azure-resource-visualizer，请使用 skills CLI：

npx skills add https://github.com/microsoft/azure-skills --skill azure-resource-visualizer

该命令会将技能定义及相关资源（示例、模板和参考文档）拉取到本地 skills 目录，供你的 agent 或工作流调用。

了解随技能提供的文件

安装完成后，查看 skills/azure-resource-visualizer 下这些关键文件和文件夹：

• SKILL.md – 技能的核心定义，包括职责说明和工作流指引。
• assets/example-diagram.md – 一个完整的 Mermaid 示例图，展示典型 Azure 资源和分层结构的表示方式。
• assets/template-architecture.md – 一个完整架构报告的 markdown 模板，包含资源清单及图表占位部分。
• references/azure-resource-graph.md – 关于使用 Azure Resource Graph 进行大规模资源发现的指南和 KQL 示例。

这些文件展示了“理想输出”的样子，也说明了如何组织自己的架构文档。

典型工作流：从资源组到架构图

步骤 1：选择或发现资源组

如果用户尚未指定资源组名称，本技能的工作流通常会：

1. 使用可用工具（通常是 az 或 Azure Resource Graph）列出资源组。
2. 以编号列表形式呈现名称和位置。
3. 询问用户要分析哪个资源组。

如果资源组已知，则可跳过发现阶段，直接进行分析。

步骤 2：发现资源及其关系

选定资源组后，azure-resource-visualizer 会重点完成：

• 列出组内所有资源（类型、名称、位置以及如 SKU 等相关配置）。
• 识别资源之间的连接关系，例如：某个 App Service 使用了哪些子网、某个 Function App 访问了哪些数据库、某些身份如何访问 Key Vault 等。

常用工具包括：

• 带 --resource-group 过滤条件的 az 命令。
• 使用类似 references/azure-resource-graph.md 中 KQL 模式的 az graph query。

步骤 3：生成 Mermaid 架构图

技能会将分析结果转换为一张 Mermaid 架构图。assets/example-diagram.md 中的示例展示了整体风格：

• 使用 subgraph 做分层分组，例如：
  • Network Layer（VNets、子网、NSGs）
  • Compute Layer（App Service plans、App Services、Functions）
  • Data Layer（databases、storage）
  • Security & Identity（Key Vault、managed identities）
• 使用详细节点标签展示地址范围、SKU、运行时版本等关键配置。
• 使用带说明文字的边标注关系，例如 "HTTPS requests"、"SQL connection" 或 "Blob/Queue access"。

生成的图是标准 Mermaid 语法，可在 GitHub markdown、文档生成器和多种图表预览工具中直接使用。

步骤 4：编写 markdown 架构报告

以 assets/template-architecture.md 为起点，为每个资源组创建结构化报告：

• 在页头填写 订阅、区域、资源数量和生成日期。
• 撰写简短的概览，说明解决方案的用途和关键组件。
• 在 Resource Inventory 表中填入资源名称、类型、SKU、位置和备注。
• 将生成的 Mermaid 图粘贴到 Architecture Diagram 部分。
• 根据发现的关系补充 Network Architecture、Data Flow、Identity & Access 和 Dependencies 描述。
• 记录备注与建议（Notes & Recommendations），包括后续优化或潜在风险。

这样就形成了一套可在多个团队或订阅间复用的报告模式。

示例使用场景

• 新成员入职 – 在核心生产资源组上运行 azure-resource-visualizer，并分享生成的 markdown，让新同事快速熟悉系统结构。
• 变更前评审 – 在进行基础设施变更前，为目标资源组生成架构图，以了解依赖关系和潜在影响范围。
• 架构文档更新 – 定期重新运行技能，更新图表和清单，使文档与线上环境保持一致。

常见问题（FAQ）

azure-resource-visualizer 会部署或修改 Azure 资源吗？

不会。azure-resource-visualizer 专注于分析、可视化和文档化。它通过 az 和 Azure Resource Graph 等查询工具读取现有 Azure 资源，并输出 Mermaid 图和 markdown，不会创建、更新或删除任何资源。

azure-resource-visualizer 依赖哪些工具？

本技能旨在与现有 Azure 工具配合使用，而不是替代它们。典型情况下，它依赖：

• Azure CLI (az) 用于列出资源组和资源。
• 可选的 Azure Resource Graph（az graph query）用于快速跨订阅查询，如 references/azure-resource-graph.md 中的示例所示。

具体使用方式取决于你的 agent 或工作流的接入方式，但通常需要安装并完成 az 的身份认证。

azure-resource-visualizer 能跨多个订阅工作吗？

可以，只要你的环境和查询配置支持跨订阅发现。通过 Azure Resource Graph，可以跨多个订阅查询资源，再将分析范围限制在某个或某几个资源组内。无论资源组属于哪个订阅，本技能的职责都围绕你选定的资源组展开。

azure-resource-visualizer 会生成什么类型的图表？

azure-resource-visualizer 会生成 基于 Mermaid 的架构图。这些图表通常：

• 使用分层的 subgraph 部分（Network、Compute、Data、Security & Identity）。
• 包含带关键属性标签的节点（例如 VNet 地址空间、SKU、运行时等）。
• 使用带方向的边，并附带文字说明组件间如何交互。

输出是标准的 Mermaid 代码，可以直接嵌入 markdown 文件、GitHub README 或支持 Mermaid 的文档站点中。

我可以自定义生成的文档吗？

可以。assets/template-architecture.md 文件就是专门为模板化而编写的。你可以：

• 调整文档结构（增删表格、标题或备注部分）。
• 统一语言风格和格式以符合组织规范。
• 将该模板作为 agent 或脚本自动生成报告的基础。

本技能的目标是提供一个一致的结构，如何根据自身流程进行调整则完全由你决定。

azure-resource-visualizer 适合非常小的测试环境吗？

它可以用于任何规模的资源组，但价值在资源和关系较多、手工制图变得繁琐时更为明显。对于仅包含单个测试 VM 或极简 demo 的场景，使用它的收益可能有限；而对于多层应用、共享服务和复杂网络环境，它会非常有帮助。

我应该多久运行一次 azure-resource-visualizer？

在以下场景都可以考虑运行：

• 完成重要的基础设施变更之后。
• 架构评审或审计之前。
• 按固定频率（例如每月或每季度）运行，以保持文档与实际环境同步。

由于本技能是只读、基于查询的方式工作，可以根据需要随时重复运行，安全无副作用。

哪里可以看到具体输出示例？

在技能目录中：

• assets/example-diagram.md 包含一份完整的 Mermaid 架构图示例，展示分层结构和带注释的关系。
• assets/template-architecture.md 展示了如何围绕该图组织一份完整的架构报告。

阅读这些文件，是了解 azure-resource-visualizer 能为你的 Azure 资源组生成什么成果的最快方式。