Netviz：用 TypeScript 寫的瀏覽器內網路拓撲設計工具

畫網路拓撲這件事，做過運維或寫系統架構文件的多半都踩過幾種雷：draw.io 開圖前要先挑 lib、檔案散在 Google Drive 找不回來；Visio 開不起來；Excalidraw 風格好看但缺網路元件；OmniGraffle 要錢。真的要快速畫一張「這台 server 接哪個 proxy、proxy 後面接什麼 DB」的草稿，常常還是回 whiteboard。

ShadowArcanist/netviz 把這個場景縮到一個瀏覽器分頁裡：開頁面、拖元件、連線、匯出 PNG，全部在 client side 跑完，圖檔存進 IndexedDB，沒有後端、沒有帳號、沒有同步衝突。整個 repo 用 TypeScript + Vite 寫，build 出來就是一包靜態檔，丟 nginx 或直接 GitHub Pages 都行。

這篇拆 netviz 的技術設計、本機跑起來的方法、跟 draw.io / Excalidraw / Netbox 怎麼分工，順便聊一下「AI-built 但作者不收 PR」這種開源新形態的取捨。

一、先看效果

操作邏輯接近 Figma 的縮影版：

• 左側 sidebar 是元件庫（server、proxy、database、router、firewall、cloud 等）
• 中間 canvas 拖放後可拉線連接
• 右側 inspector 改名稱、顏色、icon、備註
• 上排 toolbar 切深淺色、復原/重做、複製、匯出 PNG

整個 UI 用 Tailwind CSS 撐，沒有額外裝飾元件庫，bundle 維持小（dev server 啟動 < 1 秒）。

二、技術定位

「無後端」是它跟 Netbox / NetCloud / 商用 NMS 的根本分界。netviz 不打算管 IP、不追 device inventory、不做 ITSM，它只是一張可以拖拉的網路示意圖編輯器，目的是讓你 5 分鐘畫完一張會議要用的拓撲圖。

三、安裝與啟動

3.1 本機開發模式

需要 Node.js 20+ 或 Bun 1.1+：

git clone https://github.com/ShadowArcanist/netviz.git
cd netviz

# Bun（較快）
bun install
bun run dev

# 或 npm
npm install
npm run dev

打開 http://localhost:8888 就能進編輯介面。

3.2 Docker 部署

repo 內附 Dockerfile，build 出來是一個 nginx 鏡像：

docker build -t netviz:local .
docker run -d -p 8080:80 --name netviz netviz:local

開 http://localhost:8080 即可。因為資料存在每個瀏覽器的 IndexedDB，多台機器看不到彼此的圖，這是「無後端」的代價。如果要團隊共用，得搭配自己的 share 機制（例如匯出 JSON、走 Git）。

3.3 靜態主機部署

bun run build
# dist/ 整包丟 GitHub Pages / Cloudflare Pages / S3 + CloudFront

dist/ 沒有任何 server-side 依賴，純靜態 HTML/JS/CSS。配 CDN 後啟動速度比本機 dev server 還快。

四、架構解析

幾個值得注意的設計：

1. 完全 client-side：所有 state 都在記憶體 + IndexedDB，重整頁面後從 IndexedDB rehydrate 回來
2. Vite 即構即跑：dev mode HMR 跟一般 React/Vue 一樣快，但 netviz 不用 framework，directly 操 TypeScript + DOM
3. 無 backend dependency：表示斷網仍可用（PWA-friendly）、但也表示沒有跨裝置同步
4. 匯出方式只有 PNG：沒有 SVG、沒有 JSON schema export（這點下面會講）

五、實測使用

5.1 元件拖放

從左側 sidebar 把「Server」icon 拖到 canvas，會自動產生一個帶標籤的 block。雙擊 block 進入編輯模式可以改名稱、顏色、加備註。inspector 面板有更細的屬性可調（邊框、字體、layer）。

5.2 連線

