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) - 技術實作細節
|
||||
Reference in New Issue
Block a user