3、IPFS基础操作：添加文件到IPFS、查看文件内容、从IPFS下载文件、固定文件（Pin）、垃圾回收机制

好，咱们正式开始动手操作IPFS。说实话，很多教程一上来就讲架构讲原理，我反而觉得先跑通几个命令，你心里才有底。这一节我们聚焦五个最核心的操作：添加文件、查看内容、下载文件、固定文件，以及垃圾回收。这些命令你以后每天都会用，所以值得花点时间吃透。

3.1 添加文件到IPFS：你的第一个CID

先启动你的IPFS节点，确保守护进程在跑着。然后随便找个文本文件，比如一个叫 hello.txt 的文件，里面写上一句话：

echo "Hello, IPFS World!" > hello.txt

接下来，用 ipfs add 命令把它加进去：

ipfs add hello.txt

你会看到类似这样的输出：

added QmWATWQ7fVPP2HRGu6Dk6c2iBcGjY6J6J6J6J6J6J6J6J hello.txt

这个长长的字符串就是 CID（内容标识符）。它本质上是你文件内容的哈希值。注意，哪怕你只改了一个标点符号，CID都会完全不一样。我在项目中遇到过有人把两个不同版本的文件搞混了，就是因为没意识到CID是内容敏感的。

💡 我的习惯：每次添加文件后，我都会把CID复制到一个临时笔记里。因为后续所有操作都依赖这个CID，丢了就得重新添加。

你也可以一次添加整个目录：

ipfs add -r my_folder/

加上 -r 参数，IPFS会递归添加目录下的所有文件。输出会列出每个文件的CID，最后还会有一个目录本身的CID。

3.2 查看文件内容：验证你的数据

文件加进去了，怎么确认它真的存好了？用 ipfs cat：

ipfs cat QmWATWQ7fVPP2HRGu6Dk6c2iBcGjY6J6J6J6J6J6J6J6J

终端会直接打印出文件内容：

Hello, IPFS World!

嗯，这就对了。你想想看，这个命令其实是在告诉IPFS节点：「嘿，帮我把这个CID对应的数据块取回来，然后原样输出。」它不关心文件存在本地还是远端，节点会自动去网络里找。

如果文件比较大，你只想看开头几行，可以用 ipfs cat 配合管道：

ipfs cat QmYourCID | head -n 10

我曾经调试一个日志文件时，就用这招快速检查了文件头部，省得把整个大文件拖下来。

3.3 从IPFS下载文件：把数据拿回本地

下载文件其实和查看内容很像，只不过我们要把输出重定向到本地文件：

ipfs cat QmWATWQ7fVPP2HRGu6Dk6c2iBcGjY6J6J6J6J6J6J6J6J > downloaded_hello.txt

或者用更专业的 ipfs get 命令：

ipfs get QmWATWQ7fVPP2HRGu6Dk6c2iBcGjY6J6J6J6J6J6J6J6J -o ./my_downloaded_file.txt

-o 参数指定输出路径。如果不加，默认会以CID命名文件。我个人更推荐用 ipfs get，因为它会保留文件的原名和目录结构（如果你下载的是目录的话）。

⚠️ 注意：下载速度取决于网络状况和数据的分布情况。如果数据只在你自己的节点上，那下载就是本地读取，速度很快。但如果数据在远端节点，就需要通过DHT（分布式哈希表）寻址，可能会慢一些。

3.4 固定文件（Pin）：防止数据被清理

这里有个关键概念要讲清楚。IPFS节点有一个本地存储缓存，叫「块存储」（blockstore）。默认情况下，节点只会缓存它最近访问过的数据。如果缓存满了，旧数据可能会被清理掉——这就是垃圾回收机制要干的事。

那怎么保证你的重要数据不被清理？答案是 固定（Pin）。

固定就是告诉节点：「这些数据我很看重，别动它们。」

固定一个文件：

ipfs pin add QmWATWQ7fVPP2HRGu6Dk6c2iBcGjY6J6J6J6J6J6J6J6J

查看当前所有固定的内容：

ipfs pin ls

输出会列出所有被固定的CID，以及它们的固定类型。常见的有两种：

固定类型 说明
recursive 递归固定，会固定该CID及其所有子对象（比如整个目录）
direct 只固定该CID本身，不固定其引用的子对象

取消固定：

ipfs pin rm QmWATWQ7fVPP2HRGu6Dk6c2iBcGjY6J6J6J6J6J6J6J6J
💡 避坑指南：我曾经有一次忘了固定一个重要的配置文件，结果跑完垃圾回收后，那个文件就丢了。虽然理论上可以从其他节点重新获取，但如果全网只有你这一份副本，那就真的找不回来了。所以，重要数据一定要固定。

3.5 垃圾回收机制：清理无用数据

垃圾回收（Garbage Collection，简称GC）是IPFS节点定期清理未固定数据的机制。说白了，就是帮你腾空间。

手动触发垃圾回收：

ipfs repo gc

你会看到类似这样的输出：

removed QmSomeOldData1
removed QmSomeOldData2
...

每个 removed 行代表一个被清理的数据块。这些数据块都是没有被任何固定引用的。

IPFS节点也会自动执行GC，频率取决于配置。你可以通过以下命令查看当前GC设置：

ipfs config show | grep -A 5 "GC"

常见的配置项包括：

配置项 说明
Datastore.GCPeriod 自动GC的间隔时间，默认1小时
Datastore.StorageMax 节点存储上限，默认10GB

你可以手动调整这些值。比如，把GC周期改成2小时：

ipfs config Datastore.GCPeriod "2h"
⚠️ 重要提醒：垃圾回收是不可逆的。一旦数据被清理，如果你没有在其他地方备份，那就真的没了。所以，在运行 ipfs repo gc 之前，务必确认所有重要数据都已经固定。

3.6 实战小练习：完整流程

来，咱们走一遍完整的流程，加深印象：

  1. 创建一个文件 test.txt，内容随意。
  2. 用 ipfs add 添加它，记下CID。
  3. 用 ipfs cat 验证内容。
  4. 用 ipfs get 下载到另一个文件名。
  5. 用 ipfs pin add 固定它。
  6. 用 ipfs pin ls 确认固定成功。
  7. 手动运行 ipfs repo gc，观察输出。
  8. 再次用 ipfs cat 访问文件，确认它还在（因为被固定了）。

做完这八步，你就掌握了IPFS最核心的日常操作。说实话，这些命令我每天都要用好几遍，已经形成肌肉记忆了。你多用几次，也会一样的。

下一节，我们会深入IPFS的底层数据结构——Merkle DAG。理解了它，你才能真正明白CID是怎么算出来的，以及为什么IPFS能做到内容寻址。准备好了吗？

← 上一章 📖 返回目录 下一章 →