常见问题

关于 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。该服务按"现状"提供。