MyTool/docker/README.md

MangTool Docker 部署

前后端单容器部署：拉代码后进入 docker 目录，执行启动脚本即可。

环境要求

• Docker
• Docker Compose（v2 推荐：docker compose）

部署步骤

1. 拉取代码

git clone <仓库地址>
cd MyTool

2. 配置工作目录

工作目录默认为 docker/data/（相对于 docker-compose.yml），可通过环境变量 MANGTOOL_DATA_DIR 覆盖：

# 使用默认目录（docker/data/）
cd docker
docker compose up -d --build

# 指定自定义目录
MANGTOOL_DATA_DIR=/your/actual/path/MusicWork docker compose up -d --build

或在 .env 文件中设置：

# 在 docker/ 目录下创建 .env 文件
echo 'MANGTOOL_DATA_DIR=/your/actual/path/MusicWork' > .env
docker compose up -d --build

工作目录下应包含 Input/（放入待处理的音频文件）、Library/（整理后的曲库）和 Rejected/（被拒绝的文件）三个子目录，首次启动时系统会自动创建。

3. 启动服务

Linux / macOS：

cd docker
chmod +x start.sh
./start.sh

Windows：

在资源管理器中进入 docker 目录，双击运行 start.bat；或在终端执行：

cd docker
start.bat

或直接使用 docker compose：

cd docker
docker compose up -d --build

4. 访问应用

浏览器打开：http://localhost:8080

前端与后端由同一服务提供，无需单独配置 API 地址。

5. 一键导入

1. 在 配置 页面设置工作根目录（与挂载路径一致，如 /home/mangtool/MusicWork）。
2. 将待处理的音频文件放入 Input/ 目录。
3. 切换到 一键导入 页面，点击「开始一键导入」。
4. 系统自动完成：扫描 → 校验元数据 → 繁简转换 → 转码为 FLAC → 去重 → 整理入库。
5. 成功文件进入 Library/ 目录，被拒绝的文件进入 Rejected/ 下的对应子目录。

常用命令

操作	命令
后台启动	docker compose up -d --build
查看日志	docker compose logs -f
停止并删除	docker compose down
仅重新构建	docker compose build --no-cache
查看状态	docker compose ps
健康检查	docker compose exec mangtool wget -q -O- http://localhost:8080/api/health

端口与数据

• 端口：宿主机 8080 映射容器 8080，可在 docker-compose.yml 中修改左侧端口，例如 "8888:8080"。
• 数据：工具读写路径在容器内通过 volume 挂载；请确保宿主机目录存在且容器内用户有读写权限。首次启动后系统会在工作根目录下自动创建 Input/、Library/、Rejected/ 子目录。

FFmpeg / FFprobe

容器内置 FFmpeg 和 FFprobe（FFmpeg 套件自带），一键导入过程中的格式转换（WAV/APE/AIFF/WV/TTA → FLAC）和音频完整性验证自动使用容器内的工具。

运维与可观测性

依赖自检

部署后可用依赖自检确认外部工具就绪：

docker compose exec mangtool wget -q -O- http://localhost:8080/api/health/dependencies

返回 ffmpegAvailable/ffprobeAvailable 及版本行；任一为 false 时导入会在预检阶段直接报错。

导入报告与歌词统计

每次导入在工作根目录 Rejected/Reports/ 下写入结构化 JSON 报告（逐文件结果 + 歌词 有/无/失败 统计）。前端「一键导入」页可实时查看歌词统计并「下载导入报告」。歌词的有无与失败绝不影响音频入库。

任务取消与重启恢复

• 取消：POST /api/ingest/cancel，只停止后续文件处理，已入库文件保留，未处理文件留在 Input/。
• 重启恢复：任务状态持久化于 工作根目录/.mangtool/ingest-tasks.json；容器重启后仍在运行的任务标记为 interrupted，重新导入只处理未完成文件（已完成文件已移出 Input/，不会重复搬运）。

Library 健康检查（只读，修复需确认）

# 只读扫描（不修改任何文件）
docker compose exec mangtool wget -q -O- --post-data='' http://localhost:8080/api/library/health/scan

修复动作（歌词回填、封面回填、删除孤立侧车等）必须在请求体显式 confirm=true 才会执行，否则仅演练。

修复示例（含封面回填）：

# 默认配置下不修改磁盘。加上 confirm=true 与 backfillCovers=true 即可安全回填封面与修复曲库
docker compose exec mangtool wget -q -O- --header="Content-Type: application/json" --post-data='{"confirm":true,"backfillCovers":true}' http://localhost:8080/api/library/health/repair

备份与恢复

导入为「移动」语义，批量导入前建议对宿主机工作目录做快照：

# 在挂载的宿主机数据目录（默认 docker/data）执行
tar czf mangtool-backup-$(date +%Y%m%d).tgz -C /path/to/MusicWork Library Rejected .mangtool

Library/ 为必备成品数据；Rejected/Reports/ 便于追溯；.mangtool/ 为任务状态。恢复时解压回原数据目录即可，Navidrome 直接扫描 Library/，无需外部数据库。

常见问题

构建失败

如果构建时遇到 Maven 依赖下载失败（如 handshake_failure 或网络超时）：

1. 检查网络连接：确保 Docker 容器可以访问外网
2. 使用国内镜像：已默认配置阿里云镜像，如仍有问题可修改 docker/maven-settings.xml
3. 清理缓存重建：

   docker compose down
   docker compose build --no-cache
   docker compose up -d
   

端口被占用

如果 8080 端口已被占用，修改 docker-compose.yml 中的端口映射：

ports:
  - "8888:8080"  # 改为其他端口

查看详细日志

# 查看构建日志
docker compose build --progress=plain

# 查看运行日志
docker compose logs -f mangtool

Cover Art Settings

• MANGTOOL_COVER_ENABLED (default: false) - Enable Cover Art Fetch
• MANGTOOL_MB_BASE_URL (default: https://musicbrainz.org/ws/2)
• MANGTOOL_CAA_BASE_URL (default: https://coverartarchive.org)
• MANGTOOL_MB_USER_AGENT (default: MangTool/1.0 (https://gitea.mangmang.fun/LiuMangMang/MyTool)) - User-Agent for MusicBrainz API requests

环境变量说明

• MANGTOOL_UPLOAD_TEMP: 前端文件上传的临时存放目录，默认值为 /home/mangtool/MusicWork/.upload-tmp。