jbenet/go-ipfs

go-ipfs Docker镜像文档

!banner

![]([] ![]([] ![]([] ![GoDoc]([] ![Build Status]([***]

镜像概述

go-ipfs是IPFS（InterPlanetary File System，星际文件系统）的Go语言实现，通过Docker镜像可快速部署IPFS节点。IPFS是一个全球性、版本化的点对点文件系统，融合了Git、BitTorrent、Kademlia、SFS和Web的优秀理念，类似于一个交换Git对象的BitTorrent集群，提供与HTTP Web一样简单的接口，但内置永久性，还可将整个网络挂载到/ipfs路径下。

核心功能与特性

• 点对点网络：节点间直接通信，无需中央服务器
• 内容寻址：通过文件内容的哈希值而非位置定位数据
• 版本化文件系统：支持文件历史版本追踪，类似Git
• 分布式存储：数据分散存储在多个节点，提高可用性和容错性
• 永久存储：内容一旦添加，理论上可永久保存（需节点固定）
• 挂载支持：可将IPFS文件系统挂载到本地目录
• 跨平台兼容：支持Linux、macOS、Windows等主流操作系统

使用场景与适用范围

• 分布式文件存储：替代传统中心化存储，提高数据冗余和可用性
• 内容分发网络：高效分发静态资源，降低带宽成本
• 去中心化应用（DApp）：为DApp提供数据存储和共享基础设施
• 数据备份与归档：利用内容寻址和分布式特性实现可靠备份
• 学术数据共享：便于科研数据的永久保存和开放共享

使用方法与配置说明

系统要求

• 推荐至少2GB内存（单CPU核心即可运行），最低1GB内存（可能不稳定）
• 支持Linux、macOS、Windows系统

Docker部署步骤

1. 准备挂载目录

为确保数据持久化和文件导入/导出，需创建两个本地目录：

bash
export ipfs_staging=</绝对路径/用于文件导入导出>  # 如：/home/user/ipfs/staging
export ipfs_data=</绝对路径/用于IPFS数据存储>    # 如：/home/user/ipfs/data

2. 启动IPFS容器

bash
docker run -d \
  --name ipfs_host \
  -v $ipfs_staging:/export \
  -v $ipfs_data:/data/ipfs \
  -p 4001:4001 \  # P2P网络端口
  -p 127.0.0.1:8080:8080 \  # 只读网关端口（本地访问）
  -p 127.0.0.1:5001:5001 \  # API端口（本地访问）
  ipfs/go-ipfs:latest

3. 查看容器日志

bash
docker logs -f ipfs_host

当日志中出现以下信息时，表示IPFS节点启动成功：

Gateway (readonly) server listening on /ip4/0.0.0.0/tcp/8080

基本操作

执行IPFS命令

通过docker exec在容器内执行IPFS命令：

bash
# 查看连接的对等节点
docker exec ipfs_host ipfs swarm peers

# 添加文件到IPFS
cp -r <本地文件> $ipfs_staging
docker exec ipfs_host ipfs add -r /export/<文件路径>

# 查看文件内容
docker exec ipfs_host ipfs cat <内容哈希>

# 停止容器
docker stop ipfs_host

配置参数

环境变量

• IPFS_PROFILE：首次启动且数据目录为空时，用于指定初始化配置文件。可选值：
  • server：适用于服务器环境，禁用本地网络发现
  • default：默认配置（包含本地网络发现）

示例：使用server配置文件启动

bash
docker run -d \
  --name ipfs_host \
  -e IPFS_PROFILE=server \
  -v $ipfs_staging:/export \
  -v $ipfs_data:/data/ipfs \
  -p 4001:4001 -p 127.0.0.1:8080:8080 -p 127.0.0.1:5001:5001 \
  ipfs/go-ipfs:latest

端口映射说明

更新IPFS

使用ipfs-update工具

IPFS提供独立的更新工具ipfs-update，可通过以下步骤安装和使用：

1. 下载ipfs-update：[***]
2. 安装后执行更新：

   bash
   ipfs update install latest
   

通过IPFS网络下载更新

1. 列出可用版本：

   bash
   docker exec ipfs_host ipfs cat /ipns/dist.ipfs.io/go-ipfs/versions
   

2. 下载指定版本（替换$VERSION为具体版本号）：

   bash
   docker exec ipfs_host ipfs get /ipns/dist.ipfs.io/go-ipfs/$VERSION/go-ipfs_$VERSION_linux-amd64.tar.gz
   

故障排除

• 节点启动失败：若之前安装过IPFS，尝试删除或备份数据目录（默认~/.ipfs），重新初始化：

  bash
  rm -rf $ipfs_data/*  # 注意：此操作会删除所有本地IPFS数据
  docker start ipfs_host  # 容器会自动重新初始化
  

• 内存不足：IPFS在内存小于1GB的系统上可能不稳定，建议升级硬件或增加Swap空间。

• 网络连接问题：检查防火墙是否开放4001端口，确保P2P网络通信正常。

• 安全漏洞报告：如发现安全问题，发送邮件至***（GPG密钥：4B9665FB 92636D17 7C7A86D3 50AAE8A9 59B13AF3），不要公开提交issue。

相关资源

• 官方文档：[***]
• GitHub仓库：https://github.com/ipfs/go-ipfs
• 社区论坛：[***]
• IRC频道：freenode #ipfs