Template
192 lines
6.4 KiB
Markdown
192 lines
6.4 KiB
Markdown
# MangTool Docker 部署
|
||
|
||
前后端单容器部署：拉代码后进入 `docker` 目录，执行启动脚本即可。
|
||
|
||
## 环境要求
|
||
|
||
- Docker
|
||
- Docker Compose（v2 推荐：`docker compose`）
|
||
|
||
## 部署步骤
|
||
|
||
### 1. 拉取代码
|
||
|
||
```bash
|
||
git clone <仓库地址>
|
||
cd MyTool
|
||
```
|
||
|
||
### 2. 配置工作目录
|
||
|
||
工作目录默认为 `docker/data/`（相对于 docker-compose.yml），可通过环境变量 `MANGTOOL_DATA_DIR` 覆盖：
|
||
|
||
```bash
|
||
# 使用默认目录（docker/data/）
|
||
cd docker
|
||
docker compose up -d --build
|
||
|
||
# 指定自定义目录
|
||
MANGTOOL_DATA_DIR=/your/actual/path/MusicWork docker compose up -d --build
|
||
```
|
||
|
||
或在 `.env` 文件中设置：
|
||
|
||
```bash
|
||
# 在 docker/ 目录下创建 .env 文件
|
||
echo 'MANGTOOL_DATA_DIR=/your/actual/path/MusicWork' > .env
|
||
docker compose up -d --build
|
||
```
|
||
|
||
工作目录下应包含 `Input/`（放入待处理的音频文件）、`Library/`（整理后的曲库）和 `Rejected/`（被拒绝的文件）三个子目录，首次启动时系统会自动创建。
|
||
|
||
### 3. 启动服务
|
||
|
||
**Linux / macOS：**
|
||
|
||
```bash
|
||
cd docker
|
||
chmod +x start.sh
|
||
./start.sh
|
||
```
|
||
|
||
**Windows：**
|
||
|
||
在资源管理器中进入 `docker` 目录，双击运行 `start.bat`；或在终端执行：
|
||
|
||
```cmd
|
||
cd docker
|
||
start.bat
|
||
```
|
||
|
||
或直接使用 docker compose：
|
||
|
||
```bash
|
||
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）和音频完整性验证自动使用容器内的工具。
|
||
|
||
## 运维与可观测性
|
||
|
||
### 依赖自检
|
||
|
||
部署后可用依赖自检确认外部工具就绪：
|
||
|
||
```bash
|
||
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 健康检查（只读，修复需确认）
|
||
|
||
```bash
|
||
# 只读扫描（不修改任何文件）
|
||
docker compose exec mangtool wget -q -O- --post-data='' http://localhost:8080/api/library/health/scan
|
||
```
|
||
|
||
修复动作（歌词回填、封面回填、删除孤立侧车等）必须在请求体显式 `confirm=true` 才会执行，否则仅演练。
|
||
|
||
**修复示例（含封面回填）**：
|
||
```bash
|
||
# 默认配置下不修改磁盘。加上 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
|
||
```
|
||
|
||
### 备份与恢复
|
||
|
||
导入为「移动」语义，批量导入前建议对宿主机工作目录做快照：
|
||
|
||
```bash
|
||
# 在挂载的宿主机数据目录（默认 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. **清理缓存重建**：
|
||
```bash
|
||
docker compose down
|
||
docker compose build --no-cache
|
||
docker compose up -d
|
||
```
|
||
|
||
### 端口被占用
|
||
|
||
如果 8080 端口已被占用，修改 `docker-compose.yml` 中的端口映射：
|
||
|
||
```yaml
|
||
ports:
|
||
- "8888:8080" # 改为其他端口
|
||
```
|
||
|
||
### 查看详细日志
|
||
|
||
```bash
|
||
# 查看构建日志
|
||
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`。 |