architecture-diagrams

架构图

便携式 Claude Agent 技能

使用 Diagrams Python 库生成专业架构图。生成的图表达到出版质量，并采用真实的云服务提供商图标（AWS、Azure、GCP、K8s、OnPrem、Generic）。

便携性： 整个 architecture-diagrams/ 文件夹完全自包含。将其复制到 ~/.claude/skills/ 或任意项目的 .claude/skills/ 目录中。每个位置只需运行一次 ./scripts/setup.sh。

安装与设置

系统前置条件

必须在系统范围内安装 Graphviz（提供 dot 二进制文件）：

# Ubuntu/Debian
sudo apt install graphviz

# macOS
brew install graphviz

# RHEL/Fedora
sudo dnf install graphviz

一次性设置（每个安装位置）

cd <path-to>/architecture-diagrams/
chmod +x scripts/setup.sh
./scripts/setup.sh

这会创建 .venv/、安装 Python 依赖项并验证 Graphviz。

自动设置检查

cd <path-to>/architecture-diagrams/
if [ ! -d ".venv" ]; then
  ./scripts/setup.sh
fi
echo "Skill ready"

快速入门

# 1. Navigate to your project directory
cd ~/projects/my-project/

# 2. Set skill path for convenience
SKILL_DIR=~/.claude-wa/.claude/skills/architecture-diagrams

# 3. Verify setup
if [ ! -d "$SKILL_DIR/.venv" ]; then cd "$SKILL_DIR" && ./scripts/setup.sh && cd -; fi

# 4. Activate venv
source "$SKILL_DIR/.venv/bin/activate"

# 5. Create a diagram script in your project
cat > my-diagram.py << 'EOF'
from diagrams import Diagram, Cluster
from diagrams.aws.compute import EC2
from diagrams.aws.network import ELB

with Diagram("My Architecture", show=False):
    lb = ELB("Load Balancer")
    with Cluster("Web Tier"):
        web = [EC2("Web 1"), EC2("Web 2")]
    lb >> web
EOF

# 6. Generate PNG (output goes to ./output/png/ in current directory)
python "$SKILL_DIR/scripts/generate.py" my-diagram.py

# Output: ~/projects/my-project/output/png/my-diagram.png

文件结构

architecture-diagrams/        <-- Skill root (portable)
  SKILL.md                    # This file
  requirements.txt            # Python deps (diagrams, graphviz)
  .venv/                      # Python virtual environment (created by setup.sh)
  scripts/
    setup.sh                  # Creates .venv and installs deps
    generate.py               # Runs diagram script, outputs to cwd/output/png/
  src/
    templates/                # Starter templates — copy these
      basic-template.py       # Minimal template with TODOs
    examples/                 # Working example diagrams
      cisco-network.py        # Network topology with routers, switches, firewall
      aws-architecture.py     # AWS cloud architecture with VPC, ALB, RDS
      kubernetes-cluster.py   # K8s cluster with namespaces, services, monitoring
  docs/
    icon-reference.md         # Index with top icons + navigation (load this first)
    icons/                    # Provider-specific icon catalogs (load on demand, all ≤450 lines)
      generic.md              # Generic infrastructure (26 icons)
      aws.md                  # Amazon Web Services (562 icons)
      azure-compute-network.md # Azure: Compute, Network, Database, Storage (~400 icons)
      azure-app-devops.md     # Azure: App Services, DevOps, Identity, Integration, IoT (~240 icons)
      azure-web-security.md   # Azure: Management, Security, Web Services (~170 icons)
      gcp.md                  # Google Cloud Platform (144 icons)
      kubernetes.md           # Kubernetes (69 icons)
      onprem.md               # On-Premise tools (211 icons)
      saas.md                 # SaaS providers (42 icons)
      programming.md          # Languages & frameworks (81 icons)
      elastic-firebase.md     # Elastic Stack, Firebase (~109 icons)
      digitalocean-ibm.md     # DigitalOcean, IBM Cloud (~309 icons)
      oracle-openstack.md     # Oracle OCI, OpenStack (~415 icons)
      outscale-alibaba-misc.md # Outscale, Alibaba, GIS, Custom, C4 (~220 icons)

输出路径行为

图表会生成在相对于当前工作目录的 ./output/png/ 中（而非技能目录）。因此，输出会出现在你的项目文件夹中：

# From your project directory
cd ~/projects/my-project/
python <skill>/scripts/generate.py diagram.py
# Output: ~/projects/my-project/output/png/diagram.png

