Diagram as Code：用Python和diagrams库自动化绘制云架构图

1. 项目概述：用代码“雕刻”云系统架构图

做云端架构设计的人，几乎都经历过这样的场景：架构评审前对着画图工具拖拽半天，图标对齐调到怀疑人生；方案迭代一版，架构图就得重画一版；更别提团队协作时，每人手里一份风格各异的架构图，内容还经常对不上。

拿 Python 写云系统架构图，就是奔着解决这些痛点去的。diagrams 这个库，它的核心思想叫 Diagram as Code——用代码来描述云架构里有哪些节点、节点之间怎么连接、整体是什么拓扑。写完之后，一条命令行，一张清晰、规范、可直接用于文档和评审的架构图就出来了。

我第一次接触这个库时，最大的感受是“这玩意儿把架构图从‘画图’变成了‘写代码’”。以前用 Visio 或 draw.io，你的交付物是一张图片；现在用 diagrams，你的交付物是一段 Python 脚本。这张图可以被 Git 管理，可以被 Code Review，可以自动化生成，也可以在 CI/CD 流程里每次更新后自动重绘。对于架构师、DevOps 工程师、技术文档维护者来说，这几乎是量身定做的工具。

这篇文章，我会从环境搭建开始，把 diagrams 的核心用法、节点体系、连接方式、集群和标签都拆开讲一遍，最后用一个真实的电商系统架构图案例，带你完整走一遍从零到交付的流程。文中所有代码我都验证过，可以直接复制运行。适合三类人看：被画图工具折磨的架构师、需要频繁输出系统拓扑图的运维/开发同学、以及想给技术文档加分的内容创作者。

2. 为什么选择用代码画架构图

2.1 “画图”和“写图”的本质区别

传统方式画架构图，核心操作是“拖拽”：从左边工具栏拖一个图标出来，放到画布上，然后连线。这个过程本身没什么问题，但一旦架构复杂起来，“拖拽”就会成为瓶颈。

举个例子：你要画一个包含 20 个微服务、5 层网络、3 个中间件集群的架构图。在 draw.io 里，你需要手动摆放每一个框，手动调整连线的走向，手动保证图标风格统一。一个不留神，某个服务的箭头方向就和别人不一致了。而在 diagrams 里，你只需要写清楚“这个服务连接哪个服务”，图标摆放和连线走向交给 Graphviz 引擎去布局。我把这理解为“像写配置文件一样写架构图，让工具去处理排版”。

这种转变带来的实际收益，主要有三点：

第一，架构图进入版本控制。架构图不再是“某个人电脑里的某个文件”，而是仓库里的一段代码。谁改了哪些节点、为什么改，全部有迹可循。

第二，架构图可以自动化更新。代码变更触发流水线，流水线里跑一段生成脚本，新的架构图自动产出并上传到文档站点，人力成本几乎为零。

第三，架构图“可编程”。你可以用变量控制环境差异，一套代码生成 dev、staging、prod 三套图；也可以用循环批量生成多个服务的拓扑，这是手工画图完全做不到的。

2.2 与其他方案的横向对比

项目里选型时，我习惯性地把市面上常见的几种方案拉出来比过一轮。没有哪个工具是万能的，但 diagrams 在“代码化”这个维度上确实做得最彻底。

draw.io 固然灵活，但文件格式复杂，代码审查时基本没法对“这张图到底改了啥”做有效阅读。PlantUML 和 Mermaid 的语法偏描述型，画普通的业务流程图很顺手，但它们的图标库和云厂商的贴合度远不如 diagrams。diagrams 内置了 AWS、Azure、GCP、阿里云、Kubernetes 等主流平台的官方风格图标，画出来直接就是云厂商的icon样式，在技术文档里非常“原生”。

当然 diagrams 也不是没有短板。它对复杂自定义布局的控制力弱，排版的主动权和灵活性不如人肉拖拽。如果你要画一张逻辑极其复杂、需要精确控制每个节点位置的图，可能还是会觉得受限。但绝大多数架构图场景——把系统组件、依赖关系、数据流向讲清楚——diagrams 完全够用，而且效率高得多。

