2、IPFS环境搭建：在Linux/Mac/Windows上安装IPFS、初始化IPFS节点、启动IPFS守护进程、查看节点信息

好，咱们正式开始动手了。这一章我带你把IPFS跑起来。说实话，很多新手在环境搭建这一步就被劝退了——不是装不上，就是装上了不知道咋验证。别担心，我踩过的坑，你一个都不用再踩。

2.1 下载与安装：三平台全覆盖

IPFS官方提供了预编译的二进制包，支持Linux、macOS和Windows。我个人习惯用命令行安装，干净利落。你想想看，一个分布式存储网络，第一步就是下载一个不到50MB的小程序，是不是挺有意思？

Linux（以Ubuntu 20.04+为例）

# 下载最新版（建议先访问 https://dist.ipfs.tech 查看最新版本号）
wget https://dist.ipfs.tech/kubo/v0.27.0/kubo_v0.27.0_linux-amd64.tar.gz

# 解压
tar -xvzf kubo_v0.27.0_linux-amd64.tar.gz

# 进入目录
cd kubo

# 执行安装脚本
sudo bash install.sh

# 验证安装
ipfs --version

嗯，这里要注意：kubo是IPFS的Go语言实现，以前叫go-ipfs，2023年改名了。我在项目中遇到过有人下载了旧版go-ipfs，结果跟新版节点连不上——版本兼容性问题，很坑。

macOS（两种方式）

如果你用Homebrew，一行命令搞定：

brew install ipfs

如果你不用Homebrew，或者想控制版本，手动下载也行：

# 下载macOS版
wget https://dist.ipfs.tech/kubo/v0.27.0/kubo_v0.27.0_darwin-amd64.tar.gz

# 解压并安装
tar -xvzf kubo_v0.27.0_darwin-amd64.tar.gz
cd kubo
sudo bash install.sh

我建议用Homebrew，因为后续升级方便。不过有一次我在M1芯片的Mac上装，发现brew install默认装的是x86版，得加个--arm64参数才行。Apple Silicon用户注意一下。

Windows

Windows用户有两个选择：

  1. 下载exe安装包：去 https://dist.ipfs.tech 下载windows-amd64.zip，解压后把ipfs.exe放到C:\Windows\System32或添加到PATH。
  2. 用PowerShell脚本：
# 以管理员身份运行PowerShell
Invoke-WebRequest -Uri https://dist.ipfs.tech/kubo/v0.27.0/kubo_v0.27.0_windows-amd64.zip -OutFile ipfs.zip
Expand-Archive -Path ipfs.zip -DestinationPath C:\ipfs
# 手动将 C:\ipfs\kubo 添加到系统环境变量PATH
⚠️ 避坑指南：Windows上安装后，如果命令行输入ipfs提示找不到命令，八成是PATH没配好。我曾经帮一个学员远程调试，搞了半小时才发现他解压后直接双击了ipfs.exe——那玩意儿是命令行工具，不是GUI程序！

2.2 初始化IPFS节点

装好了？好，接下来初始化。这一步会在你的机器上创建一个IPFS仓库，说白了就是本地存储数据的文件夹。

ipfs init

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

initializing IPFS node at /home/yourname/.ipfs
generating 2048-bit RSA keypair...done
peer identity: 12D3KooW...（一串哈希）
to get started, enter:

    ipfs cat /ipfs/Qm...（欢迎文件的哈希）

这里有几个关键信息：

  • 仓库路径：默认在~/.ipfs，里面存了你的私钥、配置文件、本地数据块。
  • Peer ID：你的节点身份证，全网唯一。后面跟其他节点通信就靠它。
  • 欢迎文件：IPFS网络上的第一个文件，你可以用ipfs cat查看。

为什么会生成密钥对？因为IPFS节点之间通信需要加密和身份验证。说白了，你的节点就是网络中的一个对等体，没有身份证明，别人凭什么信任你？

💡 我的习惯：初始化后，我通常会先备份~/.ipfs/config文件。有一次我不小心改了配置导致节点启动失败，还好有备份，直接恢复就完事了。

2.3 启动IPFS守护进程

初始化只是准备工作，真正让节点跑起来需要启动守护进程：

