IPNS — IPFS 的可变名称

IPNS (InterPlanetary Name System) 为您提供稳定、可分享的地址，可以随时间更新指向不同的内容。虽然 IPFS CID 在每次内容更改时都会变化，但 IPNS 名称保持不变 — 您只需更新它指向的位置。

在 Bodhi（3 个名称，每月 100 次发布）和 Nirvana（10 个名称，每月 1,000 次发布）计划中可用。

了解更多关于 IPNS

要深入了解 IPNS 在协议层面的工作原理，请参阅 IPFS 官方文档中的 IPNS。

为什么使用 IPNS？

问题： 每次您将文件的新版本上传到 IPFS 时，都会获得不同的 CID。如果您已经将旧 CID 分享给用户，他们仍然看到旧内容。您必须每次都分享新链接。

解决方案： 创建一次 IPNS 名称，分享它，然后在内容更改时更新它指向的位置。拥有 IPNS 地址的任何人始终获取最新版本。

常见使用场景

IPFS 上的网站 — 部署网站，获取 CID，发布到 IPNS 名称。重新部署 → 新 CID → 更新 IPNS 名称。URL 永不改变。
可进化的 NFT 元数据 — 将 NFT 的 tokenURI 指向 IPNS 地址。更新元数据（例如游戏道具升级）而无需更改智能合约。
配置文件 — 应用从 IPNS 地址读取配置。更新配置而无需重新部署应用。
数据源 — 在稳定的 IPNS 地址下发布每日数据集或价格源。
DNSLink — 将您的域名连接到 IPNS，使 https://yourdomain.com 始终提供最新的 IPFS 内容。

使用仪表盘

1. 创建 IPNS 名称

在侧边栏的"托管"下找到 IPNS。
点击创建名称。
输入标签（如 "my-website"）并点击创建。
复制 IPNS 地址（以 k51... 开头）— 这是您永久的、可分享的地址。

2. 将 CID 发布到 IPNS 名称

在列表中找到 IPNS 名称并点击发布。
输入要指向的 CID（如 QmXk7VRz... 或 bafybei...）。
点击发布。这将传播到 IPFS 网络，可能需要最多 60 秒。
发布后，可通过以下方式访问内容：
- IPFS 网关： https://ipfs.ninja/ipns/{your-ipns-name}
- 任何公共网关： https://dweb.link/ipns/{your-ipns-name}
- IPFS 原生： ipns://{your-ipns-name}

3. 更新内容

当内容更改时：

将新版本上传到 IPFS（通过仪表盘或 API）→ 获取新 CID。
返回 IPNS，在同一名称上点击发布，输入新 CID。
IPNS 地址保持不变 — 使用它的任何人都会自动获取新内容。

4. 解析 IPNS 名称

使用页面底部的解析部分查找任何 IPNS 名称的当前 CID — 您的或其他人的。

5. 删除 IPNS 名称

点击任何名称旁边的删除按钮。IPNS 记录将在 48 小时内从网络中过期。

使用 DNSLink 连接域名

您可以使用 DNSLink 将自己的域名指向 IPNS 地址。这让用户可以通过普通 URL（如 https://yourdomain.com）访问您的 IPFS 内容。

如何设置 DNSLink

创建 IPNS 名称并将内容 CID 发布到该名称（上述步骤）。

在域名 DNS 提供商处添加 DNS TXT 记录：

_dnslink.yourdomain.com  TXT  "dnslink=/ipns/{your-ipns-name}"

示例： 如果您的 IPNS 名称是 k51qzi5uqu5djcpbukxs...：

_dnslink.myapp.com  TXT  "dnslink=/ipns/k51qzi5uqu5djcpbukxs..."

使用 dig 或 nslookup 验证记录：

bash

dig +short TXT _dnslink.myapp.com
# Should return: "dnslink=/ipns/k51qzi5uqu5djcpbukxs..."

通过任何支持 DNSLink 的 IPFS 网关访问：
```
https://ipfs.ninja/ipns/myapp.com
```
或通过支持 IPFS 的浏览器（如 Brave）：
```
ipns://myapp.com
```