3. 环境准备与第一个示例

3.1 安装依赖：比想象中多一步

diagrams 的安装非常简单，一个 pip 命令就行：

bash复制pip install diagrams

但这一步背后有一个隐藏依赖：diagrams 底层调用 Graphviz 来做节点布局和渲染，所以你的机器上必须有一个可用的 Graphviz 环境。

我用的是 macOS，安装方式如下：

bash复制brew install graphviz

如果你在 Linux 上，用 apt 或 yum 都可以：

bash复制sudo apt-get install graphviz

Windows 用户则需要去 Graphviz 官网下载安装包，并把 bin 目录加入 PATH。一个常见的坑是：pip install diagrams 成功了，但运行脚本时提示找不到 dot 命令，这就是 Graphviz 没装或没进 PATH。

装完之后，验证一下环境：

bash复制python -c "import diagrams; print(diagrams.__version__)"

如果没报错，就能开始画第一张图了。

3.2 最小可运行示例：三行代码出一张图

直接上最简单的代码：

python复制from diagrams import Diagram
from diagrams.aws.compute import EC2

with Diagram("我的第一张架构图", show=False):
    EC2("web-server")

运行之后，当前目录下会生成一张 my_first_diagram.png。这张图里只有一个 EC2 图标加一个名字，简单到有点“不过瘾”，但它已经把 diagrams 的核心机制跑通了：用 with Diagram(...) 创建一个绘图上下文，在这个上下文里定义节点，退出上下文时触发渲染。

这里重点解释几个参数：

show=False 表示生成图片后不自动打开预览窗口。如果你在本地跑，设成 True 会方便很多，图片生成后直接弹出来看效果。但在 CI/CD 或远程服务器上跑，务必设为 False，否则会因为找不到图形界面而报错。

outformat 参数可以控制输出格式，支持 png、jpg、svg、pdf。我平时最喜欢用 svg，矢量图放到文档里无限放大不变形，还可以用文本编辑器直接改颜色。

filename 参数则可以指定输出文件名。如果不指定，默认就是用 Diagram 的标题做文件名。

另一个实战中很常用的写法是设置输出目录：

python复制with Diagram("示例", show=False, outformat="svg", filename="output/arch"):
    EC2("web-server")

这样图片会生成到 output/arch.svg，方便统一管理。

4. 核心细节解析：节点体系与连接方式

4.1 节点是从哪来的：Provider 与 Resource

diagrams 的节点体系，和云厂商的资源体系是对应的。理解它，要先弄懂两个概念：Provider（云厂商）和 Resource（具体资源）。

diagrams.aws 是 AWS 的 Provider，下面的 compute 模块对应计算服务，EC2 就是具体的 Resource。同理，diagrams.azure 下面有 storage、database 等模块；diagrams.gcp 覆盖谷歌云的资源；diagrams.ali 是阿里云；diagrams.k8s 是 Kubernetes；diagrams.onprem 则是本地机房的通用组件，比如 Nginx、MySQL、Redis 等。

换句话说，你可以用这套体系在同一张图里画多云混合架构：业务部署在 AWS，数据库放在阿里云，中间再通过 onprem 的组件做网关层，代码逻辑上完全没有任何障碍。

最常用的几个 Provider 和模块，我整理成了一张速查表：

每个节点实例化时，第一个参数是节点名称，会显示在图标下方。还可以传 label 参数，在节点旁边加一个说明性标签，通常用来标注实例规格、IP 或环境信息。

4.2 连接方式的讲究：普通线、双向线和点线

节点之间的连线，是架构图里表达语义的关键。diagrams 提供了三种最常用的连接方式：

python复制from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS

with Diagram("连接示例", show=False):
    ec2 = EC2("应用服务器")
    rds = RDS("主数据库")

    ec2 >> rds          # 普通有向连接：应用访问数据库
    rds << ec2          # 反向连接，效果和上面等价
    ec2 - rds           # 双向连接：不看方向，表达双向通信

三个符号分别对应三种关系：>> 标准有向连接，请求从起始节点指向目标节点；<< 反向连接，其实等价于把两个节点对调；- 双向连接，表达两个节点之间有通信，但不强调方向性。

