01. 專案總覽

BusyBox-Diag 是一套深度整合進 BusyBox 的輕量 Linux 系統診斷工具組。本專案透過新增三個自訂的 BusyBox applet,並在底層共用同一個 libdiag 量測層,提供高內聚、低開銷的系統數據監控能力。

💡 重要架構合約提示: 最終交付目標並非三個彼此獨立的 standalone 執行檔,而是標準的 BusyBox applet 整合。這意味著所有工具最後都會被編譯進同一個 busybox binary 中,並完全透過 BusyBox 的 argv[0] symlink dispatch 機制來分流執行。
  • diagfs:檔案系統元資料監控(空間、Inode、Extent)
  • diagnet:被動式核心 Socket 狀態觀察器(TCP/UDP 連線分佈)
  • ptop:基於 Snapshot-Delta 架構的輕量行程資源監控器

02. 開始前所需環境

系統編譯與驗證需要滿足以下基本 Linux 環境要求:

🔹 作業系統:Linux 實體主機、虛擬機或具備特權的 Linux 容器環境。

🔹 工具鏈:GNU Toolchain (gcc, make) 與基礎建構組件。

🔹 依賴組件:python3(用於自動化 JSON 結構與語法驗證)、wget、tar。

Ubuntu 22.04 / 24.04 環境參考安裝指令:

sudo apt update
sudo apt install -y build-essential make gcc libncurses-dev bison flex python3 wget tar

03. 下載 BusyBox 原始碼

專案指定搭配穩定版 busybox-1.36.1。請依序建立工作區並解壓縮官方原始碼:

mkdir -p ~/workspace
cd ~/workspace

wget https://busybox.net/downloads/busybox-1.36.1.tar.bz2
tar xf busybox-1.36.1.tar.bz2

執行 ls ~/workspace/busybox-1.36.1 進行結構驗證,確認包含以下 BusyBox 標準核心目錄:

📁 applets/ (註冊路由器)
📁 include/ (共用標頭檔)
📁 miscutils/ (整合目標區)
📁 libbb/ (內部共用庫)
📄 Makefile
📄 Config.in (Kconfig入口)

04. 取得 BusyBox-Diag 儲存庫

將本專題的開源儲存庫複製至指定的工作目錄中:

cd ~/workspace
git clone https://github.com/aloea4/BusyBox-Diag final_project

請確保您的目錄拓撲結構嚴格維持如下排列:

~/workspace/
├── busybox-1.36.1/   # 上游 BusyBox 原始碼樹
└── final_project/     # 本專題核心程式碼與腳本庫

05. 一鍵 Bootstrap 自動建構

這是專案推薦的主線建構路徑,腳本會全自動驅動完整生命週期:

cd ~/workspace/final_project
scripts/bootstrap_busybox_diag.sh ~/workspace/busybox-1.36.1

如果您不希望建構腳本自動修改環境變數路徑(~/.bashrc),可加入防護旗標:

scripts/bootstrap_busybox_diag.sh ~/workspace/busybox-1.36.1 --no-activate

⚙️ Bootstrap 自動化流程內幕:

  1. 套用 BusyBox-Diag 原始碼圖層 (Overlay) 至上游原始碼樹。
  2. 同步核心運作輔助腳本至 BusyBox Tree 內。
  3. 執行靜態組態配置並編譯整合型巨型二進位檔。
  4. 自動化觸發全套單元測試與功能性驗證矩陣。
  5. 將解耦的 applet 命令投放至安全安裝路徑 /usr/local/busybox-diag/bin。

06. 安裝後生命週期驗證

若於上一步編譯時指定了 --no-activate,請先於當前 Shell 內手動導入 PATH 變數:

export PATH=/usr/local/busybox-diag/bin:$PATH

依序檢查二進位分流路徑與核心幫助面板:

which diagfs && which diagnet && which ptop

diagfs --help
diagnet --help
ptop --help
✅ 預期正確輸出: 指令回報應精確指向 /usr/local/busybox-diag/bin/[工具名],且各工具的標準幫助面板能完美渲染輸出,未出現符號缺失 (Symbol Missing) 錯誤。

07. 基本使用與指令規範

所有自研工具原生遵循高度一致的 CLI 行為。可透過 --output [table|raw|json] 參數切換數據流表現形態。

7.1 diagfs 檔案系統工具

diagfs --output table /
diagfs --output json /

📊 核心回報指標含義:

Path: 觀測掛載目標路徑
Filesystem type: 底層檔案系統型態
Space usage: 區塊層實際空間水位
Inode usage: Metadata 節點耗盡水位

7.2 diagnet 網路狀態監控

diagnet --output table
diagnet --output raw

作為一個嚴格的 被動式核心狀態觀察器,它直接解碼 Linux 核心匯出的虛擬文字。運作期間絕不建立 Socket、不主動探測、亦不抓取實體封包,對線上運行業務具備零侵入性。

7.3 ptop 行程資源監控

ptop --output table -1 -n 1
ptop --output json -1 -n 5 -t 10

⚙️ 核心調校參數:

• -1: 啟動單次快照批次模態 (One-shot)
• -n N: 設定樣本數據更新上限次數
• -t N: 限制僅渲染資源消耗最高的前 N 家行程

08. 結構化 JSON 合法性校驗

為確保各 applet 工具輸出的 JSON 數據流可完美相容於上游自動化 Dashboard 體系,可透過 Python 原生解析模組進行語法合法性嚴格校驗:

