win-remote-toolkit/SUMMARY.md

Project Summary: The Why Behind Windows Remote Toolkit

這個專案的設計故事：為什麼這樣做、遇到什麼問題、如何解決。

🎯 專案起源

問題陳述

你有一台 Windows 機器需要定期維護，但你主要使用 macOS/Linux。每次都要：

1. RDP 連進去手動操作
2. 記住複雜的 PowerShell 指令
3. 重複做同樣的系統清理工作
4. 在不同機器間傳檔案很麻煩

核心需求

• 遠端自動化：不要每次都 RDP 進去手動點擊
• 冪等操作：可以重複執行不會壞事
• 跨平台控制：從 macOS/Linux 管理 Windows
• 可追蹤性：知道做了什麼、結果如何

🏗️ 架構演進史

第一版：純 PowerShell

問題：如何從 macOS 執行 Windows PowerShell？
嘗試：直接 SSH 執行 PowerShell 命令
結果：命令太長，轉義問題，維護困難

第二版：雙檔案架構

突破：分離傳輸邏輯和執行邏輯
設計：.sh 檔案負責上傳和執行，.ps1 檔案負責實際操作
優點：PowerShell 程式碼可以複雜，Shell 邏輯保持簡單

第三版：多連線方法支援

發現：SSH 穩定但慢，WinRM 快但有限制
解決：同時支援兩種方法，用戶可選擇
進化：智慧選擇器根據腳本大小自動選最佳方法

第四版：配置驅動

痛點：不同環境需要不同參數，硬編碼難維護
方案：抽取配置到 JSON 檔案，支援環境變數覆寫
效果：同一套腳本可適應不同的目標機器和需求

🤔 關鍵設計決策

為什麼選擇雙檔案架構？

其他方案考慮：

• 單一 Python 腳本：需要在目標機器安裝 Python
• 純 Ansible：學習成本高，Windows 支援複雜
• 純 SSH 命令列：命令太長，轉義地獄

選擇雙檔案的原因：

優點：
✅ PowerShell 程式碼清晰可讀
✅ 利用 Windows 原生能力
✅ Shell 包裝器簡單可靠
✅ 容易除錯和修改
✅ 不需要目標機器額外安裝軟體

缺點：
❌ 檔案數量較多
❌ 需要保持兩個檔案同步

為什麼支援 SSH + WinRM 雙方法？

發現過程：

1. 最初只有 SSH：recon.sh 需要 22 秒
2. 實驗 WinRM：同樣操作只需要 12 秒
3. 但 WinRM 有命令長度限制：大腳本會失敗
4. 結論：兩者各有適用場景

決策邏輯：

SSH 方法：
- 適合：大型腳本、複雜操作、穩定性要求高
- 速度：標準（22 秒）
- 穩定性：高
- 限制：較慢

WinRM 方法：
- 適合：快速查詢、小型腳本、效能敏感
- 速度：快（12 秒，1.9x 提升）
- 穩定性：中等
- 限制：命令長度限制

智慧選擇：
- 自動根據腳本大小選擇最佳方法
- 提供手動覆寫選項

為什麼用 JSON 而不是 YAML 配置？

原因：

• PowerShell 原生支援 ConvertFrom-Json
• Windows 環境不一定有 YAML 解析器
• JSON 格式簡單，出錯機率低
• 與 Win11Debloat 原專案格式保持一致

為什麼日誌檔名包含主機名和時間戳？

場景：管理多台機器時需要區分日誌來源

格式：{operation}-{hostname}-{timestamp}.log
範例：recon-PC-74269-20260427-103045.log

優點：
- 一眼看出是哪台機器的記錄
- 時間戳避免檔名衝突
- 方便批次處理和自動化分析

🧩 技術難題解決

問題一：PowerShell 編碼亂碼

現象：中文 Windows 系統執行腳本出現亂碼 原因：Windows PowerShell 將無 BOM 的 UTF-8 檔案當作 CP950 讀取 解決：腳本自動為上傳的 .ps1 檔案添加 UTF-8 BOM

# 在每個 .sh 腳本中加入
printf '\xEF\xBB\xBF' > /tmp/script_with_bom.ps1
cat original.ps1 >> /tmp/script_with_bom.ps1

問題二：防火牆設定重啟後失效

