byted-volcengine-topology-builder

name	byted-volcengine-topology-builder
description	从火山引擎账号资产快照中尽量全量拉取当前已接入的资源数据，并沉淀为可复用的基础资产数据与拓扑视图。只要用户在做火山引擎账号资产盘点、资源梳理、依赖关系建模、运维底座建设，或者希望为拓扑分析、影响面评估、自动化运维、故障排查等上层场景准备基础数据时，都应该使用这个 skill；当用户提到“看图”“画图”“导图”“导出拓扑图片”时，也要触发。

火山引擎基础资产数据与拓扑 Skill

能力定位

这个 Skill 的职责是构建一层可复用的基础数据，而不是只服务某一个上层分析场景。

• 采集层：尽量全量拉取当前已接入的火山引擎资源资产
• 建模层：把原始快照整理成结构化资产数据和统一关系表达
• 输出层：落盘为 json/md/dot/svg/png 等可复用产物
• 复用层：供拓扑分析、影响面评估、自动化运维、故障排查、资产盘点、依赖梳理等场景继续消费

默认产物

默认会在当前工作空间的 business_topologies/<business_key>/ 下生成：

business_topologies/<business_key>/
  account_assets_snapshot.json
  topology.json
  topology.md
  topology.dot
  topology.svg   # 本地装有 Graphviz 或自动安装成功时生成
  topology.png   # 本地装有 Graphviz 或自动安装成功时生成

说明：

• account_assets_snapshot.json 是原始资产快照，是后续所有分析和重建的基础输入
• topology.json 是结构化关系模型，适合被脚本、agent、分析工具继续消费
• topology.md 是给人快速浏览的文本视图
• topology.dot 会始终生成，便于后续用 Graphviz 或其他工具继续转换
• topology.svg/png 主要用于“看图/导图/给用户展示”

一键流水线

1. 准备当前工作空间内的 .env：

VOLCENGINE_AK=...
VOLCENGINE_SK=...

2. 运行通用入口脚本：

python3 <byted-volcengine-topology-builder-skill>/scripts/run_topology_pipeline.py \
  --workspace-root "$(pwd)" \
  --env-path ./.env \
  --region cn-shanghai \
  --business default-topology

这条流水线默认会依次执行：

• 采集资产快照
• 从快照构建拓扑
• 保存 topology.json/topology.md
• 生成 topology.dot
• 如果本地可用 Graphviz，再继续生成 topology.svg/topology.png

如果本地没有 dot 命令，脚本会先尝试自动安装 Graphviz；安装失败后再降级为仅输出 topology.dot，不会阻塞整个基础数据落盘流程。

常用参数

通用入口脚本 run_topology_pipeline.py 支持：

• --business：业务或资产视图标识
• --region：地域
• --include：需要采集的资源类型，可重复传入或逗号分隔
• --entry：构图时优先使用的入口资源类型，可重复传入或逗号分隔
• --skip-render-graph：只生成结构化产物，不额外产图

例如：

python3 <byted-volcengine-topology-builder-skill>/scripts/run_topology_pipeline.py \
  --workspace-root "$(pwd)" \
  --env-path ./.env \
  --region cn-shanghai \
  --business payment-core \
  --include ecs,eip,clb,alb,natgateway,rds_mysql,redis \
  --entry eip --entry clb

分层执行

1. 采集资产快照

python3 <byted-volcengine-topology-builder-skill>/scripts/dump_account_assets.py \
  --region cn-shanghai \
  --env-path ./.env \
  --include ecs,eip,clb,alb,natgateway,rds_mysql,redis \
  --output-file ./business_topologies/payment-core/account_assets_snapshot.json

这一层的目标是尽量沉淀稳定、可复用、可重建的基础资产数据。

2. 从快照构图

python3 <byted-volcengine-topology-builder-skill>/scripts/build_topology_from_account_assets.py \
  --assets-file ./business_topologies/payment-core/account_assets_snapshot.json \
  --region cn-shanghai \
  --entry eip --entry clb --entry alb --entry natgateway \
  --output-file ./business_topologies/payment-core/topology.json

这一层负责把离散资产组织成统一关系模型，方便后续分析和可视化。

3. 保存并渲染产物

python3 <byted-volcengine-topology-builder-skill>/scripts/save_topology.py \
  --business payment-core \
  --root ./business_topologies \
  --topology-file ./business_topologies/payment-core/topology.json

如果只想对已有 topology.json 单独补画图：

python3 <byted-volcengine-topology-builder-skill>/scripts/render_topology_graph.py \
  --topology-file ./business_topologies/payment-core/topology.json \
  --output-dir ./business_topologies/payment-core

关系表达

当前 topology.json 使用 nodes + chains 的结构：

• path[].relation：主链路关系
• contexts.<node_id>：路径节点的上下文资源

当前关系语义：

• attached_to：A 绑定到 B，例如 EIP -> CLB、ECS -> EBS
• has：A 拥有 B，例如 CLB -> 后端服务器组
• contains：A 包含 B，例如 后端服务器组 -> ECS、VPC -> 子网
• belongs_to：A 归属 B，例如 ECS -> VPC/子网/安全组

展示层默认以资源 id 为主，避免实例名称重复导致歧义；name 保留在元数据中作为辅助信息。

当前覆盖范围

在权限允许且快照字段完整的情况下，当前优先沉淀下面这些基础关系：

• EIP -> CLB -> 后端服务器组 -> ECS
• EIP -> ECS
• ECS -> VPC/子网/安全组/EBS
• VPC -> 子网

这意味着它已经能为很多上层场景提供基础输入，但它依然是一个可扩展的底座，不应被理解为“已经完整覆盖所有云资源关系”。

常见问题

• AccessDenied (403)：账号没有对应产品的只读权限，脚本会尽量降级并保留已成功拉取的资产
• rds_mysql/redis 对应 SDK 方法或字段不稳定：说明当前采集适配仍需继续扩展，但不影响已有基础产物落盘
• 本地没有 dot 命令：不会阻塞 topology.json/topology.md 生成，至少仍会得到 topology.dot
• 如果不希望渲染脚本自动安装 Graphviz，可在直接调用渲染脚本时加 --skip-auto-install-graphviz