wasidola/tr181-scanner

TR-181/TR-069 Automated Test Tool

!https://img.shields.io/badge/version-latest-blue !https://img.shields.io/badge/platform-Linux%20%7C%20Windows%20%7C%20macOS-lightgrey

這是一個專為網路測試工程師設計的自動化測試工具，用於驗證 WiFi Gateway、FWA 與 Mesh AP 的 TR-181 Data Model 一致性。本工具整合了輕量化 ACS 引擎與 PyQt6 圖形介面，支援自動化掃描、參數寫入校驗、以及詳盡的 HTML 測試報告導出。

🚀 快速開始 (Quick Start)

由於本工具包含圖形介面 (GUI)，在 Docker 中執行時需要額外的步驟來將視窗顯示到您的主機畫面上。

1. 準備工作 (Prerequisites)

請先在您的電腦上建立一個名為 reports 的資料夾，用於存放測試報告：

bash
mkdir reports

2. 各平台執行步驟

🪟 Windows (推薦使用 Docker Desktop) Windows 使用者最常見的情況是透過 Docker Desktop 執行。 安裝 X Server：下載並安裝 VcXsrv。 啟動 VcXsrv： 選擇 "Multiple windows"。 重要：在 "Extra settings" 頁面，務必勾選 "Disable access control"。 取得主機 IP：開啟 PowerShell，輸入 ipconfig 找到您的 IPv4 地址 (例如 192.168.1.100)。 執行容器： 在專案目錄下建立 docker-compose.yml (內容見下方)，並在 PowerShell 執行：

PowerShell
$env:DISPLAY_ENV = "192.168.1.100:0"
docker-compose up

🐧 Linux (Ubuntu 24.04+) 開放 X11 權限：

Bash
xhost +local:docker

執行容器：

Bash
DISPLAY_ENV=$DISPLAY docker-compose up

🍎 macOS 安裝 XQuartz：透過 Homebrew brew install --cask xquartz 或官網下載。 設定 XQuartz：啟動後進入偏好設定 -> 安全性，勾選 "Allow connections from network clients" 並重啟。 執行容器：

Bash
xhost + 127.0.0.1
DISPLAY_ENV=docker.for.mac.host.internal:0 docker-compose up

🛠️ Docker Compose 配置 請將以下內容儲存為 docker-compose.yml，這能讓您輕鬆啟動環境：

YAML
services:
  tr181-scanner:
    image: your_docker_hub_username/tr181-scanner:latest
    container_name: tr181_test_tool
    network_mode: host  # 確保 ACS 埠口 (7547) 可被 CPE 存取
    environment:
      - DISPLAY=${DISPLAY_ENV:-:0}
      - QT_X11_NO_MITSHM=1
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix
      - ./reports:/app  # 測試報告會同步至主機的 reports 資料夾
    stdin_open: true
    tty: true

📋 功能亮點 (Key Features) 自動化掃描：一鍵執行 GPV/GPN/GPA，完整解析設備 Data Model。 一致性校驗：自動測試 ReadOnly 參數防護與非法型別寫入 (Fault 9006/9007/9008)。 自定義測試：支援針對特定參數設置自定義測試間隔與寫入值。 持久化報告：測試完成後，導出的 HTML 報告會透過 Volume 自動保存在主機的 reports 目錄中。

⚠️ 注意事項 (Notes) 網路模式：本工具預設使用 network_mode: host。如果您在 Windows/macOS 上遇到 CPE 無法連線至 ACS 的問題，請確認防火牆已允許 7547 埠口。 版本資訊：本 Image 嚴格遵循版本管理規範。如需特定版本，請查閱 Tags 標籤（格式如 vYYYYMMDD_buildXX）。 Maintainer: Bagah (Network Test Engineer)