常见问题

关于 IPFS Ninja 的常见问题。

综合

IPFS Ninja 是什么？

IPFS Ninja 是一项托管的 IPFS 固定服务。您可以通过简单的 REST API 上传任何文件，或固定 IPFS 网络上的现有 CID。每个文件都会获得一个永久内容标识符 (CID)，并可通过我们的网关 ipfs.ninja/ipfs/<CID> 访问。

ipfs.ninja/ipfs/<CID> 是否提供 IPFS 网络上的任何 CID？

不是。apex 网关仅提供由 IPFS Ninja 用户上传或固定的 CID。对未知 CID 的请求返回 HTTP 410 Gone，并指向公共 IPFS 网关（ipfs.io、dweb.link）。要通过我们的网关提供第三方 CID，请先对您的账户执行 POST /pin — 一旦固定，该 CID 即可通过 apex 网关和您的专属网关 URL 访问。

apex 网关和专属网关有什么区别？

方面	apex ipfs.ninja/ipfs/<CID>	专属 <slug>.gw.ipfs.ninja/ipfs/<CID>
范围	所有用户共享	仅您的 CID
认证	无	可选令牌 / IP allowlist / origin allowlist
SLA	尽力而为	完整 SLA
推荐用于	随意链接	生产嵌入（NFT、视频、网站）
速率限制	按 IP + 按 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 网络上仍然可用。

为什么我的新 CID 从 Qm... 变成了 bafy...？

新的上传和固定操作会按照 IPIP-0499 unixfs-v1-2025 规范返回现代 CIDv1（小型单区块内容为 bafk…，较大文件和目录为 bafy…）：CIDv1 base32 编码、1 MiB 分块、原始叶子节点（raw leaves）。这与现代工具（Helia、最新版 Kubo、ipfs-car）针对相同内容生成的结果一致，因此通过我们上传的文件所获得的 CID，与任何现代客户端针对相同字节计算出的 CID 完全相同。

早期上传产生的旧版 Qm… CID 仍然完全可以解析 — 网关、POST /pin、GET /file、IPNS 以及所有其他端点都会无限期地接受这两种格式。您已有的内容不会受到任何影响。

如何固定位于私有 / 非 DHT 节点上的内容？

POST /pin 接受可选的 multiaddresses[] 参数（最多 5 个）。如果提供，我们的集群会在执行固定操作之前，对每一个提示分别执行 ipfs swarm connect <multiaddr>，这样一来，未通过公共 DHT 广播的对等节点（私有节点、预发布环境、VPN 内网机器）上的内容也能够被访问到。请参阅从私有 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。

哪些计划包含专属网关？

所有付费计划（Bodhi $5/月、Karma $19/月、Nirvana $59/月）均包含专属网关。每个计划的月度网关带宽配额同时覆盖来自 apex 网关和专属网关的流量。各计划的具体配额请参阅下文的"有带宽费用吗？"。

可以限制谁访问我的网关吗？

可以。您可以启用令牌必填模式（每个请求都需要 gwt_ 令牌）和/或设置 IP 白名单（最多 100 个地址）。

可以按来源/域名限制我的网关吗？

可以。在您的网关设置中配置 allowedOrigins，提供一份 HTTPS 来源列表。只有来自这些来源的浏览器请求才会被允许。不带 Origin 头的非浏览器请求可以正常通过。空列表表示允许所有来源。

什么是签名上传令牌？

签名上传令牌是用于客户端上传的限时凭证。您在服务器上使用 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 请求，无需信用卡。

有带宽费用吗？

任何计划都没有按量计费的带宽费用。每个计划都包含一个月度网关带宽配额，这是一个硬性上限 — 一旦达到该配额，您的内容将停止通过 apex 网关和专属网关提供服务，直到下个月 1 日或升级计划后才会恢复：

计划	每月带宽
Dharma	2 GB
Bodhi	20 GB
Karma	100 GB
Nirvana	500 GB

当您的用量达到配额的 80% 和 100% 时，您将收到警告邮件。

存储空间会重置吗？

存储空间不会重置。您的计划包含一个总存储配额（Dharma 1 GB / Bodhi 10 GB / Karma 100 GB / Nirvana 1 TB）。要释放空间，请删除不再需要的文件。升级计划会增加您的总配额。

可以随时取消吗？

可以。通过计费门户取消订阅 — 没有锁定期。您的账户将恢复到免费层级，现有已固定的文件仍然可以访问。

如果降级，我的文件会怎样？

您的文件仍然固定在 IPFS 上，但如果您当前的用量超过新计划的存储限制，则无法再上传更多文件。删除文件即可回到限制以内。

安全

我的数据是否加密？

所有数据在传输过程中均通过 TLS/HTTPS 加密。认证使用 JWT 令牌（Cognito）以及安全存储的 API 密钥。IPFS 上的文件内容在静态存储时不加密 — IPFS 本质上是一个公共网络。

在服务器端代码中使用 API 密钥安全吗？

安全。API 密钥是为服务器端使用而设计的。切勿在客户端代码中暴露它们。对于客户端文件访问，请使用只读的网关令牌（gwt_）。

支持

如何获取帮助？

发送邮件至 info@ipfs.ninja 或查看 API 参考 文档。

有 SLA 吗？

我们致力于提供高可用性，但目前不提供正式的 SLA。该服务按"现状"提供。