微服務依賴關係地圖生成：從黑盒架構到可視化的系統理解

微服務架構上線一年，團隊擴張到三十人，沒人清楚服務之間的完整呼叫關係；後端工程師改了一個內部 API 的回應格式，不知道會影響哪些下游服務，結果導致三個服務同時報錯；新人接手專案，花幾週時間閱讀程式碼、問同事，才能勉強摸清系統全貌。這類「架構黑盒」是微服務團隊最常見的痛點：難以理解、難以預測、而且知識集中在少數資深工程師腦中。這篇是操作配方：用 Jaeger、Prometheus、LLM 節點與圖形化庫串出一條依賴地圖生成流水線，讓機器從分散式追蹤數據提取呼叫關係、建構依賴圖、識別關鍵路徑、生成互動式地圖，人只處理需要業務語境補充的部分。全文最重要的一節是第五節——哪些環節可以從追蹤數據自動提取，哪些環節必須由人補充業務語境，這條邊界畫錯了，自動化會比人工更危險。

這個場景解決什麼

適合這個配方的流程有四種特徵：高頻率（每天都有流量）、跨服務（多個微服務互相呼叫）、規則說得清楚（HTTP/gRPC 呼叫有明確的追蹤 ID）、繁瑣但必須做。四者俱備的人工梳理，通常有三種損耗：不完整（只知道自己負責的服務）、延遲（等到出事才發現依賴關係）、不直觀（文字描述難以理解複雜的呼叫鏈）。

做完這個配方之後的目標狀態：服務依賴關係被自動提取並可視化為互動式地圖，關鍵路徑與單點故障被標記，新人能在十分鐘內理解系統全貌。人的角色從「憑記憶畫白版圖」變成「審核自動生成的地圖並補充業務語境」。

同時畫清邊界：這篇處理的是運行時依賴關係的可視化，不是要你用 AI 取代架構設計；需要長期演進方向判斷與權衡取捨的環節（例如「是否要拆分某個服務」、「是否要引入事件驅動架構」）也不在自動化範圍內。判斷一個場景值不值得自動化，先讀什麼時候不該用 AI。

工具組合與前置準備

• Jaeger：開源分散式追蹤系統，支援 OpenTracing 與 OpenTelemetry 標準，能記錄請求在微服務間的完整流轉路徑。優點是與主流框架深度整合、易於部署；缺點是需要應用程式埋點。可自架或採用雲端版。自建與採購的系統性取捨見自建還是採購。
• Prometheus：開源監控與告警系統，支援多維度數據模型與強大的查詢語言 PromQL。用於收集服務調用量、延遲、錯誤率等指標，輔助依賴關係驗證。優點是生態豐富、社區活躍；缺點是需要學習曲線。GitHub 上有活躍的開源社群。
• LLM API（本文以 DeepSeek 為例，任何供應商皆可）：負責流程中「業務語境補充」與「自然語言生成」的判斷。單價以供應商官網為準；接通後第一件事是在供應商控制台設定花費上限與用量告警。
• 圖形化庫（D3.js、Vis.js 或 Cytoscape.js）：用於生成互動式的依賴關係地圖，支援縮放、拖曳、高亮路徑等功能。優點是客製化自由度高；缺點是需要前端開發能力。

前置檢查表——每一項都有明確答案才動工：

資料分級的判斷方法見企業資料安全基本盤。

憑證紀律（先講，因為最常被忽略）：所有 API Key、OAuth Token 放進 CI/CD 平台的 secrets 機制；不要寫死在 workflow 檔案、註解或說明文件裡；不要把含憑證的配置檔提交到公開倉庫。

一、盤點人工梳理痛點

花兩週，把所有微服務依賴梳理中的常見問題列成一張表：

兩個填寫紀律：頻率與成本是從實際 incident report 與 onboarding 反饋統計出來的，不靠印象——口頭回憶幾乎總是低估；修復成本要寫具體事件（哪次服務中斷、花了多少人天），寫不出成本的問題，說明它可能根本不值得優先自動化。

這張表有兩個用途：下一步的選型依據，以及上線後計算效益的基線。「自動化前平均每筆依賴梳理多久、自動化後例外處理要多久」都從這張表與後面的執行紀錄算出來——自己測的數字，比任何文章裡的參考值可靠。

二、選一條最痛的服務鏈

四個條件同時成立才動手：頻率高（經常被呼叫）、規則寫得出來（有明確的追蹤 ID）、出錯有代價（影響多個服務）、工具鏈有介面。

兩類流程先避開：實驗性服務（變動太快，地圖追不上）；無追蹤數據的 legacy 服務（需要先接入 OpenTelemetry，工作量過大）。

第一版切小：只做「追蹤數據提取 → 呼叫關係建構 → 關鍵路徑識別 → 地圖生成 → 業務語境補充 → 互動式展示」這一條主幹。自動化架構建議、歷史趨勢預測全留到第二版。一條穩定跑通的主幹，勝過一張完整但沒上線的設計圖。

