P2P 与分布式存储 / 系统课时
安装 Kubo 并初始化节点仓库
安装 Kubo 并初始化节点仓库
要在本机运行 IPFS 节点,需要先安装 Kubo 命令行程序,再初始化用于保存节点身份、配置和数据的仓库。本课以 Kubo 0.3x 系列的常用命令为基础,分别给出 Windows、macOS 和 Linux 的安装方法,并通过版本检查、仓库初始化和配置读取确认环境可用。
学习目标
- 根据操作系统安装 Kubo,并确认
ipfs命令可以执行。 - 使用
ipfs init创建本地节点仓库,识别节点身份与仓库路径。 - 找到仓库配置文件,验证节点可以启动,并处理常见初始化问题。
安装前确认系统与发行包
Kubo 是 IPFS 的 Go 语言实现,提供 ipfs 命令行工具和常驻节点进程。安装时应从官方发布渠道获取对应系统及 CPU 架构的发行包,而不是下载不明来源的可执行文件。
官方入口为 https://docs.ipfs.tech/install/command-line/ ,发行包可从 https://dist.ipfs.tech/kubo/ 获取。选择发行包时注意以下对应关系:
| 操作系统 | 常见架构 | 发行包标识 |
|---|---|---|
| Windows 64 位 | x86-64 | windows-amd64 |
| macOS Intel | x86-64 | darwin-amd64 |
| macOS Apple Silicon | ARM64 | darwin-arm64 |
| Linux x86-64 | x86-64 | linux-amd64 |
| Linux ARM64 | ARM64 | linux-arm64 |
先确认机器架构。Windows 在 PowerShell 中执行 $env:PROCESSOR_ARCHITECTURE,macOS 或 Linux 在终端执行 uname -m。其中 AMD64 或 x86_64 对应 amd64,arm64 或 aarch64 对应 arm64。
安装 Kubo 并检查版本
Windows 可以下载对应的 ZIP 发行包,解压后找到 ipfs.exe。将它放入独立工具目录,例如 C:\Tools\Kubo,再通过系统环境变量 Path 添加该目录。重新打开 PowerShell 后执行:
# 确认 PowerShell 可以定位 Kubo 可执行文件
Get-Command ipfs
ipfs version预期输出示例(安装目录和版本号随实际环境变化):
CommandType Name Version Source
----------- ---- ------- ------
Application ipfs.exe 0.0.0.0 C:\Tools\Kubo\ipfs.exe
ipfs version 0.3x.x这里的 0.3x.x 表示实际安装的版本号,并非要求终端原样显示。Get-Command 的表格列也可能因 PowerShell 版本不同而变化。
macOS 可以使用 Homebrew 安装。在已安装 Homebrew 的终端执行:
# 安装 Kubo 并检查当前版本
brew install ipfs
ipfs version预期输出的最后一行类似:
ipfs version 0.3x.xLinux 推荐从官方发行包下载与架构匹配的压缩文件。解压后进入包含安装脚本的 kubo 目录,执行:
# 当前目录应为官方发行包解压得到的 kubo 目录
sudo bash install.sh
ipfs version
command -v ipfs预期结果为安装脚本成功完成,ipfs version 显示实际版本,command -v ipfs 返回可执行文件路径,通常是 /usr/local/bin/ipfs。安装脚本的具体输出取决于发行版本。
上述三种安装方式任选其一,不需要全部执行。若命令找不到,应先检查可执行文件是否存在、PATH 是否包含安装目录,以及终端是否已重新打开。
初始化节点仓库
安装完成后,ipfs 程序已经存在,但本地仓库通常还未建立。仓库用于保存节点身份、配置、区块数据及相关状态。首次执行 ipfs init 时,Kubo 会创建仓库并生成节点身份。
在终端执行:
# 只在尚未初始化的本地仓库上执行
ipfs init
ipfs config Identity.PeerID
ipfs repo stat预期结果是初始化命令报告仓库已建立,ipfs config Identity.PeerID 输出本机节点的 Peer ID,ipfs repo stat 显示仓库统计信息,包括仓库大小及对象数量等。Peer ID 是动态值,可记为 <ID>;仓库统计值会随内容变化,不应要求与示例机器完全相同。
默认仓库位置如下:
| 系统 | 默认仓库目录 |
|---|---|
| Windows | %USERPROFILE%\.ipfs |
| macOS | ~/.ipfs |
| Linux | ~/.ipfs |
仓库路径也可以通过 IPFS_PATH 环境变量指定。这个变量应在执行 ipfs init 之前设置,后续命令也必须使用同一个值,否则可能操作另一个仓库。
例如在 Linux 或 macOS 上创建隔离实验仓库:
# 将实验仓库与默认 ~/.ipfs 分开
export IPFS_PATH="$HOME/ipfs-lab"
ipfs init
ipfs config Identity.PeerID预期结果为 $HOME/ipfs-lab 下出现仓库文件,命令返回新生成的 Peer ID。该目录不应预先包含另一套已初始化仓库。Windows PowerShell 中可以使用 $env:IPFS_PATH = "$HOME\ipfs-lab" 设置当前会话的仓库路径。
识别仓库文件与配置位置
初始化完成后,重点检查仓库根目录中的 config、datastore、blocks、keystore 和 version 等内容。实际文件布局可能随 Kubo 版本及存储实现有所不同,不能把某个内部子目录当成稳定的应用接口。

