ipfs/js-ipfs

js-ipfs - JavaScript实现的IPFS协议

镜像概述

js-ipfs是IPFS（星际文件系统）协议的JavaScript实现，允许在Node.js环境和浏览器中创建和运行IPFS节点。该项目目前处于Alpha阶段，正在积极开发中，API可能会发生变化。

核心功能和特性

• 跨平台支持：可在Node.js和浏览器环境中运行
• 完整的IPFS协议实现：包括内容寻址、P2P网络、数据块交换等核心功能
• 命令行界面：提供jsipfs命令行工具，与Go-IPFS接口兼容
• 编程API：可作为模块集成到JavaScript应用中
• 可配置网络：支持自定义引导节点、中继配置和连接管理
• 实验性功能：包括pubsub、IPNS pubsub和目录分片等

使用场景和适用范围

• 构建基于IPFS的去中心化应用
• 在浏览器中直接访问IPFS网络
• 开发IPFS相关工具和库
• 作为IPFS网络的轻量级节点
• 教育和研究IPFS协议实现

安装与使用

通过npm安装

bash
# 本地安装
npm install ipfs

# 全局安装（用于CLI）
npm install ipfs --global

注意：js-ipfs依赖于需要node-gyp编译的原生模块，可能需要安装额外的构建工具。

基本使用方法

作为命令行工具

bash
# 查看帮助
jsipfs --help

# 启动IPFS守护进程
jsipfs daemon

默认配置与Go-IPFS不同，避免冲突：

• 默认仓库位置：~/.jsipfs（可通过IPFS_PATH环境变量修改）
• 默认swarm端口：4002
• 默认API端口：5002

作为Node.js模块

javascript
const IPFS = require('ipfs')
const node = new IPFS()

node.on('ready', () => {
  console.log('IPFS节点已准备就绪')
  
  // 使用IPFS API
  node.add({ path: 'test.txt', content: Buffer.from('Hello IPFS!') }, (err, result) => {
    if (err) {
      return console.error(err)
    }
    console.log('添加文件成功:', result[0].hash)
    
    // 停止节点
    node.stop(() => console.log('IPFS节点已停止'))
  })
})

在浏览器中使用

通过CDN引入：

html
<!-- 加载压缩版本 -->
<script src="https://unpkg.com/ipfs/dist/index.min.js"></script>

<script>
  const node = new window.Ipfs()
  
  node.on('ready', () => {
    console.log('浏览器IPFS节点已准备就绪')
  })
</script>

Docker部署

使用Docker运行js-ipfs

bash
# 拉取镜像
docker pull ipfs/js-ipfs

# 运行容器
docker run -d --name js-ipfs -p 4002:4002 -p 5002:5002 ipfs/js-ipfs

Docker Compose配置

yaml
version: '3'

services:
  ipfs:
    image: ipfs/js-ipfs
    ports:
      - "4002:4002"  # Swarm端口
      - "5002:5002"  # API端口
    volumes:
      - ./ipfs-data:/root/.jsipfs
    restart: unless-stopped

配置选项

IPFS节点构造函数接受以下配置选项：

基本配置

网络配置

javascript
{
  relay: {
    enabled: true,        // 启用中继拨号器和监听器
    hop: {
      enabled: false,     // 是否作为中继节点
      active: false       // 是否主动中继
    }
  },
  preload: {
    enabled: true,        // 启用内容预加载
    addresses: [          // 预加载节点地址
      '/dns4/node0.preload.ipfs.io/tcp/443/https',
      '/dns4/node1.preload.ipfs.io/tcp/443/https'
    ]
  }
}

实验性功能

javascript
{
  EXPERIMENTAL: {
    pubsub: false,        // 启用libp2p pub-sub
    ipnsPubsub: false,    // 启用IPNS pub-sub
    sharding: false       // 启用目录分片
  }
}

核心API

IPFS节点提供以下核心功能API：

文件操作

• ipfs.add(data, [options], [callback]): 添加文件到IPFS
• ipfs.cat(ipfsPath, [options], [callback]): 获取IPFS中的文件内容
• ipfs.get(ipfsPath, [options], [callback]): 下载IPFS中的文件或目录
• ipfs.ls(ipfsPath, [callback]): 列出IPFS路径下的内容

MFS（可变文件系统）

• ipfs.files.cp([from, to], [callback]): 复制文件
• ipfs.files.mkdir(path, [options], [callback]): 创建目录
• ipfs.files.write(path, content, [options], [callback]): 写入文件
• ipfs.files.read(path, [options], [callback]): 读取文件内容
• ipfs.files.rm(path, [options], [callback]): 删除文件

DAG操作

• ipfs.dag.put(dagNode, [options], [callback]): 存储DAG节点
• ipfs.dag.get(cid, [path], [options], [callback]): 获取DAG节点
• ipfs.dag.tree(cid, [path], [options], [callback]): 列出DAG节点的路径

网络管理

• ipfs.bootstrap.add(addr, [callback]): 添加引导节点
• ipfs.bootstrap.list([callback]): 列出引导节点
• ipfs.swarm.connect(addr, [callback]): 连接到指定节点
• ipfs.swarm.peers([options], [callback]): 列出连接的对等节点

事件

IPFS节点是Node.js EventEmitter，可监听以下事件：

• error: 发生错误时触发
• init: 仓库初始化完成后触发
• ready: 节点准备就绪可使用时触发
• start: 节点启动后触发
• stop: 节点停止后触发

javascript
node.on('ready', () => {
  console.log('节点已准备就绪')
})

node.on('error', (err) => {
  console.error('节点错误:', err)
})

项目状态

当前项目处于Alpha阶段：

• 已实现大部分核心功能
• API可能会发生不兼容变化
• 正在积极开发和完善中

资源链接

• https://github.com/ipfs/js-ipfs
• https://github.com/ipfs/interface-ipfs-core
• https://github.com/ipfs/js-ipfs/tree/master/examples
• https://github.com/ipfs/pm/issues/650

许可证

本项目采用https://github.com/ipfs/js-ipfs/blob/master/LICENSE%E3%80%82