Restructure project documentation with clear separation of concerns
- README.md: Reference manual with detailed script functionality - QUICKSTART.md: Practical guide for installation, configuration, and troubleshooting - SUMMARY.md: Design rationale and architectural decisions Each document serves distinct user needs without overlap. Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
This commit is contained in:
252
SUMMARY.md
Normal file
252
SUMMARY.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# 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
|
||||
```bash
|
||||
# 在每個 .sh 腳本中加入
|
||||
printf '\xEF\xBB\xBF' > /tmp/script_with_bom.ps1
|
||||
cat original.ps1 >> /tmp/script_with_bom.ps1
|
||||
```
|
||||
|
||||
### 問題二：防火牆設定重啟後失效
|
||||
**現象**：重啟 Windows 機器後 SSH 無法連線
|
||||
**原因**：Private/Public 設定檔會恢復為系統預設（阻擋入站）
|
||||
**解決**：建立跨所有設定檔的永久規則
|
||||
```powershell
|
||||
# 不只設定 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 找出正確的安裝特定設定檔路徑
|
||||
```powershell
|
||||
# 查找正確的設定檔路徑邏輯
|
||||
$InstallSection = Get-Content profiles.ini | Select-String "Install"
|
||||
$ProfilePath = Get-Content profiles.ini | Select-String "Default=" | ForEach-Object { ... }
|
||||
```
|
||||
|
||||
### 問題五：WinRM 命令長度限制
|
||||
**現象**：大型 PowerShell 腳本透過 WinRM 執行失敗
|
||||
**原因**：WinRM 有命令列長度限制，複雜腳本會超過限制
|
||||
**解決**：智慧選擇器根據腳本大小自動選擇連線方法
|
||||
```python
|
||||
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](README.md) - 腳本功能完整參考
|
||||
- [QUICKSTART.md](QUICKSTART.md) - 實用的操作指南
|
||||
- [CLAUDE.md](CLAUDE.md) - 深度技術實作文檔
|
||||
Reference in New Issue
Block a user