LiuMangMang/music-metadata-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
feature/p6-frontend
music-metadata-system/docs/总方案/音乐元数据标准化与归档系统 需求梳理 + 架构技术方案.md

40 KiB
Raw Permalink Blame History

音乐元数据标准化与归档系统 需求梳理+架构技术方案

文档版本：V1.0 修订日期：2026年03月15日 文档状态：正式版 技术约束：后端Java + GraalVM原生编译、前端Vue技术栈 核心适配：Navidrome音乐服务器官方最佳实践

一、文档概述

1.1 文档目的

本文档完整梳理「音乐元数据标准化与归档系统」的业务需求、架构设计、核心规则、技术实现与落地路径，为系统开发、测试、部署提供全流程指导，确保系统最终实现元数据零错误识别、目录结构100%适配Navidrome、全流程自动化+人工兜底可控的核心目标。

1.2 适用范围

  • 业务范围：个人/家庭级音乐库元数据标准化、自动归档、全生命周期管理
  • 技术范围：后端Java服务开发、GraalVM原生编译适配、Vue前端可视化界面开发、Navidrome音乐库适配
  • 读者对象：开发人员、测试人员、系统运维人员、最终用户

1.3 术语定义

术语 全称 说明
元数据 Music Metadata 音乐文件内嵌的标签信息，包括歌曲标题、歌手、专辑、封面、曲目编号等核心信息
音频指纹 Acoustic Fingerprint 基于音频内容生成的唯一特征码，不受元数据、格式、比特率影响，用于精准识别歌曲
归档 Archiving 按规范规则重命名文件、生成标准化目录结构，将音乐文件整理到目标音乐库的过程
增量入库 Incremental Storage 仅处理新增的音乐文件，跳过已处理完成的文件，避免重复归档
原生镜像 Native Image 基于GraalVM将Java程序编译为平台相关的可执行文件，实现极速启动、低内存占用

二、项目背景与目标

2.1 项目背景

个人/家庭音乐库的文件来源多样（CD抓取、网络下载、音频转录等），普遍存在以下核心痛点：

  1. 元数据不规范：字段缺失、乱码、格式不统一，导致Navidrome等流媒体服务器无法正确识别歌手、专辑、封面、歌词等信息
  2. 目录结构混乱：无统一归档规则，文件存放分散，Navidrome扫描后出现歌手分裂、专辑错乱、曲目排序错误等问题
  3. 重复文件冗余：同一首歌存在多个版本，占用存储空间，音乐库管理混乱
  4. 无标准化管理能力：缺失元数据的文件无统一兜底处理流程，最终成为音乐库中的“无效文件”

2.2 核心目标

  1. 标准化适配：建立严格的元数据校验规则，确保处理后的音乐文件100%被Navidrome及主流播放器完整识别
  2. 自动化归档：按预设规则自动完成音乐文件的目录整理、重命名、元数据写入，无需人工干预合规文件
  3. 全流程可控：对不符合规范的文件进行精准标记、全链路记录，通过可视化界面实现人工补全兜底
  4. 增量高效处理：支持重复调用，仅处理新增文件，内置多级去重能力，避免重复入库
  5. 高性能轻量化：基于GraalVM实现原生编译，实现毫秒级启动、低内存占用，适配家庭级单机部署场景

2.3 次要目标

  1. 支持多格式音频文件的元数据读写，覆盖主流无损/有损音频格式
  2. 提供可视化的处理进度监控、处理报告、数据统计能力
  3. 不修改、不删除用户原始源文件，保障源文件安全
  4. 提供可配置的规则扩展能力，适配不同播放器的元数据规范

三、需求详细梳理

3.1 功能性需求

3.1.1 音乐源接入模块

支持两种核心输入方式，覆盖批量处理与单文件快速处理场景：

  1. 本地目录批量接入
    • 支持用户指定本地音乐源目录，支持多级目录递归扫描
    • 支持配置文件格式过滤，仅扫描指定后缀的音频文件
    • 支持扫描断点续传，异常中断后可从断点继续扫描，无需重新全量扫描
    • 支持扫描进度实时反馈，前端展示已扫描文件数、待处理文件数
  2. 前端页面文件上传
    • 支持单个/多个音乐文件批量上传，支持拖拽上传
    • 支持大文件分片上传，断点续传
    • 上传完成后自动触发元数据校验与处理流程
    • 支持上传文件格式校验，拒绝非支持的音频格式

3.1.2 元数据解析与校验模块（核心）

  1. 全格式元数据解析：支持MP3(ID3v1/v2)、FLAC(Vorbis Comment)、M4A(MP4 Metadata)、OGG、WAV主流音频格式的元数据读取与写入
  2. 编码自动检测与校验：自动检测元数据原始编码，强制校验是否为UTF-8编码，非UTF-8编码且无法正常转换的直接标记失败
  3. 一票否决制强制校验：明确核心必填字段，任一必填字段不满足规范要求，直接标记为处理失败，不进行任何猜测式补全，仅记录失败原因
  4. 非必填字段提示：对建议字段的缺失/不规范进行记录，不影响归档，仅在处理报告中提示用户补全
  5. 元数据快照存储：对所有处理文件的原始元数据进行快照存储，用于后续人工处理溯源与回滚

