VoiceHub

VoiceHub - 校园广播站点歌系统

这是一个使用Nuxt 4全栈框架开发的现代化校园广播站点歌管理系统。系统提供完整的点歌、投票、排期管理、通知推送、数据分析、权限控制和数据库管理功能，支持多角色权限管理和灵活的系统配置。

项目截图

主要功能

🎵 核心功能

• 智能点歌系统：用户可以点歌或给已有歌曲投票，支持网易云音乐、QQ音乐和哔哩哔哩搜索，可选择期望播出时段
• 多平台登录支持：
  • OAuth 账户系统：支持通过 GitHub、Casdoor 等 OAuth 提供商快速创建和登录账户
    • 直接创建账户：用户通过 OAuth 认证后可创建新账户，但仍需设置本地用户名和密码
    • 账户绑定：已有账户的用户可将 OAuth 身份绑定到现有账户，实现多平台统一登录
    • WebAuthn 支持：支持 HarmonyOS Passkey、Windows Hello、生物识别和硬件安全密钥（如 YubiKey）登录
    • 双因素认证（2FA）：支持 TOTP 和邮箱验证，增强账户安全性
  • 网易云音乐登录：支持扫码登录，登录后可搜索个人歌单、收藏及播客电台内容
    • 一键添加到歌单：登录后支持将排期中的网易云音乐歌曲一键添加到个人歌单
    • 从歌单投稿：支持从个人歌单中直接投稿歌曲到系统
    • 从最近播放投稿：支持从最近播放记录中投稿歌曲
    • 播客电台投稿：支持搜索和投稿播客电台内容
• 投稿限额管理：灵活配置用户投稿限制，支持按时间段、用户角色设置不同的投稿额度，有效控制系统负载
• 歌曲去重功能：智能识别重复歌曲，优化歌曲库管理，避免重复播放
• 歌曲管理：按热度排序，避免重复播放，动态URL防止链接过期，支持黑名单管理
• 音乐播放器：内置音乐播放器，支持进度控制和音质实时切换
• 音质切换：支持多种音质选择（标准、HQ、无损、Hi-Res等），动态获取最新播放链接
• 音乐下载功能：支持管理员下载歌曲到本地，提供多种音质选择和批量下载
• 歌曲重播功能：支持用户对已播放过的歌曲发起重播申请，支持查看申请记录和撤回申请

👥 用户管理

• 用户管理：管理员添加用户，支持按年级班级分类
• 账户创建方式：
  • 管理员直接添加账户
  • 用户通过 OAuth 快速创建账户
  • 用户通过传统用户名/密码注册
• 权限控制：多级权限管理，支持普通用户、管理员、超级管理员
• 账户安全：
  • bcrypt 密码加密
  • 双因素认证（TOTP、邮箱验证）
  • WebAuthn 支持（HarmonyOS Passkey、生物识别、硬件密钥）
  • 账户锁定和风险控制
• 身份关联：支持将多个 OAuth 身份绑定到同一账户，实现统一登录
• 黑名单管理：支持歌曲和艺术家黑名单，自动过滤不当内容

📅 排期管理

• 排期管理：管理员可以通过拖拽界面进行歌曲排期和顺序管理
• 排期草稿：支持保存排期草稿功能，允许管理员分步完成排期安排
  • 草稿状态不影响公开展示，可随时修改和完善
  • 支持草稿发布为正式排期，确保排期质量
• 播出时段：灵活配置播出时段，支持多时段管理
• 打印排期：支持自定义纸张大小、内容选择、编写备注和PDF导出的打印功能
• 学期管理：管理员可设置当前学期，自动关联点歌记录
• 公开展示：公开展示歌曲播放排期，按日期分组展示

🔔 通知系统

• 实时通知：歌曲被选中、投票和系统通知
• 通知设置：用户可自定义通知偏好，支持独立页面设置
• 批量通知：管理员可向特定用户群体发送通知
• 社交账号绑定：支持绑定MeoW等账号，同步推送通知到外部平台
• 验证码验证：安全的验证码验证机制，支持动态样式反馈

💾 数据管理

• 数据库备份：完整的数据库备份和恢复功能
• 数据库重置：支持安全的数据库重置操作，可选择性保留用户数据或完全重置
• 文件导入导出：支持备份文件的上传、下载和管理
• 数据库自检：自动数据库验证和修复机制，确保系统稳定性

🎨 用户体验

• 现代UI：响应式设计，深色主题，流畅的动画效果
• 玻璃态设计：现代化的视觉效果和交互体验
• 交互反馈：hover效果，点击反馈，状态变化动画
• 移动端优化：适配支持移动设备访问，触摸友好的交互设计

技术栈

前端技术

• Nuxt 4：Vue.js全栈框架，提供SSR和SPA支持
• Vue 3：响应式前端框架，使用Composition API
• TypeScript：类型安全的JavaScript，提供完整的类型定义
• Tailwind CSS：实用优先的CSS框架，响应式设计
• Vue Router：前端路由管理

后端技术

• Nuxt Server API：服务端API路由，支持中间件和认证
• Drizzle ORM：现代化数据库ORM，提供类型安全的数据库操作和高性能查询
• Neon Database：Serverless PostgreSQL数据库，支持自动启停和无缝扩展
• PostgreSQL：关系型数据库，支持复杂查询和事务处理
• Redis：可选的分布式短期状态服务，仅用于验证码、限流和临时安全状态
• JWT：标准JWT认证机制，支持24小时token有效期
• bcrypt：密码加密，安全的哈希算法
• Multer：文件上传处理，支持多种存储方式

系统架构

系统采用了现代化的 Serverless 全栈架构：

• 前端：使用 Nuxt 4 + Vue 3 组合式API构建响应式用户界面
• 后端：使用 Nuxt Server API 构建 RESTful API 服务
• 数据库：使用 Drizzle ORM + Neon Database，提供类型安全和高性能的数据库操作
• 认证：标准 JWT 认证系统
• 数据读取：PostgreSQL 是唯一业务数据源，歌曲、排期和用户状态不使用 Redis 缓存
• 部署：支持 Vercel、Netlify、EdgeOne 等 Serverless 平台一键部署，并提供 Docker、Linux 一键脚本及飞牛 FnOS (fpk安装包) 等多种部署方式

部署指南

一键部署

本项目可以一键部署到Vercel/Netlify/EdgeOne平台：

在部署过程中，需要输入必要的环境变量：

1. DATABASE_URL：PostgreSQL数据库连接地址
2. JWT_SECRET：JWT令牌签名密钥

Claw 部署

1. 点击部署按钮：选择上方的 Claw 部署按钮
2. 打开应用程序启动板：打开 App Launchpad （应用程序启动板）
3. 创建应用：选 Create App （创建应用）
4. 相关配置：

   Application Name：VoiceHub 或 其它
   Image Name: ghcr.io/laoshuikaixue/voicehub:latest
   Usage：按需调整
   Network：3000 ，开 Public Access
   Environment Variables：
      DATABASE_URL=postgresql://user:password@postgres:5432/voicehub
      # 可能需要 ?sslmode=disable
      JWT_SECRET=your-jwt-secret-here
      # 按实际情况填写
   

5. 等待部署：平台会自动构建和部署应用
6. 访问应用：部署完成后，您将获得一个可访问的 URL

Linux 服务器部署

本项目提供了针对 Ubuntu/Debian 服务器的一键部署脚本，支持自动安装 Node.js 22、配置环境变量、安装依赖和构建项目。

一键命令：

