常見問題

關於 IPFS Ninja 的常見問題。

綜合

IPFS Ninja 是什麼？

IPFS Ninja 是一項代管的 IPFS 固定服務。您可以透過簡單的 REST API 上傳任何檔案，或固定 IPFS 網路上的現有 CID。每個檔案都會取得一個永久內容識別碼 (CID)，並可透過我們的閘道 ipfs.ninja/ipfs/<CID> 存取。

支援哪些檔案類型？

支援所有檔案類型。JSON 物件和陣列可以直接傳送。所有其他檔案（圖片、PDF、HTML、影片、音訊、二進位檔案）以 base64 編碼內容傳送。

有檔案大小限制嗎？

單個上傳受您方案儲存配額的限制。除可用儲存空間外，沒有單個檔案大小限制。

可以固定 IPFS 上已存在的內容嗎？

可以。使用 POST /pin 並提供任何有效的 CID。我們的叢集將從 IPFS 網路擷取內容並固定到您的帳戶。詳情請參閱固定 API 文件。

固定需要多長時間？

這取決於檔案大小和擁有該內容的 IPFS 節點數量。小型且分佈廣泛的檔案通常幾秒內即可固定。大型或很少被固定的內容可能需要幾分鐘。固定端點會立即傳回 pinning 狀態 — 輪詢 GET /pin/:cid 檢查進度。

如果找不到 CID 會怎樣？

狀態會變為 failed。這表示 CID 無效，或者內容在任何可達的 IPFS 節點上都已不可用。

上傳到 IPFS 的資料是公開的嗎？

是的。固定到 IPFS 的所有內容都可以透過任何 IPFS 閘道使用其 CID 公開存取。如果您需要私有存取，請使用帶有權杖必填模式的專屬閘道 — 這會限制透過您的閘道的存取，但內容在更廣泛的 IPFS 網路上仍然可用。

如果我取消帳戶，檔案會留在 IPFS 上嗎？

當您取消時，我們會從節點上取消固定您的檔案。如果其他 IPFS 節點快取了您的內容，它可能仍然可存取。但是，沒有活躍的固定，檔案最終會被網路中的垃圾回收清除。

驗證和 API

如何驗證 API 請求？

透過 X-Api-Key 標頭傳遞您的 API 金鑰。在儀表板的 API 金鑰頁面產生金鑰。

有 API 速率限制嗎？

沒有。IPFS Ninja 不對 API 請求施加速率限制。您可以在任何方案上發出任意數量的請求。

API 金鑰會過期嗎？

不會。API 金鑰在您刪除之前一直有效。您可以建立多個金鑰並個別撤銷。

API 金鑰和閘道權杖有什麼區別？

API 金鑰（bws_）擁有完全存取權限 — 上傳、刪除、列出檔案。閘道權杖（gwt_）是唯讀的，只能透過您的專屬閘道存取檔案。閘道權杖可以安全地嵌入前端應用程式中。

專屬閘道

什麼是專屬閘道？

專屬閘道是位於您自己的子網域（例如 abc123.gw.ipfs.ninja）的私有 IPFS 閘道，僅提供固定到您帳戶的檔案。與公共閘道不同，它不會解析其他使用者的 CID。

哪些方案包含專屬閘道？

專屬閘道在 Nirvana 方案（$29/月）中可用，包含每月 50 GB 的閘道頻寬。

可以限制誰存取我的閘道嗎？

可以。您可以啟用權杖必填模式（每個請求都需要 gwt_ 權杖）和/或設定 IP 白名單（最多 100 個位址）。

可以按來源/網域限制我的閘道嗎？

可以。在您的閘道設定中設定 allowedOrigins，包含 HTTPS 來源清單。只有來自這些來源的瀏覽器請求才會被允許。不帶 Origin 標頭的非瀏覽器請求（如伺服器端請求或 curl）不受限制。空清單允許所有來源。

什麼是簽章上傳權杖？

簽章上傳權杖是用於用戶端上傳的限時憑證。您在伺服器上使用 POST /upload/signed-url 產生它們，然後傳遞給瀏覽器或行動應用程式。用戶端使用 Authorization: Signed <token> 進行驗證，而不是暴露您的 API 金鑰。每個權杖都會追蹤使用情況並自動過期。詳情請參閱簽章權杖文件。

可以最佳化從 IPFS 提供的圖片嗎？

可以。使用 GET /image/:cid 並附帶 w、h、format 和 quality 等查詢參數來即時調整大小、轉換和壓縮圖片。回應基於內容定址的 CID 進行快取。此功能在所有方案中可用。請參閱圖片最佳化。

可以為檔案附加中繼資料嗎？

可以。在透過 POST /upload/new 上傳或透過 POST /pin 固定時，包含一個最多 10 個鍵值對的 metadata 物件。中繼資料會在檔案清單和檔案詳情端點中傳回。請參閱檔案和固定文件。

帳單和方案

有免費方案嗎？

有。Dharma 方案永久免費 — 1 GB 儲存空間，無限 API 請求，無需信用卡。

有頻寬費用嗎？

任何方案的 API 請求都沒有頻寬費用。專屬閘道頻寬（Nirvana 方案）包含每月 50 GB。達到限制後，閘道請求將被封鎖，直到下個月。

儲存空間會重置嗎？

儲存空間不會重置。您的方案包含總儲存配額（1 GB / 10 GB / 100 GB）。要釋放空間，請刪除不再需要的檔案。升級方案會增加您的總配額。

可以隨時取消嗎？

可以。透過帳單入口取消訂閱 — 沒有綁約。您的帳戶將恢復到免費層級，現有固定的檔案仍然可存取。

如果降級，我的檔案會怎樣？

您的檔案仍然固定在 IPFS 上，但如果目前使用量超過新方案的儲存限制，則無法上傳更多檔案。刪除檔案以回到限制以下。

安全

我的資料是否加密？

所有資料透過 TLS/HTTPS 在傳輸中加密。驗證使用 JWT 權杖（Cognito）和安全儲存的 API 金鑰。IPFS 上的檔案內容在靜態時不加密 — IPFS 本質上是一個公共網路。

在伺服器端程式碼中使用 API 金鑰安全嗎？

安全。API 金鑰是為伺服器端使用而設計的。永遠不要在用戶端程式碼中暴露它們。對於用戶端檔案存取，請使用唯讀的閘道權杖（gwt_）。

支援

如何取得協助？

傳送電子郵件至 info@ipfs.ninja 或查看 API 參考文件。

有 SLA 嗎？

我們致力於提供高可用性，但目前不提供正式的 SLA。該服務按「現狀」提供。