CAR 가져오기 (DAG 가져오기)

CAR(Content Addressable aRchive) 파일을 사용하여 전체 IPFS DAG를 단일 요청으로 가져옵니다. CID는 정확히 보존됩니다 — 재청킹이나 재해싱이 없습니다.

CAR 파일이란 무엇인가요?

CAR 파일은 전체 IPFS 디렉터리 트리 또는 DAG를 하나의 이동 가능한 아카이브로 패키징합니다. 각 블록은 원래의 CID와 함께 저장되므로, 서비스는 모든 것을 있는 그대로 가져옵니다. 이는 다음을 의미합니다:

CID 보존 — 로컬에서 CID를 계산하고, 서비스가 정확히 동일한 CID를 반환하는지 검증
일괄 업로드 — 하나씩이 아니라 한 번의 요청으로 수백 개의 파일 업로드
제공업체 마이그레이션 — 다른 제공업체에서 DAG를 내보내고, 동일한 CID로 IPFS Ninja에 가져오기
사용자 정의 DAG — 모든 IPLD 데이터 구조를 직접 업로드

대시보드를 통한 업로드

/upload의 두 가지 드래그 앤 드롭 경로가 동일한 가져오기 플로우로 연결됩니다 — 코드 불필요:

.car 파일 드롭. 업로드 영역이 확장자를 자동으로 감지하고 "CAR archive detected" 배너를 표시하며, 제출 버튼이 "Import <filename> as CAR"로 바뀝니다. 아카이브 자체의 루트 CID가 보존됩니다.
폴더 드롭. 대시보드가 브라우저에서 폴더를 UnixFS DAG로 패키징하고(IPIP-0499에 따른 최신 1 MiB 청커를 사용하는 ipfs-unixfs-importer 사용) 결과 CAR를 동일한 경로로 업로드합니다. 루트 CID는 /ipfs/{cid}/{subpath}에서 해석되는 bafybei… 디렉터리입니다.

몇 MB를 넘는 모든 것은 presigned-PUT 플로우를 사용합니다 — 파일 크기 상한은 CAR당 5 GB입니다.

REST API

POST /upload/new

일반 업로드와 동일한 엔드포인트입니다 — CAR 가져오기를 알리려면 car: true를 추가하세요.

요청 본문

매개변수	유형	필수	설명
`content`	string	예	base64 인코딩된 CAR 파일
`car`	boolean	예	CAR 가져오기를 활성화하려면 `true`로 설정
`description`	string	아니요	가져오기에 대한 간단한 설명
`folderId`	string	아니요	가져온 콘텐츠를 정리할 폴더 ID
`metadata`	object	아니요	사용자 정의 키-값 쌍 (일반 업로드와 동일한 규칙)

예시: curl로 CAR 파일 가져오기

1단계: ipfs-car를 사용하여 로컬 디렉터리에서 CAR 파일 생성:

bash

npx ipfs-car pack ./my-directory -o my-archive.car

2단계: CAR 파일 업로드:

bash

curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d "{
    \"content\": \"$(base64 -w0 my-archive.car)\",
    \"car\": true,
    \"description\": \"My directory import\"
  }"

예시: JavaScript로 CAR 파일 가져오기

javascript

import fs from "fs";

const carBuffer = fs.readFileSync("my-archive.car");
const base64Content = carBuffer.toString("base64");

const response = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "X-Api-Key": "bws_your_api_key_here",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    content: base64Content,
    car: true,
    description: "My directory import"
  })
});

const result = await response.json();
console.log("Root CID:", result.cid);
console.log("Gateway:", result.uris.url);

예시: Python으로 CAR 파일 가져오기

python

import requests
import base64

with open("my-archive.car", "rb") as f:
    car_content = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.ipfs.ninja/upload/new",
    headers={
        "X-Api-Key": "bws_your_api_key_here",
        "Content-Type": "application/json"
    },
    json={
        "content": car_content,
        "car": True,
        "description": "My directory import"
    }
)

