摘要

WebTras 为面向个人用户的轻量化 Web 端音乐资产管理系统，采用前后端分离架构，依托 Vue 3 前端框架、Django 3.2 后端框架、SQLite 嵌入式数据库构建，原生集成 WebDAV 协议服务与客户端能力，实现本地音频文件上传、元数据解析、在线流式播放、歌单管理、远端 WebDAV 存储批量导入等完整业务能力。本文基于项目规划文档与运维文档，系统阐述项目核心特性、架构设计、部署方案、开发规范与迭代路线。

项目地址:WebTras

一、项目特性

1.1 基础音频管理能力

1.2 WebDAV 双向协议支持（核心差异化能力）

1.3 部署轻量化优势

1. 存储层采用 SQLite 嵌入式数据库，无需独立数据库服务，无额外部署依赖；

2. 开发环境双服务分离（Vite 前端 + Django 后端），生产环境支持 Docker 容器一键部署；

3. 前后端完全解耦，开发阶段通过 Vite 代理解决跨域，生产环境可静态资源一体化托管。

1.4 兼容音频格式清单

原生支持：MP3、WAV、FLAC、AAC、OGG、M4A； 不支持：ALAC、APE、DSD 等浏览器原生不兼容格式，可通过文件下载功能本地解码。

二、架构设计

2.1 技术栈分层选型表

2.2 项目目录分层结构

WebTras/                          # 项目根目录
├── manage.py                     # Django程序入口
├── requirements.txt              # Python后端依赖清单
├── WebTras/                      # Django全局配置模块
│   ├── settings.py               # 全局配置、媒体路径、跨域、应用注册
│   ├── urls.py                   # 全局路由分发
├── music/                        # 核心业务应用（音频/歌单/歌手模型与API）
├── webdav_app/                   # WebDAV服务端路由与视图模块
├── media/music/                  # 音频文件持久化存储目录（运行自动生成）
├── frontend/                     # Vue3前端独立工程
│   ├── vite.config.js            # 开发代理、端口固定配置
│   └── src/                      # 页面、组件、API请求封装
└── db.sqlite3                    # SQLite数据库文件

2.3 数据库模型关系设计

系统采用主模型 + 中间关联表实现实体关系解耦，核心实体：Artist（歌手）、Song（歌曲）、Playlist（歌单）、PlaylistEntry（歌单关联中间表）。

1. 一对多关系：单个Artist关联多条Song；

2. 多对多关系：Song与Playlist通过PlaylistEntry中间表关联，支持自定义歌曲排序、添加时间记录；

3. 核心字段约束：音频文件路径采用相对路径存储，时长以浮点秒数记录，文件大小单位为字节。

2.4 API 路由规范

1. 业务 REST 接口统一前缀：/api/；

2. WebDAV 服务端挂载端点：/webdav/；

3. WebDAV 远端导入客户端接口：/api/webdav/；

核心业务 API 清单

三、部署方案

3.1 环境前置依赖要求

3.2 本地开发环境部署（Windows/macOS/Linux 通用）

3.2.1 后端启动流程

# 1. 创建并激活虚拟环境
python -m venv venv
# Windows PowerShell
.\venv\Scripts\Activate.ps1
# macOS/Linux
source venv/bin/activate

# 2. 安装后端依赖
pip install -r requirements.txt

# 3. 数据库初始化迁移
python manage.py makemigrations
python manage.py migrate

# 4. 可选：创建后台管理员账号
python manage.py createsuperuser

# 5. 启动Django开发服务
python manage.py runserver 8000

3.2.2 前端启动流程

cd frontend
npm install
npm run dev

3.2.3 开发环境访问地址

3.3 Docker 容器化生产部署（NAS / 服务器推荐）

# 1. 构建并后台启动容器
docker compose up -d --build

# 2. 查看容器运行状态
docker compose ps

# 3. 查看后端运行日志
docker compose logs -f backend

# 4. 创建后台管理员账号
docker compose exec backend python manage.py createsuperuser

# 5. 项目版本更新流程
git pull
docker compose down
docker compose build --no-cache
docker compose up -d

容器默认对外暴露 8080 端口，访问地址：http://NAS_IP:8080。

持久化数据目录映射

3.4 WebDAV 客户端接入配置规范

远端 WebDAV 导入接口标准请求体：

{
  "url": "https://dav.example.com/remote.php/dav/files/user/Music",
  "username": "user",
  "password": "pass",
  "paths": [
    "Albums/xxx.mp3"
  ],
  "verify_ssl": false
}

• verify_ssl=false适用于内网 NAS 自签名证书场景，关闭 SSL 校验；

• Windows 本地挂载 WebDAV 服务端地址格式：\\localhost@8000\webdav\。

四、开发规范

4.1 开发阶段划分与优先级

4.2 核心模块关键实现逻辑

4.2.1 音频文件上传流程

1. 前端通过multipart/form-data提交音频文件；

2. DRF 解析文件流，存入media/music持久化目录；

3. mutagen 读取音频标签，自动填充歌手、标题、专辑、时长字段；

4. 写入Song数据表，返回完整歌曲资源。

4.2.2 音频流式播放实现

1. 后端识别 HTTP Range 请求头，对音频文件分片读取；

2. 响应头配置Accept-Ranges: bytes、对应音频 MIME 类型；

3. 前端 \\ 标签直接绑定流式接口地址，支持拖拽进度、断点续播。

4.2.3 WebDAV 服务端集成逻辑

1. 全局路由/webdav/转发至 wsgidav WSGI 应用；

2. 文件存储根目录绑定项目media/music；

3. 对接 Django 用户认证体系，实现访问权限控制。

4.3 代码开发规范

五、迭代规划

5.1 短期迭代（Beta 1.x）

1. 新增歌手、专辑独立筛选页面；

2. 完善歌手详情页，展示对应专辑、全部曲目、歌手简介。

5.2 中长期迭代（Beta 3.x+）

六、常见问题

结语

WebTras 以轻量化、自主可控为核心设计目标，打通本地文件管理、Web 在线播放、NAS 远端存储批量迁移三类核心场景，前后端分离架构具备良好的可维护性与扩展能力。开发环境适配个人本地调试，Docker 方案适配 NAS、服务器长期稳定运行，可满足个人私有音乐库全生命周期管理需求。