aws-architecture-diagram

AWS 架构图技能

使用官方 AWS Architecture Icons 将 AWS 架构图生成为原生 .drawio 文件。还可选择导出为 PNG、SVG 或 PDF，并嵌入 XML（使导出的文件仍可在 draw.io 中编辑）。

如何创建图表

1. 生成 draw.io XML，采用 mxGraphModel 格式并遵循以下规则
2. 使用 Write 工具将 XML 写入 .drawio 文件
3. 如果用户要求导出格式（png、svg、pdf），使用 draw.io CLI 导出（参见“导出”部分）
4. 使用 open（macOS）、xdg-open（Linux）打开结果，或打印文件路径

布局规则

• 数据／请求路径采用从左到右的流程
• UI／前端位于左侧（用户从左侧访问）
• 数据源／外部系统位于右侧
• 并行路径使用水平泳道（上方泳道、下方泳道）
• 图标之间至少保持 220px 的水平间距（为边标签留出空间）
• 泳道之间至少保持 250px 的垂直间距
• 辅助服务（监控、DLQ）放在主流程下方，间距至少为 280px
• 画布：pageWidth="2400" pageHeight="1400"，视口 dx="2800" dy="1600"
• 背景矩形之后始终添加标题块：

<mxCell value="&lt;b&gt;Diagram Title&lt;/b&gt;&lt;br&gt;Author | Date | Version" style="text;html=1;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=14;spacing=8;" vertex="1" parent="1">
  <mxGeometry x="40" y="30" width="420" height="60" as="geometry" />
</mxCell>

图标样式

• 图标来自 draw.io 内置的 mxgraph.aws4 模板库，即官方 AWS Architecture Icons（https://aws.amazon.com/architecture/icons/）
• 图标尺寸：主服务为 78x78px，辅助服务为 65x65px
• 所有图标均使用 sketch=0
• 所有 AWS 服务图标均使用 strokeColor=#ffffff
• 标签字号：12px
• 分组框不得使用彩色背景——始终使用 fillColor=none

3D／等距图——使用不同的图标库

如果用户要求 3D、等距或“AWS 3D”图表，不要把扁平的 aws4 图标放在手工绘制的平台／底座形状上来伪造 3D 效果。draw.io 提供了一个真正独立的内置图标库：mxgraph.aws3d.*。

• 选择图标前，先加载 references/aws-icons-3d.md——其中包含经过验证的形状表、样式前缀、尺寸和原生 isometricEdgeStyle 边模板。
• 此图标库是 2019 年之前的旧版图标集，覆盖范围远小于 aws4（不包含 API Gateway、ECS/EKS/Fargate、Step Functions、EventBridge、SNS、Aurora、CloudWatch、IAM 等）。在假定存在某个图标前，先查看该参考文件中的缺失项表；不要猜测模板名称，如需使用替代图标，请告知用户。
• 对于没有 AWS 专属图标的通用硬件（客户端、本地服务器、机架、交换机），请参阅 references/aws-icons-allied-telesis.md——这是一个独立捆绑的等距图像库，可补足这些需求。
• 这些图标本身已经是 3D 效果——请将它们排列成向上延伸的等距阶梯（节点之间采用对角偏移），不要在下方添加伪造的平台。
• 连接线使用 edgeStyle=isometricEdgeStyle（并使用 endArrow=block 覆盖设置，以确保箭头正常显示），而不是 orthogonalEdgeStyle。

边的样式 — 对绘制清晰的图表至关重要

基本边样式：

edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;

边标签规则：

• 标签要简短（最多 1～2 个词）。详细信息放在图标标签中，不要放在边标签中。
• 对带标签的边，始终添加 labelBackgroundColor=#F5F5F5;fontSize=11;
• 对不带标签的边：完全省略 value
• 无需添加标签的情况：流程显而易见时（Lambda → DynamoDB 不需要标注“写入”）

对于指向主流程上方或下方服务的边，请使用明确的退出点／进入点：

• 底部退出：exitX=0.5;exitY=1;exitDx=0;exitDy=0;
• 顶部进入：entryX=0.5;entryY=0;entryDx=0;entryDy=0;
• 这样可以避免 draw.io 绘制的连线穿过其他图标

边的类型：

