您的架構圖是否有持續維護?

「最新版的架構圖在哪裡?」

僅需瀏覽器即可製作基礎設施架構圖:從代碼自動生成圖表

當團隊新成員這樣詢問時,有多少開發現場能自信地拿出檔案呢?在許多專案中,初期設計時用 draw.io 或 PowerPoint 畫的圖,往往在未經更新的情況下就被擱置一旁。

原因很簡單:「因為修正起來很麻煩」。
在瀏覽器上點選連線、調整配置、匯出成圖片。在基礎設施變動頻繁的現代開發中,這樣的成本實在太高了。

想要「像寫代碼一樣」畫圖

就像我們用 Git 管理代碼一樣,如果架構圖也能以文字為基礎進行管理,文件的即時性將會大幅改善。這正是 Mermaid.js 值得關注的地方。

只需用文字定義連線關係,瀏覽器就會自動以最合適的佈局繪製圖表。沒有理由不使用這種如同「魔法」般的機制。

graph TD
    Internet["Internet"] --> LB["Load Balancer"]
    LB --> WebServer["Web Server"]
    WebServer --> DB[("Database")]

為了不被工具所累的「視覺化編輯器」

話雖如此,要死記硬背所有 Mermaid 語法並手寫出來,也是一樁難事。我們希望專注於「思考基礎設施配置」,而非在「Mermaid 語法錯誤」上耗費心神。

本站的 基礎架構圖產生器 正是為了兼顧兩者優點而設計的。

直觀組裝,聰明匯出

  1. 放置節點:從 UI 加入伺服器、資料庫等組件。
  2. 連接路徑:只需選擇節點間的通訊路徑。
  3. 複製 Mermaid:完成的圖表可以直接作為代碼複製。

將產出的 Mermaid 代碼貼到 GitHub 的 README 或 Notion,該處便會成為「始終保持最新的架構圖」。一旦需要修正,只需改動一行代碼。這種輕快感,才是「文件化」應有的樣貌。

讓架構圖更易讀的訣竅

節點與連線越多,圖就越複雜。留意以下幾點,日後回頭看也能輕鬆理解。

  • 依層級分組:使用 Mermaid 的 subgraph,依「網路層」「應用層」「資料層」,或依 VPC/可用區分組,職責的邊界就一目了然。
  • 統一通訊方向:像外部 → 負載平衡器 → 應用程式 → 資料庫這樣,把流向統一為由上到下(或由左到右),就能直覺地追蹤資料流。
  • 以標籤代替圖例:像 WebServer["Web Server (ECS)"] 這樣放入具體名稱,光看圖就能傳達架構。
graph TD
    subgraph Public
        Internet["Internet"] --> LB["Load Balancer"]
    end
    subgraph Private
        LB --> App["App Server"]
        App --> DB[("RDS")]
    end

與其一開始就追求完美的圖,不如先只畫出主要的通訊路徑,每次變更時再更新程式碼,最終反而能維持「永遠最新」的架構圖。

用群組與顏色讓圖更易讀

在基礎設施架構圖建構器中,每個節點都可以指定類型與群組。

  • 群組:填入相同名稱的節點會集中成 Mermaid 的 subgraph,並以框線圍起來(例如 Private subnet、VPC)。沒有群組的節點排在前面,群組則依輸入順序排列。連線會寫在群組之外,所以跨越群組的線也能照常連接
  • 類型:從 user、gateway、server、database、storage、network、cloud 中選擇
  • 依類型上色:勾選後,只有用到的類型會上色(default 不上色)。例如 server 為藍色、database 為綠色、user 為黃色、gateway 為紫色。圖的區域即使在深色模式下也維持明亮的背景,所以採用淡色填滿加深色文字的組合
subgraph grp_1["Private subnet"]
    n3["App Server 1"]
    n5[("Database")]
end
classDef infra_server fill:#dbeafe,stroke:#2563eb,color:#1e3a8a
class n3 infra_server

結語

基礎設施架構圖並非產出後就完工的「藝術品」,而是隨著系統成長不斷改變形狀的「生物」。

告別「點點點」的手動作業,追求更輕盈、更精確的方式。
利用文字的力量視覺化您的設計,並持續更新團隊的共同認知吧。

💡 小貼士:在 GitHub 發送 Pull Request 時,建議根據基礎設施的變動同步更新 Mermaid 代碼。這樣一來,便能與代碼審查一同進行架構變更的審閱,有效防止文件形式化。

進階 SVG 顯示:手動整理,下次接著用

除了 Mermaid 程式碼,也可以用**自製的「進階 SVG」**檢視架構圖(這是預設的顯示方式;Mermaid 顯示與複製程式碼仍可使用)。

  • 外觀:帶陰影的卡片,並以小字標示節點類型;群組以彩色的框繪製,名稱放在分頁形標籤上。實線、虛線、粗線、無箭頭的線會分別繪製,也能加上標籤
  • 操作:滑鼠移到節點上(鍵盤則是聚焦),只會保留相連的線,點擊可看連接到哪裡、從哪裡連來。可拖曳節點(或聚焦後用方向鍵)重新排列,按「重設配置」即可回到自動排列
  • 儲存:圖可縮放到符合寬度、放大縮小,並以你調整好的配置儲存為 SVG 或 PNG
  • 匯出:除了 Mermaid,還能匯出 Graphviz DOT、PlantUML、D2 與 Mermaid 的 architecture-beta

你製作的架構圖與移動過的節點位置,會自動儲存在這個瀏覽器中,下次開啟時可以接著使用。也可以刪除已儲存的內容,或以 JSON 匯出、匯入。不會傳送到伺服器。

常見問題

Mermaid 架構圖可以貼到哪裡使用?

許多支援 Mermaid 的服務——GitHub README 與 Issue/PR、GitLab、Notion 等——只要以程式碼區塊貼上就會渲染成圖表。與圖片不同,它是可用 Git 管理的文字,因此會留在你的 diff 中並保有變更歷史。

與 draw.io 或 PowerPoint 相比有什麼優勢?

GUI 工具能細緻調整外觀,但編輯與重新匯出很繁瑣,圖表容易過時。Mermaid 只要改一行文字就能更新圖表,並可用 Git 版本控制,因此容易隨配置變更同步、保持「始終最新」。

我輸入的配置會被傳送到外部嗎?

基礎架構圖產生器 在你的瀏覽器內完成處理,不會將你的配置或 Mermaid 代碼傳送到伺服器,因此可安全地將內部系統架構等敏感資訊繪製成圖。

如何讓大型複雜的架構圖更易讀?

用 Mermaid 的 subgraph 依網路層、應用層、資料層,或依 VPC/區域分組,並把通訊方向統一為由上到下(或由左到右),職責邊界與資料流就更容易追蹤。與其一開始就畫出全部,不如先只畫主要路徑,每次變更時更新,更能維持圖的新鮮度。