| # 本轮功能更新说明 |
|
|
| 本文记录从 `Music-Together-Pro-UNM-Support` 分支移植并在当前项目中完成适配的功能，涵盖用户数据持久化、多音源、账号系统、服务器管理员、权限安全和审计日志。 |
|
|
| ## 1. 用户数据持久化 |
|
|
| - 新增 SQLite 数据库，默认地址为 `file:./data/music-together.db`，可通过 `DATABASE_URL` 修改。 |
| - 用户账号资料、密码 Hash、角色和平台登录 Cookie 均可在服务器重启后恢复。 |
| - 用户再次访问时可通过身份 Cookie 恢复账号及对应的房间身份。 |
| - 平台 Cookie 加密后再持久化，避免以明文形式保存第三方平台凭据。 |
| - 用户 ID 使用不区分大小写的唯一性约束，不能注册或修改为已存在的 ID。 |
|
|
| > 当前房间和播放状态仍保存在内存中。服务器重启后，账号数据会保留，但正在运行的房间会消失。 |
|
|
| ## 2. 更广的音源与音质支持 |
|
|
| - 扩展网易云音乐相关能力，并接入 QQ 音乐、酷狗音乐等音源。 |
| - 增加多平台搜索、歌曲信息解析、播放地址获取和歌单解析能力。 |
| - 支持按平台选择更多音质，包括标准、高品质、无损及平台提供的更高规格音质。 |
| - 客户端会根据音源展示可用音质，服务端负责对应音源和音质的解析与回退。 |
|
|
| 第三方平台接口和高音质播放能力仍受账号权限、Cookie 有效期、地区限制及平台接口可用性影响。 |
|
|
| ## 3. 账号功能 |
|
|
| - 账号现在包含：账号 ID、昵称、密码、头像和角色。 |
| - 用户可修改自己的昵称、头像、密码和账号 ID。 |
| - 修改密码时需要验证当前密码，验证失败返回 `401`。 |
| - 修改账号 ID 时会检查格式、重复 ID、系统保留 ID和管理员配置 ID；冲突返回 `409`，非法或不可占用的 ID 返回 `400`。 |
| - 普通用户只能修改自己的账号资料，不能指定其他用户作为修改目标，也不能自行提升为服务器管理员。 |
| - 未登录或身份失效时，会按接口要求返回 `401`、`403` 或 `409`，不会绕过账号归属检查。 |
|
|
| ## 4. 延迟创建正式账号 |
|
|
| 账号生成逻辑已调整为“设置昵称后才创建正式账号”： |
|
|
| 1. 用户首次访问时只签发临时身份 Cookie。 |
| 2. 此时不会向 `users` 表写入账号，也不会在客户端保存或展示正式用户 ID。 |
| 3. 用户保存昵称，或使用需要正式身份的创建/加入房间流程后，服务器才生成唯一账号 ID并创建账号。 |
| 4. 正式账号创建后，账号 ID、头像和密码设置等控件才会开放。 |
|
|
| 未设置昵称时： |
|
|
| - `GET /api/auth/me` 返回 `204 No Content`。 |
| - 密码和头像设置接口返回 `409 Conflict`。 |
| - 设置页显示“保存昵称后生成账号 ID”，不会暴露临时身份值。 |
|
|
| ## 5. 修改账号 ID时的数据迁移 |
|
|
| 账号 ID 修改不是简单地改一个字段。服务端会同步迁移与旧 ID 关联的数据和运行时身份，包括： |
|
|
| - 用户资料、密码 Hash 和账号角色。 |
| - 已保存的平台 Cookie。 |
| - 房主、主持人和房间管理员身份。 |
| - WebSocket 用户映射与重连票据。 |
|
|
| 迁移完成后，原账号 ID 不再代表该用户；新的身份 Cookie 和运行时映射会继续指向同一账号。 |
|
|
| ## 6. 服务器管理员 |
|
|
| - 新增服务器管理员角色和管理界面。 |
| - 可通过 `SERVER_ADMIN_IDS` 配置初始服务器管理员账号 ID，多个 ID使用英文逗号分隔。 |
| - 服务器管理员可查看用户和房间列表、重置用户密码、删除用户以及解散房间。 |
| - 配置中的管理员 ID和系统保留 ID不能被普通用户抢占。 |
|
|
| ### 权限分层 |
|
|
| 服务器管理员和房间管理员是两套独立身份： |
|
|
| - **服务器管理员**负责服务器级用户与房间治理。 |
| - **房主、主持人、房间管理员**负责当前房间内的管理操作。 |
| - 服务器管理员身份不会覆盖或清除房间角色，房间角色也不会自动获得服务器管理权限。 |
| - 所有敏感操作都在服务端重新校验身份和目标对象，不能仅靠修改客户端请求获得权限。 |
|
|
| ## 7. 管理员审计日志 |
|
|
| 管理员操作已按项目原有日志格式增加结构化审计记录，包含操作者、目标对象、操作结果及必要上下文。 |
|
|
| 新增的主要审计事件包括： |
|
|
| - `admin.access_denied` |
| - `admin.users_viewed` |
| - `admin.rooms_viewed` |
| - `admin.user_deleted` |
| - `admin.user_delete_failed` |
| - `admin.user_delete_rejected` |
| - `admin.user_password_reset` |
| - `admin.user_password_reset_failed` |
| - `admin.user_password_reset_rejected` |
| - `admin.room_dissolved` |
| - `admin.room_dissolve_failed` |
|
|
| 房间管理日志同时增加 `operatorIsServerAdmin` 字段，用于区分操作来自房间权限还是服务器管理员权限。 |
|
|
| ## 8. 安全加固 |
|
|
| - 账号资料修改以服务端认证身份为准，不接受客户端伪造的目标用户 ID。 |
| - 普通用户不能读取或修改其他用户的敏感账号信息。 |
| - 普通用户不能调用服务器管理员接口，越权访问返回 `403 Forbidden`。 |
| - 账号 ID修改采用唯一性校验和事务迁移，防止重复 ID及只迁移部分数据。 |
| - 密码只保存 Hash，不保存明文。 |
| - 平台 Cookie 加密持久化，并绑定到账号身份。 |
| - 删除用户、重置密码、解散房间等高风险管理员操作均记录成功、拒绝或失败结果。 |
|
|
| ## 9. 配置项 |
|
|
| 本轮涉及的主要环境变量如下： |
|
|
| ```dotenv |
| # SQLite 数据库地址 |
| DATABASE_URL=file:./data/music-together.db |
| |
| # 服务器管理员账号 ID，多个值使用英文逗号分隔 |
| SERVER_ADMIN_IDS=account-id-1,account-id-2 |
| |
| # 是否只通过 HTTPS发送身份 Cookie |
| IDENTITY_COOKIE_SECURE=false |
| ``` |
|
|
| 部署时应使用持久化磁盘保存数据库文件，并在 HTTPS生产环境中启用安全 Cookie 配置。 |
|
|
| ## 10. 验证结果 |
|
|
| 本轮修改已完成以下验证： |
|
|
| - 项目完整构建通过。 |
| - Prettier 格式检查通过。 |
| - Git 差异空白检查通过。 |
| - 普通用户跨账号修改注入测试通过。 |
| - 普通用户访问管理员接口返回 `403`。 |
| - 重复账号 ID返回 `409`。 |
| - 管理员配置 ID抢占返回 `400`。 |
| - 错误当前密码返回 `401`。 |
| - 修改账号 ID后，房主身份和平台 Cookie 能正确迁移。 |
| - 管理员操作会实际输出结构化审计日志。 |
| - 首次访问不会创建数据库用户；保存昵称后才生成正式账号。 |
| - 保存昵称前后账号设置界面状态正确，移动端页面无水平溢出，浏览器控制台无错误。 |
|
|
