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
# 确认 PowerShell 可以定位 Kubo 可执行文件
Get-Command ipfs
ipfs version

预期输出示例(安装目录和版本号随实际环境变化):

text
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 的终端执行:

bash
# 安装 Kubo 并检查当前版本
brew install ipfs
ipfs version

预期输出的最后一行类似:

text
ipfs version 0.3x.x

Linux 推荐从官方发行包下载与架构匹配的压缩文件。解压后进入包含安装脚本的 kubo 目录,执行:

bash
# 当前目录应为官方发行包解压得到的 kubo 目录
sudo bash install.sh
ipfs version
command -v ipfs

预期结果为安装脚本成功完成,ipfs version 显示实际版本,command -v ipfs 返回可执行文件路径,通常是 /usr/local/bin/ipfs。安装脚本的具体输出取决于发行版本。

上述三种安装方式任选其一,不需要全部执行。若命令找不到,应先检查可执行文件是否存在、PATH 是否包含安装目录,以及终端是否已重新打开。

初始化节点仓库

安装完成后,ipfs 程序已经存在,但本地仓库通常还未建立。仓库用于保存节点身份、配置、区块数据及相关状态。首次执行 ipfs init 时,Kubo 会创建仓库并生成节点身份。

在终端执行:

bash
# 只在尚未初始化的本地仓库上执行
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 上创建隔离实验仓库:

bash
# 将实验仓库与默认 ~/.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 版本及存储实现有所不同,不能把某个内部子目录当成稳定的应用接口。

Kubo节点仓库的主要组成与配置关系

config 是 JSON 格式的节点配置文件,常用字段包括:

  • Identity.PeerID:当前节点的身份标识。
  • Addresses.Swarm:节点用于建立对等连接的监听地址。
  • Addresses.API:本地 HTTP RPC API 的监听地址。
  • Addresses.Gateway:本地 HTTP 网关的监听地址。
  • Bootstrap:节点用于初始发现网络对等节点的引导地址集合。
  • Datastore:仓库数据存储相关配置。

使用 Kubo 自带命令读取配置,比直接修改 JSON 更安全:

bash
# 分别读取身份、API监听地址和网关监听地址
ipfs config Identity.PeerID
ipfs config Addresses.API
ipfs config Addresses.Gateway

预期输出示例:

text
<ID>
/ip4/127.0.0.1/tcp/5001
/ip4/127.0.0.1/tcp/8080

这里的 <ID> 是实际 Peer ID 的占位符。5001 和 8080 是常见默认端口,若配置经过修改,以实际输出为准。读取配置不要求守护进程已经启动。

启动节点并验证运行状态

初始化只完成了本地仓库准备。要让节点参与网络连接,还需要启动 Kubo 守护进程。

在第一个终端执行:

bash
# 启动节点,保持终端运行
ipfs daemon

预期结果是终端显示节点启动日志,完成初始化后出现:

text
Daemon is ready

不同版本还可能输出 API、Gateway 监听地址及网络连接状态。不要把启动日志中出现的端口或 Peer ID 视为固定值。

保持第一个终端运行,在第二个终端执行:

bash
# 查询本地节点身份与连接状态
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 上可以用以下命令检查仓库环境变量和当前进程:

bash
# 检查是否指定了自定义仓库
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、文件添加和跨节点分发实验所需的基础环境。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

安装 Kubo 并初始化节点仓库

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通