3.1.3 元数据权威补全模块

仅保留基于音频指纹的权威API补全作为唯一自动补全手段，无任何文件名/目录结构的猜测式补全，确保元数据准确性：

  1. 音频指纹提取：对校验失败的文件，自动提取音频指纹，生成唯一特征码
  2. 权威API对接：对接AcoustID音频指纹识别API、MusicBrainz开源音乐元数据库API，获取歌曲权威元数据
  3. 补全数据二次校验：API返回的元数据必须再次通过「一票否决制」强制校验，校验通过方可写入文件，校验不通过仍标记为失败
  4. API调用限流与容错：内置API调用频率限制、超时重试、异常降级机制，避免因第三方API故障导致处理流程中断

3.1.4 文件去重与增量入库模块

  1. 多级去重算法
    • 一级快速去重：计算文件SHA-256哈希值，与数据库中已归档文件哈希比对，完全一致直接跳过
    • 二级特征去重：哈希不同，但「歌手+歌曲标题+专辑+音频时长」完全一致，标记为疑似重复，进入人工确认队列，不自动归档
    • 三级指纹去重：音频指纹一致，判定为同一首歌的不同版本，标记为疑似重复，进入人工确认队列
  2. 增量入库能力
    • 每次处理任务启动时，先扫描源目录生成文件哈希清单，与已处理完成的清单比对，仅对新增/修改的文件进行处理
    • 支持全量重扫配置，用户可手动触发全量文件重新校验
    • 已标记为失败的文件，支持手动触发重新处理，无需重新扫描全目录

3.1.5 自动分类归档模块

严格遵循双规则归档，100%适配Navidrome官方推荐最佳实践，归档文件默认采用复制模式，不修改/删除原始源文件：

  1. 一级分类规则：按专辑艺术家名称首字母分为A-Z 26个目录，非字母开头（中文、数字、符号等）的专辑艺术家统一归入#目录
  2. 底层目录规则：严格遵循Navidrome官方规范，最终目录结构为： 
    目标音乐库根目录/
├── A/
│   └── 专辑艺术家名称/
│       └── 专辑名称/
│           ├── 01 - 歌曲标题.flac
│           ├── 02 - 歌曲标题.flac
│           ├── cover.jpg
│           └── 01 - 歌曲标题.lrc
├── B/
│   └── 专辑艺术家名称/
...
└── #/
    └── 非字母开头专辑艺术家名称/
        └── 专辑名称/
            └── 01 - 歌曲标题.mp3
  3. 文件名规范化规则：统一命名格式为2位曲目编号 - 歌曲标题.文件扩展名，曲目编号不足2位补前导零，去除文件名中不支持的特殊字符
  4. 封面与歌词归档规则
    • 封面：必须内嵌到音频文件中，同时在专辑目录下生成cover.jpg（Navidrome优先读取），自动缩放为800x800正方形分辨率，格式为JPG
    • 歌词：支持内嵌LRC时间轴歌词，同时在同级目录下生成与歌曲同名.lrc文件，强制UTF-8编码
  5. 归档冲突处理：目标目录已存在同名文件时，自动比对哈希值，哈希一致则跳过，哈希不一致则保留两个文件并标记冲突，等待人工处理

3.1.6 失败文件统一管理模块（核心兜底）

对所有处理失败的文件进行全生命周期管理，提供可视化人工处理界面，确保所有文件可追溯、可兜底：

  1. 失败文件全信息记录：记录文件原始路径、文件名、哈希值、失败原因、原始元数据快照、失败时间、处理状态
  2. 失败原因结构化存储：精准标记失败类型，包括：必填字段缺失、编码乱码、封面不符合规范、API未匹配、曲目编号格式错误等
  3. 可视化列表管理
    • 支持按失败类型、处理状态、时间范围、歌手/专辑名称筛选搜索
    • 支持批量重新提交处理、批量删除操作
    • 列表展示文件核心信息、失败原因摘要、处理状态、操作按钮
  4. 元数据人工编辑页面
    • 内置音频预览播放器，支持试听文件，确认歌曲信息
    • 核心必填字段表单编辑，带必填校验与格式校验
    • 封面上传/在线搜索获取功能，自动缩放裁剪
    • 歌词上传/在线搜索获取功能，支持LRC格式校验
    • 对接MusicBrainz API提供字段自动补全建议，提升人工处理效率
  5. 人工处理提交流程：编辑完成后提交，系统自动重新执行全流程校验，校验通过则完成归档，更新状态为已解决；校验不通过则更新失败原因，返回编辑页面

