S3 相容性

使用 AWS SDK 在 IPFS Ninja 上傳、下載和管理檔案，程式碼與 Amazon S3 完全相同。

Endpoint

https://s3.ipfs.ninja

憑證

S3 API 使用您的 IPFS Ninja API key 進行身份驗證。您的 API key 同時充當 access key 和 secret key。

如何取得憑證

1. 前往 Dashboard > API Keys
2. 點選 Create API key 並設定名稱（例如 "S3 access"）
3. 立即複製完整的 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 頁面 建立新的。

快速開始

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 上	列出資料夾中的檔案

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 或網頁介面來組織檔案 — 它們共用同一個資料夾系統。

INFO

與 Amazon S3 不同，IPFS Ninja 的資料夾預設是扁平的。若要建立巢狀結構，請使用 REST API 的資料夾 endpoint 搭配 parentFolderId。在 S3 API 中，使用 key 前綴（例如 images/photo.png）在資料夾內進行組織。

支援的操作

PutObject

將檔案上傳到 IPFS。檔案會被釘選、進行安全掃描，CID 透過 ETag 和 x-amz-meta-cid header 回傳。

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);

# 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 下載檔案。

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

取得檔案中繼資料而不下載內容。

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 取消釘選檔案並從您的帳戶中刪除。

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

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

ListObjectsV2

列出 bucket 中的檔案，支援可選的前綴過濾和分頁。

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 會自動處理：

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);

或者手動控制分片：

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 範例

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 用戶端配置：

 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：

 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
 });