# Custom output directory
python <skill>/scripts/generate.py diagram.py --output-dir ./diagrams/
# Output: ~/projects/my-project/diagrams/diagram.png

# Absolute path
python <skill>/scripts/generate.py diagram.py --output-dir /tmp/diagrams/
# Output: /tmp/diagrams/diagram.png

图标参考（渐进式披露）

17 个提供商共有 2634 个图标，按类别组织，便于高效加载上下文：

1. 从 docs/icon-reference.md 开始 — 主索引（约 130 行），包含导航表、最常用的 30 个图标和快速入门导入语句
2. 按需加载提供商文件，这些文件位于 docs/icons/ 中 — 只加载所需提供商对应的文件（例如，AWS 图标请加载 docs/icons/aws.md）

提供商文件	图标数	加载时机
icons/generic.md	26	网络设备、操作系统、计算、存储
icons/aws.md	562	AWS 云架构
Azure（拆分）：	810	Microsoft Azure — 按需加载
icons/azure-compute-network.md	~400	Azure 计算、网络、数据库、存储
icons/azure-app-devops.md	~240	Azure 应用服务、DevOps、身份、IoT
icons/azure-web-security.md	~170	Azure 管理、安全、Web
icons/gcp.md	144	GCP 架构
icons/kubernetes.md	69	K8s 集群、Pod、服务
icons/onprem.md	211	自托管基础设施、数据库、CI/CD
icons/saas.md	42	SaaS 提供商
icons/programming.md	81	语言、框架
其他云（拆分）：	689	其他云服务提供商 — 按需加载
icons/elastic-firebase.md	~109	Elastic Stack、Firebase
icons/digitalocean-ibm.md	~309	DigitalOcean、IBM Cloud
icons/oracle-openstack.md	~415	Oracle OCI、OpenStack
icons/outscale-alibaba-misc.md	~220	Outscale、Alibaba、GIS、自定义、C4

核心概念

Diagram 上下文管理器

每个图表都使用 Diagram 上下文管理器：

from diagrams import Diagram, Cluster, Edge

with Diagram(
    "Diagram Title",          # Title shown on diagram
    filename="output-name",   # Output filename (no extension)
    outformat="png",          # png, jpg, svg, pdf, dot
    show=False,               # Don't auto-open
    direction="TB",           # TB, BT, LR, RL
    graph_attr={...},         # Graphviz attributes
):
    # nodes and connections here

方向

值	含义	最适用于
TB	从上到下	层级架构、网络拓扑
BT	从下到上	向上的数据流
LR	从左到右	管道、数据流、时间线
RL	从右到左	反向流

图属性

graph_attr = {
    "fontsize": "14",       # Title font size
    "bgcolor": "#ffffff",   # Background color
    "pad": "0.5",           # Padding around diagram
    "nodesep": "0.6",       # Horizontal spacing
    "ranksep": "0.8",       # Vertical spacing between ranks
    "splines": "spline",    # Edge routing: spline, ortho, curved, polyline
    "concentrate": "true",  # Merge parallel edges
}

节点提供商快速参考

Generic（网络基础设施）

from diagrams.generic.network import Firewall, Router, Switch, Subnet, VPN
from diagrams.generic.compute import Rack
from diagrams.generic.database import SQL
from diagrams.generic.storage import Storage
from diagrams.generic.device import Mobile, Tablet
from diagrams.generic.place import Datacenter
from diagrams.generic.os import Ubuntu, Windows, LinuxGeneral, Debian, RedHat, CentOS
from diagrams.generic.virtualization import Vmware, Virtualbox, Qemu
from diagrams.generic.blank import Blank  # Invisible node for layout control

AWS

# Compute
from diagrams.aws.compute import EC2, ECS, Lambda, Fargate, ElasticBeanstalk, Batch
# Database
from diagrams.aws.database import RDS, Aurora, Dynamodb, ElastiCache, Neptune, Redshift
# Network
from diagrams.aws.network import ELB, Route53, CloudFront, VPC, APIGateway, DirectConnect
# Storage
from diagrams.aws.storage import S3, EFS, FSx
# Security
from diagrams.aws.security import Cognito, WAF, IAM, KMS, CertificateManager
# Integration
from diagrams.aws.integration import SQS, SNS, Eventbridge, StepFunctions
# Management
from diagrams.aws.management import Cloudwatch, Cloudformation, Cloudtrail, AutoScaling
# Analytics
from diagrams.aws.analytics import Kinesis, Athena, Glue, EMR
# General
from diagrams.aws.general import Users, Client