3.1.7 系统管理模块

  1. 基础配置管理：目标音乐库根目录配置、归档模式（复制/移动）配置、封面分辨率配置、API密钥配置、必填字段可配置开关
  2. 任务管理：处理任务的创建、暂停、继续、终止，任务进度实时监控，历史任务记录查询
  3. 处理报告：每次任务完成后生成详细报告，包括处理总数、成功数、失败数、重复数、失败原因统计、文件清单导出
  4. 日志管理：系统操作日志、处理日志、错误日志的查询与导出，支持日志级别配置
  5. 数据备份与恢复：支持系统数据库、配置文件的手动/自动备份与恢复

3.2 非功能性需求

  1. 性能需求
    • 批量处理能力：单机环境下，每秒可处理≥5个音频文件（不含第三方API调用时间）
    • 启动速度：基于GraalVM原生编译后，服务启动时间≤500ms
    • 内存占用：原生镜像运行时，稳态内存占用≤200MB
    • 大文件支持：支持最大2GB的单音频文件处理
  2. 兼容性需求
    • 音频格式：兼容MP3、FLAC、M4A、OGG、WAV主流音频格式
    • 系统兼容：支持Windows、Linux、macOS三大主流操作系统
    • Navidrome兼容：严格适配Navidrome最新稳定版，确保扫描零错误、识别零异常
    • 浏览器兼容：前端界面支持Chrome、Edge、Firefox主流浏览器
  3. 稳定性需求
    • 异常容错：单个文件处理失败不影响整体任务流程，异常文件自动标记并跳过
    • 断点续传：扫描、处理、上传流程均支持断点续传，异常中断后可恢复
    • 数据安全：不修改、不删除原始源文件，元数据写入前自动备份原始文件
    • 服务可用性：全年可用率≥99.9%，无内存泄漏、无进程崩溃问题
  4. 易用性需求
    • 前端界面简洁直观，核心功能3步内可完成操作
    • 处理进度可视化，失败原因清晰易懂，人工编辑门槛低
    • 提供一键批量处理能力，无需复杂配置即可完成标准化归档
  5. 安全性需求
    • 文件操作权限控制：仅对用户授权的目录进行读写操作
    • 无网络泄露：本地文件处理全程不传输原始音频文件，仅音频指纹特征码用于第三方API查询
    • 配置加密：第三方API密钥等敏感配置采用加密存储

3.3 约束条件

  1. 技术栈约束：后端必须采用Java语言开发，基于GraalVM实现原生编译；前端必须采用Vue技术栈开发
  2. 兼容性约束：归档目录结构、元数据规范必须严格遵循Navidrome官方最佳实践，不得自定义非兼容规则
  3. 数据安全约束：默认采用复制模式归档，禁止未经用户授权修改、删除原始源文件
  4. 元数据规则约束：必填字段不满足规范必须标记为失败，禁止任何无权威来源的猜测式自动补全

四、整体架构设计

4.1 分层架构设计

采用经典的DDD分层架构，实现业务与技术解耦，便于扩展与维护，同时适配GraalVM原生编译要求：

层级 核心职责 核心组件
接入层 负责系统对外的所有接入入口，处理用户请求与文件接入 Vue前端界面、HTTP接口服务、本地目录扫描器、文件上传服务
应用层 编排核心业务流程，处理事务控制，不包含核心业务规则 任务管理服务、文件处理流程编排服务、失败文件管理服务、系统配置服务
领域层 实现系统核心业务规则与领域逻辑，是系统的核心 元数据校验规则、归档规则、去重规则、音频指纹识别领域服务、元数据读写领域服务
基础设施层 为上层提供技术能力支撑，封装底层技术实现，适配GraalVM原生编译 文件操作组件、元数据读写组件、音频指纹提取组件、第三方API客户端、数据库访问组件、图片处理组件、日志组件
数据层 负责系统数据持久化与文件存储 关系型数据库、本地文件系统、目标音乐库目录

4.2 核心业务全流程

graph TD
    A[任务启动：目录扫描/文件上传] --> B[生成文件清单，计算SHA-256哈希]
    B --> C{哈希比对：是否已归档?}
    C -->|是| D[标记为已重复，跳过处理]
    C -->|否| E[读取文件原始元数据，生成快照]
    E --> F{核心必填字段校验：是否全部合规?}
    F -->|是| G[进入去重二次校验]
    F -->|否| H[提取音频指纹，调用AcoustID+MusicBrainz API]
    H --> I{API是否返回完整合规元数据?}
    I -->|是| J[写入API元数据到文件，二次校验必填字段]
    J --> K{二次校验是否通过?}
    K -->|是| G
    K -->|否| L[标记为处理失败，记录结构化失败原因]
    I -->|否| L
    L --> M[存入失败文件数据库，状态为待处理]
    M --> N[前端失败管理页面人工编辑补全]
    N --> E
    G -->{二次去重：是否疑似重复?}
    -->|是| O[标记为疑似重复，进入人工确认队列]
    -->|否| P[按Navidrome规范生成目录与文件名]
    P --> Q[写入标准化元数据、封面、歌词]
    Q --> R[复制文件到目标音乐库归档目录]
    R --> S[更新数据库，标记为处理完成]
    S --> T[任务结束，生成处理报告]

4.3 部署架构设计