• 实线（strokeWidth=2）：主要数据流
• 虚线（strokeWidth=2;dashed=1;）：可选／异步
• 红色虚线（strokeWidth=2;dashed=1;strokeColor=#DD344C;）：错误路径

边的连接（至关重要 — 解决“绿色十字”问题）：

• 每条边都必须包含 source="<cell-id>" 和 target="<cell-id>" 属性，并引用有效的单元格 ID
• 切勿创建悬空／未连接的边 — 所有边的两端都必须连接到形状
• 始终包含 exitX/exitY 和 entryX/entryY，以定义形状周边的精确连接点
• **跨容器边：**当源和目标位于不同容器中时，将边的 parent="1"

视觉质量：箭头笔直、无重叠、布局专业

图表即使图标正确，但布局杂乱，依然会显得不专业。完成前，请根据以下规则检查每张图表——这些规则刻意写得具体且可检查，而不是含糊地建议“让它看起来漂亮”：

• 将节点对齐到一致的轴线上，使边由单条直线段组成。 在流程中让相邻节点之间的水平或垂直偏移保持一致（同一泳道的 y 坐标、相同的列间距），这样连接边才会呈现为一条干净的直线，而不是折线。
• 将分支节点／次级节点精确对齐到其父节点的中心线上。 如果某个节点从垂直方向分支出来（例如位于主流程下方的辅助服务），其水平中心必须与父节点的水平中心完全一致——计算 child.x = parent.center_x - child.width/2，不要凭目测摆放。几像素的偏差就会让“垂直向下”的边变成明显歪斜的对角线。
• 每条边最多拐弯一次，最好不要拐弯。 如果计算出的边路径需要拐弯超过一次才能避开障碍物，说明布局有问题——移动节点，不要增加拐弯来绕行。
• 边不得穿过无关图标的边界框。 确定坐标前，检查每条边的路径是否会穿过它未连接的图标的 (x, y, width, height) 矩形。如果会，就移动节点，或添加明确的出口／入口点来绕行。
• 边不得彼此重叠或在视觉上融为一体。 如果两条边会沿同一条通道行进（例如两条平行流程位于相同的泳道之间），就将它们错开——使用不同的出口／入口点，或添加明确的路径点，确保两条边之间有可见间距。
• 尽可能减少边的交叉。 按照数据的实际流向排列节点，让边尽量不必彼此交叉。如果无法避免交叉（例如反馈／响应路径），则通过明显错开的路径进行布线，而不要让它与另一条边重叠。
• 保持间距一致，而不只是“足够”。 流程中每对相邻节点之间都使用相同的最小步长——有些间隔为 400px、有些为 250px 的图表，即使没有任何实际重叠，看起来也会很随意。
• 让画布上的构图保持平衡。 不要让页面一半内容密集、另一半空空荡荡；根据实际内容和一致的边距设置画布尺寸。
• 完成前自检： 放置每个坐标后，在脑海中从起点到终点追踪每条边，并确认 (1) 不会穿过任何图标，(2) 不会与其他边重叠，(3) 最多拐弯一次，(4) 端点与所连接的图标边缘齐平。如果任何一项不符合，就修正布局，而不只是停留在意图上。

PNG 导出背景

根单元格之后的第一个元素（z-order 最低）：

<mxCell value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#F5F5F5;strokeColor=none;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="2400" height="1400" as="geometry" />
</mxCell>

AWS 图标模式（已验证可用）

resourceIcon（78x78，彩色方形边框）

服务	resIcon	fillColor
Lambda	mxgraph.aws4.lambda	#ED7100
API Gateway	mxgraph.aws4.api_gateway	#E7157B
EventBridge	mxgraph.aws4.eventbridge	#E7157B
SNS	mxgraph.aws4.sns	#E7157B
SES	mxgraph.aws4.simple_email_service	#DD344C
Step Functions	mxgraph.aws4.step_functions	#E7157B
DynamoDB	mxgraph.aws4.dynamodb	#C925D1
RDS	mxgraph.aws4.rds	#C925D1
S3	mxgraph.aws4.s3	#7AA116
CloudFront	mxgraph.aws4.cloudfront	#8C4FFF
Route 53	mxgraph.aws4.route_53	#8C4FFF
ECS	mxgraph.aws4.ecs	#ED7100
EC2	mxgraph.aws4.ec2	#ED7100

样式模板：

sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;fillColor=<COLOR>;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.<SERVICE>

productIcon（70x100，更高，带服务标题栏）

服务	prIcon
SQS	mxgraph.aws4.sqs

样式模板：

sketch=0;outlineConnect=0;fontColor=#232F3E;gradientColor=none;strokeColor=#ffffff;fillColor=#232F3E;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;whiteSpace=wrap;fontSize=12;fontStyle=0;shape=mxgraph.aws4.productIcon;prIcon=mxgraph.aws4.<SERVICE>

独立形状（无需 resIcon）

形状	形状值	fillColor
客户端/浏览器	mxgraph.aws4.client	#232F3D
传统服务器	mxgraph.aws4.traditional_server	#232F3D
防火墙	mxgraph.aws4.generic_firewall	#232F3D
ALB	mxgraph.aws4.application_load_balancer	#8C4FFF
NLB	mxgraph.aws4.network_load_balancer	#8C4FFF
VPC 端点	mxgraph.aws4.endpoints	#8C4FFF

分组边界

分组	grIcon	strokeColor
AWS 云	mxgraph.aws4.group_aws_cloud_alt	#232F3E
账户	mxgraph.aws4.group_account	#CD2264
本地部署	mxgraph.aws4.group_on_premise	#5A6C86
企业数据中心	mxgraph.aws4.group_corporate_data_center	#388E3C
VPC	mxgraph.aws4.group_vpc2	#8C4FFF
子网（公有）	mxgraph.aws4.group_security_group	#7AA116
子网（私有）	mxgraph.aws4.group_security_group	#147EBA

容器嵌套（分组的关键）：

• 所有分组/边界形状的样式都必须包含 container=1;dropTarget=1;
• 边界内的子单元格必须设置 parent="<boundary-cell-id>"，而不是 parent="1"
• 这样移动边界时，其所有子项都会一起移动
• 子项的几何坐标是相对于父容器的，而不是画布
• **跨容器边：**源和目标位于不同容器时，将边的 parent="1"

已损坏的图标 — 请勿使用

• resIcon=mxgraph.aws4.dynamodb_table — 会渲染为空白色块
• resIcon=mxgraph.aws4.dynamodb_stream — 会渲染为空白色块
• resIcon=mxgraph.aws4.general_saml_token — 会渲染为黑色方块
• resIcon=mxgraph.aws4.endpoint — 可能无法渲染
• resIcon=mxgraph.aws4.kinesis_data_streams — 渲染不稳定

替代方案：

• DynamoDB 表/流 → 使用 resIcon=mxgraph.aws4.dynamodb 并添加描述性标签
• 外部系统 → 使用 shape=mxgraph.aws4.traditional_server
• 浏览器/客户端 → 使用 shape=mxgraph.aws4.client

受众模式

生成前，评估目标受众：

• **技术受众：**使用服务名称、协议标签（HTTPS、gRPC）、CIDR 网段、实例类型
• **非技术受众：**使用操作标签（“存储数据”“发送通知”），隐藏实现细节，使用带编号的流程（① ② ③）

如果不确定，请询问：“面向技术受众还是高管/非技术受众？”

带编号的流程边（用于非技术模式）

不要使用技术标签，而是用带圈数字显示流程顺序：

• 流程 A：① → ② → ③ → ④（白色带圈数字）
• 流程 B：❶ → ❷ → ❸ → ❹（第二条流程使用黑色带圈数字）

使用边标签：value="①"，并设置 fontSize=14;fontStyle=1;labelBackgroundColor=#ffffff;

配套指南

生成 .drawio 文件后，还要生成一份 markdown 指南：

• 使用相同文件名，扩展名为 .md
• 内容：图表标题、流程说明（带编号步骤）、服务列表及其用途、关键设计决策

两步编辑方法

生成初始 .drawio 文件后：

1. 导出为 PNG，使用 draw.io CLI（参见导出部分）
2. 目视检查 PNG — 检查是否有空白/损坏的图标、边是否重叠、标签是否未对齐
3. 在 .drawio XML 中修复问题并重新导出

这能发现原始 XML 中无法直接看出的渲染问题（错误的 stencil 名称、损坏的样式）。

图标名称注意事项 — 至关重要

draw.io 模板名称并不总是与当前 AWS 服务名称一致。更名后的服务仍保留旧的模板名称：

