客户端推荐实现
本文档在《概览与最小实现》的基础上,说明实际工程接入时推荐的批量下载调度、缓存未命中自愈闭环、WebSeed 桥接实现以及极简本地缓存管理策略。
1. 三条基本原则
- 本地缓存存的必须是真实的
NSFID -> hash映射:不管是来自latest.json的入口记录,还是从种子file tree展开出来的子文件记录,Key 都必须是符合 RFC 3986 Section 6.2.2 规范的url:<Base64>(或未来启用的sha256:<Hex>),Value 为 64 位小写十六进制哈希。注意:第三方启动器向 NCP SDK 传入 URL 时,必须传入未经过第三方镜像源(如 BMCLAPI)替换的 Mojang/官方源原始 URL。 - 种子落盘与
file tree展开必须视为同一事务:首次下载某个.torrent文件并落盘时,必须同步把它的file tree展开写入本地持久化数据库nsci_cache表,并在同一数据库事务内将torrents_state.is_expanded置为1,两边都成功才算种子获取完成。 raw_file现场直出,不在.nodestone/中留存历史缓存:对于version_manifest_v2.json等高频可变raw_file,每次请求时直接从当前latest.json现场解码并校验 SHA-256 后交付(不在.nodestone/下按<torrenthash>持久化缓存),从而彻底省去可变单文件的缓存清理与生命周期管理。
2. 批量获取优化(nsGetFilesBatch)
启动器解析完 <version>.json 和 <asset_index>.json 后,通常要一次性下载成百上千个 libraries 和 assets 小文件。由于不同版本的种子之间允许包含相同 URL 的公共 libraries 和 assets 文件,在 nsci_cache 的「重复即覆盖(Upsert)」机制下,公共文件指向任意一个包含它的已展开版本种子均符合协议预期并可正常下载。
为避免逐个调用 nsGetFile 产生重复查库和调度开销,推荐优先实现并使用批量接口 nsGetFilesBatch(nsfidList, contextEntryNSFIDs=None):
- 批量查库:一次性在本地
nsci_cache表中查询nsfidList中所有项的(torrenthash, rel_path, orig_url)。如果有任何一个NSFID未命中(或仅有入口torrenthash但rel_path尚未展开填充),先执行第 3 节的自愈流程;自愈后重新查库,若仍有未命中项则中止并报错。 - 按目标哈希分组:把命中的请求按
torrenthash聚合为Map<torrenthash, List<(NSFID, rel_path, orig_url)>>。 - 按组批量获取与提交下载:对每个去重后的
torrenthash调用一次nsGetTorrent(latest, torrenthash):- 若返回
DeliveryResult::DirectFile(local_path)(仅针对raw_file独立单文件),直接将该组内NSFID映射至local_path。 - 若返回
DeliveryResult::Torrent(torrent_meta)(通常在前一步下载<version>.json时种子就已经在本地了),把该组内的目标文件列表一次性提交给 BT 引擎设置文件优先级,并配合第 4 节的 WebSeed 机制并发或按需回退拉取。
- 若返回
- 交付结果:全部完成后返回
Map<NSFID, LocalFilePath>,或者通过完成回调每下完一个文件通知一次上层启动器。
3. 缓存未命中的排查与四步自愈闭环
实际接入时,很多第三方启动器自己带有本地文件缓存(比如 .minecraft/versions/<ver>/<ver>.json 已经在硬盘上了)。如果用户删过 .nodestone/ 目录、旧启动器中途刚接入 NCP SDK,或者上次展开种子时意外退出,启动器就会跳过下载 <version>.json,直接读本地已有的 JSON 去调 nsGetFile / nsGetFilesBatch 请求里面的 libraries、<asset_index>.json 和 assets,导致本地 nsci_cache 查不到记录。
遇到未命中时,客户端按顺序执行以下四步自愈:
第一步:URL 规范化重算
把未命中的 url:<Base64> 解码回原始 URL,严格按照 RFC 3986 Section 6.2.2(Syntax-Based Normalization) 检查是否存在协议或域名大写、带了默认端口(:80 / :443)、百分号编码十六进制大小写不一致(应统一为大写 %XX)、非保留字符被多余转义、特殊字符(如空格、方括号)未转义或路径存在 /./、/../ 的问题。规范化后重新编码出 NSFID,再查一次本地 nsci_cache。
第二步:按上下文入口(contextEntryNSFIDs)调用 nsGetFile 补齐并展开版本种子
启动器在调用 nsGetFile(aNSFID, contextEntryNSFIDs) 或 nsGetFilesBatch(nsfidList, contextEntryNSFIDs) 下载某个版本的依赖文件时,应在 contextEntryNSFIDs 参数里带上当前任务的顶层入口文件 NSFID(即当前版本 <version>.json 的 NSFID)。
当子文件未命中时,SDK 遍历 contextEntryNSFIDs 中的每个 entryNSFID:
- 检查
entryNSFID在nsci_cache中对应的torrenthash是否已在torrents_state中标记为is_expanded == 1。 - 若未查到或未展开,直接调用
nsGetFile(entryNSFID, contextEntryNSFIDs=None):- 若此时
.nodestone/刚被清空或服务端刚发布了新版本(导致entryNSFID自身在nsci_cache中也未命中),该次nsGetFile(entryNSFID, contextEntryNSFIDs=None)会自然进入第三步刷新latest.json,将最新入口映射写入nsci_cache; - 随后
nsGetFile内部调用nsGetTorrent下载对应的版本种子,并将种子内的info["file tree"]全量展开写入nsci_cache(置is_expanded = 1)。 - 注意:自愈内部调用
nsGetFile(entryNSFID)时必须将contextEntryNSFIDs设为None,防止递归死循环。
- 若此时
只要传入了 contextEntryNSFIDs,哪怕 .nodestone/ 目录刚被彻底清空,这一步通过直接调用 nsGetFile(entryNSFID) 也能形成完整闭环,把该版本的所有子文件索引一次性补齐。
第三步:扫描本地未展开的种子与刷新 latest.json
- 如果调用方没传
contextEntryNSFIDs(或当前正在查找的就是entryNSFID本身):- 先扫描本地
.nodestone/torrents/目录,把已经下载到本地、但在torrents_state中尚未标记is_expanded == 1的.torrent文件补跑一次file tree展开。 - 如果还是未命中,且距离上次拉取
latest.json已经超过冷却间隔(例如 60 秒,或本地nsci_cache为空),就从provider.urls重新拉取一次最新revision的latest.json更新nsci_cache入口映射(应对 Mojang 刚刚发布新版本或.nodestone/刚被清空的场景)。
- 先扫描本地
第四步:明确报错并由上层决定是否回退直连
如果走完前三步还是查不到(比如启动器传入了一个根本不在官方源里的第三方文件 URL),不要静默吞掉错误,应当向上层抛出带有 (orig_url, nsfid, local_revision) 的未命中异常,由启动器记录告警日志,并由启动器决定是中止任务还是回退到普通的 HTTPS 直连下载。
4. WebSeed 推荐实现(复用 BT 引擎原生调度与 BEP-52 校验)
在标准 BEP-19(HTTP/FTP Seeding)规范中,BT 引擎请求多文件种子的 WebSeed 时,会自动将末尾带 / 的 url-list、种子名 info["name"] 和文件树内相对路径 rel_path 拼接为:
<url-list><info.name>/<rel_path>
而在 NCP 种子中,rel_path 第一级目录固定为官方源主机名(如 libraries.minecraft.net/com/mojang/... 或 piston-data.mojang.com/v1/...)。如果直接在顶层 url-list 填入 "https://",原生 BT 引擎会把 info["name"](如 minecraft-version-1.21.4)拼到域名位置导致 DNS 解析失败。
为了完全免去 SDK 手写 HTTP 分块 Range 请求与 BEP-52 Merkle Tree 哈希校验的复杂度,同时 100% 复用底层 BT 引擎现成的 P2P/WebSeed 混合调度、Merkle 校验与即时做种能力,推荐客户端根据自身技术栈从以下两种实现方案中任选其一:
实现方案 C-1:SDK 本地极简 HTTP 307 路由代理(零 BT 引擎源码修改,通用推荐)
适用于直接引入现成第三方 BT 库(如预编译的 libtorrent-rasterbar、Rust rqbit、Go anacrolix/torrent 等)而不希望修改 BT 引擎源码的客户端:
- 挂载带
<torrenthash>与末尾斜杠的本地环回 WebSeed: SDK 在本地环回地址启动一个极轻量的 HTTP/1.1 路由服务,在挂载.torrent时先清空种子可能携带的url-list,再调用 BT 引擎 API 将http://127.0.0.1:<port>/webseed/<torrenthash>/(注意末尾必须带/,确保根据 BEP-19 规范无论是单文件还是多文件种子均在末尾追加路径)注册为该种子的标准 BEP-19 WebSeed(例如torrent_handle.add_url_seed(...))。 - 剥离
/<info.name>/并返回307 Temporary Redirect: 当 BT 引擎判定某个文件或分块需要通过 WebSeed 下载时,会按照标准 BEP-19 向本地端口发起GET或HEAD请求(自动携带Range: bytes=<start>-<end>头):GET /webseed/<torrenthash>/<info.name>/<rel_path>本地路由服务收到请求后无需代理转发文件流,只需:- 根据
<torrenthash>查找该种子的ns-schemes(默认"https://"); - 剥离前缀
/webseed/<torrenthash>/<info.name>/提取出<rel_path>,先对路径做unquote解码再按 RFC 3986 重新编码各路径段(保留第一级<host>[:<port>]),拼上协议头得到官方真实直链orig_url(或按需在此处通过前缀替换表映射至兼容的镜像源 URL); - 立即返回 HTTP
307 Temporary Redirect(严格保持原请求方法GET/HEAD与Range头不变):Location: https://<rel_path>
- 根据
- BT 引擎自动跟随重定向并完成 Merkle 校验:
BT 引擎内置的 WebSeed 客户端会自动携带原
Range头跟随 307 重定向至 Mojang 官方 CDN 拉取数据块,并在引擎内部自动完成 BEP-52 的pieces root/piece layersMerkle 树校验、落盘及向其他 Peer 广播做种。
from http.server import BaseHTTPRequestHandler
from urllib.parse import unquote, quote
class NcpWebSeedRedirectHandler(BaseHTTPRequestHandler):
protocol_version = "HTTP/1.1"
# torrent_schemes_map: dict[torrenthash, list[str]],记录各挂载种子的 ns-schemes
torrent_schemes_map = {}
def _handle_redirect(self):
# 请求路径格式: /webseed/<torrenthash>/<info.name>/<host>/<path...>
path_only = self.path.split("?", 1)[0]
parts = path_only.lstrip("/").split("/", 3)
if len(parts) < 4 or parts[0] != "webseed":
self.send_error(404, "Invalid NCP WebSeed path")
return
_, torrenthash, _info_name, raw_rel_path = parts
schemes = self.torrent_schemes_map.get(torrenthash) or ["https://"]
raw_scheme = schemes[0].strip().lower().rstrip(":/")
scheme = f"{raw_scheme}://" if raw_scheme in ("http", "https") else "https://"
# 将 BT 引擎发来的路径解码后按 RFC 3986 规范化编码,防止二次转义或特殊字符失配
rel_segments = [unquote(seg) for seg in raw_rel_path.split("/")]
host_port = rel_segments[0].strip().lower()
encoded_path = "/".join(quote(seg, safe="-._~") for seg in rel_segments[1:])
target_url = f"{scheme}{host_port}/{encoded_path}"
self.send_response(307)
self.send_header("Location", target_url)
self.send_header("Content-Length", "0")
self.end_headers()
def do_GET(self):
self._handle_redirect()
def do_HEAD(self):
self._handle_redirect()
实现方案 C-2:BT 引擎 URL 拼接层微补丁(适合自编译 BT 引擎的官方/原生 SDK)
适用于自行编译维护底层 BT 引擎(如自编译 C++ libtorrent-rasterbar 或定制 Rust BT 引擎)的 SDK:
- 识别 NCP 种子标志:
在 BT 引擎加载种子元数据时,检查
info["ns-schemes"](或顶层ns-schemes)字段是否存在(例如["https://"])。 - 跳过
info["name"]直接拼接scheme + rel_path: 在 BT 引擎构造 BEP-19 多文件 WebSeed 请求 URL 的函数处(例如libtorrent::web_peer_connection的 URL 组装逻辑),增加分支判断:当种子开启了 NCP WebSeed 模式时,不再拼接info["name"]目录层级,而是直接取ns-schemes[0](如"https://")与文件在info["file tree"]中经 RFC 3986 路径段编码后的相对路径rel_path(即<host>/<path>)拼接为完整目标 URL。 - 原生直连跨域名官方源:
补丁生效后,即便同一个多文件种子内同时包含
piston-data.mojang.com、libraries.minecraft.net和resources.download.minecraft.net的文件,BT 引擎内置的 WebSeed 调度器也能直接向对应的官方域名发起 HTTPSGET/Range请求并自动完成 BEP-52 Merkle 校验。
5. 本地缓存管理与清理设计
在 NCP v0.9.0 中,得益于两项核心设计:
- 可变清单现场直出:
version_manifest_v2.json等高频变化单文件强制使用delivery.integrated.type = "raw_file"直出,不在.nodestone/下生成种子或留存历史缓存副本; - 版本种子 100% 不可变且单种子仅约 300 KB:所有生成
.torrent的资源均为已发布的不可变版本全量包(minecraft-version-<ver>)。即便只下载或保留全部正式版的.torrent种子文件,总元数据体积也仅约 20 MB,相对于游戏本体可谓九牛一毛;且不同版本间的公共libraries和assets指向任意一个包含它的已展开种子均可正常下载(串包亦完全符合协议预期)。
因此,客户端无需维护复杂的三表外键级联或引用计数机制,只需采用极简的 nsci_cache 单主键 Upsert 表配合 torrents_state 状态表即可。
1. 数据库表结构与 Upsert 规范
建议使用 SQLite(存放在 .nodestone/cache/nsci.db)持久化本地缓存,连接时建议开启 PRAGMA journal_mode = WAL; 与 PRAGMA busy_timeout = 5000; 以提升并发读写稳定性:
PRAGMA journal_mode = WAL;
PRAGMA busy_timeout = 5000;
-- 1. 客户端全局元数据表(记录 local_revision、last_fetched_at 等状态)
CREATE TABLE IF NOT EXISTS meta_state (
key TEXT PRIMARY KEY,
value TEXT NOT NULL
);
-- 2. 本地种子展开状态表(记录每个 torrenthash 的 file tree 是否已展开完成)
CREATE TABLE IF NOT EXISTS torrents_state (
torrenthash TEXT PRIMARY KEY,
is_expanded INTEGER NOT NULL DEFAULT 0, -- 0: 未展开, 1: file tree 已完整展开至 nsci_cache
updated_at INTEGER NOT NULL
);
-- 3. NSCI 核心映射缓存表(单主键 Upsert,重复即覆盖)
CREATE TABLE IF NOT EXISTS nsci_cache (
nsfid TEXT PRIMARY KEY,
torrenthash TEXT NOT NULL,
rel_path TEXT,
orig_url TEXT
);
CREATE INDEX IF NOT EXISTS idx_nsci_torrenthash ON nsci_cache(torrenthash);
- 刷新
latest.json(同步nsci.raw_kv)时: 在同一事务中更新meta_state的local_revision并 Upsertnsci_cache(使用ON CONFLICT(nsfid) DO UPDATE仅更新torrenthash,从而保留已展开的<version>.json原本的rel_path与orig_url):INSERT INTO nsci_cache (nsfid, torrenthash)VALUES (?, ?)ON CONFLICT(nsfid) DO UPDATE SETtorrenthash = excluded.torrenthash; - 展开种子
info["file tree"]时: 将展开出的(nsfid, torrenthash, rel_path, orig_url)与torrents_state.is_expanded = 1在同一个数据库事务中原子提交:
import base64
import time
from urllib.parse import quote
def expand_filetree_to_db(torrent: dict, torrenthash: str, db_conn):
info = torrent["info"]
path_segments_list = parse_btv2_file_tree_segments(info["file tree"])
schemes = info.get("ns-schemes") or torrent.get("ns-schemes") or ["https://"]
if isinstance(schemes, str):
schemes = [schemes]
records = []
for segments in path_segments_list:
host_port = segments[0].strip().lower()
rel_path = "/".join([host_port] + segments[1:])
encoded_path = "/".join(quote(seg, safe="-._~") for seg in segments[1:])
for raw_scheme in schemes:
clean = raw_scheme.strip().lower().rstrip(":/")
scheme = f"{clean}://" if clean in ("http", "https") else "https://"
orig_url = f"{scheme}{host_port}/{encoded_path}"
b64 = base64.b64encode(orig_url.encode("utf-8")).decode("ascii")
nsfid = f"url:{b64}"
records.append((nsfid, torrenthash, rel_path, orig_url))
now_ts = int(time.time())
with db_conn:
db_conn.execute(
"""
INSERT INTO torrents_state (torrenthash, is_expanded, updated_at)
VALUES (?, 1, ?)
ON CONFLICT(torrenthash) DO UPDATE SET
is_expanded = 1,
updated_at = excluded.updated_at
""",
(torrenthash, now_ts)
)
db_conn.executemany(
"""
INSERT INTO nsci_cache (nsfid, torrenthash, rel_path, orig_url)
VALUES (?, ?, ?, ?)
ON CONFLICT(nsfid) DO UPDATE SET
torrenthash = excluded.torrenthash,
rel_path = excluded.rel_path,
orig_url = excluded.orig_url
""",
records
)
2. 本地种子的常驻做种与按需重置
- 推荐常驻保留已获取的
.torrent种子: 由于每个正式版.torrent种子体积很小且永久不可变,推荐客户端默认常驻保留.nodestone/torrents/<torrenthash>.torrent及nsci_cache中的展开记录。这样不仅能让任何指向该种子的公共文件随时秒级命中,还能最大化 P2P 做种覆盖面。 - 清理或重置缓存时的注意事项:
- 若客户端需要停止某个旧版本种子的后台做种任务以释放内存或句柄,只需从 BT 引擎中移除该
torrent_handle即可,必须保留磁盘上的.torrent文件与nsci_cache数据库记录(因为其他版本的公共libraries/assets在nsci_cache中可能正指向该torrenthash;保留.torrent文件即可在下次请求公共文件时直接从本地挂载种子并按需下载该单文件)。 - 禁止单独删除单个
.torrent文件或单条torrents_state记录:若用户主动执行「清空缓存」,应整体清空.nodestone/torrents/目录并重置nsci.db(nsci_cache与torrents_state),切勿只删磁盘.torrent文件而留存nsci_cache中的悬空指针。
- 若客户端需要停止某个旧版本种子的后台做种任务以释放内存或句柄,只需从 BT 引擎中移除该