Gateway Khusus

Pengguna pelan Nirvana mendapat gateway IPFS peribadi di subdomain unik. Gateway ini hanya menyajikan fail yang disemat ke akaun anda — ia tidak akan menyelesaikan CID daripada pengguna lain atau rangkaian IPFS awam.

URL Gateway anda

URL gateway anda ditunjukkan di halaman Gateway anda dan dikembalikan oleh endpoint /user/profile:

https://<your-slug>.gw.ipfs.ninja/ipfs/<CID>

Mod akses

Mod	Tingkah laku
Terbuka (lalai)	Sesiapa yang mempunyai URL gateway + CID anda boleh mengakses fail anda. Tiada token diperlukan.
Token diperlukan	Permintaan mesti menyertakan gateway token melalui parameter kueri ?token=gwt_... atau header X-Gateway-Token.

Had

• Lebar jalur gateway 50 GB/bulan disertakan dengan Nirvana
• Apabila had lebar jalur dicapai, permintaan gateway mengembalikan 429 sehingga bulan berikutnya
• Penggunaan storan direset pada hari pertama setiap bulan kalendar
• Hanya menyajikan CID yang disemat ke akaun anda — permintaan untuk CID lain mengembalikan 403

Gateway apex

Gateway apex bersama di https://ipfs.ninja/ipfs/<CID> tersedia dalam semua pelan dan tidak memerlukan pengesahan, tetapi hanya menyajikan CID yang telah dimuat naik atau disematkan oleh pengguna IPFS Ninja. Permintaan untuk CID lain mengembalikan HTTP 410 Gone.

Untuk CID yang anda tidak miliki, anda boleh (a) lakukan POST /pin untuk menyematkannya ke akaun anda, kemudian gunakan URL apex, atau (b) gunakan gateway pihak ketiga seperti https://ipfs.io/ipfs/<CID> atau https://dweb.link/ipfs/<CID>.

Untuk pembenaman peringkat pengeluaran (video, pemapar NFT, tapak), gateway khusus di atas adalah corak yang disyorkan — ia menawarkan had kadar yang lebih tinggi, kawalan akses boleh dikonfigurasi, dan lebar jalur khusus.

Tetapan Gateway

Konfigurasikan kawalan akses untuk gateway khusus anda.

Kemas Kini Tetapan

PUT /gateway-settings

Parameter	Jenis	Diperlukan	Penerangan
tokenRequired	boolean	Tidak	Dayakan/lumpuhkan keperluan gateway token.
ipWhitelist	string[]	Tidak	Tatasusunan alamat IP yang dibenarkan. Maks 100. Tatasusunan kosong membuang whitelist.
allowedOrigins	string[]	Tidak	Tatasusunan origin yang dibenarkan untuk permintaan pelayar. Maks 100. Mesti format HTTPS (cth. https://myapp.com). Tatasusunan kosong membenarkan semua origin.

Contoh

# Dayakan mod token diperlukan
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"tokenRequired": true}'

# Tetapkan IP whitelist
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipWhitelist": ["203.0.113.1", "198.51.100.0"]}'

# Kosongkan IP whitelist (benarkan semua IP)
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipWhitelist": []}'

# Hadkan kepada origin tertentu
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"allowedOrigins": ["https://myapp.com", "https://staging.myapp.com"]}'

# Buang sekatan origin (benarkan semua origin)
curl -X PUT https://api.ipfs.ninja/gateway-settings \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"allowedOrigins": []}'

Sekatan Origin

Apabila allowedOrigins dikonfigurasikan, hanya permintaan pelayar dari origin yang disenaraikan dibenarkan. Gateway menyemak header Origin dan Referer pada permintaan masuk.

• Jika senarai kosong (lalai), semua origin dibenarkan.
• Jika origin ditentukan, permintaan dengan header Origin atau Referer yang tidak sepadan ditolak dengan respons 403.
• Permintaan bukan pelayar yang tidak menyertakan header Origin (seperti fetch sisi pelayan atau curl) melepasi tanpa sekatan.

Ini berguna untuk menyematkan kandungan gateway dalam aplikasi web anda sambil menghalang laman lain daripada memaut terus fail anda.

Gateway Tokens

Gateway token (prefix gwt_) adalah baca sahaja dan selamat untuk disematkan dalam aplikasi frontend. Tidak seperti API key, gateway token hanya boleh mengakses fail melalui gateway khusus anda — ia tidak boleh memuat naik, memadam atau mengurus akaun anda.

Keupayaan	API Key (bws_)	Gateway Token (gwt_)
Muat naik / padam fail	Ya	Tidak
Senarai / dapatkan metadata fail	Ya	Tidak
Baca fail melalui gateway	Tidak	Ya
Selamat untuk disematkan di frontend	Tidak	Ya

Cipta Gateway Token

POST /gateway-tokens

Parameter	Jenis	Diperlukan	Penerangan
name	string	Tidak	Label untuk token (cth. "Frontend"). Lalai kepada "Default".

Respons 201 Created

{
  "token": "gwt_a1b2c3d4e5f6789012345678abcdef01",
  "tokenPrefix": "gwt_a1b2c3d4",
  "tokenName": "Frontend",
  "createdAt": 1711036800000
}

WARNING

Token penuh hanya dikembalikan sekali semasa penciptaan. Simpan dengan selamat.

Senaraikan Gateway Tokens

GET /gateway-tokens

[
  {
    "tokenPrefix": "gwt_a1b2c3d4",
    "tokenName": "Frontend",
    "createdAt": 1711036800000
  }
]

Padam Gateway Token

DELETE /gateway-tokens/:prefix

Parameter	Jenis	Diperlukan	Penerangan
prefix	string	Ya	Prefix token untuk dipadam (cth. "gwt_a1b2c3d4").

Menggunakan gateway token

Apabila gateway anda mempunyai mod token diperlukan didayakan, hantar token sebagai parameter kueri atau header:

# Parameter kueri
curl "https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz...?token=gwt_your_token"

# Atau header
curl https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz... \
  -H "X-Gateway-Token: gwt_your_token"