diagfs --output json / | python3 -m json.tool
diagnet --output json | python3 -m json.tool
ptop --output json -1 -n 1 | python3 -m json.tool

💡 若語法完全合法,終端機將輸出美化排版後的結構化 JSON,若解析出錯則會直接噴出 Parser 報錯訊息。

09. Shell Pipeline 高級自動化串接

藉由內建的 raw 模態,數據流能以高度規整的單行純文字格式輸出,極度適合使用 UNIX 古典工具進行管線過濾處理:

# 自動提取掛載點特定指標
diagfs --output raw / | awk '{print $1, $2, $3}'

# 擷取連線分佈前 20 條記錄
diagnet --output raw | head -20

# 採集系統進程快照精簡摘要
ptop --output raw -1 -n 10 | head -20

10. 進階:手動逐步構建生命週期

如果您需要更細緻地控制構建工序,可以跳過 Bootstrap,依次手動執行各分步核心控制腳本:

cd ~/workspace/final_project
scripts/apply_overlay.sh ~/workspace/busybox-1.36.1

cd ~/workspace/busybox-1.36.1
scripts/build_busybox_diag.sh
scripts/verify_busybox_diag.sh
scripts/install_busybox_diag_local.sh --activate

11. 基準效能自動化評測

本腳本專門用於就地量測自研組件與 GNU 官方工具鏈的開銷對照,生成正式的專案成效證據檔:

cd ~/workspace/final_project
scripts/benchmark_busybox_diag.sh ~/workspace/busybox-1.36.1

執行完畢後將於本地自動產出以下核心對照分析報告:

📄 benchmarks/binary_size.txt
記錄靜態與常駐記憶體體積
📄 benchmarks/verification_summary.txt
保存全面測試矩陣回報
📄 benchmarks/manual_test_summary.txt
記錄人工邊界情境抽樣指標

12. 專案成果 Freeze 證據歸檔

專案正式凍結交付前,所有靜態建構日誌(Build Logs)、驗證矩陣報告、Demo 情境輸出腳本、以及 Kconfig 核心快照,皆會被封裝歸檔至專案目錄下的 release/ 與 release/freeze/ 目錄中,作為評分與規格合約檢驗的最終客觀依據。

13. 系統全乾淨移除規範

若需將本專題工具從您的 Linux 系統中完全撤銷,請執行以下清理工序:

# 1. 抹除實體二進位與軟連結目錄
sudo rm -rf /usr/local/busybox-diag

# 2. 編輯您的 ~/.bashrc 移除下方環境變數設定
# export PATH=/usr/local/busybox-diag/bin:$PATH

14. 疑難排解 (Troubleshooting)

故障 1: diagfs: command not found

原因:當前終端機對話尚未導入二進位安裝路徑。

解法:手動執行 export PATH=/usr/local/busybox-diag/bin:$PATH。

故障 2: Filesystem type: unknown

原因:容器虛擬化環境(如 Docker OverlayFS)特殊的掛載型態未包含在輕量化靜態映射表內。

解法:此為正常已知限制,底層區塊層空間與 Inode 指標依然精確有效,不影響業務診斷。

故障 3: 效能測試指標中出現許多 SKIP

原因:測試執行環境屬於精簡版最小化容器,系統內缺乏 ss 或 /usr/bin/time 等原生對照組基準工具。

解法:這代表對照組被跳過,自製工具本體功能依然完全合格,於主機補齊套件即可。

15. 自動化測試 PASS 指標含義

PASS 標籤 核心考核面向與通過定義
Build PASS 原始碼 Overlay 成功合流,上游 BusyBox 核心編譯完全無符號阻斷錯誤。
Verify PASS 各工具 CLI 選項解析、矩陣回報健全度、JSON 基線合法性完全合規。
Applet registration PASS 三個自研命名空間成功註冊進 BusyBox 頂層全域 Applet 靜態路由表。
Symlink dispatch PASS 透過建立的軟連結獨立呼叫指令時,BusyBox 路由能精確分流至對應的 main()。

16. 資料流設計模型摘要

// 數據從核心層到展示層的單向低開銷流動線路

Kernel Interfaces (/proc virtual fs, statfs system calls)

└──> [libdiag] Shared Measurement Layer (容錯、邊界防禦與結構化抽象)

└──> [Applet Analysis Layer] 執行時間差分、Ceiling 運算、狀態映射

└──> [Presentation Formatter] isatty() 偵測、動態控制字元自動開閉

└──> BusyBox Applet Dispatcher (單一靜態連結 Binary 交付)

17. 專案已知限制 (Known Limitations)

  • ⚠️ 當前實作為工程驗證原型,尚未完全清除 BusyBox 核心模組原有的上游編譯 Warning。
  • ⚠️ diagnet 當前聚焦於原生 IPv4 虛擬文字解碼,尚未擴充支援 /proc/net/tcp6。
  • ⚠️ ptop 採用極簡批次時間快照架構,本質上非完整的全功能動態互動式 ncurses 終端機 UI。
  • ⚠️ 部分特殊或極新檔案系統類型可能在顯示上退化為 unknown,但不影響數據採集準確度。

18. 終端機常用快速指令速查表

# 1. 驅動自動化 Bootstrap 安裝流程

scripts/bootstrap_busybox_diag.sh ~/workspace/busybox-1.36.1

# 2. 檔案系統多模態採樣

diagfs --output table / && diagfs --output json /

# 3. 網路狀態無污染管線過濾

diagnet --output raw | head -n 10

# 4. 行程資源 One-shot 摘要擷取

ptop --output table -1 -n 1