DNS 传播

DNS 更改可能需要最多 24 小时在全球传播。添加 TXT 记录后，请等待几小时再测试。

TIP

您只需设置一次 DNSLink。当您将新 CID 发布到 IPNS 名称时，域名会自动解析到新内容 — 无需更改 DNS。

使用 Cloudflare 的 DNSLink

如果您使用 Cloudflare：

前往 DNS → Records。
添加新记录：Type: TXT, Name: _dnslink, Content: dnslink=/ipns/k51...
将代理状态设为 DNS only（灰色云朵）。

使用 Route 53 的 DNSLink

前往 Route 53 中的托管区域。
创建记录：Name: _dnslink.yourdomain.com, Type: TXT, Value: "dnslink=/ipns/k51..."

使用示例

示例 1：静态网站部署

bash

# 1. Build your site
npm run build

# 2. Upload the build output to IPFS
CID=$(curl -s -X POST https://api.ipfs.ninja/upload/new \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"content\": $(cat dist/index.html | base64 -w0 | jq -Rs .), \"description\": \"Website v2.1\"}" \
  | jq -r '.cid')

echo "Uploaded: $CID"

# 3. Update your IPNS name to point to the new build
curl -X POST https://api.ipfs.ninja/ipns/publish \
  -H "X-Api-Key: bws_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{\"ipnsName\": \"k51qzi5uqu5dlvj2bv6...\", \"cid\": \"$CID\"}"

# Your site at ipns://k51... now serves the new version

示例 2：可变 NFT 元数据

javascript

// Smart contract points tokenURI to IPNS address:
// tokenURI = "ipns://k51qzi5uqu5dlvj2bv6..."

// When the NFT evolves (e.g., game item levels up):
const newMetadata = {
  name: "Dragon Sword",
  description: "A legendary weapon — Level 5",
  image: "ipfs://QmNewImageCID...",
  attributes: [
    { trait_type: "Level", value: 5 },
    { trait_type: "Damage", value: 150 }
  ]
};

// Upload new metadata
const uploadRes = await fetch("https://api.ipfs.ninja/upload/new", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "bws_your_api_key"
  },
  body: JSON.stringify({ content: newMetadata, description: "Dragon Sword v5" })
});
const { cid } = await uploadRes.json();

// Update the IPNS pointer — tokenURI stays the same!
await fetch("https://api.ipfs.ninja/ipns/publish", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "bws_your_api_key"
  },
  body: JSON.stringify({ ipnsName: "k51qzi5uqu5dlvj2bv6...", cid })
});

示例 3：CI/CD 集成

yaml

