자주 묻는 질문

IPFS Ninja에 대해 자주 묻는 질문입니다.

일반

IPFS Ninja란 무엇인가요?

IPFS Ninja는 관리형 IPFS 피닝 서비스입니다. 간단한 REST API를 통해 모든 파일을 업로드하거나 IPFS 네트워크의 기존 CID를 피닝할 수 있습니다. 각 파일은 영구 콘텐츠 식별자(CID)를 받으며, ipfs.ninja/ipfs/<CID> 게이트웨이를 통해 접근할 수 있습니다.

어떤 파일 유형이 지원되나요?

모든 파일 유형이 지원됩니다. JSON 객체와 배열은 직접 전송할 수 있습니다. 기타 모든 파일(이미지, PDF, HTML, 비디오, 오디오, 바이너리)은 base64 인코딩된 콘텐츠로 전송됩니다.

파일 크기 제한이 있나요?

개별 업로드는 플랜의 저장 공간 할당량에 의해 제한됩니다. 사용 가능한 저장 공간 외에 파일별 크기 제한은 없습니다.

IPFS에 이미 존재하는 콘텐츠를 피닝할 수 있나요?

네. POST /pin에 유효한 CID를 제공하세요. 클러스터가 IPFS 네트워크에서 콘텐츠를 가져와 계정에 피닝합니다. 자세한 내용은 피닝 API 문서를 참조하세요.

피닝에 얼마나 걸리나요?

파일 크기와 해당 콘텐츠를 보유한 IPFS 노드의 수에 따라 다릅니다. 작고 널리 분산된 파일은 몇 초 내에 피닝됩니다. 크거나 드물게 피닝된 콘텐츠는 몇 분이 걸릴 수 있습니다. 피닝 엔드포인트는 즉시 pinning 상태를 반환합니다 — GET /pin/:cid를 폴링하여 진행 상황을 확인하세요.

CID를 찾을 수 없으면 어떻게 되나요?

상태가 failed로 변경됩니다. 이는 CID가 유효하지 않거나 접근 가능한 IPFS 노드에 콘텐츠가 더 이상 존재하지 않음을 의미합니다.

IPFS에 업로드된 데이터는 공개인가요?

네. IPFS에 피닝된 모든 콘텐츠는 CID를 통해 모든 IPFS 게이트웨이에서 공개적으로 접근할 수 있습니다. 비공개 접근이 필요한 경우 토큰 필수 모드의 전용 게이트웨이를 사용하세요 — 게이트웨이를 통한 접근은 제한되지만, 콘텐츠는 더 넓은 IPFS 네트워크에서 여전히 이용할 수 있습니다.

계정을 취소하면 파일이 IPFS에 남아 있나요?

취소 시 노드에서 파일의 피닝을 해제합니다. 다른 IPFS 노드가 콘텐츠를 캐시한 경우 여전히 접근할 수 있을 수 있습니다. 그러나 활성 피닝이 없으면 파일은 결국 네트워크 전체의 가비지 컬렉션에 의해 제거됩니다.

인증 및 API

API 요청은 어떻게 인증하나요?

X-Api-Key 헤더로 API 키를 전달하세요. 대시보드의 API 키 페이지에서 키를 생성하세요.

API 속도 제한이 있나요?

없습니다. IPFS Ninja는 API 요청에 속도 제한을 부과하지 않습니다. 모든 플랜에서 필요한 만큼 요청을 보낼 수 있습니다.

API 키가 만료되나요?

아니요. API 키는 삭제할 때까지 유효합니다. 여러 개의 키를 생성하고 개별적으로 폐기할 수 있습니다.

API 키와 게이트웨이 토큰의 차이점은 무엇인가요?

API 키(bws_)는 전체 접근 권한을 가집니다 — 업로드, 삭제, 파일 목록 조회. 게이트웨이 토큰(gwt_)은 읽기 전용이며 전용 게이트웨이를 통해서만 파일에 접근할 수 있습니다. 게이트웨이 토큰은 프론트엔드 앱에 안전하게 임베드할 수 있습니다.

전용 게이트웨이

전용 게이트웨이란 무엇인가요?

자체 서브도메인(예: abc123.gw.ipfs.ninja)의 프라이빗 IPFS 게이트웨이로, 계정에 피닝된 파일만 제공합니다. 퍼블릭 게이트웨이와 달리 다른 사용자의 CID를 해석하지 않습니다.

어떤 플랜에 전용 게이트웨이가 포함되나요?

전용 게이트웨이는 Nirvana 플랜($29/월)에서 사용할 수 있으며, 월 50 GB의 게이트웨이 대역폭이 포함됩니다.

