# QN-DL **Repository Path**: YuYao-Gith/QN-DL ## Basic Information - **Project Name**: QN-DL - **Description**: Minecraft 资源镜像下载器（Java 21，支持 Mojang/BMCLAPI 镜像源） - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-08-20 - **Last Updated**: 2026-08-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # QN-DL — Minecraft 资源镜像下载器 QN-DL（青年-DL）是一个用 Java 21 编写的 Minecraft 资源下载工具，支持**命令行参数**与**交互式面板**两种使用方式。它通过可插拔的镜像源（Mojang 官方 / BMCLAPI）下载客户端、服务端、库文件、资源、映射表、各加载器安装器和 Modrinth Mod，下载目录遵循官方 `.minecraft` 布局。 ## 功能特性 - **完整下载**：客户端 JAR + 全部 libraries + assets 资源（官方 `.minecraft` 目录布局：`versions/`、`libraries/`、`assets/`） - **单项下载**：客户端 JAR、服务端 JAR、库文件、资源、映射表（client/server/joined） - **安装器**：Forge、Fabric、NeoForge、Quilt（自动解析最新版本） - **Mod 下载**：Modrinth 搜索 + 版本选择下载 - **镜像源**：Mojang 官方、BMCLAPI（URL 重写规则数据驱动，`mirrors.json` 可扩展） - **自定义请求 IP**（`--resolve 主机=IP`）：把下载请求定向到任意服务器，同时保持原始 Host 头与 TLS SNI/证书校验，语义等同 `curl --resolve` - **不污染系统临时目录**：`.part` 临时文件默认存放在目标文件旁边（可用 `--temp-dir` 指定），服务器上运行不会在 `/tmp`、`/var` 堆积垃圾文件 - **断点续传**：HTTP Range 请求，中断后从 `.part` 文件继续 - **SHA-1 校验**：下载后校验，失败自动重试（最多 3 次）；已存在且校验通过的文件自动跳过 - **并发下载**：多线程（默认 8），实时速度/ETA - **`--json` 输出**：NDJSON 机器可读事件流，适合网站/服务端集成 - **`--dry-run`**：只列出将要下载的文件 - **多语言**：中文（默认）/ English / 日本語 / Deutsch / Français / Español / العربية，`--lang` 或交互面板切换 - **持久化配置**：`~/.config/qn-dl/config.json`（Windows 在 `%APPDATA%\qn-dl\config.json`） ## 构建 需要 JDK 21+ 与 Maven 3.9+： ```bash make build # 或: mvn -q package make test # 或: mvn -q test java -jar target/qn-dl.jar --help ``` 产物为自包含可执行 JAR（`target/qn-dl.jar`），无需额外依赖。 ## 快速开始 ```bash # 交互式面板（无参数启动） java -jar qn-dl.jar # 完整下载 1.21.4（客户端 + 库 + 资源），走 BMCLAPI 镜像 java -jar qn-dl.jar full 1.21.4 --mirror bmclapi --dir /data/mc # 只下服务端 JAR（latest = 最新正式版） java -jar qn-dl.jar server latest --dir /data/mc # 下载安装器 java -jar qn-dl.jar installer fabric --mc 1.21.4 java -jar qn-dl.jar installer forge --mc 1.20.1 java -jar qn-dl.jar installer neoforge --mc 1.21.1 java -jar qn-dl.jar installer quilt --mc 1.21.4 # 搜索/下载 Mod java -jar qn-dl.jar mod search sodium --mc 1.21.4 java -jar qn-dl.jar mod download sodium --mc 1.21.4 --loader fabric ``` ## 命令一览 | 命令 | 说明 | |---|---| | `full <版本>` | 完整下载（客户端 + 库 + 资源），`--mappings` 附带映射表 | | `client <版本>` / `server <版本>` | 客户端 / 服务端 JAR | | `libraries <版本>` | 版本的全部库文件，`--all-platforms` 下载所有平台原生库 | | `assets <版本>` | 资源文件（含资源索引） | | `mappings <版本>` | 映射表（client/server/joined） | | `installer ` | 安装器，`--mc` 指定游戏版本（默认最新正式版），`--version` 指定具体版本 | | `mod search <关键词>` / `mod download ` | Modrinth 搜索与下载 | | `manifest [--list\|--latest]` | 查看版本清单 | | `config [--show\|--set k=v \|--path]` | 查看/修改配置 | | `version` / `--version` | 版本号 | 版本参数支持 `latest`（最新正式版）、`latest-snapshot`、完整 ID（`1.21.4`）或唯一前缀（`1.21`）。 ### 全局选项 | 选项 | 说明 | |---|---| | `--mirror ` | 镜像源：`official` / `bmclapi` | | `--dir <路径>` | 下载根目录（默认 `./minecraft`，官方布局） | | `--threads ` | 并发数（默认 8） | | `--lang ` | 语言：zh/en/ja/de/fr/es/ar | | `--resolve <主机=IP>` | 自定义请求 IP，可重复（见下文） | | `--temp-dir <路径>` | `.part` 临时文件目录（默认在目标文件旁） | | `--no-verify` | 跳过 SHA-1 校验 | | `--force` | 强制重新下载 | | `--dry-run` | 只列出将下载的文件 | | `--json` | NDJSON 输出（服务端集成） | | `--proxy ` | HTTP 代理 | | `--timeout <秒>` | 请求超时（默认 30） | | `--config <路径>` | 指定配置文件 | ## 自定义请求 IP（--resolve） ```bash # 把 piston-meta 的请求解析到指定 IP（如内网缓存/CDN 节点），其余主机正常解析 java -jar qn-dl.jar full 1.21.4 --resolve piston-meta.mojang.com=192.0.2.10 \ --resolve piston-data.mojang.com=192.0.2.11 # 持久化到配置 java -jar qn-dl.jar config --set resolve=piston-meta.mojang.com=192.0.2.10 ``` - 可重复使用，作用于所有 HTTP 请求（包括镜像源跳转后的 CDN 请求） - 连接使用指定 IP，但 **Host 头、TLS SNI 与证书校验仍按原主机名进行**，因此可安全指向任何 HTTP 服务器（反代、CDN 缓存节点、另一台镜像机） - 对 Modrinth（`api.modrinth.com`、`cdn.modrinth.com`）同样生效 **服务器场景**：网站提供资源镜像下载时，可以把下载请求指到自己的缓存节点，且由于 `.part` 文件默认存放在目标目录旁（`--temp-dir` 可指定其他位置），不会在 `/tmp`、`/var` 堆积临时文件。 ## --json 输出（服务端集成） ```bash java -jar qn-dl.jar server latest --json --dir /data/mc ``` 每行一个 JSON 对象（NDJSON）： ```json {"event":"start","count":1,"bytes":54237648} {"event":"progress","file":"/data/mc/versions/1.21.4/1.21.4-server.jar","done":1048576,"total":54237648} {"event":"file","file":"/data/mc/versions/1.21.4/1.21.4-server.jar","ok":true,"skipped":false} ``` 事件：`start`（批次开始）、`progress`（进度）、`file`（单个文件结束，`ok`/`skipped`/`error` 字段）。退出码：0 全部成功，1 有失败。 ## 镜像源 镜像定义在 JAR 内的 `mirrors.json`（也可参考 `src/main/resources/mirrors.json`），为**有序 URL 前缀重写规则**（首个匹配生效）： | 官方域名 | BMCLAPI 重写 | |---|---| | `piston-meta.mojang.com` | `bmclapi2.bangbang93.com/mc/game/` | | `piston-data.mojang.com` / `launcher.mojang.com` | `bmclapi2.bangbang93.com/` | | `libraries.minecraft.net` | `bmclapi2.bangbang93.com/maven/` | | `resources.download.minecraft.net` | `bmclapi2.bangbang93.com/assets/` | | `meta.fabricmc.net` | `bmclapi2.bangbang93.com/fabric-meta/` | | `maven.fabricmc.net` | `bmclapi2.bangbang93.com/maven/` | | `maven.minecraftforge.net` | `bmclapi2.bangbang93.com/maven/` | | `maven.neoforged.net/releases/` | `bmclapi2.bangbang93.com/maven/` | | `meta.quiltmc.org` | `bmclapi2.bangbang93.com/quilt-meta/` | 注：Modrinth API/CDN 与 Forge 促销信息 JSON（小文件）无镜像，直接访问官方源；均可用 `--resolve` 走自定义节点。 ## 配置 配置文件：`~/.config/qn-dl/config.json`。优先级：默认值 < 配置文件 < 命令行参数。 ```json { "lang": "zh", "mirror": "bmclapi", "dir": "minecraft", "threads": 8, "tempDir": null, "verify": true, "force": false, "proxy": null, "timeoutSeconds": 30, "resolves": ["piston-meta.mojang.com=192.0.2.10"] } ``` ## 技术说明 - **HTTP 层使用 OkHttp 而非 JDK HttpClient**：`--resolve` 需要可插拔的 DNS 解析器，JDK 的 HttpClient 在 JDK 18 短暂引入后于 19 移除了该 API，而 OkHttp 的 `Dns` 接口可以精确实现 `curl --resolve` 语义（自定义 IP + 保持 Host/SNI）。 - 依赖仅三个：OkHttp（HTTP）、Jackson（JSON）、JUnit（测试）。 - 交互面板在 POSIX 终端使用原生 raw 模式（`stty`）+ ANSI；Windows 自动降级为行输入模式。 ## 测试 ```bash make test ``` 覆盖：镜像 URL 重写、CLI 参数解析、配置读写、SHA-1、版本清单/版本 JSON/资源索引解析（含原生库与规则过滤）、下载器（含断点续传、校验失败清理、跳过/强制、dry-run，基于 JDK 内置 HTTP 测试服务器）。 ## 作者 - **YuYao-Gith**（asdf2502@126.com） - Gitee: 如果本项目对你有所帮助，欢迎在 Gitee 上关注或 Star。 ## 许可 默认采用 **Apache License 2.0**，见 [LICENSE](LICENSE)。 特别条款：若本项目被用于任何商业目的（包括但不限于销售、捆绑销售、或作为付费服务的一部分）的**二进制分发**，授权将自动切换为 **GNU Affero General Public License v3.0 (AGPL-3.0)**。详见 LICENSE 文件开头的版权声明。