result = response.json()
print("Root CID:", result["cid"])
print("Gateway:", result["uris"]["url"])

응답 `200 OK`

json

{
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "sizeMB": 4.2,
  "car": true,
  "fileCount": 12,
  "uris": {
    "ipfs": "ipfs://bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "url": "https://ipfs.ninja/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
  }
}

파일 개수 계산 방식

CAR 내부의 각 파일은 개별적으로 플랜의 파일 한도에 포함됩니다. 12개 파일을 포함하는 CAR는 13개 슬롯을 사용합니다(자식 12개 + 루트 CAR 항목 1개). 단일 파일 CAR는 1개 슬롯으로 계산됩니다.

저장 공간은 루트 CAR 항목에 대해 한 번만 청구됩니다 (전체 CAR 파일 크기)
개별 자식 파일은 메타데이터에 루트 CID(carParentCid)를 포함하여 파일 목록에 나타나므로 그룹화할 수 있습니다
CAR 가져오기당 최대 1000개 파일 — 더 큰 DAG는 여러 번의 가져오기로 분할해야 합니다

CAR를 가져오면 플랜의 파일 개수를 초과하는 경우, 요청은 402 오류로 거부되고 콘텐츠는 자동으로 언핀됩니다:

json

{
  "error": "file limit exceeded: this CAR contains 523 files, you have 800/1000. Upgrade your plan."
}

S3 호환 API

S3 API를 통해 CAR 파일을 가져오려면 PutObject 요청에 x-amz-meta-import: car 헤더를 사용하세요.

javascript

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import fs from "fs";

const s3 = new S3Client({
  endpoint: "https://s3.ipfs.ninja",
  credentials: {
    accessKeyId: "bws_628bba35",
    secretAccessKey: "bws_628bba35e9e0079d9ff9c392b1b55a7b"
  },
  region: "us-east-1",
  forcePathStyle: true
});

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "my-archive.car",
  Body: fs.readFileSync("my-archive.car"),
  ContentType: "application/vnd.ipld.car",
  Metadata: { import: "car" }   // ← triggers CAR import
}));

console.log("Root CID:", result.ETag);

MCP 서버

ipfs_import_car 도구는 MCP 서버(v1.3.0 이상)에서 사용할 수 있습니다:

You: Import my-archive.car to IPFS
Claude: [calls ipfs_import_car with base64 content]
     → Root CID: bafybeig... — https://ipfs.ninja/ipfs/bafybeig...

CAR 파일 생성하기

디렉터리에서 (권장)

ipfs-car CLI 도구를 사용하세요:

bash

# Install
npm install -g ipfs-car

# Pack a directory into a CAR file
ipfs-car pack ./my-directory -o my-archive.car

# Check the root CID before uploading
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

실행 중인 IPFS 노드에서

Kubo CLI를 사용하여 모든 CID를 CAR 파일로 내보내세요:

bash

ipfs dag export QmXyz... > my-archive.car

JavaScript로 프로그래밍 방식으로

@ipld/car 라이브러리를 사용하세요:

javascript

import { CarWriter } from "@ipld/car";
import { CID } from "multiformats/cid";
import * as raw from "multiformats/codecs/raw";
import { sha256 } from "multiformats/hashes/sha2";

// Create blocks
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

// Write CAR
const { writer, out } = CarWriter.create([cid1]);
writer.put({ cid: cid1, bytes: block1 });
writer.close();

// Collect output
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

CID 무결성 검증

CAR 가져오기의 핵심 이점은 CID 보존입니다. 업로드 전후로 루트 CID가 일치하는지 확인할 수 있습니다:

bash

# 1. Pack directory and note the root CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Upload to IPFS Ninja
curl -s -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 collection.car)\", \"car\": true}" \
  | jq .cid
