S3 kompatibilitás

Használja az AWS SDK-t fájlok feltöltéséhez, letöltéséhez és kezeléséhez az IPFS Ninja-n ugyanazzal a kóddal, amit az Amazon S3-hoz használ.

Endpoint

https://s3.ipfs.ninja

Hitelesítő adatok

Az S3 API az Ön IPFS Ninja API kulcsát használja hitelesítéshez. Az API kulcsa egyszerre szolgál access key-ként és secret key-ként.

Hogyan szerezheti meg a hitelesítő adatait

Menjen az Irányítópult > API kulcsok oldalra
Kattintson a Create API key gombra, és adjon neki nevet (pl. „S3 hozzáférés")
Azonnal másolja ki a teljes kulcsot — csak egyszer jelenik meg, és később nem kérhető le

A kulcsa így néz ki:

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

Leképezés AWS hitelesítő adatokra

AWS paraméter	Érték	Példa
`accessKeyId`	Az API kulcsa első 12 karaktere	`bws_628bba35`
`secretAccessKey`	A teljes API kulcs (mind a 36 karakter)	`bws_628bba35e9e0079d9ff9c392b1b55a7b`
`region`	Mindig `us-east-1`	`us-east-1`

WARNING

A teljes API kulcs csak egyszer jelenik meg, amikor létrehozza. Ha elveszíti, törölje a kulcsot, és hozzon létre újat az API kulcsok oldalon.

Gyors kezdés

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: bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi

Buckets = Mappák

Az S3 bucketek az Ön IPFS Ninja mappáinak felelnek meg. Amikor feltölt egy fájlt egy bucketbe, az a megfelelő mappában tárolódik. Amikor listázza egy bucket objektumait, a mappa fájljait látja.

S3 művelet	IPFS Ninja megfelelő
`CreateBucket`	Új mappa létrehozása
`ListBuckets`	Mappái listázása
`DeleteBucket`	Mappa és minden fájljának törlése
`PutObject` bucketbe	Fájl feltöltése a mappába
`ListObjectsV2` bucketen	Fájlok listázása a mappában

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

Az S3 API-n keresztül létrehozott mappák ugyanazok a mappák, amelyek az Irányítópultján láthatók. A fájlokat az S3 API-ból, a REST API-ból vagy a webes felületről egyaránt rendezheti — mindegyik ugyanazt a mapparendszert használja.

INFO

Az Amazon S3-tól eltérően az IPFS Ninja mappák alapértelmezetten laposak. Egymásba ágyazott struktúrák létrehozásához használja a REST API mappa végpontjait a parentFolderId paraméterrel. Az S3 API-ból használjon kulcs-prefixeket (pl. images/photo.png) a mappán belüli szervezéshez.

A bucket nevek globálisan egyediek

A bucket nevek egy globális névtérben élnek az összes ügyfél között, az AWS S3 szemantikájának megfelelően. Ez azt jelenti:

Az első felhasználó, aki egy adott néven hoz létre bucketet, globálisan lefoglalja azt a nevet.
A későbbi, ugyanazzal a névvel érkező CreateBucket hívások bármely fiókból BucketAlreadyExists (409) hibát adnak vissza.
Ha megpróbálja újra létrehozni saját bucketjét, BucketAlreadyOwnedByYou (409) hibát kap.
Az irányítópulton lévő mappa neve fiókonkénti, és bármi lehet — csak az S3-ban látható bucket név megy át a globális névtéren.

Ha egy kívánt név foglalt, válasszon egy máshogy megkülönböztetett nevet (myapp-photos-2026, acme-nft-metadata) — ugyanaz a konvenció, mint az Amazon S3-on.

Támogatott műveletek

PutObject

Töltsön fel egy fájlt az IPFS-re. A fájl rögzítésre és biztonsági vizsgálatra kerül, a CID pedig az ETag és x-amz-meta-cid fejlécekben kerül visszaadásra.

Egy CAR fájl importálásához (rendes fájl helyett) adja hozzá az x-amz-meta-import: car metaadat fejlécet. Részletekért lásd a CAR importot.

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

Töltsön le egy fájlt a kulcsa (fájlneve) vagy CID-je alapján.

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

Kérje le a fájl metaadatait a tartalom letöltése nélkül.

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

Oldja fel egy fájl rögzítését az IPFS-en, és törölje a fiókjából.

javascript

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

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

ListObjectsV2

Listázza egy bucket fájljait opcionális prefix szűréssel és lapozással.

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

Töltsön fel nagy fájlokat (legfeljebb 5 GB) multipart feltöltéssel. Az AWS SDK ezt automatikusan kezeli:

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

Vagy kezelje manuálisan a részeket:

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 példa

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 példa

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 beállítása (böngészős SDK hozzáférés)

Ha az S3 API-t közvetlenül böngésző JavaScriptből hívja (SPA, wallet alkalmazás, irányítópult eszköz), először be kell állítania a CORS-t a bucketen. Ellenkező esetben a böngészők blokkolják a preflight kérést, és a feltöltései a No 'Access-Control-Allow-Origin' header is present hibával hiúsulnak meg.

Ugyanaz a felépítés, mint az AWS S3-nál — PutBucketCors / GetBucketCors / DeleteBucketCors alerőforrások:

PutBucketCors

javascript

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

javascript

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

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

DeleteBucketCors

javascript

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

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

Korlátok és alapértékek

Legfeljebb 5 szabály bucketenként (a specifikáció 100-at engedélyez, mi 5-re korlátozzuk, hogy a böngésző preflight válasza kompakt maradjon).
A teljes konfiguráció legfeljebb 64 KB szerializálva.
Ha nincs beállítva CORS konfiguráció, a böngésző preflightok elutasításra kerülnek — az AWS S3 alapértelmezett viselkedésének megfelelően. Állítson be explicit szabályokat azokhoz az origin-ekhez, amelyekről ténylegesen kiszolgál.

Valós biztonsági megjegyzés

A CORS egy böngésző-oldali kényelmi réteg, nem biztonsági határ. Minden S3 API hívás továbbra is érvényes SigV4 aláírást igényel, amelyet az API kulcsából számítanak ki — egy megengedő CORS konfiguráció nem teszi lehetővé senkinek, hogy ez a hitelesítő adat nélkül használja a bucketjét. Amit a CORS megakadályoz: egy nem kívánt origin (pl. az alkalmazása elavult másolata a dev.myapp.com címen) böngészőkontextusból küldött, aláírt kéréseit.

Irányítópult alternatíva

A Fájlok oldalon minden mappa műveletmenüjében van egy S3 CORS bejegyzés. Ugyanaz az alapul szolgáló tárolás; ha nem szeretne PutBucketCors kódot írni, ott is beállíthatja.

Különbségek az Amazon S3-hoz képest

Funkció	Amazon S3	IPFS Ninja S3
Tárolási modell	Módosítható objektumok	Tartalom-címzett (változtathatatlan CID-ek)
Felülírási viselkedés	Helyben cseréli az objektumot	Új CID-et hoz létre, a régi CID továbbra is elérhető
Verziózás	Támogatott	Nem támogatott (használjon CID-eket verziózáshoz)
Szerveroldali titkosítás	Támogatott	Nem támogatott (a tartalom az IPFS-en van)
Életciklus-szabályzatok	Támogatottak	Nem támogatottak
Bucket szabályzatok / ACL-ek	Támogatottak	Használja a gateway hozzáférési módokat
Előre aláírt URL-ek	Támogatottak	Használja az aláírt feltöltési tokeneket
Maximális objektumméret	5 TB	5 GB (multipart), 100 MB (egyszeri PUT)
Régiók	Több régió	Csak `us-east-1`
`ETag` érték	MD5 hash	IPFS CID
Extra fejlécek	Standard S3	`x-amz-meta-cid` (IPFS CID)
CID formátum	N/A	Modern CIDv1 (`bafy…`) az új feltöltésekhez; az örökölt `Qm…` továbbra is érvényes bemenetként
Bucket névtér	Globális (AWS-szintű)	Globális (az összes IPFS Ninja fiók között) — ugyanaz a szemantika
CORS	`PutBucketCors` támogatott	`PutBucketCors` támogatott (5 szabályos korlát)

Migrálás az Amazon S3-ról

Cserélje ki az S3 kliens konfigurációját:

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

A meglévő PutObject, GetObject, ListObjectsV2 és DeleteObject hívásai változtatás nélkül működnek.

Migrálás a Filebase-ről

Cserélje ki az endpoint URL-t:

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 kompatibilitás ​

Endpoint ​

Hitelesítő adatok ​

Hogyan szerezheti meg a hitelesítő adatait ​

Leképezés AWS hitelesítő adatokra ​

Gyors kezdés ​

Buckets = Mappák ​

A bucket nevek globálisan egyediek ​

Támogatott műveletek ​

PutObject ​

GetObject ​

HeadObject ​

DeleteObject ​

ListObjectsV2 ​

Multipart Upload ​

Python példa ​

Go példa ​

CORS beállítása (böngészős SDK hozzáférés) ​

PutBucketCors ​

GetBucketCors ​

DeleteBucketCors ​

Korlátok és alapértékek ​

Valós biztonsági megjegyzés ​

Irányítópult alternatíva ​

Különbségek az Amazon S3-hoz képest ​

Migrálás az Amazon S3-ról ​

Migrálás a Filebase-ről ​

S3 kompatibilitás

Endpoint

Hitelesítő adatok

Hogyan szerezheti meg a hitelesítő adatait

Leképezés AWS hitelesítő adatokra

Gyors kezdés

Buckets = Mappák

A bucket nevek globálisan egyediek

Támogatott műveletek

PutObject

GetObject

HeadObject

DeleteObject

ListObjectsV2

Multipart Upload

Python példa

Go példa

CORS beállítása (böngészős SDK hozzáférés)

PutBucketCors

GetBucketCors

DeleteBucketCors

Korlátok és alapértékek

Valós biztonsági megjegyzés

Irányítópult alternatíva

Különbségek az Amazon S3-hoz képest

Migrálás az Amazon S3-ról

Migrálás a Filebase-ről