# AudioGo

**Repository Path**: codekpy/audio-go

## Basic Information

- **Project Name**: AudioGo
- **Description**: 使用Go+vue开发的兼容subsonic协议的音乐管理网页
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-05-03
- **Last Updated**: 2026-05-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Audio-Go - Subsonic 增强协议音乐云服务

基于 Go (Gin) + Vue 3 (TypeScript) 构建的个人音乐云平台，兼容 Subsonic 协议 v1.16.1。

![首页预览](docs/home.png)

## 功能特性

- 兼容 **Subsonic v1.16.1** 协议（50+ 个 API 端点）
  - 艺术家/专辑/歌曲浏览与搜索
  - 音频流媒体播放（支持转码 mp3/opus）
  - 歌词获取、封面艺术显示
  - 播放列表管理（创建/更新/删除）
  - 收藏/评分/播放记录（scrobble）
  - 正在播放、随机歌曲
- 扩展写操作接口（分片上传、元数据编辑）
- 双模式认证（经典 Subsonic 认证 + Token 认证）
- 基于角色的访问控制（管理员/普通用户）
- 响应式前端界面（Element Plus UI）
- HTML5 音频播放器（支持进度拖拽）
- 分片上传组件（支持拖拽、进度显示）
- 媒体库自动扫描（基于 ffprobe 元数据读取）
- 支持音频格式：MP3, FLAC, AAC/M4A, WAV, OGG, Opus, APE, WMA, AIFF, DSF, DFF

## 技术栈

### 后端
| 技术 | 用途 |
|------|------|
| **Go 1.22+** | 开发语言 |
| **Gin** | Web 框架 |
| **GORM** | ORM（SQLite 驱动） |
| **SQLite** | 数据库 |
| **JWT (golang-jwt/v5)** | Token 认证 |
| **golang.org/x/time/rate** | 速率限制 |
| **ffprobe** | 媒体文件元数据读取 |
| **ffmpeg** | 实时音频转码 |
| **AES** | 密码加密传输 |

### 前端
| 技术 | 用途 |
|------|------|
| **Vue 3 (Composition API)** | 前端框架 |
| **TypeScript** | 开发语言 |
| **Pinia** | 状态管理 |
| **Vue Router 4** | 路由 |
| **Element Plus** | UI 组件库 |
| **Axios** | HTTP 客户端 |
| **Vite** | 构建工具 |

## 快速开始

### 前置条件

- Go 1.22+
- Node.js 18+
- npm 10+

### 启动后端

```bash
cd backend

# 安装依赖
go mod tidy

# 运行服务（默认端口 4533）
go run ./cmd/server
```

首次启动会自动：
1. 创建 SQLite 数据库 (`data/audio-go.db`)
2. 自动迁移数据库表
3. 创建默认管理员账号 (`admin` / `admin123`)
4. 扫描 `./music` 目录下的音频文件

### 启动前端

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务器（默认端口 3000）
npm run dev
```

前端开发服务器会自动代理 `/rest` 请求到后端 `http://localhost:4533`。

### 访问

1. 打开浏览器访问 `http://localhost:3000`
2. 使用默认管理员账号登录：`admin` / `admin123`
3. 开始浏览和管理您的音乐库

## 使用教程

### 初次使用

1. **启动服务**（参见快速开始）
2. 浏览器打开 `http://localhost:3000`（前端）或 `http://localhost:4533`（后端 API）
3. 使用默认管理员账号登录：`admin` / `admin123`
4. 将音频文件放入 `backend/music` 目录，重启服务或调用扫描接口即可自动识别

### 音乐浏览

| 页面 | 功能 |
|------|------|
| **艺术家** | 按艺术家浏览专辑，点击进入专辑查看歌曲列表 |
| **专辑** | 按专辑封面和标题浏览，支持多种排序（最新、最常播放、随机等） |
| **搜索** | 全局搜索艺术家、专辑和歌曲 |
| **我的收藏** | 查看收藏的歌曲、专辑和艺术家 |
| **播放列表** | 创建和管理播放列表 |

### 播放控制

- 点击歌曲行或封面图开始播放
- 底部播放栏支持：播放/暂停、上一首/下一首、进度拖拽、音量调节
- 支持音频格式转码播放（MP3/Opus）

### 编辑歌曲元数据

进入专辑详情页，点击歌曲右侧的编辑按钮，可修改：

| 字段 | 说明 |
|------|------|
| **标题** | 歌曲名称 |
| **艺术家** | 歌手/演奏者 |
| **专辑** | 所属专辑 |
| **流派** | 音乐风格分类 |
| **年份** | 发行年份 |
| **曲目号** | 专辑内曲目序号 |
| **歌词** | 同步/普通歌词 |
| **封面** | 上传封面图片（支持 JPG/PNG/WebP） |