게이트웨이 접근을 제한할 수 있나요?

네. 토큰 필수 모드(모든 요청에 gwt_ 토큰 필요)를 활성화하거나 IP 화이트리스트(최대 100개 주소)를 설정할 수 있습니다.

오리진/도메인으로 게이트웨이를 제한할 수 있나요?

네. 게이트웨이 설정에서 allowedOrigins에 HTTPS 오리진 목록을 설정하세요. 해당 오리진의 브라우저 요청만 허용됩니다. Origin 헤더가 없는 비브라우저 요청(서버 측 요청이나 curl 등)은 제한 없이 통과합니다. 빈 목록은 모든 오리진을 허용합니다.

서명된 업로드 토큰이란 무엇인가요?

서명된 업로드 토큰은 클라이언트 측 업로드를 위한 시간 제한 자격 증명입니다. 서버에서 POST /upload/signed-url을 사용해 생성한 후 브라우저나 모바일 앱에 전달합니다. 클라이언트는 API 키를 노출하는 대신 Authorization: Signed <token>으로 인증합니다. 각 토큰은 사용량을 추적하고 자동으로 만료됩니다. 자세한 내용은 서명된 토큰 문서를 참조하세요.

IPFS에서 제공되는 이미지를 최적화할 수 있나요?

네. GET /image/:cid에 w, h, format, quality 등의 쿼리 매개변수를 사용하여 이미지를 실시간으로 리사이즈, 변환, 압축할 수 있습니다. 응답은 콘텐츠 주소 지정 CID에 기반하여 캐시됩니다. 이 기능은 모든 플랜에서 사용할 수 있습니다. 이미지 최적화를 참조하세요.

파일에 메타데이터를 첨부할 수 있나요?

네. POST /upload/new로 업로드하거나 POST /pin으로 피닝할 때 최대 10개의 키-값 쌍이 포함된 metadata 객체를 포함하세요. 메타데이터는 파일 목록과 파일 상세 엔드포인트에서 반환됩니다. 파일 및 피닝 문서를 참조하세요.

요금 및 플랜

무료 플랜이 있나요?

네. Dharma 플랜은 영구 무료입니다 — 1 GB 저장 공간, 무제한 API 요청, 신용카드 불필요합니다.

대역폭 요금이 있나요?

모든 플랜의 API 요청에 대역폭 요금은 없습니다. 전용 게이트웨이 대역폭(Nirvana 플랜)은 월 50 GB가 포함됩니다. 한도에 도달하면 다음 달까지 게이트웨이 요청이 차단됩니다.

저장 공간이 초기화되나요?

저장 공간은 초기화되지 않습니다. 플랜에는 총 저장 공간 할당량(1 GB / 10 GB / 100 GB)이 포함됩니다. 공간을 확보하려면 더 이상 필요하지 않은 파일을 삭제하세요. 플랜을 업그레이드하면 총 할당량이 증가합니다.

언제든 취소할 수 있나요?

네. 결제 포털에서 구독을 취소할 수 있습니다 — 약정이 없습니다. 계정은 무료 플랜으로 되돌아가며, 기존 피닝된 파일은 계속 접근할 수 있습니다.

다운그레이드하면 파일은 어떻게 되나요?

파일은 IPFS에 피닝된 상태로 유지되지만, 현재 사용량이 새 플랜의 저장 공간 한도를 초과하는 경우 추가 업로드가 불가합니다. 한도 이하로 돌아가려면 파일을 삭제하세요.

보안

데이터가 암호화되나요?

모든 데이터는 TLS/HTTPS를 통해 전송 중에 암호화됩니다. 인증에는 JWT 토큰(Cognito)과 안전하게 저장된 API 키를 사용합니다. IPFS의 파일 콘텐츠는 저장 시 암호화되지 않습니다 — IPFS는 설계상 공개 네트워크입니다.

서버 측 코드에서 API 키를 사용해도 안전한가요?

네. API 키는 서버 측 사용을 위해 설계되었습니다. 클라이언트 측 코드에서는 절대 노출하지 마세요. 클라이언트 측 파일 접근에는 읽기 전용 게이트웨이 토큰(gwt_)을 사용하세요.

지원

도움을 받으려면 어떻게 하나요?

info@ipfs.ninja로 이메일을 보내거나 API 레퍼런스 문서를 확인하세요.

SLA가 있나요?

높은 가용성을 위해 노력하고 있지만, 현재 공식 SLA는 제공하지 않습니다. 서비스는 "있는 그대로" 제공됩니다.