Tương thích S3

Sử dụng AWS SDK để tải lên, tải xuống và quản lý tệp trên IPFS Ninja với cùng mã nguồn bạn dùng cho Amazon S3.

Endpoint

https://s3.ipfs.ninja

Thông tin xác thực

S3 API sử dụng API key IPFS Ninja của bạn để xác thực. API key của bạn đóng vai trò vừa là access key vừa là secret key.

Cách lấy thông tin xác thực

1. Truy cập Dashboard > API Keys
2. Nhấn Create API key và đặt tên (ví dụ: "S3 access")
3. Sao chép toàn bộ key ngay lập tức — key chỉ hiển thị một lần và không thể khôi phục sau đó

Key của bạn có dạng như sau:

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

Ánh xạ sang thông tin xác thực AWS

Tham số AWS	Giá trị	Ví dụ
accessKeyId	12 ký tự đầu tiên của API key	bws_628bba35
secretAccessKey	API key đầy đủ (tất cả 36 ký tự)	bws_628bba35e9e0079d9ff9c392b1b55a7b
region	Luôn là us-east-1	us-east-1

WARNING

API key đầy đủ chỉ hiển thị một lần khi bạn tạo. Nếu bạn mất nó, hãy xóa key và tạo key mới từ trang API Keys.

Bắt đầu nhanh

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 = Thư mục

S3 bucket tương ứng với thư mục IPFS Ninja của bạn. Khi bạn tải tệp lên một bucket, nó được lưu trong thư mục tương ứng. Khi bạn liệt kê đối tượng trong một bucket, bạn thấy các tệp trong thư mục đó.

Thao tác S3	Tương đương IPFS Ninja
CreateBucket	Tạo thư mục mới
ListBuckets	Liệt kê thư mục của bạn
DeleteBucket	Xóa thư mục và tất cả tệp bên trong
PutObject vào bucket	Tải tệp lên thư mục
ListObjectsV2 trên bucket	Liệt kê tệp trong thư mục

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

Các thư mục tạo qua S3 API giống hệt các thư mục hiển thị trên Dashboard của bạn. Bạn có thể sắp xếp tệp từ S3 API, REST API hoặc giao diện web — tất cả đều dùng chung hệ thống thư mục.

INFO

Khác với Amazon S3, thư mục IPFS Ninja mặc định là phẳng. Để tạo cấu trúc lồng nhau, sử dụng endpoint thư mục của REST API với parentFolderId. Từ S3 API, sử dụng tiền tố key (ví dụ: images/photo.png) để tổ chức bên trong thư mục.

Các thao tác được hỗ trợ

PutObject

Tải tệp lên IPFS. Tệp được ghim, quét an toàn, và CID được trả về trong header ETag và x-amz-meta-cid.

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

Tải xuống tệp theo key (tên tệp) hoặc 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

Lấy metadata tệp mà không cần tải nội dung.

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

Gỡ ghim tệp khỏi IPFS và xóa khỏi tài khoản của bạn.

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

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

ListObjectsV2

Liệt kê tệp trong bucket với tùy chọn lọc theo tiền tố và phân trang.

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

Tải lên các tệp lớn (tối đa 5 GB) bằng multipart upload. AWS SDK xử lý tự động:

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

Hoặc kiểm soát các phần thủ công:

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

Ví dụ 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())

Ví dụ 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!")
}

Khác biệt so với Amazon S3

Tính năng	Amazon S3	IPFS Ninja S3
Mô hình lưu trữ	Đối tượng có thể thay đổi	Định địa chỉ theo nội dung (CID bất biến)
Hành vi ghi đè	Thay thế đối tượng tại chỗ	Tạo CID mới, CID cũ vẫn truy cập được
Phiên bản	Hỗ trợ	Không hỗ trợ (dùng CID để quản lý phiên bản)
Mã hóa phía server	Hỗ trợ	Không hỗ trợ (nội dung nằm trên IPFS)
Chính sách vòng đời	Hỗ trợ	Không hỗ trợ
Chính sách bucket / ACL	Hỗ trợ	Sử dụng chế độ truy cập gateway
URL ký trước	Hỗ trợ	Sử dụng token tải lên có chữ ký
Kích thước đối tượng tối đa	5 TB	5 GB (multipart), 100 MB (PUT đơn)
Vùng	Đa vùng	Chỉ us-east-1
Giá trị ETag	MD5 hash	IPFS CID
Header bổ sung	S3 tiêu chuẩn	x-amz-meta-cid (IPFS CID)

Di chuyển từ Amazon S3

Thay thế cấu hình S3 client của bạn:

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

Các lệnh PutObject, GetObject, ListObjectsV2 và DeleteObject hiện có của bạn hoạt động không thay đổi.

Di chuyển từ Filebase

Thay thế URL endpoint:

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