dd86ccb782
- R2StorageAdapter: S3 호환 클라이언트 래퍼
- R2FileHandler: 그누보드 통합 핸들러
- Presigned URL 지원
- 유저별 경로 분리 (users/{member_id}/...)
- 대용량 파일 멀티파트 업로드 지원
- 로컬 스토리지 폴백
- DB 마이그레이션 스크립트 포함
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
173 lines
4.1 KiB
Markdown
173 lines
4.1 KiB
Markdown
# 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
|