系统支持两种部署模式，优先适配家庭用户单机部署场景，同时支持Docker容器化部署：

4.3.1 单机部署模式（推荐）

基于GraalVM原生镜像部署，无需安装JDK环境，解压即可运行，适配Windows/Linux/macOS：

  1. 前端Vue项目打包为静态资源，内置到后端原生镜像中，单文件启动
  2. 数据库采用嵌入式H2数据库，无需额外安装数据库服务
  3. 直接读写本地文件系统，无网络转发损耗，性能最优

4.3.2 Docker容器化部署模式

  1. 基于GraalVM原生镜像构建Docker镜像，镜像体积小（≤100MB），启动速度快
  2. 支持目录挂载，将源音乐目录、目标音乐库目录、配置目录挂载到宿主机
  3. 支持Docker Compose一键部署，适配NAS、家庭服务器等Linux环境

五、元数据标准化核心规则（强制执行）

5.1 字段规范与一票否决制

5.1.1 核心必填字段（缺一不可，不满足直接标记失败）

字段名 英文标识 强制规范要求 Navidrome依赖等级
歌曲标题 title 非空、无乱码、UTF-8编码、长度≥1字符，去除首尾空格 ⭐⭐⭐⭐⭐
歌手 artist 非空、无乱码、UTF-8编码、长度≥1字符，去除首尾空格 ⭐⭐⭐⭐⭐
专辑艺术家 album_artist 非空、无乱码、UTF-8编码、长度≥1字符，合辑/单曲默认与artist一致，必须显式存在 ⭐⭐⭐⭐⭐
专辑名 album 非空、无乱码、UTF-8编码、长度≥1字符，去除首尾空格 ⭐⭐⭐⭐⭐
曲目编号 track 格式必须为「序号/总曲目数」，序号与总曲目数均为正整数，序号≤总曲目数，序号不足2位补前导零 ⭐⭐⭐⭐⭐
专辑封面 cover 必须内嵌到音频文件中，图片格式为JPG/PNG，分辨率≥300x300，宽高比1:1 ⭐⭐⭐⭐⭐

5.1.2 建议补充字段（缺失不标记失败，仅提示补全）

字段名 英文标识 规范要求
发行年份 year 4位数字格式，范围1900-当前年份
流派 genre 标准音乐流派术语，多个流派用分号分隔
歌词 lyrics UTF-8编码，支持LRC时间轴格式，内嵌到音频文件中
光盘编号 disc 格式为「序号/总光盘数」，多光盘专辑必填
备注 comment 用于记录版本信息（Live/Remix等），无乱码

5.2 元数据清洗强制规则

仅对合规字段进行标准化清洗，不修改字段核心含义，清洗后仍需满足必填规范：

  1. 编码规范：所有元数据强制转换为UTF-8编码，无法正常转换、出现乱码的字段直接标记失败
  2. 特殊字符处理：去除字段首尾空格、换行符、不可见特殊字符；目录/文件名不支持的字符\ / : * ? " < > |统一替换为_
  3. 分隔符规范：多个歌手/流派统一用英文分号+空格; 分隔，替换原有的&、feat.、/等分隔符
  4. 大小写规范：英文单词首字母大写，特殊冠词（a/an/the）句中非首字母小写，统一格式
  5. 版本信息规范：歌曲标题中的Live/Remix/伴奏等版本信息，统一移至comment字段，标题仅保留歌曲核心名称

5.3 唯一自动补全规则

仅支持基于音频指纹的权威API补全，禁止任何基于文件名、目录结构的猜测式补全：

  1. 补全数据源仅认可AcoustID+MusicBrainz返回的权威元数据，其他第三方数据源不纳入自动补全范围
  2. API返回的元数据必须完整覆盖所有核心必填字段，且符合规范要求，方可自动写入
  3. 写入前必须进行二次校验，任一必填字段不满足规范，仍标记为失败，不进行部分字段补全
  4. 人工编辑场景下，可提供MusicBrainz API搜索建议，由用户手动确认后写入，不自动覆盖

六、数据库设计

采用嵌入式H2数据库，适配GraalVM原生编译，支持单机运行无需额外部署，核心表结构如下：

6.1 文件处理记录表（t_file_process）

记录所有文件的全流程处理信息，是系统的核心主表

字段名 数据类型 主键 非空 说明
id BIGINT 是 是 自增主键
file_hash VARCHAR(64) 否 是 文件SHA-256哈希值，唯一索引
source_file_path VARCHAR(1000) 否 是 原始源文件完整路径
source_file_name VARCHAR(200) 否 是 原始文件名
file_extension VARCHAR(10) 否 是 文件扩展名
file_size BIGINT 否 是 文件大小（字节）
audio_duration INT 否 否 音频时长（秒）
raw_metadata TEXT 否 是 原始元数据快照，JSON格式存储
process_status VARCHAR(20) 否 是 处理状态：PENDING(待处理)/PROCESSING(处理中)/SUCCESS(已完成)/FAIL(处理失败)/DUPLICATE(已重复)/CONFLICT(冲突)
fail_reason TEXT 否 否 失败原因，结构化JSON格式存储
target_file_path VARCHAR(1000) 否 否 归档后目标文件完整路径
task_id BIGINT 否 是 所属处理任务ID
created_at DATETIME 否 是 记录创建时间
updated_at DATETIME 否 是 最后更新时间

