Riak 提供两套客户端接入方式：HTTP REST 和 Protocol Buffers（下称 PB）。HTTP 适合用 curl 直接调试，但 PB 基于 protobuf 二进制编码，单帧体积更小，解析更快，在批量读取、二级索引查询、CRDT 等场景中优势明显。接入 PB 前需要先理解它并不是在 HTTP 路径上增加参数，而是一套独立的 TCP 长连接协议，默认监听 8087 端口。接着从协议帧、客户端配置、连接管理和版本兼容几个角度展开。
一、PB接口与HTTP接口的差异
Riak 的 HTTP 接口默认监听 8098 端口，操作对象时使用类似 /buckets/{bucket}/keys/{key} 的路径，调试非常直观。PB 接口则完全脱离 URI 和 HTTP 方法，客户端需要通过 TCP 连接发送 protobuf 编码的请求消息。以读取一个对象为例，HTTP 会发送 GET 请求并解析 JSON 或纯文本响应；PB 会构造 RpbGetReq 消息，填写 bucket 和 key 字段，直接发送二进制帧。服务端返回 RpbGetResp，其中 content 字段携带对象值和元数据。
实际选择时，如果只是低 QPS 的简单 KV 操作，HTTP 开发成本更低，排查问题也更方便。但一旦出现大量小对象读写、批量 get/put、MapReduce 或二级索引查询，PB 的字段编码优势和长连接复用能明显降低网络与 CPU 开销。需要特别注意，两者支持的能力并不完全对称，部分功能在 PB 中才暴露得更完整，比如向量时钟、修改索引等。生产环境常见做法是两者都开，HTTP 用于日常排查和运维，PB 用于业务主链路。
从客户端角度看，HTTP 可以直接用 requests、curl 等工具调用，PB 则需要对应的客户端库或手工实现帧封装。很多开发者就是因为直接套用 HTTP 的使用习惯，忽略了 PB 的二进制帧协议，导致连接建立后无法正确通信。下一节会先把 PB 的帧格式讲清楚，这也是排查协议问题的基础。
二、PB协议的帧结构：长度前缀、消息码与消息体
Riak PB 接口默认绑定在 8087 端口。每个请求和响应都封装为一段字节流，结构非常固定：4 字节大端整数表示长度，1 字节消息码表示请求或响应类型，后面紧跟 protobuf 编码后的消息体。长度字段的值等于 1 加消息体字节数，因为消息码本身也占用 1 字节。例如发送一个空的 RpbPingReq，消息体长度为 0，总长度就是 1，网络字节序写作 00 00 00 01，后面跟上消息码 01。
很多 PB 接入问题都出在长度前缀上。如果长度少算了消息码，或者使用了小端序，服务端会直接断开连接或等待超时。Riak 客户端在内部已经封装好这些细节，用手工 socket 发 Ping 请求的目的只是验证端口是否可达、协议是否按预期响应。下面是一段 Python 示例，不需要安装 protobuf 依赖，因为 RpbPingReq 的消息体为空。
import socket
import struct
def recv_exact(sock, n):
data = b''
while len(data) != n:
chunk = sock.recv(n - len(data))
if not chunk:
break
data += chunk
return data
def riak_ping(host='127.0.0.1', port=8087):
sock = socket.create_connection((host, port), timeout=5)
# 4字节长度 + 1字节消息码，RpbPingReq=1，消息体为空
frame = struct.pack('!I', 1) + b'\x01'
sock.sendall(frame)
header = recv_exact(sock, 4)
if len(header) != 4:
sock.close()
raise TimeoutError('no response')
length = struct.unpack('!I', header)[0]
body = recv_exact(sock, length)
sock.close()
msg_code = body[0] if body else -1
return length, msg_code, body[1:]
if __name__ == '__main__':
print(riak_ping())
这段代码先建立到 8087 的 TCP 连接，然后发送 4 字节长度前缀和 1 字节消息码。recv_exact 函数循环读取指定字节数，避免单次 recv 返回不足导致解析错误。正常情况下响应体的第一个字节是消息码 2，表示 RpbPingResp；如果返回 0，说明收到 RpbErrorResp，通常意味着集群不可用或协议不匹配。实际开发中这种手工探测常用于自动化脚本或监控检查。
三、用官方客户端完成PB接入
手工封包只适合验证连通性，生产代码应优先使用官方或社区维护的客户端。Python 生态中安装 riak 包后，可以通过 protocol='pbc' 明确切换到 PB 协议，并指定节点列表。需要注意，HTTP 客户端默认连 8098，PB 客户端默认连 8087，因此配置项不要混用 pb_port 和 http_port。连接串中如果写错端口，会表现为连接超时或服务端直接拒绝。
from riak import RiakClient
client = RiakClient(protocol='pbc', nodes=[
{'host': '127.0.0.1', 'pb_port': 8087}
])
bucket = client.bucket('user_profile')
profile = bucket.get('user_1001')
if profile.exists:
print(profile.data)
else:
new_profile = bucket.new('user_1001', data={'name': 'Alice', 'level': 7})
new_profile.store()
上面的例子先获取名为 user_profile 的 bucket，然后尝试读取 user_1001。如果对象存在，profile.exists 会返回 True，data 属性中就是原始数据；如果不存在，则通过 bucket.new 创建一个带初始数据的对象并调用 store 方法写入。store 方法内部会构造 RpbPutReq 并发送到服务端，整个过程对业务代码屏蔽了帧和 protobuf 编码细节。
需要连接多个 Riak 节点时，可以在 nodes 列表中配置多个 host 和 pb_port。客户端会根据健康状态、请求轮询或故障转移策略选择节点。配置多个节点可以避免单点连接失败导致业务中断。官方客户端内部还负责 protobuf 消息版本匹配、连接复用和必要时的自动重连，这些能力如果自己实现成本会非常高。
四、连接池、超时与错误处理
PB 依赖 TCP 长连接，连接管理比 HTTP 更直接影响性能。大多数客户端会维护连接池，避免每次请求都重新三次握手。不同语言的客户端中连接池行为不同，例如 Python 客户端默认使用连接池复用 socket，Java 客户端也会缓存连接。若你直接在应用里手写 socket，需要自己实现连接池和重连，否则高并发下会频繁建立和销毁连接，进一步放大延迟。
超时设置要区分连接超时和请求超时。连接超时控制建立 TCP 连接的时间，请求超时控制发送请求后等待响应的最大时间。以 Python 客户端为例，可以在初始化时传入 timeout 参数，单位通常是毫秒。设置太短会造成正常请求被取消，设置太长又会让故障转移变慢。一般根据 P99 延迟加一定余量，并配合熔断机制使用，避免在某个节点已经不可用时仍有大量请求排队等待。
from riak import RiakError
import time
def store_with_retry(obj, retries=3):
for attempt in range(retries):
try:
obj.store()
return
except RiakError as exc:
print('store failed:', exc)
if attempt != retries - 1:
time.sleep(0.5 * (attempt + 1))
else:
raise
错误处理还需要关注 PB 错误响应。Riak 在操作失败时返回 RpbErrorResp，消息码为 0，消息体里包含错误码和错误描述。客户端会把这些信息包装成异常，比如 RiakError。捕获异常后可以区分对待：对象不存在通常不是致命错误，结合 exists 判断即可；节点不可达或超时则可以换节点重试。读写操作大多幂等，但重试前要确保业务逻辑允许重复提交，尤其是写操作可能携带客户端生成的 key 或多节点并发写入时。
五、安全加固与版本兼容
Riak PB 端口默认只做简单 TCP 监听，本身没有用户名密码或 TLS 加密。若集群部署在公网或不可信网络，必须通过防火墙限制来源 IP，或者将 pb_ip 绑定到内网网卡。不要把 8087 直接暴露到公网，否则任何人都可以读取和写入数据。生产上常见做法是用安全组或 iptables 只放行应用服务器网段，必要时再通过 VPN 或内部代理访问 PB 端口。
版本兼容是另一个容易忽略的点。PB 消息由 riak.proto 中定义的消息结构驱动，不同版本的 Riak 可能会增加或调整字段。Protobuf 本身有向后兼容机制，旧客户端遇到新增字段会忽略，新客户端遇到旧消息也可以使用默认值。但主版本升级时官方可能移除废弃消息码或改变语义，因此客户端版本与集群的大版本最好保持一致。否则可能出现某些字段取出来是默认值，或者请求直接返回错误码。
升级顺序上建议先升级客户端到兼容新旧协议的版本，再升级集群，这样可以平滑过渡。若出现未知消息码或解码失败，先检查客户端版本是否高于或远低于集群版本，再抓包确认消息帧是否正确。通常只要长度前缀、消息码和 protobuf 定义三者匹配，PB 接入不会出现莫名其妙的解析错误。遇到异常时不要急着改业务代码，先确认端口、版本和网络策略三个基础环节。
RiakProtocol Buffers客户端接入修改时间：2026-09-19 09:18:57