4、IPFS节点搭建：本地IPFS节点安装、初始化、启动与基本命令操作
好，咱们进入实操环节。前面聊了那么多IPFS的理论，说白了，你得亲手搭一个节点，才能真正理解它怎么工作。我个人习惯在本地先跑通，再去折腾服务器部署。这样调试起来方便，出了问题也容易定位。
4.1 安装IPFS：选对版本，少踩坑
IPFS的安装其实不复杂，但版本选择上我吃过亏。早期版本有些API不兼容，后来官方统一了。现在推荐用 go-ipfs 的稳定版，别追最新版，除非你想当小白鼠。
根据你的操作系统，下载对应的二进制包：
- Linux/macOS：下载 .tar.gz 压缩包
- Windows：下载 .exe 安装程序或解压版
我个人习惯用Linux做开发机，所以下面以Ubuntu为例。你如果是Windows用户，操作逻辑完全一样，只是路径写法不同。
安装步骤（Linux/macOS）：
# 下载最新稳定版（以v0.21.0为例，实际请去官网查最新）
wget https://dist.ipfs.tech/kubo/v0.21.0/kubo_v0.21.0_linux-amd64.tar.gz
# 解压
tar -xvzf kubo_v0.21.0_linux-amd64.tar.gz
# 进入目录
cd kubo
# 执行安装脚本
sudo bash install.sh
# 验证安装
ipfs --version看到输出版本号，就说明装好了。嗯，这里要注意：install.sh 会把 ipfs 命令复制到 /usr/local/bin，所以全局都能用。如果你不想用sudo，也可以手动把二进制文件放到自己的 ~/bin 目录下。
小技巧： 我建议装完后立刻运行 ipfs update 检查一下是否有安全更新。曾经有个版本有漏洞，我就是靠这个命令及时发现的。
4.2 初始化节点：创建你的身份ID
安装完别急着用，得先初始化。这一步会生成节点的密钥对和配置文件。
ipfs init执行后，你会看到类似这样的输出：
initializing IPFS node at /home/yourname/.ipfs
generating 2048-bit RSA keypair...done
peer identity: 12D3KooW...（一串哈希值）这个 peer identity 就是你的节点ID，全网唯一。说白了，这就是你在IPFS网络里的身份证。我在项目中遇到过一个问题：如果你在多台机器上初始化，每个节点ID都不同，文件同步时得互相添加对端地址才行。
初始化干了三件事：
- 创建了
~/.ipfs目录（默认存储路径） - 生成了RSA密钥对（用于身份验证）
- 写入了默认配置文件
config
警告： 千万别把 ~/.ipfs 目录里的私钥泄露出去！如果有人拿到你的私钥，就能冒充你的节点。我曾经有个同事不小心把整个目录上传到了GitHub...嗯，后来他花了一整天重新生成密钥并通知所有对端节点。
4.3 启动节点：让IPFS跑起来
初始化完成后，启动节点就一行命令：
ipfs daemon你会看到一堆日志刷屏，包括：
- Swarm listening on /ip4/...（监听地址）
- API server listening on /ip4/127.0.0.1/tcp/5001（API端口）
- Gateway (readonly) server on /ip4/127.0.0.1/tcp/8080（网关端口）
这里有个坑：默认情况下，API和网关只监听本地地址。如果你想让其他机器访问你的节点，得修改配置文件。但作为开发环境，保持默认就好。
启动后，你可以打开浏览器访问 http://localhost:5001/webui，会看到一个Web界面。不过我个人更喜欢命令行，效率高得多。
后台运行： 如果你不想一直开着终端，可以用 nohup ipfs daemon > ipfs.log 2>&1 & 或者用 screen / tmux 管理。我习惯用tmux，方便随时切回来看日志。
4.4 基本命令操作：增、查、存
节点跑起来后，我们来玩几个核心命令。这三个命令你以后天天都会用：ipfs add、ipfs cat、ipfs pin。
4.4.1 ipfs add：上传文件到IPFS
把文件添加到IPFS网络，说白了就是计算哈希并存储到本地节点。
# 添加一个文本文件
echo "Hello, IPFS!" > hello.txt
ipfs add hello.txt
# 输出示例：
# added QmX...（哈希值） hello.txt返回的哈希值就是内容的唯一标识。你想想看，哪怕你只改了一个字符，哈希值都会变。这就是内容寻址的魅力。
添加目录也支持：
ipfs add -r myfolder/这里有个参数 --cid-version=1，我建议加上。CIDv1比默认的CIDv0更短，而且兼容性更好。我在做NFT元数据存储时，就强制要求用CIDv1，因为有些区块链平台只认这个格式。
实战经验： 添加大文件时，加上 --progress 参数能看到进度条。我曾经上传一个500MB的3D模型文件，没加这个参数，还以为卡死了。
4.4.2 ipfs cat：读取文件内容
有了哈希值，怎么把内容读回来？用 ipfs cat：
ipfs cat QmX...（刚才的哈希值）你会看到输出 Hello, IPFS!。这个命令的原理是：根据哈希找到本地存储的内容，如果本地没有，就从网络上的其他节点拉取。
注意：ipfs cat 只能读取文件，不能读取目录。要列出目录内容，得用 ipfs ls：
ipfs ls QmY...（目录的哈希值）它会显示目录下所有文件和子目录的哈希值及大小。
注意： 如果你关掉了 ipfs daemon，ipfs cat 会报错。因为节点没运行，没法从网络获取数据。我曾经调试了半天，结果发现是忘了启动daemon...这种低级错误，谁还没犯过呢？
4.4.3 ipfs pin：固定数据，防止被清理
这是IPFS里非常重要的概念。默认情况下，IPFS节点会定期清理未使用的缓存数据（GC机制）。如果你想让某个文件永久保留在本地节点，就得把它 固定（pin） 起来。
# 固定一个文件
ipfs pin add QmX...（哈希值）
# 查看已固定的内容
ipfs pin ls
# 取消固定
ipfs pin rm QmX...固定分为几种类型：
- direct：直接固定单个文件
- recursive：递归固定整个目录（包括子文件）
- indirect：间接固定（被其他固定项引用）
我举个例子：你上传了一个NFT的元数据JSON文件，如果不固定它，下次GC运行时可能就被删了。那你的NFT就变成「空投」了——只有哈希，没有内容。这在NFT圈里可是大忌！
最佳实践： 对于NFT元数据，我建议用 ipfs pin add --recursive 固定整个目录。这样目录里的图片、JSON文件都会被保留。另外，可以搭配 ipfs pin remote 把固定操作委托给远程固定服务（比如Pinata），防止本地节点宕机后数据丢失。
4.5 常用命令速查表
| 命令 | 作用 | 常用参数 |
|---|---|---|
ipfs init |
初始化节点 | --profile server（服务器优化） |
ipfs daemon |
启动节点 | --migrate（自动迁移仓库） |
ipfs add |
添加文件 | -r（递归）、--cid-version=1 |
ipfs cat |
读取文件 | 无特殊参数 |
ipfs ls |
列出目录 | -v（显示详细信息） |
ipfs pin add |
固定数据 | --recursive（递归固定） |
ipfs pin ls |
查看固定列表 | --type=all（显示所有类型） |
ipfs pin rm |
取消固定 | -r（递归取消） |
4.6 避坑指南
最后分享几个我踩过的坑：
- 端口冲突：如果5001或8080端口被占用，daemon会启动失败。用
lsof -i :5001查一下谁在用，或者修改配置文件里的端口号。 - 磁盘空间：IPFS默认存储上限是10GB。如果你要存大量NFT数据，记得修改
Datastore.StorageMax配置项。我曾经没改，结果节点突然拒绝新数据，排查了半天。 - 跨网络访问：如果你在云服务器上跑节点，记得开放4001端口（Swarm端口），否则其他节点连不上你。
- 版本兼容：不同版本的IPFS节点之间通信可能有问题。我建议团队内部统一版本，避免出现「你的节点能连上，我的不行」这种玄学问题。
好了，本地节点搭建就这些内容。说白了，就是装、初始化、启动、然后玩转那三个核心命令。下一节我们会聊如何把IPFS集成到NFT的铸造流程中，到时候这些命令都会派上用场。