124 lines
4.2 KiB
Markdown
124 lines
4.2 KiB
Markdown
# AM Downloader
|
||
|
||
独立的音乐搜索与下载 Web 服务，使用 AM 音乐 API 解析资源，并可选同步到 WebDAV/NAS。
|
||
|
||
## 特性
|
||
|
||
- 多用户登录、角色与权限隔离（admin / privileged / user）
|
||
- 积分账户、预扣、成功扣除、失败退款
|
||
- 兑换码批次生成、使用、撤销与审计
|
||
- 音乐搜索与分页
|
||
- 下载队列、用户任务去重、跨用户媒体资源去重、失败重试
|
||
- 自动识别实际音频格式，避免错误扩展名
|
||
- 标记解析后的音质与实际音质
|
||
- WebDAV/NAS 同步
|
||
- 可配置同曲低音质版本清理策略
|
||
- 可配置上传成功后的本地文件清理策略
|
||
- Docker Compose 部署
|
||
|
||
## 架构
|
||
|
||
`9540` 提供 Downloader Web/API；音乐解析服务通过配置的 `AM_API_URL` 访问，默认指向本机 `9530`。
|
||
|
||
运行时数据库和下载文件不会进入 Git 仓库。
|
||
|
||
## 快速部署
|
||
|
||
```bash
|
||
git clone <your-gitea-repository>
|
||
cd am-downloader
|
||
docker compose up -d --build
|
||
```
|
||
|
||
默认访问：`http://127.0.0.1:9540`
|
||
|
||
## 配置
|
||
|
||
Docker Compose 中只保存非敏感的运行参数。WebDAV 凭据通过 Web UI 的设置页面写入运行时数据库，**不要将数据库提交到 Git**。
|
||
|
||
可配置：
|
||
|
||
- `PORT`：Web 服务端口，默认 `9540`
|
||
- `DB_PATH`：SQLite 数据库路径
|
||
- `DOWNLOAD_DIR`：下载目录
|
||
- `AM_API_URL`：AM 音乐 API 地址
|
||
- `WORKERS`：下载 worker 数量
|
||
|
||
首次部署后进入设置页面填写 WebDAV 地址、用户名、密码和远程目录。
|
||
|
||
## 数据与安全
|
||
|
||
以下内容属于运行时数据，默认被 `.gitignore` 排除：
|
||
|
||
- `data/`
|
||
- `downloads/`
|
||
- `*.db`
|
||
- 日志、临时文件和本地环境文件
|
||
|
||
提交前应检查 Git diff，确认没有密码、Token、Cookie、私有密钥或个人环境配置。
|
||
|
||
## 开发
|
||
|
||
```bash
|
||
go test ./...
|
||
go build -o am-downloader .
|
||
```
|
||
|
||
前端为单页静态界面，由 Go 服务直接提供。
|
||
|
||
## API
|
||
|
||
认证：
|
||
|
||
- `POST /api/auth/login`
|
||
- `POST /api/auth/logout`
|
||
- `POST /api/auth/password`
|
||
- `GET /api/auth/me`
|
||
|
||
用户功能：
|
||
|
||
- `GET /api/search`
|
||
- `GET /api/tasks`
|
||
- `POST /api/tasks`
|
||
- `POST /api/tasks/:id/retry`
|
||
- `DELETE /api/tasks/:id`
|
||
- `GET /api/credits`
|
||
- `POST /api/redeem`
|
||
- `GET/PUT /api/webdav/config`
|
||
- `POST /api/webdav/test`
|
||
|
||
管理员功能：
|
||
|
||
- `GET/POST /api/admin/users`
|
||
- `PUT /api/admin/users/:id`
|
||
- `GET /api/admin/redeem`
|
||
- `POST /api/admin/redeem`
|
||
- `POST /api/admin/redeem/:id/revoke`
|
||
- `GET /api/admin/audit`
|
||
- `GET/PUT /api/admin/settings`
|
||
- `POST /api/admin/webdav/test`
|
||
|
||
## 数据库迁移注意事项
|
||
|
||
首次从旧版本升级时，启动过程会自动执行 GORM schema migration，并将旧任务归属到首次创建的管理员账号；同时把旧的全局任务唯一索引改为按用户隔离的唯一索引，并创建共享媒体资源表。
|
||
|
||
升级前仍建议先备份 `data/downloader.db`。Docker 部署时不要把 `data/` 或 `downloads/` 加入 Git。
|
||
|
||
当前版本不会主动删除旧媒体文件；媒体资源记录缺失本地文件时会在下一次请求中重新取得资源。
|
||
|
||
## 多用户并发与恢复
|
||
|
||
下载任务和共享媒体资源分离：
|
||
|
||
- 同一 source + rid + quality 只允许一个 Asset 物理下载，多个用户 Task 可以共享。
|
||
- 每个用户 Task 保留独立 WebDAV 目标路径、状态和额度预留。
|
||
- Task 使用数据库条件更新抢占状态，重复点击不会启动多个 worker。
|
||
- Asset 使用数据库租约（heartbeat/lease）防止 worker 崩溃后永久占锁；过期租约会自动恢复旧任务。
|
||
- 下载文件使用按 Asset/generation 隔离的缓存目录和 task-specific .part 临时文件，避免并发用户覆盖同一个本地文件。
|
||
- WebDAV 上传采用独立的 upload_pending -> uploading -> done 状态机；上传失败只重试上传，不重新扣积分。
|
||
- 已提交额度的历史失败任务会自动恢复；已退款任务不会因为后台 resync 被无条件重新扣费。
|
||
- SQLite 使用 WAL + busy timeout，并对关键事务做锁冲突重试；高并发写入仍由 SQLite 单写者模型串行化。
|
||
- 本地共享文件只有在没有其他活动 Task 需要时才允许清理。
|
||
|
||
并发回归测试覆盖：Task 抢占、共享 Asset 租约恢复、已提交额度重试、已退款额度重试、并发积分预留以及 Asset generation 隔离。
|