bash <(curl -sL https://raw.githubusercontent.com/laoshuikaixue/VoiceHub/main/sh/main.sh)

如果你需要 gh-proxy 加速，使用以下命令：

bash <(curl -sL https://gh-proxy.com/https://raw.githubusercontent.com/laoshuikaixue/VoiceHub/main/sh/main.sh)

Docker 部署

VoiceHub 支持通过 Docker 进行容器化部署，提供了多种部署方式。

方式一：使用 Docker Compose（推荐）

这是最简单的部署方式，会自动创建应用和数据库容器。

使用预构建镜像

查看 docker-compose 并选择适合的配置文件

本地构建镜像

1. 克隆项目

git clone https://github.com/laoshuikaixue/VoiceHub.git
cd VoiceHub

2. 修改 docker-compose.yml 中的环境变量

environment:
  - DATABASE_URL=postgresql://user:password@postgres:5432/voicehub # 可能需要 ?sslmode=disable
  - JWT_SECRET=your-jwt-secret-here # 请修改为强随机字符串
  - NODE_ENV=production

3. 启动服务

docker-compose up -d

4. 访问应用 打开浏览器访问 http://localhost:3000

默认管理员账号：

• 用户名：admin
• 密码：admin123

方式二：使用预构建镜像

如果你已有 PostgreSQL 数据库，可以直接使用预构建的镜像。

使用 GitHub 镜像源：

docker run -d \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://username:password@host:port/database?sslmode=require" \
  # 可能需要替换成 ?sslmode=disable
  -e JWT_SECRET="your-very-secure-jwt-secret-key" \
  -e NODE_ENV=production \
  --name voicehub \
  ghcr.io/laoshuikaixue/voicehub:latest

使用南京大学镜像源：

docker run -d \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://username:password@host:port/database?sslmode=require" \
  # 可能需要替换成 ?sslmode=disable
  -e JWT_SECRET="your-very-secure-jwt-secret-key" \
  -e NODE_ENV=production \
  --name voicehub \
  ghcr.nju.edu.cn/laoshuikaixue/voicehub:latest

方式三：本地构建镜像

如果需要自定义构建，可以本地构建镜像。

git clone https://github.com/laoshuikaixue/VoiceHub.git
cd VoiceHub

# 构建镜像（不使用缓存，确保完全重新构建）
docker build --no-cache -t voicehub .

# 运行容器
docker run -d \
  -p 3000:3000 \
  -e DATABASE_URL="postgresql://username:password@host:port/database?sslmode=require" \
  # 可能需要替换成 ?sslmode=disable
  -e JWT_SECRET="your-very-secure-jwt-secret-key" \
  -e NODE_ENV=production \
  --name voicehub \
  voicehub

飞牛 (FnOS) 部署

VoiceHub 现已支持飞牛 OS (FnOS) 的 .fpk 安装包。

• 从 GitHub Actions 获取最新版本

Nix / NixOS

VoiceHub 提供了一个 Nix flake，用于构建、开发和在 NixOS 上部署。

前提条件

• Nix（带 flake 支持）
• PostgreSQL 数据库

NixOS 部署

将 VoiceHub 添加为 flake input：

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    voicehub.url = "github:laoshuikaixue/VoiceHub";
  };

  outputs = { self, nixpkgs, voicehub, ... }: {
    nixosConfigurations.my-server = nixpkgs.lib.nixosSystem {
      specialArgs = { inherit voicehub; };
      modules = [
        voicehub.nixosModules.default
        ./configuration.nix
      ];
    };
  };
}

然后在 NixOS 配置中使用模块，根据数据库管理方式选择对应场景。

# 场景 A：自动配置本地 PostgreSQL
# environmentFile 只需提供 JWT_SECRET，DATABASE_URL 由模块自动构造
{ pkgs, inputs, config, ... }: {
  imports = [ inputs.voicehub.nixosModules.default ];

  services.voicehub = {
    enable = true;
    database.createLocally = true;
    environmentFile = config.sops.templates."voicehub-env".path;
    runDeployScript = true;
  };

  sops.templates."voicehub-env" = {
    content = ''
      JWT_SECRET=${config.sops.placeholder."voicehub/jwt-secret"}
    '';
  };
}

# 场景 B：手动管理数据库（Neon / Docker / 远程 PG）
# environmentFile 需同时提供 DATABASE_URL 和 JWT_SECRET
{ pkgs, inputs, config, ... }: {
  imports = [ inputs.voicehub.nixosModules.default ];

  services.voicehub = {
    enable = true;
    environmentFile = config.sops.templates."voicehub-env".path;
    runDeployScript = true;
  };

  sops.templates."voicehub-env" = {
    content = ''
      DATABASE_URL=${config.sops.placeholder."voicehub/database-url"}
      JWT_SECRET=${config.sops.placeholder."voicehub/jwt-secret"}
    '';
  };
}

环境文件 (sops.templates."voicehub-env".content) 格式参考：

DATABASE_URL=postgresql://voicehub:secret@localhost:5432/voicehub
JWT_SECRET=your-very-secure-jwt-secret-key
NUXT_PUBLIC_HOST=https://voicehub.example.com

推荐使用 sops-nix 管理 secrets，避免明文存储在 Nix store 中。

模块会自动设置 DynamicUser、ProtectSystem=strict、NoNewPrivileges 等安全加固。 防火墙默认不开放端口，在配置中启用以允许外部访问：

services.voicehub.openFirewall = true;

应用配置并部署：

sudo nixos-rebuild switch --flake .#my-server

查看服务状态和日志：

systemctl status voicehub
journalctl -u voicehub -f

默认监听 0.0.0.0:3000，可通过 services.voicehub.host 和 services.voicehub.port 修改。

使用 Binary Cache 加速构建

VoiceHub CI 会将构建产物推送到 Cachix binary cache， 下游用户可直接下载预构建的 pnpmDeps 和 voicehub 包，跳过本地构建。

在你的 flake 中添加 nixConfig 以启用：

{
  nixConfig = {
    extra-substituters = [ "https://voicehub.cachix.org" ];
    extra-trusted-public-keys = [ "voicehub.cachix.org-1:CKw4/RvZy5c0WVpyo5ZyLbJgdpHZ/+epofIwGOeIOhU=" ];
  };
  inputs = {
    voicehub.url = "github:laoshuikaixue/VoiceHub";
  };
}

[!IMPORTANT] 请勿通过 follows 覆盖 VoiceHub 的 nixpkgs input。缓存中的产物使用 VoiceHub 自带的 nixpkgs 构建，替换后 hash 不同，无法命中缓存。

其他功能

开发环境

进入开发 shell（自动提供 Node.js、pnpm、PostgreSQL 客户端）：

nix develop

然后在 shell 内：

cp .env.example .env   # 配置 DATABASE_URL + JWT_SECRET
pnpm install
pnpm run dev           # 启动开发服务器 (port 3000)

构建

nix build              # 产出 result/bin/voicehub

构建产物可以直接运行（需要 DATABASE_URL 等环境变量）：

DATABASE_URL="postgresql://..." JWT_SECRET="..." ./result/bin/voicehub

或使用附带的环境文件：

nix run .#default --impure

nix run 需要设置 DATABASE_URL 环境变量，否则会启动失败。

更新 pnpm 依赖哈希

当 pnpm-lock.yaml 更新后，需要同步 flake.nix 中的 pnpmDeps 哈希。仓库已配置 GitHub Actions，会在 pnpm-lock.yaml 或 flake.nix 变更时自动计算新哈希并提交回触发分支。

如果需要在本地手动更新，可以先将 flake.nix 中 pnpmDeps.hash 临时改为空字符串，然后运行：