Azure

from diagrams.azure.compute import VM, FunctionApps, ContainerInstances, KubernetesServices
from diagrams.azure.database import CosmosDb, SQLDatabases, CacheForRedis
from diagrams.azure.network import LoadBalancers, ApplicationGateway, DNS, VirtualNetworks
from diagrams.azure.storage import BlobStorage, StorageAccounts
from diagrams.azure.security import KeyVaults, ActiveDirectory
from diagrams.azure.integration import ServiceBus, EventGrid
from diagrams.azure.web import AppServices

GCP

from diagrams.gcp.compute import GCE, GKE, Functions, Run, AppEngine
from diagrams.gcp.database import SQL as GcpSQL, Spanner, Firestore, BigTable, Memorystore
from diagrams.gcp.network import LoadBalancing, CDN, DNS as GcpDNS, VPC as GcpVPC
from diagrams.gcp.storage import GCS
from diagrams.gcp.analytics import BigQuery, PubSub, Dataflow
from diagrams.gcp.security import IAP, KMS as GcpKMS

Kubernetes

from diagrams.k8s.compute import Pod, Deployment, StatefulSet, ReplicaSet, Job, CronJob, DaemonSet
from diagrams.k8s.network import Ingress, Service, NetworkPolicy
from diagrams.k8s.storage import PV, PVC, StorageClass
from diagrams.k8s.rbac import ServiceAccount, Role, ClusterRole
from diagrams.k8s.infra import Node as K8sNode, Master
from diagrams.k8s.clusterconfig import HPA, ConfigMap, Secret
from diagrams.k8s.podconfig import Container

本地部署

# Network
from diagrams.onprem.network import Nginx, HAProxy, Traefik, Istio, Envoy, Consul, Kong, Apache
# Database
from diagrams.onprem.database import PostgreSQL, MySQL, MongoDB, Cassandra, Redis as OnPremRedis
from diagrams.onprem.database import Neo4J, CockroachDB, InfluxDB, Clickhouse
# Queue
from diagrams.onprem.queue import Kafka, RabbitMQ, ActiveMQ, Celery, Nats
# Container
from diagrams.onprem.container import Docker
# CI/CD
from diagrams.onprem.ci import Jenkins, GithubActions, GitlabCI, CircleCI
from diagrams.onprem.cd import Spinnaker, Tekton
from diagrams.onprem.gitops import ArgoCD, Flux
# Monitoring
from diagrams.onprem.monitoring import Prometheus, Grafana, Datadog, Splunk, Nagios
from diagrams.onprem.logging import Loki, Fluentbit
from diagrams.onprem.tracing import Jaeger, Tempo
# IAC
from diagrams.onprem.iac import Terraform, Ansible
# VCS
from diagrams.onprem.vcs import Git, Github, Gitlab
# Analytics
from diagrams.onprem.analytics import Spark, Hadoop, Flink
# Auth/Security
from diagrams.onprem.security import Vault, Trivy
# Workflow
from diagrams.onprem.workflow import Airflow, Kubeflow, Nifi
# In-Memory
from diagrams.onprem.inmemory import Redis, Memcached
# Compute
from diagrams.onprem.compute import Server, Nomad

自定义图标

from diagrams.custom import Custom

# Use any local PNG/JPG image as a node icon
my_service = Custom("My Service", "./path/to/icon.png")

集群（分组）

with Cluster("VPC"):
    with Cluster("Public Subnet"):
        web = EC2("Web")
    with Cluster("Private Subnet"):
        api = EC2("API")
        db = RDS("Database")

集群属性：

with Cluster("Styled Group", graph_attr={
    "bgcolor": "#e8f4fd",     # Background color
    "style": "dashed",        # solid, dashed, dotted, rounded
    "color": "#2196F3",       # Border color
    "penwidth": "2.0",        # Border width
    "fontsize": "12",         # Label font size
    "fontcolor": "#333333",   # Label color
    "labeljust": "l",         # Label alignment: l, r, c
}):
    pass

边（连接）

基本连接

# Forward direction
node_a >> node_b

# Backward direction
node_a << node_b

# Bidirectional (no arrows)
node_a - node_b

# One-to-many
node_a >> [node_b, node_c, node_d]

# Chain
node_a >> node_b >> node_c

样式化边

from diagrams import Edge

node_a >> Edge(
    label="HTTPS",        # Text label on the edge
    color="blue",         # Edge color (name or hex)
    style="dashed",       # solid, dashed, dotted, bold
    minlen="2",           # Minimum edge length (ranks)
) >> node_b

