架构图怎么画？软件团队的分步指南

第一次画架构图时，难点不在于画框，而在于决定哪些东西不画。本文讲的是软件和系统架构图怎么画：服务、数据库、队列、网络区域，以及它们之间的连接。无论这是你的第一张软件架构图，还是团队的第十张，按照下面的步骤，都能画出一张别人看得懂、并且能持续保持最新的图。

先确定读者和问题

一张好的架构图只回答一个问题。“我们系统里的所有东西”不是问题，而是一份清单，清单更适合放在表格里。

动笔之前，先写下两句话：

• 谁来读？ 刚入职的开发、值班的 SRE、安全评审、产品经理、外部审计。
• 它回答什么问题？ “一个下单请求会经过哪些服务？”“哪些组件暴露在公网上？”“某个区域故障时流量会去哪里？”

这两句话决定了图的范围。新入职的开发需要的细节和网络团队需要的不一样。想用一张图同时满足两者，结果往往是谁都没满足。

选择图的类型

问题清楚了，图的类型基本也就定了。C4 模型是个不错的起点：它把系统分成 context、container、component、code 几个缩放层级（详见 c4model.com）。

拿不准的时候，就从系统上下文图开始。它能把系统边界和外部依赖讲清楚，也为后面的图提供框架。

架构图怎么画：分步骤说明

1. 确定范围和边界

写下图里包含什么、哪些留在外面。你的团队负责的组件放在边界内；支付服务商、身份提供商或其他团队的服务这类依赖放在边界外。每个外部系统只画成一个框，它的内部结构不需要你来画。

2. 列出组件

动笔前先列清单：服务、数据库、队列、缓存、外部 API、用户类型。用团队实际使用的名字；如果能和仓库名或 deployment 名一一对应就更好了。如果清单长到一眼看不完，多半说明应该拆成两张图。

3. 用带标签的有向箭头画出关系

没有标签的线只能告诉读者两个东西“有某种关系”。给每个箭头加上方向，并至少标出两项信息：协议和意图。必要时再注明是同步还是异步。

checkout-web  --[HTTPS/JSON · POST /orders · sync]-->  order-api
order-api     --[AMQP · order.created · async]------>  orders-queue
order-api     --[TCP 5432 · SQL · read/write]------->  orders-db

箭头从调用方指向接收方。不要再为响应画第二根箭头，那只会让线条数量翻倍。如果请求和响应的先后顺序很重要，那正是时序图要做的事。

4. 用 frame 分组

分组是图的第二层信息。把组件放进有实际含义的边界里：

• 网络区域： 公有子网、私有子网、DMZ、本地机房网络
• Kubernetes namespace： payments、platform、observability
• 区域和账号： eu-central-1、us-east-1、生产和预发账号
• 信任边界： 来自公网的流量在哪里完成认证

可以嵌套（区域 > VPC > 子网），但层级越深，图就越难读。

5. 加上图例

如果颜色、线型或图标带有含义，就必须写进图例。虚线代表异步消息吗？红框代表 PCI 范围吗？画图的人觉得一目了然的东西，半年后看图的人未必明白。

6. 写上标题、日期和负责人

每张图的角落都应该有三项信息：说明图内容的标题（“Checkout — 容器图，生产环境”）、最后更新日期，以及负责的团队。没有日期的图，没人知道它是否还准确；没有负责人的图，也没人会去更新。

7. 请没画过这张图的人来评审

把图拿给没参与绘制的人看，问他你一开始写下的那个问题。如果他不需要你解释就能找到答案，这张图就合格了。如果你一直在说“这里其实是指……”，那就把这句解释直接写进图里。

常见错误

• 把所有东西塞进一张图。 上下文、部署和网络细节混在一起，最后哪部分都没人看。
• 箭头没有标签，或者是双向箭头。 谁调用谁说不清楚，而这恰恰是处理故障时最需要的信息。
• 抽象层级混杂。 一个框叫“支付系统”，旁边的框却是“Redis pod”，读者会失去尺度感。
• 颜色没有说明。 图例里没有的颜色，要么只是装饰，要么会被误读。
• 没有负责人和日期。 放在 Wiki 上、不知道是谁画的图，迟早会变成错误信息的来源。

