# downloadHack

**Repository Path**: net_yc60/download-hack

## Basic Information

- **Project Name**: downloadHack
- **Description**: Java+spring开发的下载器
- **Primary Language**: Java
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-09-06
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# downloadHack

一个基于 **Java 21 + Spring Boot** 的下载器：支持 HTTP/HTTPS 大文件多线程分片下载、HLS(m3u8) 流媒体下载、
断点续传、限速、并发控制、任务组、暂停/恢复/取消、失败自动重试、进程重启恢复，并提供一个带 **Web 界面**
的开箱即用下载器应用。MySQL 8.0+ 与 SQLite 3.x 双库兼容。

> 本文件是**零基础上手总览**（怎么跑起来）。想了解每个模块的接入用法与内部设计，见下方「模块地图」链接；
> 完整架构与开发记录见 [DEVELOPMENT.md](DEVELOPMENT.md)。

---

## 模块地图

| 模块 | 定位 | 文档 |
|---|---|---|
| **download-server** | 可直接运行的下载器应用：Web 界面 + REST API + 装配 | [download-server/README.md](download-server/README.md) |
| **download-core** | 下载能力模块（纯库）：对外暴露 `DownloadService` / `ConfigService` 两个门面 | [download-core/README.md](download-core/README.md) |
| **download-persistent** | 数据持久层：实体 / 仓库 / 双库 DDL 与初始化数据 | [download-persistent/README.md](download-persistent/README.md) |
| download-boot | 最小可运行示例与端到端测试壳（非交付产物） | —— |

依赖关系：`download-server → download-core → download-persistent`。想要「拿来即用的下载器」，直接跑 **download-server**；
想把下载能力嵌进你自己的应用，接入 **download-core**（见其 README）。

---

## 一、环境依赖

| 依赖 | 版本 | 是否必需 | 说明 |
|---|---|---|---|
| JDK | **21+** | 必需 | 使用虚拟线程 |
| Maven | 3.9+ | 必需 | 构建 |
| 数据库 | SQLite 3.x（默认）**或** MySQL 8.0+ | 必需（二选一） | **SQLite 零安装、开箱即用**；MySQL 需自备可连接的库 |
| m3u8-parse | 1.4.2 | 必需 | HLS 解析库，**不在中央仓**，需先本地安装（见启动步骤第 1 步） |
| ffmpeg | 任意近版 | 可选 | 仅 **HLS 合并 / 去广告查验** 功能用；只下载不合并**不需要** |

---

## 二、启动步骤

### 1. 先安装本地依赖 m3u8-parse（只需一次）

HLS 解析库 `com.lang:m3u8-parse:1.4.2` 不在 Maven 中央仓，需先在其源码目录本地安装到 `.m2`：

```bash
# 在 m3u8-parse 项目根目录执行
mvn clean source:jar install -DskipTests
```

### 2. 构建

在本项目根目录执行（务必带 `clean`）：

```bash
mvn clean package
```

### 3. 运行下载器（download-server）

```bash
# 方式一：直接跑（默认 SQLite，开箱即用）
mvn spring-boot:run -pl download-server -am

# 方式二：跑打包好的 jar
java -jar download-server/target/download-server-1.0.0.jar

# 切换 MySQL（需先准备好可连接的 download_hack 库）
java -jar download-server/target/download-server-1.0.0.jar --spring.profiles.active=mysql
```

### 4. 打开界面

浏览器访问 **http://localhost:8080/** ，用默认账号登录：

- 用户名 `admin` ，密码 `admin` （**公网部署务必先改密码**，见配置说明）

首次启动会自动建表并写入默认配置，**无需手动执行任何 SQL**。

---

## 三、配置说明

配置分两类：**启动配置**（改 `application.yml`，需重启）与**运行期配置**（存数据库、界面上改，即时生效）。

### 启动配置（`download-server/src/main/resources/application.yml`）

| 配置项 | 默认值 | 说明 |
|---|---|---|
| `spring.profiles.active` | `sqlite` | 数据库切换：`sqlite`（零安装）/ `mysql` |
| `server.port` | `8080` | 服务端口 |
| `download.security.auth.enable` | `true` | 是否开启登录鉴权；纯本机可信部署可设 `false` 放行 |
| `download.security.auth.username` / `password` | `admin` / `admin` | 登录账号密码，**公网务必修改** |
| `download.security.confine-save-dir` | `true` | 把下载目录限制在允许根目录内（防路径穿越）；本机想下到任意目录可关 |
| `download.security.block-private-networks` | `true` | 拦截指向内网/回环的下载 URL（防 SSRF） |

- MySQL 连接信息在 `application-mysql.yml`（默认 `localhost:3306/download_hack`）。
- SQLite 数据文件为进程工作目录下的 `download-server.db`（含 WAL 边车文件）。

### 运行期配置（界面「设置」或配置 API，即时生效）

并发数、全局/单任务限速、检查点阈值、重试次数、下载目录、HLS 分片写盘参数等**全部存数据库 `dict` 表**，
在界面上直接改、保存即刻生效，无需重启。完整配置项清单见 [download-core/README.md](download-core/README.md) 第五节。

---

## 四、常见报错

| 现象 | 原因 | 解决 |
|---|---|---|
| 构建报 `Could not find artifact com.lang:m3u8-parse` | 没装本地依赖 m3u8-parse | 执行启动步骤第 1 步把 m3u8-parse 安装到 `.m2` |
| 启动报 `Unsupported class file major version` / 需要更高 Java | JDK 版本低于 21 | 安装并切换到 **JDK 21+**（`java -version` 确认） |
| 打开 `http://localhost:8080/` 跳转到登录页 | 已默认开启鉴权 | 用 `admin`/`admin` 登录；或在 `application.yml` 关 `auth.enable` |
| 下载报「保存目录不允许」 | 目标目录不在允许根目录内（`confine-save-dir=true`） | 下到允许目录内，或本机可信部署时把 `confine-save-dir` 设为 `false` |
| 下载内网/回环地址报被拦截 | SSRF 防护 `block-private-networks=true` | 本机可信部署可关此开关 |
| HLS 合并 / 去广告查验失败，日志提示找不到 ffmpeg | 未安装 ffmpeg 或不在 PATH | 安装 ffmpeg 并加入 PATH，或在运行期配置 `ffmpegPath` 指向其路径（只下载不合并无需 ffmpeg） |
| MySQL 启动连不上库 | 未准备 `download_hack` 库或连接信息不符 | 建库并核对 `application-mysql.yml` 的地址/账号/密码 |

---

## 五、更多文档

- 应用层（Web 界面 / REST API / 装配）：[download-server/README.md](download-server/README.md)
- 下载能力接入（嵌入你自己的应用）：[download-core/README.md](download-core/README.md)
- 数据持久层（实体 / 仓库 / 建表脚本）：[download-persistent/README.md](download-persistent/README.md)
- 完整架构、设计决策与开发记录：[DEVELOPMENT.md](DEVELOPMENT.md)