300 lines
12 KiB
Markdown
300 lines
12 KiB
Markdown
# 4KHD Downloader
|
||
|
||
`migmg.ssuu.uk`（4KHD 系采集站）画廊批量下载器。浏览器里用油猴脚本把画廊推给本地程序，
|
||
程序解析分页页、拿到全部图片直链、多线程下载到本地。
|
||
|
||
程序结构和交互沿用 [eh-downloader](../eh-downloader)（E-Hentai 版），
|
||
但站点协议层是照着 4KHD 的真实页面重写的。
|
||
|
||
---
|
||
|
||
## 快速上手
|
||
|
||
### 1. 构建
|
||
|
||
前置：**Go 1.24+**，以及 **Wails CLI v2** 和 **WebView2 运行时**（Win10/11 一般已自带）。
|
||
|
||
```powershell
|
||
# 装 Wails CLI
|
||
go install github.com/wailsapp/wails/v2/cmd/wails@v2.16.0
|
||
|
||
# 构建
|
||
cd hd4k-downloader
|
||
wails build
|
||
```
|
||
|
||
产物在 `build\bin\4KHD-Downloader.exe`。
|
||
|
||
> 本机 Go 装在 `%USERPROFILE%\.local\go`，不在系统 PATH 里，
|
||
> 调用前需要 `$env:PATH = "$env:USERPROFILE\.local\go\bin;$env:PATH"`。
|
||
|
||
### 2. 装油猴脚本
|
||
|
||
把 [`userscript/hd4k-to-downloader.user.js`](userscript/hd4k-to-downloader.user.js)
|
||
拖进 Tampermonkey 即可，无需额外配置（端口和 token 已写死在内）。
|
||
|
||
- **画廊详情页**：标题下面出现「📤 发送画廊地址」按钮
|
||
- **列表页**：每条画廊前面出现复选框，右下角浮出批量工具条
|
||
|
||
### 3. 下图
|
||
|
||
点推送 → 程序窗口自动弹到前台 → 「开始下载」。
|
||
|
||
也可在程序里「导入链接」，粘贴一批 URL（每行一条）手动加任务。
|
||
|
||
---
|
||
|
||
## 它是怎么工作的
|
||
|
||
```
|
||
浏览器 (油猴脚本)
|
||
│ GM_xmlhttpRequest → http://127.0.0.1:37778/add
|
||
▼
|
||
本地桥口 (Go, 只监听 127.0.0.1)
|
||
│ {url, title} → 解析成 GalleryRef，URL 域名归一化，入队
|
||
▼
|
||
下载引擎
|
||
│ 抓第 1 页 → 从 .page-link-box 读总页数 → 并发抓 2..N 页
|
||
│ 从 HTML 抽 i0.wp.com 直链 → 过滤推荐位 → 按页去重
|
||
│ 多线程下载 → .part 临时文件 → 原子改名
|
||
▼
|
||
下载目录/<模板>/xxx-001.webp … + .hd4k.json（清单，用于续传）
|
||
```
|
||
|
||
### 和 eh-downloader 的关键差异
|
||
|
||
| | EH Downloader | 4KHD Downloader |
|
||
|---|---|---|
|
||
| 任务主键 | gid + token | id（**主域名 + 路径**） |
|
||
| 图片地址 | hath 签名链接，**会过期** | 稳定 URL 哈希，**永久有效** |
|
||
| 续传方式 | 清单存直链，重启 0 请求 | 同左（4KHD 更彻底） |
|
||
| 抓取请求数 | 2N+1（列表 + 详情 ×2） | **N**（只有分页页） |
|
||
| 分辨率 | 可选 `xres=org` 等 | **走源站直链**（不用 Photon 代理，否则免费额度打爆会被 429 封） |
|
||
| 目录占位符 | `{title} {gid} {artist} {group} {series} {category} {lang} {tag1} {tags:3}` | `{title} {name} {slug} {host} {category} {id}` |
|
||
| 桥口端口 | 37777 | **37778** |
|
||
|
||
4KHD 没有 EH 那套 artist/group/series/tags 标签体系，站点真实提供的元数据只有
|
||
标题、路径名、域名和分类数字，所以占位符和预设都相应变少了。
|
||
|
||
---
|
||
|
||
## 站点适配（重要）
|
||
|
||
这类采集站**随时换域名**。实测 `www.4khd.com`、`m.4khd.com` 现在全部 404，
|
||
只有 `migmg.ssuu.uk` 活着。所以域名做成了设置项，不用改代码：
|
||
|
||
- **设置 → 站点域名** → 加一行即可
|
||
- 保存后，油猴脚本下次加载会从桥口 `/info` 读到最新域名列表
|
||
|
||
### 域名归一化
|
||
|
||
页面上散布的链接**未必指向主域名**。实测 `migmg.ssuu.uk` 首页里 90 个
|
||
`/content/` 链接**全部**指向已 404 的 `www.4khd.com`。
|
||
|
||
所以 `4khd.com`、`www.4khd.com`、`m.4khd.com` 都配成了 `migmg.ssuu.uk` 的
|
||
**别名**：不管用户从哪个域名复制链接，后端都会归一到主域名。
|
||
不归一的话，同一个画廊会因为「从哪个域名复制的链接」变成两个不同任务，
|
||
而且引擎会去请求一个死域名。
|
||
|
||
分页后缀（`…/x.html/2`）也会被剥掉，避免 `/2` 和 `/1` 变成两个任务。
|
||
|
||
---
|
||
|
||
## 协议层是怎么定下来的
|
||
|
||
全部基于 2026-10-11 对真实页面的实测，不是照着 HTML 猜的。几个关键点：
|
||
|
||
**图片地址**：页面给的是 Jetpack Photon 代理，但我们**不直接用**
|
||
|
||
页面里的图片地址长这样：
|
||
|
||
```
|
||
https://i0.wp.com/pic.4khd.com/{seg1}/{seg2}/{seg3}/w1300-rw/{name}.webp?w=1300
|
||
```
|
||
|
||
去掉 `https://i0.wp.com/` 前缀、丢掉 `?w=1300` 查询串，就是源站直链：
|
||
|
||
```
|
||
https://pic.4khd.com/{seg1}/{seg2}/{seg3}/w1300-rw/{name}.webp
|
||
```
|
||
|
||
解析时一律转成源站直链（`OriginURL()`）。原因见下面的「为什么不用 Photon」。
|
||
|
||
- 路径里的 `w1300-rw` 是**原站自己的缩略图目录**，必须保留；
|
||
Photon 的 `?w=1300` 是它的 resize 参数，源站不认，要去掉
|
||
- 实测去掉查询串后字节数与 Photon 正常时**完全一致**，画质没变
|
||
- 源站**零防盗链**：裸 GET（无 Referer / Cookie / UA）直接 200
|
||
|
||
### 为什么不用 Photon（2026-10-11 实测教训）
|
||
|
||
Photon 是 WordPress 的**免费图片 CDN**。批量下载会打爆它的免费额度，
|
||
被封后返回：
|
||
|
||
```
|
||
HTTP 429
|
||
Access has been disabled due to excessive usage.
|
||
```
|
||
|
||
关键点：**这跟请求头无关**。实测对照同一张图、同一时刻：
|
||
|
||
| 请求方式 | 结果 |
|
||
|---|---|
|
||
| 我们的头（Chrome UA + Referer） | 429 |
|
||
| 完整浏览器头（+ Sec-Fetch-* / avif） | 429 |
|
||
| 裸请求（一个头都不发） | **429** |
|
||
| **源站直连**（`pic.4khd.com`） | **200，128056 字节** |
|
||
|
||
被封后连裸请求都 429，说明是**按 IP 的额度封禁**，不是指纹识别。
|
||
而浏览器还能正常加载，只是因为它那点量远没到限额。
|
||
|
||
源站压测：**20 并发全部成功，零限流**；连续下 50 张也全部成功。
|
||
|
||
### 遇到限流怎么办
|
||
|
||
即便换了源站，如果将来源站也开始限流，引擎有全局冷却机制：
|
||
|
||
- 认出 429/503/403 后，**所有 worker 一起停**（而不是各自退避重试）
|
||
- 优先遵守服务器给的 `Retry-After`，没给就按 10s→20s→40s→80s 指数退避
|
||
- 冷却期满一起放行
|
||
|
||
> 为什么必须「一起停」：40 个 worker 各自独立退避会错峰重试，
|
||
> 结果是持续往已限流的服务器打请求，永远缓不过来。
|
||
|
||
**每页必须去重**：每张图在 HTML 里出现**两次** —— 一次 `<a href>`、一次 `<img src>`，
|
||
内容完全相同。不去重的话 20 张会解析成 40 张（这个 bug 是被真实样本夹具测出来的）。
|
||
|
||
**推荐位图片怎么认**：正文图和推荐图走的是**同一个 CDN**，域名区分不了，只能靠特征：
|
||
|
||
- `4KHD-beautifulGirls.webp`（推荐位统一封面）
|
||
- `/w1090-h1500-p-k-no-rw/`（推荐位尺寸段）
|
||
- `?resize=`（推荐位查询参数）
|
||
|
||
> 路径第 3 段的时间戳**区分不了**两者 —— 实测两边形式完全一样，都是 base36 时间戳。
|
||
|
||
**分页**：`.page-link-box` 里每个页码是**独立的 `<li class="numpages">`**，
|
||
取最大值即总页数。
|
||
|
||
**不能追 `rel=next`**：页面里的 `rel="next"` 和 `canonical` 都指向已 404 的
|
||
`www.4khd.com`。所以引擎只按总页数自己拼 URL，不跟这条链。
|
||
|
||
**标题**：优先 `h3.wp-block-post-title`。
|
||
|
||
> ⚠️ 别抓 `<h1>` —— 那是站点名 "4KHD"，不是画廊标题。
|
||
> h3 里是**双空格**（`Myu_a(뮤아)␣␣SWEETBOX`，分享链接里的 `%20%20` 证实双空格才是原文），
|
||
> 而 `<title>` / `og:title` 被 WordPress 规范化成了单空格。解析时会折叠空白。
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
main.go Wails 入口
|
||
app.go 绑定层：把 Go 能力暴露给前端
|
||
wails.json Wails 配置
|
||
|
||
internal/hd4k/ ← 站点协议层（换站点只动这里）
|
||
site.go 站点配置、URL 解析、域名归一化
|
||
hd4k.go 抓取、图片 URL 提取、下载
|
||
limiter.go 限流器
|
||
testdata/ 真实页面样本（p1/p2/p3）
|
||
hd4k_test.go
|
||
manual_real_test.go 连真实站点的手动验证（-tags manual）
|
||
|
||
internal/core/ ← 与站点无关的通用引擎
|
||
store.go 任务表 + 设置（原子落盘）
|
||
engine.go 调度、并发、重试、断点续传
|
||
manifest.go .hd4k.json 清单读写
|
||
paths.go 目录模板与文件名清洗
|
||
bridge.go 127.0.0.1 本地桥口（给油猴用）
|
||
version.go 版本号、桥口 token
|
||
core_test.go
|
||
engine_test.go 端到端集成测试（本地假站点）
|
||
|
||
frontend/ 静态界面（无框架、无打包）
|
||
userscript/ 油猴脚本
|
||
```
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
```powershell
|
||
$env:PATH = "$env:USERPROFILE\.local\go\bin;$env:PATH"
|
||
go test ./internal/... -v
|
||
```
|
||
|
||
56 个顶层测试 + 3 个参数化子测试，全部离线跑（本地 `httptest` 假站点）。
|
||
|
||
关键覆盖：
|
||
|
||
- **真实页面夹具**：p1/p2/p3 三页真实 HTML，断言 20/20/13 张、共 53 张
|
||
- **解析器边界**：标题提取与实体解码、分页后缀剥离、别名域名归一
|
||
- **桥口**：token 校验（无 token → 403）、CORS 只放行已知站点、只绑回环地址
|
||
- **引擎端到端**：解析 → 下载 → 落盘 → 写清单 → 状态机整条链路
|
||
- **断点续传**：清单完整时重启 **0 网络请求**；清单信息不全时老实回退重抓
|
||
- **改目录模板**：复用老目录里已下好的文件，不重下
|
||
|
||
### 连真实站点验证（需网络，默认不跑）
|
||
|
||
```powershell
|
||
$env:HD4K_URL = "https://migmg.ssuu.uk/content/09/djawa-photo-vol0411-ddiddi-yummy-delivery.html"
|
||
$env:HD4K_N = "6"
|
||
go test -tags manual -run TestRealSiteDownload -v ./internal/hd4k/
|
||
```
|
||
|
||
---
|
||
|
||
## 应用图标
|
||
|
||
用的是站点自己的图标（`/wp-content/uploads/2023/02/4khd-1.png`，200×200）。
|
||
注意它在页面上挂的是已 404 的 `www.4khd.com`，所以从 `migmg.ssuu.uk` 取。
|
||
|
||
环境里没有 ImageMagick / ffmpeg / Python，所以 ICO 是自己生成的
|
||
（`tools/mkico`，10 个尺寸，小尺寸 BMP + 大尺寸 PNG-in-ICO）：
|
||
|
||
```powershell
|
||
go run ./tools/mkico -in build/icon-source.png -out build/windows/icon.ico
|
||
go run ./tools/icocheck build/windows/icon.ico <导出目录> # 校验 + 导出各尺寸看效果
|
||
go run ./tools/alphaprobe <某张图> # 打印采样点的 RGBA 与 alpha 分布
|
||
```
|
||
|
||
> 缩放必须用 box filter + premultiplied alpha。少做 premultiplied 那一步的话，
|
||
> 缩放结果会**反色**（橙色变纯白）—— 这就是 `alphaprobe` 存在的理由，
|
||
> 光看缩略图分不清是图错了还是预览器把透明当白底。
|
||
|
||
---
|
||
|
||
## 清理过小的图片
|
||
|
||
「清除已完成」按钮除了清任务列表，还会顺带**删掉画廊目录里小于 10KB 的图片**。
|
||
|
||
门槛 `MinImageBytes = 10KB`（`internal/core/paths.go`）取自实测：4KHD 正文图
|
||
最小也在 **90KB 以上**，而占位图 / 损坏图 / CDN 错误页伪装的图通常只有几 KB。
|
||
实测 50 张真实下载的图，最小 90.2 KB —— 10KB 门槛不会误伤正常图。
|
||
|
||
清扫规则：
|
||
|
||
- 只删**图片扩展名**的文件（`.webp .jpg .jpeg .png .gif .bmp .avif .jfif`）
|
||
- 清单（`.hd4k.json`）**不动** —— 要留着续传
|
||
- `.part` 未完成的下载**不动** —— 它可能正好小于门槛但其实没下完
|
||
- 非图片文件（`.txt` 等）不动
|
||
- 单个文件出错不中断整个清扫
|
||
|
||
没有已完成任务时也能用 —— 这时按钮只做「清理小图」这一步。
|
||
|
||
---
|
||
|
||
## 已知限制
|
||
|
||
- 解析器首选 `i\d+.wp.com` 精确匹配；一张都匹配不到时会退到宽松匹配
|
||
（任何图片扩展名 + 推荐位特征过滤），以防站点换 CDN 就全线失败
|
||
- 单个画廊最多抓 2000 页，防止异常页码把机器跑满
|
||
- 桥口 token 是明文常量，仅靠「只监听 127.0.0.1」防外部访问 —— 别把它暴露到公网
|
||
|
||
---
|
||
|
||
## 声明
|
||
|
||
本工具仅供个人学习与备份自己有权保存的内容使用。
|
||
使用者需自行遵守目标站点的条款与所在地区的法律，
|
||
因使用本工具产生的一切后果由使用者自行承担。 |