6.2 失败文件管理表（t_fail_file）

专门存储处理失败的文件信息，用于人工兜底处理

字段名 数据类型 主键 非空 说明
id BIGINT 是 是 自增主键
file_process_id BIGINT 否 是 关联文件处理记录表ID，外键
file_hash VARCHAR(64) 否 是 文件SHA-256哈希值，唯一索引
source_file_path VARCHAR(1000) 否 是 原始源文件完整路径
file_name VARCHAR(200) 否 是 文件名
fail_type VARCHAR(50) 否 是 失败类型：MISSING_FIELD(字段缺失)/ENCODING_ERROR(编码乱码)/COVER_INVALID(封面无效)/API_NO_MATCH(API未匹配)/TRACK_FORMAT_ERROR(曲目格式错误)/OTHER(其他)
fail_detail TEXT 否 是 失败详细原因，结构化JSON格式
raw_metadata TEXT 否 是 原始元数据快照，JSON格式
edit_metadata TEXT 否 否 人工编辑后的元数据草稿，JSON格式
status VARCHAR(20) 否 是 处理状态：PENDING(待处理)/EDITING(编辑中)/RESOLVED(已解决)/DISCARDED(已废弃)
created_at DATETIME 否 是 失败记录创建时间
updated_at DATETIME 否 是 最后编辑时间
resolved_at DATETIME 否 否 解决时间

6.3 处理任务表（t_process_task）

记录每次批量处理任务的信息，用于任务管理与进度追踪

字段名 数据类型 主键 非空 说明
id BIGINT 是 是 自增主键
task_name VARCHAR(100) 否 是 任务名称
task_type VARCHAR(20) 否 是 任务类型：DIR_SCAN(目录扫描)/UPLOAD(文件上传)/REPROCESS(重新处理)
source_path VARCHAR(1000) 否 否 源目录路径（目录扫描任务）
total_file_count INT 否 是 总文件数
processed_count INT 否 是 已处理文件数
success_count INT 否 是 处理成功数
fail_count INT 否 是 处理失败数
duplicate_count INT 否 是 重复文件数
task_status VARCHAR(20) 否 是 任务状态：RUNNING(运行中)/PAUSED(已暂停)/FINISHED(已完成)/TERMINATED(已终止)/ERROR(异常中断)
start_time DATETIME 否 是 任务启动时间
end_time DATETIME 否 否 任务结束时间
created_by VARCHAR(50) 否 是 创建人
remark VARCHAR(500) 否 否 任务备注

6.4 系统配置表（t_system_config）

存储系统全局配置信息，支持可视化配置修改

字段名 数据类型 主键 非空 说明
id BIGINT 是 是 自增主键
config_key VARCHAR(100) 否 是 配置键，唯一索引
config_value TEXT 否 否 配置值
config_name VARCHAR(100) 否 是 配置名称
config_desc VARCHAR(500) 否 否 配置描述
is_editable TINYINT 否 是 是否可前端编辑：0-否，1-是
created_at DATETIME 否 是 创建时间
updated_at DATETIME 否 是 最后更新时间

七、技术栈选型与实现方案

7.1 后端技术栈（Java + GraalVM）

技术组件 选型 版本要求 选型说明
核心框架 Spring Boot 3.x ≥3.2.0 原生支持GraalVM Native Image，生态完善，适配嵌入式开发
原生编译支持 Spring Native 与Spring Boot版本一致 官方提供的GraalVM原生编译适配方案，解决反射、动态代理等原生镜像兼容问题
数据库访问 MyBatis-Plus ≥3.5.5 轻量级ORM框架，适配GraalVM原生编译，简化数据库操作
嵌入式数据库 H2 Database ≥2.2.224 嵌入式关系型数据库，无需额外部署，单文件运行，完美适配原生镜像
元数据读写 Jaudiotagger ≥2.2.7 业界主流Java音频元数据处理库，支持全格式音频标签读写，API简单易用
编码检测 juniversalchardet ≥2.4.0 Mozilla开源编码检测库，自动识别元数据原始编码，适配中文/日文等多语言
音频指纹提取 AcoustID4J + FFmpeg 最新稳定版 AcoustID4J对接指纹识别API，FFmpeg提取音频特征，适配全格式音频
图片处理 Thumbnailator ≥0.4.20 轻量级图片处理库，支持封面缩放、裁剪、格式转换，API简洁，适配原生编译
HTTP客户端 Spring Cloud OpenFeign 最新稳定版 声明式HTTP客户端，对接第三方API，适配GraalVM原生编译
文件上传 Spring Boot Standard Servlet 原生支持 支持大文件分片上传、断点续传，适配大音频文件处理
日志框架 Logback 与Spring Boot版本一致 适配原生编译，高性能日志框架，支持日志分级、滚动输出

