架构图文档 (v11.1.0)

🌐 Architecture Diagrams Documentation (v11.1.0+)

在 mermaid-js 的上下文中，架构图用于展示云端或 CI/CD 部署中常见的服务和资源之间的关系。在架构图中，服务（节点）通过边进行连接。相关服务可以放置在组中，以更好地说明它们的组织方式。

示例

🌐 Example

代码:

⌘ + 回车键|

语法

🌐 Syntax

一个架构的构建模块是 groups、services、edges 和 junctions。

🌐 The building blocks of an architecture are groups, services, edges, and junctions.

对于支持的组件，图标通过将图标名称用 () 括起来来声明，而标签通过将文本用 [] 括起来来声明。

🌐 For supporting components, icons are declared by surrounding the icon name with (), while labels are declared by surrounding the text with [].

要开始一个架构图，请使用关键字 architecture-beta，然后列出你的组、服务、边和交汇点。虽然这三个构建块可以以任意顺序声明，但必须确保标识符已由另一个组件先前声明。

🌐 To begin an architecture diagram, use the keyword architecture-beta, followed by your groups, services, edges, and junctions. While each of the 3 building blocks can be declared in any order, care must be taken to ensure the identifier was previously declared by another component.

群组

🌐 Groups

声明一个组的语法是：

🌐 The syntax for declaring a group is:

group {group id}({icon name})[{title}] (in {parent id})?

组合起来：

🌐 Put together:

group public_api(cloud)[Public API]

创建了一个名为 public_api 的组，使用图标 cloud，并带有标签 Public API。

🌐 creates a group identified as public_api, uses the icon cloud, and has the label Public API.

此外，可以使用可选的 in 关键字将组放入另一个组中

🌐 Additionally, groups can be placed within a group using the optional in keyword

group private_api(cloud)[Private API] in public_api

服务

🌐 Services

声明服务的语法是：

🌐 The syntax for declaring a service is:

service {service id}({icon name})[{title}] (in {parent id})?

组合起来：

🌐 Put together:

service database1(database)[My Database]

创建名为 database1 的服务，使用图标 database，标签为 My Database。

🌐 creates the service identified as database1, using the icon database, with the label My Database.

如果该服务属于某个组，可以通过可选的 in 关键字将其放入该组中

🌐 If the service belongs to a group, it can be placed inside it through the optional in keyword

service database1(database)[My Database] in private_api

边缘

🌐 Edges

声明边的语法是：

🌐 The syntax for declaring an edge is:

{serviceId}{{group}}?:{T|B|L|R} {<}?--{>}? {T|B|L|R}:{serviceId}{{group}}?

边的方向

🌐 Edge Direction

边缘从服务的哪一侧出来，可以通过在连接箭头的服务一侧添加冒号（:）并加上 L|R|T|B 来指定

🌐 The side of the service the edge comes out of is specified by adding a colon (:) to the side of the service connecting to the arrow and adding L|R|T|B

例如：

🌐 For example:

db:R -- L:server

在服务 db 和 server 之间创建一条边，该边从 db 的右侧延伸到 server 的左侧。

🌐 creates an edge between the services db and server, with the edge coming out of the right of db and the left of server.

db:T -- L:server

在服务 db 和 server 之间创建一个 90 度的连接边，该边从 db 的顶部和 server 的左侧延出。

🌐 creates a 90 degree edge between the services db and server, with the edge coming out of the top of db and the left of server.

箭头

🌐 Arrows

通过在左侧方向前添加 <，和/或在右侧方向后添加 >，可以在边的每一侧添加箭头。

🌐 Arrows can be added to each side of an edge by adding < before the direction on the left, and/or > after the direction on the right.

例如：

🌐 For example:

subnet:R --> L:gateway

创建一个箭头指向 gateway 服务的边

🌐 creates an edge with the arrow going into the gateway service

组外边

🌐 Edges out of Groups

要使边从一个组转移到另一个组或另一个组内的服务，可以在 serviceId 之后添加 {group} 修饰符。

🌐 To have an edge go from a group to another group or service within another group, the {group} modifier can be added after the serviceId.

例如：

🌐 For example:

service server[Server] in groupOne
service subnet[Subnet] in groupTwo