三、自架還是雲端

決策方法：資料分級結果說「不能出網」時，自架 Jaeger 與 Prometheus 幾乎是唯一選項；否則先用雲端版的 APM 工具（如 Datadog、New Relic）把第一條流程跑通，累積了真實用量與失敗紀錄，再評估要不要遷移。不論哪種，都先用測試環境跑通示範流程，第一天不碰生產環境。

四、串出最小可跑版本

節點組裝順序：

1. 觸發節點：定時觸發（每天一次）或手動觸發。優先定時觸發，確保地圖保持最新。
2. 數據提取節點：呼叫 Jaeger API 獲取指定時間範圍內的追蹤數據，過濾掉健康檢查等無關請求，保留業務相關的呼叫鏈。
3. 關係建構節點：從追蹤數據提取服務間的呼叫關係（來源服務、目標服務、API 路徑、呼叫次數、平均延遲、錯誤率），建構有向圖。
4. 關鍵路徑識別節點：基於呼叫次數、延遲、錯誤率計算每個服務的重要性評分，識別關鍵路徑與單點故障。
5. LLM 補充節點：將服務名稱、API 路徑、呼叫統計送入 LLM，要求生成業務語境說明（如「此服務負責訂單創建，是核心業務路徑」）。
6. 地圖生成節點：使用 D3.js 或 Cytoscape.js 將依賴關係轉換為互動式地圖，支援縮放、拖曳、高亮路徑、顯示詳細資訊。
7. 發布通知節點：將地圖連結發送給團隊成員，附帶變更摘要（新增服務、刪除服務、依賴關係變化）。

試跑期三條紀律：

• 用測試環境：建立 test-microservices 環境，故意製造已知依賴關係（服務 A 呼叫服務 B，服務 B 呼叫服務 C），驗證工具能否正確提取並生成地圖。
• 留執行紀錄：除平台內建的執行歷史外，為重要流程加一個「台帳」分支——每次執行把時間、服務數量、依賴關係數、關鍵路徑寫進一張專用表格或資料庫。這是第八節監控的原料。
• 影子模式上線：自動化先生成地圖但不強制使用，人照樣憑記憶或手動繪製，逐週比對兩邊結果。連續一致之後才讓自動化接管地圖更新，人轉為審核與補充。

五、哪些環節交給自動提取、哪些必須用人補充

這是全文最重要的一節。原則一句話：確定性的呼叫關係給自動提取工具，LLM 只做「業務語境補充」這一類需要領域知識的事。

兩條鐵律：

1. 技術細節永遠不經過 LLM 的嘴。 服務名稱、API 路徑、呼叫次數由自動提取工具原樣提取；LLM 只產語境說明，不產事實。自動化地圖裡代價最高的事故，形態幾乎都是「模型改寫了一個服務名稱，而且改得很像真的」。
2. LLM 輸出永遠當作不可信輸入。 LLM 節點要求輸出固定結構的 JSON（欄位在提示詞裡逐一列舉）；下游第一個節點做格式校驗，校驗不過直接進例外分支，不允許「盡量解析」。

LLM 節點的提示詞寫法：給業務語境補充規則（「根據服務名稱與 API 路徑推斷業務功能」）、給輸出 JSON 的欄位定義、給邊界規則（「只根據提供的服務資訊生成語境說明，不 invent 新的服務」），溫度調低以減少隨機性。提示詞不神奇，神奇的是它後面接了校驗節點。

以下是一個典型的 LLM 業務語境補充提示詞範例：

你是一位資深系統架構師，負責為以下微服務生成業務語境說明。

【服務資訊】
- 服務名稱：{{service_name}}
- API 路徑列表：{{api_paths}}
- 上游服務：{{upstream_services}}
- 下游服務：{{downstream_services}}
- 日均呼叫量：{{daily_calls}}
- 平均延遲：{{avg_latency}}ms
- 錯誤率：{{error_rate}}%

【業務語境規則】
- 根據服務名稱與 API 路徑推斷業務功能（如 "order-service" + "/orders/create" → 「訂單創建服務」）
- 根據呼叫量與延遲判斷服務重要性（高呼叫量 + 低延遲 → 核心服務）
- 根據上下游關係判斷服務在系統中的位置（多上游 + 多下游 → 樞紐服務）

【輸出格式】
請嚴格按照以下 JSON 格式輸出，不要添加任何其他文字：
{
  "business_context": {
    "functional_description": string,
    "importance_level": "critical" | "high" | "medium" | "low",
    "role_in_system": "gateway" | "core" | "hub" | "leaf",
    "key_responsibilities": [string]
  },
  "risk_assessment": {
    "single_point_of_failure": boolean,
    "cascade_failure_risk": "high" | "medium" | "low",
    "recommended_redundancy": string
  },
  "documentation_suggestions": [
    {
      "topic": string,
      "priority": "high" | "medium" | "low",
      "suggested_content": string
    }
  ],
  "summary": string
}

