P2P 与分布式存储 / 系统课时
生成自有测试文件的种子元信息
生成自有测试文件的种子元信息
本课使用 Python 和标准 BitTorrent v1 元信息格式,为一份自有测试文件生成可供客户端加载的 .torrent 文件。完成后,你将得到包含文件长度、分块哈希、Tracker 地址和资源标识的种子元数据,并能核对发布端是否保留完整原始文件。
学习目标
- 选择有分发权限的测试文件,并确定 Piece 大小和 Tracker 地址。
- 生成符合 BitTorrent v1 规范的种子元信息,计算并核对 Info Hash。
- 使用解析脚本和 BitTorrent 客户端验证种子结构及初始完整副本。
准备测试资源与发布参数
建议使用自己生成的二进制文件,避免版权和隐私问题。本例生成一个 1 MiB 的确定性测试文件,所有字节均由固定模式构成,方便重复生成和校验。环境要求为 Python 3.10 或更新版本,无须安装第三方依赖。
在空目录中执行以下命令,生成 sample.bin:
python -c "from pathlib import Path; Path('sample.bin').write_bytes(bytes(range(256)) * 4096); print(Path('sample.bin').stat().st_size)"预期输出:
1048576接下来采用以下发布参数:
| 参数 | 本例取值 | 作用 |
|---|---|---|
| 文件名 | sample.bin | 种子中记录的资源名称 |
| 文件长度 | 1048576 字节 | 与磁盘文件长度一致 |
| Piece 长度 | 262144 字节(256 KiB) | 决定哈希校验和分块数量 |
| Piece 数量 | 4 | 1048576 ÷ 262144 |
| Tracker | http://127.0.0.1:6969/announce | 仅供本机测试的示例地址 |
| private | 省略 | 不声明为私有种子 |
127.0.0.1 仅指向当前机器,并不代表已有 Tracker 服务。若需要让其他设备参与测试,应使用实际可访问且允许该资源宣告的 Tracker 地址;不要将本机回环地址直接发布给其他设备。
理解种子元信息的组成
BitTorrent v1 使用 Bencode 编码字典、列表、整数和字节字符串。单文件种子的顶层字典通常包含 announce 与 info,其中 info 保存文件名称、长度、Piece 长度及连续拼接的 SHA-1 分块摘要。