server{group}:B --> T:subnet{group}

创建一条边，从 groupOne 出发，连接到 server 邻近位置，然后进入 groupTwo，连接到 subnet 邻近位置。

🌐 creates an edge going out of groupOne, adjacent to server, and into groupTwo, adjacent to subnet.

需要注意的是，groupId 不能用于指定边，而 {group} 修饰符只能用于组内的服务。

🌐 It's important to note that groupIds cannot be used for specifying edges and the {group} modifier can only be used for services within a group.

对齐兄弟节点 (v<MERMAID_RELEASE_VERSION>+)

🌐 Aligning siblings (v<MERMAID_RELEASE_VERSION>+)

当多个服务共享相似的边缘拓扑（例如，三个数据库都连接到 R --> L:mcp）时，布局启发式可能会将它们折叠到相同的坐标，从而导致两个服务渲染在彼此之上。 align 指令声明一组服务共享同一行（相同 y 坐标）或同一列（相同 x 坐标），并强制它们沿该轴展开。

🌐 When several services share similar edge topology (for example, three databases all connecting R --> L:mcp), the layout heuristic may collapse them onto the same coordinate so that two render on top of each other. The align directive declares that a set of services share a row (same y) or a column (same x), and forces them to spread along that axis.

align row {idA} {idB} {idC} ...
align column {idA} {idB} ...

成员必须已经声明为服务或交点，并且至少需要两个成员。每个 align 指令都独立占用一行。

🌐 Members must already be declared as services or junctions, and at least two members are required. Each align directive lives on its own line.

根据列出的成员如何连接选择轴：

🌐 Pick the axis based on how the listed members are connected:

• 当成员通过相同的水平端口对（例如都使用 R --> L:mcp）连接到公共下游节点时，使用 align column。它们自然在一侧形成垂直堆叠，并且有平行箭头指向下游节点。
• 当成员通过相同的垂直端口对（例如都使用 B --> T:proc）连接到公共下游节点时，使用 align row。它们自然会在下游节点上方形成一排横向排列。

三个数据库都通过从右到左的边传输到 mcp → 将它们堆叠在一列中：

🌐 Three databases all feeding mcp via right-to-left edges → stack them in a column:

代码:

⌘ + 回车键|

三个来源都通过自上而下的边传输到 proc → 将它们排成一排：

🌐 Three sources all feeding proc via top-to-bottom edges → arrange them in a row:

代码:

⌘ + 回车键|

align 指令中成员的顺序决定了它们沿轴的顺序。对齐成员之间的间隙由 idealEdgeLengthMultiplier 控制。

🌐 The order of members in the align directive determines their order along the axis. The gap between aligned members is controlled by idealEdgeLengthMultiplier.

注意： 声明的顺序不得与列出成员之间的边的方向相矛盾。例如，如果图中包含 a:L --> R:b（它将 a 放置在 b 的右侧），那么 align row a b 将与该边的方向冲突，布局引擎将无法渲染。请改用 align row b a，或移除冲突的边。

网格布局（结合 row 和 column）

🌐 Grid layouts (combining row and column)

align row 仅固定其成员的 y 坐标。要生成一个干净的网格，使得列在不同层之间也能对齐，请将每个 align row 与一个或多个 align column 指令配对。列可以跨越任意数量的行——将每个应共享 x 坐标的节点链在一起，即使跨组也可以。

代码:

⌘ + 回车键|

结果是三个从左到右的层垂直堆叠，中间列有一条直脊柱。对齐节点之间的边渲染为直的水平或垂直线；跨轴边（例如 db_one:R --> T:hub）则有一个 90° 的折角。

🌐 The result is three left-to-right tiers stacked vertically with a straight spine through the middle column. Edges between aligned nodes render as straight horizontal or vertical lines; cross-axis edges (e.g. db_one:R --> T:hub) get a single 90° elbow.

提示： 如果在较小的 iconSize 值时，长的单词标签过宽无法在一行内显示，请增加 iconSize（或使用更短的标题）以保持在一行内。

交汇处

🌐 Junctions

枢纽是一种特殊类型的节点，它可以作为边的潜在四向分叉点。

🌐 Junctions are a special type of node which acts as a potential 4-way split between edges.