让架构图保持最新

架构图只有在被信任时才有用。几个习惯会有帮助：

• 把图放在所描述系统的文档旁边，并在 README 或 runbook 里加上链接。
• 在会改动架构的 pull request 检查清单里加一项“架构图更新了吗？”。
• 大的改动之前先保留一个版本，这样“上个季度是什么样？”就有据可查。
• 在负责团队的日历上安排定期评审，比如每季度一次。

在 Archboard 中画软件架构图

Archboard 是一个面向平台团队和产品团队的云端架构工作空间。上面的步骤在任何工具里都适用，在 Archboard 中是这样做的：

1. 登录。 通过登录页面使用 Google 或 GitHub 账号登录。首次登录会自动创建账号和组织，无需信用卡。
2. 选择节点包。 Archboard 内置 27 个节点包、223 种节点类型。画第一张图时，通常这几个就够了：
   • C4 Model： Person、Software System、Container、Component、Database 和 boundary，用于上下文图和容器图。
   • Kubernetes： Namespace（以 frame 形式绘制）、Deployment、Pod、Service、Ingress、ConfigMap、Secret、PVC、HPA、NetworkPolicy 等。
   • Cloud： 用于云基础设施，包含用于多账号架构图的 k8s-cluster 节点。
   • Network： 用于网络区域和链路。
3. 连接端口。 节点不是普通图形，而是带端口的一等节点。从一个端口拖出连线到另一个端口，并在标签里写上协议和意图。
4. 用 frame 分组。 用 Core 包里的 Frame 表示网络区域和区域（region），用 Kubernetes 的 Namespace 表示 namespace，用 C4 的 boundary 表示系统边界。
5. 加上标题和图例。 在画布上放一个 Markdown 块或 Table，把标题、日期、负责人和图例集中在一处。
6. 分享。 把公开分享链接发给评审的人（免费版链接带有 Archboard 品牌标识）。Pro 和 Enterprise 版可以通过 iframe 把图嵌入你的文档站点。
7. 导出。 可导出 SVG 或 PNG（免费版带水印）；Pro 版还支持 JPEG、PDF 和动画 GIF / WebM，全部无水印。也可以把图的文档导出为结构化 JSON。

所有更改都会自动保存，每张图都保留修订版本：Free 计划保留最近 5 个版本，Pro 保留一年的历史，Enterprise 则没有时间限制。Free 包含全部内置节点包、3 张图以及每张图 15 个图表节点和 150 个便签、文本、贴纸和思维导图主题，画第一张上下文图绰绰有余；如果要绘制完整的部署地图，Pro 可解锁无限的图和节点。详情请见价格页面。

开始之前，先浏览一下示例图库：打开一个公开示例，用使用此示例把它复制到你的工作区（计入你的图表配额）。C4 和 Kubernetes 的具体用法，请参见 C4 使用场景和 Kubernetes 使用场景页面。最初的想法也可以在同一块画布上开始：Archboard 在架构节点包旁边还提供便利贴和思维导图。

检查清单和常见问题

发布之前检查：

• 已写下读者和问题
• 边界清晰，外部系统各用一个框表示
• 每个箭头都有方向，并标注了协议和意图
• 分组对应真实的边界：网络区域、namespace、区域
• 有图例、标题、日期和负责人
• 没画过这张图的人能回答那个问题

架构图和流程图有什么区别？ 架构图展示结构：有哪些组件，它们如何连接。流程图展示一个流程的步骤和判断节点。如果请求在时间上的先后顺序很重要，请用时序图。

应该画几张图？ 每一组“读者 + 问题”对应一张。对大多数系统来说，先画一张上下文图、一张容器图和一张部署图是不错的开始。

应该用什么工具？ 用一个懂你所画概念的工具。Archboard 把 Kubernetes、C4 和云概念做成带端口的现成节点，让图保持清晰易读，也更容易保持最新。无论选择什么工具，真正的检验标准是这张图能否回答你的问题。

免费开始 — 1 个席位，无需信用卡