diagrams 库 Cluster 集群上下文详解：用 Python 代码实现节点分组、嵌套集群与可视化边界

本文围绕 diagrams（Diagram as Code 云架构图绘制库）官方指南中的 Cluster 集群功能展开：Cluster 用于把一组节点圈进带标签、带背景的独立分组中，并通过 Python 的上下文管理器实现无深度限制的嵌套集群。读完本文，你能掌握集群的基本用法、嵌套写法，并理解其背后的 contextvars 全局上下文机制、子图（subgraph）挂载逻辑与跨集群连线的底层实现。

什么是 Cluster：集群上下文（cluster context）

在 diagrams 中，Diagram 是全局图上下文，Node 代表单个系统组件，而 Cluster 则代表一个本地集群上下文——它把若干节点归拢到一个带标签、带边框的隔离分组里，用来表达“同一区域”“同一 VPC”“同一数据层”等逻辑边界。

核心语义有两点：

• 使用 Cluster 类创建集群上下文，语法上就是普通的 Python with 块；
• 集群内的节点可以与集群外的其他节点自由连线——集群只是视觉/逻辑分组，不隔离数据流。

一个典型的“简单 Web 服务 + 数据库集群”示例：

from diagrams import Cluster, Diagram
from diagrams.aws.compute import ECS
from diagrams.aws.database import RDS
from diagrams.aws.network import Route53

with Diagram("Simple Web Service with DB Cluster", show=False):
    dns = Route53("dns")
    web = ECS("service")

    with Cluster("DB Cluster"):
        db_primary = RDS("primary")
        db_primary - [RDS("replica1"),
                     RDS("replica2")]

    dns >> web >> db_primary

这个示例展示了集群的典型用途：DB Cluster 内部用无向边 - 把主库与两个只读副本归为同一分组，而集群外的 Route53 与 ECS 通过有向边 >> 依次连接，最终指向集群内的 db_primary。这正是文档强调的能力：集群内节点可以连接到集群外节点。

源码级解析：Cluster 如何依托 contextvars 工作

Cluster 的完整实现在 diagrams/init.py。理解它的运行方式，关键是仓库开头定义的一对全局上下文变量（diagrams/init.py）：

# Global contexts for a diagrams and a cluster.
#
# These global contexts are for letting the clusters and nodes know
# where context they are belong to. So the all clusters and nodes does
# not need to specify the current diagrams or cluster via parameters.
__diagram = contextvars.ContextVar("diagrams")
__cluster = contextvars.ContextVar("cluster")

从源码结构看，整套设计是“隐式上下文绑定”：

1. 构造函数校验归属。Cluster.__init__ 会先调用 getdiagram() 取全局 Diagram，取不到直接抛 EnvironmentError("Global diagrams context not set up")——这解释了为什么 Cluster 必须写在 with Diagram(...) 块内部；tests/test_diagram.py 中的 test_node_not_in_diagram 正是对这类约束的验证（tests/test_diagram.py）。
2. __enter__/__exit__ 维护上下文栈。进入 with Cluster(...) 时，__enter__ 调用 setcluster(self)，把当前集群压入上下文；退出时 __exit__ 把自己作为子图挂到父级（父集群或全局 Diagram），然后 setcluster(self._parent) 恢复上一层上下文（diagrams/init.py）：

def __exit__(self, exc_type, exc_value, traceback):
    if self._parent:
        self._parent.subgraph(self.dot)
    else:
        self._diagram.subgraph(self.dot)
    setcluster(self._parent)

3. 节点自动落到“最内层”上下文。Node.__init__ 中通过 getcluster() 判断当前是否处于集群内：是则 self._cluster.node(...)，否则 self._diagram.node(...)（diagrams/init.py）。这就是为什么你无需显式声明“这个节点属于哪个集群”——缩进即归属。

测试用例 test_with_nested_cluster 直接验证了这套上下文栈的进出顺序：进入 c1 后 getcluster() 返回 c1，嵌套进入 c2 后返回 c2，退出 c2 后回到 c1，最终恢复为 None（tests/test_diagram.py）。

Cluster 的构造参数

Cluster 构造函数签名为（diagrams/init.py）：

参数	默认值	说明
label	"cluster"	集群标签，渲染为分组框左上角的标题
direction	"LR"	数据流方向，仅接受 TB/BT/LR/RL，非法值抛 ValueError
graph_attr	None（按空字典处理）	自定义 Graphviz dot 图属性，会覆盖默认值

默认图属性定义了分组框的视觉样式：shape=box、style=rounded（圆角方框）、pencolor=#AEB6BE（灰蓝色边框）、左对齐标签等（diagrams/init.py）：

