hyw-koneko-source-admin-original/README.md

# HYW & Koneko 音源管理后台

<div align="center">

**多平台音源聚合服务**

支持 LX Music、澜音、QZ Music 格式

[![Version](https://img.shields.io/badge/version-3.0.0-blue.svg)](https://github.com)
[![License](https://img.shields.io/badge/license-ISC-green.svg)](LICENSE)
[![Next.js](https://img.shields.io/badge/Next.js-15-black.svg)](https://nextjs.org)
[![Ant Design](https://img.shields.io/badge/Ant%20Design-5-blue.svg)](https://ant.design)

</div>

---

## 📖 项目简介

HYW & Koneko 音源管理后台是一个功能强大的多平台音源聚合服务，支持多种音源格式，提供完善的音源管理、卡密系统、频率限制、主题定制等功能。

### 🎯 核心特性

- **多格式支持**：支持 LX Music、澜音、QZ Music 三种主流音源格式
- **多平台覆盖**：支持酷我、酷狗、QQ音乐、网易云、咪咕五大音乐平台
- **多音质选择**：从 128kbps 到 Master 臻品音质，满足不同需求
- **智能调度**：5种调度策略，自动选择最优音源
- **主题系统**：8种预设主题 + 自定义主题编辑器
- **卡密系统**：完善的卡密生成、验证、统计功能
- **频率限制**：全局 QPS、单 IP 限制、自动封禁
- **鉴权系统**：支持本地登录和第三方认证（预留）

---

## 👥 开发团队

### 合作开发

**MistAperio Studio × Macrohard Studio**

### 编写人

- **雾启工作室@云汀** (Cloudwhisper / Miao-moe)
- **Macrohard Studio@Ryn磷熠** (Macrohard0001)

### 致谢

> 旧版后台由 Macrohard Studio 开发，编写人 @Macrohard0001

---

## 🚀 快速开始

### 环境要求

- Node.js >= 18.0.0
- npm >= 9.0.0 或 pnpm >= 8.0.0

### 安装依赖

```bash
npm install
# 或
pnpm install
```

### 配置环境变量

```bash
cp .env.example .env
# 编辑 .env 文件配置你的环境变量
```

### 初始化数据库

```bash
npm run db:push
# 或
npm run db:migrate
```

### 启动开发服务器

```bash
npm run dev
```

访问 http://localhost:3000 查看效果。

---

## 📁 项目结构

```
hyw-koneko-source-admin/
├── prisma/                 # 数据库模型
│   └── schema.prisma
├── public/                 # 静态资源
├── src/
│   ├── app/               # Next.js App Router
│   │   ├── api/          # API 路由
│   │   ├── login/        # 登录页面
│   │   ├── sources/      # 音源管理
│   │   ├── settings/     # 系统设置
│   │   ├── card-keys/    # 卡密管理
│   │   ├── ip-rules/     # IP 规则
│   │   ├── logs/         # 日志查询
│   │   ├── theme/        # 主题设置
│   │   └── ...
│   ├── components/        # React 组件
│   ├── hooks/            # 自定义 Hooks
│   ├── lib/              # 核心库
│   │   ├── auth/        # 鉴权模块
│   │   ├── music/       # 音乐业务模块
│   │   └── theme/       # 主题系统
│   └── types/            # 类型定义
├── package.json
├── tsconfig.json
└── next.config.ts
```

---

## 🎨 主题系统

### 预设主题

| 主题 | 描述 |
|------|------|
| 默认主题 | Ant Design 经典蓝色主题 |
| 深色模式 | 护眼深色主题 |
| 二次元 | 可爱的粉色调主题 |
| 福瑞 | 温暖的橙棕色调主题 |
| 樱花 | 浪漫的樱花粉色主题 |
| 海洋 | 清新的海洋蓝色主题 |
| 森林 | 自然的森林绿色主题 |
| 午夜 | 深邃的紫色调深色主题 |

### 自定义主题

支持通过主题编辑器自定义：
- 主题色、背景色、文字色、边框色
- 圆角大小
- 背景图片（支持模糊、透明度）
- 自定义 CSS

---

## 📡 API 文档

### 获取音乐 URL

```http
GET /api/music/url?platform=kw&songId=123456&quality=320k
```

### 批量获取

```http
POST /api/music/url
Content-Type: application/json

{
  "items": [
    { "platform": "kw", "songId": "123", "quality": "320k" },
    { "platform": "tx", "songId": "456", "quality": "flac" }
  ]
}
```

### 音源管理

```http
GET    /api/music/source     # 获取音源列表
POST   /api/music/source     # 上传音源
PUT    /api/music/source     # 更新音源
DELETE /api/music/source     # 删除音源
```

---

## 🔐 鉴权系统

### 支持的认证方式

1. **本地登录**：用户名/邮箱 + 密码
2. **第三方认证**：auth.shiqianjiang.cn（预留）

### 权限等级

| 角色 | 权限 |
|------|------|
| user | 基础音质访问 |
| vip | 全部音质访问 |
| admin | 完全控制权限 |

---

## 📊 支持的平台与音质

### 平台

| 代码 | 平台 | ID 字段 |
|------|------|---------|
| kw | 酷我音乐 | songId / rid |
| kg | 酷狗音乐 | hash |
| tx | QQ音乐 | songmid / strMediaMid |
| wy | 网易云音乐 | songId |
| mg | 咪咕音乐 | copyrightId |

### 音质

| 代码 | 名称 |
|------|------|
| 128k | 128kbps |
| 320k | 320kbps |
| flac | FLAC 无损 |
| flac24bit | FLAC 24bit |
| hires | Hi-Res |
| dolby | Dolby Atmos |
| atmos_plus | Dolby Atmos Plus |
| master | Master 臻品 |

---

## 📝 开发命令

```bash
# 开发
npm run dev

# 构建
npm run build

# 启动生产服务器
npm run start

# 数据库操作
npm run db:generate    # 生成 Prisma Client
npm run db:push        # 推送数据库结构
npm run db:migrate     # 创建迁移
npm run db:studio      # 打开 Prisma Studio

# 代码检查
npm run lint
```

---

## 📄 许可证

ISC License

---

## 🙏 致谢

- [Next.js](https://nextjs.org/)
- [Ant Design](https://ant.design/)
- [Prisma](https://www.prisma.io/)
- [LX Music](https://github.com/lyswhut/lx-music-desktop)

---

<div align="center">

**Made with ❤️ by MistAperio Studio × Macrohard Studio**

</div>