7.1.1 GraalVM原生编译核心实现方案

  1. 环境要求：GraalVM JDK 21+，安装Native Image组件
  2. 原生镜像适配
    • 对反射类、动态代理类、资源文件提前注册到reflect-config.json、proxy-config.json、resource-config.json配置文件中
    • 使用Spring Boot 3.x原生AOT提前处理，在编译期生成代理类、解析注解，避免运行期反射导致的原生镜像兼容问题
    • 对第三方库（Jaudiotagger、juniversalchardet等）进行原生镜像适配，解决第三方库的反射、资源加载问题
  3. 构建命令：通过Spring Boot Maven插件一键构建原生镜像，命令如下： 
    mvn clean native:compile -Pnative
  4. 产物输出：构建完成后生成平台相关的可执行文件，无需JDK环境，直接双击即可运行

7.2 前端技术栈（Vue）

技术组件 选型 版本要求 选型说明
核心框架 Vue 3 ≥3.4.0 组合式API，性能优异，生态完善，符合用户技术栈要求
构建工具 Vite ≥5.0.0 极速冷启动、热更新，开发体验优异，打包体积小
UI组件库 Element Plus ≥2.6.0 适配Vue 3，组件丰富，界面美观，支持暗黑模式，适配桌面端管理系统
状态管理 Pinia ≥2.1.0 Vue 3官方推荐状态管理库，轻量简洁，支持TypeScript
路由管理 Vue Router ≥4.2.0 Vue官方路由库，适配Vue 3，支持嵌套路由、路由守卫
HTTP请求 Axios ≥1.6.0 业界主流HTTP客户端，支持请求拦截、响应拦截、超时重试
文件上传 vue-simple-uploader ≥1.0.0 支持大文件分片上传、断点续传、拖拽上传，适配大音频文件
音频播放 vue3-audio 最新稳定版 适配Vue 3的音频播放器组件，支持文件预览试听
图表可视化 ECharts ≥5.4.0 百度开源图表库，性能优异，支持处理报告数据可视化展示
代码规范 TypeScript + ESLint 最新稳定版 类型安全，代码规范统一，提升可维护性

7.2.1 前端核心页面设计

  1. 仪表盘首页：展示音乐库统计数据、近期任务处理情况、失败文件数量、磁盘占用情况，核心功能快捷入口
  2. 任务管理页面：处理任务的创建、暂停、继续、终止，任务进度实时展示，历史任务查询，处理报告查看与导出
  3. 文件上传页面：支持单个/多个文件拖拽上传，上传进度展示，上传完成后自动触发处理流程
  4. 失败文件管理页面：失败文件列表筛选、搜索，批量操作，人工编辑入口，处理状态跟踪
  5. 元数据编辑页面：音频预览播放器，元数据表单编辑，封面上传/搜索，歌词上传/搜索，校验与提交功能
  6. 系统配置页面：全局配置可视化编辑，包括目标音乐库目录、归档模式、封面规格、API密钥配置等
  7. 日志管理页面：系统日志查询、筛选、导出，日志级别配置

八、核心API接口设计

采用RESTful风格设计，统一返回格式，适配前后端分离架构，核心接口如下：

8.1 统一返回格式

{
  "code": 200,
  "message": "操作成功",
  "data": {},
  "timestamp": 1710000000000
}
  • 成功状态码：200
  • 业务异常状态码：400-499
  • 系统异常状态码：500

8.2 核心接口清单

接口分类 请求方式 接口路径 接口说明
任务管理 POST /api/v1/task/create-dir-task 创建目录扫描处理任务
任务管理 GET /api/v1/task/list 分页查询任务列表
任务管理 GET /api/v1/task/{id}/detail 查询任务详情与进度
任务管理 PUT /api/v1/task/{id}/pause 暂停任务
任务管理 PUT /api/v1/task/{id}/resume 继续任务
任务管理 PUT /api/v1/task/{id}/terminate 终止任务
任务管理 GET /api/v1/task/{id}/report 获取任务处理报告
文件上传 POST /api/v1/file/upload 音频文件分片上传
文件上传 POST /api/v1/file/upload/merge 分片上传完成后合并文件
元数据处理 POST /api/v1/metadata/validate 手动校验文件元数据合规性
元数据处理 POST /api/v1/metadata/reprocess/{id} 重新处理指定失败文件
失败文件管理 GET /api/v1/fail-file/list 分页查询失败文件列表
失败文件管理 GET /api/v1/fail-file/{id}/detail 查询失败文件详情与原始元数据
失败文件管理 PUT /api/v1/fail-file/{id}/edit 保存人工编辑的元数据草稿
失败文件管理 POST /api/v1/fail-file/{id}/submit 提交编辑后的元数据，重新触发处理流程
失败文件管理 POST /api/v1/fail-file/batch-reprocess 批量重新处理失败文件
系统配置 GET /api/v1/config/list 查询系统配置列表
系统配置 PUT /api/v1/config/update 更新系统配置
系统配置 POST /api/v1/config/backup 手动备份系统配置与数据库