【邊界規則】
- 只根據提供的服務資訊生成語境說明，不 invent 新的服務或 API
- 如果某些資訊缺失，在輸出中标記 "data_missing"
- 不要改寫任何服務名稱或 API 路徑

六、錯誤處理、重試與冪等

先把失敗分成三類，因為三類的處置完全不同：

冪等是重試的前提：流程要保證「同一個時間範圍跑兩次不會重複生成地圖」。做法是在生成地圖前先查詢該時間範圍的地圖是否已存在——存在就跳過或更新，絕不無腦新增。沒有冪等設計就開重試，等於裝了一台地圖製造機：重複的版本歷史，比人工繪製還難收拾。

七、失敗告警

• 告警發到「有人在值班」的渠道：即時通訊群組或 email，且群組裡有明確的值班表。告警沒人看，等於沒有告警。
• 告警內容模板：流程名稱、失敗節點、錯誤摘要、發生時間、重跑方式。讓收到的人在半分鐘內能決定「現在處理還是稍後處理」。
• 分級防洗版：單筆地圖生成例外進每週匯總；API Key 過期、服務停機這類「流程已停」的事件才即時推送。每筆例外都彈一次通知，值班的人很快會把渠道靜音——告警系統就死在靜音那一刻。

八、上線後的監控

• 前兩週是觀察期：每天看執行歷史與台帳，記錄執行總數、失敗次數、誤報率（人工標記為不準確的業務語境比例）。兩週之後自己算誤報率與主因分佈——這是你的流程自己的數據，判斷門檻（誤報率高到多少要調整提示詞）由你的團隊容忍度決定，定了就寫進值班說明，不要引用任何文章裡的現成數字。
• 每週抽樣複核：固定抽 3-5 個服務的業務語境說明，人工複查是否準確、是否有助於理解。抽樣筆數依服務量自定，關鍵是固定頻率、留下紀錄、發現問題就調整規則或提示詞。抽樣抓的是「流程沒報錯但語境說明不合理」這類最安靜的事故。
• 變更紀律：團隊服務架構更新、LLM 供應商更新模型版本、你改提示詞，都算變更。改動前先用最近的例外樣本與幾筆正常樣本重跑一遍，確認沒有變差再上；改動寫進台帳。
• 成本：LLM 節點的用量乘上供應官網單價，加上 Jaeger/Prometheus 授權費與你的維運時間，就是這條流程的真實成本；估算方法見AI 成本怎麼算。

成果與驗收標準

常見踩坑

• 讓 LLM 做確定性工作：「讓 AI 順便提取一下呼叫關係」一時方便，代價是同樣輸入可能不同輸出，出了錯無法重現、無從追查。
• 用個人帳號的憑證：當事人離職、改密碼的那天，流程集體猝死。用服務帳號，並納入組織的憑證管理。
• 直接在生產環境上實驗：正確順序是測試環境、非敏感服務小範圍、全量。跳級的人通常在第二步就出事。
• 沒做冪等就開重試：重試機制會把偶發錯誤放大成重複地圖事故。
• LLM 節點不設花費上限：一個迴圈觸發的臭蟲能讓流程整夜持續呼叫 API。上限與告警在供應商控制台設定，五分鐘的事。
• 告警發到沒人看的渠道：沒有值班表的告警是自我安慰。
• 忽略追蹤數據完整性：自動化提取的前提是所有服務都已接入 Jaeger/OpenTelemetry。如果團隊尚未統一追蹤標準，先花時間接入所有服務，否則自動化只會提取出不完整的地圖。
• 一次性生成所有服務地圖：一週把上百個服務全部自動化，第二週就沒有人力調整誤報。先讓核心服務鏈（最高頻使用的 10-20 個服務）穩定跑滿一個月，把模式沉澱成範本，再複製到其他服務。
• 缺乏架構文檔支持：自動化地圖只能反映運行時依賴關係，無法替代架構設計文檔。如果團隊尚未建立架構文檔規範，先花時間補充設計決策、業務邏輯說明，否則地圖只能回答「怎麼呼叫」，無法回答「為什麼這樣設計」。

下一步

• 同一套「自動提取＋人工審核」模式用在代碼審查場景：自動化代碼審查助手
• API 文檔同步更新系統：API 文檔同步更新系統
• 技術債的量化與優先級排序：技術債追蹤與重構優先級排序
• CI/CD 管道的異常檢測：CI/CD 管道異常檢測與修復建議
• 資料分級與安全邊界：企業資料安全基本盤
• 上線前的合規檢查表：AI 合規與風險邊界
• 流程越串越多、要不要升級成平台：自建還是採購