协议总览与最小实现
1. 快速概览(Quick overview)
- NodeStone Compass Protocol (NCP):一套开放的资源分发协议,设计上支持任意资源的分发。
- NodeStone Compass 服务:NodeStone 官方基于该协议维护的元数据源,提供 Minecraft 本体、ModLoader 及 Mod 的下载索引。
- NodeStone BT:基于 BitTorrent v2(BEP-52) 的分发机制。
- NodeStone SDK:官方提供的开发包,方便第三方启动器接入。
核心术语:
- NSCL(NodeStone Compass List):元数据清单文件(
latest.json),体积约 20 KB,包含入口索引映射与种子/直出文件获取方式。 - NSCI(NodeStone Compass Index):
NSFID -> Target Hash的核心映射表。 - NSFID(NodeStone File ID):文件唯一标识,分为
url:<Base64>(当前启用)和sha256:<Hex>(未来预留)两种格式。
工作流程
启动器先从 NodeStone 官方源或镜像源下载 latest.json(约 20 KB),校验 minisign 签名和 revision 版本号后,把里面的 nsci.raw_kv 映射写入本地 NSCI 缓存(重复 Key 即覆盖)。
打包 MC 资源时,服务端遵循**「可变清单现场直出、不可变版本分包做种」**的原则:
- 高频变化的顶层清单(如
version_manifest_v2.json):强制采用delivery.integrated的raw_file模式内嵌直出,不生成.torrent种子,也不在客户端.nodestone/下按 Hash 持久化留存历史缓存副本,而是在请求时现场解码校验并直接交付。 - 不可变游戏版本包(
minecraft-version-<ver>):每个已发布版本对应一个独立的 BitTorrent v2(BEP-52) 种子,直接包含该版本的<version>.json、client.jar、该版本依赖的全部libraries、对应的<asset_index>.json以及该版本关联的全部assets/objects资源文件。不同版本种子之间天然允许包含相同 URL 的公共libraries和assets文件(由于.torrent文件本身仅约 300 KB 且已在本地或瞬间拉取,公共文件的NSFID指向任意一个包含它的版本种子均可正常完成 BT / WebSeed 下载)。 latest.json的nsci.raw_kv不需要记录海量小文件,只需收录version_manifest_v2.json和各个版本的<version>.json的NSFID -> Hash。客户端请求<version>.json时,会自动拉下该版本的种子并将里面所有的client.jar、libraries、<asset_index>.json和assets映射一次性批量展开到本地缓存。
预配置 (provider.urls / namespace / minisign_keys / version_manifest 的 NSFID)
│
▼ 1. 拉取并校验 latest.json + minisign + revision
NSCL (latest.json)
├─ nsci.raw_kv : NSFID -> Hash (64-hex BT v2 InfoHash 或 raw_file 的 SHA-256)
└─ assets.torrents : Hash -> delivery (integrated / url / magnetic)
│
▼ 2. 合并至本地 NSCI 缓存 nsci_cache (重复 Key 即覆盖)
本地 NSCI 缓存 (NSFID -> Target Hash)
│
├─► 请求 version_manifest_v2.json (命中 raw_file)
│ └─ 现场从 latest.json Base64 解码并校验 SHA-256(不在 .nodestone/ 下留存历史缓存副本),直接交付返回 DirectFile(local_path)
│
└─► 请求 <version>.json (命中 BT v2 版本种子)
└─ 首次拿到种子 (.nodestone/torrents/<torrenthash>.torrent) 后展开 file tree:
提取 info.file tree 与 ns-schemes -> 路径段 RFC 3986 编码拼出官方 URL -> Base64 编码为 NSFID
批量写入本地 NSCI 缓存 (一次性展开 client.jar、libraries、<asset_index>.json 及全部 assets),返回 Torrent(torrent_meta)
这样一来,启动器下载 <version>.json 时,就会顺带把该版本所有的 client.jar、libraries、<asset_index>.json 和 assets 映射一次性写进本地缓存。启动器上层全程只管传入 Mojang 官方 URL,底层会自动把请求映射到对应的现场直出载荷或 BT 种子。
2. 最小实现(Minimal implementation)
1. 预配置常量
provider.namespace(string):命名空间(例如 Minecraft 本体为minecraft)。provider.urls(list/string):NSCL 文件的 HTTP(S) 源地址列表。provider.minisign_keys(list/string):minisign 公钥列表(例如RWSDsxUzF3dwx5sVM6sxlIE1S2HzTJtaOtEOSKQiX6ArWc7u3hcDcaTk)。
2. NodeStone File ID(NSFID)的格式
为了避免 URL 里的特殊字符(如 ?、&、=、%、空格或方括号)在不同语言库里解析出不同的转义结果,URL 类型的 NSFID 在编码前必须严格执行 RFC 3986 Section 6.2.2(Syntax-Based Normalization) 标准 URL 规范化:
- 协议与主机名小写化:将
scheme与host转为小写(如HTTPS://Piston-Meta.Mojang.com转为https://piston-meta.mojang.com)。 - 移除默认端口:去掉协议对应的默认端口(
http移除:80,https移除:443)。 - 百分号编码规范化:对路径中除 RFC 3986 非保留字符(Unreserved Characters:
ALPHA / DIGIT / "-" / "." / "_" / "~")及路径分隔符/以外的字符执行 UTF-8 百分号编码,将所有百分号编码(Percent-Encoding)的十六进制字母统一转为大写(如%2f转为%2F),并对所有已被多余转义的非保留字符执行百分号解码。 - 路径段折叠:执行
remove_dot_segments折叠路径中的/./与/../。
完成规范化后,统一用标准 Base64(RFC 4648,UTF-8 编码,保留末尾 = 填充,不换行)编码:
- 格式 1(当前启用):
url:<Base64(规范化后的官方源完整原始 URL)>- 例如
https://piston-meta.mojang.com/mc/game/version_manifest_v2.json编码后为:url:aHR0cHM6Ly9waXN0b24tbWV0YS5tb2phbmcuY29tL21jL2dhbWUvdmVyc2lvbl9tYW5pZmVzdF92Mi5qc29u
- 例如
- 格式 2(未来预留,v0.9.0 暂不启用):
sha256:<此文件的 64 位小写十六进制 SHA-256 值>
3. 获取与校验索引
- 下载清单:从
<provider.urls[i]>/v09/<provider.namespace>/latest.json下载清单文件,并下载同路径下的签名文件latest.json.minisig。 - 签名校验:用预配置的
provider.minisign_keys校验latest.json文件签名,并建议同时核对签名中的trusted comment包含<provider.namespace>;校验失败就换下一个源。 - 字段校验:把 JSON 解析为
latest,检查以下三项:filetype必须为"nscl/v0.9"。namespace必须与<provider.namespace>一致。revision必须大于或等于本地已缓存的revision(防止滞后的镜像源用旧版合法签名造成回滚)。
- 写入本地 NSCI 缓存:读取
latest.nsci.raw_kv,将NSFID -> Hash键值对按「重复即覆盖(Upsert)」的方式写入本地 NSCI 缓存(仅更新torrenthash,保留已有的rel_path与orig_url)。
4. 从种子 file tree 还原 URL 与 WebSeed 下载
BitTorrent v2 种子的 InfoHash 是 info 字典的 SHA-256 值(64 位小写十六进制字符串),目录结构存在 info["file tree"] 中。
在 NCP 中,无论是单文件种子还是跨多个官方域名的多文件种子,打包时统一把官方源规范化后的完整主机名(<host>[:<port>])作为 info["file tree"] 的第一级目录,后续层级对应百分号解码(Unescaped)后的原始 UTF-8 路径段与文件名;协议头列表则存放在 info["ns-schemes"](同时兼容顶层 ns-schemes,缺省为 ["https://"])。
- 拼接官方 URL 与生成 NSFID:
设文件在
info["file tree"]中的各级目录与文件名列表为[host_port, seg_1, seg_2, ...]:- 磁盘相对路径
rel_path由各级原始名称用/拼接(如libraries.minecraft.net/com/mojang/logging/1.1.1/logging-1.1.1.jar)。 - 读取协议列表
schemes = torrent["info"].get("ns-schemes") or torrent.get("ns-schemes") or ["https://"](注意:严禁回退读取url-list)。 - 将除第一级
host_port外的每个路径段按 RFC 3986 规范做百分号编码(urllib.parse.quote(seg, safe="-._~")),再与规范化后的scheme("https://"或"http://")和host_port.lower()拼接出规范化的orig_url。 - 按第 2 节规则对
orig_url做 UTF-8 Base64 编码得到url:<Base64>格式的NSFID,按「重复即覆盖」写入本地 NSCI 缓存:NSFID -> (torrenthash, rel_path, orig_url)。
- 磁盘相对路径
- SDK 接管 WebSeed 下载与 BT 引擎配置:
- 底层 BT 引擎必须启用 BEP-5(DHT)、BEP-11(PEX) 和 BEP-14(LSD)。
- 底层 BT 引擎挂载种子时,必须禁用 BT 引擎自带的顶层多文件 BEP-19
url-listWebSeed(避免引擎把info["name"]拼进域名导致请求报错)。 - 当某个文件或分块需要用 WebSeed 辅助下载或 P2P 超时回退时,由 SDK 通过本地 HTTP 307 路由代理或引擎层 URL 拼接补丁将请求指向还原出的
orig_url,直接复用 BT 引擎的 BEP-52pieces root/piece layersMerkle 树校验与落盘逻辑(详见《客户端推荐实现》第 4 节)。
import base64
from urllib.parse import quote
def expand_filetree_to_nsci(torrent: dict, torrenthash: str, nsci_cache: dict):
info = torrent["info"]
# parse_btv2_file_tree_segments 返回形如 [["libraries.minecraft.net", "com", "mojang", ...], ...] 的路径段列表
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]
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}"
nsci_cache[nsfid] = (torrenthash, rel_path, orig_url)
5. 核心方法定义
为避免 .torrent 种子与 raw_file 内嵌直出文件在调用链路上产生类型冲突,nsGetTorrent 的返回值明确区分为以下两种可辨识联合类型(Tagged Union / Enum):
DeliveryResult::Torrent(torrent_meta):表示目标为标准 BT v2 种子,返回已校验并完成file tree展开的种子元数据对象(及本地.torrent路径)。DeliveryResult::DirectFile(local_path):表示目标为integrated.type == "raw_file"的内嵌纯独立单文件,返回现场解码并校验 SHA-256 后的文件落盘路径。
方法定义:
-
nsGetTorrent(latest, torrenthash, target_path=None) -> DeliveryResult:获取种子文件(或现场提取内嵌直出单文件)。- 检查本地缓存
.nodestone/torrents/<torrenthash>.torrent,如果文件存在且 InfoHash v2 校验通过(且在本地torrents_state表中已标记is_expanded == 1),直接返回DeliveryResult::Torrent(torrent_meta)。 - 如果本地没有该
.torrent(或目标为raw_file),按顺序检查latest.assets.torrents[torrenthash].delivery(若内存中尚无latest或当前latest.assets.torrents中未找到该torrenthash,则先现场拉取一次最新latest.json更新nsci_cache):delivery.integrated:- 当
integrated.type为"torrent"(或未填)时:Base64 解码integrated.payload得到.torrent内容,校验 InfoHash v2 等于torrenthash后保存到.nodestone/torrents/<torrenthash>.torrent,按步骤 3 展开file tree后返回DeliveryResult::Torrent(torrent_meta)。 - 当
integrated.type为"raw_file"时(协议强制约束:仅允许用于不包含任何下游子文件映射依赖的纯独立单文件,如version_manifest_v2.json):现场对integrated.payload进行 Base64 解码得到目标单文件本体,校验文件整体线性 SHA-256 等于torrenthash后,直接写入调用方指定的target_path(或固定的单文件临时覆写路径),返回DeliveryResult::DirectFile(local_path)。严禁在.nodestone/下按<torrenthash>持久化缓存raw_file历史副本,以免产生额外的缓存生命周期管理负担;无需走 BT 引擎,也无需执行步骤 3。
- 当
delivery.url:通过 HTTP(S)/FTP 下载.torrent文件,校验 InfoHash v2 后保存到.nodestone/torrents/<torrenthash>.torrent,按步骤 3 展开file tree后返回DeliveryResult::Torrent(torrent_meta)。delivery.magnetic:通过磁力链接(xt=urn:btmh:1220<torrenthash>&tr=...)拉取种子并校验,按步骤 3 展开file tree后返回DeliveryResult::Torrent(torrent_meta)。注意:支持delivery.magnetic的客户端,其 BT 引擎必须启用 BEP-5 (DHT)、BEP-11 (PEX)、BEP-14 (LSD) 并实现 BEP-52 的hash request/hashes扩展消息以拉取piece layers。
- 首次获取到
Torrent类型种子时,必须按第 4 节规则遍历info["file tree"]还原出orig_url和NSFID,与torrents_state的is_expanded = 1状态在同一事务内写入本地缓存数据库后再返回DeliveryResult::Torrent(torrent_meta)。
- 检查本地缓存
-
nsGetFile(aNSFID, contextEntryNSFIDs=None, target_path=None) -> LocalFilePath:获取单个文件。- 在本地
nsci_cache中查找aNSFID对应的(torrenthash, rel_path, orig_url)。如果未查到,执行自愈流程(见《客户端推荐实现》第 3 节)。 - 调用
res = nsGetTorrent(latest, torrenthash, target_path=target_path)(注意:若torrenthash指向的是旧版raw_file,导致步骤 2 触发了latest.json刷新并更新了nsci_cache中aNSFID的torrenthash,则用更新后的新torrenthash重新提取):- 若
res为DeliveryResult::DirectFile(local_path),直接返回local_path。 - 若
res为DeliveryResult::Torrent(torrent_meta),进入步骤 3。
- 若
- 从
nsci_cache取出aNSFID对应的(rel_path, orig_url)(注:若aNSFID恰好是首次下载的<version>.json入口文件,在步骤 1 查库时rel_path尚未填充,步骤 2 首次展开种子后rel_path与orig_url即已在nsci_cache中补齐),通过 BT v2 及 WebSeed 下载文件,校验通过后返回本地路径。
- 在本地