编辑保存后会同时：
- 通过 `ffmpeg` 将元数据写入音频文件标签
- 将封面图片嵌入音频文件
- 更新数据库记录

> 修改元数据需要管理员权限。

### 封面上传

有两种方式为歌曲设置封面：

1. **在编辑对话框中上传** — 选择图片文件上传，自动保存到 `data/covers/` 目录
2. **将封面图片放入歌曲所在目录** — 命名为 `cover.jpg`、`folder.jpg`、`front.jpg` 或 `album.jpg`，重启扫描后自动识别

> 注意：手动上传的封面在重启扫描后不会丢失。

### 上传音乐文件

支持大文件分片上传：

1. 进入"上传"页面
2. 拖拽或选择音频文件
3. 系统自动分片上传，显示上传进度
4. 上传完成后自动合并文件到音乐目录
5. 可手动触发扫描将其加入曲库

### 第三方客户端连接

由于兼容 Subsonic 协议，可使用支持 Subsonic 的客户端连接：

| 客户端 | 平台 | 说明 |
|--------|------|------|
| **Symfonium** | Android | 功能丰富的音乐播放器 |
| **音流** | Android/iOS | 支持 Subsonic 协议的国内应用 |
| **DSub** | Android | 经典 Subsonic 客户端 |
| **Ultrasonic** | Android | 开源 Subsonic 客户端 |
| **Substreamer** | iOS | 流畅的 Subsonic 客户端 |
| **Navidrome** | - | 另一个 Subsonic 服务端，可与之互操作 |

连接参数：

```
服务器地址: http://<你的IP>:4533
用户名: admin（或你创建的用户名）
密码: admin123（或你设置的密码）
协议版本: v1.16.1
```

### 管理维护

**触发媒体库扫描**：
```bash
# 重新扫描音乐目录，更新元数据和封面
curl "http://localhost:4533/rest/startScan.view?v=1.16.1&c=app&f=json&u=admin&p=<密码哈希>"
```

**查看扫描状态**：
```bash
curl "http://localhost:4533/rest/getScanStatus.view?v=1.16.1&c=app&f=json&u=admin&p=<密码哈希>"
```

> 密码哈希 = `SHA256("subsonic" + 明文密码)` 转为十六进制小写字符串。
> 例如：`admin123` → `SHA256("subsonicadmin123")` → `22858bab5c6a89f7839822e3733103dae2008dfcd2c1e8353528a8bf1af49e06`

## 配置说明

### 后端配置 (`backend/config/config.yaml`)

```yaml
server:
  port: 4533
  rate_limit: 10
  rate_burst: 20

database:
  path: data/audio-go.db

music:
  music_dir: ./music
  scan_interval: 3600s

auth:
  jwt_secret: "your-jwt-secret"
```

可通过环境变量覆盖配置：
- `AUDIO_GO_PORT` - 服务端口
- `AUDIO_GO_DB_PATH` - 数据库路径
- `AUDIO_GO_MUSIC_DIR` - 音乐目录
- `AUDIO_GO_JWT_SECRET` - JWT 密钥
- `AUDIO_GO_LOG_LEVEL` - 日志级别

## API 接口

项目完整实现了 **Subsonic v1.16.1** 协议，所有端点均支持 XML 和 JSON 两种响应格式。

> 请求示例：`/rest/search3.view?u=admin&t=<token>&s=<salt>&v=1.16.1&c=AppName&f=json&query=keyword`

### 公开接口（无需认证）

| 接口 | 说明 |
|------|------|
| `/rest/ping.view` | 健康检查 |
| `/rest/getLicense.view` | 获取许可信息 |
| `/rest/getMusicFolders.view` | 获取音乐文件夹 |
| `/rest/getToken.view` | 获取认证 Token（自定义扩展） |
| `/rest/getJwtToken.view` | 获取 JWT Token（自定义扩展） |
| `/rest/getArtists.view` | 获取艺术家列表 |
| `/rest/getArtist.view` | 获取艺术家详情（含专辑列表） |
| `/rest/getAlbum.view` | 获取专辑详情（含歌曲列表） |
| `/rest/getAlbumList.view` | 专辑列表（按类型筛选） |
| `/rest/getAlbumList2.view` | 专辑列表 v2（按类型筛选） |
| `/rest/getSong.view` | 获取歌曲信息 |
| `/rest/getSongsByGenre.view` | 按流派获取歌曲 |
| `/rest/getCoverArt.view` | 获取封面图片 |
| `/rest/getLyrics.view` | 获取歌词 |
| `/rest/getGenres.view` | 获取流派列表 |
| `/rest/getArtistInfo.view` | 获取艺术家信息 |
| `/rest/getArtistInfo2.view` | 获取艺术家信息 v2 |
| `/rest/getAlbumInfo.view` | 获取专辑信息 |
| `/rest/getAlbumInfo2.view` | 获取专辑信息 v2 |
| `/rest/search3.view` | 搜索（query 为空时返回全部） |

