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

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

【免费下载链接】diagrams:art: Diagram as Code for prototyping cloud system architectures项目地址: https://gitcode.com/GitHub_Trending/di/diagrams

本文基于 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(...)的完整参数如下：

几个实用取值示例：

• 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 的依赖声明为准确认。

【免费下载链接】diagrams:art: Diagram as Code for prototyping cloud system architectures项目地址: https://gitcode.com/GitHub_Trending/di/diagrams