边样式模式

连接类型	颜色	样式	示例
同步 API	blue 或 navy	solid	REST/gRPC 调用
异步消息传递	orange 或 green	dashed	Kafka、SQS、事件
数据库访问	purple 或 red	solid	SQL 查询
复制	gray	dashed	数据库复制
监控	gray	dotted	指标/日志
外部 API	brown 或 gold	solid	第三方
缓存	red	solid	Redis/Memcached
存储	brown	dotted	S3、NFS、iSCSI

输出格式

格式	标志	使用场景
PNG	png（默认）	文档、演示文稿
SVG	svg	可缩放的网页嵌入
PDF	pdf	印刷质量的文档
JPG	jpg	压缩图像
DOT	dot	便于手动编辑的 Graphviz 源文件

# Single format
with Diagram("Title", outformat="svg"): ...

# Multiple formats at once
with Diagram("Title", outformat=["png", "svg", "pdf"]): ...

生成脚本用法

# Set skill path
SKILL=~/.claude-wa/.claude/skills/architecture-diagrams

# Activate venv first
source "$SKILL/.venv/bin/activate"

# Generate from example (output in ./output/png/)
python "$SKILL/scripts/generate.py" "$SKILL/src/examples/cisco-network.py"

# Custom output name
python "$SKILL/scripts/generate.py" "$SKILL/src/examples/cisco-network.py" --name my-network

# SVG format
python "$SKILL/scripts/generate.py" "$SKILL/src/examples/aws-architecture.py" --outformat svg

# Custom output directory
python "$SKILL/scripts/generate.py" "$SKILL/src/examples/aws-architecture.py" --output-dir ./my-diagrams/

# Generate in a project directory
cd ~/projects/my-project/
python "$SKILL/scripts/generate.py" my-diagram.py
# Output: ~/projects/my-project/output/png/my-diagram.png

常见图表模式

网络拓扑

布局：TB。使用 diagrams.generic.network 表示 Router、Switch、Firewall、VPN、Subnet。按 DMZ、Internal、Management 区域进行分组。参见 src/examples/cisco-network.py。

云架构

布局：TB。使用 AWS/Azure/GCP 提供商图标。按 VPC、子网、AZ 进行分组。为边添加协议标签。参见 src/examples/aws-architecture.py。

Kubernetes 集群

布局：TB。使用 diagrams.k8s 表示 Pod、Deployment、Service、Ingress。按命名空间进行分组。使用 OnPrem 表示监控堆栈（Prometheus、Grafana）。参见 src/examples/kubernetes-cluster.py。

微服务

布局：TB 或 LR。混合使用提供商：用 OnPrem 表示服务，用 AWS 表示基础设施。按服务组进行分组。使用不同的边样式区分同步/异步/数据流。

CI/CD 流水线

布局：LR。使用 diagrams.onprem.ci 和 diagrams.onprem.cd。采用线性流程，并为不同环境设置分支。

常见错误

错误	修复方法
ModuleNotFoundError: diagrams	先激活 venv：source .venv/bin/activate
ExecutableNotFound: dot	安装 graphviz：sudo apt install graphviz
图表在查看器中打开	在 Diagram() 中设置 show=False
文件保存到了错误的目录	输出位于 cwd/output/png/ — 从项目目录运行，或使用 --output-dir
导入提供商类时出错	在 diagrams.mingrammer.com/docs/nodes/ 中检查准确的类名
边线杂乱且相互重叠	在 graph_attr 中使用 "splines": "ortho" 或 "concentrate": "true"
节点间距过小	在 graph_attr 中增大 nodesep 和 ranksep
图表过大或过小	调整 pad、fontsize 和每个分组中的节点数
找不到自定义图标	路径必须相对于脚本的工作目录
无法生成多种输出格式	将列表传给 outformat：outformat=["png", "svg"]

故障排除

问题	解决方案
setup.sh 失败	确保已安装 Python 3.7+ 和 graphviz 二进制文件
创建 .venv 失败	尝试运行 python3 -m venv .venv --clear 重新创建
输出空白/为空	确认节点定义在 with Diagram() 代码块内
输出时权限被拒绝	检查对 output/png/ 目录的写入权限
生成缓慢	包含许多节点的大型图表生成较慢是正常的 — 减少分组或节点数量
dot 发生段错误	更新 graphviz：sudo apt install --only-upgrade graphviz