S3 채널 추가

적합한 경우

다음과 같은 경우 S3 채널을 사용하세요.

• Cloudflare R2, Backblaze B2, MinIO, AWS S3 또는 기타 호환 공급자처럼 S3 호환 오브젝트 스토리지 서비스에 연결하려는 경우.
• Endpoint, Access Key, Secret Key를 사용하는 표준 S3 구성 방식을 선호하는 경우.
• Cloudflare R2의 네이티브 바인딩 채널을 사용하고 싶지 않거나, 저장소 공급자가 Cloudflare R2가 아닌 경우.

시작하기 전에 필요한 항목

요구 사항	용도
S3 Endpoint	오브젝트 스토리지 서비스의 S3 API 엔드포인트.
Bucket name	파일이 저장될 버킷.
Region	저장소 리전. Cloudflare R2에서는 일반적으로 auto입니다.
Access Key ID	S3 액세스 키 ID.
Secret Access Key	S3 시크릿 액세스 키.
CDN domain	파일 접근용 선택적 사용자 지정 도메인.

S3 API를 통해 Cloudflare R2를 사용하는 예:

Endpoint: https://your-account-id.r2.cloudflarestorage.com
Bucket: your-r2-bucket-name
Region: auto
Access Key ID: copied from the Cloudflare R2 API token
Secret Access Key: copied from the Cloudflare R2 API token

추가 위치

1. 시스템 설정을 엽니다.
2. 업로드 설정으로 이동합니다.
3. 오른쪽 위의 Add Channel을 클릭합니다.
4. S3를 선택합니다.

필드 참조

필드	기능	필수
채널 이름	이 S3 채널을 식별하기 쉬운 이름. 예: s3test 또는 R2-S3.	예
채널 활성화	이 채널이 업로드 대상 선택에 참여할지 제어합니다.	권장
Endpoint	https://. 포함한 전체 S3 서비스 엔드포인트.	예
Custom CDN domain	선택 사항. 설정하면 생성되는 파일 링크가 이 도메인을 우선 사용합니다.	아니요
Bucket name	버킷 이름. 예: s3test 또는 img-r2.	예
Bucket region	리전. Cloudflare R2에서는 일반적으로 auto입니다.	예
Access Key ID	S3 액세스 키 ID.	예
Secret Access Key	S3 시크릿 액세스 키.	예
Path-style access	호환성 스위치. 기본값은 꺼짐입니다. 일부 MinIO, OpenList 또는 자체 호스팅 S3 서비스에서 필요할 수 있습니다.	아니요
Quota limit	이 S3 채널이 용량 기준 업로드 대상 선택에 참여할지 제어합니다.	아니요
Capacity limit	쿼터 제한을 활성화한 뒤 필요합니다. 예: 10 GB.	쿼터 제한이 활성화된 경우 필수
Threshold	사용량이 이 비율에 도달하면 쓰기를 중지합니다. 예: 90%.	쿼터 제한이 활성화된 경우 필수
Remark	자체 유지보수용 메모.	아니요

Cloudflare R2 S3 API 키 만들기

1. Cloudflare Dashboard를 엽니다.
2. R2 Object Storage로 이동합니다.
3. Manage R2 API Tokens 또는 API token 관리 항목을 찾습니다.

4. 대상 버킷에 접근할 수 있는 R2 API 토큰을 만듭니다.

5. 생성된 Access Key ID와 Secret Access Key를 복사합니다.

6. R2 버킷 페이지로 돌아가 버킷 이름을 확인합니다.
7. 계정의 S3 API 엔드포인트를 기록합니다. 일반적으로 다음과 같은 형식입니다.

https://your-account-id.r2.cloudflarestorage.com

설정 단계

1. 업로드 설정을 엽니다.
2. Add Channel을 클릭합니다.
3. S3를 선택합니다.
4. 식별하기 쉬운 채널 이름을 입력합니다. 예: s3test.
5. Endpoint에 S3 API 엔드포인트를 입력합니다.
6. 사용자 지정 CDN을 사용하는 경우 Custom CDN domain에 입력합니다. 그렇지 않으면 비워 둡니다.
7. 버킷 이름을 입력합니다.
8. region을 입력합니다. Cloudflare R2 예에서는 auto를 사용합니다.
9. Access Key ID와 Secret Access Key를 입력합니다.
10. 공급자가 명시적으로 요구하지 않는 한 path-style access는 꺼진 상태로 둡니다.
11. 용량 제어를 사용하려면 쿼터 제한을 활성화하고 capacity limit과 threshold를 입력합니다.
12. 저장을 클릭합니다.

확인 방법

확인 항목	확인 방법
채널 카드 표시	저장 후 업로드 설정 페이지에 S3 채널 카드가 표시됩니다.
채널 활성화	카드 오른쪽 위의 스위치가 켜진 상태로 유지됩니다.
주요 필드 저장	상세 보기에서 Endpoint, Bucket, Region, path-style access 및 관련 필드를 확인할 수 있습니다.
업로드 동작	테스트 이미지를 업로드하고 대상 버킷에 오브젝트가 나타나는지 확인합니다.
링크 열림	업로드 후 반환된 이미지 링크가 정상적으로 열립니다.
용량 표시 동작	쿼터 제한이 활성화된 경우 카드에 사용 용량과 설정된 한도가 표시됩니다.

S3 용량 통계는 공급자 버킷을 실시간으로 조회하지 않고, ImgHost의 로컬 파일 기록에서 계산됩니다. S3 설정을 저장하면 시스템은 현재 D1 records에서 quota ledger를 다시 계산합니다.

FAQ

path-style access를 활성화해야 하나요?

일반적으로는 필요하지 않습니다.

S3 호환 공급자가 virtual-hosted-style URL을 지원하지 않거나 공급자 문서에서 path-style access를 명시적으로 요구하는 경우에만 활성화하세요. 일부 MinIO, 자체 호스팅 S3, OpenList 호환 엔드포인트에서는 필요할 수 있습니다.

CDN domain은 무엇에 사용하나요?

버킷 앞단에 CDN 또는 사용자 지정 접근 도메인을 두는 경우 여기에 입력합니다.

설정 후 생성되는 파일 링크는 이 도메인을 우선 사용합니다. CDN을 사용하지 않으면 비워 둡니다.

업로드가 실패하는 이유는 무엇인가요?

먼저 다음 항목을 확인하세요.

1. Endpoint에 https://. 포함한 전체 URL이 들어 있습니다.
2. 버킷 이름이 올바릅니다.
3. Region이 공급자 요구 사항과 일치합니다.
4. Access Key ID와 Secret Access Key가 완전히 복사되었습니다.
5. 키에 대상 버킷에 대한 쓰기 권한이 있습니다.
6. 공급자가 path-style access를 요구하지 않거나, 필요한 경우 path-style access가 활성화되어 있습니다.

빠른 체크리스트

Prepare S3 Endpoint, Bucket, Region, Access Key, and Secret Key
-> Open Upload Settings
-> Add Channel
-> Select S3
-> Enter Endpoint / Bucket / Region / Access Key / Secret Key
-> Enter a CDN domain if needed
-> Leave path-style access off by default
-> Enable quota limit if needed
-> Save
-> Upload a test image and check the result