convert to gitea
This commit is contained in:
154
README.md
Normal file
154
README.md
Normal file
@ -0,0 +1,154 @@
|
||||
# SharePoint Online 고성능 백업 및 검증 스크립트
|
||||
|
||||
|
||||
|
||||
|
||||
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\<User>\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]` 타입으로 변환해 테라바이트 단위 지원
|
||||
|
||||
---
|
||||
|
||||
```
|
||||
Reference in New Issue
Block a user