diagrams 安装与快速上手：从配置 Graphviz 依赖到生成第一张云架构图

本文基于 diagrams 仓库的入门文档 installation.md，系统讲解 diagrams（Diagram as Code，用代码描述云系统架构）的完整安装流程：环境要求、Graphviz 系统依赖的配置、三种 Python 包管理器的安装方式，以及通过十几行 Python 代码生成第一张 AWS 架构图的快速上手步骤。读完本文，你可以独立完成 diagrams 的安装验证，理解 Diagram 上下文管理器的渲染机制与输出文件命名规则，并能根据 Diagram 类源码 正确调整方向、输出格式等渲染参数。

环境要求：Python 版本与 Graphviz 系统依赖

diagrams 的渲染管线分为两层：Python 包负责以代码方式构建有向图，底层的 Graphviz 引擎负责把图布局并渲染为图片。因此两者缺一不可。

Python 版本

入门文档 installation.md 中写的是 Python 3.7 或更高版本，但需要注意当前仓库的实际要求已经提高：

• pyproject.toml 中声明 python = "^3.9"，即当前版本（0.24.1）要求 Python 3.9 及以上；
• README.md 也明确写有 "It requires Python 3.9 or higher"。

因此以当前仓库为准，安装前请先确认 Python 版本：

$ python --version

Graphviz 系统依赖

Graphviz 是操作系统级别的依赖，不能通过 pip 安装，需要单独安装。不同平台可以这样装：

# macOS + Homebrew
$ brew install graphviz

# Windows + Chocolatey
$ choco install graphviz

Linux 用户可通过发行版包管理器（如 apt/dnf）安装 graphviz。安装后可用 dot -V 验证 Graphviz 是否可用。

注意区分两个 "graphviz"：一个是操作系统里的 Graphviz 引擎（提供 dot 等可执行程序），另一个是 Python 生态中的 graphviz 封装包。pyproject.toml 中对后者有明确版本约束 graphviz = ">=0.13.2,<0.21.0"，并依赖 jinja2 = ">=2.10,<4.0" 用于图标资源的处理，这些会在安装 diagrams 时由 pip 自动解决。

安装 diagrams

安装好 Graphviz 后（或系统已具备时），即可通过常用的 Python 包管理器安装 diagrams：

# 使用 pip（或 pip3）
$ pip install diagrams

# 使用 pipenv
$ pipenv install diagrams

# 使用 poetry
$ poetry add diagrams

安装成功后，diagrams 包会随包内置各云厂商（AWS、Azure、GCP、阿里云、K8s、On-Prem 等）的图标资源，from diagrams.aws.compute import EC2 之类的导入语句即可直接使用，无需额外下载图标。

快速上手：生成第一张架构图

安装完成后，创建一个 diagram.py 文件，写入以下代码：

# diagram.py
from diagrams import Diagram
from diagrams.aws.compute import EC2
from diagrams.aws.database import RDS
from diagrams.aws.network import ELB

with Diagram("Web Service", show=False):
    ELB("lb") >> EC2("web") >> RDS("userdb")

执行：

$ python diagram.py

运行结束后，当前工作目录会生成 web_service.png，即入门文档中展示的 "Web Service" 架构图（上文配图）：一个 ELB 负载均衡指向 EC2 实例，再指向 RDS 数据库。

输出文件名是怎么来的

"Web Service" 为什么会变成 web_service.png？从 diagrams/init.py 的 Diagram.__init__ 可以看到文件名生成逻辑：

• 如果显式传入了 filename 参数（不含扩展名），则直接使用；
• 如果没传 filename，则用 "_".join(self.name.split()).lower() 把 name 按空格拆分、转小写、用下划线连接——"Web Service" 就变成了 web_service；
• 如果 name 和 filename 都没传，默认使用 diagrams_image 作为文件名。

生成流程的源码视角

with Diagram(...) 是一个上下文管理器，渲染发生在上下文退出时。从 diagrams/init.py 的实现看：

def __enter__(self):
    setdiagram(self)
    return self

def __exit__(self, exc_type, exc_value, traceback):
    self.render()
    # Remove the graphviz file leaving only the image.
    os.remove(self.filename)
    setdiagram(None)

• __enter__ 把当前 Diagram 写入 contextvars 全局上下文（见 第 9-15 行），之后创建的每个节点（Node）和集群（Cluster）都会通过 getdiagram() 自动关联到"当前图"，无需手动传参；
• __exit__ 调用 render() 触发 Graphviz 渲染，随后 删除临时的 .dot 中间文件，只保留最终图片；
• Node 的 >>、-、<< 运算符重载（diagrams/init.py）分别实现"单向连接（默认无方向）""前向连接""后向连接"，这就是 ELB("lb") >> EC2("web") >> RDS("userdb") 一行代码能串联三个组件的底层机制。

Diagram 参数速查

结合 diagrams/init.py 中 Diagram.__init__ 的签名与文档字符串，Diagram(...) 的完整参数如下：

参数	类型	默认值	说明
name	str	""	图名，用作图表标题；未给 filename 时据此生成输出文件名
filename	str	""	输出文件名（不含扩展名），未给则由 name 生成
direction	str	"LR"	数据流方向，取值 TB/BT/LR/RL（对应 rankdir）
curvestyle	str	"ortho"	连线弯曲样式，取值 ortho 或 curved
outformat	str 或 list[str]	"png"	输出格式，可选 png、jpg、svg、pdf、dot，列表形式可一次输出多种格式
autolabel	bool	False	为 True 时自动在节点标签前加上类名前缀
show	bool	True	为 True 时渲染完自动打开图片，为 False 时仅保存（脚本/CI 场景建议设为 False）
strict	bool	False	渲染时是否合并多重边
graph_attr / node_attr / edge_attr	dict	None	覆盖默认 Graphviz 属性（dot 配置），例如默认图属性包含 pad=2.0、splines=ortho、nodesep=0.60 等（见 diagrams/init.py）

几个实用取值示例：

• Diagram("Web Service", show=False, direction="TB")：改为自上而下布局，适合纵向分层架构；
• Diagram("Web Service", outformat=["png", "svg"])：同时导出位图与矢量图；
• Diagram("Web Service", curvestyle="curved")：把正交折线换成曲线连接。

下一步

• 更多组合示例（分组 Worker、集群服务、K8s 部署、带颜色的 Edge 连线、Custom 自定义图标节点等）见 examples.md；
• 对 Diagram、Cluster、Node、Edge 的详细用法见 docs/guides/diagram.md、docs/guides/cluster.md、docs/guides/node.md 与 docs/guides/edge.md；
• 各云厂商全部可用节点图标列表按厂商整理在 docs/nodes/ 目录下，如 docs/nodes/aws.md、docs/nodes/k8s.md 等。

需要再次强调适用前提：本文环境要求以当前仓库为准——Python 3.9+ 与系统级 Graphviz，这与较早期文档中 "Python 3.7+" 的说法不同，实际安装前请以 pyproject.toml 的依赖声明为准确认。