feat: Gnuboard5 Cloudflare R2 Storage Module

- R2StorageAdapter: S3 호환 클라이언트 래퍼 - R2FileHandler: 그누보드 통합 핸들러 - Presigned URL 지원 - 유저별 경로 분리 (users/{member_id}/...) - 대용량 파일 멀티파트 업로드 지원 - 로컬 스토리지 폴백 - DB 마이그레이션 스크립트 포함 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-10 14:36:38 +09:00
commit dd86ccb782
8 changed files with 1628 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,172 @@
+# Gnuboard5 Cloudflare R2 Storage Module
+
+그누보드5를 위한 Cloudflare R2 파일 스토리지 모듈입니다.
+
+## 주요 기능
+
+- Cloudflare R2 S3 호환 API를 통한 파일 업로드/다운로드
+- 유저별 경로 분리 (`users/{member_id}/...`)
+- Presigned URL을 통한 보안 다운로드
+- 대용량 파일 멀티파트 업로드 지원 (100MB+)
+- 로컬 스토리지 폴백 지원
+- 기존 파일 R2 마이그레이션 도구
+
+## 디렉토리 구조
+
+```
+gnuboard-r2-storage/
+├── extend/
+│   ├── r2_hooks.php              # 그누보드 자동 로드 훅
+│   └── r2-storage/
+│       ├── composer.json
+│       ├── r2_config.php         # R2 설정 파일
+│       ├── src/
+│       │   ├── R2StorageAdapter.php
+│       │   └── R2FileHandler.php
+│       └── migrations/
+│           ├── 001_add_r2_columns.sql
+│           └── 002_rollback.sql
+└── README.md
+```
+
+## 설치 방법
+
+### 1. Cloudflare R2 설정
+
+1. [Cloudflare Dashboard](https://dash.cloudflare.com) 접속
+2. R2 Object Storage > Create bucket
+3. 버킷 이름: `gnuboard-files` (또는 원하는 이름)
+4. Manage R2 API Tokens > Create API token
+   - Permissions: Object Read & Write
+   - Specify bucket: 생성한 버킷 선택
+5. Access Key ID와 Secret Access Key 저장
+
+### 2. 모듈 설치
+
+```bash
+# 그누보드 extend 디렉토리에 복사
+cp -r gnuboard-r2-storage/extend/* /path/to/gnuboard/extend/
+
+# Composer 의존성 설치
+cd /path/to/gnuboard/extend/r2-storage
+composer install
+```
+
+### 3. 설정 파일 수정
+
+`extend/r2-storage/r2_config.php` 파일을 열고 R2 인증 정보 입력:
+
+```php
+define('R2_ACCOUNT_ID', 'your_account_id');
+define('R2_ACCESS_KEY_ID', 'your_access_key');
+define('R2_SECRET_ACCESS_KEY', 'your_secret_key');
+define('R2_BUCKET_NAME', 'gnuboard-files');
+```
+
+### 4. 데이터베이스 마이그레이션
+
+```bash
+# MySQL에서 실행
+mysql -u username -p database_name < extend/r2-storage/migrations/001_add_r2_columns.sql
+```
+
+## 사용 방법
+
+### 기본 업로드
+
+```php
+// 파일 업로드
+$result = r2_upload_file($_FILES['bf_file'][0], $bo_table, $member['mb_no']);
+
+if ($result['success']) {
+    $r2Key = $result['r2_key'];
+    $downloadUrl = $result['url'];
+}
+```
+
+### 다운로드 URL 생성
+
+```php
+$downloadUrl = r2_get_download_url($r2Key);
+```
+
+### 파일 삭제
+
+```php
+r2_delete_file($r2Key);
+```
+
+### 연결 테스트
+
+```php
+$test = r2_test_connection();
+var_dump($test);
+```
+
+## 그누보드 통합
+
+### write_update.php 수정 예시
+
+```php
+// 기존 파일 업로드 코드 전에 추가
+if (is_r2_enabled()) {
+    $r2Result = r2_before_upload($file, $bo_table, $member['mb_no']);
+    if ($r2Result && $r2Result['storage_type'] === 'r2') {
+        // R2 업로드 성공 - DB에 r2_key 저장
+        $bf_r2_key = $r2Result['r2_key'];
+        $bf_storage_type = 'r2';
+        // 로컬 move_uploaded_file 스킵
+    }
+}
+```
+
+### get_file() 결과 확장
+
+```php
+$files = get_file($bo_table, $wr_id);
+$files = r2_extend_files($files);
+```
+
+## 마이그레이션 도구
+
+기존 로컬 파일을 R2로 마이그레이션:
+
+```php
+// 특정 게시판의 파일 100개 마이그레이션
+$result = r2_migrate_board_files('free', 100);
+print_r($result);
+// ['migrated' => 95, 'failed' => 2, 'skipped' => 3, 'errors' => [...]]
+```
+
+## 저장 경로 구조
+
+```
+bucket/
+├── users/{member_id}/
+│   ├── board/{bo_table}/{filename}     # 게시판 첨부파일
+│   ├── editor/{date}/{filename}        # 에디터 이미지
+│   └── profile/{filename}              # 프로필 이미지
+└── public/
+    └── board/{bo_table}/{filename}     # 비회원 업로드
+```
+
+## 설정 옵션
+
+| 상수 | 기본값 | 설명 |
+|------|--------|------|
+| `R2_ENABLED` | `true` | R2 스토리지 활성화 |
+| `R2_USE_PRESIGNED_URL` | `true` | Presigned URL 사용 |
+| `R2_PRESIGNED_EXPIRY` | `3600` | URL 만료 시간 (초) |
+| `R2_MULTIPART_THRESHOLD` | `100MB` | 멀티파트 업로드 임계값 |
+| `R2_FALLBACK_TO_LOCAL` | `true` | R2 실패 시 로컬 저장 |
+
+## 요구사항
+
+- PHP 7.4+
+- Composer
+- AWS SDK for PHP 3.x
+- 그누보드 5.x
+
+## 라이선스
+
+MIT License