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:
288
QUICKSTART.md
Normal file
288
QUICKSTART.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# Quick Start Guide
|
||||
|
||||
快速上手 Windows Remote Toolkit，從安裝到實際使用。
|
||||
|
||||
## 🚀 5 分鐘快速開始
|
||||
|
||||
### 1. 準備執行環境
|
||||
|
||||
#### macOS/Linux 需求
|
||||
```bash
|
||||
# 安裝 sshpass（SSH 方法必需）
|
||||
brew install hudochenkov/sshpass/sshpass
|
||||
|
||||
# 安裝 Python WinRM 庫（WinRM 方法，可選）
|
||||
pip3 install pywinrm
|
||||
```
|
||||
|
||||
#### 目標 Windows 機器需求
|
||||
- Windows 10/11 with PowerShell 5.1
|
||||
- 啟用 OpenSSH Server（連接埠 22）
|
||||
- 網路可達
|
||||
|
||||
### 2. 驗證連線
|
||||
|
||||
```bash
|
||||
# 測試基本連線
|
||||
ssh Admin@192.168.88.112
|
||||
|
||||
# 或使用自訂連線參數
|
||||
HOST=your.windows.ip USER_NAME=your_user PASS='your_pass' ./scripts/ssh/recon.sh
|
||||
```
|
||||
|
||||
### 3. 執行第一個腳本
|
||||
|
||||
```bash
|
||||
# 系統偵察（安全且資訊豐富）
|
||||
./scripts/ssh/recon.sh
|
||||
|
||||
# 查看結果
|
||||
ls logs/recon-*
|
||||
```
|
||||
|
||||
## 🎯 常見使用情境
|
||||
|
||||
### 情境一：新機器初始化
|
||||
```bash
|
||||
# 步驟 1：確保永久 SSH 存取
|
||||
./scripts/ssh/firewall-allow-ssh.sh
|
||||
|
||||
# 步驟 2：啟用 WinRM（可選，用於快速執行）
|
||||
./scripts/ssh/enable-winrm.sh
|
||||
|
||||
# 步驟 3：系統偵察
|
||||
./scripts/ssh/recon.sh
|
||||
|
||||
# 步驟 4：Windows 啟用
|
||||
./scripts/ssh/activate-windows.sh
|
||||
|
||||
# 步驟 5：移除 AI 組件 → **重啟** → 驗證
|
||||
./scripts/ssh/remove-windows-ai.sh
|
||||
# 手動重啟機器後
|
||||
./scripts/ssh/verify-ai-removed.sh
|
||||
|
||||
# 步驟 6：系統去膨脹 → **重啟** → 驗證
|
||||
./scripts/ssh/win11debloat.sh
|
||||
# 手動重啟機器後
|
||||
./scripts/ssh/verify-debloat.sh
|
||||
|
||||
# 步驟 7：安裝常用軟體
|
||||
./scripts/ssh/install-apps.sh
|
||||
./scripts/ssh/install-thunderbird.sh
|
||||
./scripts/ssh/setup-thunderbird.sh
|
||||
```
|
||||
|
||||
### 情境二：應用程式管理
|
||||
```bash
|
||||
# 安裝常用軟體
|
||||
./scripts/ssh/install-apps.sh
|
||||
|
||||
# 移除特定軟體（自訂 config/remove-apps-config.json）
|
||||
./scripts/ssh/remove-apps.sh
|
||||
|
||||
# 安裝診斷工具
|
||||
./scripts/ssh/install-nirsoft.sh
|
||||
```
|
||||
|
||||
### 情境三：系統診斷
|
||||
```bash
|
||||
# 完整系統資訊
|
||||
./scripts/ssh/recon.sh
|
||||
|
||||
# 深度診斷並打包結果
|
||||
./scripts/ssh/nirsoft-dump.sh
|
||||
|
||||
# 檢查系統狀態
|
||||
./scripts/ssh/verify-debloat.sh
|
||||
./scripts/ssh/verify-ai-removed.sh
|
||||
```
|
||||
|
||||
## ⚙️ 自訂配置
|
||||
|
||||
### 修改連線目標
|
||||
有三種方法：
|
||||
|
||||
#### 方法一：環境變數（單次執行）
|
||||
```bash
|
||||
HOST=192.168.1.100 USER_NAME=MyUser PASS='MyPass' ./scripts/ssh/recon.sh
|
||||
```
|
||||
|
||||
#### 方法二：Shell 設定檔（長期使用）
|
||||
在 `~/.zshrc` 或 `~/.bashrc` 中加入：
|
||||
```bash
|
||||
export HOST=192.168.1.100
|
||||
export USER_NAME=MyUser
|
||||
export PASS='MyPass'
|
||||
```
|
||||
|
||||
#### 方法三：修改腳本檔案（不推薦）
|
||||
直接編輯各 `.sh` 檔案中的預設值。
|
||||
|
||||
### 自訂配置檔案
|
||||
|
||||
#### Win11Debloat 設定
|
||||
編輯 `config/win11debloat-config.json`：
|
||||
```json
|
||||
{
|
||||
"Tweaks": ["DisableTelemetry", "DisableCortana"],
|
||||
"Apps": ["Microsoft.BingWeather", "Microsoft.Xbox*"]
|
||||
}
|
||||
```
|
||||
|
||||
#### Thunderbird 電子郵件設定
|
||||
編輯 `config/thunderbird-config.json`：
|
||||
```json
|
||||
{
|
||||
"accounts": [
|
||||
{
|
||||
"name": "我的信箱",
|
||||
"email": "user@gmail.com",
|
||||
"provider": "gmail"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### 應用程式移除清單
|
||||
編輯 `config/remove-apps-config.json`：
|
||||
```json
|
||||
{
|
||||
"apps": [
|
||||
"Microsoft.BingNews",
|
||||
"Microsoft.GetHelp"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 🏃♂️ 效能優化
|
||||
|
||||
### SSH vs WinRM 方法選擇
|
||||
|
||||
| 方法 | 速度 | 穩定性 | 適用場景 |
|
||||
|------|------|--------|----------|
|
||||
| SSH | 標準 | 高 | 大型腳本、批次操作 |
|
||||
| WinRM | 1.9x 快 | 中等 | 小型腳本、快速查詢 |
|
||||
|
||||
```bash
|
||||
# SSH 方法（預設）
|
||||
./scripts/ssh/recon.sh
|
||||
|
||||
# WinRM 方法
|
||||
python3 scripts/winrm/test_simple_winrm.py
|
||||
|
||||
# 智慧選擇（自動判斷最佳方法）
|
||||
python3 scripts/winrm/smart_executor.py scripts/powershell/recon.ps1
|
||||
```
|
||||
|
||||
### 批次執行技巧
|
||||
```bash
|
||||
# 平行執行多個獨立任務
|
||||
./scripts/ssh/install-apps.sh &
|
||||
./scripts/ssh/install-nirsoft.sh &
|
||||
wait
|
||||
|
||||
# 循序執行有相依性的任務
|
||||
./scripts/ssh/remove-windows-ai.sh && \
|
||||
echo "請重啟機器後按 Enter 繼續..." && read && \
|
||||
./scripts/ssh/verify-ai-removed.sh
|
||||
```
|
||||
|
||||
## 🛠️ 故障排除
|
||||
|
||||
### 常見問題
|
||||
|
||||
#### 1. "Permission denied" 或連線失敗
|
||||
```bash
|
||||
# 檢查 SSH 服務狀態
|
||||
ssh Admin@192.168.88.112 'Get-Service sshd'
|
||||
|
||||
# 檢查防火牆規則
|
||||
ssh Admin@192.168.88.112 'netsh advfirewall firewall show rule name=all | findstr SSH'
|
||||
```
|
||||
|
||||
**解決方案**：
|
||||
- 確認 Windows 已啟用 OpenSSH Server
|
||||
- 執行 `firewall-allow-ssh.sh` 建立防火牆規則
|
||||
|
||||
#### 2. 重啟後無法連線
|
||||
**原因**：Windows 防火牆設定檔重置
|
||||
|
||||
**解決方案**：
|
||||
```bash
|
||||
# 重新設定防火牆（從能連線的網路或本機執行）
|
||||
./scripts/ssh/firewall-allow-ssh.sh
|
||||
```
|
||||
|
||||
#### 3. PowerShell 腳本執行策略錯誤
|
||||
**錯誤訊息**：`execution of scripts is disabled on this system`
|
||||
|
||||
**解決方案**：腳本已自動使用 `-ExecutionPolicy Bypass`，無需額外設定
|
||||
|
||||
#### 4. WinRM 無法連線
|
||||
```bash
|
||||
# 檢查 WinRM 設定
|
||||
./scripts/ssh/check-winrm.sh
|
||||
|
||||
# 修復 WinRM 配置
|
||||
./scripts/ssh/fix-winrm.sh
|
||||
```
|
||||
|
||||
#### 5. 中文字元顯示亂碼
|
||||
**原因**：PowerShell 編碼問題
|
||||
|
||||
**解決方案**：腳本自動處理 UTF-8 BOM，無需手動修正
|
||||
|
||||
### 偵錯技巧
|
||||
|
||||
#### 查看詳細執行記錄
|
||||
```bash
|
||||
# 即時監看日誌
|
||||
tail -f logs/recon-PC-74269-$(date +%Y%m%d)*.log
|
||||
|
||||
# 搜尋錯誤訊息
|
||||
grep -i error logs/*.log
|
||||
```
|
||||
|
||||
#### 測試單一 PowerShell 命令
|
||||
```bash
|
||||
# 透過 SSH 執行單一命令
|
||||
ssh Admin@192.168.88.112 'powershell -Command "Get-ComputerInfo"'
|
||||
```
|
||||
|
||||
#### 開啟偵錯模式
|
||||
```bash
|
||||
# 在腳本中加入偵錯資訊（環境變數）
|
||||
DEBUG=1 ./scripts/ssh/recon.sh
|
||||
```
|
||||
|
||||
## 📝 最佳實務
|
||||
|
||||
### 執行順序建議
|
||||
1. **連線測試** → `recon.sh`
|
||||
2. **防火牆設定** → `firewall-allow-ssh.sh`
|
||||
3. **系統配置** → `remove-windows-ai.sh` → 重啟 → `win11debloat.sh` → 重啟
|
||||
4. **軟體安裝** → `install-apps.sh` 等
|
||||
5. **帳戶管理**（最後）→ `rename-hide-accounts.sh`
|
||||
|
||||
### 安全注意事項
|
||||
- 不要在腳本中硬編碼密碼
|
||||
- 重要操作前先測試並備份
|
||||
- 帳戶重新命名操作建議最後執行
|
||||
- 敏感檔案已加入 `.gitignore`
|
||||
|
||||
### 備份策略
|
||||
```bash
|
||||
# 操作前先收集系統資訊
|
||||
./scripts/ssh/recon.sh
|
||||
./scripts/ssh/nirsoft-dump.sh
|
||||
|
||||
# 保存配置備份
|
||||
cp config/*.json config/backup/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
🔗 **相關文檔**：
|
||||
- [README.md](README.md) - 完整腳本功能參考
|
||||
- [SUMMARY.md](SUMMARY.md) - 架構設計理念
|
||||
- [CLAUDE.md](CLAUDE.md) - 技術實作細節
|
||||
213
README.md
213
README.md
@@ -1,22 +1,207 @@
|
||||
# Windows Remote Toolkit
|
||||
|
||||
A comprehensive remote management toolkit for configuring and managing Windows machines from macOS/Linux systems.
|
||||
A comprehensive remote management toolkit for configuring and managing Windows machines from macOS/Linux systems via SSH and WinRM.
|
||||
|
||||
## Overview
|
||||
## 🛠️ 腳本功能參考
|
||||
|
||||
This toolkit provides automated scripts for system debloating, application installation, security configuration, and diagnostics on remote Windows machines via SSH and WinRM.
|
||||
|
||||
## Quick Start
|
||||
### 系統配置類
|
||||
|
||||
#### `activate-windows.sh`
|
||||
透過 KMS 啟用 Windows 授權
|
||||
```bash
|
||||
# Enable SSH access
|
||||
./firewall-allow-ssh.sh
|
||||
|
||||
# System reconnaissance
|
||||
./recon.sh
|
||||
|
||||
# Remove Windows AI components
|
||||
./remove-windows-ai.sh
|
||||
./scripts/ssh/activate-windows.sh
|
||||
```
|
||||
|
||||
See [CLAUDE.md](CLAUDE.md) for detailed documentation and usage instructions.
|
||||
#### `firewall-allow-ssh.sh`
|
||||
在 Windows 防火牆中建立永久的 SSH 存取規則
|
||||
```bash
|
||||
./scripts/ssh/firewall-allow-ssh.sh
|
||||
```
|
||||
- 建立跨所有防火牆設定檔的入站規則
|
||||
- 確保重啟後 SSH 連線仍可用
|
||||
|
||||
#### `win11debloat.sh`
|
||||
執行 Win11Debloat 腳本移除膨脹軟體並停用遙測
|
||||
```bash
|
||||
./scripts/ssh/win11debloat.sh
|
||||
```
|
||||
- 使用 `config/win11debloat-config.json` 配置
|
||||
- 支援 `MODE=Apply|Revert` 環境變數
|
||||
|
||||
#### `remove-windows-ai.sh`
|
||||
移除 Windows AI/Copilot 組件
|
||||
```bash
|
||||
./scripts/ssh/remove-windows-ai.sh
|
||||
MODE=Apply ./scripts/ssh/remove-windows-ai.sh # 套用移除
|
||||
MODE=Revert ./scripts/ssh/remove-windows-ai.sh # 還原變更
|
||||
```
|
||||
|
||||
### 連線管理類
|
||||
|
||||
#### `enable-winrm.sh`
|
||||
配置 WinRM 服務用於快速連線
|
||||
```bash
|
||||
./scripts/ssh/enable-winrm.sh
|
||||
```
|
||||
|
||||
#### `test-winrm-connection.sh`
|
||||
測試 WinRM 連線狀態
|
||||
```bash
|
||||
./scripts/ssh/test-winrm-connection.sh
|
||||
```
|
||||
|
||||
#### `check-winrm.sh`
|
||||
檢查 WinRM 服務配置
|
||||
```bash
|
||||
./scripts/ssh/check-winrm.sh
|
||||
```
|
||||
|
||||
### 應用程式管理類
|
||||
|
||||
#### `install-apps.sh`
|
||||
批次安裝常用應用程式
|
||||
```bash
|
||||
./scripts/ssh/install-apps.sh
|
||||
```
|
||||
|
||||
#### `remove-apps.sh`
|
||||
批次移除指定應用程式
|
||||
```bash
|
||||
./scripts/ssh/remove-apps.sh
|
||||
```
|
||||
- 使用 `config/remove-apps-config.json` 配置
|
||||
|
||||
#### `install-thunderbird.sh`
|
||||
安裝 Mozilla Thunderbird
|
||||
```bash
|
||||
./scripts/ssh/install-thunderbird.sh
|
||||
```
|
||||
|
||||
#### `setup-thunderbird.sh`
|
||||
配置 Thunderbird 電子郵件帳戶
|
||||
```bash
|
||||
./scripts/ssh/setup-thunderbird.sh
|
||||
```
|
||||
- 使用 `config/thunderbird-config.json` 配置
|
||||
- 支援多種電子郵件提供商
|
||||
|
||||
#### `install-telegram.sh`
|
||||
安裝 Telegram Desktop（per-user 安裝）
|
||||
```bash
|
||||
./scripts/ssh/install-telegram.sh
|
||||
```
|
||||
|
||||
#### `install-nirsoft.sh`
|
||||
安裝 NirSoft 診斷工具集
|
||||
```bash
|
||||
./scripts/ssh/install-nirsoft.sh
|
||||
```
|
||||
|
||||
#### `install-cports.sh`
|
||||
安裝 CurrPorts 網路連線監控工具
|
||||
```bash
|
||||
./scripts/ssh/install-cports.sh
|
||||
```
|
||||
|
||||
### 診斷類
|
||||
|
||||
#### `recon.sh`
|
||||
完整系統偵察（15 個資訊區塊）
|
||||
```bash
|
||||
./scripts/ssh/recon.sh
|
||||
```
|
||||
- 硬體資訊、網路配置、軟體清單等
|
||||
- 輸出儲存到 `logs/` 目錄
|
||||
|
||||
#### `nirsoft-dump.sh`
|
||||
使用 NirSoft 工具進行系統診斷並打包結果
|
||||
```bash
|
||||
./scripts/ssh/nirsoft-dump.sh
|
||||
```
|
||||
- 輸出 ZIP 檔案到 `dumps/` 目錄
|
||||
|
||||
#### `verify-debloat.sh`
|
||||
驗證 Win11Debloat 變更是否已套用
|
||||
```bash
|
||||
./scripts/ssh/verify-debloat.sh
|
||||
```
|
||||
|
||||
#### `verify-ai-removed.sh`
|
||||
驗證 Windows AI 組件是否已移除
|
||||
```bash
|
||||
./scripts/ssh/verify-ai-removed.sh
|
||||
```
|
||||
|
||||
### 使用者管理類
|
||||
|
||||
#### `rename-hide-accounts.sh`
|
||||
重新命名或隱藏系統帳戶
|
||||
```bash
|
||||
./scripts/ssh/rename-hide-accounts.sh
|
||||
```
|
||||
- **⚠️ 風險操作**：建議最後執行
|
||||
|
||||
#### `apply-ui-to-user.sh`
|
||||
將 UI 設定套用到指定使用者
|
||||
```bash
|
||||
TARGET_USER=username ./scripts/ssh/apply-ui-to-user.sh
|
||||
```
|
||||
|
||||
### 輸入法配置
|
||||
|
||||
#### `configure-ime.sh`
|
||||
配置中文輸入法設定
|
||||
```bash
|
||||
./scripts/ssh/configure-ime.sh
|
||||
```
|
||||
|
||||
## 🚀 快速執行包裝器
|
||||
|
||||
### SSH 方法（預設）
|
||||
```bash
|
||||
./ssh_run.sh <script.ps1> # 執行單一 PowerShell 腳本
|
||||
```
|
||||
|
||||
### WinRM 方法（更快）
|
||||
```bash
|
||||
./winrm_run.sh <script.ps1> # WinRM 執行
|
||||
python3 scripts/winrm/smart_executor.py <script.ps1> # 智慧選擇連線方法
|
||||
```
|
||||
|
||||
## ⚙️ 環境變數覆寫
|
||||
|
||||
所有腳本支援連線參數覆寫：
|
||||
```bash
|
||||
HOST=192.168.x.x USER_NAME=admin PASS='secret' ./scripts/ssh/recon.sh
|
||||
MODE=Apply ./scripts/ssh/remove-windows-ai.sh
|
||||
TARGET_USER=someone ./scripts/ssh/apply-ui-to-user.sh
|
||||
```
|
||||
|
||||
## 📋 配置檔案
|
||||
|
||||
| 檔案 | 用途 |
|
||||
|------|------|
|
||||
| `config/win11debloat-config.json` | Win11Debloat 操作設定 |
|
||||
| `config/thunderbird-config.json` | 電子郵件帳戶配置 |
|
||||
| `config/remove-apps-config.json` | 應用程式移除清單 |
|
||||
| `config/nirsoft-config.json` | NirSoft 工具下載設定 |
|
||||
|
||||
## 📁 輸出目錄
|
||||
|
||||
- `logs/` - 執行日誌（帶時間戳）
|
||||
- `dumps/` - 診斷資料 ZIP 檔案
|
||||
|
||||
## 🎯 預設連線目標
|
||||
|
||||
- **主機**：`192.168.88.112` (PC-74269)
|
||||
- **使用者**：`Admin`
|
||||
- **密碼**：`P@ssw0rd!`
|
||||
|
||||
可透過環境變數覆寫連線參數。
|
||||
|
||||
---
|
||||
|
||||
更多詳細資訊請參考：
|
||||
- [QUICKSTART.md](QUICKSTART.md) - 安裝與操作指南
|
||||
- [SUMMARY.md](SUMMARY.md) - 設計理念與架構說明
|
||||
- [CLAUDE.md](CLAUDE.md) - 完整技術文檔
|
||||
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