CAR Import (DAG Import)

Nhập toàn bộ IPFS DAG trong một yêu cầu duy nhất bằng cách sử dụng tệp CAR (Content Addressable aRchive). CID của bạn được bảo toàn chính xác — không chia lại hoặc băm lại.

Tệp CAR là gì?

Tệp CAR đóng gói toàn bộ cây thư mục IPFS hoặc DAG thành một kho lưu trữ di động duy nhất. Mỗi khối được lưu trữ với CID gốc của nó, vì vậy dịch vụ nhập mọi thứ nguyên trạng. Điều này có nghĩa là:

• Bảo toàn CID — tính toán CID cục bộ, xác minh dịch vụ trả về chính xác cùng một CID
• Tải lên hàng loạt — tải lên hàng trăm tệp trong một yêu cầu thay vì từng tệp một
• Di chuyển nhà cung cấp — xuất DAG từ nhà cung cấp khác, nhập vào IPFS Ninja với CID giống hệt
• DAG tùy chỉnh — tải lên bất kỳ cấu trúc dữ liệu IPLD nào trực tiếp

REST API

POST /upload/new

Cùng endpoint với tải lên thông thường — thêm car: true để báo hiệu nhập CAR.

Nội dung yêu cầu

Tham số	Kiểu	Bắt buộc	Mô tả
content	string	Có	Tệp CAR được mã hóa Base64
car	boolean	Có	Đặt thành true để bật nhập CAR
description	string	Không	Mô tả ngắn về nội dung nhập
folderId	string	Không	ID thư mục để tổ chức nội dung đã nhập
metadata	object	Không	Các cặp khóa-giá trị tùy chỉnh (cùng quy tắc với tải lên thông thường)

Ví dụ: Nhập tệp CAR bằng curl

Bước 1: Tạo tệp CAR từ thư mục cục bộ bằng ipfs-car:

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

Bước 2: Tải lên tệp CAR:

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\"
  }"

Ví dụ: Nhập tệp CAR bằng 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);

Ví dụ: Nhập tệp CAR bằng 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"])

Phản hồi 200 OK

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

S3-tương thích API

Sử dụng tiêu đề x-amz-meta-import: car trong yêu cầu PutObject để nhập tệp CAR qua S3 API.

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" }   // ← kích hoạt nhập CAR
}));

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

MCP Server

Công cụ ipfs_import_car có sẵn trong MCP Server (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...

Tạo tệp CAR

Từ thư mục (khuyến nghị)

Sử dụng công cụ CLI ipfs-car:

# Cài đặt
npm install -g ipfs-car

# Đóng gói thư mục thành tệp CAR
ipfs-car pack ./my-directory -o my-archive.car

# Kiểm tra CID gốc trước khi tải lên
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Từ một nút IPFS đang chạy

Xuất bất kỳ CID nào dưới dạng tệp CAR bằng Kubo CLI:

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

Lập trình bằng JavaScript

Sử dụng thư viện @ipld/car:

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

// Tạo các khối
const block1 = new TextEncoder().encode("Hello, IPFS!");
const hash1 = await sha256.digest(block1);
const cid1 = CID.create(1, raw.code, hash1);

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

// Thu thập đầu ra
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

Xác minh tính toàn vẹn CID

Lợi ích chính của nhập CAR là bảo toàn CID. Bạn có thể xác minh CID gốc khớp nhau trước và sau khi tải lên:

# 1. Đóng gói thư mục và ghi lại CID gốc
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. Tải lên 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"
# ✓ CID khớp nhau — nội dung được nhập chính xác như đã tạo cục bộ

Di chuyển từ nhà cung cấp khác

Từ Pinata

# Xuất từ Pinata qua cổng IPFS
ipfs dag export QmYourCID > export.car

# Nhập vào 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}"

Từ Filebase

# Filebase hỗ trợ xuất CAR qua S3 API của họ
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# Nhập vào 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}"

Giới hạn

Giới hạn	Giá trị
Kích thước tệp CAR tối đa	100 MB
Gốc đơn tối đa	Phải có ít nhất một CID gốc
Định dạng CAR	CARv1 (được hỗ trợ phổ biến)
Khả dụng	Tất cả các gói (Dharma, Bodhi, Nirvana)

Giới hạn lưu trữ và số lượng tệp từ gói của bạn được áp dụng. DAG đã nhập được tính là một mục tệp, và kích thước tệp CAR được trừ từ hạn mức lưu trữ của bạn.

Khắc phục sự cố

"invalid CAR file: too small"

Nội dung tải lên nhỏ hơn 40 byte, quá nhỏ để là tệp CAR hợp lệ. Đảm bảo bạn đang gửi toàn bộ nội dung CAR được mã hóa base64.

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

Tệp CAR đã giải mã vượt quá 100 MB. Chia nội dung của bạn thành nhiều tệp CAR nhỏ hơn bằng gói carbites, hoặc tải lên từng tệp riêng lẻ.

"dag/import did not return a root CID"

Nút IPFS không thể xử lý tệp CAR. Xác minh tệp là kho lưu trữ CARv1 hợp lệ:

ipfs-car roots my-archive.car

Nếu lệnh này thất bại, tệp CAR bị lỗi. Tạo lại bằng ipfs-car pack hoặc ipfs dag export.

"not enough storage"

Đã đạt giới hạn lưu trữ của gói. Xóa các tệp không sử dụng hoặc nâng cấp gói của bạn tại ipfs.ninja/pricing.