go-ipfs Docker镜像文档

一、镜像概述和主要用途

go-ipfs 是 IPFS 协议实现项目 Kubo 的遗留（Legacy）Docker 镜像命名。该镜像仅为向后兼容性目的而保留，用于支持已基于 go-ipfs 镜像构建的旧有系统或脚本。新用户应优先使用官方推荐的 ipfs/kubo 镜像，kubo 是该项目的当前正式名称。

二、核心功能和特性

go-ipfs 镜像的功能与 ipfs/kubo 完全一致，其核心功能继承自 Kubo 项目，主要包括：

• IPFS 网络节点：作为全功能节点接入 IPFS 去中心化网络，支持内容寻址和 peer-to-peer 数据传输。
• 文件管理：提供 ipfs add、ipfs cat 等命令，支持文件/目录的添加、检索与管理。
• 数据持久化：通过数据卷挂载支持节点数据（如区块存储、配置文件）的持久化存储。
• API 接口：内置 HTTP API 和 Gateway，支持通过 REST 接口与节点交互。
• 兼容性：完全兼容 Kubo 的配置体系、数据格式及网络协议。

注：go-ipfs 与 ipfs/kubo 镜像内容完全一致，仅命名不同，均指向 Kubo 项目的同版本实现。

三、使用场景和适用范围

适用场景

• 旧系统兼容性：已基于 go-ipfs 镜像编写的部署脚本、CI/CD 流程或容器编排配置（如 Docker Compose、Kubernetes），需维持原有命名以避免修改成本。
• 历史版本依赖：部分旧应用或工具明确指定依赖 go-ipfs 镜像标签（如 go-ipfs:v0.14.0），需通过该镜像获取对应版本。

不适用场景

• 新项目/新部署：所有新用户或新系统应直接使用 ipfs/kubo 镜像，避免依赖遗留命名。
• 长期维护场景：go-ipfs 镜像可能随 Kubo 项目演进逐步停止更新，长期维护应迁移至 ipfs/kubo。

四、使用方法和配置说明

基本使用（Docker Run）

通过 docker run 启动 go-ipfs 容器，基本命令如下（与 ipfs/kubo 完全一致）：

docker run -d \
  --name go-ipfs-node \
  -p 4001:4001 \  # IPFS 对等节点通信端口（P2P）
  -p 5001:5001 \  # IPFS API 端口（本地访问）
  -p 8080:8080 \  # IPFS Gateway 端口（HTTP 网关）
  -v /path/to/local/data:/data/ipfs \  # 挂载本地目录持久化节点数据
  go-ipfs:latest

参数说明：

• -v /path/to/local/data:/data/ipfs：必须挂载数据卷，否则容器重启后节点数据（区块、配置）将丢失。
• 端口映射：根据实际需求开放，例如仅需 API 可省略 Gateway 端口。

配置与环境变量

go-ipfs 镜像支持与 ipfs/kubo 相同的配置方式，主要通过以下途径：

1. 配置文件修改
   容器内配置文件路径为 /data/ipfs/config，可通过挂载本地配置文件覆盖默认配置：

   docker run -d \
     --name go-ipfs-node \
     -v /path/to/local/config:/data/ipfs/config \  # 挂载自定义配置文件
     -v /path/to/local/data:/data/ipfs \
     go-ipfs:latest
   

2. 启动命令覆盖
   通过 command 参数指定启动时执行的 ipfs 命令，例如初始化节点（首次启动需初始化）：

   docker run --rm -v /path/to/local/data:/data/ipfs go-ipfs:latest ipfs init
   

迁移至 ipfs/kubo 镜像

为避免依赖遗留命名，建议尽快将 go-ipfs 迁移至 ipfs/kubo，步骤如下：

1. 停止并备份当前节点数据：

   docker stop go-ipfs-node
   cp -r /path/to/local/data /path/to/backup/data  # 备份数据卷目录
   

2. 使用 ipfs/kubo 启动新节点：
   直接替换镜像名称，复用原数据卷和配置：

   docker run -d \
     --name kubo-node \
     -p 4001:4001 \
     -p 5001:5001 \
     -p 8080:8080 \
     -v /path/to/local/data:/data/ipfs \  # 复用原数据卷
     ipfs/kubo:latest
   

3. 验证迁移
   通过 API 检查节点状态，确认数据和网络连接正常：

   curl http://localhost:5001/api/v0/id  # 查看节点 ID，应与原节点一致
   

五、注意事项

• 版本一致性：go-ipfs:latest 标签始终与 ipfs/kubo:latest 同步，版本号（如 v0.25.0）也完全对应，无需担心功能差异。
• 安全更新：建议定期更新镜像版本以获取安全补丁，命令与 ipfs/kubo 相同：

  docker pull go-ipfs:latest  # 或指定版本标签如 go-ipfs:v0.25.0
  

• 官方支持：go-ipfs 镜像的维护优先级低于 ipfs/kubo，问题反馈建议直接参考 Kubo 官方文档。