九、部署与运维方案

9.1 环境要求

9.1.1 开发环境

组件 版本要求
JDK GraalVM JDK 21+
Maven ≥3.9.0
Node.js ≥18.0.0
FFmpeg 最新稳定版
操作系统 Windows 10+/macOS 12+/Linux 内核4.15+

9.1.2 生产环境（原生镜像运行）

组件 最低要求 推荐配置
CPU 2核4线程 4核8线程
内存 512MB 2GB
磁盘 剩余空间≥1GB 剩余空间≥10GB（与音乐库大小匹配）
操作系统 Windows 10+/macOS 12+/Linux 内核4.15+ Linux 64位（NAS/家庭服务器）
依赖 FFmpeg（音频指纹提取） FFmpeg最新稳定版

9.2 部署步骤

9.2.1 原生镜像单机部署（Windows/Linux/macOS）

  1. 构建原生镜像：通过Maven命令构建对应平台的原生可执行文件
  2. 环境准备：目标机器安装FFmpeg，配置环境变量
  3. 文件部署：将可执行文件、配置文件、数据库目录复制到目标机器
  4. 配置修改：修改application.yml配置文件，设置目标音乐库目录、API密钥等配置
  5. 服务启动：
    • Windows：双击可执行文件即可启动
    • Linux/macOS：赋予执行权限后，./music-metadata-tool启动
  6. 访问验证：浏览器访问http://localhost:8080，进入前端管理界面

9.2.2 Docker容器化部署

  1. 构建Docker镜像：基于GraalVM原生镜像构建Docker镜像，Dockerfile示例如下： 
    # 构建阶段
FROM ghcr.io/graalvm/graalvm-community:21 AS builder
WORKDIR /app
COPY . .
RUN gu install native-image
RUN mvn clean native:compile -Pnative -DskipTests

# 运行阶段
FROM alpine:3.19
WORKDIR /app
# 安装依赖
RUN apk add --no-cache ffmpeg libc6-compat
# 复制原生可执行文件
COPY --from=builder /app/target/music-metadata-tool /app/music-metadata-tool
# 复制配置文件
COPY src/main/resources/application.yml /app/config/application.yml
# 暴露端口
EXPOSE 8080
# 挂载目录
VOLUME ["/app/config", "/app/data", "/music/source", "/music/library"]
# 启动命令
ENTRYPOINT ["/app/music-metadata-tool", "--spring.config.location=/app/config/application.yml"]
  2. Docker Compose部署：编写docker-compose.yml文件，一键启动服务
  3. 目录挂载：将源音乐目录、目标音乐库目录、配置目录、数据目录挂载到宿主机
  4. 启动服务：docker-compose up -d启动容器，浏览器访问对应端口即可使用

9.3 运维方案

  1. 日志管理：系统日志按天滚动输出，保留30天日志，支持日志级别动态调整，异常日志自动标记告警
  2. 数据备份：支持手动/自动备份数据库与配置文件，默认每天凌晨自动备份，保留最近7个备份文件
  3. 监控告警：内置服务健康检查接口，支持Prometheus监控指标采集，磁盘空间不足、任务异常失败时自动告警
  4. 版本升级：原生镜像版本升级只需替换可执行文件，重启服务即可完成，兼容历史数据；Docker版本升级只需替换镜像版本
  5. 故障恢复：提供数据库恢复、配置回滚功能，任务异常中断后可自动恢复，无需重新全量处理

十、测试方案

10.1 单元测试

  • 测试范围：核心领域层逻辑，包括元数据校验规则、去重算法、归档规则、编码转换等核心方法
  • 测试框架：JUnit 5 + Mockito
  • 覆盖率要求：核心业务逻辑代码覆盖率≥90%
  • 重点测试场景：必填字段校验、边界值测试、异常场景测试、编码转换测试

10.2 集成测试

  • 测试范围：第三方API对接、元数据读写、数据库操作、文件操作等组件集成能力
  • 重点测试场景：AcoustID/MusicBrainz API对接、音频文件元数据写入与读取、数据库CRUD操作、大文件上传与处理

10.3 功能测试

测试模块 核心测试点
音乐源接入 多级目录递归扫描、断点续传、大文件分片上传、格式过滤、异常文件拒绝
元数据校验 必填字段一票否决、编码乱码识别、格式规范校验、合规文件正常通过
元数据补全 API正常补全、补全数据二次校验、API异常容错、无猜测式补全
去重与增量入库 哈希去重、特征去重、增量文件识别、重复文件跳过、异常去重处理
自动归档 目录结构生成、文件名规范化、封面/歌词归档、Navidrome适配、冲突处理
失败文件管理 失败原因记录、列表筛选、人工编辑、重新提交流程、批量操作
系统管理 配置修改、任务管理、处理报告生成、日志查询、数据备份与恢复

