diagrams Diagram as Code 实战从 AWS 到 Kubernetes 的八类架构图示例全解析【免费下载链接】diagrams:art: Diagram as Code for prototyping cloud system architectures项目地址: https://gitcode.com/GitHub_Trending/di/diagrams本文以 diagrams 官方示例文档 为主体完整收录其中 8 个架构示例AWS 分组 Worker、集群化 Web 服务、AWS 事件处理、GCP 消息收集、Kubernetes 暴露 Pod 与有状态架构、本地机房高级 Web 服务及其彩色标注版、自定义图标 RabbitMQ 消费者并结合 核心源码 讲解Diagram、Cluster、Node、Edge的上下文机制与渲染流程读完即可用 Python 代码原型化任意云架构并输出可版本管理的 PNG/SVG 图片。运行前提与输出约定所有示例共享同一套运行前提来自 README 与 pyproject.tomlPython 3.9 及以上pyproject.toml中声明python ^3.9当前仓库版本为 0.24.1系统需安装 Graphvizdiagrams 依赖graphviz 0.13.2的 Python 包调用 Graphviz 渲染引擎通过pip install diagrams安装后即可直接运行本文任一示例脚本。示例脚本统一使用with Diagram(名称, showFalse)上下文写法showFalse表示只保存图片、不自动打开查看器。从 Diagram.init源码看输出文件名由name自动派生——空格替换为下划线并转小写如Grouped Workers生成grouped_workers.png也可以显式传入filename覆盖name与filename都为空时回退为diagrams_image。渲染发生在上下文退出时exit中调用 render()随后删除中间.gv文件只保留图片。outformat支持png、jpg、svg、pdf、dot五种格式且可以传列表一次导出多种格式render 实现test_outformat_list 验证了同时生成.png与.dot。下面三张图依次对应后文的第一个示例AWS 分组 Worker、集群化 Web 服务与彩色标注版本地机房架构的渲染效果核心语法速览三种连线与广播语法示例代码中反复出现的-、、在 Node 类 中分别实现了__sub__双向边、__rshift__正向边、__lshift__反向边运算符同时提供__rsub__/__rrshift__/__rlshift__支持「节点列表在前」的写法。关键规则node1 - node2无方向箭头适合主从复制、对等同步node1 node2从左到右的单向箭头表达数据流node1 node2箭头反向适合「采集」「上报」这类反向依赖广播a [b, c, d]等价于a分别连向列表内每个节点[a, b] c反向亦然。源码在列表分支中遍历并逐一connectEdge对象可插入链路中间作为「链式中转」例如a Edge(colorbrown) b。这些行为均有单测佐证test_node_to_nodes / test_nodes_to_node 验证节点与列表的互连返回值EdgeTest 覆盖了color、label、双向边 Edge 组合时dir属性自动置为both见 Edge.attrs等场景。示例一AWS 上的分组 Worker这是最简单的「广播 换行」用例一个 ELB 后挂 5 个 EC2 Worker再汇聚到 RDS。directionTB将布局改为自上而下默认是LR从左到右合法值TB/BT/LR/RL在 Diagram 构造校验 中强制非法值抛ValueErrortest_validate_direction 验证了这一点。from diagrams import Diagram from diagrams.aws.compute import EC2 from diagrams.aws.database import RDS from diagrams.aws.network import ELB with Diagram(Grouped Workers, showFalse, directionTB): ELB(lb) [EC2(worker1), EC2(worker2), EC2(worker3), EC2(worker4), EC2(worker5)] RDS(events)要点中括号列表写法让 5 个 Worker 共用 ELB 一条出边语义链式返回使整行可继续向右串联到RDS。示例二集群化 Web 服务Cluster 分区引入Cluster把节点划入虚线分组框是表达「服务区 / 数据库区」的惯用手段。源码上Cluster 在exit时把自己作为子图挂载到父 Cluster 或 Diagram嵌套层级 depth 会循环取四档背景色#E5F5FD、#EBF3E7、#ECE8F6、#FDF7E3以区分内外层这正是渲染图中不同分区底色不同的原因。from diagrams import Cluster, Diagram from diagrams.aws.compute import ECS from diagrams.aws.database import ElastiCache, RDS from diagrams.aws.network import ELB from diagrams.aws.network import Route53 with Diagram(Clustered Web Services, showFalse): dns Route53(dns) lb ELB(lb) with Cluster(Services): svc_group [ECS(web1), ECS(web2), ECS(web3)] with Cluster(DB Cluster): db_primary RDS(userdb) db_primary - [RDS(userdb ro)] memcached ElastiCache(memcached) dns lb svc_group svc_group db_primary svc_group memcached两个易错点db_primary - [RDS(userdb ro)]使用无方向的双向边表达主从库svc_group是列表变量svc_group db_primary依赖Node.__rrshift__完成「列表 → 单节点」的批量连线。注意Cluster内部定义的节点在with块内声明但连线语句放在集群块外也能正确渲染因为 Node 连接始终登记到全局 Diagram 而非 Clusterconnect注释明确说明边必须加在全局图上下文上。示例三AWS 上的事件处理三层嵌套 Cluster该示例展示Cluster多层嵌套时的表达力Event Flows内再嵌Event Workers与Processing对应从 EKS 数据源、ECS Worker、SQS 队列、Lambda 处理到 S3/Redshift 落盘的完整事件链路。from diagrams import Cluster, Diagram from diagrams.aws.compute import ECS, EKS, Lambda from diagrams.aws.database import Redshift from diagrams.aws.integration import SQS from diagrams.aws.storage import S3 with Diagram(Event Processing, showFalse): source EKS(k8s source) with Cluster(Event Flows): with Cluster(Event Workers): workers [ECS(worker1), ECS(worker2), ECS(worker3)] queue SQS(event queue) with Cluster(Processing): handlers [Lambda(proc1), Lambda(proc2), Lambda(proc3)] store S3(events store) dw Redshift(analytics) source workers queue handlers handlers store handlers dw从源码结构看嵌套 Cluster 依赖contextvars.ContextVar维护「当前所属 cluster」setcluster/getcluster 随with进出切换上下文test_with_nested_cluster 验证了嵌套时getcluster()正确回退到父级。若某个 Cluster 内没有节点、或忘了with就声明节点节点会落到外层图或抛出EnvironmentErrorNode 构造检查全局上下文对应 test_node_not_in_diagram。示例四GCP 上的消息收集系统跨云厂商的示例以 PubSub 为中枢左侧 IoT Core 集群作为数据源右侧 Dataflow 分流到大查询/数据湖与事件驱动AppEngine/Cloud Functions两条处理路径。from diagrams import Cluster, Diagram from diagrams.gcp.analytics import BigQuery, Dataflow, PubSub from diagrams.gcp.compute import AppEngine, Functions from diagrams.gcp.database import BigTable from diagrams.gcp.iot import IotCore from diagrams.gcp.storage import GCS with Diagram(Message Collecting, showFalse): pubsub PubSub(pubsub) with Cluster(Source of Data): [IotCore(core1), IotCore(core2), IotCore(core3)] pubsub with Cluster(Targets): with Cluster(Data Flow): flow Dataflow(data flow) with Cluster(Data Lake): flow [BigQuery(bq), GCS(storage)] with Cluster(Event Driven): with Cluster(Processing): flow AppEngine(engine) BigTable(bigtable) with Cluster(Serverless): flow Functions(func) AppEngine(appengine) pubsub flow此处列表写法[IotCore(...)] pubsub是「多对一」聚合的简洁表达Data Lake与Event Driven两个子 Cluster 共享同一个flow上游展示了同一节点可扇出到多个子分组。示例五Kubernetes 上 3 副本的暴露 Pod表达「HPA → Deployment → ReplicaSet → 3 Pod」的伸缩链路与 Ingress/Service 的暴露关系注意这里用了把右侧的 HPA 链回接到左侧的 Service/Ingress 一侧从而在同一行内完成两条链路的合流。from diagrams import Diagram from diagrams.k8s.clusterconfig import HPA from diagrams.k8s.compute import Deployment, Pod, ReplicaSet from diagrams.k8s.network import Ingress, Service with Diagram(Exposed Pod with 3 Replicas, showFalse): net Ingress(domain.com) Service(svc) net [Pod(pod1), Pod(pod2), Pod(pod3)] ReplicaSet(rs) Deployment(dp) HPA(hpa)从 diagrams/k8s/compute.py 源码看Deployment、ReplicaSet、StatefulSet等只是别名字符串到具体类Deployment Deploy、ReplicaSet RS、StatefulSet STS的别名导入名对大小写/缩写不敏感时可用别名替换。示例六Kubernetes 有状态架构循环生成 Pod该示例用 Python 循环生成 3 组「Service → Pod → PVC」并用反向把 PV/StorageClass 接到各 PVC 上表达存储挂载关系。from diagrams import Cluster, Diagram from diagrams.k8s.compute import Pod, StatefulSet from diagrams.k8s.network import Service from diagrams.k8s.storage import PV, PVC, StorageClass with Diagram(Stateful Architecture, showFalse): with Cluster(Apps): svc Service(svc) sts StatefulSet(sts) apps [] for _ in range(3): pod Pod(pod) pvc PVC(pvc) pod - sts - pvc apps.append(svc pod pvc) apps PV(pv) StorageClass(sc)要点apps收集的是每次svc pod pvc的返回值即pvc节点列表因此apps PV(pv)实际是「三个 PVC 分别连向 PV」的广播。这说明链返回链尾节点可被 Python 常规数据结构继续处理是生成规模化拓扑图的实用技巧。示例七本地机房高级 Web 服务onprem 全家桶混合了onprem各分类节点Nginx 入口、gRPC 服务集群、Redis/PostgreSQL 双主从 HA、Fluentd 日志链路与 Prometheus/Grafana 监控采集。from diagrams import Cluster, Diagram from diagrams.onprem.analytics import Spark from diagrams.onprem.compute import Server from diagrams.onprem.database import PostgreSQL from diagrams.onprem.inmemory import Redis from diagrams.onprem.aggregator import Fluentd from diagrams.onprem.monitoring import Grafana, Prometheus from diagrams.onprem.network import Nginx from diagrams.onprem.queue import Kafka with Diagram(Advanced Web Service with On-Premises, showFalse): ingress Nginx(ingress) metrics Prometheus(metric) metrics Grafana(monitoring) with Cluster(Service Cluster): grpcsvc [ Server(grpc1), Server(grpc2), Server(grpc3)] with Cluster(Sessions HA): primary Redis(session) primary - Redis(replica) metrics grpcsvc primary with Cluster(Database HA): primary PostgreSQL(users) primary - PostgreSQL(replica) metrics grpcsvc primary aggregator Fluentd(logging) aggregator Kafka(stream) Spark(analytics) ingress grpcsvc aggregator语义拆解metrics Grafana表示 Grafana 反向指向 Prometheus查询方向primary - Redis(replica) metrics中-表达主从复制的无方向关系 metrics表达「被 Prometheus 采集」grpcsvc primary让 3 台 gRPC 服务同时连向会话主库。示例八同一架构的彩色标注版Edge 深度用法与上一节同一拓扑但所有连接边都换成显式Edge通过color、style、label三个参数着色描边Edge.init中这三个参数最终合并进 Graphviz 边属性Edge.attrs 依据forward/reverse标志自动计算dir为forward/back/both/none。更多 Edge 用法见 Edges 指南。from diagrams import Cluster, Diagram, Edge from diagrams.onprem.analytics import Spark from diagrams.onprem.compute import Server from diagrams.onprem.database import PostgreSQL from diagrams.onprem.inmemory import Redis from diagrams.onprem.aggregator import Fluentd from diagrams.onprem.monitoring import Grafana, Prometheus from diagrams.onprem.network import Nginx from diagrams.onprem.queue import Kafka with Diagram(nameAdvanced Web Service with On-Premise (colored), showFalse): ingress Nginx(ingress) metrics Prometheus(metric) metrics Edge(colorfirebrick, styledashed) Grafana(monitoring) with Cluster(Service Cluster): grpcsvc [ Server(grpc1), Server(grpc2), Server(grpc3)] with Cluster(Sessions HA): primary Redis(session) primary - Edge(colorbrown, styledashed) - Redis(replica) Edge(labelcollect) metrics grpcsvc Edge(colorbrown) primary with Cluster(Database HA): primary PostgreSQL(users) primary - Edge(colorbrown, styledotted) - PostgreSQL(replica) Edge(labelcollect) metrics grpcsvc Edge(colorblack) primary aggregator Fluentd(logging) aggregator Edge(labelparse) Kafka(stream) Edge(colorblack, stylebold) Spark(analytics) ingress Edge(colordarkgreen) grpcsvc Edge(colordarkorange) aggregator三个 Edge 细节值得注意color支持 CSS 颜色名firebrick、brown、darkgreen等也支持十六进制style取 Graphviz 边线型dashed、dotted、bold等Edge可作为链式中继A Edge(...) B与A - Edge(...) - B中 Edge 的__lshift__/__sub__会记录方向并调用connect链中连续多个 Edge 时后一个会拷贝前一个的属性Edge.connecttest_node_to_node_with_attributes 覆盖了这类混合写法A Edge B这种「先正后反」写法会同时置位forward与reverse最终渲染为双向箭头dirboth。示例九自定义图标节点Custom前面的节点图标都来自内置resources目录若服务没有内置图标Custom允许直接引用本地图片文件作为节点图像。Custom 类 覆写了_load_icon直接返回用户传入的icon_path因此图片需先下载到本地远程 URL 需自行处理。from urllib.request import urlretrieve from diagrams import Cluster, Diagram from diagrams.aws.database import Aurora from diagrams.custom import Custom from diagrams.k8s.compute import Pod # Download an image to be used into a Custom Node class rabbitmq_url https://jpadilla.github.io/rabbitmqapp/assets/img/icon.png rabbitmq_icon rabbitmq.png urlretrieve(rabbitmq_url, rabbitmq_icon) with Diagram(Broker Consumers, showFalse): with Cluster(Consumers): consumers [ Pod(worker), Pod(worker), Pod(worker)] queue Custom(Message queue, rabbitmq_icon) queue consumers Aurora(Database)从 Node._load_icon 可对比实现差异内置节点返回resources/provider/type/icon的本地路径图标文件随包分发pyproject.toml中include [resources/**/*]保证其打包而Custom直接把第二个构造参数当作图像路径。若图标不存在渲染会失败或显示空白建议先确认文件落在脚本工作目录下。渲染细节从 with 语句到 PNG 的完整链路把上述示例的底层机制串起来均来自 diagrams/init.pywith Diagram(...)进入时enter调用 setdiagram(self)将当前图写入全局ContextVar构造时依次写入 默认图属性pad/splines/nodesep 等、节点属性rounded 方框 1.4x1.4与边属性#7B8894 灰色再校验direction、curvestyleortho/curved、outformat集群内节点创建时Node.init检查当前 cluster 上下文决定挂载点有 cluster 则登记进 cluster 子图否则直接进主图节点若有图标则附加image属性并按换行数补偿高度每条连线由connect统一登记到主图connect 实现Edge.attrs在登记时注入方向with退出时exit调用 render 并删除 .gv 中间文件showTrue时额外自动打开图片。这也解释了示例中的几个常见困惑连线语句写在哪里集群内或外不影响边本身只影响节点归属而diagrams只绘制、不管理真实云资源也不会生成 CloudFormation/Terraform 代码README 明确说明其定位是架构原型与文档化的「图即代码」可随 Git 提交做架构变更追踪。小结与延伸阅读本文覆盖的 8 个示例共同构成 diagrams 的完整能力面方向与格式控制direction、outformat、分组表达Cluster嵌套与自动底色、广播连线列表语法、边样式Edge三参数、循环生成规模拓扑、以及Custom自定义图标。继续深入可查阅安装与快速上手Cluster 指南、Node 指南、Edge 指南、Diagram 指南各厂商节点清单AWS 节点、Kubernetes 节点、on-prem 节点、GCP 节点测试基线test_diagram.py方向/格式校验、上下文、广播、Edge 属性全场景【免费下载链接】diagrams:art: Diagram as Code for prototyping cloud system architectures项目地址: https://gitcode.com/GitHub_Trending/di/diagrams创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考