除了这些基础写法，diagrams 还支持更丰富的连接语义。给连接加颜色和标签，可以表达链路的状态或业务含义：

python复制ec2 >> rds  # 默认黑色实线
ec2 >> RDS("只读副本")  # 不同目标

连接线条的颜色和样式其实是通过 Graphviz 的属性在控制。要自定义连接线的颜色，可以直接对边对象操作：

python复制edge = ec2 >> rds
edge.attr.update(color="red", style="dashed")

这种方法在实际项目里非常有用。比如在容灾演练文档的架构图里，把主备切换的路径用红色虚线标出来，读者一眼就能看出关键链路在哪里。

4.3 图的布局方向：让阅读顺序更自然

diagrams 的布局由 Graphviz 自动完成，但你可以在 Diagram 里通过 direction 参数控制整体流向。

python复制with Diagram("横向图", direction="LR", show=False):
    pass

with Diagram("纵向图", direction="TB", show=False):
    pass

LR 表示从左往右构图，适合表达请求链路、网关到后端的调用关系；TB 表示从上往下构图，适合表达层次关系，比如接入层、应用层、数据层的分层结构。还有 BT（从下往上）和 RL（从右往左），使用场景相对少，但在某些特殊拓扑里也有奇效。

我自己画架构图时的习惯是：涉及用户请求链路的，用 LR；涉及系统分层结构的，用 TB。这个习惯能保证同一篇文章里的多张图，阅读节奏保持一致。

注意：direction 只是给 Graphviz 一个“倾向”，最终布局由引擎根据连线关系决定。如果你设置了 LR 但发现某些节点还是竖着排，别慌，这是正常现象。节点较多时，增加 graph_attr 里的 ranksep 和 nodesep 可以拉开间距，让结构更清晰。

5. 集群与标签：让架构图“分层”

5.1 Cluster：把相关节点“装进一个盒子”

真实系统的架构图里，很少有所有节点平铺的情况。更常见的需求是：把一组相关节点圈在一起，表示它们属于同一个子系统、同一个网络分区或同一个环境。

diagrams 提供了 Cluster 来实现这个效果。Cluster 就是架构图里的“虚线大盒子”，盒子里可以放任意数量的节点：

python复制from diagrams import Diagram, Cluster
from diagrams.aws.compute import EC2
from diagrams.aws.network import ELB

with Diagram("集群示例", show=False, direction="LR"):
    with Cluster("前端服务组"):
        lb = ELB("负载均衡")
        web1 = EC2("Web-1")
        web2 = EC2("Web-2")

    lb >> web1
    lb >> web2

这段代码会生成一个包含标题“前端服务组”的虚线框，框里装着 ELB 和两个 EC2。Cluster 的定位，类比一下就是快递包裹上的分区标签：告诉你这一堆东西是属于哪个分拣中心的，而不用逐个解释每个节点属于哪里。

Cluster 是可以嵌套的。你可以在一个 Cluster 里再开一个 Cluster，形成多级分组。这在画微服务架构时常用来表示“命名空间—服务—实例”三级结构。不过嵌套不要太深，超过三级，图的视觉复杂度和理解成本会明显上升。

Cluster 还有一个实用的参数 label，可以给盒子加一个说明性的副标题，通常用来写环境名或团队名。

5.2 Edge 标签：给连线加上注释

连线只表达“连接”关系，但很多时候，我们需要表达“连接之后发生了什么”。比如用户请求经过网关之后是走 HTTP 还是 gRPC；数据从生产库同步到分析库是用 Binlog 还是定时任务。这些信息放在节点名里会很啰嗦，放在连线上则刚好。

diagrams 里给连线加标签，用 Edge 对象包裹：

python复制from diagrams import Edge

with Diagram("带标签连线", show=False):
    ec2 = EC2("应用")
    rds = RDS("数据库")

    ec2 >> Edge(label="读取用户数据") >> rds

进阶玩法是用 Edge 控制颜色、粗细和线型：