現象：重啟 Windows 機器後 SSH 無法連線 原因：Private/Public 設定檔會恢復為系統預設（阻擋入站） 解決：建立跨所有設定檔的永久規則

# 不只設定 Domain，三個設定檔都要設定
netsh advfirewall firewall add rule name="Allow SSH" dir=in action=allow protocol=TCP localport=22 profile=domain,private,public

問題三：Win11Debloat 設定檔格式陷阱

現象：設定檔被拒絕為 "no importable data" 原因：設定檔格式必須完全符合 Win11Debloat 的 Features.json 解決：使用正確的 JSON 架構 (Tweaks/Deployment/Apps)，並驗證所有項目都存在於原始特性清單中

問題四：Thunderbird 設定檔路徑變更

現象：Thunderbird 72+ 設定檔沒有生效 原因：新版本使用 [Install<HASH>] 區塊而非 Default=1 解決：解析 profiles.ini 找出正確的安裝特定設定檔路徑

# 查找正確的設定檔路徑邏輯
$InstallSection = Get-Content profiles.ini | Select-String "Install"
$ProfilePath = Get-Content profiles.ini | Select-String "Default=" | ForEach-Object { ... }

問題五：WinRM 命令長度限制

現象：大型 PowerShell 腳本透過 WinRM 執行失敗 原因：WinRM 有命令列長度限制，複雜腳本會超過限制 解決：智慧選擇器根據腳本大小自動選擇連線方法

def choose_method(script_size):
    if script_size > WINRM_LIMIT:
        return "ssh"
    else:
        return "winrm"  # 更快的方法

📈 效能最佳化歷程

第一次最佳化：並行化檔案操作

before：循序上傳、執行、清理 after：並行處理無相依性的操作 效果：25% 時間減少

第二次最佳化：WinRM 整合

before：只支援 SSH（22 秒） after：支援 WinRM（12 秒） 效果：90% 速度提升（適用場景下）

第三次最佳化：智慧方法選擇

before：手動選擇連線方法 after：自動根據腳本特性選擇 效果：開發者體驗提升，不需要記憶每個腳本適用的方法

🔮 未來演進方向

已考慮但未實作的功能

1. 完全無代理架構

想法：只用 WMI/WinRM 原生能力，不上傳檔案 放棄原因：複雜邏輯用 WMI 表達困難，可讀性差

2. Web UI 介面

想法：提供圖形化介面選擇要執行的操作 放棄原因：目標用戶偏好命令列，增加複雜度

3. Ansible 整合

想法：包裝成 Ansible Playbook 放棄原因：Ansible Windows 支援學習成本高

潛在改進方向

1. 設定檔驗證

目標：在執行前驗證 JSON 設定檔格式
實作：JSON Schema 驗證
效益：減少執行時錯誤

2. 回滾機制

目標：對於風險較高的操作提供自動回滾
實作：操作前建立系統還原點
效益：提高操作安全性

3. 多機器並行

目標：同時管理多台 Windows 機器
實作：機器清單 + 並行執行框架
效益：適應大規模部署場景

🎓 學到的經驗

設計原則

1. 簡單勝於聰明：雙檔案架構雖然檔案多，但邏輯清晰
2. 具體問題具體分析：SSH vs WinRM 沒有銀彈，各有適用場景
3. 向前相容比向後相容重要：優先支援新的系統和軟體版本
4. 可觀測性是必需的：詳細日誌比省儲存空間重要

踩過的坑

1. 編碼問題：多語系環境下字元編碼永遠是問題
2. 防火牆設定檔：Windows 防火牆設定比想像的複雜
3. 軟體版本變更：上游軟體變更設定格式會破壞自動化
4. 網路環境假設：不同網路環境對連線方法的支援度不同

成功經驗

1. 配置外部化：JSON 配置檔讓腳本適應性大增
2. 智慧預設值：合理的預設值減少配置負擔
3. 詳細錯誤訊息：投資在錯誤訊息品質上，除錯效率高很多
4. 文檔分層：README/QUICKSTART/SUMMARY 分工讓使用者快速找到需要的資訊

---

這個專案的核心價值：將複雜的 Windows 系統管理任務轉換為簡單的命令列操作，讓跨平台的系統管理變得優雅而可靠。

🔗 相關文檔：

• README.md - 腳本功能完整參考
• QUICKSTART.md - 實用的操作指南
• CLAUDE.md - 深度技術實作文檔