ipfs daemon

你会看到日志刷刷地滚：

Initializing daemon...
Swarm listening on /ip4/127.0.0.1/tcp/4001
Swarm listening on /ip4/192.168.1.100/tcp/4001
Swarm listening on /ip6/::1/tcp/4001
API server listening on /ip4/127.0.0.1/tcp/5001
WebUI: http://127.0.0.1:5001/webui
Gateway (readonly) server listening on /ip4/127.0.0.1/tcp/8080
Daemon is ready

看到Daemon is ready就说明成功了。这个进程会一直运行，监听几个端口：

端口 用途 说明
4001 Swarm P2P通信端口，跟其他节点交换数据
5001 API 本地API，供ipfs命令调用
8080 Gateway HTTP网关，浏览器可以直接访问IPFS内容

嗯，这里有个细节：如果你在云服务器上跑，记得在防火墙开放4001端口，否则其他节点连不上你。我刚开始做IPFS应用时，部署到阿里云上发现节点一直处于"半离线"状态，查了半天才发现安全组没放行4001端口。

⚠️ 注意：守护进程默认是前台运行的。如果你想让它后台运行，可以加--daemon参数或者用nohup、screen、systemd等方式管理。我个人推荐用systemd，开机自启最稳。

2.4 查看节点信息

守护进程跑起来了，怎么确认它正常工作？几个常用命令：

查看节点ID

ipfs id

输出示例：

{
  "ID": "12D3KooW...",
  "PublicKey": "...",
  "Addresses": [
    "/ip4/127.0.0.1/tcp/4001/p2p/12D3KooW...",
    "/ip4/192.168.1.100/tcp/4001/p2p/12D3KooW..."
  ],
  "AgentVersion": "kubo/0.27.0/...",
  "ProtocolVersion": "ipfs/0.1.0"
}

这里能看到你的公钥、监听地址、软件版本。如果Addresses里只有127.0.0.1，说明你的节点只能本地访问，外网连不上——检查一下网络配置。

查看连接的对等节点

ipfs swarm peers

刚启动时可能只有几个默认节点，过一会儿会多起来。如果一直是0个，说明网络有问题。我曾经在公司的内网环境里测试，发现一个节点都连不上——因为公司防火墙把4001端口封了。后来我用了ipfs config --json Swarm.EnableRelayHop true开启中继模式才解决。

查看仓库统计

ipfs repo stat

输出：

NumObjects: 12
RepoSize: 45678
StorageMax: 10000000000
RepoPath: /home/yourname/.ipfs
Version: fs-repo@11

这个命令告诉你本地存了多少数据块、总大小、存储上限。默认上限是10GB，如果你要存大量数据，记得调大：

ipfs config --json Datastore.StorageMax '"100GB"'

查看节点带宽

ipfs stats bw

这个命令实时显示上下行速率。如果你发现上传速度很慢，可能是NAT穿透没做好。嗯，这个话题后面讲网络配置时会细说。

📌 快速验证节点是否正常

打开浏览器，访问 http://127.0.0.1:5001/webui，你会看到一个漂亮的Web界面。如果能看到节点ID、连接数、带宽等信息，说明一切正常。这个WebUI是IPFS自带的，不用额外安装。

2.5 常见问题与排错

我整理了几个新手最容易遇到的问题：

问题 原因 解决方法
ipfs: command not found 没添加到PATH 检查安装路径，手动添加到环境变量
Error: lock /home/xxx/.ipfs/repo.lock 另一个IPFS进程在运行 killall ipfs 或重启终端
Error: failed to open IPFS repo 仓库损坏或权限问题 检查~/.ipfs权限，或重新ipfs init
WebUI打不开 API端口被占用或没启动 检查5001端口是否被其他程序占用

我曾经遇到过最诡异的问题：在macOS上ipfs daemon启动后，过几分钟就自动退出。查了半天，发现是系统自带的launchd在作怪——它把IPFS当成了需要管理的服务，自动重启导致冲突。最后我用launchctl unload禁用了相关配置才解决。

好了，环境搭好了，节点也跑起来了。下一章我们开始往IPFS里存文件——那才是真正好玩的部分。

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