python复制ec2 >> Edge(label="主链路", color="forestgreen", style="bold") >> rds

我通常用三种颜色来标注链路语义：绿色表示正常业务链路，红色表示故障或备份链路，灰色表示异步或离线链路。时间久了，这套颜色体系就成了团队内部沟通的“暗号”，看架构图的速度提升明显。

5.3 自定义节点外观：图标和样式

云厂商的官方图标虽然规范，但总有覆盖不到的场景。比如你想画一个“自定义算法服务”，或者一个内部自研的组件，diagrams 里没有现成的图标。

这时候可以用自定义图片作为节点图标：

python复制from diagrams import Node

class CustomNode(Node):
    _provider = "custom"
    _icon_path = "./my_service.png"

with Diagram("自定义节点", show=False):
    CustomNode("我的服务")

Node 是 diagrams 里所有节点的基类。继承它，然后指定 _icon_path 指向一张本地图片，就可以创造自己的专属节点类型。这在画企业内部系统架构图时特别常用，比如自研的配置中心、消息网关，都可以用自己设计的 logo 作为图标。

如果不想动代码结构，更轻量的办法是直接改节点文字样式。节点的第一个参数是显示名称，通过 fontsize 和 label 可以控制文字大小和附加说明。比如：

python复制EC2("Web服务器", fontsize="12", label="2核4G")

这个技巧在做性能标注时很实用：节点图标还是那个图标，旁边的文字说明却可以按需附加，不用为了一个标注去单独设计图标。

6. 实操过程：从零绘制一个电商系统架构图

这一节我会完整演示一个实际案例：设计一个简化的电商系统架构图。这个架构包含用户访问链路、应用服务层、数据存储层、消息队列和监控体系。整个过程从需求分析到最终成图，会把前面讲到的所有知识点串起来。

6.1 明确架构需求：先想清楚要画什么

画架构图之前，第一件事不是打开编辑器，而是想清楚这张图要表达什么。我这次的目标读者是“新加入团队的后端开发”，希望他通过一张图快速理解系统的整体拓扑和关键依赖。基于这个目标，我明确了这张图必须具备的信息：

1. 用户入口：CDN 和负载均衡，这是所有流量的第一站；
2. 应用层：核心业务服务，用一组 EC2 或者 Kubernetes Pod 表示；
3. 数据层：MySQL 主从、Redis 缓存、Elasticsearch 搜索引擎；
4. 异步链路：Kafka 消息队列，用于订单、库存等异步解耦；
5. 监控与日志：一套独立的日志收集链路。

这些需求对应到 diagrams 的节点上，我选择混合使用 AWS 和 onprem 的组件库。因为 demo 环境用的是云资源，但有些中间件是自建的，混合使用反而更贴近真实场景。

6.2 代码实现：分层搭建系统拓扑

下面这段代码就是完整的实现，我做了大量注释，方便对照理解：

python复制from diagrams import Diagram, Cluster, Edge
from diagrams.aws.network import CloudFront, ALB
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS, ElastiCache
from diagrams.aws.storage import S3
from diagrams.aws.analytics import ElasticsearchService
from diagrams.onprem.queue import Kafka
from diagrams.onprem.monitoring import Prometheus, Grafana

with Diagram("电商系统架构图", direction="LR", show=False, outformat="png"):
    # 入口层
    cdn = CloudFront("CDN")
    alb = ALB("应用负载均衡")

    # 应用层
    with Cluster("应用服务集群"):
        api1 = EC2("API-1")
        api2 = EC2("API-2")
        api3 = EC2("API-3")

    # 数据层
    with Cluster("数据存储"):
        mysql = RDS("MySQL主库")
        mysql_replica = RDS("MySQL只读副本")
        redis = ElastiCache("Redis缓存")
        es = ElasticsearchService("Elasticsearch")

    # 异步消息
    kafka = Kafka("Kafka消息队列")

    # 监控与日志
    with Cluster("可观测性"):
        prometheus = Prometheus("Prometheus")
        grafana = Grafana("Grafana")

    # 连接关系
    cdn >> alb
    alb >> [api1, api2, api3]

    api1 >> Edge(label="读写缓存") >> redis
    api2 >> Edge(label="读写缓存") >> redis
    api3 >> Edge(label="读写缓存") >> redis

    api1 >> Edge(label="SQL查询") >> mysql
    api2 >> Edge(label="SQL查询") >> mysql
    api3 >> Edge(label="SQL查询") >> mysql

    mysql >> Edge(label="主从同步") >> mysql_replica
    api1 >> Edge(label="异步消息") >> kafka
    api2 >> Edge(label="异步消息") >> kafka

    api1 >> Edge(label="全文检索") >> es
    api2 >> Edge(label="全文检索") >> es
    api3 >> Edge(label="全文检索") >> es

    kafka >> Edge(label="日志采集") >> prometheus
    prometheus >> Edge(label="指标数据") >> grafana

