📕 示例 4: 401-Providing 内容提供详解

🎯 学习目标

🗑️ 垃圾回收 (GC) 机制

┌─────────────────────────────────────────┐
│           Blockstore                    │
├─────────────────────────────────────────┤
│  Block A  ◄── 被引用（已固定）            │
│  Block B  ◄── 未被引用 ⚠️ GC 可回收       │
│  Block C  ◄── 被引用（已固定）            │
└─────────────────────────────────────────┘

垃圾回收会删除未被引用的数据块，释放存储空间。

📌 内容固定 (Pinning)

固定 = 标记内容不可被垃圾回收

import { createHelia } from 'helia'

const helia = await createHelia()

// 添加文件
const cid = await fs.addBytes(data)

// 1️⃣ 固定 CID（防止被 GC）
await helia.pins.add(cid)
console.log('Pinned:', cid.toString())

// 2️⃣ 查看固定列表
for await (const pin of helia.pins.ls()) {
  console.log('Pinned CID:', pin.cid.toString())
}

// 3️⃣ 取消固定
await helia.pins.rm(cid)

🏷️ 固定元数据

可以为固定添加自定义元数据：

// 固定并添加元数据
await helia.pins.add(cid, {
  metadata: {
    name: 'important-document.pdf',
    timestamp: Date.now(),
    tags: ['work', 'urgent']
  }
})

// 查看带元数据的固定
for await (const pin of helia.pins.ls()) {
  console.log('CID:', pin.cid.toString())
  console.log('Metadata:', pin.metadata)
}

🌍 DHT 提供 (Providing)

提供 = 向 DHT 宣告你拥有某个 CID，让其他节点可以找到你

// 启动 DHT 服务
import { kadDHT } from '@libp2p/kad-dht'

const libp2p = await createLibp2p({
  // ... 其他配置
  services: {
    dht: kadDHT()
  }
})

const helia = await createHelia({ libp2p })

// 提供 CID 到 DHT
await helia.routing.provide(cid)
console.log('Provided CID to DHT:', cid.toString())

🔄 完整工作流程

import { createHelia } from 'helia'
import { unixfs } from '@helia/unixfs'

// 1. 启动节点
const helia = await createHelia()
const fs = unixfs(helia)

// 2. 添加内容
const data = new TextEncoder().encode('Hello IPFS World!')
const cid = await fs.addBytes(data)
console.log('✅ Added:', cid.toString())

// 3. 固定内容（防止 GC）
await helia.pins.add(cid)
console.log('📌 Pinned')

// 4. 提供到 DHT（让网络发现）
await helia.routing.provide(cid)
console.log('🌍 Provided to DHT')

// 5. 运行垃圾回收（未固定内容将被删除）
await helia.gc()
console.log('🗑️ GC completed')

// 6. 验证内容仍在
const chunks = []
for await (const chunk of fs.cat(cid)) {
  chunks.push(chunk)
}
const retrieved = new TextDecoder().decode(Buffer.concat(chunks))
console.log('✅ Retrieved:', retrieved)

📊 关键概念对比

💡 最佳实践

// ✅ 重要内容：添加 + 固定 + 提供
await fs.addBytes(data)
await helia.pins.add(cid)
await helia.routing.provide(cid)

// ✅ 临时内容：仅添加（依赖 GC 自动清理）
await fs.addBytes(tempData)
// 不固定，下次 GC 自动删除

// ✅ 定期维护
setInterval(async () => {
  await helia.gc()
}, 60 * 60 * 1000) // 每小时运行一次 GC

🚀 运行命令

npm run 401-providing

🎉 恭喜完成 Helia 101！

你现在掌握了：

• ✅ UnixFS 基础操作
• ✅ 持久化存储配置
• ✅ P2P 网络连接
• ✅ 内容固定和提供