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...
將 Proxy 狀態設為 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 運作原理

方案限制

延伸閱讀