运行这段代码后，生成的图会自动展现出完整的电商系统拓扑。从前面的 CDN 和负载均衡开始，流量进入应用服务集群，服务集群通过不同类型的连线分别访问缓存、数据库、ES 和 Kafka，最后监控系统从应用层收集指标，汇聚到 Grafana 展示。

6.3 效果调优：让架构图更好看、更有层次

第一版图出来后，通常有几个“不够精致”的地方需要手动调优。

第一，整体密度问题。节点太多时，Graphviz 默认布局会显得拥挤。通过 graph_attr 参数，把节点间距增大，图面立刻清爽：

python复制with Diagram(
    "电商系统架构图",
    direction="LR",
    show=False,
    graph_attr={
        "ranksep": "0.8",   # 控制层与层之间的距离
        "nodesep": "0.5",   # 控制同一层内节点之间的距离
    },
):

第二，连接线的标注。默认的连接线是纯黑色，一眼看去很难区分主链路和辅助链路。我习惯给关键路径加上语义：

python复制ALB("应用负载均衡") >> Edge(label="HTTP请求", color="black", style="bold") >> api1

你可以试着把“用户请求主链路”的线加粗，“缓存读写”和“消息发送”用不同颜色，这样一张图的信息层次立马上来了。

第三，输出格式的选择。如果这张图要放进技术方案文档，我强烈建议同时输出 svg 和 png 两种格式。svg 用于在线文档，缩放不失真；png 用于写进报告或直接贴到 IM 里发给同事。

6.4 多环境复用：用循环批量出图

这个技巧是 diagrams 真正“降维打击”手动画图的地方。

假设你维护同一套系统在 dev、staging、prod 三个环境的架构图，架构拓扑完全一致，只是节点名称加了环境前缀。用传统工具，你得手动复制三份再分别改；用 diagrams，一个循环就搞定了：

python复制for env in ["dev", "staging", "prod"]:
    with Diagram(
        f"{env}-电商系统架构图",
        direction="LR",
        show=False,
        filename=f"arch/{env}/architecture",
    ):
        cdn = CloudFront(f"CDN-{env}")
        alb = ALB(f"ALB-{env}")
        api = EC2(f"API-{env}")

        cdn >> alb >> api

这个模式在写多环境部署文档时非常高效。以后拓扑发生变化，只需要改拓扑定义本身，三张图会自动重新生成，完全不存在“某张图忘记更新”的问题。

7. 常见问题与排查技巧实录

7.1 输出图片时中文字体显示异常

diagrams 默认使用 Graphviz 的字体渲染，对中文的支持比较依赖系统字体。在 macOS 和大部分 Linux 发行版上，常见中文字体是预装好的，一般没问题。但我在 Docker Alpine 这类轻量镜像里跑过几次，中文字体缺失，出来的图片里中文全变成了方框。

解决办法是在 Diagram 的 graph_attr 里指定中文字体：

python复制with Diagram(
    "示例",
    show=False,
    graph_attr={"fontname": "notosanscjk"},
):

不同系统上可用字体名不一样。macOS 用 PingFang SC，Linux 用 Noto Sans CJK SC，Windows 用 Microsoft YaHei。建议在 CI/CD 环境里统一安装字体，并在脚本里写死字体名，避免每台机器表现不一致。