AWS 服务名称	draw.io resIcon 名称	原因
Amazon OpenSearch Service	elasticsearch_service	2021 年从 Elasticsearch 更名；opensearch_service 也可用
Amazon EventBridge	eventbridge	原名为 CloudWatch Events
AWS Fargate	fargate	正确
VPC Peering	peering	资源级：shape=mxgraph.aws4.peering;strokeColor=none — 不是 vpc_peering 或 peering_connection（这些会渲染为空白方框）
Amazon MSK	managed_streaming_for_kafka	不是 msk（会渲染为空白方框）
IAM Identity Center	single_sign_on	不是 iam_identity_center（会渲染为空白方框）

规则： 始终从参考文件中确认图标名称。如果服务图标渲染为空方框，则模板名称有误。请在 src/main/webapp/js/diagramly/sidebar/Sidebar-AWS4.js 中检查 draw.io 源码以获取规范名称（对于旧版 3D/等距视图库，请检查 Sidebar-AWS3D.js；对于通用硬件图像库，请检查 Sidebar-AlliedTelesis.js — 注意，3D 库的形状名称采用驼峰命名法，例如 dynamoDb 而不是 dynamodb）。

未映射服务的后备方案： 如果在任何参考文件中都找不到某项服务，请使用此通用 AWS 云图标，并将服务名称作为标签：

sketch=0;outlineConnect=0;fontColor=#232F3E;fillColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.general_AWScloud

切勿将未知服务渲染成没有标签的纯色矩形。

验证步骤

生成 XML 后，请确认：

1. 每个 resIcon= 值都存在于参考文件中
2. 服务级图标具有 strokeColor=#ffffff
3. 资源级图标具有 strokeColor=none
4. 不包含 XML 注释
5. 所有单元格 ID 都唯一
6. 每条边都包含 <mxGeometry relative="1" as="geometry" />
7. 图标未使用猜测的模板名称 — 所有名称均已对照参考文件验证
8. 每条边都具有 source 和 target 属性，且引用有效的单元格 ID（不存在悬空边）
9. 所有组/边界形状的样式都包含 container=1;dropTarget=1;
10. 边界内的子项使用 parent="<boundary-id>"（而不是 parent="1"）

导出

使用 draw.io Desktop CLI 导出 PNG/SVG/PDF：

多页图表

对于复杂架构，请在一个 .drawio 文件中使用多个页面：

<mxfile>
  <diagram id="overview" name="Overview">...</diagram>
  <diagram id="networking" name="Networking Detail">...</diagram>
  <diagram id="data-flow" name="Data Flow">...</diagram>
</mxfile>

• 第 1 页：高层概览（仅使用服务级图标）
• 第 2 页及后续页面：详细视图（资源级图标、子网布局等）

图例 / 标题栏

将其放置在左上角的背景矩形内：

<mxCell value="&lt;b&gt;Diagram Title&lt;/b&gt;&lt;br&gt;Author | Date | Version" style="text;html=1;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=14;spacing=8;" vertex="1" parent="1">
  <mxGeometry x="40" y="40" width="300" height="50" as="geometry" />
</mxCell>

PNG 导出背景修复

放置一个覆盖整个图表的 #F5F5F5 矩形作为最底层元素，以防止导出时出现黑色背景。

导出 CLI

平台	CLI 路径
macOS	/Applications/draw.io.app/Contents/MacOS/draw.io
Linux	drawio（通过 snap/apt 在 PATH 中）
Windows	"C:\Program Files\draw.io\draw.io.exe"

<CLI> -x -f <format> -e -b 10 -o <output> <input>

标志：-x 导出，-f 格式（png/svg/pdf），-e 嵌入图表 XML，-b 10 边框

导出的文件使用双扩展名：name.drawio.png — 表示已嵌入 XML，可在 draw.io 中重新编辑。

XML 格式良好性（至关重要）

• 绝不包含 XML 注释（``） — 它们会导致解析错误
• 转义特殊字符：& < > "
• 始终为每个 mxCell 使用唯一的 id 值
• 每条边都必须包含子元素 <mxGeometry relative="1" as="geometry" />
• 根结构必须包含单元格 id="0"（根）和 id="1"（默认图层，parent="0"）

官方参考

• XML 参考：https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md
• 样式参考：https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/style-reference.md