P2P 与分布式存储 / 系统课时
启动节点并确认对等连接
启动节点并确认对等连接
本课使用 Kubo 命令行启动一个本地 IPFS 节点,依次检查守护进程、Peer ID、监听地址和实际对等连接。完成后,你将能够判断节点只是本地运行正常,还是已经连接到公共 IPFS 网络,并能定位没有 Peer 时最常见的启动与网络问题。
学习目标
- 使用
ipfs daemon启动节点,并通过命令验证 API 可用性。 - 区分 Peer ID、监听地址、公告地址和已连接 Peer 的含义。
- 根据连接数量、连接地址及网络测试结果判断节点是否成功接入公共网络。
启动前确认节点已经初始化
以下操作适用于安装了 Kubo 的常见桌面或服务器环境。示例使用 Kubo CLI 的稳定命令,不依赖图形界面。请先打开终端,检查安装版本和仓库状态。
ipfs version
ipfs config Identity.PeerID预期结果:第一条命令显示已安装的 Kubo 版本,第二条命令返回当前仓库的 Peer ID。例如:
ipfs version 0.x.y
12D3KooW...这里的版本号和 Peer ID 仅表示输出格式,实际值取决于安装版本与节点身份。Peer ID 是节点的标识符,不是文件 CID,也不是节点的公网 IP 地址。
如果第二条命令提示仓库尚未初始化,并且当前环境确实是新建节点,可以执行:
ipfs init预期结果:命令创建本地 IPFS 仓库、节点身份和默认配置,并显示初始化成功信息。已经初始化的仓库不要重复执行此命令;如果出现仓库锁定或已初始化提示,应先检查现有仓库,而不是删除数据重新开始。
启动守护进程并验证本地 API
在第一个终端运行:
ipfs daemon预期结果:守护进程完成仓库加载、网络监听和 API 启动,终端出现类似以下内容:
Initializing daemon...
Daemon is ready启动日志的其他内容、地址与顺序会因版本及配置不同而变化。此终端需要保持运行;直接关闭终端通常会结束前台守护进程。
在第二个终端执行:
ipfs id -f='<id>\n'预期结果:输出一个 Peer ID,具体值由本地节点生成。
12D3KooW...ipfs id 成功返回说明 CLI 可以访问节点 API 并读取节点身份,但不能单凭这一结果断定已接入公共网络。即使节点没有连接任何远端 Peer,本地 API 仍可能正常工作。
默认配置通常将 RPC API 绑定在本机回环地址的 TCP 5001 端口,Gateway 使用 TCP 8080,Swarm 监听常见的 TCP 或 UDP 4001 端口。实际配置可能不同,必须以当前节点输出为准。RPC API 不应直接暴露到不可信公网。
读取节点地址与实际连接
首先查询节点身份及地址信息:
ipfs id预期结果:返回包含 ID、PublicKey、Addresses、AgentVersion 和 ProtocolVersion 等字段的 JSON 对象。Addresses 中可能出现类似 /ip4/192.168.1.20/tcp/4001/p2p/<ID> 的多地址;其中 <ID> 代表实际 Peer ID,IP 和端口也应以真实输出为准。
再查看本地 Swarm 监听位置与公告地址:
ipfs swarm addrs listen
ipfs swarm addrs local预期结果:第一条命令列出节点正在监听的多地址;第二条列出节点对外使用或公布的本地多地址。具体条目随网络接口、传输协议和 Kubo 配置变化。例如监听地址可能包括:
/ip4/0.0.0.0/tcp/4001
/ip6/::/tcp/40010.0.0.0 和 :: 表示监听相应地址族的网络接口,不代表可以把这些地址直接发给远端节点连接。地址中出现局域网 IP,也不代表公网节点能够主动访问该 IP。
接着检查真正建立的对等连接:
ipfs swarm peers预期结果:有连接时,每行列出一个已连接 Peer 的多地址,可能包含远端 IP、传输协议和 /p2p/<ID>。无连接时,命令可以成功执行但不输出任何 Peer。
可以使用以下命令统计当前连接数:
ipfs swarm peers | wc -l预期结果:在支持 wc 的 Linux、macOS 或类 Unix Shell 环境中输出一个非负整数,例如:
8这里的 8 仅是示例,不是公共网络的最低连接要求。Windows PowerShell 可改用 (ipfs swarm peers | Measure-Object -Line).Lines。连接数会随网络状态变化,不能把某个固定数字当作健康阈值。

