Template
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. 一键导入
- 在 配置 页面设置工作根目录（与挂载路径一致，如
/home/mangtool/MusicWork）。 - 将待处理的音频文件放入
Input/目录。 - 切换到 一键导入 页面，点击「开始一键导入」。
- 系统自动完成：扫描 → 校验元数据 → 繁简转换 → 转码为 FLAC → 去重 → 整理入库。
- 成功文件进入
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
容器内置 FFmpeg，一键导入过程中的格式转换（WAV/APE/AIFF/WV/TTA → FLAC）自动使用容器的 FFmpeg。
常见问题
构建失败
如果构建时遇到 Maven 依赖下载失败（如 handshake_failure 或网络超时）：
- 检查网络连接：确保 Docker 容器可以访问外网
- 使用国内镜像：已默认配置阿里云镜像，如仍有问题可修改
docker/maven-settings.xml - 清理缓存重建：
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