# SharePoint Online 고성능 백업 및 검증 스크립트 ![PowerShell Version](https://img.shields.io/badge/PowerShell-7.2%2B-blue.svg) ![License](https://img.shields.io/badge/License-MIT-green.svg) Microsoft Graph API와 PoshRSJob 모듈을 활용하여 SharePoint Online 문서 라이브러리를 빠르고 안전하게 로컬로 백업하고, 백업된 데이터의 무결성을 검증하는 PowerShell 스크립트. --- ## ✨ 주요 기능 - 🚀 **고성능 병렬 다운로드**: `PoshRSJob` 모듈을 사용해 다수의 파일을 동시에 다운로드, 백업 속도 극대화 - 🔄 **지능형 재시도**: 실패 파일만 자동 재시도 → 전체 스캔 없이 빠른 복구 - 🛡️ **API 사용량 제한 대응**: `429 Too Many Requests` 오류 시 `Retry-After` 헤더 기반 대기 및 재시도 - 📊 **실시간 모니터링**: 진행률, 다운로드 속도, 경과 시간 표시 - 🔍 **백업 무결성 검증**: 로컬 백업과 원본 SharePoint를 비교해 누락/손상 여부 확인 - 📂 **파일/폴더명 정제**: 한글, 공백, 특수문자 포함된 이름 안전 변환 - 📑 **종합 보고서**: 용량 분석 포함 결과 로그 생성 --- ## 📋 필수 요구사항 1. PowerShell **7.2 이상** 2. PowerShell 모듈 - `Microsoft.Graph` - `PoshRSJob` 3. Microsoft Graph 권한: `Sites.Read.All` --- ## 🛠️ 설치 및 초기 설정 ### 1. PowerShell 7 설치 [공식 PowerShell GitHub 릴리스 페이지](https://github.com/PowerShell/PowerShell/releases)에서 최신 버전 설치. ### 2. 필수 모듈 설치 ```powershell Install-Module Microsoft.Graph -Scope CurrentUser -Force Install-Module PoshRSJob -Scope CurrentUser -Force ```` #### 🔹 PoshRSJob 모듈 설명 `ForEach-Object -Parallel` 대비 안정적인 병렬 작업 관리와 상태 추적을 지원하는 고성능 병렬 처리 모듈. 대규모 파일 다운로드에서 권장되는 사실상 표준. #### 🔹 PoshRSJob 수동 설치 네트워크/캐시 문제로 `Install-Module`이 실패할 경우: 1. 캐시 삭제 후 재시도: ```powershell Remove-Item -Path "$env:LOCALAPPDATA\NuGet\Cache\*" -Recurse -Force -ErrorAction SilentlyContinue ``` 2. [PowerShell Gallery](https://www.powershellgallery.com/packages/PoshRSJob)에서 `.nupkg` 다운로드 3. 파일 속성 → **차단 해제(Unblock)** 체크 4. 확장자 `.zip`으로 변경 후 압축 해제 5. 모듈 경로(`($env:PSModulePath -split ';')[0]`)에 `PoshRSJob` 폴더 생성 후 복사 * 예: `C:\Users\\Documents\PowerShell\Modules\PoshRSJob\` 6. 설치 확인: ```powershell Get-Module -ListAvailable PoshRSJob ``` ### 3. Microsoft Graph 최초 연결 ```powershell Connect-MgGraph -Scopes "Sites.Read.All" ``` --- ## 🚀 사용법 ### 1. 백업 스크립트 ```powershell .\Backup-SPO-PoshRSJob.ps1 -SiteUrl "https://tenant.sharepoint.com/sites/SiteName" ``` * `ThrottleLimit`으로 병렬 다운로드 개수 조정 (기본값 3, 권장 1\~3) * 실패 시 `_failed_files.json` 기반 자동 이어받기 지원 ### 2. 검증 스크립트 ```powershell .\Verify-SPO-Backup.ps1 -SiteUrl "https://tenant.sharepoint.com/sites/SiteName" -BackupPath "D:\Backups\SharePoint" ``` --- ## 📊 보고서 예시 ``` ================================================== SharePoint 백업 결과 보고서 (PoshRSJob) ================================================== > 백업 일시 : 2025-08-20 13:31:22 > 대상 사이트 : https://oneunivrs.sharepoint.com/sites/Anvil > 저장 위치 : F:\action_anvil -------------------------------------------------- [ 사이트 저장소 현황 ] - 전체 할당량 (Quota) : 100.00 GB - 실제 총 사용량 : 101.01 GB - 현재 파일 총 용량 : 98.53 GB - 기타 용량 (버전 기록 등) : 2.48 GB -------------------------------------------------- [ 백업된 파일 정보 ] - 스캔된 총 폴더 수 : 264 개 - 스캔된 총 파일 수 : 2612 개 -------------------------------------------------- [ 백업 작업 결과 ] - ✅ 성공 : 2612 개 - ⏩ 건너뜀 : 0 개 - ❌ 실패 : 0 개 - ⏱️ 총 소요 시간 : 00:47:51 - ↓ 실제 평균 속도 : 34.30 MB/s ================================================== ``` --- ## 💡 문제 해결 및 고급 주제 (Troubleshooting & Advanced Topics) ### 1. API 사용량 제한 (429 오류) * **문제:** 대용량 다운로드 시 `Too Many Requests` 발생 * **해결:** * `Retry-After` 헤더 기반 대기 후 재시도 * 점진적 대기 (5초, 10초, 15초...) 적용 * **팁:** `-ThrottleLimit` 값은 1\~2 권장 ### 2. 왜 PoshRSJob 인가? * `ForEach-Object -Parallel`은 공유 변수 전달 시 오류 발생 * `PoshRSJob`은 Job 기반 격리 실행, 상태 추적과 안정성 우수 ### 3. 파일 이름 문제 * Windows 불가 문자를 `_`로 치환 (예: `:` → `_`) * 모든 파일 작업에 `-LiteralPath` 적용 ### 4. 대용량(>2GB) 처리 * PowerShell 기본 `Int32` 한계로 오류 발생 * 모든 파일 크기 계산을 `[long]` 타입으로 변환해 테라바이트 단위 지원 --- ```