S3 兼容性

使用 AWS SDK 在 IPFS Ninja 上上传、下载和管理文件，代码与 Amazon S3 完全相同。

Endpoint

https://s3.ipfs.ninja

凭证

S3 API 使用您的 IPFS Ninja API key 进行身份验证。您的 API key 同时充当 access key 和 secret key。

如何获取凭证

前往 Dashboard > API Keys
点击 Create API key 并设置名称（例如 "S3 access"）
立即复制完整的 key — 它只会显示一次，之后无法找回

您的 key 格式如下：

bws_628bba35e9e0079d9ff9c392b1b55a7b
├──────────┘└──────────────────────────┘
 prefix (12 chars)    rest of key

映射到 AWS 凭证

AWS 参数	值	示例
`accessKeyId`	API key 的前 12 个字符	`bws_628bba35`
`secretAccessKey`	完整的 API key（全部 36 个字符）	`bws_628bba35e9e0079d9ff9c392b1b55a7b`
`region`	始终为 `us-east-1`	`us-east-1`

WARNING

完整的 API key 只在创建时显示一次。如果丢失，请删除该 key 并从 API Keys 页面创建新的。

快速开始

javascript

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

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

// Upload a file
const put = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "hello.json",
  Body: JSON.stringify({ hello: "IPFS" }),
  ContentType: "application/json"
}));

console.log("CID:", put.Metadata?.cid);
// CID: QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy

Bucket = 文件夹

S3 bucket 对应您的 IPFS Ninja 文件夹。当您向 bucket 上传文件时，文件会存储在对应的文件夹中。当您列出 bucket 中的对象时，您看到的是该文件夹中的文件。

S3 操作	IPFS Ninja 等效操作
`CreateBucket`	创建新文件夹
`ListBuckets`	列出您的文件夹
`DeleteBucket`	删除文件夹及其中所有文件
`PutObject` 到 bucket	上传文件到文件夹
`ListObjectsV2` 在 bucket 上	列出文件夹中的文件

javascript

import { ListBucketsCommand, CreateBucketCommand, PutObjectCommand } from "@aws-sdk/client-s3";

// Create a bucket (= create a folder)
await s3.send(new CreateBucketCommand({ Bucket: "nft-metadata" }));

// Upload a file into the folder
await s3.send(new PutObjectCommand({
  Bucket: "nft-metadata",      // ← folder name
  Key: "token-42.json",        // ← filename within the folder
  Body: JSON.stringify({ name: "My NFT #42" })
}));

// List buckets (= list your folders)
const { Buckets } = await s3.send(new ListBucketsCommand({}));
console.log(Buckets);
// [{ Name: "nft-metadata", CreationDate: "2026-04-13T..." }]

TIP

通过 S3 API 创建的文件夹与您在 Dashboard 中看到的文件夹完全相同。您可以通过 S3 API、REST API 或 Web 界面来组织文件 — 它们共享同一个文件夹系统。

INFO

与 Amazon S3 不同，IPFS Ninja 的文件夹默认是扁平的。要创建嵌套结构，请使用 REST API 的文件夹 endpoint 配合 parentFolderId。在 S3 API 中，使用 key 前缀（例如 images/photo.png）在文件夹内进行组织。

支持的操作

PutObject

将文件上传到 IPFS。文件会被固定、进行安全扫描，CID 通过 ETag 和 x-amz-meta-cid header 返回。

javascript

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

const result = await s3.send(new PutObjectCommand({
  Bucket: "my-project",
  Key: "photo.png",
  Body: fs.readFileSync("photo.png"),
  ContentType: "image/png"
}));

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

bash

# curl equivalent
curl -X PUT "https://s3.ipfs.ninja/my-project/photo.png" \
  --data-binary @photo.png \
  -H "Content-Type: image/png" \
  --aws-sigv4 "aws:amz:us-east-1:s3" \
  --user "bws_628bba35:bws_628bba35e9e0079d9ff9c392b1b55a7b"

GetObject

通过 key（文件名）或 CID 下载文件。

javascript

import { GetObjectCommand } from "@aws-sdk/client-s3";

