P2P 与分布式存储 / 系统课时

调用 Kubo RPC 上传文件

调用 Kubo RPC 上传文件

应用程序可以通过 Kubo RPC API 将文件导入本地 IPFS 节点,并从响应中取得内容标识符 CID。本课使用 Python 完成一次真实的文件上传,检查 multipart 请求、返回字段和错误处理,并验证返回的 CID 能否读取到原始内容。

学习目标

  • 使用 HTTP multipart/form-data 调用 Kubo 的 /api/v0/add 接口。
  • 正确解析 Name、Hash、Size,并通过 CID 验证上传结果。
  • 识别连接失败、HTTP 错误和内容校验失败,明确 RPC 接口的安全边界。

确认节点与 RPC 服务

以下操作适用于提供 /api/v0/add 的 Kubo RPC API,示例使用本机 Kubo 节点和 Python 3.10 及以上版本。Kubo 的默认 RPC 地址通常为 127.0.0.1:5001,但实际值以节点配置为准。

首次使用 Kubo 时,先在终端执行:

bash
ipfs init

预期结果:命令成功完成仓库初始化,并显示初始化相关信息。已有仓库不需要重复执行。随后在单独的终端启动节点:

bash
ipfs daemon

预期结果:节点启动完成后出现类似以下提示,进程持续运行:

text
Daemon is ready

在另一个终端查询 RPC 地址:

bash
ipfs config Addresses.API

默认配置的预期输出为:

text
/ip4/127.0.0.1/tcp/5001

如果返回其他地址或端口,应使用实际配置修改后续程序中的 RPC_URL。若节点尚未运行,执行上传请求会出现连接拒绝或超时。

构造文件上传请求

Kubo 的 /api/v0/add 使用 HTTP POST,文件内容放在 multipart/form-data 的文件字段中。查询参数 cid-version=1 指定生成 CIDv1,pin=true 请求将导入的内容递归固定在本地仓库。

本例使用 Python 标准库构造 multipart 请求,不需要安装第三方 HTTP 包。将以下代码保存为 upload_ipfs.py:

python
import json
import uuid
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

RPC_URL = 'http://127.0.0.1:5001'
FILE = Path('hello.txt')
FILE.write_bytes(b'hello ipfs\n')

# multipart 的 boundary 必须与请求头和请求体一致。
boundary = 'ipfs-' + uuid.uuid4().hex
payload = (
    f'--{boundary}\r\n'
    'Content-Disposition: form-data; name="file"; filename="hello.txt"\r\n'
    'Content-Type: application/octet-stream\r\n\r\n'
).encode() + FILE.read_bytes() + f'\r\n--{boundary}--\r\n'.encode()

params = urlencode({'cid-version': '1', 'pin': 'true'})
request = Request(
    f'{RPC_URL}/api/v0/add?{params}',
    data=payload,
    headers={'Content-Type': f'multipart/form-data; boundary={boundary}'},
    method='POST',
)

try:
    with urlopen(request, timeout=30) as response:
        # add 可以返回按行分隔的 JSON;取最后一个非空结果。
        lines = response.read().decode('utf-8').splitlines()
        records = [json.loads(line) for line in lines if line.strip()]
        if not records:
            raise ValueError('RPC 返回空响应')
        result = records[-1]
        for key in ('Name', 'Hash', 'Size'):
            if key not in result:
                raise ValueError(f'响应缺少字段: {key}')
        print('Name:', result['Name'])
        print('CID:', result['Hash'])
        print('Size:', result['Size'])
except HTTPError as exc:
    print('HTTP 错误:', exc.code, exc.read().decode('utf-8', errors='replace'))
except URLError as exc:
    print('连接失败:', exc.reason)
except (ValueError, json.JSONDecodeError) as exc:
    print('响应解析失败:', exc)

运行:

bash
python upload_ipfs.py

预期结果:本地生成 hello.txt,请求成功后打印三个字段,格式类似:

text
Name: hello.txt
CID: <CID>
Size: <SIZE>

