CAR Import (DAG Import)

使用 CAR (Content Addressable aRchive) 文件在单个请求中导入完整的 IPFS DAG。您的 CID 会被精确保留——不会重新分块或重新哈希。

什么是 CAR 文件？

CAR 文件将完整的 IPFS 目录树或 DAG 打包成单个可移植的归档文件。每个区块都以其原始 CID 存储，因此服务会原样导入所有内容。这意味着：

• CID 保留 — 在本地计算 CID，验证服务返回完全相同的 CID
• 批量上传 — 在一个请求中上传数百个文件，而不是逐个上传
• 提供商迁移 — 从其他提供商导出 DAG，以相同的 CID 导入到 IPFS Ninja
• 自定义 DAG — 直接上传任何 IPLD 数据结构

REST API

POST /upload/new

与常规上传使用相同的 endpoint — 添加 car: true 以表示 CAR 导入。

请求体

参数	类型	必填	描述
content	string	是	Base64 编码的 CAR 文件
car	boolean	是	设置为 true 以启用 CAR 导入
description	string	否	导入的简短描述
folderId	string	否	用于组织导入内容的文件夹 ID
metadata	object	否	自定义键值对（与常规上传相同的规则）

示例：使用 curl 导入 CAR 文件

步骤 1： 使用 ipfs-car 从本地目录创建 CAR 文件：

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

步骤 2： 上传 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\"
  }"

示例：使用 JavaScript 导入 CAR 文件

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 文件

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

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

S3 兼容 API

在 PutObject 请求中使用 x-amz-meta-import: car 头来通过 S3 API 导入 CAR 文件。

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" }   // ← 触发 CAR 导入
}));

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

MCP Server

ipfs_import_car 工具可在 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...

创建 CAR 文件

从目录创建（推荐）

使用 ipfs-car CLI 工具：

# 安装
npm install -g ipfs-car

# 将目录打包成 CAR 文件
ipfs-car pack ./my-directory -o my-archive.car

# 上传前检查根 CID
ipfs-car roots my-archive.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

从运行中的 IPFS 节点

使用 Kubo CLI 将任何 CID 导出为 CAR 文件：

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

使用 JavaScript 编程创建

使用 @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";

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

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

// 收集输出
const chunks = [];
for await (const chunk of out) chunks.push(chunk);
const carBuffer = Buffer.concat(chunks);

验证 CID 完整性

CAR 导入的关键优势是 CID 保留。您可以验证根 CID 在上传前后是否匹配：

# 1. 打包目录并记录根 CID
ipfs-car pack ./my-nft-collection -o collection.car
ipfs-car roots collection.car
# bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

# 2. 上传到 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 匹配 — 内容完全按照本地构建的方式导入

从其他提供商迁移

从 Pinata

# 通过 IPFS 网关从 Pinata 导出
ipfs dag export QmYourCID > export.car

# 导入到 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

# Filebase 支持通过其 S3 API 导出 CAR
aws s3 cp s3://your-bucket/your-file.car export.car \
  --endpoint-url https://s3.filebase.com

# 导入到 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 归档：

ipfs-car roots my-archive.car

如果此命令失败，则 CAR 文件格式错误。使用 ipfs-car pack 或 ipfs dag export 重新生成。

"not enough storage"

已达到您计划的存储限制。删除未使用的文件或在 ipfs.ninja/pricing 升级您的计划。