ความเข้ากันได้กับ S3

ใช้ AWS SDK เพื่ออัปโหลด ดาวน์โหลด และจัดการไฟล์บน IPFS Ninja ด้วยโค้ดเดียวกับที่คุณใช้กับ Amazon S3

Endpoint

https://s3.ipfs.ninja

ข้อมูลประจำตัว

S3 API ใช้ API key ของ IPFS Ninja สำหรับการยืนยันตัวตน API key ของคุณทำหน้าที่เป็นทั้ง access key และ secret key

วิธีรับข้อมูลประจำตัว

1. ไปที่ แดชบอร์ด > API Keys
2. คลิก Create API key และตั้งชื่อ (เช่น "S3 access")
3. คัดลอก key ทั้งหมดทันที — จะแสดงเพียงครั้งเดียวและไม่สามารถเรียกดูได้ภายหลัง

key ของคุณมีรูปแบบดังนี้:

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

การแมปกับข้อมูลประจำตัว AWS

พารามิเตอร์ AWS	ค่า	ตัวอย่าง
accessKeyId	12 ตัวอักษรแรกของ API key	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: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Buckets = โฟลเดอร์

S3 bucket แมปกับโฟลเดอร์ของคุณใน IPFS Ninja เมื่อคุณอัปโหลดไฟล์ไปยัง bucket ไฟล์จะถูกเก็บในโฟลเดอร์ที่สอดคล้องกัน เมื่อคุณลิสต์ออบเจกต์ใน bucket คุณจะเห็นไฟล์ในโฟลเดอร์นั้น

S3 Operation	เทียบเท่าใน 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 คือโฟลเดอร์เดียวกับที่แสดงบนแดชบอร์ดของคุณ คุณสามารถจัดระเบียบไฟล์จาก S3 API, REST API หรือเว็บอินเทอร์เฟซ — ทุกช่องทางใช้ระบบโฟลเดอร์เดียวกัน

INFO

ต่างจาก Amazon S3 โฟลเดอร์ของ IPFS Ninja เป็นแบบแบนโดยค่าเริ่มต้น หากต้องการสร้างโครงสร้างซ้อน ให้ใช้ endpoint โฟลเดอร์ของ REST API กับ parentFolderId จาก S3 API ให้ใช้ prefix ของ key (เช่น images/photo.png) เพื่อจัดระเบียบภายในโฟลเดอร์

ชื่อ bucket ไม่ซ้ำกันทั่วโลก

ชื่อ bucket อยู่ในเนมสเปซทั่วโลกร่วมกันของลูกค้าทุกราย ตรงตามความหมายของ AWS S3 นั่นหมายความว่า:

• ผู้ใช้คนแรกที่สร้าง bucket ด้วยชื่อที่กำหนด จอง ชื่อนั้นไว้ทั่วโลก
• การเรียก CreateBucket ในภายหลังด้วยชื่อเดียวกันจากบัญชีใดก็ตามจะส่งคืน BucketAlreadyExists (409)
• หากคุณพยายามสร้าง bucket ของคุณเองซ้ำ คุณจะได้รับ BucketAlreadyOwnedByYou (409)
• ชื่อโฟลเดอร์ของคุณในแดชบอร์ดเป็นแบบต่อบัญชีและยังคงเป็นอะไรก็ได้ — เฉพาะชื่อbucketที่มองเห็นได้ทาง S3 เท่านั้นที่ผ่านเนมสเปซทั่วโลก

หากชื่อที่คุณต้องการถูกใช้ไปแล้ว ให้เลือกชื่อที่มีขอบเขตต่างออกไป (myapp-photos-2026, acme-nft-metadata) — แนวทางเดียวกับที่คุณจะใช้บน Amazon S3

การดำเนินการที่รองรับ

PutObject

อัปโหลดไฟล์ไปยัง IPFS ไฟล์จะถูกปักหมุด สแกนความปลอดภัย และ CID จะถูกส่งกลับใน header ETag และ x-amz-meta-cid

หากต้องการนำเข้าไฟล์ CARแทนไฟล์ปกติ ให้เพิ่ม header metadata x-amz-meta-import: car ดู การนำเข้า CAR สำหรับรายละเอียด

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 พร้อมการกรองด้วย prefix และการแบ่งหน้าที่เป็นตัวเลือก

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)

อัปโหลดไฟล์ขนาดใหญ่ (สูงสุด 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!")
}

กำหนดค่า CORS (การเข้าถึง SDK บนเบราว์เซอร์)

หากคุณเรียก S3 API โดยตรงจาก JavaScript บนเบราว์เซอร์ (SPA, แอปกระเป๋าเงิน, เครื่องมือแดชบอร์ด) คุณต้องกำหนดค่า CORS บน bucket ก่อน มิฉะนั้นเบราว์เซอร์จะบล็อกการทำ preflight และการอัปโหลดของคุณจะล้มเหลวด้วย No 'Access-Control-Allow-Origin' header is present