nix build .#voicehub

Nix 会因固定输出哈希不匹配而失败，并输出 got: sha256-...，将该值写回 pnpmDeps.hash 即可。也可以使用 impure 构建辅助命令（需要网络和已安装的 pnpm）：

nix run .#build                # 在项目目录中执行，生成 .output 目录

---

本地开发部署

前提条件

• Node.js 20+
• PostgreSQL 数据库（推荐使用 Neon）
• Redis 数据库（可选；多实例或 Serverless 部署建议配置）

快速开始

1. 克隆项目

git clone https://github.com/laoshuikaixue/VoiceHub.git
cd VoiceHub

2. 安装依赖

pnpm install --frozen-lockfile

3. 配置环境变量

复制 .env.example 文件并重命名为 .env：

cp .env.example .env

编辑 .env 文件，配置必需的环境变量：

# 数据库连接地址（必填）
DATABASE_URL="postgresql://username:password@host:port/database?sslmode=require"
# 可能需要替换成 ?sslmode=disable

# JWT 认证密钥（必填）
JWT_SECRET="your-very-secure-jwt-secret-key"

# 应用运行环境（可选）
NODE_ENV=development

4. 初始化数据库

首次运行需要初始化数据库结构：

# 生成数据库迁移文件
pnpm run db:generate

# 执行数据库迁移
pnpm run db:migrate

或使用一键部署命令（推荐）：

pnpm run deploy

5. 创建管理员账户

系统会在首次部署时自动创建管理员账户。如需手动创建：

pnpm run create-admin

默认管理员账户：

• 用户名：admin
• 密码：admin123

6. 启动开发服务器

pnpm run dev

应用将在 http://localhost:3000 启动。

生产环境部署

1. 构建生产版本

pnpm run build

2. 启动生产服务器

pnpm run start

数据库管理命令

# 新的数据库初始化
pnpm run init-help

# 生成迁移文件
pnpm run db:generate

# 执行数据库迁移
pnpm run db:migrate

# 推送模式变更到数据库（开发环境）
pnpm run db:push

# 启动 Drizzle Studio（数据库管理界面）
pnpm run db:studio

# 清空数据库并重新创建管理员
pnpm run clear-db

# 安全迁移（带备份）
pnpm run safe-migrate

升级与迁移

有关如何升级现有部署和迁移数据，请参阅 升级指南。

系统配置

站点配置管理

VoiceHub 提供了完整的站点配置管理功能，支持通过管理后台动态配置系统参数：

基本信息配置

• 站点标题：自定义系统显示名称
• 站点描述：系统功能描述和介绍
• 站点Logo：支持上传自定义Logo图片

播放时段管理

• 多时段支持：支持配置多个播放时段（如午间、晚间）
• 时段名称：自定义时段显示名称
• 开始/结束时间：精确到分钟的时间控制
• 时段排序：支持拖拽调整时段显示顺序

通知系统配置

• 通知开关：控制系统通知功能的启用状态
• 通知类型：配置不同类型通知的发送规则
• 通知模板：自定义通知消息的格式和内容

数据库备份与恢复

系统提供了完整的数据备份和恢复解决方案：

备份功能

• 完整备份：包含所有数据表的完整系统备份
• 用户数据备份：仅备份用户相关数据（用户、歌曲、投票等）
• 增量备份：支持基于时间的增量备份策略

恢复功能

• 合并模式：将备份数据与现有数据合并，保留现有数据
• 替换模式：完全替换现有数据（谨慎使用）
• 数据验证：恢复前自动验证备份文件完整性

权限与角色管理

VoiceHub 实现了细粒度的权限控制系统：

角色类型

• 超级管理员 (SUPER_ADMIN)：拥有所有系统权限，包括用户管理、系统配置、数据库管理等
• 管理员 (ADMIN)：拥有日常管理权限，如用户管理、排期管理、歌曲管理、系统配置等
• 歌曲管理员 (SONG_ADMIN)：专门负责歌曲相关管理，包括排期管理、歌曲管理、打印排期等
• 普通用户 (USER)：基本的点歌、投票和查看权限

权限分类

• 内容管理权限：排期管理、歌曲管理、打印排期等
• 用户管理权限：创建、编辑、删除用户账户
• 系统管理权限：通知管理、播放时间管理、学期管理、黑名单管理、站点配置、数据库管理等

权限继承与分配

• SUPER_ADMIN：拥有所有权限
• ADMIN：拥有除数据库管理外的所有权限
• SONG_ADMIN：拥有内容管理相关权限（排期、歌曲、打印）
• USER：仅拥有基本的点歌和查看权限

权限验证

• 前端基于角色动态显示界面元素和菜单
• 后端API进行严格的权限验证
• 支持页面级和功能级的权限控制

环境变量说明

变量名	必填	说明	示例值
DATABASE_URL	是	PostgreSQL数据库连接字符串	postgresql://username:password@host:port/database?sslmode=require
JWT_SECRET	是	JWT令牌签名密钥，建议使用强随机字符串	your-very-secure-jwt-secret-key
NODE_ENV	否	运行环境，development或production	production
REDIS_URL	否	Redis短期状态服务连接字符串，用于验证码、限流和临时锁定	redis://default:password@host:port
REDIS_KEY_PREFIX	否	Redis键命名空间，多环境共用Redis时应分别设置	voicehub:v2:
NITRO_PRESET	否	Nitro预设	vercel
NUXT_PUBLIC_HOST	否	用于 CORS 和反向代理的主机名验证	your-app.com
NUXT_PUBLIC_SEO_CONFIG	否	用于自定义 PWA/SEO 配置的 JSON 字符串	{"title":"VoiceHub校园广播站点歌系统","shortName":"校园广播","description":"校园广播站点歌系统 - 让你的声音被听见","logo":"/images/logo.png"}

Redis 不参与歌曲、排期、点赞或用户资料缓存。迁移旧部署时可先执行 dry-run：

pnpm run redis:scan-legacy

确认 Redis 数据库为 VoiceHub 独占后，才可显式执行清理。PowerShell 示例：

$env:REDIS_LEGACY_CLEANUP_CONFIRM = 'VOICEHUB'
pnpm run redis:scan-legacy -- --apply

共享 Redis 默认不会自动删除；禁止使用 FLUSHDB。

OAuth 配置

系统支持通过 OAuth 提供商（如 GitHub、Casdoor、Google 等）快速创建账户和登录：

OAuth 运行时配置统一保存在管理员后台数据库中；环境变量仅用于兼容旧部署和后台一键导入，导入后以后台保存值为准。

1. 在管理员后台配置：

• 导航到系统设置 > OAuth 配置
• 配置基础设置：
  • OAuth 重定向 URI：https://yourdomain.com/api/auth/[provider]/callback
  • OAuth State 密钥：强随机字符串，用于 state 参数加密
• 启用需要的 OAuth 提供商并填写相应凭证：
  • GitHub：Client ID / Secret
  • Casdoor：Server URL / Client ID / Secret / Organization Name
  • Google：Client ID / Secret
  • 聚合登陆：AppID / AppKey / 接口地址，并可同时启用 QQ、微信、支付宝、抖音
  • 第三方 OAuth2：完整的 OAuth 端点和字段映射

2. OAuth 提供商配置： 在 OAuth 提供商的开发者控制台配置重定向 URI，确保与后台配置一致

3. 账户创建流程：

• 用户点击 OAuth 登录按钮
• 完成 OAuth 认证后，若身份未关联，用户可选择：
  • 创建新账户：设置用户名和密码，直接创建新账户
  • 绑定现有账户：输入现有用户名和密码进行绑定
