专属网关

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"