# 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-09-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# downloadHack

一个基于 **Java 21 + Spring Boot** 的下载器套件：支持 HTTP/HTTPS 大文件多线程分片下载、HLS(m3u8) 流媒体下载、
断点续传、限速、并发控制、任务组、暂停/恢复/取消、失败自动重试、进程重启恢复，并提供三个带 **Web 界面**
的开箱即用应用——下载器（download-server）、资源库（resource-hub）、爬虫引擎（crawler-engine）。
MySQL 8.0+ 与 SQLite 3.x 双库兼容。前端为 PC 端与移动端各一套独立页面，入口页按设备自动跳转。

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

---

## 模块地图

| 模块 | 定位 | 文档 |
|---|---|---|
| **download-server** | 可直接运行的下载器应用：Web 界面 + REST API + 装配（端口 8080） | [download-server/README.md](download-server/README.md) |
| **resource-hub** | 可直接运行的资源库应用：剧集聚合 / 播放 / 一键下载到 download-server（端口 8081） | [resource-hub/README.md](resource-hub/README.md) |
| **crawler-engine** | 可直接运行的爬虫引擎应用：配置化爬虫 + 分层提取 + 自动推送到 resource-hub（端口 8082） | [crawler-engine/README.md](crawler-engine/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`；`resource-hub` 独立成包，
运行时通过 HTTP 调用 download-server 提交下载任务；`crawler-engine` 独立成包，
运行时通过 HTTP 调用 resource-hub 推送爬取结果。想要「拿来即用的下载器」，直接跑 **download-server**；
想要「资源浏览 + 一键下载」，再起一个 **resource-hub**；想要「自动爬取外部网站并推送」，再起一个 **crawler-engine**；想把下载能力嵌进你自己的应用，接入 **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 合并 / 去广告查验** 功能用；只下载不合并**不需要** |
| Docker | 任意近版 | 可选 | 仅用 `docker-compose.yml` + `start.sh` 容器化部署时需要（三个服务打包到一个镜像组） |

---

## 二、启动步骤

### 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. 运行资源库（resource-hub，可选）

资源库依赖 download-server 提交下载任务，**务必先启动 download-server 再启动 resource-hub**。

```bash
# 方式一：直接跑（默认 SQLite，工作目录为 resource-hub/）
mvn spring-boot:run -pl resource-hub -am

# 方式二：跑打包好的 jar（工作目录需为 resource-hub/，否则 SQLite 相对路径解析不对）
cd resource-hub
java -jar target/resource-hub-1.0.0.jar
```

### 5. 运行爬虫引擎（crawler-engine，可选）

爬虫引擎依赖 resource-hub 接收推送，**务必先启动 resource-hub 再启动 crawler-engine**。

```bash
# 方式一：直接跑（默认 SQLite）
mvn spring-boot:run -pl crawler-engine -am

# 方式二：跑打包好的 jar
java -jar crawler-engine/target/crawler-engine-1.0.0.jar
```

### 6. 用 Docker 一键启动三个服务（可选）

项目根提供 `docker-compose.yml` 与 `start.sh`，把三个服务打包为独立镜像，
数据统一持久化到宿主机数据目录（默认 `./data`，可在 `.env` 设 `DATA_DIR` 指定任意位置）：

```bash
# 构建好三个 jar（见第 2 步）后，在项目根目录执行
bash start.sh          # 启动（后台，默认 SQLite）
bash start.sh mysql    # MySQL 模式
bash start.sh logs     # 查看日志
bash start.sh stop     # 停止
bash start.sh restart  # 重启
```

> Docker 部署使用 `bash build.sh` 打包三个镜像为 tar，`start.sh` 自动检测并 `docker load`。
> 详见 [DEPLOY.md](DEPLOY.md)。

### 7. 打开界面

- 下载器：浏览器访问 **http://localhost:8080/**
- 资源库：浏览器访问 **http://localhost:8081/resource.html**
- 爬虫引擎：浏览器访问 **http://localhost:8082/channel.html**

入口页会按设备自动跳转：PC 端 → `index-pc.html` / `resource-pc.html` / `crawler-pc.html`；移动端 → `index-mobile.html` / `resource-mobile.html` / `crawler-mobile.html`。
若开启了鉴权（默认关闭），未登录访问页面跳登录页，默认账号 `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` | `false` | 是否开启登录鉴权；纯本机可信部署默认放行，**公网务必设 `true`** |
| `download.security.auth.username` / `password` | `admin` / `admin` | 登录账号密码，**公网务必修改** |
| `download.security.confine-save-dir` | `false` | 把下载目录限制在允许根目录内（防路径穿越）；公网部署建议设 `true` |
| `download.security.block-private-networks` | `false` | 拦截指向内网/回环的下载 URL（防 SSRF）；公网部署建议设 `true` |

> 以上安全开关均为 **fail-closed 语义的反向**：本机可信部署默认全开（放行），面向公网时请逐项收紧。

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

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

| 配置项 | 默认值 | 说明 |
|---|---|---|
| `server.port` | `8081` | 服务端口 |
| `spring.datasource.url` | `jdbc:sqlite:../data/resource_hub.db` | SQLite 数据库（相对工作目录的上级 `data/`） |

resource-hub 跨服务调用 download-server 的地址写死在前端 `shared-api.js` 的 `DOWNLOAD_SERVER_URL`
（默认 `http://localhost:8080`），由用户浏览器发起，指向宿主机 8080 端口。Docker 部署时已做端口映射，无需改动。

### Docker 部署的数据目录

`docker-compose.yml` 所有卷映射都以 **`DATA_DIR`** 为根（默认 `./data`，可在 `.env` 设任意目录，如 Linux 的 `/opt/downloadhack-data`）：
- download-server：数据库 `/data/db/sqlite/download-server.db`、下载产物 `/data/downloads/`、分片配置/临时/广告段、ffmpeg、日志
- resource-hub：数据库 `/data/db/sqlite/resource_hub.db`、封面缓存 `/data/cover-cache/`、日志
- crawler-engine：数据库 `/data/db/sqlite/crawler_engine.db`、日志
- MySQL 模式：数据文件落 `${DATA_DIR}/db/mysql/`

启动时 `start.sh` 会按 `DATA_DIR` 自动创建全部子目录（含 `cover-cache`），**备份只需打包整个数据根目录**。详见 [DEPLOY.md](DEPLOY.md)。

### 运行期配置（界面「设置」或配置 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/` 跳转到登录页 | 已手动开启鉴权（`auth.enable=true`） | 用 `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` 的地址/账号/密码 |
| resource-hub 点「下载」无反应 / 报连不上 download-server | download-server 未启动，或 8080 端口被占 | 先启动 download-server；检查 `shared-api.js` 的 `DOWNLOAD_SERVER_URL` 是否指向正确地址 |
| `bash start.sh` 报 `bind: address already in use`（8080/8081/8082） | 端口被已运行的 jar 进程占用 | 先停掉本地 `java -jar` 服务再启 Docker，或改 `docker-compose.yml` 端口映射 |
| `bash start.sh` 报本机不存在镜像 | 未提前准备镜像 | 先执行 `bash build.sh` 构建镜像，或从 `dist/` 导入 tar |
| Docker 启动后 resource-hub 数据库路径不对 | jar 的工作目录与 `../data/resource_hub.db` 解析不符 | 容器内 `working_dir` 必须为 `/app`（`docker-compose.yml` 已设） |
| 爬虫推送失败 `Connection refused` | crawler-engine 无法连接 resource-hub | 确认 resource-hub 已启动；Docker 部署用 service name 访问 |
| 爬虫提取不到数据 | CSS 选择器写错 / 网站动态渲染 | 打开调试面板查看「原始响应」和「诊断」Tab 排查 |

---

## 五、更多文档

- 下载器应用（Web 界面 / REST API / 装配）：[download-server/README.md](download-server/README.md)
  — download-server 的 REST API 接口文档**内嵌在该 README 的「REST API」章节**
- 资源库应用（剧集聚合 / 播放 / 一键下载）：[resource-hub/README.md](resource-hub/README.md)
  — resource-hub 的 REST API 接口文档独立成 [resource-hub/API.md](resource-hub/API.md)
- 爬虫引擎应用（配置化爬虫 / 分层提取 / 自动推送）：[crawler-engine/README.md](crawler-engine/README.md)
  — crawler-engine 的配置教程和调试面板用法见其 README「快速上手」和「调试面板」章节
- 下载能力接入（嵌入你自己的应用）：[download-core/README.md](download-core/README.md)
- 数据持久层（实体 / 仓库 / 建表脚本）：[download-persistent/README.md](download-persistent/README.md)
- 完整架构、设计决策与开发记录：[DEVELOPMENT.md](DEVELOPMENT.md)
- 部署指南（面向运维）：[DEPLOY.md](DEPLOY.md)

> 三个服务都有 REST API 文档：download-server 内嵌在自身 README；resource-hub 独立为 `API.md`；crawler-engine 见其 README。
> 爬虫引擎往 resource-hub 推送资源（`POST /api/resource-hub/push`）的用法见 [resource-hub/API.md](resource-hub/API.md) 第五节。