10.4 兼容性测试

  1. 音频格式兼容：覆盖MP3、FLAC、M4A、OGG、WAV格式的元数据读写与处理测试
  2. 系统兼容：Windows、Linux、macOS三大操作系统的原生镜像部署与运行测试
  3. Navidrome兼容：处理后的音乐库导入Navidrome最新稳定版，验证扫描识别率、歌手/专辑/封面/歌词展示、曲目排序等核心场景
  4. 浏览器兼容：Chrome、Edge、Firefox主流浏览器的前端界面功能测试

10.5 性能测试

  • 批量处理性能：1000个音频文件批量处理，验证处理速度、内存占用、CPU使用率
  • 启动性能：原生镜像启动时间测试，验证是否≤500ms
  • 大文件处理：2GB单音频文件上传、处理、归档全流程测试
  • 并发性能：多个任务同时运行，验证系统稳定性与处理能力

十一、风险与应对措施

风险类型 风险描述 风险等级 应对措施
技术风险 GraalVM原生镜像第三方库兼容问题，部分库存在反射、动态代理导致的编译失败 中 1. 提前对第三方库进行原生镜像适配验证；2. 优先选择支持GraalVM原生镜像的库；3. 提前注册反射、代理配置，通过Spring AOT提前处理
业务风险 第三方API调用限流、故障，导致元数据补全失败 中 1. 内置API调用限流、超时重试机制；2. 提供API密钥配置，用户可使用自己的密钥；3. 异常时直接标记失败，不中断整体任务，后续支持手动重试
数据风险 元数据写入导致音频文件损坏、原始文件丢失 高 1. 默认采用复制模式，不修改原始源文件；2. 元数据写入前自动备份源文件；3. 写入后校验文件完整性，异常时自动回滚；4. 提供移动模式开关，用户手动确认后开启
性能风险 超大音乐库（10万+文件）全量扫描与处理性能瓶颈 中 1. 多线程并发处理，可配置线程数；2. 扫描与处理流程解耦，异步处理；3. 哈希比对优化，建立哈希索引，提升去重速度；4. 断点续传，支持分批次处理
兼容性风险 小众音频格式元数据读写异常 低 1. 优先适配主流音频格式，小众格式提前校验，不支持的格式直接标记失败；2. 完善异常捕获，单个文件处理失败不影响整体任务
安全风险 目录越权访问，误操作非授权目录文件 高 1. 目录白名单机制，仅对用户授权的目录进行读写；2. 严格校验文件路径，禁止路径穿越；3. 默认只读访问源目录，仅对目标目录有写入权限

十二、阶段文档索引与实施说明

为避免总方案文档随着阶段推进不断膨胀，P0、P1 及后续阶段的“开发落地说明、测试结果、验收证据、偏差说明”统一沉淀到项目仓库内的阶段文档中；本总文档仅保留全局设计、总体规则、阶段索引与里程碑说明。

12.1 文档组织规则

  • 总方案文档：保留项目背景、需求、总体架构、统一规则、阶段规划
  • 阶段落地文档：写入每个阶段的实现内容、关键文件、测试策略、验收结果、已知偏差
  • 阶段落地文档统一存放于：music-metadata-system/docs/

12.2 当前阶段文档索引

阶段 文档 说明
P0 music-metadata-system/docs/P0-基础架构-开发落地说明.md 记录基础架构、数据库底座、统一异常与响应规范的落地情况
P1 music-metadata-system/docs/P1-元数据解析与校验-开发落地说明.md 记录元数据读取、快照存储、一票否决校验、真实文件测试与覆盖率结果

12.3 当前状态摘要

  • P0 已完成基础工程、数据库底座、基础持久化层和统一异常处理能力建设
  • P1 已完成元数据读取、编码检测与修复尝试、快照持久化、一票否决校验、目录扫描与去重相关验收能力
  • 详细实现、测试与验收结果请以对应阶段文档为准

十三、项目里程碑规划

阶段 周期 核心交付物 完成标准
第一阶段：需求确认与架构设计 1周 需求规格说明书、架构设计文档、数据库设计文档、API接口文档 需求与架构方案确认完成，核心规则与技术选型敲定
第二阶段：核心后端模块开发 3周 元数据解析与校验模块、文件去重模块、自动归档模块、API对接模块、数据库访问层 核心业务流程可跑通，音频文件可完成标准化校验与归档，适配Navidrome规范
第三阶段：前端界面开发 2周 Vue前端工程、所有核心页面、前后端接口联调 前端界面可正常访问，所有功能可通过界面操作完成
第四阶段：GraalVM原生编译适配 1周 原生镜像适配配置、可执行文件构建脚本、Docker镜像构建文件 可正常构建对应平台的原生镜像，镜像可正常启动与运行，无兼容问题
第五阶段：测试与Bug修复 2周 测试用例、测试报告、Bug修复记录 完成所有测试场景，核心功能无Bug，系统稳定运行，性能达标
第六阶段：部署与上线 1周 部署文档、用户操作手册、正式版安装包、Docker镜像 系统可正常部署运行，用户可通过手册完成操作，正式版交付
合计 10周 完整系统、全量文档、交付物 系统所有功能实现，满足所有需求与约束条件，可正式投入使用
Reference in New Issue View Git Blame Copy Permalink