รูปแบบเดียวกับ AWS S3 — subresource PutBucketCors / GetBucketCors / DeleteBucketCors:

PutBucketCors

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

await s3.send(new PutBucketCorsCommand({
  Bucket: "my-bucket",
  CORSConfiguration: {
    CORSRules: [{
      AllowedOrigins: ["http://localhost:3000", "https://myapp.com"],
      AllowedMethods: ["GET", "HEAD", "PUT", "POST", "DELETE"],
      AllowedHeaders: ["*"],
      ExposeHeaders: ["ETag", "x-amz-meta-cid", "x-amz-request-id"],
      MaxAgeSeconds: 3600,
    }],
  },
}));

GetBucketCors

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

const { CORSRules } = await s3.send(new GetBucketCorsCommand({ Bucket: "my-bucket" }));
console.log(CORSRules);

DeleteBucketCors

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

await s3.send(new DeleteBucketCorsCommand({ Bucket: "my-bucket" }));

ขีดจำกัดและค่าเริ่มต้น

• สูงสุด 5 กฎต่อ bucket (สเปกอนุญาต 100 แต่เราจำกัดไว้ที่ 5 เพื่อให้การตอบกลับ preflight ของเบราว์เซอร์กระชับ)
• ขนาดการตั้งค่ารวมจำกัดที่ 64 KB เมื่อ serialise แล้ว
• หากไม่มีการตั้งค่า CORS การ preflight ของเบราว์เซอร์จะถูกปฏิเสธ — ตรงกับท่าทีค่าเริ่มต้นของ AWS S3 กำหนดกฎที่ชัดเจนสำหรับ origin ที่คุณให้บริการจริง

หมายเหตุด้านความปลอดภัยในโลกจริง

CORS เป็นเลเยอร์อำนวยความสะดวกฝั่งเบราว์เซอร์ ไม่ใช่ ขอบเขตความปลอดภัย ทุกการเรียก S3 API ยังคงต้องใช้ลายเซ็น SigV4 ที่ถูกต้องซึ่งคำนวณจาก API key ของคุณ — การตั้งค่า CORS ที่อนุญาตกว้างไม่ได้ทำให้ใครก็ตามใช้ bucket ของคุณได้โดยไม่มีข้อมูลรับรองนั้น สิ่งที่ CORS ป้องกันได้คือ: origin ที่ไม่ได้ตั้งใจ (เช่น สำเนาเก่าของแอปคุณบน dev.myapp.com) ส่งคำขอที่ลงนามแล้วจากบริบทเบราว์เซอร์

ทางเลือกในแดชบอร์ด

หน้า Files มีรายการ S3 CORS ในเมนูการกระทำของแต่ละโฟลเดอร์ ที่จัดเก็บส่วนกลางเดียวกัน หากคุณไม่ต้องการเขียนโค้ด PutBucketCors ให้ตั้งค่าที่นั่น

ความแตกต่างจาก Amazon S3

ฟีเจอร์	Amazon S3	IPFS Ninja S3
โมเดลการจัดเก็บ	ออบเจกต์ที่เปลี่ยนแปลงได้	ระบุตำแหน่งด้วยเนื้อหา (CID ที่เปลี่ยนแปลงไม่ได้)
พฤติกรรมการเขียนทับ	แทนที่ออบเจกต์ในที่เดิม	สร้าง CID ใหม่ CID เก่ายังเข้าถึงได้
การกำหนดเวอร์ชัน	รองรับ	ไม่รองรับ (ใช้ CID สำหรับการกำหนดเวอร์ชัน)
การเข้ารหัสฝั่งเซิร์ฟเวอร์	รองรับ	ไม่รองรับ (เนื้อหาอยู่บน IPFS)
นโยบายวงจรชีวิต	รองรับ	ไม่รองรับ
นโยบาย bucket / ACL	รองรับ	ใช้โหมดการเข้าถึง gateway
URL ที่ลงนามล่วงหน้า	รองรับ	ใช้โทเค็นอัปโหลดที่ลงนาม
ขนาดออบเจกต์สูงสุด	5 TB	5 GB (หลายส่วน), 100 MB (PUT เดียว)
ภูมิภาค	หลายภูมิภาค	us-east-1 เท่านั้น
ค่า ETag	MD5 hash	IPFS CID
Header เพิ่มเติม	S3 มาตรฐาน	x-amz-meta-cid (IPFS CID)
รูปแบบ CID	ไม่มี	CIDv1 รุ่นใหม่ (bafy…) สำหรับการอัปโหลดใหม่; Qm… แบบเก่ายังคงใช้เป็นอินพุตได้
เนมสเปซ bucket	ทั่วโลก (ทั้ง AWS)	ทั่วโลก (ทุกบัญชี IPFS Ninja) — ความหมายเดียวกัน
CORS	รองรับ PutBucketCors	รองรับ PutBucketCors (จำกัด 5 กฎ)

การย้ายจาก Amazon S3

เปลี่ยนการตั้งค่า S3 client ของคุณ:

 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

เปลี่ยน 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
 });