### 需认证接口

| 接口 | 说明 |
|------|------|
| `/rest/stream.view` | 音频流媒体播放（支持转码 mp3/opus，支持断点续传） |
| `/rest/download.view` | 下载文件 |
| `/rest/getRandomSongs.view` | 获取随机歌曲 |
| `/rest/scrobble.view` | 记录播放历史 |
| `/rest/nowPlaying.view` | 获取正在播放列表 |
| `/rest/star.view` | 收藏 |
| `/rest/unstar.view` | 取消收藏 |
| `/rest/getStarred.view` | 获取已收藏内容 |
| `/rest/getStarred2.view` | 获取已收藏内容 v2 |
| `/rest/setRating.view` | 设置评分 |
| `/rest/getPlaylists.view` | 获取播放列表 |
| `/rest/getPlaylist.view` | 获取播放列表详情 |
| `/rest/createPlaylist.view` | 创建播放列表 |
| `/rest/updatePlaylist.view` | 更新播放列表 |
| `/rest/deletePlaylist.view` | 删除播放列表 |
| `/rest/getUser.view` | 获取用户信息 |
| `/rest/getUsers.view` | 获取用户列表（管理员） |

### 管理员接口

| 接口 | 方法 | 说明 |
|------|------|------|
| `/rest/initUpload.view` | POST | 初始化分片上传（自定义扩展） |
| `/rest/uploadChunk.view` | POST | 上传文件分片（自定义扩展） |
| `/rest/finalizeUpload.view` | GET | 完成上传并合并分片（自定义扩展） |
| `/rest/updateMetadata.view` | POST | 更新音乐元数据（自定义扩展） |
| `/rest/startScan.view` | GET | 触发媒体库扫描 |

> 管理员接口为项目自定义扩展，非 Subsonic 标准协议。

## 认证方式

### 经典模式
请求参数携带 `u`（用户名）和 `p`（密码哈希）：
```
p = SHA256("subsonic" + 明文密码)
p = "enc:" + 上述哈希值
```

### Token 模式
1. 调用 `/rest/getToken.view` 获取 JWT Token
2. 后续请求携带 `t`（Token）和 `s`（16位随机盐值）

## 项目结构

```
audio-go/
├── backend/                          # Go 后端
│   ├── cmd/server/
│   │   ├── main.go                   # 入口文件：启动服务器、初始化数据库、启动扫描
│   │   └── router.go                 # 路由注册（公开/认证/管理员三级权限）
│   ├── config/
│   │   ├── config.go                 # 配置加载（YAML + 环境变量覆盖）
│   │   └── config.yaml               # 默认配置
│   ├── internal/
│   │   ├── auth/                     # 认证模块（Subsonic 认证 + JWT Token）
│   │   ├── database/                 # 数据库（SQLite 初始化、GORM 模型）
│   │   ├── metadata/                 # 元数据编辑模块
│   │   ├── middleware/               # 中间件（CORS、日志、限速、认证）
│   │   ├── music/                    # 音乐库核心（Subsonic 50+ API 实现）
│   │   ├── scan/                     # 媒体扫描模块（ffprobe 元数据读取）
│   │   ├── system/                   # 系统模块（ping、license、用户管理）
│   │   └── upload/                   # 分片上传模块（断点续传、文件合并）
│   └── pkg/utils/                    # 通用工具（Subsonic 响应构建、错误码）
│
├── frontend/                         # Vue 3 前端
│   ├── src/
│   │   ├── api/                      # Axios HTTP 客户端（封装 Subsonic 认证）
│   │   ├── components/               # 公共组件（播放器、对话框等）
│   │   ├── router/                   # 前端路由
│   │   ├── stores/                   # Pinia 状态管理（认证、播放器）
│   │   ├── types/                    # TypeScript 类型定义
│   │   └── views/                    # 页面视图（艺术家、专辑、上传等）
│   └── vite.config.ts                # Vite 构建配置（开发代理至后端）
│
└── .trae/specs/                      # 项目规范和 Subsonic API 文档
```