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 时,先在终端执行:
ipfs init预期结果:命令成功完成仓库初始化,并显示初始化相关信息。已有仓库不需要重复执行。随后在单独的终端启动节点:
ipfs daemon预期结果:节点启动完成后出现类似以下提示,进程持续运行:
Daemon is ready在另一个终端查询 RPC 地址:
ipfs config Addresses.API默认配置的预期输出为:
/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:
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)运行:
python upload_ipfs.py预期结果:本地生成 hello.txt,请求成功后打印三个字段,格式类似:
Name: hello.txt
CID: <CID>
Size: <SIZE><CID> 是实际返回的 CIDv1 字符串,<SIZE> 是 Kubo 返回的十进制大小字符串。两者应以实际响应为准。这里的 Size 是导入对象的累计 DAG 大小,不应直接当作原始文件字节数;本例原始文件内容为 11 字节。
理解 RPC 调用边界与响应
上传请求经过应用、Kubo RPC 服务和本地内容仓库三个部分。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 和导入模块。
# 使用返回的 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')这是依赖前面主示例上下文的片段示例,不应单独执行。重新运行完整脚本后,预期在原有三行结果后增加:
内容校验: 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 和本地字节校验后,应用才具备一条可验证的本地导入链路;跨节点可用性仍需要单独验收。