Mermaid Architecture 架构图实战指南：用 architecture-beta 绘制云基础设施拓扑

Mermaid Architecture 架构图实战指南：用 architecture-beta 绘制云基础设施拓扑

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills

导读

本文是 scientific-agent-skills 仓库中 markdown-mermaid-writing 技能体系下的 Architecture 图类型完整指南，围绕 architecture.md 展开。该技能确立了"以 Markdown 内嵌 Mermaid 图表作为默认文档标准"的规范，而architecture-beta正是其中用于表达云基础设施、服务拓扑、部署架构、网络布局的专属语法。读完本文，你将掌握group/service/in三层核心语法、方向注释连线规则、内置图标类型的使用边界，并能直接复制生产级示例与模板，绘制出符合可访问性要求、可在 GitHub 明暗双主题下稳定渲染的架构图。

一、为什么需要专门的架构图语法

在 mermaid_style_guide.md 的"Choosing the Right Diagram"选择表中，Mermaid 共覆盖 24 种图类型，其中与"系统结构"相关的就有 Flowchart、C4、Block、Architecture 四种。选对类型，而不是默认用流程图，是该技能反复强调的第一原则：

• Flowchart（flowchart.md）：表达顺序流程、工作流、决策逻辑、排障树；
• C4（c4.md）：表达系统架构的不同缩放层级（Context / Container / Component），面向逻辑系统边界；
• Block（block.md）：表达组件布局、分层架构，侧重空间排布；
• Architecture（architecture-beta）：表达云基础设施、服务拓扑、部署架构、网络布局，带云语义图标。

三者的边界在 architecture.md 中定义得十分明确：

⚠️无障碍前置要求：与 Flowchart、Sequence、C4 等类型不同，Architecture 图不支持accTitle/accDescr。因此必须在代码块正上方放置一段描述性的斜体Markdown 段落，供屏幕阅读器与文本检索使用。这一规则同样适用于 Mindmap、Timeline、Quadrant、Sankey、XY Chart、Block、Kanban、Packet、Radar、Treemap（见 mermaid_style_guide.md 的 Accessibility Requirements 一节）。

二、语法基础：group、service 与 in

architecture-beta的核心语法只有三组概念，理解它们即可覆盖 90% 的绘图需求：

1.group— 逻辑边界

用group表达逻辑容器：VPC、区域（Region）、集群、可用区（Availability Zone）。

语法结构为group 节点id(图标类型)[标签]，其中(cloud)指定图标类型。group图标类型同样从内置图标集中选取（参见下文）。

2.service— 单个组件

用service表达独立部署的组件：负载均衡器、API 服务器、数据库、缓存等。

语法结构为service 节点id(图标类型)[标签] in 父组id。in关键字将节点放入已声明的组中。

3. 连线与方向注释

节点之间的连线是架构图最有特色的部分——每条边都必须声明连接锚点方向：

方向注释语法为源节点:方向 --> 方向:目标节点，支持四个方位：

• :L— 左侧（left）
• :R— 右侧（right）
• :T— 顶部（top）
• :B— 底部（bottom）

关于方向注释，有两个必须记住的要点：

• 方向注释是防重叠的关键手段。api:B --> T:cache表达"从 api 底部连到 cache 顶部"，lb:R --> L:api表达"从 lb 右侧连到 api 左侧"。若省略方向注释，Mermaid 会把边全部堆叠在一起，导致图面混乱（见 architecture.md 复杂示例的 "Why this works" 说明）。
• -->的箭头语法对空格严格敏感，必须严格按lb:R --> L:api这种格式书写（该陷阱被明确记录在 mermaid_style_guide.md 的 "Known Parser Gotchas" 表格中）。

4. 内置图标类型

Architecture 图提供一组内置图标类型，直接写在( )中：

三、示例图：云托管 Web 应用

下面这段来自 architecture.md 的示例，展示了一个部署在 VPC 内的云托管 Web 应用：负载均衡器、API 服务器、数据库与缓存四类组件。注意代码块上方必须放置描述性斜体段落以满足可访问性要求：

Architecture diagram showing a cloud-hosted web application with a load balancer, API server, database, and cache deployed within a VPC:

阅读这段代码时可以拆解为三个层次：

1. 分组层：cloud组代表整个云平台，vpc组通过in cloud嵌套其中，形成"云 → VPC"的两级逻辑边界；
2. 组件层：四个service通过in vpc全部归属 VPC，分别使用internet、server、database、disk四种图标区分角色；
3. 连线层：三条边全部带方向注释——lb:R --> L:api表示负载均衡右侧连 API 左侧，api:R --> L:db表示 API 到数据库，api:B --> T:cache表示 API 底部连缓存顶部。

四、核心操作要点（Tips 全览）

architecture.md 给出了 8 条经过验证的操作要点，逐条解读如下：