# "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
# ✓ CIDs match — content imported exactly as built locally

다른 제공업체에서 마이그레이션

Pinata에서

bash

# Export from Pinata using IPFS gateway
ipfs dag export QmYourCID > export.car

# Import to IPFS Ninja
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

Filebase에서

bash

# Filebase supports CAR export via their S3 API
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Import to IPFS Ninja
curl -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": \"$(base64 -w0 export.car)\", \"car\": true}"

제한 사항

제한	값
최대 CAR 파일 크기	100 MB
최대 단일 루트	최소 하나의 루트 CID 필요
CAR 형식	CARv1 (범용적으로 지원됨)
이용 가능 여부	모든 플랜 (Dharma, Bodhi, Nirvana)

플랜의 저장 공간 및 파일 개수 제한이 적용됩니다. 가져온 DAG는 하나의 파일 항목으로 계산되며, CAR 파일 크기가 저장 공간 할당량에서 차감됩니다.

문제 해결

"invalid CAR file: too small"

업로드된 콘텐츠가 40바이트 미만으로, 유효한 CAR 파일이 되기에는 너무 작습니다. 전체 base64 인코딩된 CAR 콘텐츠를 보내고 있는지 확인하세요.

"File too large. Maximum upload size is 100 MB."

디코딩된 CAR 파일이 100 MB를 초과합니다. carbites 패키지를 사용하여 콘텐츠를 여러 개의 더 작은 CAR 파일로 분할하거나, 파일을 개별적으로 업로드하세요.

"dag/import did not return a root CID"

IPFS 노드가 CAR 파일을 처리할 수 없었습니다. 파일이 유효한 CARv1 아카이브인지 확인하세요:

bash

ipfs-car roots my-archive.car

이 명령이 실패하면 CAR 파일이 손상된 것입니다. ipfs-car pack 또는 ipfs dag export로 다시 생성하세요.

"not enough storage"

플랜의 저장 공간 한도에 도달했습니다. 사용하지 않는 파일을 삭제하거나 ipfs.ninja/pricing에서 플랜을 업그레이드하세요.

CAR 가져오기 (DAG 가져오기) ​

CAR 파일이란 무엇인가요? ​

대시보드를 통한 업로드 ​

REST API ​

요청 본문 ​

예시: curl로 CAR 파일 가져오기 ​

예시: JavaScript로 CAR 파일 가져오기 ​

예시: Python으로 CAR 파일 가져오기 ​

응답 200 OK ​

파일 개수 계산 방식 ​

S3 호환 API ​

MCP 서버 ​

CAR 파일 생성하기 ​

디렉터리에서 (권장) ​

실행 중인 IPFS 노드에서 ​

JavaScript로 프로그래밍 방식으로 ​

CID 무결성 검증 ​

다른 제공업체에서 마이그레이션 ​

Pinata에서 ​

Filebase에서 ​

제한 사항 ​

문제 해결 ​

"invalid CAR file: too small" ​

"File too large. Maximum upload size is 100 MB." ​

"dag/import did not return a root CID" ​

"not enough storage" ​

CAR 가져오기 (DAG 가져오기)

CAR 파일이란 무엇인가요?

대시보드를 통한 업로드

REST API

요청 본문

예시: curl로 CAR 파일 가져오기

예시: JavaScript로 CAR 파일 가져오기

예시: Python으로 CAR 파일 가져오기

응답 `200 OK`

파일 개수 계산 방식

S3 호환 API

MCP 서버

CAR 파일 생성하기

디렉터리에서 (권장)

실행 중인 IPFS 노드에서

JavaScript로 프로그래밍 방식으로

CID 무결성 검증

다른 제공업체에서 마이그레이션

Pinata에서

Filebase에서

제한 사항

문제 해결

"invalid CAR file: too small"

"File too large. Maximum upload size is 100 MB."

"dag/import did not return a root CID"

"not enough storage"