判断是否真正接入公共网络
节点运行状态和网络接入状态需要分开验收。推荐按照以下顺序检查,而不是只看守护进程日志中的 Daemon is ready。
| 检查项 | 成功表现 | 能证明什么 |
|---|---|---|
ipfs id |
返回本地 Peer ID | 本地 API 与节点身份可读取 |
ipfs swarm addrs listen |
返回监听地址 | Swarm 传输监听已配置并启动 |
ipfs swarm peers |
返回远端 Peer | 至少存在对等连接 |
ipfs ping |
收到指定远端 Peer 的响应 | 与该 Peer 的 IPFS 通信可用 |
要进一步验证远端通信,可以从 ipfs swarm peers 的输出中选择一个实际在线的 Peer ID,执行:
ipfs ping -n 3 <PEER_ID>预期结果:成功时显示三次 Ping 的响应及延迟信息;实际延迟会变化。<PEER_ID> 必须替换为真实的远端节点 ID,不要保留尖括号直接执行。如果远端不支持相应协议、主动断开或发生超时,Ping 也可能失败,因此单次失败不能直接判定整个公共网络不可用。
还需要确认连接对象的来源。ipfs swarm peers 只证明存在 libp2p 连接,不能自动证明对方属于公共 IPFS 网络:它可能是同一局域网的节点、手动连接的私有节点,或者使用私有 Swarm Key 的节点。
对于默认公共网络配置,可以结合远端地址、公共 Bootstrap 配置以及从独立网络中的另一台公共 Kubo 节点发起连接测试进行交叉验证。查看当前 Bootstrap 列表:
ipfs bootstrap list预期结果:显示当前仓库配置的 Bootstrap 多地址列表。列表非空只表示配置了候选引导节点,不代表这些节点已经连接成功。最终应以实际 Swarm 连接和跨网络通信测试为准。
没有 Peer 时按层定位
如果 ipfs swarm peers 没有输出,先不要重新初始化仓库。按本地进程、监听配置、引导节点和网络出口逐层检查。
- 确认运行
ipfs daemon的终端没有退出,并检查是否出现仓库锁定、端口占用或启动失败。若ipfs id无法连接 API,先解决守护进程问题。 - 使用
ipfs swarm addrs listen检查 Swarm 是否实际监听。若没有预期地址,检查当前仓库的Addresses.Swarm配置,以及 TCP、UDP 端口是否被其他程序占用。 - 使用
ipfs bootstrap list检查引导节点配置。若列表为空,且希望恢复当前 Kubo 版本的默认公共引导节点,可以执行ipfs bootstrap add --default,但不要在有意隔离的私有网络中执行。 - 检查主机防火墙、企业网络策略、DNS 和出站 TCP/UDP 连通性。NAT 可能限制入站连接,但不一定阻止节点主动建立出站连接。
- 等待节点完成发现与拨号后重新检查连接数。若有远端 Peer 但 Ping 失败,应结合具体 Peer 的在线状态和连接日志判断,避免把远端不响应误判为本地节点故障。
需要查看当前连接信息时,可执行:
ipfs swarm peers -v预期结果:在支持该选项的 Kubo 版本中,输出包含连接多地址、传输或连接方向等附加信息的 Peer 列表;字段格式因版本而异。若命令报告不支持 -v,使用 ipfs swarm peers --help 检查本机版本的可用选项。
完成节点验收与安全收尾
本次操作至少记录四项信息:Kubo 版本、本地 Peer ID、Swarm 监听地址和当前连接 Peer 数量。对于公共网络实验,再记录一次远端 Ping 的成功或失败结果,并说明测试时是否启用了私有网络配置。
验收标准分为两个等级:本地运行通过要求守护进程正常、ipfs id 成功、监听地址存在;公共网络连接通过还要求至少连接一个经确认属于目标公共网络的远端 Peer,并能完成相应通信测试。连接数为零时可以判定尚未观察到活跃对等连接,但不能据此认定 Kubo 安装失败。
实验结束后,在运行守护进程的终端按 Ctrl+C 正常退出,等待进程释放仓库锁和网络监听端口。下次启动时继续使用同一仓库,Peer ID 通常保持不变,无需再次初始化。