<CID> 是实际返回的 CIDv1 字符串,<SIZE> 是 Kubo 返回的十进制大小字符串。两者应以实际响应为准。这里的 Size 是导入对象的累计 DAG 大小,不应直接当作原始文件字节数;本例原始文件内容为 11 字节。

理解 RPC 调用边界与响应

上传请求经过应用、Kubo RPC 服务和本地内容仓库三个部分。RPC 服务负责解析请求并执行导入;成功响应表示本地节点已完成相应操作,不表示其他节点已经复制该文件。

应用调用 Kubo RPC 上传文件的数据流

响应字段的含义如下:

字段 含义 使用方式
Name 导入文件的名称 展示原始文件名,不作为唯一标识
Hash 导入对象的根 CID 保存为后续检索与校验的标识
Size 对象的累计 DAG 大小 用于记录导入结果,不代替原始文件长度

cid-version=1 影响 CID 版本,但不保证不同导入配置下同一原始文件必然得到相同 CID。分块策略、UnixFS 编码等参数也可能改变根 CID。应用数据库通常保存 CID、原始文件名、业务所有者及上传时间,而不依赖文件名定位内容。

根据 CID 验证上传内容

上传完成后,应当使用返回的 CID 读取内容,再比较原始字节,而不只是判断 HTTP 请求成功。以下验证代码可直接追加到 upload_ipfs.py 的成功响应分支中,放在打印 Size 之后;它依赖前面已经定义的 result、FILE、RPC_URL 和导入模块。

python
        # 使用返回的 CID 读取 UnixFS 文件内容。
        cid = result['Hash']
        cat_url = f'{RPC_URL}/api/v0/cat?' + urlencode({'arg': cid})
        with urlopen(Request(cat_url, data=b'', method='POST'), timeout=30) as cat:
            downloaded = cat.read()
        assert downloaded == FILE.read_bytes(), '内容与原文件不一致'
        print('内容校验: OK')

这是依赖前面主示例上下文的片段示例,不应单独执行。重新运行完整脚本后,预期在原有三行结果后增加:

text
内容校验: OK

这里比较的是完整文件字节,包括末尾换行。实际应用应采用流式上传和下载,避免对大型文件使用 read_bytes() 或一次性读取整个响应造成内存峰值。对于大文件,还可边读取边计算 SHA-256,与业务侧预先保存的摘要比较。

本地 cat 成功只能证明当前节点可以读取内容。若要验证网络分发,应在独立节点上使用相同 CID 执行读取,并确保该节点没有预先导入相同内容。

处理错误与生产环境边界

上传接口的故障应按层次区分,避免将所有失败统一报告为上传失败。

现象 常见原因 处理方法
Connection refused Kubo 未启动或 RPC 地址错误 检查 ipfs daemon 与 Addresses.API
HTTP 400 请求参数或 multipart 格式不合法 检查 Content-Type、boundary、文件字段及参数
HTTP 500 Kubo 内部处理或仓库异常 查看节点日志、磁盘空间和仓库状态
响应 JSON 解析失败 响应格式不符合预期或被中间代理改写 保存脱敏后的状态码与响应片段进行定位
上传成功但远端无法读取 内容尚未被发现、网络连接失败或远端不可达 独立检查提供者发现、连接与区块获取

生产环境还应设置上传大小上限、并发限制和合理超时。示例中的 30 秒超时仅用于小文件演示;大文件应结合文件大小、网络条件和业务 SLA 调整。由于 add 可能产生持久化副作用,客户端超时后不能简单认定导入失败;重试前应结合业务请求 ID 做幂等控制,并检查是否已经保存 CID。

最后需要区分两种安全边界:业务后端可以向 Kubo 发送受控 RPC 请求,普通浏览器或不可信客户端不应直接持有 RPC 管理权限。完成上传、解析 CID 和本地字节校验后,应用才具备一条可验证的本地导入链路;跨节点可用性仍需要单独验收。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

调用 Kubo RPC 上传文件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通