refactor: 全面重构代码并加白话注释,移动全局并行,去掉去向/重复记录

- 重构后端与前端,全程大白话注释(不懂程序也能看懂)
- 移动阶段改为全局并行(MoveAll,工人数=CPU核心数)
- 去掉记录每个文件搬去哪了(删除去向回填,解决写库卡顿)
- 去掉重复文件标记与统计:重复判定改为 MD5+路径都相同才算,重复则原地忽略不移动;MD5 相同但路径不同仍照常搬
- 媒体库去掉归类目录列,看板去掉重复/归类分布统计
This commit is contained in:
2025-05-11 21:05:35 +08:00
parent f915a9b1ac
commit 8979c744a8
26 changed files with 1044 additions and 683 deletions
+163 -135
View File
@@ -1,4 +1,13 @@
// Package organize 编排整理流程:探测 → 归类 → 收集 bucket → 一次性移动并记录去向。
// Package organize 是"整理"这一步的总指挥,负责把一批文件分门别类、搬到该去的地方。
//
// 整理一辆快递车的过程可以这样理解:
// 1. 探测(并行):每个文件先做"体检"——是图片还是视频?多大?什么分辨率?会不会是重复的?
// 2. 归类(串行):根据体检结果,决定这个文件该进哪个分类目录,或者直接判为重复/异常/忽略
// 3. 移动(并行):把每个分类目录攒齐的文件,批量搬进对应的文件夹,并把"搬去哪了"记进数据库
//
// 为什么探测要并行、归类要串行?
// - 探测很慢(读文件、算 MD5、调 ffprobe),多个一起干能明显提速;
// - 归类要看"前面有没有见过同样的文件"(去重判断),必须按顺序一个个来,否则会乱。
package organize
import (
@@ -18,32 +27,44 @@ import (
"kenaito-media-picker/internal/store"
)
// 特殊归类目录名
// ============================ 阶段与目录命名 ============================
// 整理内部的两个阶段名,上报进度时用,供上层(service)区分显示。
const (
dirImagePSD = "图片_PSD"
dirImageErr = "图片_读取异常"
dirImageIgnored = "图片_已忽略"
dirVideoErr = "视频_读取异常"
dirVideoIgnored = "视频_已忽略"
dirAudio = "音频"
dirDuplicate = "重复文件"
PhaseImages = "images" // 正在处理图片
PhaseMedia = "media" // 正在处理视频/音频
PhaseMove = "move" // 正在移动文件
)
// Organizer 整理器:按目标目录收集文件,处理完成后统一建目录并移动
// 特殊归类目录的名字(都是大白话,用户一眼能看懂)。
const (
dirImagePSD = "图片_PSD" // 没做任何处理,原样收走的 PSD 设计稿
dirImageErr = "图片_读取异常" // 打不开、读不出信息的图片
dirImageIgnored = "图片_已忽略" // 不支持的图片格式,原样收走但不做处理
dirVideoErr = "视频_读取异常" // 打不开、读不出信息的视频
dirVideoIgnored = "视频_已忽略" // 不支持的视频格式,原样收走
dirAudio = "音频" // 音频统一放这一个文件夹
)
// ============================ 整理器主体 ============================
// Organizer 整理器。它的工作方式:
// - 先把文件按"目标目录"分堆攒起来(buckets),
// - 攒完后统一创建目录、批量搬文件。
//
// 这样设计是为了避免"边分类边搬"导致目录反复开关、文件搬来搬去,效率更高。
type Organizer struct {
pickerDir string
ffprobePath string
store *store.Store
mover *mover.Mover
buckets map[string][]string // 目标目录 → 文件路径
order []string // 目标目录的创建顺序(保证输出稳定)
seenMd5 map[string]bool // 本次扫描已入库的 MD5(同一扫描内去重)
onProgress func(done, total int)
pending []*store.MediaInfo // 待批量入库的媒体记录
pendingDup []*store.MediaInfo // 待批量入库的重复文件记录
pickerDir string // 整理后的文件都放到这个根目录下
ffprobePath string // ffprobe 程序路径;为空表示没有可用解码器
store *store.Store // 数据库;为 nil 表示不记录媒体信息
mover *mover.Mover // 负责实际搬文件的家伙
buckets map[string][]string // 目标目录 → 里面该放哪些文件(只记源路径)
order []string // 目标目录的先后顺序(保证输出稳定、不来回跳)
onProgress func(phase string, done, total int)
pending []*store.MediaInfo // 待写入数据库的媒体记录(攒一批再批量写)
}
// New 创建整理器;store 可为 nil(数据库初始化失败时仅不记录信息)
// New 创建整理器。store 可以为 nil——数据库打不开时,整理照常进行,只是不记入库信息。
func New(pickerDir, ffprobePath string, st *store.Store) *Organizer {
return &Organizer{
pickerDir: pickerDir,
@@ -51,37 +72,40 @@ func New(pickerDir, ffprobePath string, st *store.Store) *Organizer {
store: st,
mover: &mover.Mover{},
buckets: make(map[string][]string),
seenMd5: make(map[string]bool),
}
}
// SetProgress 设置进度回调(done/total 为已处理文件数与总数)
func (o *Organizer) SetProgress(fn func(done, total int)) {
// SetProgress 设置进度回调。回调参数:
// - phase:当前在干哪一步(PhaseImages / PhaseMedia / PhaseMove)
// - done / total:这一步已完成数和总数
func (o *Organizer) SetProgress(fn func(phase string, done, total int)) {
o.onProgress = fn
}
// report 上报进度
func (o *Organizer) report(done, total int) {
// report 上报进度。total 为 0 表示这一步没活干,就不用报了。
func (o *Organizer) report(phase string, done, total int) {
if o.onProgress != nil && total > 0 {
o.onProgress(done, total)
o.onProgress(phase, done, total)
}
}
// workerCount 并行探测的 worker 数量:不超过 CPU 核数,且限制在 1~8 之间
// ============================ 并行小工具 ============================
// workerCount 并行探测的工人数:直接用满 CPU 核心数(空闲时的极限值)。
// 多核机器并行探测能明显提速;如果机器同时还在跑别的重活,再手动调低即可。
func workerCount() int {
n := runtime.NumCPU()
if n < 1 {
return 1
}
if n > 8 {
return 8
}
return n
}
// runParallel 用固定 worker 数并行处理切片,按原顺序收集结果。
// onProgress 在每次完成一个任务后调用(done 为已完成任务数,并发安全)。
// 返回 results[i] 对应 items[i] 的处理结果。
// runParallel 用固定数量的工人并行处理一批东西,结果按原来的顺序放回。
//
// 通俗理解:一条流水线有 N 个工人,每个工人从传送带上拿一个活干完,
// 干完把结果按编号放回架子上(results[i] 对应 items[i] 的结果)。
// onProgress 每干完一个活就报一次数(已完成几个),线程安全、只会涨不会退。
func runParallel[T any, R any](items []T, fn func(T) R, onProgress func(done int)) []R {
results := make([]R, len(items))
if len(items) == 0 {
@@ -114,7 +138,9 @@ func runParallel[T any, R any](items []T, fn func(T) R, onProgress func(done int
return results
}
// add 将文件归入某个子目录
// ============================ 分类与入库小工具 ============================
// add 把一个文件记到某个目标目录的名下(先攒着,最后统一搬)。
func (o *Organizer) add(f scanner.File, subDir string) {
dir := filepath.Join(o.pickerDir, subDir)
if _, ok := o.buckets[dir]; !ok {
@@ -123,8 +149,11 @@ func (o *Organizer) add(f scanner.File, subDir string) {
o.buckets[dir] = append(o.buckets[dir], f.Path)
}
// calcFileInfo 读取文件大小并计算 MD5(大文件优先用指纹复用已入库的 MD5,跳过全量读取)。
// store 为 nil 时直接返回空值(无需去重/入库)。
// calcFileInfo 读取文件大小并算 MD5(文件的"身份证号")。
//
// 大文件算全量 MD5 很费时间,所以先用"指纹"(文件大小 + 头尾各 256KB 的 MD5)
// 去数据库里找找看有没有同款——有的话直接借它的 MD5 用,省得再全量算一遍。
// store 为 nil 时直接返回空,因为没有数据库可查,也不需要去重/入库。
func (o *Organizer) calcFileInfo(f scanner.File) (md5Str, headMd5, tailMd5 string, size int64) {
if o.store == nil {
return "", "", "", 0
@@ -140,7 +169,7 @@ func (o *Organizer) calcFileInfo(f scanner.File) (md5Str, headMd5, tailMd5 strin
if head, tail, ferr := digest.CalcFileFingerprint(f.Path, size); ferr == nil {
headMd5, tailMd5 = head, tail
if existing, ok := o.store.FindMediaByFingerprint(size, head, tail); ok && existing.FileMd5 != "" {
md5Str = existing.FileMd5 // 指纹命中,复用MD5,跳过全量读取
md5Str = existing.FileMd5 // 指纹命中,复用已入库的 MD5,跳过全量计算
}
}
}
@@ -153,17 +182,17 @@ func (o *Organizer) calcFileInfo(f scanner.File) (md5Str, headMd5, tailMd5 strin
return md5Str, headMd5, tailMd5, size
}
// isDuplicate 判断文件是否重复:
// 1. 本次扫描已入库的 MD5 → 重复(同一扫描内去重)
// 2. 库中已有记录且其副本在磁盘上仍存在(DestPath)→ 重复
// 若库中副本已被移动/改名/删除,说明是同一文件被重新扫描,不算重复。
func (o *Organizer) isDuplicate(md5Str string) bool {
// isDuplicate 判断一个文件是不是"同一个文件又出现了一次"。
//
// 判据:数据库里已经有一条记录,**MD5 相同、源路径也相同**。
// 只有这种情况才认为是"同一个文件被重复扫到",直接忽略:不动它、不记录、不搬走。
//
// 特别注意:MD5 一样但**路径不一样**,那是另一个文件(碰巧内容一样),
// 不算重复,照样要搬进媒体库。
func (o *Organizer) isDuplicate(md5Str, path string) bool {
if md5Str == "" {
return false
}
if o.seenMd5[md5Str] {
return true
}
if o.store == nil {
return false
}
@@ -171,22 +200,10 @@ func (o *Organizer) isDuplicate(md5Str string) bool {
if !ok {
return false
}
if existing.DestPath != "" {
if _, err := os.Stat(existing.DestPath); err == nil {
return true
}
}
return false
return existing.FilePath == path
}
// markSeen 记录本次扫描已入库的 MD5(去重用)
func (o *Organizer) markSeen(md5Str string) {
if md5Str != "" {
o.seenMd5[md5Str] = true
}
}
// record 收集媒体信息到待入库缓冲(不立即写库,ProcessImages/ProcessMedia 结束统一批量提交)
// record 把一份媒体信息记到"待入库"缓冲里(先攒着,最后统一批量写库)。
func (o *Organizer) record(f scanner.File, mediaType string, res *probe.ProbeResult, md5Str, headMd5, tailMd5 string, size int64) {
if o.store == nil || md5Str == "" {
return
@@ -194,20 +211,14 @@ func (o *Organizer) record(f scanner.File, mediaType string, res *probe.ProbeRes
o.pending = append(o.pending, buildMediaInfo(f, mediaType, res, md5Str, headMd5, tailMd5, size))
}
// recordDuplicate 收集重复文件信息到待入库缓冲
func (o *Organizer) recordDuplicate(f scanner.File, mediaType string, res *probe.ProbeResult, md5Str, headMd5, tailMd5 string, size int64) {
if o.store == nil || md5Str == "" {
return
}
o.pendingDup = append(o.pendingDup, buildMediaInfo(f, mediaType, res, md5Str, headMd5, tailMd5, size))
}
// buildMediaInfo 构造入库记录
// buildMediaInfo 把探测结果整理成一条要入库的记录。
func buildMediaInfo(f scanner.File, mediaType string, res *probe.ProbeResult, md5Str, headMd5, tailMd5 string, size int64) *store.MediaInfo {
// 视频记视频编码,音频记音频编码
codec := res.VideoCodec
if mediaType == "audio" {
codec = res.AudioCodec
}
// 格式名:ffprobe 没读出来就用扩展名顶替(去掉前面的点)
format := res.Format
if format == "" && f.Ext != "" {
format = strings.TrimPrefix(f.Ext, ".")
@@ -231,7 +242,7 @@ func buildMediaInfo(f scanner.File, mediaType string, res *probe.ProbeResult, md
}
}
// flushRecords 将缓冲的媒体/重复记录批量提交入库
// flushRecords 把缓冲的媒体记录批量写进数据库(一次事务,快得多)。
func (o *Organizer) flushRecords() {
if o.store == nil {
return
@@ -242,47 +253,51 @@ func (o *Organizer) flushRecords() {
}
o.pending = nil
}
if len(o.pendingDup) > 0 {
if err := o.store.InsertDuplicateBatch(o.pendingDup); err != nil {
fmt.Printf("=== 批量保存重复文件信息失败: %v\n", err)
}
o.pendingDup = nil
}
}
// imageProbeResult 图片探测结果(并行阶段产出,串行阶段归类)
// ============================ 图片整理 ============================
// imageProbeResult 是"给一张图片做完体检"的结论,体检在并行阶段完成,
// 后面的归类(判断重复、分目录)在串行阶段根据这个结论来定。
type imageProbeResult struct {
psd bool // PSD 特殊归类
unsupported bool // 非白名单且无 ffprobe 兜底,忽略
probeErr bool // 探测失败,归入异常
res *probe.ProbeResult
md5Str string
headMd5 string
tailMd5 string
size int64
darkScore float64
lightScore float64
// 下面几个是"体检结论",最多只有一个为 true:
psd bool // 是 PSD 设计稿,不做处理原样收走
unsupported bool // 不支持的格式,归入"已忽略"
probeErr bool // 体检失败(打不开/读不出),归入"读取异常"
res *probe.ProbeResult // 体检出的尺寸等信息(体检成功时才有)
md5Str string // 文件 MD5
headMd5 string // 文件头采样 MD5(大文件指纹)
tailMd5 string // 文件尾采样 MD5
size int64 // 文件大小
darkScore float64 // 暗色像素占比(用于亮度分类)
lightScore float64 // 亮色像素占比
}
// probeImage 并行探测一张图片:探测尺寸 + MD5 + 明暗分析(不含重复判断/归类/入库)。
// 注意:不访问 o.seenMd5 等共享可变状态,仅读 store(指纹复用),并行安全。
// probeImage 给一张图片做体检(并行阶段执行):探测尺寸 + 算 MD5 + 分析明暗。
// 注意:这里不能碰 o.buckets 之类的共享可变状态,因为多个工人同时跑;
// 只读数据库(查指纹),这是安全的。
func (o *Organizer) probeImage(f scanner.File) imageProbeResult {
r := imageProbeResult{}
// PSD 不体检,直接标记"原样收走"
if strings.EqualFold(f.Ext, ".psd") {
r.psd = true
return r
}
// 格式不认识,又没有 ffprobe 兜底 → 标记"忽略"
if !probe.IsSupportImage(f.Ext) && o.ffprobePath == "" {
r.unsupported = true
return r
}
// 探测尺寸
res, err := probe.ProbeImage(f.Path, o.ffprobePath)
if err != nil {
r.probeErr = true
return r
}
r.res = res
// 算 MD5(顺便拿指纹,可能省掉全量计算)
r.md5Str, r.headMd5, r.tailMd5, r.size = o.calcFileInfo(f)
// 分析明暗(GIF 不做,动画图逐帧分析没意义)
if !strings.EqualFold(f.Ext, ".gif") {
dark, light, berr := probe.AnalyzeBrightness(f.Path)
if berr != nil {
@@ -294,34 +309,37 @@ func (o *Organizer) probeImage(f scanner.File) imageProbeResult {
return r
}
// ProcessImages 处理全部图片:并行探测(尺寸/MD5/明暗)→ 串行去重归类
// ProcessImages 处理全部图片:先并行体检,再按顺序一个个归类。
func (o *Organizer) ProcessImages(images []scanner.File) {
// 统计结果,最后打一行总结给用户看
success, fail, ignore, dup := 0, 0, 0, 0
total := len(images)
results := runParallel(images, o.probeImage, func(done int) {
o.report(done, total)
o.report(PhaseImages, done, total)
})
for i, r := range results {
f := images[i]
switch {
case r.psd:
// PSD 设计稿:不做处理,原样收进「图片_PSD」
o.add(f, dirImagePSD)
success++
case r.unsupported:
// 不支持的格式:原样收进「图片_已忽略」
o.add(f, dirImageIgnored)
ignore++
case r.probeErr:
// 体检失败:收进「图片_读取异常」
o.add(f, dirImageErr)
fail++
fmt.Printf("=== 异常图片: %s \n", f.Path)
case o.isDuplicate(r.md5Str):
o.recordDuplicate(f, "image", r.res, r.md5Str, r.headMd5, r.tailMd5, r.size)
o.add(f, dirDuplicate)
case o.isDuplicate(r.md5Str, f.Path):
// 同一个文件又出现一次:直接忽略,不动它、不记录
dup++
fmt.Printf("=== 重复图片: %s \n", f.Path)
fmt.Printf("=== 重复图片(同路径), 忽略: %s \n", f.Path)
default:
// 正常图片:按分辨率/方向/明暗归入对应的分类目录
o.record(f, "image", r.res, r.md5Str, r.headMd5, r.tailMd5, r.size)
o.markSeen(r.md5Str)
o.add(f, classify.ImageDir(f.Ext, r.res.Width, r.res.Height, r.darkScore, r.lightScore))
success++
}
@@ -329,22 +347,26 @@ func (o *Organizer) ProcessImages(images []scanner.File) {
fmt.Printf("=== 图片处理完毕,成功: %d, 读取异常: %d, 忽略: %d, 重复: %d \n\n", success, fail, ignore, dup)
}
// mediaProbeResult 媒体探测结果(并行阶段产出,串行阶段归类)
// ============================ 视频/音频整理 ============================
// mediaProbeResult 是"给一个视频/音频做完体检"的结论(并行阶段产出)。
type mediaProbeResult struct {
res *probe.ProbeResult
err error
md5 string
head string
tail string
size int64
res *probe.ProbeResult // 体检结果(ffprobe 读出的信息)
err error // 体检失败的原因
md5 string // 文件 MD5
head string // 文件头采样 MD5
tail string // 文件尾采样 MD5
size int64 // 文件大小
}
// probeMedia 并行探测一个媒体文件(ffprobe + MD5)。不访问共享可变状态。
// probeMedia 给一个媒体文件做体检(并行阶段执行):调 ffprobe 读信息 + 算 MD5。
// 不访问任何共享可变状态,多个工人可以同时跑。
func (o *Organizer) probeMedia(f scanner.File) mediaProbeResult {
res, err := probe.ProbeMediaFile(o.ffprobePath, f.Path)
if err != nil {
return mediaProbeResult{err: err}
}
// 既没有视频流也没有音频流:说明根本不是媒体,不用算 MD5 了
if !res.HasVideo && !res.HasAudio {
return mediaProbeResult{res: res}
}
@@ -352,18 +374,23 @@ func (o *Organizer) probeMedia(f scanner.File) mediaProbeResult {
return mediaProbeResult{res: res, md5: md5, head: head, tail: tail, size: size}
}
// ProcessMedia 处理媒体候选:并行 ffprobe 判定 → 串行去重归类
// ProcessMedia 处理全部媒体候选:先并行体检,再按顺序一个个归类。
//
// 特别说明:文件虽然进了"媒体候选"名单,但很多其实是"不知道是什么"的文件
// (比如扩展名被改过、或者 MIME 没认出来)。ffprobe 一探便知真假——
// 探出有视频/音频流的就是真媒体,探不出来的就看它的 MIME 是不是明确标注了媒体类型。
func (o *Organizer) ProcessMedia(media []scanner.File) {
video, audio, fail, ignore, dup := 0, 0, 0, 0, 0
total := len(media)
results := runParallel(media, o.probeMedia, func(done int) {
o.report(done, total)
o.report(PhaseMedia, done, total)
})
for i, r := range results {
f := media[i]
// ---------- 体检失败 ----------
if r.err != nil {
// 仅 MIME 明确为视频/音频的文件才移入异常/忽略目录;
// octet-stream/空 MIME 且 ffprobe 无法确认的原地忽略,不移动
// 只有 MIME 明确说是视频/音频的才收进"异常/忽略"目录;
// 完全没头绪的文件(MIME 为空或 octet-stream)原地不管,不搬走
if strings.HasPrefix(f.Mime, "video/") {
fail++
o.add(f, dirVideoErr)
@@ -377,33 +404,33 @@ func (o *Organizer) ProcessMedia(media []scanner.File) {
}
continue
}
// ---------- 体检成功:看它到底是什么 ----------
switch {
case r.res.HasVideo:
if o.isDuplicate(r.md5) {
o.recordDuplicate(f, "video", r.res, r.md5, r.head, r.tail, r.size)
// 有视频流 → 视频
if o.isDuplicate(r.md5, f.Path) {
// 同一个文件又出现一次:直接忽略,不动它、不记录
dup++
o.add(f, dirDuplicate)
fmt.Printf("=== 重复媒体: %s \n", f.Path)
fmt.Printf("=== 重复媒体(同路径), 忽略: %s \n", f.Path)
continue
}
video++
o.record(f, "video", r.res, r.md5, r.head, r.tail, r.size)
o.markSeen(r.md5)
o.add(f, classify.VideoDir(f.Ext, r.res.Width, r.res.Height))
case r.res.HasAudio:
if o.isDuplicate(r.md5) {
o.recordDuplicate(f, "audio", r.res, r.md5, r.head, r.tail, r.size)
// 有音频流 → 音频
if o.isDuplicate(r.md5, f.Path) {
// 同一个文件又出现一次:直接忽略,不动它、不记录
dup++
o.add(f, dirDuplicate)
fmt.Printf("=== 重复媒体: %s \n", f.Path)
fmt.Printf("=== 重复媒体(同路径), 忽略: %s \n", f.Path)
continue
}
audio++
o.record(f, "audio", r.res, r.md5, r.head, r.tail, r.size)
o.markSeen(r.md5)
o.add(f, dirAudio)
default:
// ffprobe 无音视频流:MIME 明确为媒体的归入忽略目录,其余原地不动
// 没有视频流也没有音频流 → 假媒体。
// MIME 明确标注是媒体的,收进「已忽略」;否则原地不动。
if scanner.IsExplicitMediaMime(f.Mime) {
ignore++
o.add(f, dirVideoIgnored)
@@ -416,25 +443,26 @@ func (o *Organizer) ProcessMedia(media []scanner.File) {
fmt.Printf("=== 媒体处理完毕,视频: %d, 音频: %d, 读取异常: %d, 忽略: %d, 重复: %d \n\n", video, audio, fail, ignore, dup)
}
// Flush 先将缓冲的媒体记录批量入库,再将收集到的文件移动到对应目录并回填归类去向。
// 移动期间按累计完成数上报进度。
// ============================ 移动(最后一步) ============================
// Flush 收尾两步:
// 1. 把之前攒的媒体记录一次性写进数据库;
// 2. 把每个分类目录攒的文件**全局并行**搬过去(所有目录的文件一起搬)。
// 不需要记录每个文件搬去哪了——文件就在分类目录里,一眼能看到。
func (o *Organizer) Flush() {
o.flushRecords()
total := 0
// 把 buckets 里所有文件拼成一张"搬运清单"
jobs := make([]mover.MoveJob, 0)
for _, dir := range o.order {
total += len(o.buckets[dir])
}
movedAll := 0
for _, dir := range o.order {
onProgress := func(done int) {
o.report(movedAll+done, total)
}
moved := o.mover.MoveToDir(o.buckets[dir], dir, onProgress)
movedAll += len(o.buckets[dir])
for src, dest := range moved {
if err := o.store.UpdateMediaDest(src, dir, dest); err != nil {
fmt.Printf("=== 更新媒体去向失败: %s, 错误: %v\n", src, err)
}
for _, src := range o.buckets[dir] {
jobs = append(jobs, mover.MoveJob{Source: src, TargetDir: dir})
}
}
// 全局并行搬完:不管文件分散在几个目录,所有文件同时开搬。
// onProgress 收到的是全局累计已搬数,正好和总数对得上。
o.mover.MoveAll(jobs, func(done int) {
o.report(PhaseMove, done, len(jobs))
})
}