This article is not yet available in English. You are reading the Traditional Chinese original. The English edition will appear here once it is translated.
Browse articles that do have an English edition微服務依賴關係地圖生成：從黑盒架構到可視化的系統理解
微服務架構上線一年，團隊擴張到三十人，沒人清楚服務之間的完整呼叫關係；後端工程師改了一個內部 API 的回應格式，不知道會影響哪些下游服務，結果導致三個服務同時報錯；新人接手專案，花幾週時間閱讀程式碼、問同事，才能勉強摸清系統全貌。這類「架構黑盒」是微服務團隊最常見的痛點：難以理解、難以預測、而且知識集中在少數資深工程師腦中。這篇是操作配方：用 Jaeger、Prometheus、LLM 節點與圖形化庫串出一條依賴地圖生成流水線，讓機器從分散式追蹤數據提取呼叫關係、建構依賴圖、識別關鍵路徑、生成互動式地圖，人只處理需要業務語境補充的部分。全文最重要的一節是第五節——哪些環節可以從追蹤數據自動提取，哪些環節必須由人補充業務語境，這條邊界畫錯了，自動化會比人工更危險。
這個場景解決什麼
適合這個配方的流程有四種特徵：高頻率（每天都有流量）、跨服務（多個微服務互相呼叫）、規則說得清楚（HTTP/gRPC 呼叫有明確的追蹤 ID）、繁瑣但必須做。四者俱備的人工梳理，通常有三種損耗：不完整（只知道自己負責的服務）、延遲（等到出事才發現依賴關係）、不直觀（文字描述難以理解複雜的呼叫鏈）。
做完這個配方之後的目標狀態：服務依賴關係被自動提取並可視化為互動式地圖，關鍵路徑與單點故障被標記，新人能在十分鐘內理解系統全貌。人的角色從「憑記憶畫白版圖」變成「審核自動生成的地圖並補充業務語境」。
同時畫清邊界：這篇處理的是運行時依賴關係的可視化，不是要你用 AI 取代架構設計；需要長期演進方向判斷與權衡取捨的環節（例如「是否要拆分某個服務」、「是否要引入事件驅動架構」）也不在自動化範圍內。判斷一個場景值不值得自動化，先讀什麼時候不該用 AI。
工具組合與前置準備
- Jaeger：開源分散式追蹤系統，支援 OpenTracing 與 OpenTelemetry 標準，能記錄請求在微服務間的完整流轉路徑。優點是與主流框架深度整合、易於部署；缺點是需要應用程式埋點。可自架或採用雲端版。自建與採購的系統性取捨見自建還是採購。
- Prometheus：開源監控與告警系統，支援多維度數據模型與強大的查詢語言 PromQL。用於收集服務調用量、延遲、錯誤率等指標，輔助依賴關係驗證。優點是生態豐富、社區活躍；缺點是需要學習曲線。GitHub 上有活躍的開源社群。
- LLM API（本文以 DeepSeek 為例，任何供應商皆可）：負責流程中「業務語境補充」與「自然語言生成」的判斷。單價以供應商官網為準；接通後第一件事是在供應商控制台設定花費上限與用量告警。
- 圖形化庫（D3.js、Vis.js 或 Cytoscape.js）：用於生成互動式的依賴關係地圖，支援縮放、拖曳、高亮路徑等功能。優點是客製化自由度高；缺點是需要前端開發能力。
前置檢查表——每一項都有明確答案才動工：
| 檢查項 | 要確認什麼 | 沒確認就做的後果 |
|---|---|---|
| 追蹤數據完整性 | 所有微服務是否已接入 Jaeger/OpenTelemetry | 部分服務無法出現在地圖中，依賴關係不完整 |
| 數據保留策略 | Jaeger 是否有足夠的歷史數據（至少一週） | 無法捕捉低頻呼叫的依賴關係 |
| 資料分級 | 追蹤數據是否包含敏感資訊（用戶 ID、訂單號）；能否傳給外部 LLM | 敏感資訊洩露，合規事故 |
| 維運責任 | 上線後誰看地圖、誰調整提取規則 | 地圖產出但無人使用，比沒有更糟 |
資料分級的判斷方法見企業資料安全基本盤。
憑證紀律（先講，因為最常被忽略）：所有 API Key、OAuth Token 放進 CI/CD 平台的 secrets 機制；不要寫死在 workflow 檔案、註解或說明文件裡；不要把含憑證的配置檔提交到公開倉庫。
一、盤點人工梳理痛點
花兩週，把所有微服務依賴梳理中的常見問題列成一張表：
| 問題類型 | 發生頻率 | 平均梳理時間 | 修復成本 | 現在誰發現 |
|---|---|---|---|---|
| 未知的下游依賴 | 每月 1-2 次 | 2-4 小時 | 高（需緊急修復） | 值班工程師 |
| 循環依賴導致死鎖 | 每季度 1 次 | 4-8 小時 | 極高（需重構架構） | 架構師 |
| 單點故障未識別 | 每半年 1 次 | 8+ 小時 | 極高（服務中斷） | 生產環境事故 |
| 新人學習曲線陡峭 | 每次新入職 | 2-4 週 | 中（人力成本） | 新入職工程師 |
兩個填寫紀律：頻率與成本是從實際 incident report 與 onboarding 反饋統計出來的，不靠印象——口頭回憶幾乎總是低估；修復成本要寫具體事件（哪次服務中斷、花了多少人天），寫不出成本的問題，說明它可能根本不值得優先自動化。
這張表有兩個用途：下一步的選型依據，以及上線後計算效益的基線。「自動化前平均每筆依賴梳理多久、自動化後例外處理要多久」都從這張表與後面的執行紀錄算出來——自己測的數字，比任何文章裡的參考值可靠。
二、選一條最痛的服務鏈
四個條件同時成立才動手：頻率高（經常被呼叫）、規則寫得出來（有明確的追蹤 ID）、出錯有代價（影響多個服務）、工具鏈有介面。
兩類流程先避開：實驗性服務（變動太快，地圖追不上）；無追蹤數據的 legacy 服務（需要先接入 OpenTelemetry，工作量過大）。
第一版切小：只做「追蹤數據提取 → 呼叫關係建構 → 關鍵路徑識別 → 地圖生成 → 業務語境補充 → 互動式展示」這一條主幹。自動化架構建議、歷史趨勢預測全留到第二版。一條穩定跑通的主幹，勝過一張完整但沒上線的設計圖。
三、自架還是雲端
| 考量點 | 自架 | 官方雲端 |
|---|---|---|
| 資料位置 | 追蹤數據與地圖在自己環境，適合分級要求高的專案 | 數據經供應商環境，須先過資料分級這一關 |
| 維護責任 | 升級、擴展、停機處置都是你的 | 供應商負責 |
| 起步速度 | 需要伺服器資源與基本 DevOps 能力 | 註冊即用，幾分鐘內完成整合 |
| 預算形態 | 伺服器費用加維運人力 | 訂閱制，金額以官網為準 |
決策方法：資料分級結果說「不能出網」時，自架 Jaeger 與 Prometheus 幾乎是唯一選項；否則先用雲端版的 APM 工具（如 Datadog、New Relic）把第一條流程跑通，累積了真實用量與失敗紀錄，再評估要不要遷移。不論哪種，都先用測試環境跑通示範流程，第一天不碰生產環境。
四、串出最小可跑版本
節點組裝順序：
- 觸發節點：定時觸發（每天一次）或手動觸發。優先定時觸發，確保地圖保持最新。
- 數據提取節點：呼叫 Jaeger API 獲取指定時間範圍內的追蹤數據，過濾掉健康檢查等無關請求，保留業務相關的呼叫鏈。
- 關係建構節點：從追蹤數據提取服務間的呼叫關係（來源服務、目標服務、API 路徑、呼叫次數、平均延遲、錯誤率），建構有向圖。
- 關鍵路徑識別節點：基於呼叫次數、延遲、錯誤率計算每個服務的重要性評分，識別關鍵路徑與單點故障。
- LLM 補充節點：將服務名稱、API 路徑、呼叫統計送入 LLM，要求生成業務語境說明（如「此服務負責訂單創建，是核心業務路徑」）。
- 地圖生成節點：使用 D3.js 或 Cytoscape.js 將依賴關係轉換為互動式地圖，支援縮放、拖曳、高亮路徑、顯示詳細資訊。
- 發布通知節點：將地圖連結發送給團隊成員，附帶變更摘要（新增服務、刪除服務、依賴關係變化）。
試跑期三條紀律：
- 用測試環境：建立
test-microservices環境，故意製造已知依賴關係（服務 A 呼叫服務 B，服務 B 呼叫服務 C），驗證工具能否正確提取並生成地圖。 - 留執行紀錄：除平台內建的執行歷史外，為重要流程加一個「台帳」分支——每次執行把時間、服務數量、依賴關係數、關鍵路徑寫進一張專用表格或資料庫。這是第八節監控的原料。
- 影子模式上線：自動化先生成地圖但不強制使用，人照樣憑記憶或手動繪製，逐週比對兩邊結果。連續一致之後才讓自動化接管地圖更新，人轉為審核與補充。
五、哪些環節交給自動提取、哪些必須用人補充
這是全文最重要的一節。原則一句話：確定性的呼叫關係給自動提取工具，LLM 只做「業務語境補充」這一類需要領域知識的事。
| 環節 | 用什麼 | 為什麼 |
|---|---|---|
| 服務間呼叫關係、API 路徑、呼叫次數 | 從 Jaeger 追蹤數據自動提取 | 同樣輸入必須同樣輸出；這些是確定性資訊，LLM 做不到這個保證 |
| 平均延遲、錯誤率、P99 延遲 | 從 Prometheus 指標自動提取 | 基於時間序列數據的精確計算，準確率 100% |
| 關鍵路徑識別、單點故障檢測 | 圖算法（PageRank、Betweenness Centrality） | 基於數學模型的精確計算，可解釋性強 |
| 服務業務語境說明 | LLM 節點＋人工校準 | 需要理解業務價值、用戶影響，純技術分析無法得出 |
| 架構風險評估 | LLM 節點＋依賴圖分析 | 需要結合業務重要性與技術指標，LLM 能給出綜合評估 |
| 地圖的自然語言標籤 | LLM 節點 | 但服務名稱、API 路徑由自動提取工具原樣注入，LLM 不得改寫任何技術細節 |
兩條鐵律：
- 技術細節永遠不經過 LLM 的嘴。 服務名稱、API 路徑、呼叫次數由自動提取工具原樣提取；LLM 只產語境說明，不產事實。自動化地圖裡代價最高的事故，形態幾乎都是「模型改寫了一個服務名稱，而且改得很像真的」。
- 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 路徑
六、錯誤處理、重試與冪等
先把失敗分成三類，因為三類的處置完全不同：
| 失敗類型 | 例子 | 處置 |
|---|---|---|
| 暫時性 | API 限流、網路逾時 | 節點自動重試（設次數與間隔）；重試耗盡仍失敗進例外分支 |
| 資料性 | 追蹤數據為空、數據格式異常、LLM 輸出格式錯誤 | 不重試（重試還是錯）；直接進例外分支，人修配置後重跑 |
| 設定性 | API Key 過期、Jaeger 服務停機、資料庫連接失敗 | 立即停止流程並告警，等人介入 |
冪等是重試的前提：流程要保證「同一個時間範圍跑兩次不會重複生成地圖」。做法是在生成地圖前先查詢該時間範圍的地圖是否已存在——存在就跳過或更新，絕不無腦新增。沒有冪等設計就開重試，等於裝了一台地圖製造機：重複的版本歷史，比人工繪製還難收拾。
七、失敗告警
- 告警發到「有人在值班」的渠道：即時通訊群組或 email，且群組裡有明確的值班表。告警沒人看，等於沒有告警。
- 告警內容模板：流程名稱、失敗節點、錯誤摘要、發生時間、重跑方式。讓收到的人在半分鐘內能決定「現在處理還是稍後處理」。
- 分級防洗版：單筆地圖生成例外進每週匯總；API Key 過期、服務停機這類「流程已停」的事件才即時推送。每筆例外都彈一次通知，值班的人很快會把渠道靜音——告警系統就死在靜音那一刻。
八、上線後的監控
- 前兩週是觀察期：每天看執行歷史與台帳，記錄執行總數、失敗次數、誤報率（人工標記為不準確的業務語境比例）。兩週之後自己算誤報率與主因分佈——這是你的流程自己的數據，判斷門檻（誤報率高到多少要調整提示詞）由你的團隊容忍度決定，定了就寫進值班說明，不要引用任何文章裡的現成數字。
- 每週抽樣複核：固定抽 3-5 個服務的業務語境說明，人工複查是否準確、是否有助於理解。抽樣筆數依服務量自定，關鍵是固定頻率、留下紀錄、發現問題就調整規則或提示詞。抽樣抓的是「流程沒報錯但語境說明不合理」這類最安靜的事故。
- 變更紀律：團隊服務架構更新、LLM 供應商更新模型版本、你改提示詞，都算變更。改動前先用最近的例外樣本與幾筆正常樣本重跑一遍，確認沒有變差再上；改動寫進台帳。
- 成本：LLM 節點的用量乘上供應官網單價，加上 Jaeger/Prometheus 授權費與你的維運時間，就是這條流程的真實成本；估算方法見AI 成本怎麼算。
成果與驗收標準
| 檢查點 | 通過標準 | 沒通過怎麼辦 |
|---|---|---|
| 盤點基線 | 有依賴梳理痛點表，頻率與成本是從 incident report 統計的紀錄 | 回到第一節；先別急著搭流程 |
| 主幹跑通 | 測試環境端到端跑完，檢測到故意放入的依賴關係 | 檢查工具配置與權限 |
| 確定性邊界 | 服務名稱、API 路徑沒有任何一個由 LLM 改寫 | 改成自動提取工具直接提取 |
| LLM 輸出校驗 | LLM 輸出有格式校驗節點，不合法進例外分支 | 在 LLM 節點後補校驗 |
| 冪等 | 手動觸發同一個時間範圍兩次，沒有重複地圖版本 | 加版本存在性檢查 |
| 影子期 | 與人工並行連續數週結果一致才交接 | 延長影子期，逐項找不一致的原因 |
| 告警有效 | 故意製造一次失敗（暫撤測試 API Key），告警在承諾時間內到達值班渠道且內容完整 | 修告警路由與值班安排 |
| 監控習慣 | 台帳連續兩週每週有紀錄，抽樣複核有留痕 | 把監控指派到具體的人，放進行事曆 |
常見踩坑
- 讓 LLM 做確定性工作：「讓 AI 順便提取一下呼叫關係」一時方便，代價是同樣輸入可能不同輸出，出了錯無法重現、無從追查。
- 用個人帳號的憑證：當事人離職、改密碼的那天，流程集體猝死。用服務帳號，並納入組織的憑證管理。
- 直接在生產環境上實驗：正確順序是測試環境、非敏感服務小範圍、全量。跳級的人通常在第二步就出事。
- 沒做冪等就開重試：重試機制會把偶發錯誤放大成重複地圖事故。
- LLM 節點不設花費上限：一個迴圈觸發的臭蟲能讓流程整夜持續呼叫 API。上限與告警在供應商控制台設定，五分鐘的事。
- 告警發到沒人看的渠道：沒有值班表的告警是自我安慰。
- 忽略追蹤數據完整性：自動化提取的前提是所有服務都已接入 Jaeger/OpenTelemetry。如果團隊尚未統一追蹤標準，先花時間接入所有服務，否則自動化只會提取出不完整的地圖。
- 一次性生成所有服務地圖：一週把上百個服務全部自動化，第二週就沒有人力調整誤報。先讓核心服務鏈（最高頻使用的 10-20 個服務）穩定跑滿一個月，把模式沉澱成範本，再複製到其他服務。
- 缺乏架構文檔支持：自動化地圖只能反映運行時依賴關係，無法替代架構設計文檔。如果團隊尚未建立架構文檔規範，先花時間補充設計決策、業務邏輯說明，否則地圖只能回答「怎麼呼叫」，無法回答「為什麼這樣設計」。
下一步
- 同一套「自動提取＋人工審核」模式用在代碼審查場景：自動化代碼審查助手
- API 文檔同步更新系統：API 文檔同步更新系統
- 技術債的量化與優先級排序：技術債追蹤與重構優先級排序
- CI/CD 管道的異常檢測：CI/CD 管道異常檢測與修復建議
- 資料分級與安全邊界：企業資料安全基本盤
- 上線前的合規檢查表：AI 合規與風險邊界
- 流程越串越多、要不要升級成平台：自建還是採購