声明一个交汇点的语法是：

🌐 The syntax for declaring a junction is:

junction {junction id} (in {parent id})?

代码:

⌘ + 回车键|

配置

🌐 Configuration

randomize（v11.14.0及以上）

🌐 randomize (v11.14.0+)

默认情况下，架构图将节点的起始位置设置在确定性种子位置（randomize: false）。将 randomize 设置为 true 会在运行布局算法之前随机化初始节点位置，这可能在每次渲染时产生不同但可能间距更好的布局。

🌐 By default, architecture diagrams start nodes at deterministic seed positions (randomize: false). Setting randomize to true randomizes initial node positions before running the layout algorithm, which may produce varied but potentially better-spaced layouts on each render.

注意：仅使用 randomize: false 并不足以保证渲染完全相同 —— 底层的 fcose 布局在其约束求解器中仍然会调用 Math.random()。使用下面描述的 seed 选项可以完全锁定布局。

通过前言部分：

🌐 Via frontmatter:

%%{init: {"architecture": {"randomize": true}}}%%
architecture-beta
    group api(cloud)[API]
    service db(database)[Database] in api
    service server(server)[Server] in api
    db:R --> L:server

通过 mermaid.initialize()：

🌐 Via mermaid.initialize():

mermaid.initialize({
  architecture: {
    randomize: true,
  },
});

选项	类型	默认值	描述
randomize	布尔值	false	在运行布局之前是否随机化初始节点位置。

布局调整 (v11.15.0+)

🌐 Layout tuning (v11.15.0+)

以下选项会传递到底层的 fcose 布局，因此你可以在不更改图表源的情况下调整间距和密度：

🌐 The following options pass through to the underlying fcose layout so you can adjust spacing and density without changing your diagram source:

选项	类型	默认值	描述
nodeSeparation	数字	75	同一组中兄弟节点之间的最小间距，单位为像素。传递给 fcose。
idealEdgeLengthMultiplier	数字	1.5	应用于 iconSize 的乘数，用于计算同一组内节点之间边的理想长度。增加以获得更多空间，减少以更紧凑排列。跨组边不受影响。
edgeElasticity	数字	0.45	同组边的弹性（0–1）。数值越高，会将连接的节点拉得更近；数值越低，会让它们分散开。跨组边不受影响。
numIter	数字	2500	最大 fcose 迭代次数。在大型图表上增加以获得更高质量的布局，但会增加渲染时间。
seed	数字	1	fcose 的确定性种子。默认为 1，因此相同的图始终以相同的布局渲染。设置为 0 可选择退出并使用本地（非确定性）Math.random。任何其他数字将选择不同的可重现布局变体。

示例 — 推动 idealEdgeLengthMultiplier 会拉伸链中连接节点之间的间距：

🌐 Example — bumping idealEdgeLengthMultiplier stretches the spacing between connected nodes in a chain:

%%{init: {"architecture": {"idealEdgeLengthMultiplier": 3}}}%%
architecture-beta
    service a(server)[A]
    service b(server)[B]
    service c(server)[C]
    a:R --> L:b
    b:R --> L:c

注意： 这些旋钮用于调节 fcose 的力导向布局；它们不会改变布局启发式算法认为相邻的节点。如果两个兄弟节点因为在空间地图中共享相同的逻辑位置而重叠渲染（#6120 已跟踪的已知限制），无论如何调整这些旋钮都无法将它们分开 — 请参阅即将推出的 align row|column 指令。

图标

🌐 Icons

默认情况下，架构图支持以下图标：cloud、database、disk、internet、server。用户可以使用 iconify.design 上提供的 200,000+ 图标中的任何图标，或通过注册图标包添加其他自定义图标。

🌐 By default, architecture diagram supports the following icons: cloud, database, disk, internet, server. Users can use any of the 200,000+ icons available in iconify.design, or add other custom icons, by registering an icon pack.

图标安装完成后，可以在架构图中使用格式“name:icon-name”来使用它们，其中 name 是注册图标包时使用的值。

🌐 After the icons are installed, they can be used in the architecture diagram by using the format "name:icon-name", where name is the value used when registering the icon pack.

代码:

⌘ + 回车键|