_default_graph_attrs = {
    "shape": "box",
    "style": "rounded",
    "labeljust": "l",
    "pencolor": "#AEB6BE",
    "fontname": "Sans-Serif",
    "fontsize": "12",
}

需要特别注意源码中的 FIXME 注释：集群级别的 direction 参数目前实际不生效——Graphviz 无法正确渲染与父图方向不同的子图（diagrams/init.py）。因此跨层级想调整布局方向时，应从 Diagram 层面设置，而非依赖 Cluster(direction=...)。

嵌套深度与自动背景色

嵌套集群没有深度限制。为了在视觉上区分不同层级的分组，源码按集群深度循环取用一组背景色（diagrams/init.py）：

# Set cluster depth for distinguishing the background color
self.depth = self._parent.depth + 1 if self._parent else 0
coloridx = self.depth % len(self.__bgcolors)
self.dot.graph_attr["bgcolor"] = self.__bgcolors[coloridx]

其中顶层集群 depth 为 0，每嵌套一层加 1；颜色池为 ("#E5F5FD", "#EBF3E7", "#ECE8F6", "#FDF7E3")，即蓝、绿、紫、米黄四色循环。你可以据此推断：同一深度的集群共享同一种背景色，深度不同的相邻层级必然异色，多层嵌套时颜色按模 4 循环复用。

嵌套集群（Nested Clusters）实战

在集群内直接再写 with Cluster(...) 即可无限嵌套。官方给出的“事件处理”示例展示了三层结构：Event Flows 包着 Event Workers 与 Processing 两个子集群：

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", show=False):
    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

官方文档原文明确指出：“There is no depth limit to nesting. Feel free to create nested clusters as deep as you want.”（嵌套没有深度上限，可以随意建多深的嵌套集群）。

这个示例还演示了列表节点与集群的批量连接写法：workers 与 handlers 都是 Node 列表，source >> workers >> queue >> handlers 会经由 __rrshift__/__rshift__ 对列表中每个节点逐一建边（diagrams/init.py）。

跨集群连线：边为什么必须挂在全局 Diagram 上

一个容易忽视的底层细节：无论两端节点位于哪些集群，连线（edge）始终添加在全局 Diagram 上，而不是某个集群子图上。见 Node.connect 的注释与实现（diagrams/init.py）：

# An edge must be added on the global diagrams, not a cluster.
self._diagram.connect(self, node, edge)

而节点则是挂在“当前最内层”上下文（集群或全局 Diagram）上。这种“节点入子图、边入主图”的分离正是 Graphviz 子图模型的标准做法，也保证了上面示例中 source（集群外）→ workers（两层嵌套内）这类跨层级连线的正确渲染。

使用要点与常见坑

结合文档与源码，实际使用时建议注意以下几点：

1. 必须在 Diagram 内使用。在 Diagram 上下文之外创建 Cluster 会抛出 EnvironmentError，因为 getdiagram() 返回 None；同理在没有任何上下文时创建节点也会失败。
2. direction 参数要谨慎使用。如前所述，Cluster(direction=...) 目前存在渲染问题（源码 FIXME），非法方向值仍会被校验为 ValueError（合法值为 TB、BT、LR、RL，见 tests/test_diagram.py 的 ClusterTest.test_validate_direction）。
3. graph_attr 可覆盖默认样式。需要 CHANGELOG 中提到的“Support custom graph attributes for the Cluster”能力时，直接传字典即可，例如 Cluster("DB Cluster", graph_attr={"bgcolor": "#fff3cd"}) 覆盖自动背景色。
4. Group 是 Cluster 的别名（diagrams/init.py：Group = Cluster），两种写法等价，团队中统一一种命名即可。
5. 运行环境前提：项目要求 Python ≥ 3.9，并依赖本机安装的 Graphviz 渲染引擎；安装方式为 pip install diagrams（见 README 与 pyproject.toml 中 python = "^3.9"、graphviz >= 0.13.2, < 0.21.0 的依赖声明）。
6. show=False 只保存图片不弹窗，适合 CI 或脚本场景；示例代码中均以此参数避免阻塞。

小结

Cluster 是 diagrams 表达架构边界的核心原语：一个 with 块圈定分组，节点按缩进自动归属，连线跨集群自由建立，嵌套无深度上限且按层级自动着色。其实现依托 contextvars 维护 Diagram/Cluster 双层上下文栈，节点挂子图、边挂主图的分离策略保证了跨层级连接的正确性。配合 节点连接指南 与 Diagram 选项指南，即可完成从单节点、数据流到多层集群分组的完整架构出图。