ipfs/ipfs-cluster

IPFS Cluster 镜像文档

目录

• 镜像概述与主要用途
• 核心功能与特性
• 使用场景与适用范围
• 详细使用方法与配置说明
• 配置参数与环境变量
• Docker 部署方案示例
• 贡献与许可

镜像概述与主要用途

IPFS Cluster 是一款针对 IPFS（星际文件系统）网络的固定集（pinset）编排工具，旨在通过跨多个 IPFS 守护进程（daemon）分配、复制和跟踪全局固定集，实现分布式环境下的数据协同管理。其核心目标是解决多节点 IPFS 部署中数据一致性、可用性及冗余管理问题，确保指定数据在集群内的可靠存储与访问。

核心功能与特性

核心组件

1. 集群节点服务（ipfs-cluster-service）
   作为核心组件，需与 kubo（原 go-ipfs）守护进程配合运行（sidecar 模式），负责本地节点的固定集管理、集群通信及数据同步。

2. 客户端 CLI（ipfs-cluster-ctl）
   提供命令行接口，通过 HTTP API 与集群节点交互，支持固定集添加/删除、集群状态查询、节点管理等操作。

3. 跟随节点服务（ipfs-cluster-follow）
   简化「跟随节点」（follower peer）的配置与启动流程，无需手动管理复杂集群参数，快速接入现有集群。

关键特性

• 分布式固定集管理：统一协调集群内所有节点的固定策略，确保全局固定集一致性。
• 数据自动复制：支持按策略（如副本数、节点筛选规则）在集群内自动复制数据，提升冗余与可用性。
• 集群协同通信：基于 libp2p 实现节点间通信，支持动态节点加入/退出，维护集群拓扑。
• 灵活配置：支持自定义固定策略、节点权重、网络参数，适配不同规模与场景需求。

使用场景与适用范围

典型场景

• 企业级 IPFS 部署：管理多节点 IPFS 集群，确保业务数据在分布式环境中的可靠存储。
• 分布式存储系统：作为底层数据编排层，为分布式应用提供跨节点数据固定与复制能力。
• 数据冗余与容灾：通过多节点复制，防止单点故障导致的数据丢失，满足高可用性需求。
• 内容分发网络：协调边缘节点固定热门内容，优化内容访问延迟。

适用范围

• 需管理 2 个及以上 IPFS 节点的个人或组织。
• 对数据可用性、冗余度有明确要求的 IPFS 应用场景。
• 需要统一管控跨节点固定策略的管理员或开发团队。

详细使用方法与配置说明

基本工作流程

1. 初始化集群：启动首个集群节点（leader），生成集群密钥与初始配置。
2. 添加节点：其他节点通过引导地址（bootstrap address）加入集群，同步全局固定集。
3. 管理固定集：通过 ipfs-cluster-ctl 提交固定任务，集群自动分配至节点并复制。
4. 监控与维护：通过 CLI 或 API 监控集群状态，调整节点权重或复制策略。

核心操作示例（CLI）

bash
# 查看集群状态
ipfs-cluster-ctl status

# 添加 CID 至全局固定集（副本数 2）
ipfs-cluster-ctl pin add <CID> --replication 2

# 移除固定集
ipfs-cluster-ctl pin rm <CID>

# 查看集群节点列表
ipfs-cluster-ctl peers ls

配置参数与环境变量

IPFS Cluster 支持通过环境变量或配置文件（config.json）自定义参数，常用环境变量如下：

Docker 部署方案示例

1. 单节点集群快速启动（docker run）

bash
# 启动 IPFS 守护进程（kubo）
docker run -d --name ipfs-daemon -p 4001:4001 -p 5001:5001 ipfs/kubo:latest

# 生成集群密钥（本地执行）
CLUSTER_SECRET=$(od -vN 32 -An -tx1 /dev/urandom | tr -d ' \n')

# 启动 IPFS Cluster 节点（关联上述 IPFS 守护进程）
docker run -d --name ipfs-cluster \
  --link ipfs-daemon:ipfs \
  -e CLUSTER_SECRET=$CLUSTER_SECRET \
  -e IPFS_CLUSTER_IPFSHTTP_NODE=http://ipfs:5001 \
  -p 9094:9094 \  # HTTP API 端口
  -p 9096:9096 \  # 集群通信端口
  ipfs/ipfs-cluster:latest

2. 多节点集群部署（docker-compose）

yaml
# docker-compose.yml
version: '3'
services:
  ipfs-1:
    image: ipfs/kubo:latest
    ports:
      - "4001:4001"
      - "5001:5001"
    volumes:
      - ipfs1-data:/data/ipfs

  cluster-1:
    image: ipfs/ipfs-cluster:latest
    depends_on:
      - ipfs-1
    environment:
      - CLUSTER_SECRET=your-cluster-secret-here  # 替换为实际密钥
      - IPFS_CLUSTER_IPFSHTTP_NODE=http://ipfs-1:5001
      - CLUSTER_PEERNAME=cluster-node-1
      - CLUSTER_BOOTSTRAP=  # 首个节点无需引导地址
    ports:
      - "9094:9094"
      - "9096:9096"
    volumes:
      - cluster1-data:/data/ipfs-cluster

  ipfs-2:
    image: ipfs/kubo:latest
    ports:
      - "4002:4001"
      - "5002:5001"
    volumes:
      - ipfs2-data:/data/ipfs

  cluster-2:
    image: ipfs/ipfs-cluster:latest
    depends_on:
      - ipfs-2
      - cluster-1
    environment:
      - CLUSTER_SECRET=your-cluster-secret-here  # 与 cluster-1 一致
      - IPFS_CLUSTER_IPFSHTTP_NODE=http://ipfs-2:5001
      - CLUSTER_PEERNAME=cluster-node-2
      - CLUSTER_BOOTSTRAP=/ip4/cluster-1/tcp/9096/p2p/<cluster-1-peer-id>  # 替换为 cluster-1 的 peer ID
    ports:
      - "9095:9094"
      - "9097:9096"
    volumes:
      - cluster2-data:/data/ipfs-cluster

volumes:
  ipfs1-data:
  cluster1-data:
  ipfs2-data:
  cluster2-data:

注意：CLUSTER_BOOTSTRAP 需替换为首个集群节点（cluster-1）的实际 peer ID，可通过 docker logs cluster-1 查看启动日志获取。

贡献与许可

贡献

IPFS Cluster 欢迎社区贡献，具体指南参见 贡献规范。

许可

本项目采用双许可证授权：Apache 2.0 与 MIT 许可证。
© 2022 Protocol Labs, Inc.

参考文档：完整用户手册与技术细节请参见 IPFS Cluster 官方文档。