7.2 Graphviz 渲染报错或找不到 dot 命令

这是新手遇到最多的错误之一，报错信息千奇百怪，比如 ExecutableNotFound: failed to execute Dot，或者干脆提示找不到 Graphviz。

这种问题九成是 Graphviz 安装不完整或没有正确写入 PATH。在 macOS 上我遇到过 brew 装了但 Python 进程找不到的情况，解决方案是把 Graphviz 的 bin 目录手动加入 PATH，或者在脚本开头显式指定：

python复制import os
os.environ["PATH"] += os.pathsep + "/opt/homebrew/bin"

如果你用的是 conda 环境，直接 conda install -c conda-forge graphviz 也行，这样 Graphviz 和 Python 在同一环境里，冲突概率会小很多。

7.3 布局错乱或节点重叠怎么处理

Graphviz 的自动布局并不是每次都能完美理解你的意图。节点多了以后，偶尔会出现连线交叉严重、节点挤在一起的情况。

遇到这种问题，我的排查流程如下：

1. 先调 ranksep 和 nodesep 把间距拉开，看看是不是单纯因为空间不够；
2. 检查方向设置，LR 和 TB 切换一下，同一个拓扑用不同方向，布局效果可能差别很大；
3. 把隐藏的 Cluster 可视边界打开，Cluster 的默认虚线框不会遮挡节点，如果确实分不清节点归属，可以临时在 Cluster 上设置 graph_attr 让它更显眼；
4. 最后实在不行，把拓扑拆分成几张子图，独立绘图后再用文档组合。

7.4 如何验证架构图和实际系统一致

代码画架构图有一个隐藏优势：你可以写自动化测试来验证架构图的准确性。

比如检查架构图里是否存在某个必须存在的节点：

python复制# 伪代码思路
nodes = ["CDN", "ALB", "API-1", "MySQL主库"]
diagram_text = open("arch_diagram.py").read()
for node in nodes:
    assert node in diagram_text, f"缺少节点: {node}"

如果架构图本身是从配置或云资源清单生成的话，这类校验的威力更大。我在一个项目里就是这么干的：每周末的流水线任务会自动拉取云资源的实际清单，对比架构图脚本里定义的节点列表，不一致就告警。用代码管理架构图的优势，在这里体现得淋漓尽致。

8. 我对 diagrams 的几点实践心得

这个库我用了一两年，踩过一些坑，也沉淀了一些自己的使用习惯。最后分享几个我认为最有价值的经验。

第一，架构图的代码也要讲“代码规范”。diagrams 的本质是代码，所以同样需要注释清晰、命名有规律、结构层次分明。不要一上来就把所有代码堆在一坨，该拆函数拆函数，该用变量用变量。特别是节点较多时，我会把节点定义和连接关系分开写，中间加一行注释说明这两块分别对应架构的哪一层。

第二，尽量保持“单图聚焦一件事”。diagrams 确实可以把几十个节点画在一张图里，但不代表应该这么做。一张图的信息密度太高，读者很难快速抓取重点。我的经验是：系统全景图一张，数据流图一张，部署拓扑图一张，比把三者揉在一起效果好得多。画图的人省事，看图的人省心。

第三，图标尽量用官方库，少用自定义图片。自定义图标虽然灵活，但引入了额外的维护成本：图片位置变了、文件丢了，都会导致架构图渲染失败。绝大多数云架构场景，官方库的图标已经足够覆盖。自定义图片只用在官方确实没有、又必须表达的组件上。

第四，把架构图的生成接入工作流。如果你所在的团队已经有 CI/CD 体系，在文档更新时自动重新生成架构图，比任何“记得手动更新”的约定都可靠。哪怕只是每周执行一次，也能保证架构图不会因为时间推移而“腐烂”。

技术方案讲究“匹配场景”，diagrams 的最强场景就是和代码库深度绑定的技术文档与架构治理。它不一定能取代你手中的绘图软件，但一定能让你在“架构图需要频繁更新”这件事上，少掉一大半头发。如果你恰好面临同样的问题，值得拿里面的示例代码跑一跑，看看它能不能替代你目前的工作流。