• 成功后自动登录

4. 安全特性：

• 所有密码使用 bcrypt 加密
• OAuth 状态参数使用 AES 加密校验
• 绑定令牌有 10 分钟有效期
• 支持账户锁定和风险控制

项目结构

VoiceHub/
├── .github/                   # GitHub 配置目录
│   └── workflows/             # GitHub Actions 工作流
│       ├── build-fpk.yml      # FnOS FPK 安装包构建
│       ├── docker-build.yml   # Docker 镜像构建
│       ├── docker-postgres.yml # PostgreSQL Docker 镜像构建
│       ├── nix.yml            # Nix 构建校验
│       └── update-nix-pnpm-hash.yml # 自动同步 pnpmDeps 哈希
├── app/                       # Nuxt 4 应用主目录
│   ├── app.vue                # 应用入口文件
│   ├── assets/                # 静态资源目录
│   │   └── css/               # CSS样式文件
│   │       ├── components.css      # 组件样式
│   │       ├── lyric-player.module.css  # 歌词播放器样式
│   │       ├── main.css           # 主样式文件
│   │       ├── markdown.css       # Markdown样式
│   │       ├── mobile-admin.css   # 移动端管理样式
│   │       ├── print-fix.css      # 打印样式修复
│   │       ├── sf-pro-icons.css   # SF Pro图标字体
│   │       ├── theme-protection.css # 主题保护样式
│   │       ├── transitions.css    # 过渡动画样式
│   │       ├── variables.css      # CSS变量定义
│   │       └── year-review.css    # 年度回顾样式
│   ├── components/            # Vue组件目录
│   │   ├── Admin/             # 管理员功能组件
│   │   │   ├── ApiKeyManager.vue      # API密钥管理
│   │   │   ├── BackupManager.vue      # 数据库备份管理
│   │   │   ├── BatchUpdateModal.vue   # 批量更新模态框
│   │   │   ├── BlacklistManager.vue   # 黑名单管理
│   │   │   ├── CardCodesManager.vue   # 点歌券管理
│   │   │   ├── DataAnalysisPanel.vue  # 数据分析面板
│   │   │   ├── DatabaseManager.vue    # 数据库管理
│   │   │   ├── EmailTemplateManager.vue # 邮件模板管理
│   │   │   ├── NotificationSender.vue # 通知发送管理
│   │   │   ├── OAuthConfigManager.vue # OAuth 配置管理
│   │   │   ├── OverviewDashboard.vue  # 管理概览仪表板
│   │   │   ├── PlayTimeManager.vue    # 播放时间管理
│   │   │   ├── ProviderConfigSection.vue # OAuth 提供商配置组件
│   │   │   ├── RequestTimeManager.vue # 点歌时间管理
│   │   │   ├── ScheduleForm.vue       # 排期表单
│   │   │   ├── ScheduleItemPrint.vue  # 排期项目打印
│   │   │   ├── ScheduleManager.vue    # 排期管理
│   │   │   ├── SchedulePlaylistFilterModal.vue # 排期歌单过滤器
│   │   │   ├── SchedulePrinter.vue    # 排期打印功能
│   │   │   ├── ScheduleTablePrint.vue # 排期表格打印功能
│   │   │   ├── SemesterManager.vue    # 学期管理
│   │   │   ├── Sidebar.vue            # 管理后台侧边栏
│   │   │   ├── SiteConfigManager.vue  # 站点配置管理
│   │   │   ├── SmtpManager.vue        # SMTP邮件服务管理
│   │   │   ├── SongDownloadDialog.vue # 歌曲下载弹窗
│   │   │   ├── SongManagement.vue     # 歌曲管理
│   │   │   ├── SubmissionRemarkDialog.vue # 投稿备注弹窗
│   │   │   ├── UserManager.vue        # 用户管理
│   │   │   ├── UserSongsModal.vue     # 用户歌曲查看弹窗
│   │   │   └── VotersModal.vue        # 投票人员查看弹窗
│   │   ├── AMLL/              # Apple Music-Like Lyrics组件
│   │   │   └── LyricPlayer.vue # AMLL歌词播放器
│   │   ├── Auth/              # 认证相关组件
│   │   │   ├── Providers/     # 第三方登录提供商组件
│   │   │   │   ├── Casdoor/   # Casdoor登录组件
│   │   │   │   │   └── Icon.vue # Casdoor图标
│   │   │   │   ├── GitHub/    # GitHub登录组件
│   │   │   │   │   └── Icon.vue # GitHub图标
│   │   │   │   └── Google/    # Google登录组件
│   │   │   │       └── Icon.vue # Google图标
│   │   │   ├── ChangePasswordForm.vue # 修改密码表单
│   │   │   ├── LoginForm.vue         # 登录表单
│   │   │   ├── OAuthBindingCard.vue  # OAuth绑定卡片
│   │   │   ├── CaptchaInput.vue      # 图形验证码输入组件
│   │   │   ├── TurnstileWidget.vue   # Cloudflare Turnstile验证组件
│   │   │   ├── OAuthButtons.vue      # OAuth登录按钮组
│   │   │   ├── TwoFactorSetup.vue    # 双重认证设置组件
│   │   │   └── TwoFactorVerify.vue   # 双重认证验证组件
│   │   ├── Common/            # 通用组件
│   │   │   └── UserSearchModal.vue   # 用户搜索弹窗
│   │   ├── Notifications/     # 通知系统组件
│   │   │   └── NotificationSettings.vue # 通知设置
│   │   ├── Player/            # 播放器相关组件
│   │   │   └── PlayerLyric/   # 播放器歌词子组件
│   │   │       ├── AMLyric.vue        # Apple Music风格歌词
│   │   │       └── DefaultLyric.vue   # 默认风格歌词
│   │   ├── Songs/             # 歌曲相关组件
│   │   │   ├── AlbumDetailsModal.vue   # 网易云音乐专辑详情弹窗
│   │   │   ├── BilibiliEpisodesModal.vue # Bilibili剧集选择弹窗
│   │   │   ├── DuplicateSongModal.vue # 重复歌曲处理对话框
│   │   │   ├── ImportSongsModal.vue   # 导入歌曲弹窗
│   │   │   ├── NeteaseLoginModal.vue  # 网易云音乐登录弹窗
│   │   │   ├── NeteaseUploadDialog.vue # 网易云云盘上传弹窗
│   │   │   ├── PlaylistSelectionModal.vue # 歌单选择弹窗
│   │   │   ├── PodcastEpisodesModal.vue # 播客节目弹窗
│   │   │   ├── QQMusicLoginModal.vue # QQ音乐登录弹窗
│   │   │   ├── RecentSongsModal.vue   # 最近播放弹窗
│   │   │   ├── RequestForm.vue        # 点歌表单
│   │   │   ├── ScheduleList.vue       # 排期列表展示
│   │   │   └── SongList.vue           # 歌曲列表
│   │   ├── UI/                # 通用UI组件
│   │   │   ├── AudioPlayer/   # 音频播放器组件模块
│   │   │   │   ├── AudioElement.vue   # 音频元素组件
│   │   │   │   ├── PlayerControls.vue # 播放器控制组件
│   │   │   │   ├── PlayerInfo.vue     # 播放器信息组件
│   │   │   │   └── VolumeControl.vue  # 播放器音量控制组件
│   │   │   ├── Common/        # 通用UI组件
│   │   │   │   ├── CustomSelect.vue   # 自定义选择器
│   │   │   │   ├── DataTable.vue      # 通用数据表格组件
│   │   │   │   ├── ErrorBoundary.vue  # 错误边界组件
│   │   │   │   ├── LoadingState.vue   # 加载状态组件
│   │   │   │   ├── Pagination.vue     # 翻页组件
│   │   │   │   ├── Popover.vue        # 弹出框组件
│   │   │   │   ├── SearchFilter.vue   # 搜索过滤组件
│   │   │   │   └── StatCard.vue       # 统计卡片组件
│   │   │   ├── AppleMusicLyrics.vue   # 类Apple Music风格歌词显示组件
│   │   │   ├── AudioPlayer.vue        # 主音频播放器组件
│   │   │   ├── BilibiliIframeModal.vue # Bilibili视频预览弹窗
│   │   │   ├── ConfirmDialog.vue      # 确认对话框
│   │   │   ├── Icon.vue               # 图标组件
│   │   │   ├── LyricsModal.vue        # 全屏歌词模态框组件
│   │   │   ├── MarqueeText.vue        # 滚动文本显示组件
│   │   │   ├── Notification.vue       # 单个通知组件
│   │   │   ├── NotificationContainer.vue # 通知容器组件
│   │   │   ├── PageTransition.vue     # 页面过渡动画
│   │   │   ├── ProgressBar.vue        # 进度条组件
│   │   │   ├── AppLoadingScreen.vue   # 启动加载屏幕组件
│   │   │   ├── SongComments.vue       # 网易云音乐评论组件
│   │   │   └── WarpCanvas.vue         # 动态画布背景组件
│   │   ├── year-review/       # 年度回顾组件
│   │   └── SiteFooter.vue         # 站点页脚
│   ├── composables/           # Vue 3 组合式API
│   │   ├── useAdmin.ts         # 管理员功能hooks
│   │   ├── useAudioPlayer.ts   # 音频播放器hooks
│   │   ├── useAudioPlayerControl.ts # 音频播放器控制hooks
│   │   ├── useAudioPlayerEnhanced.ts # 增强音频播放器hooks
│   │   ├── useAudioPlayerSync.ts # 音频播放器同步hooks
│   │   ├── useAudioQuality.ts  # 音质管理hooks
│   │   ├── useAudioVisualizer.ts # 音频可视化hooks
│   │   ├── useAuth.ts          # 认证功能hooks
│   │   ├── useBackgroundRenderer.ts # 背景渲染hooks
│   │   ├── useBilibiliPreview.ts # Bilibili视频预览hooks
│   │   ├── useErrorHandler.ts  # 错误处理hooks
│   │   ├── useLyricManager.ts  # 歌词管理hooks
│   │   ├── useLyricPlayer.ts   # 类Apple Music风格歌词播放器hooks
│   │   ├── useLyrics.ts        # 歌词功能hooks
│   │   ├── useLyricSettings.ts # 歌词设置hooks
│   │   ├── useMediaSession.ts  # 媒体会话API hooks
│   │   ├── useMusicSources.ts    # 音乐源管理hooks
│   │   ├── useMusicWebSocket.ts  # 音乐WebSocket hooks
│   │   ├── useNotifications.ts # 通知功能hooks
│   │   ├── usePermissions.ts   # 权限管理hooks
│   │   ├── usePasswordStrength.ts # 密码强度检测hooks
│   │   ├── useProgress.ts      # 进度管理hooks
│   │   ├── useProgressEvents.ts # 进度事件hooks
│   │   ├── useRequestDedup.ts  # 请求去重hooks
│   │   ├── useSemesters.ts     # 学期管理hooks
│   │   ├── useSiteConfig.js    # 站点配置hooks
│   │   ├── useSongPlayer.ts    # 歌曲播放器hooks
│   │   ├── useSongs.ts         # 歌曲管理hooks
│   │   ├── useSyncedTime.ts    # 时间同步hooks
│   │   ├── useToast.ts         # Toast提示hooks
│   │   └── useUserFilters.ts  # 用户过滤器hooks
│   ├── drizzle/               # 数据库相关
│   │   ├── db.ts               # 数据库连接
│   │   ├── schema.ts           # 数据库模型
│   │   └── migrations/         # 数据库迁移文件
│   │       ├── *.sql           # Drizzle 迁移脚本
│   │       └── meta/           # Drizzle 迁移快照
│   ├── layouts/               # 布局组件
│   │   └── default.vue         # 默认布局模板
│   ├── middleware/            # 中间件
│   │   └── auth.global.ts      # 全局认证中间件
│   ├── pages/                 # 页面组件（Nuxt 4路由）
│   │   ├── account/           # 账户管理页面
│   │   │   └── index.vue      # 账户中心（绑定管理）
│   │   ├── auth/              # 认证相关页面
│   │   │   └── error.vue      # 认证错误页面
│   │   ├── change-password.vue # 修改密码页面
│   │   ├── dashboard.vue       # 用户仪表盘
│   │   ├── forgot-password.vue # 找回密码页面
│   │   ├── index.vue           # 首页
│   │   ├── login.vue           # 登录页面
│   │   ├── notification-settings.vue # 通知设置页面
│   │   ├── reset-password.vue  # 重置密码页面
│   │   └── year-review.vue     # 年度回顾页面
│   ├── plugins/               # Nuxt插件
│   │   ├── auth.client.ts      # 客户端认证插件
│   │   ├── auth.server.ts      # 服务端认证插件
│   │   └── time-sync.client.ts # 客户端时间同步插件
│   ├── public/                # 静态文件目录
│   │   ├── images/            # 图片资源
│   │   │   ├── logo.png       # PNG格式Logo
│   │   │   ├── logo.svg       # SVG格式Logo
│   │   │   ├── search.svg     # 搜索图标
│   │   │   └── thumbs-up.svg  # 点赞图标
│   │   ├── favicon.ico        # 网站图标
│   │   └── robots.txt         # 搜索引擎爬虫配置
│   └── utils/                 # 工具函数
│       ├── core/              # 核心工具
│       │   └── security.ts    # 安全相关工具
│       ├── lyric/             # 歌词处理工具
│       │   ├── exclude.ts     # 歌词排除规则
│       │   ├── lyricFormat.ts # 歌词格式化
│       │   ├── lyricMatchQuality.ts # 歌词版本一致性检测
│       │   ├── lyricParser.ts # 歌词解析器
│       │   ├── lyricStripper.ts # 歌词清理
│       │   ├── parseLrc.ts    # LRC格式解析
│       │   └── qrc-parser.ts  # QRC格式解析
│       ├── bilibiliSource.ts  # 哔哩哔哩音源
│       ├── debounce.ts       # 防抖工具
│       ├── lyricAdapter.ts    # 歌词适配器
│       ├── markdown.js        # Markdown工具
│       ├── musicSources.ts    # 音乐源配置
│       ├── musicUrl.ts        # 音乐URL处理
│       ├── sentryUpstreamMusicErrors.ts # Sentry 上游音源错误过滤
│       ├── neteaseApi.ts      # 网易云音乐API
│       ├── oauth-register.ts  # OAuth注册工具
│       ├── oauth.ts           # OAuth工具
│       ├── timeUtils.ts       # 时间工具
│       ├── webauthn.js        # WebAuthn浏览器兼容工具
│       └── url.ts             # URL处理工具
├── server/                # 服务端代码
│   ├── api/                # API路由
│   │   ├── admin/          # 管理员API
│   │   │   ├── api-keys/            # API密钥管理API
│   │   │   │   ├── [id].delete.ts   # 删除API密钥
│   │   │   │   ├── [id].get.ts      # 获取API密钥详情
│   │   │   │   ├── [id].put.ts      # 更新API密钥
│   │   │   │   ├── index.get.ts     # 获取API密钥列表
│   │   │   │   ├── index.post.ts    # 创建API密钥
│   │   │   │   └── logs.get.ts      # API使用日志
│   │   │   ├── backup/              # 备份管理API
│   │   │   │   ├── delete/          # 删除备份子目录
│   │   │   │   │   └── [filename].delete.ts
│   │   │   │   ├── download/        # 下载备份子目录
│   │   │   │   │   └── [filename].get.ts
│   │   │   │   ├── clear.post.ts    # 清空备份历史
│   │   │   │   ├── download.get.ts  # 下载备份
│   │   │   │   ├── export.post.ts   # 创建备份
│   │   │   │   ├── list.get.ts      # 获取备份列表
│   │   │   │   ├── restore-chunk.post.ts # 恢复备份分片
│   │   │   │   ├── restore.post.ts  # 恢复备份
│   │   │   │   └── upload.post.ts   # 上传备份文件
│   │   │   ├── blacklist/           # 黑名单管理API
│   │   │   │   ├── [id].delete.ts   # 删除黑名单项
│   │   │   │   ├── [id].patch.ts    # 更新黑名单项
│   │   │   │   ├── index.get.ts     # 获取黑名单列表
│   │   │   │   └── index.post.ts    # 添加黑名单项
│   │   │   ├── card-codes/          # 点歌券管理API
│   │   │   │   ├── [id].put.ts      # 更新单张点歌券
│   │   │   │   ├── create.post.ts   # 创建点歌券
│   │   │   │   ├── delete.post.ts   # 删除点歌券
│   │   │   │   ├── export.get.ts    # 导出点歌券
│   │   │   │   ├── index.get.ts     # 获取点歌券列表
│   │   │   │   ├── redeem-logs.get.ts # 获取点歌券日志
│   │   │   │   └── update.post.ts   # 批量更新点歌券
│   │   │   ├── database/            # 数据库管理API
│   │   │   │   ├── cleanup.post.ts  # 数据库清理
│   │   │   │   ├── performance.get.ts # 数据库性能监控
│   │   │   │   ├── pool-status.get.ts # 连接池状态
│   │   │   │   ├── reset.post.ts    # 重置数据库
│   │   │   │   └── status.get.ts    # 数据库状态
│   │   │   ├── db-status.get.ts     # 数据库状态检查
│   │   │   ├── email-templates/     # 邮件模板管理API
│   │   │   │   ├── index.delete.ts  # 删除邮件模板
│   │   │   │   ├── index.get.ts     # 获取邮件模板列表
│   │   │   │   ├── index.post.ts    # 创建/更新邮件模板
│   │   │   │   └── preview.post.ts  # 预览邮件模板
│   │   │   ├── fix-sequence.post.ts # 修复数据库序列
│   │   │   ├── notifications/       # 管理员通知API
│   │   │   │   └── send.post.ts     # 发送通知
│   │   │   ├── play-times/          # 播放时间管理API
│   │   │   │   ├── [id].ts          # 播放时间操作
│   │   │   │   ├── index.post.ts    # 创建播放时间
│   │   │   │   └── index.ts         # 播放时间列表
│   │   │   ├── replay-requests/     # 重播申请管理API
│   │   │   │   ├── index.get.ts     # 获取重播申请列表
│   │   │   │   └── reject.post.ts   # 拒绝重播申请
│   │   │   ├── request-times/       # 点歌时间管理API
│   │   │   │   ├── [id].ts          # 点歌时间操作
│   │   │   │   ├── index.post.ts    # 创建点歌时间
│   │   │   │   └── index.ts         # 点歌时间列表
│   │   │   ├── schedule/            # 排期管理API
│   │   │   │   ├── bulk-publish.post.ts # 批量发布排期
│   │   │   │   ├── draft.post.ts    # 保存排期草稿
│   │   │   │   ├── full.get.ts      # 获取完整排期数据（包含草稿）
│   │   │   │   ├── move-date.post.ts # 排期日期迁移
│   │   │   │   ├── publish.post.ts  # 发布排期草稿
│   │   │   │   ├── remove.post.ts   # 移除排期
│   │   │   │   └── sequence.post.ts # 更新排期顺序
│   │   │   ├── schedule.post.ts     # 创建排期
│   │   │   ├── semesters/           # 学期管理API
│   │   │   │   ├── [id].delete.ts   # 删除学期
│   │   │   │   ├── [id].put.ts      # 更新学期
│   │   │   │   ├── index.get.ts     # 获取学期列表
│   │   │   │   ├── index.post.ts    # 创建学期
│   │   │   │   └── set-active.post.ts # 设置活跃学期
│   │   │   ├── smtp/                # SMTP邮件服务API
│   │   │   │   ├── reload.post.ts   # 重新加载SMTP配置
│   │   │   │   ├── test-connection.post.ts # 测试SMTP连接
│   │   │   │   └── test-email.post.ts # 发送测试邮件
│   │   │   ├── songs/               # 管理员歌曲管理API
│   │   │   │   ├── delete.post.ts   # 删除歌曲
│   │   │   │   ├── mark-played.post.ts  # 标记歌曲已播放
│   │   │   │   └── reject.post.ts  # 驳回歌曲
│   │   │   ├── stats.get.ts         # 统计数据
│   │   │   ├── activities.get.ts    # 活动管理API
│   │   │   ├── stats/               # 详细统计API
│   │   │   │   ├── active-users.get.ts # 活跃用户统计
│   │   │   │   ├── realtime.get.ts  # 实时统计
│   │   │   │   ├── semester-comparison.get.ts # 学期对比统计
│   │   │   │   ├── top-songs.get.ts # 热门歌曲统计
│   │   │   │   ├── trends.get.ts    # 趋势分析
│   │   │   │   └── user-engagement.get.ts # 用户参与度统计
│   │   │   ├── system-settings/     # 系统设置API
│   │   │   │   ├── env-oauth-import.post.ts # 导入环境变量OAuth配置
│   │   │   │   ├── env-oauth.get.ts # 获取环境变量OAuth配置
│   │   │   │   ├── index.post.ts    # 更新系统设置
│   │   │   │   ├── index.ts         # 获取系统设置
│   │   │   │   └── secretMask.ts    # 密钥脱敏工具
│   │   │   └── users/               # 用户管理API
│   │   │       ├── [id]/            # 用户详情操作子目录
│   │   │       │   ├── reset-password.post.ts # 重置用户密码
│   │   │       │   ├── songs.get.ts     # 获取用户点歌记录
│   │   │       │   ├── status-logs.get.ts # 获取用户状态变更日志
│   │   │       │   └── status.put.ts    # 更新用户状态
│   │   │       ├── [id].delete.ts   # 删除用户
│   │   │       ├── [id].put.ts      # 更新用户
│   │   │       ├── [id].get.ts      # 用户详情
│   │   │       ├── batch-grade-update.post.ts # 批量年级更新
│   │   │       ├── batch-status.put.ts # 批量状态更新
│   │   │       ├── batch-update.post.ts # 批量更新用户
│   │   │       ├── batch.post.ts    # 批量操作用户
│   │   │       ├── index.get.ts     # 获取用户列表
│   │   │       ├── index.post.ts    # 创建用户
│   │   │       ├── index.ts         # 用户管理
│   │   │       ├── options.ts       # 用户管理选项
│   │   │       └── status-logs.get.ts # 用户状态日志
│   │   ├── api-enhanced/          # 网易云音乐API
│   │   │   └── netease/           # 网易云增强接口代理
│   │   │       └── [...path].ts   # 转发网易云API请求
│   │   ├── auth/           # 认证API
│   │   │   ├── captcha.get.ts         # 图形验证码
│   │   │   ├── oauth-register-options.get.ts # OAuth注册选项
│   │   │   ├── 2fa/             # 2FA验证API
│   │   │   │   ├── send-email.post.ts # 发送2FA验证邮件
│   │   │   │   └── verify.post.ts     # 验证2FA代码
│   │   │   ├── webauthn/      # WebAuthn 相关 API
│   │   │   │   ├── login/     # 登录验证
│   │   │   │   │   ├── options.post.ts   # 获取登录 Challenge
│   │   │   │   │   └── verify.post.ts    # 验证登录签名
│   │   │   │   ├── register/  # 设备注册
│   │   │   │   │   ├── options.get.ts    # 获取注册 Challenge
│   │   │   │   │   └── verify.post.ts    # 验证注册签名
│   │   │   │   └── rename.post.ts    # 重命名设备
│   │   │   ├── [provider]/           # OAuth提供商路由
│   │   │   │   ├── callback.get.ts   # OAuth回调处理
│   │   │   │   └── index.get.ts      # OAuth授权跳转
│   │   │   ├── bind.post.ts          # 绑定社交账号
│   │   │   ├── change-password.post.ts # 修改密码
│   │   │   ├── forgot-password.post.ts # 找回密码
│   │   │   ├── identities.get.ts     # 获取已绑定身份列表
│   │   │   ├── login.post.ts        # 用户登录
│   │   │   ├── logout.post.ts       # 用户登出
│   │   │   ├── oauth-register.post.ts # OAuth用户注册
│   │   │   ├── reset-password.post.ts # 重置密码
│   │   │   ├── set-initial-password.post.ts # 设置初始密码
│   │   │   ├── unbind.post.ts        # 解绑社交账号
│   │   │   └── verify.get.ts        # 验证Token并获取用户信息
│   │   ├── bilibili/       # Bilibili相关API
│   │   │   ├── playurl.get.ts       # 获取播放链接
│   │   │   └── search.get.ts        # Bilibili视频搜索
│   │   ├── blacklist/      # 黑名单API
│   │   │   └── check.post.ts        # 检查黑名单
│   │   ├── card-codes/     # 点歌券API
│   │   │   └── validate.post.ts     # 验证点歌券可用性
│   │   ├── meow/           # MeoW账号绑定API
│   │   │   ├── bind.post.ts         # 绑定MeoW账号
│   │   │   └── unbind.post.ts       # 解绑MeoW账号
│   │   ├── music/          # 音乐相关API
│   │   │   ├── resolve-url.post.ts # 音乐播放链接统一解析
│   │   │   ├── state.post.ts        # 音乐状态管理
│   │   │   └── websocket.ts         # 音乐WebSocket连接
│   │   ├── native-api/     # 原生音乐API
│   │   │   ├── lyric/               # 歌词API
│   │   │   │   └── tx.get.ts        # 腾讯音乐歌词
│   │   │   ├── qq/                  # QQ音乐账号API
│   │   │   │   ├── avatar.get.ts    # 获取QQ音乐头像
│   │   │   │   ├── check-login.post.ts # 检查扫码登录情况
│   │   │   │   └── login-qr.get.ts  # 获取登录二维码
│   │   │   └── search/              # 搜索API
│   │   │       ├── tx.get.ts        # 腾讯音乐搜索
│   │   │       └── wy.get.ts        # 网易云音乐搜索
│   │   ├── notifications/  # 通知系统API
│   │   │   ├── [id]/                # 通知操作子目录
│   │   │   │   └── read.post.ts     # 标记通知已读
│   │   │   ├── [id].delete.ts       # 删除通知
│   │   │   ├── clear-all.delete.ts  # 清空所有通知
│   │   │   ├── index.ts             # 通知列表
│   │   │   ├── meow/                # MeoW通知API
│   │   │   │   ├── send-verification.post.ts # 发送验证码
│   │   │   │   └── test.post.ts     # 测试通知
│   │   │   ├── read-all.post.ts     # 标记所有已读
│   │   │   ├── settings.post.ts     # 更新通知设置
│   │   │   └── settings.ts          # 获取通知设置
│   │   ├── open/           # 开放API（无需认证）
│   │   │   ├── card-codes/          # 点歌券开放API
│   │   │   │   └── delete.post.ts   # 删除点歌券（兼容不支持 DELETE body 的代理）
│   │   │   ├── card-codes.delete.ts # 删除点歌券
│   │   │   ├── card-codes.get.ts    # 获取点歌券列表
│   │   │   ├── card-codes.patch.ts  # 更新点歌券
│   │   │   ├── card-codes.post.ts   # 创建点歌券
│   │   │   ├── songs/               # 歌曲相关开放API
│   │   │   │   ├── mark-played.post.ts # 标记歌曲已播放（供外部调用）
│   │   │   │   └── request.post.ts  # 使用个人集成令牌投稿歌曲
│   │   │   ├── schedules.get.ts     # 获取公开排期
│   │   │   └── songs.get.ts         # 获取公开歌曲列表
│   │   ├── play-times/     # 播放时间API
│   │   │   └── index.ts             # 播放时间管理
│   │   ├── request-times/  # 点歌时间API
│   │   │   └── index.ts             # 点歌时间管理
│   │   ├── progress/       # 进度条API
│   │   │   ├── events.ts            # 进度事件
│   │   │   └── id.ts                # 进度ID管理
│   │   ├── proxy/          # 代理服务API
│   │   │   └── image.get.ts         # 图片代理（解决HTTP/HTTPS混合内容及跨域问题）
│   │   ├── semesters/      # 学期API
│   │   │   ├── current.get.ts       # 获取当前学期
│   │   │   └── options.get.ts       # 获取学期选项
│   │   ├── site-config.get.ts       # 站点配置API
│   │   ├── songs/          # 歌曲相关API
│   │   │   ├── [id]/                # 歌曲详情操作
│   │   │   │   ├── update.put.ts    # 更新歌曲信息
│   │   │   │   └── voters.get.ts    # 获取投票人员
│   │   │   ├── collaborators/       # 联合投稿管理
│   │   │   │   └── reply.post.ts    # 处理联合投稿邀请
│   │   │   ├── add.post.ts          # 添加歌曲
│   │   │   ├── count.get.ts         # 歌曲统计
│   │   │   ├── import.post.ts       # 导入歌曲
│   │   │   ├── index.get.ts         # 歌曲列表
│   │   │   ├── public.get.ts        # 公开歌曲列表
│   │   │   ├── request.post.ts      # 点歌请求
│   │   │   ├── replay.post.ts       # 提交重播申请
│   │   │   ├── replay.delete.ts     # 撤回重播申请
│   │   │   ├── submission-status.get.ts # 投稿状态
│   │   │   ├── vote.post.ts         # 投票
│   │   │   └── withdraw.post.ts     # 撤回歌曲
│   │   ├── sys/            # 系统辅助API
│   │   │   └── time.get.ts          # 获取校准后的服务器时间
│   │   ├── system/         # 系统API
│   │   │   ├── instance.get.ts      # 实例信息
│   │   │   ├── location.get.ts      # 获取系统位置信息
│   │   │   ├── reconnect.post.ts    # 重连数据库
│   │   │   └── status.get.ts        # 系统状态
│   │   ├── user/           # 用户相关API
│   │   │   ├── 2fa/             # 2FA管理API
│   │   │   │   ├── disable.post.ts  # 关闭双重认证
│   │   │   │   ├── enable.post.ts   # 开启双重认证
│   │   │   │   └── generate.post.ts # 生成双重认证密钥
│   │   │   ├── api-keys/          # 个人集成令牌API
│   │   │   │   ├── [id].delete.ts # 删除个人集成令牌
│   │   │   │   ├── [id]/logs.get.ts # 获取个人集成令牌调用日志
│   │   │   │   ├── index.get.ts   # 获取个人集成令牌列表
│   │   │   │   └── index.post.ts  # 创建个人集成令牌
│   │   │   ├── email/               # 用户邮箱管理
│   │   │   │   ├── bind.post.ts     # 绑定邮箱
│   │   │   │   ├── resend-verification.post.ts # 重发验证邮件
│   │   │   │   ├── send-code.post.ts # 发送验证码
│   │   │   │   ├── unbind.post.ts   # 解绑邮箱
│   │   │   │   └── verify-code.post.ts # 验证邮箱验证码
│   │   │   └── year-review.get.ts   # 获取年度回顾数据
│   │   └── users/          # 用户API
│   │       ├── meow/                # 用户MeoW相关子目录
│   │       ├── social-accounts/     # 社交账号管理
│   │       │   ├── meow.delete.ts   # 删除MeoW绑定
│   │       │   └── meow.post.ts     # MeoW账号操作
│   │       ├── search.get.ts        # 搜索用户
│   │       └── social-accounts.get.ts # 获取社交账号
│   ├── card-codes/         # 点歌券相关
│   │   └── statuses.ts     # 点歌券状态枚举定义
│   ├── config/             # 服务端配置
│   │   └── constants.ts    # 风控阈值与时间窗口常量
│   ├── error.ts            # 全局错误处理
│   ├── middleware/         # 服务端中间件
│   │   ├── 00.request-id.ts # 请求ID注入中间件
│   │   ├── api-auth.ts     # API认证中间件
│   │   ├── api-cors.ts     # API跨域中间件
│   │   └── auth.ts         # 认证中间件
│   ├── plugins/            # 服务端插件
│   │   ├── 00.sentry.ts    # Sentry错误追踪插件
│   │   ├── 01.pre-warm-ssr.ts # SSR预热插件
│   │   ├── error-handler.ts # 错误处理插件
│   │   ├── redis-lifecycle.ts # Redis短期状态连接生命周期
│   │   └── time-sync.ts    # 服务器时间同步插件
│   ├── services/           # 业务服务层
│   │   ├── apiLogService.ts # API日志服务
│   │   ├── cardCodeDeleteService.ts # 点歌券删除服务
│   │   ├── cardCodeLifecycleService.ts # 点歌券生命周期服务
│   │   ├── meowNotificationService.ts # MeoW通知服务
│   │   ├── notificationService.ts # 通知服务
│   │   ├── oauthConfigService.ts # OAuth提供商配置与状态服务
│   │   ├── securityService.ts # 安全服务
│   │   ├── songRequestService.ts # 点歌投稿服务
│   │   ├── smtpService.ts  # SMTP邮件服务
│   │   └── userService.ts # 用户服务
│   ├── utils/              # 服务端工具函数
│   │   ├── apiKeyUtils.ts  # API Key生成、哈希与校验
│   │   ├── auth.ts         # 认证工具函数
│   │   ├── bilibiliWbi.ts  # Bilibili WBI签名工具
│   │   ├── captcha.ts      # 图形验证码生成工具
│   │   ├── captchaStore.ts # 分布式短期状态与验证码哈希存储
│   │   ├── card-code-delete-handler.ts # 点歌券删除开放API处理器
│   │   ├── database-health.ts # 数据库健康检查
│   │   ├── database-manager.ts # 数据库管理工具
│   │   ├── geo.ts          # 地理位置工具
│   │   ├── instance-id.ts  # 实例ID管理工具
│   │   ├── ip-utils.ts     # IP地址工具
│   │   ├── jwt-enhanced.ts # JWT工具
│   │   ├── log-manager.ts  # 日志管理工具
│   │   ├── native_common.ts # 原生API通用工具
│   │   ├── native_tx.ts    # 腾讯音乐原生API
│   │   ├── native_wy.ts    # 网易云音乐原生API
│   │   ├── oauth-providers.ts # OAuth提供商类型与纯函数工具
│   │   ├── oauth-strategies.ts # OAuth策略配置
│   │   ├── oauth-token.ts  # OAuth令牌工具
│   │   ├── oauth.ts        # OAuth通用工具
│   │   ├── permissions.js  # 权限系统配置
│   │   ├── qq_music_sdk.ts # QQ音乐SDK调用封装
│   │   ├── rateLimiter.ts  # 请求速率限制工具
│   │   ├── redis.ts        # 可选Redis连接与命名空间工具
│   │   ├── request-utils.ts # 请求处理通用工具
│   │   ├── serverTime.ts   # 服务器时间管理工具
│   │   ├── siteUtils.ts    # 站点工具函数
│   │   ├── studentMask.ts  # 学生隐私工具
│   │   ├── submissionLimit.ts # 投稿限额工具
│   │   ├── system-settings-defaults.ts # 系统设置默认值
│   │   ├── telemetry.ts    # 遥测与错误追踪工具
│   │   ├── user.ts         # 用户相关工具函数
│   │   ├── webauthn-config.ts # WebAuthn配置工具
│   │   └── webauthn-token.ts # WebAuthn令牌工具
│   └── tsconfig.json       # 服务端TypeScript配置
├── scripts/               # 构建、部署与数据库维护脚本
│   ├── build.js           # 输出环境变量解析结果并执行 Nuxt 构建
│   └── redis-scan-legacy.js # 旧Redis业务缓存键dry-run扫描工具
├── types/                 # TypeScript类型定义
│   ├── global.d.ts         # 全局类型定义
│   └── index.ts            # 通用类型定义
├── .env.example           # 环境变量示例文件
├── .gitignore             # Git忽略文件配置
├── .vercelignore          # Vercel部署忽略文件
├── docker-compose/        # Docker Compose配置目录
├── docker-compose.yml     # Docker编排文件
├── Dockerfile             # Docker构建文件
├── drizzle.config.ts      # Drizzle配置文件
├── flake.lock             # Nix flake锁定文件
├── flake.nix              # Nix构建与NixOS模块配置
├── LICENSE                # 开源许可证文件
├── netlify.toml           # Netlify部署配置
├── nuxt.config.ts         # Nuxt 4主配置文件
├── package.json           # Node.js项目配置和依赖
├── README.md              # 项目说明文档
├── tsconfig.json          # TypeScript配置文件
└── vercel.json            # Vercel部署配置

目录说明

核心目录 (app/)

• app/components/: Vue组件库，按功能模块组织
  • Admin/: 管理后台组件（排期、用户、数据分析等）
  • Admin_Backup/: 管理组件备份目录
  • AMLL/: Apple Music-Like Lyrics歌词播放器组件
  • Auth/: 认证相关组件（登录、OAuth绑定等）
  • Common/: 通用业务组件
  • Notifications/: 通知系统组件
  • Player/: 播放器相关组件
  • Songs/: 歌曲相关组件（点歌、导入、歌单等）
  • UI/: 通用UI组件（播放器、对话框、进度条等）
  • year-review/: 年度回顾功能组件
• app/pages/: 页面组件，Nuxt 4 自动路由
• app/composables/: Vue 3组合式API，业务逻辑复用
• app/drizzle/: Drizzle ORM配置、数据库连接和迁移文件

README 内容过长，已截取部分内容。完整内容请前往 GitHub 仓库查看。