P2P 与分布式存储 / 系统课时
UDP Tracker 的宣告流程
UDP Tracker 的宣告流程
UDP Tracker 通过少量二进制报文完成节点登记与 Peer 地址发现。本课按照 BEP 15 拆解 Connect、Announce 及其响应,编写可运行的 Python 客户端,并通过事务 ID、超时重试和报文校验验证一次完整的 UDP Tracker 通信。
学习目标
- 识别 UDP Tracker 的 Connect、Announce 请求与响应字段及字节布局。
- 正确使用 Connection ID、Transaction ID 和重传规则。
- 使用 Python 向真实 UDP Tracker 发起请求并解析返回的 IPv4 Peer 列表。
为什么 Announce 之前必须 Connect
HTTP Tracker 使用 HTTP 请求参数传递 info_hash、peer_id 和上传下载统计;UDP Tracker 则使用固定格式的二进制报文,减少协议开销。
BEP 15 定义的典型 IPv4 通信包含两个阶段:
- 客户端向 Tracker 发送 Connect 请求,获取短期有效的 Connection ID。
- 客户端携带该 Connection ID 发送 Announce 请求,声明自身状态并获取 Peer 地址。
- Tracker 返回下载间隔、节点数量及紧凑编码的 Peer 列表。
- 客户端按响应中的 interval 安排后续宣告,并在连接标识失效时重新 Connect。

UDP 本身无连接,Connect 并不是建立传输层连接,而是取得 Tracker 认可的协议级标识。客户端不应把它理解成永久会话,也不能将某个 Tracker 返回的 Connection ID 用于另一台 Tracker。
Connect 报文的字节结构
BEP 15 的整数采用网络字节序,即大端序。Connect 请求固定为 16 字节,响应固定为 16 字节。
| 请求偏移 | 长度 | 字段 | 值 |
|---|---|---|---|
| 0 | 8 字节 | protocol_id | 0x41727101980 |
| 8 | 4 字节 | action | 0 |
| 12 | 4 字节 | transaction_id | 客户端生成的随机 uint32 |
| 响应偏移 | 长度 | 字段 | 含义 |
|---|---|---|---|
| 0 | 4 字节 | action | 0 |
| 4 | 4 字节 | transaction_id | 与请求相同 |
| 8 | 8 字节 | connection_id | Tracker 返回的 uint64 |
例如 Python 的 struct.pack('!QII', 0x41727101980, 0, transaction_id) 可以生成完整请求。! 指定网络字节序,Q 是 8 字节无符号整数,I 是 4 字节无符号整数。
响应必须同时满足来源地址正确、长度足够、action 为 0、Transaction ID 与当前请求相同。只检查 action 而忽略 Transaction ID,可能把旧响应误判为新请求的结果。
Connection ID 应在获取后及时使用。BEP 15 规定客户端可以在取得它后的 1 分钟内使用,Tracker 应在生成后的 2 分钟内接受它。超过客户端使用窗口应重新 Connect,不应无限缓存。
Announce 报文与 Peer 列表
Announce 请求固定部分为 98 字节,其中 info_hash 和 peer_id 各占 20 字节。它们必须是原始字节,不是 40 字符的十六进制文本。
| 偏移 | 长度 | 字段 | 示例或说明 |
|---|---|---|---|
| 0 | 8 | connection_id | Connect 响应取得 |
| 8 | 4 | action | 1 |
| 12 | 4 | transaction_id | 新的随机 uint32 |
| 16 | 20 | info_hash | BitTorrent v1 的 20 字节哈希 |
| 36 | 20 | peer_id | 客户端的 20 字节标识 |
| 56 | 8 | downloaded | 已下载字节数 |
| 64 | 8 | left | 剩余字节数 |
| 72 | 8 | uploaded | 已上传字节数 |
| 80 | 4 | event | 0 无事件、1 completed、2 started、3 stopped |
| 84 | 4 | IP address | 0 表示默认使用请求源地址 |
| 88 | 4 | key | 客户端随机键 |
| 92 | 4 | num_want | -1 表示使用 Tracker 默认数量 |
| 96 | 2 | port | 客户端监听端口 |
其中 left=0 通常表示客户端已拥有完整资源。第一次正常加入下载群时可发送 started;完成下载时发送 completed,正常离开时发送 stopped。这些事件应对应真实生命周期,不应每次周期宣告都发送 started。
IPv4 Announce 成功响应的前 20 字节依次是 action、transaction_id、interval、leechers、seeders,均为 4 字节整数。后续 Peer 数据每 6 字节一组:4 字节 IPv4 地址和 2 字节端口。例如 C0 00 02 01 1A E1 对应 192.0.2.1:6881,这是格式示例,不代表可连接的真实节点。