const result = await s3.send(new GetObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

const body = await result.Body.transformToByteArray();
console.log("Size:", body.length);
console.log("CID:", result.Metadata?.cid);

HeadObject

获取文件元数据而不下载内容。

javascript

import { HeadObjectCommand } from "@aws-sdk/client-s3";

const head = await s3.send(new HeadObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

console.log("Size:", head.ContentLength);
console.log("Type:", head.ContentType);
console.log("CID:", head.Metadata?.cid);

DeleteObject

从 IPFS 取消固定文件并从您的帐户中删除。

javascript

import { DeleteObjectCommand } from "@aws-sdk/client-s3";

await s3.send(new DeleteObjectCommand({
  Bucket: "my-project",
  Key: "photo.png"
}));

ListObjectsV2

列出 bucket 中的文件，支持可选的前缀过滤和分页。

javascript

import { ListObjectsV2Command } from "@aws-sdk/client-s3";

const list = await s3.send(new ListObjectsV2Command({
  Bucket: "my-project",
  Prefix: "images/",
  MaxKeys: 100
}));

for (const obj of list.Contents ?? []) {
  console.log(obj.Key, obj.Size, obj.ETag); // ETag = CID
}

Multipart Upload

使用 multipart upload 上传大文件（最大 5 GB）。AWS SDK 会自动处理：

javascript

import { Upload } from "@aws-sdk/lib-storage";
import fs from "fs";

const upload = new Upload({
  client: s3,
  params: {
    Bucket: "my-project",
    Key: "large-dataset.tar.gz",
    Body: fs.createReadStream("large-dataset.tar.gz"),
    ContentType: "application/gzip"
  },
  partSize: 10 * 1024 * 1024, // 10 MB per part
});

upload.on("httpUploadProgress", (progress) => {
  console.log(`Uploaded ${progress.loaded} of ${progress.total} bytes`);
});

const result = await upload.done();
console.log("CID:", result.ETag);

或者手动控制分片：

javascript

import {
  CreateMultipartUploadCommand,
  UploadPartCommand,
  CompleteMultipartUploadCommand
} from "@aws-sdk/client-s3";

// 1. Start
const { UploadId } = await s3.send(new CreateMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin"
}));

// 2. Upload parts
const part1 = await s3.send(new UploadPartCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  PartNumber: 1,
  Body: chunk1
}));

// 3. Complete
const result = await s3.send(new CompleteMultipartUploadCommand({
  Bucket: "my-project",
  Key: "big-file.bin",
  UploadId,
  MultipartUpload: {
    Parts: [{ PartNumber: 1, ETag: part1.ETag }]
  }
}));

Python 示例

python

import boto3

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.ipfs.ninja",
    aws_access_key_id="bws_628bba35",
    aws_secret_access_key="bws_628bba35e9e0079d9ff9c392b1b55a7b",
    region_name="us-east-1"
)

# Upload
s3.put_object(
    Bucket="my-project",
    Key="data.json",
    Body=b'{"hello": "IPFS"}',
    ContentType="application/json"
)

# List files
response = s3.list_objects_v2(Bucket="my-project")
for obj in response.get("Contents", []):
    print(obj["Key"], obj["Size"])

# Download
result = s3.get_object(Bucket="my-project", Key="data.json")
print(result["Body"].read())

Go 示例

package main

import (
    "context"
    "fmt"
    "strings"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/credentials"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    client := s3.New(s3.Options{
        BaseEndpoint: aws.String("https://s3.ipfs.ninja"),
        Region:       "us-east-1",
        Credentials:  credentials.NewStaticCredentialsProvider("bws_628bba35", "bws_628bba35e9e0...", ""),
        UsePathStyle: true,
    })

    _, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
        Bucket:      aws.String("my-project"),
        Key:         aws.String("hello.txt"),
        Body:        strings.NewReader("Hello, IPFS!"),
        ContentType: aws.String("text/plain"),
    })
    if err != nil {
        panic(err)
    }
    fmt.Println("Uploaded!")
}

与 Amazon S3 的区别

特性	Amazon S3	IPFS Ninja S3
存储模型	可变对象	内容寻址（不可变 CID）
覆盖行为	原地替换对象	创建新 CID，旧 CID 仍可访问
版本控制	支持	不支持（使用 CID 进行版本管理）
服务端加密	支持	不支持（内容在 IPFS 上）
生命周期策略	支持	不支持
Bucket 策略 / ACL	支持	使用 gateway 访问模式
预签名 URL	支持	使用签名上传 token
最大对象大小	5 TB	5 GB（multipart），100 MB（单次 PUT）
区域	多区域	仅 `us-east-1`
`ETag` 值	MD5 hash	IPFS CID
额外 header	标准 S3	`x-amz-meta-cid`（IPFS CID）

从 Amazon S3 迁移

替换您的 S3 客户端配置：

diff

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

您现有的 PutObject、GetObject、ListObjectsV2 和 DeleteObject 调用无需修改即可使用。

从 Filebase 迁移

替换 endpoint URL：

diff

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

S3 兼容性 ​

Endpoint ​

凭证 ​

如何获取凭证 ​

映射到 AWS 凭证 ​

快速开始 ​

Bucket = 文件夹 ​

支持的操作 ​

PutObject ​

GetObject ​

HeadObject ​

DeleteObject ​

ListObjectsV2 ​

Multipart Upload ​

Python 示例 ​

Go 示例 ​

与 Amazon S3 的区别 ​

从 Amazon S3 迁移 ​

从 Filebase 迁移 ​

S3 兼容性

Endpoint

凭证

如何获取凭证

映射到 AWS 凭证

快速开始

Bucket = 文件夹

支持的操作

PutObject

GetObject

HeadObject

DeleteObject

ListObjectsV2

Multipart Upload

Python 示例

Go 示例

与 Amazon S3 的区别

从 Amazon S3 迁移

从 Filebase 迁移