服务端推荐实现
本文档将服务端打包(Packer)、NSCL(latest.json)清单生成、可变/不可变资源投递策略以及签名发布要求统一收拢,作为 NodeStone Compass 官方源与第三方镜像源构建服务端的工程规范。
1. 资源分类与投递策略(可变清单 vs 不可变版本种子)
服务端在构建某个命名空间(以 minecraft 为例)的分发索引时,必须严格区分**「高频可变顶层入口文件」与「不可变版本资源包」**,采用不同的投递策略:
1. 高频变化的纯独立单文件(强制使用 raw_file)
- 适用对象:URL 固定不变、但内容随每次版本发布而更新、且自身不需要展开任何下游子文件 NSCI 映射的顶层入口文件(例如 Mojang 的
version_manifest_v2.json)。 - 投递要求:
- 服务端必须使用
delivery.integrated.type = "raw_file"直接将文件本体进行 Base64 编码后内嵌在latest.json中。 - 该条目在
nsci.raw_kv中的 Value(Hash)为该文件本体的 64 位小写十六进制整体线性 SHA-256。 - 禁止为高频变化文件生成
.torrent种子:这样可以彻底避免服务端每次更新都产生新的废弃.torrent和做种任务,同时让客户端每次请求时直接从latest.json现场解码交付,无需在.nodestone/下管理任何历史缓存副本的生命周期。 - 禁止将
raw_file用于含子文件依赖的入口:任何承担「通过info["file tree"]展开下游子文件索引」职责的入口文件(如<version>.json),严禁使用raw_file投递,必须打包在对应的 BT v2 种子中。
- 服务端必须使用
2. 已发布的不可变游戏版本资源(按版本独立制作 BT v2 种子)
已发布的游戏版本文件(<version>.json、client.jar、libraries、<asset_index>.json、assets/objects)内容一旦发布即固定不变。为了彻底消除「大版本聚合 Assets 种子随小版本发布而频繁重打包变动」带来的协议与客户端缓存复杂度,服务端应按单个游戏版本打包为独立的不可变 BitTorrent v2(BEP-52) 种子:
- 版本全量种子(
minecraft-version-<ver>):- 包含该版本的
<version>.json、client.jar、该版本依赖的全部libraries文件、该版本对应的<asset_index>.json(如19.json)以及该索引关联的全部assets/objects资源文件。 - 在
latest.json的nsci.raw_kv中,只需将该版本<version>.json的NSFID指向该种子的 InfoHash v2(<asset_index>.json已作为子文件包含在该版本种子的info["file tree"]中,客户端展开版本种子时会自动将其索引写入nsci_cache,无需在latest.json中重复收录)。 - 不同版本的
minecraft-version-<ver>种子天然包含相同 URL 的公共libraries与assets/objects文件(在 BitTorrent v2 中,相同文件的pieces root完全一致;且客户端nsci_cache将公共文件指向任意一个已展开的版本种子均可正常通过 BT / WebSeed 完成下载)。 - 版本种子永久不可变:每个游戏版本的
.torrent种子一旦生成发布,其 InfoHash v2 永久固定,服务端无需在发布新小版本时重打历史种子。
- 包含该版本的
2. BT v2 种子打包规范(Packer 规范)
服务端打包器(NodeStone Packer)生成 .torrent 文件时,必须遵循以下底层规范:
- 纯正 BitTorrent v2(BEP-52)格式:
info["meta version"]必须固定为整数2(i2e)。info["name"]必须为不含路径分隔符/的纯 ASCII 标识符(例如minecraft-version-1.21.4)。- 种子顶层字典必须包含
piece layers字典(即使种子内所有文件均小于或等于piece length,也必须写入空字典12:piece layersde)。 - 种子唯一标识(
torrenthash)为 Bencode 编码后info字典的 SHA-256 值(64 位小写十六进制字符串)。 - Bencode 字典的所有 Key 必须严格按照原始字节序(Lexicographical Order)排序。
info["file tree"]目录结构与原始 UTF-8 路径段约定:- 无论是单文件种子还是跨多个官方域名的多文件种子,文件在
info["file tree"]中的第一级目录固定为官方源经 RFC 3986 Section 6.2.2 规范化后的完整主机名(<host>[:<port>],小写且不含默认端口:80/:443)。 - 后续目录层级与文件名必须存储百分号解码(Unescaped)后的原始 UTF-8 字符串(例如 URL 路径中的
%20在file tree中必须还原为空格' '),以确保 BT 引擎落盘的文件名与真实文件名一致,并防止 BEP-19 WebSeed 请求时发生二次百分号编码。 - 示例 1:
https://piston-meta.mojang.com/v1/packages/17c54eb33b5d4a8f9c04eb1234567890abcdef01/1.21.4.json在file tree中的层级为:piston-meta.mojang.com->v1->packages->17c54eb33b5d4a8f9c04eb1234567890abcdef01->1.21.4.json。 - 示例 2:
https://libraries.minecraft.net/com/mojang/logging/1.1.1/logging-1.1.1.jar在file tree中的层级为:libraries.minecraft.net->com->mojang->logging->1.1.1->logging-1.1.1.jar。 - 示例 3:
https://resources.download.minecraft.net/ab/ab1234567890abcdef1234567890abcdef123456在file tree中的层级为:resources.download.minecraft.net->ab->ab1234567890abcdef1234567890abcdef123456。
- 无论是单文件种子还是跨多个官方域名的多文件种子,文件在
- 协议头字段
info["ns-schemes"]与禁用url-list:- 必须在
info["ns-schemes"]中写入协议头列表(例如["https://"]),并推荐在种子顶层字典ns-schemes同步写入相同列表。将ns-schemes放入info字典内可确保通过磁力链接(BEP-9ut_metadata)拉取元数据的客户端不会丢失该字段,且受 InfoHash v2 完整性校验保护。 - 禁止在种子顶层写入标准 BEP-19
url-list字段:防止第三方普通 BT 引擎将info["name"]拼接到域名中向官方源发起错误请求。
- 必须在
- Tracker、
.torrent直链与做种节点(Seeder)部署:- 种子顶层应写入
announce及announce-list(填入官方或镜像源的高可用 Tracker 地址)。 - 服务端必须将完整
.torrent文件发布至 CDN 并在delivery.url中提供直链,同时在发布前确保官方/镜像 Seeder 节点已挂载该完整种子(含完整的piece layers)并处于活动做种状态。这样既能保证客户端通过delivery.url直接拿到piece layers走 WebSeed 校验下载,也能保证使用delivery.magnetic的客户端通过 BEP-9(ut_metadata)和 BEP-52(hash request)拉取完整元数据与 Merkle 分层哈希。
- 种子顶层应写入
3. URL 规范化与 NSFID 生成规范
服务端在生成 nsci.raw_kv 中的 NSFID 时,必须与客户端以及 info["file tree"] 还原逻辑保持 100% 一致:
- 对官方原始 URL 执行 RFC 3986 Section 6.2.2(Syntax-Based Normalization):
scheme和host转为小写;- 移除默认端口(
http的:80、https的:443); - 对路径段中除 RFC 3986 非保留字符(
ALPHA / DIGIT / "-" / "." / "_" / "~")以外的字符执行 UTF-8 百分号编码,所有百分号编码的十六进制字符统一转为大写(%XX),并解码所有被多余转义的非保留字符; - 折叠路径中的
/./与/../。
- 确保种子
info["file tree"]中的原始路径段在对每级路径段做quote(seg, safe="-._~")并与ns-schemes、第一级主机名拼接后,得到的orig_url恰好等于上述规范化后的 URL。 - 将规范化后的 URL 按 UTF-8 字节流进行标准 Base64 编码(RFC 4648,保留末尾
=填充,不换行),加上url:前缀得到NSFID。
4. NSCL(latest.json)构建与发布流程
每次服务端检测到上游资源更新(例如 Mojang 发布新版本导致 version_manifest_v2.json 变化并新增了该版本的种子)时,按以下原子流程构建并发布 latest.json:
- 组装
assets.torrents:- 为
version_manifest_v2.json计算文件整体线性 SHA-256,生成delivery.integrated("type": "raw_file","payload"为文件 Base64)。 - 为所有已打包的游戏版本种子写入
delivery.url(.torrent文件的 CDN/镜像直链列表)和delivery.magnetic。 - 磁力链接强制格式:
delivery.magnetic必须符合magnet:?xt=urn:btmh:1220<torrenthash>&dn=<url-encoded-name>&tr=<url-encoded-tracker-1>&tr=<url-encoded-tracker-2>,必须携带至少一个可用的&tr=参数。
- 为
- 组装
nsci.raw_kv:- 仅收录顶层清单(
version_manifest_v2.json)与各版本<version>.json的NSFID -> Hash映射,保持latest.json体积轻量(约 20 KB)。
- 仅收录顶层清单(
- 递增
revision与填写元数据:filetype固定设为"nscl/v0.9"。namespace设为当前命名空间(如"minecraft")。revision必须在上一版已发布清单的基础上严格单调递增(例如+1或使用单调递增的构建流水号)。- 填写当前构建节点标识
generatedBy与 UTC 时间戳generateDate(ISO 8601 格式)。
- minisign 签名与原子发布:
- 使用服务端私钥对生成的
latest.json进行 minisign 签名,生成latest.json.minisig。 - 推荐在 minisign 的受信任注释(
trusted comment)中写入namespace:<namespace> revision:<revision> date:<generateDate>,防止跨命名空间重放。 - 先上传种子,后更新清单:必须先将新增的
.torrent文件同步至对象存储/CDN 并通知 Seeder 挂载做种,确认可访问后,再将latest.json与latest.json.minisig原子替换发布到/v09/<namespace>/路径下。
- 使用服务端私钥对生成的