1. 用group表达逻辑边界——VPC、区域、集群、可用区都是典型的 group 场景；
2. 用service表达单个组件——每个部署单元一个 service；
3. 连线必须带方向注释——:L（左）、:R（右）、:T（顶）、:B（底），用于控制边的连接锚点；
4. 内置图标类型共五种——cloud、server、database、internet、disk；
5. 用in parent_group嵌套组——支持多级嵌套（如 region in cloud）；
6. 标签必须是纯文本——[]标签内禁用 emoji、禁用连字符。这是最重要的坑之一：解析器会把-当作边的操作符（edge operator），因此[US-East Region]会导致解析失败，必须写成[US East Region]；
7. 用-->表示有向箭头，--表示无向边；
8. 每个图控制在 6–8 个 service——超出会显著降低可读性；
9. 始终搭配上方文字描述——供屏幕阅读器使用（对应可访问性规则）。

⚠️标签纯文本规则的深层原因：Emoji 与连字符这两个限制都被 mermaid_style_guide.md 的 "Known Parser Gotchas" 表单独列出——Architecture 图中[]标签内出现 emoji 会导致解析错误；连字符会被解析为边操作符。因此 Architecture 图的视觉区分完全依赖组嵌套与图标类型（internet、server、database），这也是它与其他图类型（如允许 emoji 的 Flowchart、Block）在风格上的关键差异。

五、开箱即用的模板

以下模板可直接复制使用。_Description of the infrastructure topology and key components:_为必填的斜体说明段，请替换为你的实际描述：

Description of the infrastructure topology and key components:

模板结构解读：一个group表达云区域，三个service表达前端、后端、数据存储三层，两条:R --> L:横向连线表达请求从左向右流动。这是最简单的三层架构表达，任何云平台（AWS、GCP、Azure）的入门部署图都可由此扩展。

六、复杂示例：多区域云部署

当需要表达多区域、跨区复制、CDN 分发、集中监控这类真实基础设施拓扑时，group+in的嵌套能力便派上用场。architecture.md 提供了一个 3 层嵌套组、9 个 service 的生产级复杂示例：

Multi-region cloud deployment with 3 nested groups (2 regional clusters + shared services) showing 9 services, cross-region database replication, CDN distribution, and centralized monitoring. Demonstrates how nestedgroup+insyntax creates clear infrastructure boundaries:

这个复杂示例为什么有效

原文档从四个角度解释了该设计的合理性，这也是任何大规模架构图的通用准则：

• 嵌套组镜像真实基础设施——cloud > region > services正是团队思考多区域部署的方式，嵌套天然划清了爆炸半径（blast radius）边界；
• 仅用纯文本标签——Architecture 图在[]标签中使用 emoji 会解析失败，所有视觉区分都来自组嵌套与图标类型（internet、server、database）；
• 方向注释防止重叠——cdn:B --> T:lb_east（底到顶）、db_primary:R --> L:db_replica（右到左）精确控制边连接锚点；如果省略这些注释，Mermaid 会把边堆叠在一起；
• 跨区域复制被显式表达——db_primary:R --> L:db_replica这条边是全图最重要的基础设施细节，它以一条清晰的横向连接在区域之间阅读起来一目了然。

连线方向小结：cdn:B --> T:表示 CDN 底部向下分发流量，lb_east:R --> L:与db_primary:R --> L:表示东西向流量与数据复制，app_east:B --> T:db_primary表示南北向的数据访问——方向注释组合起来正好还原了真实流量路径。

七、何时不要用 Architecture 图

原文档在开头就明确划定了 Architecture 图的边界，这里结合仓库中对应的替代图类型（c4.md 与 block.md）展开说明：

判断口诀：有云图标语义 → Architecture；有逻辑系统边界 → C4；有空间布局需求 → Block；有流程与决策 → Flowchart。

八、可访问性与风格合规自查

Architecture 图在 mermaid_style_guide.md 中属于"不支持accTitle/accDescr的 11 种类型"之一，因此在每次使用 Architecture 图之前，请对照以下清单逐项检查：

• 代码块正上方是否有描述性的斜体Markdown 段落（替代accTitle/accDescr）？
• []标签是否为纯文本——无 emoji、无连字符？
• 每条连线是否都带方向注释（:L/:R/:T/:B），且-->两侧空格正确？
• 是否控制 service 数量在 6–8 个以内？（本仓库复杂示例虽有 9 个 service，但以三个嵌套组消化了复杂度）
• 是否使用了语义化的snake_case节点 ID（如db_primary、lb_east，而非a、b）？
• 是否有%%{init}主题指令或内联style？—— 两者都会被 GitHub 深色模式破坏，必须改用classDef+class（该规则适用于所有图类型，见 mermaid_style_guide.md 的 Theme Configuration 一节）；
• 是否在 GitHub 明、暗两种主题下分别验证过渲染效果？

九、快速参考卡片

最后，将本指南压缩为一张可直接查阅的速查表：

本指南属于 markdown-mermaid-writing 技能下 24 种图类型指南之一。完整的图类型选择表、GitHub 兼容色板（classDef调色板）、emoji 语义集以及全部解析器陷阱，请查阅 mermaid_style_guide.md；文档排版、引用与标题规范见 markdown_style_guide.md。当单个 Architecture 图无法覆盖全部视角时，可参考 complex_examples.md 中的 "Overview + Detail" 与 "Before/After Architecture" 组合模式（例如"迁移项目"场景建议用 Gantt 排期 + Architecture 表达迁移前后拓扑 + Flowchart 表达迁移流程），将多张图组合成一套完整的系统文档。

【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000+ scientists worldwide. 165 ready-to-use validated skills plus 100+ scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills