P2P 与分布式存储 / 系统课时
执行垃圾回收并检查仓库占用
执行垃圾回收并检查仓库占用
本课通过一组可重复的 Kubo 本地仓库实验,检查 IPFS 数据块占用、执行垃圾回收,并验证普通缓存块、Pin 保护的数据与 MFS 引用的数据为何具有不同的回收结果。完成后,你可以判断哪些块能够安全清理,以及如何避免误删仍需保留的内容。
学习目标
- 使用
ipfs repo stat查看仓库占用,并理解统计字段的含义。 - 执行
ipfs repo gc,验证 Pin、MFS 引用与垃圾回收的关系。 - 根据仓库容量、引用关系和回收结果制定安全的清理策略。
检查仓库占用与回收前提
实验使用已安装的 Kubo CLI,并假设本地仓库已初始化。先启动守护进程,保持该终端运行;以下命令在另一个终端执行。
ipfs daemon预期结果:启动成功后出现包含 Daemon is ready 的提示,具体监听地址与启动日志随环境变化。
先确认节点身份,再读取仓库统计信息。
ipfs id -f='<id>\n'
ipfs repo stat预期输出示例(实际 Peer ID 和统计值不同):
12D3KooW<...>
NumObjects: 120
RepoSize: 245760
StorageMax: 10000000000
RepoPath: <PATH>
Version: 16这里的 <PATH> 代表实际仓库路径,<...> 代表省略的 Peer ID 内容。Version 是仓库格式版本,不是 Kubo 程序版本;以上数字仅用于说明字段,不能视为所有版本的固定输出。
| 字段 | 含义 | 检查用途 |
|---|---|---|
NumObjects |
仓库中存储的数据块对象数量 | 比较回收前后的对象变化 |
RepoSize |
仓库报告的存储占用,单位为字节 | 观察回收是否释放空间 |
StorageMax |
仓库配置的存储上限,单位为字节 | 判断容量压力 |
RepoPath |
本地仓库目录 | 确认正在操作的仓库 |
Version |
仓库格式版本 | 排查仓库兼容性问题 |
RepoSize 不等同于文件管理器显示的整个仓库目录大小。数据库索引、元数据、文件系统分配方式及后端实现都可能使两者不同;它也不等同于用户导入文件的原始字节总量。
建立可回收与受保护的数据样本
Kubo 的垃圾回收以块的可达性为依据。显式 Pin 的根及其递归引用的块需要保留;MFS 文件系统中的内容也通过其根引用受到保护。仅仅通过 CID 读取过某个块,并不代表它会永久保留。
为了观察差异,准备三个内容不同的小文件:temporary.txt、pinned.txt 和 mfs.txt。以下使用 Bash,适用于 Linux、macOS 或具有 Bash 环境的 Windows。
printf 'temporary-cache-sample\n' > temporary.txt
printf 'protected-pin-sample\n' > pinned.txt
printf 'protected-mfs-sample\n' > mfs.txt
# --pin=false 避免导入时自动创建递归 Pin
TEMP_CID=$(ipfs add -Q --pin=false temporary.txt)
PIN_CID=$(ipfs add -Q --pin=false pinned.txt)
MFS_CID=$(ipfs add -Q --pin=false mfs.txt)
ipfs pin add "$PIN_CID"
ipfs files mkdir -p /gc-lab
ipfs files cp "/ipfs/$MFS_CID" /gc-lab/mfs.txt
printf 'TEMP_CID=%s\nPIN_CID=%s\nMFS_CID=%s\n' "$TEMP_CID" "$PIN_CID" "$MFS_CID"
ipfs pin ls "$PIN_CID" --type=recursive
ipfs files ls /gc-lab预期结果:打印三个实际生成的 CID;pin ls 返回被显式递归 Pin 的 CID 及其类型;MFS 列表包含 mfs.txt。CID 取决于文件内容和导入参数,不能预先写死。
三个样本的预期状态如下:
| 样本 | 保留关系 | 垃圾回收预期 |
|---|---|---|
| temporary.txt | 未显式 Pin,也未加入 MFS | 对应未被其他根引用的块可回收 |
| pinned.txt | 显式递归 Pin | 保留 |
| mfs.txt | 被 MFS 路径引用 | 保留 |

注意,实验成立的前提是这些块没有被其他 Pin、MFS 路径或系统保留根引用。对于更复杂的 UnixFS 文件,一个根 CID 可能关联多个数据块,垃圾回收的单位是块,而不是文件名。
执行垃圾回收并验证结果
在执行回收前记录仓库状态,然后调用 ipfs repo gc。此操作会遍历需要保留的引用关系,并尝试删除其余可回收块。
ipfs repo stat
ipfs repo gc
ipfs repo stat预期结果:垃圾回收可能打印一条或多条 removed <CID>,其中 <CID> 是实际被移除块的标识;若没有可回收块,则不会出现相应移除记录。回收后的 NumObjects 通常减少,RepoSize 可能下降,但不保证与文件原始大小一一对应。
随后使用只查询本地块存储的 ipfs block stat 检查样本根块,避免普通内容读取命令从网络重新下载已删除的数据。
# 临时样本的根块应已被回收
if ipfs block stat "$TEMP_CID" >/dev/null 2>&1; then
echo 'TEMP: still local'
else
echo 'TEMP: not local'
fi
# 显式Pin和MFS引用的根块应仍在本地
ipfs block stat "$PIN_CID"
ipfs block stat "$MFS_CID"
ipfs files read /gc-lab/mfs.txt预期输出示例:
TEMP: not local
Key: <CID>
Size: <BYTES>
Key: <CID>
Size: <BYTES>
protected-mfs-sample其中 <CID>、<BYTES> 为实际值。若临时块仍在本地,应检查是否存在其他保留引用,而不是直接判定垃圾回收失效。
解除引用并观察再次回收
只有在不再需要这些测试数据时,才解除显式 Pin 和 MFS 路径引用。移除 MFS 文件并不会立即删除它对应的所有块,解除 Pin 也不会立即释放空间;两者都只是使原本受保护的数据有机会成为垃圾回收候选。
ipfs pin rm "$PIN_CID"
ipfs files rm /gc-lab/mfs.txt
ipfs repo gc
ipfs repo stat预期结果:Pin 移除操作确认对应 CID 已解除固定;MFS 文件路径被移除;第二次垃圾回收可删除不再被其他保留根引用的块,仓库对象数量可能进一步下降。
如果第二次回收后对象数量没有变化,依次检查:
- 使用
ipfs pin ls --type=recursive查看是否存在其他递归 Pin 根。 - 使用
ipfs files ls /检查 MFS 中是否仍有相关文件或目录引用。 - 检查是否有其他导入、读取或后台任务重新写入了相同内容。
- 确认命令操作的是同一个
RepoPath,并检查ipfs repo gc是否报告错误。

制定仓库容量管理策略
StorageMax 是 Kubo 仓库存储上限配置。可以通过以下命令检查当前配置以及仓库使用情况。
ipfs config Datastore.StorageMax
ipfs repo stat预期结果:第一条命令返回容量配置值,例如 10GB;第二条命令返回包含 RepoSize 与 StorageMax 的统计信息。实际配置和统计值以当前节点为准。
假设 StorageMax 为 10 GB,当前 RepoSize 为 8 GB,回收后降为 6.5 GB,则按这两个统计字段估算,仓库使用比例由 80% 降为 65%,释放约 1.5 GB 的统计占用。该比例用于容量观察,不保证操作系统磁盘可用空间同步增加相同字节数。
实际运维可以采用以下检查策略:
- 每日记录
RepoSize、NumObjects与磁盘剩余容量,比较增长趋势。 - 当仓库使用比例超过内部预警阈值(例如 80%)时,先检查 Pin 与 MFS 引用,再安排回收。
- 对必须长期保存的数据使用明确的递归 Pin 或 MFS 管理,并保留其他节点或独立存储中的副本。
- 在业务低峰期执行垃圾回收,避免与大量数据写入和读取竞争资源。
通过两次垃圾回收实验可以确认:数据块是否被清理取决于它是否仍可从受保护的根引用到达,而不是它曾经是否被导入、读取或拥有文件名。容量管理应先确认引用关系,再执行回收,并以仓库统计与本地块检查共同验证结果。