pieces 字段不是文件内容,而是所有 Piece 的 SHA-1 摘要顺序拼接结果。每个摘要固定 20 字节,因此本例字段长度为 4 × 20 = 80 字节。
Info Hash 的计算对象是 info 字典的完整 Bencode 字节序列,而不是整个 .torrent 文件,也不是原始文件的 SHA-1。对于 v1 种子,它是一个 20 字节摘要,通常显示为 40 位十六进制字符串。改变 info 内的文件名、长度、分块大小或哈希内容都会改变资源标识。
编写种子生成脚本
在测试目录中新建 make_torrent.py。下面的完整示例实现所需的 Bencode 编码、逐块 SHA-1 计算、种子写入与 Info Hash 输出,不依赖特定 BitTorrent 客户端。
from pathlib import Path
import hashlib
SOURCE = Path('sample.bin')
OUTPUT = Path('sample.torrent')
PIECE_LENGTH = 256 * 1024
TRACKER = 'http://127.0.0.1:6969/announce'
def bencode(value):
if isinstance(value, int):
return b'i' + str(value).encode('ascii') + b'e'
if isinstance(value, bytes):
return str(len(value)).encode('ascii') + b':' + value
if isinstance(value, str):
return bencode(value.encode('utf-8'))
if isinstance(value, list):
return b'l' + b''.join(bencode(v) for v in value) + b'e'
if isinstance(value, dict):
# 字典键按原始字节序排序,保证编码确定性。
pairs = sorted(value.items(), key=lambda item: item[0])
return b'd' + b''.join(
bencode(k) + bencode(v) for k, v in pairs
) + b'e'
raise TypeError(f'Unsupported type: {type(value)}')
def main():
if not SOURCE.is_file():
raise FileNotFoundError(SOURCE)
length = SOURCE.stat().st_size
if length == 0:
raise ValueError('测试文件不能为空')
hashes = []
with SOURCE.open('rb') as file:
while block := file.read(PIECE_LENGTH):
# 最后一个 Piece 可以短于标准 Piece 长度。
hashes.append(hashlib.sha1(block).digest())
info = {
b'length': length,
b'name': SOURCE.name.encode('utf-8'),
b'piece length': PIECE_LENGTH,
b'pieces': b''.join(hashes),
}
info_bytes = bencode(info)
metainfo = {
b'announce': TRACKER.encode('utf-8'),
b'info': info,
}
OUTPUT.write_bytes(bencode(metainfo))
print(f'文件长度: {length}')
print(f'Piece数量: {len(hashes)}')
print(f'pieces字节数: {len(info[b"pieces"])}')
print(f'Info Hash: {hashlib.sha1(info_bytes).hexdigest()}')
print(f'种子文件: {OUTPUT.name}')
if __name__ == '__main__':
main()运行:
python make_torrent.py预期输出的固定部分如下;Info Hash 应由实际运行结果取得,不手工填写:
文件长度: 1048576
Piece数量: 4
pieces字节数: 80
Info Hash: <40位十六进制摘要>
种子文件: sample.torrent这里的尖括号内容是输出格式说明,并非程序实际打印的文本。生成器会在当前目录创建 sample.torrent。如果文件内容或元信息发生变化,Info Hash 也可能随之变化。
核对元信息与文件完整性
生成种子并不等于文件已成功分发。首先应独立检查元信息字段,并使用原始文件重新计算每个 Piece 的摘要。
在同一目录新建 verify_torrent.py,以下脚本针对本课生成的单文件 v1 种子进行验证:
from pathlib import Path
import hashlib
def decode(data, pos=0):
token = data[pos:pos + 1]
if token == b'i':
end = data.index(b'e', pos)
return int(data[pos + 1:end]), end + 1
if token == b'l':
result, pos = [], pos + 1
while data[pos:pos + 1] != b'e':
value, pos = decode(data, pos)
result.append(value)
return result, pos + 1
if token == b'd':
result, pos = {}, pos + 1
while data[pos:pos + 1] != b'e':
key, pos = decode(data, pos)
value, pos = decode(data, pos)
result[key] = value
return result, pos + 1
if b'0' <= token <= b'9':
colon = data.index(b':', pos)
size = int(data[pos:colon])
start = colon + 1
return data[start:start + size], start + size
raise ValueError('无效Bencode数据')
def main():
raw = Path('sample.torrent').read_bytes()
meta, end = decode(raw)
assert end == len(raw)
info = meta[b'info']
source = Path(info[b'name'].decode('utf-8'))
length = info[b'length']
piece_size = info[b'piece length']
hashes = info[b'pieces']
assert piece_size > 0
assert source.stat().st_size == length
expected_count = (length + piece_size - 1) // piece_size
assert len(hashes) == expected_count * 20
# 将实际文件逐块计算的摘要与种子记录逐一比较。
with source.open('rb') as file:
for index in range(expected_count):
block = file.read(piece_size)
digest = hashlib.sha1(block).digest()
assert digest == hashes[index * 20:(index + 1) * 20]
print('Tracker:', meta[b'announce'].decode('utf-8'))
print('文件长度:', length)
print('Piece数量:', expected_count)
print('全部Piece校验通过')
if __name__ == '__main__':
main()运行:
python verify_torrent.py预期输出:
Tracker: http://127.0.0.1:6969/announce
文件长度: 1048576
Piece数量: 4
全部Piece校验通过这个脚本用于验证本例生成的数据,不是面向不可信种子文件的安全解析器;它未实现完整的 Bencode 格式约束、资源限制和路径安全检查。生产环境应使用成熟的解析库,并拒绝不安全的文件路径。
检查初始 Seeder 与常见故障
元信息文件仅记录资源如何定位与校验,不包含实际的 1 MiB 文件内容。发布端必须保留完整原始文件,并让 BitTorrent 客户端识别它,才能成为初始 Seeder。
使用支持 BitTorrent v1 的客户端(例如 qBittorrent)完成以下检查:
- 将
sample.torrent导入客户端,选择已有sample.bin所在目录作为保存位置。不同客户端版本的导入对话框名称可能略有差异。 - 如果客户端将文件识别为未完成,执行强制重新校验(Force Recheck),而不是直接重新下载覆盖原始文件。
- 确认完成度为 100%,状态可以进入做种状态,并核对客户端显示的文件大小及 Info Hash。
- 若要实际测试节点发现和上传,启动可访问的 Tracker 或配置允许的其他发现机制,再使用第二个受控客户端连接并下载。

| 现象 | 优先检查 | 修正方法 |
|---|---|---|
| 导入后提示文件缺失 | 保存目录与文件名 | 指向已有文件所在目录,确认文件名一致 |
| 校验无法达到100% | 文件内容和Piece哈希 | 恢复原始文件后重新校验,必要时重新制作种子 |
| Tracker连接失败 | 地址、端口和服务状态 | 确认Tracker实际运行且网络可达 |
| 已完成但没有上传 | 是否存在下载方、节点发现和连接可达性 | 使用第二个受控Peer发起下载并检查连接 |
| Info Hash不一致 | info 字典字段和编码 |
比较文件名、长度、Piece大小与哈希数据 |
本例最终应保留 sample.bin 与 sample.torrent 两个文件,并记录生成时的 Info Hash。只有元信息校验通过、发布端完整持有文件且测试下载方能成功取得并校验全部 Piece,才算完成一次可复现的测试资源发布。