專屬閘道

Nirvana 方案使用者可取得位於唯一子網域的私有 IPFS 閘道。此閘道僅提供固定到您帳戶的檔案 — 不會解析其他使用者或公共 IPFS 網路的 CID。

您的閘道 URL

您的閘道 URL 顯示在閘道頁面中，也透過 /user/profile 端點傳回：

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

存取模式

模式	行為
開放（預設）	任何擁有您閘道 URL + CID 的人都可以存取您的檔案。無需權杖。
權杖必填	請求必須透過 ?token=gwt_... 查詢參數或 X-Gateway-Token 標頭包含閘道權杖。

限制

• Nirvana 包含每月 50 GB 閘道頻寬
• 達到頻寬限制後，閘道請求傳回 429 直到下月
• 儲存使用量在每個日曆月的第一天重置
• 僅提供固定到您帳戶的 CID — 請求其他 CID 傳回 403

TIP

ipfs.ninja/ipfs/ 的公共閘道在所有方案中均可用，無需驗證即可提供任何 CID。

閘道設定

設定專屬閘道的存取控制。

更新設定

PUT /gateway-settings

參數	類型	必填	描述
tokenRequired	boolean	否	啟用/停用閘道權杖要求。
ipWhitelist	string[]	否	允許的 IP 位址陣列。最多 100 個。空陣列移除白名單。
allowedOrigins	string[]	否	允許瀏覽器請求的來源陣列。最多 100 個。必須使用 HTTPS 格式（如 https://myapp.com）。空陣列允許所有來源。

範例

# 啟用權杖必填模式
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}'

# 設定 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": ["203.0.113.1", "198.51.100.0"]}'

# 清除 IP 白名單（允許所有 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": []}'

# 限制為特定來源
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"]}'

# 移除來源限制（允許所有來源）
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": []}'

來源限制

設定 allowedOrigins 後，僅允許來自列出來源的瀏覽器請求。閘道會檢查傳入請求的 Origin 和 Referer 標頭。

• 如果清單為空（預設），允許所有來源。
• 如果指定了來源，帶有不相符 Origin 或 Referer 標頭的請求將被 403 回應拒絕。
• 不包含 Origin 標頭的非瀏覽器請求（如伺服器端請求或 curl）不受限制通過。

這對於在 Web 應用程式中嵌入閘道內容同時防止其他網站盜連您的檔案非常有用。

閘道權杖

閘道權杖（gwt_ 前綴）是唯讀的，可安全嵌入前端應用程式。與 API 金鑰不同，閘道權杖只能透過您的專屬閘道存取檔案 — 不能上傳、刪除或管理您的帳戶。

功能	API 金鑰 (bws_)	閘道權杖 (gwt_)
上傳 / 刪除檔案	是	否
列出 / 取得檔案中繼資料	是	否
透過閘道讀取檔案	否	是
可安全嵌入前端	否	是

建立閘道權杖

POST /gateway-tokens

參數	類型	必填	描述
name	string	否	權杖標籤（如 "Frontend"）。預設為 "Default"。

回應 201 Created

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

WARNING

完整權杖僅在建立時傳回一次。請妥善保管。

列出閘道權杖

GET /gateway-tokens

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

刪除閘道權杖

DELETE /gateway-tokens/:prefix

參數	類型	必填	描述
prefix	string	是	要刪除的權杖前綴（如 "gwt_a1b2c3d4"）。

使用閘道權杖

當您的閘道啟用了權杖必填模式時，將權杖作為查詢參數或標頭傳遞：

# 查詢參數
curl "https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz...?token=gwt_your_token"

# 或標頭
curl https://a1b2c3d4.gw.ipfs.ninja/ipfs/QmXk7VRz... \
  -H "X-Gateway-Token: gwt_your_token"