點擊一個 block 的邊緣會跳出連接點，拖到另一個 block 上即建立連線。線可以選方向（單向箭頭、雙向、無箭頭）、樣式（實線、虛線）、顏色。

5.3 分層

netviz 把元件分 layer（前景/背景），用來解決「資料庫塊太大蓋住箭頭」這類常見的繪圖困擾。把網段或外框框設成背景層，server / proxy 那些放前景層，就不會疊在一起。

5.4 匯出

點工具列「Export」→ 下載 PNG。沒有 SVG、沒有 JSON。後者尤其可惜，因為這意味著：

• 圖檔不能用文字 diff（無法 Git review）
• 圖檔不能在第三方工具（Mermaid / draw.io）裡 import
• 跨機器搬遷只能用 IndexedDB 備份外掛或 redraw

5.5 IndexedDB 持久化

開 DevTools → Application → IndexedDB 能看到 netviz 的 store。每張圖一個 record，含節點、邊、屬性。理論上可以寫個 user script 把 IndexedDB 內容 dump 成 JSON，但官方沒提供 UI。

六、踩雷與觀察

實際畫了幾張圖之後，整理出幾個要注意的點：

1. AI-built 標籤要看明白
   - README 直接寫「本專案完全由 AI 開發，但已充分測試」
   - 作者也標明「除非自己需要，不接受 PR」
   - 意思是：你可以用、可以 fork、可以自己改，但不要期待社群驅動的修 bug
2. 沒有匯入 / 同步機制
   - 換瀏覽器 = 換資料、新環境從零開始
   - 公司電腦畫的圖回家看不到（除非自己用 IndexedDB 備份工具）
3. 適合做「一次性架構草稿」，不適合做「持續維護的拓撲文件」
   - 後者要的是版本控制 + 多人協作，netviz 都沒有
4. 元件 icon 集相對精簡
   - 沒有 Cisco / AWS / GCP 那種專業 icon set
   - 但允許上傳自訂圖片當 icon，可以塞進公司專屬的 logo
5. 效能
   - 100 個節點左右仍流暢
   - 500+ 節點開始拖拉延遲（純 DOM 而不是 Canvas/WebGL 的限制）

七、vs. 其他方案

簡單說：
- 需要「腦中那張圖快速畫出來、不要任何登入」→ netviz
- 需要「圖檔放 Confluence 給人改、同事一起編」→ draw.io
- 需要「白板 brainstorm 風的」→ Excalidraw
- 需要「真的管網路資產」→ Netbox

八、適合與不適合的場景

適合：
- 工程師個人筆記裡的隨手拓撲圖
- POC / Demo 時臨時畫一張背景說明
- 教學投影片補一張示意圖
- Internal tool / homelab 自我留檔
- 想自架一個無帳號的繪圖工具給團隊（搭 Docker + Coolify）

不適合：
- 多人即時協作
- 需要進入版本控制的文件
- 大型網路資產追蹤（≥ 500 節點 / IP 管理）
- 圖檔要餵給其他工具二次處理

九、小結

netviz 是一個用 TypeScript + Vite + IndexedDB 堆出來的純前端網路拓撲編輯器，定位明確：快速、無帳號、本地。把它當成「一張可拖拉的紙」、不要把它當成 Netbox 來用，體驗會很好。最大遺珠是缺 SVG / JSON export，這讓圖檔很難 git-track 或被其他工具消費；但作為快速畫圖工具，bundle 小、啟動快、UI 簡潔這些優點補回不少。

如果你正在找一個「自架、不收 telemetry、不用註冊」的網路繪圖工具，netviz 值得 clone 下來放在內部 PaaS 上跑。AI 寫的代碼 + 作者不收 PR 這件事在意的話，自己 fork 一份維護。

參考資料

• ShadowArcanist/netviz GitHub
• Vite 官方文件
• Bun 官方文件
• MDN IndexedDB API
• Tailwind CSS 官網