피닝

파일이 IPFS 네트워크에서 어떻게 지속되며 피닝이 왜 중요한지 알아보세요.

가비지 컬렉션 문제

IPFS 노드는 저장 공간이 제한되어 있습니다. 디스크 공간을 관리하기 위해 주기적으로 가비지 컬렉션 — 중요하다고 명시적으로 표시되지 않은 캐시 데이터를 제거하는 프로세스 — 을 실행합니다. 개입 없이는 업로드한 파일이 몇 시간 내에 네트워크에서 제거될 수 있습니다.

피닝은 IPFS 노드에게 "이 파일을 영구적으로 보관하세요 — 가비지 컬렉션하지 마세요"라고 알립니다. 피닝된 파일은 노드의 저장소에 무기한으로 남아 네트워크에서 계속 사용할 수 있도록 보장합니다.

로컬 피닝 vs. 원격 피닝

로컬 피닝은 자체 IPFS 노드를 실행하고 파일을 피닝하는 것을 의미합니다. 가동 시간, 저장 공간, 네트워크 연결은 사용자의 책임입니다. 노드가 오프라인이 되면 파일을 사용할 수 없게 됩니다.

원격 피닝 (IPFS.NINJA가 제공하는 것)은 항상 온라인인 인프라에서 관리형 서비스가 파일을 피닝하는 것을 의미합니다. 자체 노드를 실행하지 않고도 피닝의 영속성을 얻을 수 있습니다.

TIP

IPFS.NINJA를 통해 업로드된 모든 파일은 자동으로 IPFS 클러스터에 피닝됩니다. 추가 단계가 필요 없습니다 — 파일은 업로드 순간부터 영구적입니다.

피닝을 해제하면 어떻게 되나요

IPFS.NINJA 계정에서 파일을 삭제하면, 노드에서 피닝을 해제합니다. 하지만 다음 경우에는 파일이 여전히 접근 가능할 수 있습니다:

• 다른 IPFS 노드가 동일한 CID를 캐시하거나 피닝한 경우
• IPFS 게이트웨이 캐시에 파일이 있는 경우
• 다른 사용자가 동일한 콘텐츠를 업로드한 경우 (동일한 CID = 동일한 파일)

시간이 지나면서 어떤 노드도 CID를 피닝하지 않으면, 파일은 네트워크에서 완전히 가비지 컬렉션됩니다.

피닝 모범 사례

• 일찍 피닝하세요 — 스마트 컨트랙트, NFT 메타데이터, 외부 시스템에서 CID를 참조하기 전에 콘텐츠를 업로드하고 피닝하세요.
• 캐시에 의존하지 마세요 — IPFS 게이트웨이 캐시는 일시적입니다. 피닝된 콘텐츠만 영속성이 보장됩니다.
• 계정을 활성 상태로 유지하세요 — IPFS.NINJA 계정이 활성 상태인 한, 무료 플랜에서도 파일은 피닝된 상태를 유지합니다.

기존 콘텐츠 피닝

파일을 피닝하기 위해 IPFS.NINJA를 통해 업로드할 필요는 없습니다. 콘텐츠가 이미 IPFS 네트워크에 존재하는 경우 — 다른 사람이 업로드했거나 다른 서비스를 통해 업로드한 경우 — CID를 제공하여 계정에 피닝할 수 있습니다.

기존 CID를 피닝하면, 클러스터는:

1. IPFS 네트워크에서 콘텐츠를 보유한 노드를 검색합니다
2. 가장 가까운 가용 노드에서 콘텐츠를 다운로드합니다
3. 인프라에 로컬로 피닝합니다
4. 계정과 게이트웨이를 통해 접근 가능하게 합니다

다음과 같은 경우에 유용합니다:

• NFT 자산 보존 — 기존 컬렉션의 메타데이터와 이미지를 피닝
• 콘텐츠 백업 — 원래 피닝한 측이 오프라인이 되어도 중요한 CID가 사용 가능하도록 보장
• 다른 서비스에서 마이그레이션 — 파일을 다시 업로드하지 않고 기존 CID를 피닝

엔드포인트 상세 내용은 피닝 API 문서를 참조하세요.