用 Mermaid 30 分钟搞定网络架构图与时序图：从拓扑到升级计划-港品优选

用 Mermaid 30 分钟搞定网络架构图与时序图：从拓扑到升级计划

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid

痛点：网络文档里的图，永远比现实慢一步

网元拓扑改了，文档里的截图还是三周前的样子。新人照着过期图排查，方向全错。每次更新都得重新打开绘图软件手动画，而需求还在变。不解决，文档迟早没人敢信，事故复盘时拿不出可信的现场图。Mermaid.js 把网络架构图画成文本，改字即改图。

工具定位：用文本语法生成 SVG 图表的 JavaScript 库

Mermaid 是一个基于 JavaScript 的图表库，核心原理很简单：你写类 Markdown 的文本语法，它在浏览器端解析并渲染成 SVG。语法随代码进版本库，图永远不会落后于代码。它适合需要把架构、调用链、状态流转放进文档并持续维护的开发者和运维工程师。

官方入口：README.md、快速上手。

能力速查表：先选图型，再动手

能力	适用任务	对应图表/命令类型
拓扑与流程绘制	部署拓扑、故障排查流程	`flowchart`
服务交互还原	调用链路、协议信令分析	`sequenceDiagram`
状态流转建模	故障处理、协议状态机	`stateDiagram-v2`
排期与发布计划	版本升级、割接窗口	`gantt`
占比统计	故障类型、资源分布	`pie`

以下实战按任务拆分，可按需跳读。

任务式实战：四个可复现的小任务

任务一：画出部署拓扑

目标：拿到一张包含网关、应用、数据库、缓存的部署拓扑图。

下面这段代码用子图（subgraph）分层，虚线连接缓存，数据库节点单独着色，贴进任意 Mermaid 渲染环境即可出图。

看到三层子图、彩色存储节点和无交叉连线，说明跑通了。把应用层节点复制一份、调整LB -->指向，就能画出扩容后的对比图。

静态结构有了，接下来看请求在网元之间怎么流动。

任务二：生成服务调用时序图

目标：拿到一张带激活条、能直接贴进故障复盘文档的调用时序图。

下面这段代码描述一次下单请求，参与者用别名标注中文名，activate控制激活条的显隐，让链路长短一目了然。

参与者上方出现激活条、虚线表示响应，说明语法正确。把某个activate删掉，就能看到该段耗时的占位被缩短。

请求走通了，但故障来了怎么办，状态机比文字更清楚。

任务三：画出网络故障处理状态机

目标：拿到一张可当 SOP 挂在值班群的故障处理状态图。

下面这段代码定义从告警触发到故障恢复的完整状态流转，[*]表示起止点，边上的文字是触发条件。

看到循环回边"复测失败"指向"初步定位"，说明状态机完整。把"自动切换"拆成两个并行分支，可以表达多路径处置预案。

故障处理有了闭环，发布窗口排期用甘特图说话。

任务四：排出版本升级甘特图

目标：拿到一张带里程碑、能直接进周会的升级排期图。

下面这段代码规划 v2.4 升级，milestone标记全量切换节点，任务名里的斜杠表示完成百分比。

时间轴上出现菱形里程碑节点，说明跑通了。把a1的工期从2d改成5d，后段任务会自动顺延。

环境与集成：最小配置的本地跑通

本地快速跑通（二选一）

步骤：

克隆仓库：git clone https://gitcode.com/GitHub_Trending/me/mermaid
cd进项目目录，执行pnpm install
执行pnpm build产出 dist 产物
打开demos/flowchart.html查看内置示例
把下面这段最小页面存成index.html，浏览器打开验证

下面这个 HTML 通过 CDN 加载，一个节点、一条边，是最小可运行版本。

<!DOCTYPE html> <html> <head> <meta charset="utf-8"> <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script> <script>mermaid.initialize({ startOnLoad: true })</script> </head> <body> <pre class="mermaid"> flowchart LR A[网关] --> B[服务] </pre> </body> </html>

页面里出现带箭头的两个节点，说明渲染环境就绪。

嵌入 GitLab Wiki 的最小配置

GitLab Wiki 原生识别 Mermaid，无需装任何插件，配置就一步：在任意 Wiki 页面插入围栏代码块，语言标注为mermaid，保存即渲染。

<pre class="mermaid"> flowchart LR A[网关] --> B[服务] </pre>

保存后 Wiki 里出现渲染好的图，就说明集成完成。

踩坑与调优：先对照这五条

坑：贴进文档后只显示代码不出图。确认代码块围栏标注为mermaid，且加载脚本版本不低于 10，脚本里带上startOnLoad: true。

坑：节点一多就卡。用子图（subgraph）把模块分块，或加%%{init: {"flowchart": {"wrappingWidth": 200}}%%控制换行宽度。

坑：中文标签里的括号、冒号、引号。给标签加双引号包裹，例如A["状态(运行)"]，即可避免解析失败。

坑：subgraph 中文名报错。用显式写法并给标题加引号：subgraph CN["核心网"]，详见 flowchart 语法文档。

坑：跨版本迁移后甘特图不渲染。老版本milestone写法有差异，以 gantt 语法文档的当前写法为准。

行动清单：读完就可以做

用任务一的代码块，生成你项目的部署拓扑，替换掉文档里的截图
用stateDiagram-v2为你的值班流程画一张故障处理状态机
在团队 Wiki 里按任务二加一张服务调用时序图
用gantt画出下个版本升级排期，milestone标记发布日
本地用pnpm install && pnpm build或 CDN 方式验证一次渲染，确认团队环境可复现

把你的第一张图贴到团队文档里试试。

【免费下载链接】mermaidGeneration of diagrams like flowcharts or sequence diagrams from text in a similar manner as markdown项目地址: https://gitcode.com/GitHub_Trending/me/mermaid

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析