diagrams 贡献指南：节点类自动生成机制、autogen.sh 工作流与贡献实战

2026-09-05 11:30:28作者：余洋婵Anita

本文为 diagrams（Diagram as Code 云架构图库）贡献者的技术指南。读完你将理解这个仓库最核心的工程约定——节点类（node class）由图片资源自动生成，禁止手工编辑，掌握完整的本地开发环境搭建（Docker / Mac 两条路径）、图片资源更新与别名配置的操作步骤，并能结合 autogen.sh 与 scripts/generate.py 的源码看懂“一个 PNG 图标如何变成一类 Python 节点”的全链路。

核心约定：不要手工编辑 `diagrams/` 下的节点类文件

CONTRIBUTING.md 开篇即给出最关键的约束：

You shouldn't edit the node class files (all files under diagrams/ directory) by yourself. （你不应该自行编辑节点类文件，即 diagrams/ 目录下的所有文件。）

这条规则之所以成立，是因为 diagrams/ 下的所有节点模块都是自动生成的。以 diagrams/aws/compute.py 为例，文件第一行就写着：

# This module is automatically generated by autogen.sh. DO NOT EDIT.

from . import _AWS

class _Compute(_AWS):
    _type = "compute"
    _icon_dir = "resources/aws/compute"

class AppRunner(_Compute):
    _icon = "app-runner.png"

class EC2(_Compute):
    _icon = "ec2.png"

可以看到每个服务节点类只有一行实质代码：_icon = "<图片文件名>"。因此贡献的正确姿势是：修改图片资源或别名配置，再运行 autogen.sh 让代码与文档自动重新生成，而不是改 Python 文件本身。

搭建开发环境

CONTRIBUTING 将环境搭建细节委托给了 DEVELOPMENT.md，这里完整保留其两条路径。

路径一：Docker 本地开发（推荐）

前置条件：系统已安装 Docker。

构建开发镜像（Dockerfile 见 docker/dev/Dockerfile）：

docker build --tag diagrams:1.0 -f ./docker/dev/Dockerfile .

创建容器，后台运行并挂载项目源码：

docker run -d \
-it \
--name diagrams \
--mount type=bind,source="$(pwd)",target=/usr/src/diagrams \
diagrams:1.0

在宿主机通过容器运行单元测试，确认环境可用：
```
docker exec diagrams python -m unittest tests/*.py -v
```
运行 autogen.sh 验证生成流程：
```
docker exec diagrams ./autogen.sh
```
若单元测试与 autogen.sh 均正常通过，即表示开发环境就绪。

从 docker/dev/Dockerfile 源码可以看到，镜像基于 python:3.13.1-alpine3.20，通过 apk 安装了 graphviz、imagemagick、inkscape、go 等二进制依赖，并执行 go install github.com/mingrammer/round@latest 安装 round 工具，最后 pip install black graphviz jinja2。这正是后面运行 autogen.sh 所需的全部依赖的“开箱即用”版本。

路径二：Mac 本地开发

前置条件：已安装 Python、Go 与 Homebrew。

进入 diagrams 根目录。
安装 Python 项目管理工具 Poetry：
```
pip install poetry
```
安装项目 Python 依赖：
```
poetry install
```

安装二进制依赖：

brew install imagemagick inkscape black
go install github.com/mingrammer/round@latest
# ln -sf ~/go/bin/round ~/.local/bin/round

运行单元测试确认环境可用：
```
python -m unittest tests/*.py -v
```
运行 ./autogen.sh 做验证。
单元测试与 autogen.sh 均通过即表示系统就绪。

更新节点资源（图片图标）

所有节点类都是从图片资源文件自动生成的。例如 diagram.aws.compute.EC2 类就是基于 resources/aws/compute/ec2.png 这张图片资源生成的。因此，新增或更新节点，只需要在 resources/<provider>/<type>/<image> 下添加或更新图片文件。

CONTRIBUTING 对图片尺寸有明确要求：图片必须缩放到宽或高最大 256 像素。文档给出了两个常用工具的一行命令：

# 用 ImageMagick
convert -resize 256 my_big_image.jpg my_image.jpg

# 或用 FFmpeg
ffmpeg -i my_big_image.jpg -vf scale=w=256:h=256:force_original_aspect_ratio=decrease my_image.png

放置好图片后，运行 ./autogen.sh 生成新增或更新的节点类。

运行 autogen.sh 的前置依赖

CONTRIBUTING 特别提示：运行 autogen.sh 需要 round、black、inkscape 三个命令行工具（用于清理图片资源文件名和格式化生成的 Python 代码）。macOS 用户可通过 Homebrew 安装 inkscape，或者直接使用上面的 Docker 镜像。

这一点可以从 autogen.sh 源码得到印证：脚本开头（L25-L43）会依次检查 round、inkscape、convert（ImageMagick）、black 四个可执行文件是否存在，任一缺失则打印错误并 exit 1——这也是为什么 Docker 镜像里要把这些工具全部预装好。

生成管线到底做了什么

从 autogen.sh 源码结构看，autogen.sh 按 config.py 中 PROVIDERS 元组列出的 17 个 provider（onprem、aws、azure、digitalocean、gcp、ibm、firebase、k8s、alibabacloud、oci、programming、saas、elastic、generic、openstack、outscale，外加 base）执行两遍循环：

第一遍：资源预处理（每个 provider）