用 Python 完成一次 Connect 与 Announce
下面使用 Python 3.10 或更新版本的标准库,不需要第三方依赖。示例向命令行指定的 UDP Tracker 发送请求,并使用一个指定的 40 位十六进制 v1 Info Hash。仅对你有权测试的资源与 Tracker 运行。
保存为 udp_tracker.py:
import argparse
import secrets
import socket
import struct
import time
PROTOCOL_ID = 0x41727101980
def exchange(sock, address, payload, expected_action, txid):
# 同一次重试保留原始请求和事务ID,便于匹配迟到响应。
for attempt in range(4):
timeout = 15 * (2 ** attempt)
deadline = time.monotonic() + timeout
sock.sendto(payload, address)
while True:
remaining = deadline - time.monotonic()
if remaining <= 0:
break
sock.settimeout(remaining)
try:
data, source = sock.recvfrom(4096)
except socket.timeout:
break
if source != address or len(data) < 8:
continue
action, received_txid = struct.unpack_from('!II', data)
if received_txid != txid:
continue
if action == 3:
message = data[8:].decode('utf-8', errors='replace')
raise RuntimeError(f'Tracker error: {message}')
if action != expected_action:
continue
return data
raise TimeoutError('Tracker did not respond after retries')
def main():
parser = argparse.ArgumentParser()
parser.add_argument('host')
parser.add_argument('port', type=int)
parser.add_argument('info_hash', help='40-character v1 info hash in hex')
args = parser.parse_args()
info_hash = bytes.fromhex(args.info_hash)
if len(info_hash) != 20 or not 1 <= args.port <= 65535:
raise ValueError('Invalid info hash or Tracker port')
# 此示例只处理IPv4 Tracker与IPv4紧凑Peer列表。
address = socket.getaddrinfo(
args.host, args.port, socket.AF_INET, socket.SOCK_DGRAM
)[0][4]
peer_id = b'-PY0001-' + secrets.token_bytes(12)
key = secrets.randbits(32)
with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
tx1 = secrets.randbits(32)
connect = struct.pack('!QII', PROTOCOL_ID, 0, tx1)
response = exchange(sock, address, connect, 0, tx1)
if len(response) < 16:
raise ValueError('Short Connect response')
connection_id = struct.unpack_from('!Q', response, 8)[0]
print('Connect OK')
tx2 = secrets.randbits(32)
# 无本地资源数据时只演示协议交互,不表示真实下载进度。
announce = struct.pack(
'!QII20s20sQQQIIIiH',
connection_id, 1, tx2, info_hash, peer_id,
0, 1, 0, 0, 0, key, -1, 6881
)
response = exchange(sock, address, announce, 1, tx2)
if len(response) < 20 or (len(response) - 20) % 6:
raise ValueError('Invalid IPv4 Announce response length')
_, _, interval, leechers, seeders = struct.unpack_from(
'!IIIII', response
)
peers = []
for offset in range(20, len(response), 6):
ip = socket.inet_ntoa(response[offset:offset + 4])
port = struct.unpack_from('!H', response, offset + 4)[0]
peers.append((ip, port))
print(f'Announce OK: interval={interval}, '
f'leechers={leechers}, seeders={seeders}')
print(f'IPv4 peers received: {len(peers)}')
for ip, port in peers[:5]:
print(f'{ip}:{port}')
if __name__ == '__main__':
main()运行命令如下,将主机、端口和 Info Hash 替换为实际测试值:
python udp_tracker.py tracker.example.org 6969 0123456789abcdef0123456789abcdef01234567tracker.example.org 是占位域名,不是保证可用的公共 Tracker。实际运行时需要替换为允许访问的 Tracker 域名与 UDP 端口,并提供该 Tracker 可识别的真实资源哈希。
预期结果:在 Tracker 可达、支持 BEP 15 且接受请求的情况下,先打印 Connect OK,随后打印 Announce OK 和收到的 Peer 数量。interval、节点数量与地址取决于 Tracker 当前状态,不能预先固定;即使宣告成功,Peer 数量也可能为 0。
超时重试与事务匹配
UDP 可能丢包、乱序或收到迟到响应。BEP 15 推荐的超时重传间隔按 15 × 2^n 秒递增,n 从 0 开始,对应 15、30、60、120 秒等。实际客户端还应设置总等待上限,避免不可达 Tracker 长期占用任务。
| 情况 | 正确处理 |
|---|---|
| 超时无响应 | 重发同一请求,保留 Transaction ID |
| Transaction ID 不一致 | 忽略,不将响应交给当前请求 |
action 为 3 |
解析错误消息并报告,不按成功响应解析 |
| Connect 响应不足 16 字节 | 判定报文格式错误 |
| Announce IPv4 Peer 区长度非 6 的倍数 | 拒绝按 IPv4 紧凑列表解析 |
| Connection ID 已超过客户端使用窗口 | 重新执行 Connect |
Transaction ID 是请求与响应的关联键,不是身份认证凭据。随机生成它能够降低意外碰撞和盲猜匹配的概率,但不能替代来源校验、网络安全控制或 Tracker 自身的认证机制。
在真实下载器中,同一个 UDP Socket 可以处理多个并发请求,但需要维护以 Tracker 地址和 Transaction ID 为依据的待完成请求表,并分别检查 action 与响应长度。上面的最小示例使用顺序请求,避免引入并发调度细节。
验证报文并定位常见失败
可以使用 Wireshark 观察真实 UDP 数据包。启动抓包后,以实际 Tracker 端口过滤,例如:
udp.port == 6969这是 Wireshark 显示过滤器表达式,不是 Shell 命令。正常交互应观察到一个 16 字节 Connect 请求、一个 16 字节 Connect 响应、一个 98 字节 Announce 请求,以及一个至少 20 字节的 Announce 响应;这里的长度指 UDP 应用负载,不包含 IP 和 UDP 首部。
排查时按以下顺序检查:
- 没有响应:确认 Tracker 域名解析结果、UDP 端口、出口防火墙与 Tracker 是否支持 UDP 协议。
- Connect 成功但 Announce 失败:检查 Connection ID 是否过期,info_hash 和 peer_id 是否均为 20 字节,以及请求是否恰好按 98 字节基础结构编码。
- 收到 action=3:读取响应第 8 字节之后的错误文本,优先处理 Tracker 明确报告的问题。
- 返回 Peer 数量为 0:先确认 Announce 成功,再判断该资源是否有可发现节点,不要直接归因于网络故障。
- 解析出异常 IP 或端口:检查大端序、20 字节响应头偏移,以及 IPv4 每条 6 字节的边界。
一次成功的 UDP Tracker 宣告只证明 Tracker 接受并处理了本次请求,不保证返回的 Peer 一定在线,也不保证后续 TCP 或 uTP 连接成功。客户端应分别记录 Tracker 宣告结果、Peer 连接结果与实际分块交换状态,避免将节点发现成功误判为下载成功。