config 是 JSON 格式的节点配置文件,常用字段包括:
Identity.PeerID:当前节点的身份标识。Addresses.Swarm:节点用于建立对等连接的监听地址。Addresses.API:本地 HTTP RPC API 的监听地址。Addresses.Gateway:本地 HTTP 网关的监听地址。Bootstrap:节点用于初始发现网络对等节点的引导地址集合。Datastore:仓库数据存储相关配置。
使用 Kubo 自带命令读取配置,比直接修改 JSON 更安全:
# 分别读取身份、API监听地址和网关监听地址
ipfs config Identity.PeerID
ipfs config Addresses.API
ipfs config Addresses.Gateway预期输出示例:
<ID>
/ip4/127.0.0.1/tcp/5001
/ip4/127.0.0.1/tcp/8080这里的 <ID> 是实际 Peer ID 的占位符。5001 和 8080 是常见默认端口,若配置经过修改,以实际输出为准。读取配置不要求守护进程已经启动。
启动节点并验证运行状态
初始化只完成了本地仓库准备。要让节点参与网络连接,还需要启动 Kubo 守护进程。
在第一个终端执行:
# 启动节点,保持终端运行
ipfs daemon预期结果是终端显示节点启动日志,完成初始化后出现:
Daemon is ready不同版本还可能输出 API、Gateway 监听地址及网络连接状态。不要把启动日志中出现的端口或 Peer ID 视为固定值。
保持第一个终端运行,在第二个终端执行:
# 查询本地节点身份与连接状态
ipfs id
ipfs swarm peers预期结果为 ipfs id 返回包含 ID、PublicKey、Addresses、AgentVersion 和 ProtocolVersion 等信息的 JSON 对象;ipfs swarm peers 在已有连接时输出 Peer 多地址,每行一个。刚启动或网络受限时,Peer 列表可能为空,这不代表仓库初始化失败。
若第一个终端能够显示 Daemon is ready,第二个终端的 ipfs id 能成功返回本机身份,即可确认 Kubo 安装、仓库初始化与本地 RPC 通信已经跑通。停止实验时,在运行 ipfs daemon 的终端按 Ctrl+C 正常退出。
处理常见安装与仓库问题
遇到失败时,按命令发现、仓库状态、进程监听三个层次定位,不要直接删除仓库。
| 现象 | 可能原因 | 处理方法 |
|---|---|---|
ipfs: command not found |
PATH 未包含安装目录 | 检查安装位置,更新 PATH 后重新打开终端 |
ipfs init 提示仓库已初始化 |
已存在有效仓库 | 不重复初始化,使用 ipfs config Identity.PeerID 检查身份 |
ipfs daemon 提示端口被占用 |
API、Gateway 或 Swarm 监听端口冲突 | 检查已有 Kubo 进程及 Addresses 配置 |
| 配置读取结果与预期不同 | 当前终端使用了不同的 IPFS_PATH |
核对环境变量及仓库目录 |
| 节点启动但没有远端 Peer | 网络、防火墙或引导节点连接受限 | 先确认本地 API 可用,再检查网络连接 |
在 Linux 或 macOS 上可以用以下命令检查仓库环境变量和当前进程:
# 检查是否指定了自定义仓库
printf 'IPFS_PATH=%s\n' "${IPFS_PATH:-<未设置>}"
# 检查本机是否存在 Kubo 守护进程
pgrep -af 'ipfs daemon' || true预期结果:第一行显示当前仓库变量值或 <未设置>;第二条命令在守护进程运行时显示匹配的进程信息,没有匹配进程时不输出内容。部分 macOS 系统的 pgrep 不支持 -a,可改用 ps aux | grep '[i]pfs daemon' 检查。
最终验收只需确认四件事:ipfs version 能返回版本、仓库配置可读取、Peer ID 已生成、ipfs daemon 能正常启动并接受 ipfs id 查询。完成这些检查后,本地 Kubo 节点就具备后续 CID、文件添加和跨节点分发实验所需的基础环境。