onprem 与 azure：调用 python -m scripts.resource svg2png <pvd>，用 inkscape 把 SVG 图标批量转成 256x256 PNG（参数定义于 config.py 的 CMD_SVG2PNG_OPTS = ("-w", "256", "-h", "256", "--export-type", "png")）；
oci 与 ibm：调用 python -m scripts.resource svg2png2 <pvd>，改用 ImageMagick 转换（-shave 25%x25% -resize 256x256!）；
所有 provider：调用 python -m scripts.resource clean <pvd> 清洗文件名；
仅 aws：额外调用 python -m scripts.resource round <pvd>，用 round 工具把方形图标转成圆形图标。

其中 clean 的实现是 scripts/resource.py 中按 provider 注册的清洗函数表（L140-L157）。以 AWS 为例（cleaner_aws，L25-L36）：下划线替换为连字符、去掉 @4x/@5x 后缀与 -light-bg 背景标记、并把 Amazon-/AWS- 前缀剥离（前缀清单来自 config.py 的 FILE_PREFIXES 字典）后整体小写化。这一步保证 Amazon-Simple-Storage-Service-S3.svg 这类官方资源名最终变成统一的 s3.png。

第二遍：生成模块与文档

对每个 provider 运行 python -m scripts.generate <pvd>，生成节点类模块与节点文档；
再单独为 custom 模块生成文档；
把 resources/ 图标拷贝到 website/static/img/ 供文档网站展示；
最后用 black "$app_root_dir"/**/*.py 对所有生成的模块做代码格式化。

类名是怎么算出来的

scripts/generate.py 的 gen_classes 函数（L28-L41）是核心：它遍历 resources/<provider>/ 下的每个二级目录（即类型目录，如 compute），对其中每个 PNG 文件名按 - 切分后逐词调用 up_or_title 过滤，拼成类名，再渲染 templates/module.tmpl 模板。up_or_title 的命名规则（L20-L25）分三级：

若词在 config.py 的 UPPER_WORDS 中（如 aws 的 ec2、vpc、rds，k8s 的 pvc、rb 等），则全大写；
若词在 TITLE_WORDS 中（如 aws 的 cloudfront → CloudFront、ibm 的 ibm → IBMCloud），则用映射值；
否则做标准 title 化。

这解释了为什么 ec2.png 生成 EC2 类而 app-runner.png 生成 AppRunner 类——与 diagrams/aws/compute.py 中实际生成的类一一对应。同时 generate 函数（L84-L106）会用 apidoc.tmpl（或 provider 专属变体模板）为每个 provider 生成 docs/nodes/ 目录下的节点列表文档，例如 docs/nodes/aws.md，实现“代码、文档、网站图标”三者同步更新。

更新别名（Aliases）

部分节点类存在别名。例如 aws.compute.ECS 是 aws.compute.ElasticContainerService 类的别名。别名同样不是手写的，而是从 config.py 中的 ALIASES 映射自动生成（字典定义见 config.py L116 起）。

要新增或更新别名，只需修改 config.py 中对应 provider 下的 ALIASES 映射，然后重新运行 ./autogen.sh。其机制可以从 templates/module.tmpl 看到：模板末尾的 # Aliases 段落会对 aliases 字典逐项渲染出 {{ alias }} = {{ svc }} 赋值语句——即“别名 = 正牌类”的模块级赋值。以 AWS 为例，ALIASES["aws"]["compute"] 中包含 "ElasticContainerService": "ECS"，最终在 diagrams/aws/compute.py 中生成 ECS = ElasticContainerService，使 from diagrams.aws.compute import ECS 与 ElasticContainerService 等价可用。

运行 autogen.sh 的依赖提示与更新节点资源相同：需要 round 与 inkscape（以及 black/convert，见前述脚本检查逻辑）。

运行测试

CONTRIBUTING 给出的标准测试命令为：

python -m unittest tests/*.py -v

单元测试位于 tests/，覆盖 Diagram、Cluster、Edge 的方向校验、输出格式校验、全局上下文管理等行为。与贡献流程直接相关的是 tests/test_diagram.py 中的 ResourcesTest.test_folder_depth（L379-L395）：它遍历整个 resources 目录并断言任何资源子目录相对深度不超过 2 层，即强制约束资源目录结构必须是 resources/<provider>/<type>/<image>——这与 CONTRIBUTING 中“把图片放到 resources/<provider>/<type>/<image>”的要求互为印证，也解释了为什么新增图片放错层级会被测试拦截。

本地预览文档网站

仓库内置基于 Docusaurus 的文档网站。本地验证步骤（CONTRIBUTING 原文保留）：

cd website/
npm i
npm run start

启动后网站运行在 http://localhost:3000。文档编辑规则：网站相关改动改 website/ 目录，节点文档改 docs/ 目录（docs/nodes/ 下的各 provider 文档本身也是 autogen.sh 的产物，如需修改节点内容应回到资源与配置层面）。

贡献工作流小结

变更目标	修改位置	验证方式
新增/更新节点图标	`resources/<provider>/<type>/<image>.png`（≤256px）	`./autogen.sh` + `python -m unittest tests/*.py -v`
新增/更新类别名	config.py 中 `ALIASES`	`./autogen.sh`
新增命名词（大写/Title 映射）	config.py 中 `UPPER_WORDS` / `TITLE_WORDS`	`./autogen.sh`
节点文档、生成代码	自动生成，勿手改 diagrams/ 与 docs/nodes/	检查生成结果
网站与文档	website/、docs/	`npm run start` 本地预览