# GitHub Actions: auto-publish to IPNS on every push
- name: Upload to IPFS and publish IPNS
  run: |
    CID=$(curl -s -X POST https://api.ipfs.ninja/upload/new \
      -H "X-Api-Key: ${{ secrets.IPFS_NINJA_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{"content": '"$(cat build/output.json)"', "description": "Deploy ${{ github.sha }}"}' \
      | jq -r '.cid')

    curl -X POST https://api.ipfs.ninja/ipns/publish \
      -H "X-Api-Key: ${{ secrets.IPFS_NINJA_API_KEY }}" \
      -H "Content-Type: application/json" \
      -d '{"ipnsName": "${{ vars.IPNS_NAME }}", "cid": "'"$CID"'"}'

API 参考

所有 API 示例使用 X-Api-Key 头。从 API 密钥页面获取您的 API 密钥。

列出 IPNS 密钥

bash

curl https://api.ipfs.ninja/ipns/keys \
  -H "X-Api-Key: bws_your_api_key_here"

响应：

json

[
  {
    "ipnsName": "k51qzi5uqu5dlvj2bv6...",
    "keyName": "my-website",
    "currentCid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
    "lastPublishedAt": 1711123200000,
    "publishCountMonth": 12,
    "status": "active",
    "createdAt": 1711036800000
  }
]

创建 IPNS 密钥

bash

curl -X POST https://api.ipfs.ninja/ipns/keys \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-website"}'

响应 201：

json

{
  "ipnsName": "k51qzi5uqu5dlvj2bv6...",
  "keyName": "my-website",
  "createdAt": 1711036800000
}

发布到 IPNS

发布会更新 IPNS 名称指向新的 CID。这会传播到 IPFS DHT，可能需要最多 60 秒。

bash

curl -X POST https://api.ipfs.ninja/ipns/publish \
  -H "X-Api-Key: bws_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"ipnsName": "k51qzi5uqu5dlvj2bv6...", "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"}'

响应：

json

{
  "ipnsName": "k51qzi5uqu5dlvj2bv6...",
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi",
  "published": true
}

解析 IPNS 名称

查找任何 IPNS 名称的当前 CID。

bash

curl https://api.ipfs.ninja/ipns/resolve/k51qzi5uqu5dlvj2bv6... \
  -H "X-Api-Key: bws_your_api_key_here"

响应：

json

{
  "ipnsName": "k51qzi5uqu5dlvj2bv6...",
  "cid": "bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi"
}

删除 IPNS 密钥

bash

curl -X DELETE https://api.ipfs.ninja/ipns/keys/k51qzi5uqu5dlvj2bv6... \
  -H "X-Api-Key: bws_your_api_key_here"

响应：

json

{ "success": true }

IPNS 工作原理

密钥生成： 创建 IPNS 名称时，会生成一个加密密钥对（Ed25519）。公钥哈希成为您的 IPNS 地址（k51...）。
发布： 发布时，您签署一条记录说"此名称指向 CID X"，并将其广播到 IPFS DHT（分布式哈希表）。
解析： 当有人查找您的 IPNS 名称时，IPFS 节点查询 DHT 获取最新的签名记录并跟随它到 CID。
重新发布： IPNS 记录在 48 小时后过期。IPFS Ninja 每 12 小时自动重新发布您的记录以保持其活跃。
安全性： 只有私钥持有者（您）可以更新 IPNS 名称指向的内容。没有人可以劫持您的名称。

计划限制

计划	IPNS 名称数	每月发布次数
Dharma（免费）	不可用	—
Bodhi（$5/月）	3	100
Nirvana（$29/月）	10	1,000

记录每 12 小时自动重新发布，以在 IPFS 网络上保持活跃。
90 天未发布的名称将被标记为不活跃并停止重新发布。
不活跃的名称可以通过向其发布新 CID 来重新激活。

IPNS — IPFS 的可变名称 ​

为什么使用 IPNS？ ​

常见使用场景 ​

使用仪表盘 ​

1. 创建 IPNS 名称 ​

2. 将 CID 发布到 IPNS 名称 ​

3. 更新内容 ​

4. 解析 IPNS 名称 ​

5. 删除 IPNS 名称 ​

使用 DNSLink 连接域名 ​

如何设置 DNSLink ​

使用 Cloudflare 的 DNSLink ​

使用 Route 53 的 DNSLink ​

使用示例 ​

示例 1：静态网站部署 ​

示例 2：可变 NFT 元数据 ​

示例 3：CI/CD 集成 ​

API 参考 ​

列出 IPNS 密钥 ​

创建 IPNS 密钥 ​

发布到 IPNS ​

解析 IPNS 名称 ​

删除 IPNS 密钥 ​

IPNS 工作原理 ​

计划限制 ​

延伸阅读 ​

IPNS — IPFS 的可变名称

为什么使用 IPNS？

常见使用场景

使用仪表盘

1. 创建 IPNS 名称

2. 将 CID 发布到 IPNS 名称

3. 更新内容

4. 解析 IPNS 名称

5. 删除 IPNS 名称

使用 DNSLink 连接域名

如何设置 DNSLink

使用 Cloudflare 的 DNSLink

使用 Route 53 的 DNSLink

使用示例

示例 1：静态网站部署

示例 2：可变 NFT 元数据

示例 3：CI/CD 集成

API 参考

列出 IPNS 密钥

创建 IPNS 密钥

发布到 IPNS

解析 IPNS 名称

删除 IPNS 密钥

IPNS 工作原理

计划限制

延伸阅读