NeteaseUrl/功能介绍.md

云村小助手 · 功能介绍

一个基于 Flask + 原生前端的云村小助手。 支持搜索、单曲/歌单/专辑/歌手解析、官方榜单、个人歌单、多账号体系、批量下载、ZIP 打包、 歌词逐字高亮、评论区、接口统计、隐私协议 Cookie 管理等完整功能。

---

一、核心功能（菜单栏 Tab）

Tab	功能	说明
搜索	多类型搜索	支持按 歌曲 / 歌单 / 专辑 / 歌手 搜索；结果点击直接跳转对应功能解析
单曲	单曲解析	输入歌曲 ID / 链接，自动按账号实测最高音质解析；含封面、歌词、直链、试听播放、下载
歌单	歌单解析	输入歌单 ID / 链接，展示歌单信息与歌曲列表（10 首/页），可逐首或批量下载
专辑	专辑解析	输入专辑 ID / 链接，展示专辑信息与歌曲列表，可批量下载
播客	播客解析	支持播客电台（djradio）与单集（program/sound）链接、短链或 ID 解析；在线试听、音频直链复制、单集服务器下载（可选 ZIP）、整台播客打包 ZIP；支持播客搜索与 19 个分类的热门播客卡片墙；单集列表分页加载、正序/倒序切换
管理员设置	管理员功能	站点管理员登录（账号+密码+绑定邮箱验证码两步验证）：全局账号二维码登录 / 删除 Cookie / 用户 IP 解析下载记录（分页）
全局账号歌单	全局歌单展示	展示全局账号（cookie.txt）收藏的歌单列表与「我喜欢的音乐」，可查看歌曲、公开播放 API 一键播放
歌手	歌手解析	输入歌手 ID / 链接，展示歌手信息与热门歌曲，可批量下载
榜单	官方榜单	63 个网易云官方榜单卡片墙，点击即可加载榜单歌曲
个人歌单	个人账号歌单	游客扫码登录自己的网易云账号，查看收藏/创建的歌单（含「我喜欢的音乐」）；Cookie 仅保存在本机浏览器
关于网站	项目信息	项目介绍、功能说明、完整更新日志

二、账号体系

• 全局账号（管理员）：cookie.txt，负责默认的解析与下载；可在「管理员设置」扫码登录黑胶会员后解析更高音质。
• 个人账号（游客）：在「个人歌单」扫码登录自己的账号，登录信息仅存储在用户自己的电脑浏览器（localStorage），其他人无法访问别人的登录账号；仅用于查看个人歌单。
• 解析账号切换：登录个人账号后，可在个人歌单内「切换为个人账号解析」；切换后当前浏览器所有菜单的解析与下载都使用个人账号，顶部「解析账号」栏实时显示当前账号 VIP 类型（普通/VIP/SVIP）与实测可解析音质列表。

三、音质体系

• 音质等级：标准 / 极高 / 无损 / Hi-Res / 沉浸环绕声 / 高清环绕声 / 超清母带 / 杜比全景声。
• 最高音质（自动）：默认选项，按当前账号实测可解析列表从高到低自动尝试（要求返回音质与请求一致），保证拿到该账号能解析的最高音质。
• 实测音质探测：账号栏展示的可解析音质为接口实测结果（如：请求 Hi-Res 实际只能拿到无损时会如实显示），避免虚标。

四、下载能力

• 单曲 / 批量下载（歌单、专辑、歌手、个人歌单全部歌曲）。
• 文件命名格式：仅歌曲名 / 歌手 - 歌曲名 / 歌曲名 - 歌手。
• 元数据写入（ffmpeg）：可按字段勾选写入 歌曲名/歌手/专辑/封面/歌词/发布日期，未勾选字段保持原文件值。
• ZIP 打包：单曲下载可打包 音频 + 歌词 + 封面 + 信息文件；批量下载可一次打包整个歌单/专辑为 ZIP。
• 歌词格式：LRC / SRT（下载歌词与打包歌词通用）。
• 下载文件保存于 /app/downloads（宿主机 downloads/ 持久卷）。

五、播放器与歌词

• 自定义深色播放器：播放/暂停、重新播放、进度拖拽、音量/静音、播放进度记忆（续播）。
• SMTC：开启后在系统媒体控制面板（Windows 锁屏/音量）显示歌曲信息并支持控制。
• 歌词：LRC 毫秒级解析、翻译合并、当前句居中标蓝加粗、其他灰色、点击跳转、KTV 逐字渐变高亮（有 YRC 逐字轴的歌曲；无逐字数据的歌曲整句点亮，不做仿逐字动画）、翻译分两行显示、手动偏移校准（±0.25s）。

六、评论区

• 单曲下方评论区：热门评论 + 全部评论，10 条/页分页，展示昵称、VIP/SVIP/音乐包标识、IP 归属地、点赞数、回复引用；可在设置中关闭。
• 发表/回复评论：扫码登录个人网易云账号后可用（140 字以内、支持回复指定评论）；仅限个人账号——服务器全局账号在发评论/收藏等个人身份操作上零权限零入口（提交全局账号 Cookie 会被拒绝并记录审计日志）。

七、设置中心（⚙️）

• 外观：浅色 / 深色 / 跟随系统 + 8 种主题色（默认蓝/红/橙/火山/青/绿/粉/紫罗兰）。
• 下载配置：文件命名格式、写入元数据开关、写入字段多选、ZIP 打包（各自带「保存」按钮）。
• 批量下载配置：写入元数据、ZIP 打包（保存按钮）。
• 歌词：LRC/SRT 格式、翻译分两行、KTV 逐字模式（保存按钮）。
• 播放：播放进度记忆。
• 其他配置：SMTC、显示评论区、接口请求统计（/api/topen 实时统计弹窗，10 秒自动刷新）、隐私与协议（Cookie 偏好管理）。

八、隐私与协议

• 新用户首次打开网站自动弹出「隐私与协议设置」：需勾选同意《用户协议》《隐私政策》后才能使用。
• Cookie 类型：
  • 必要 Cookie（始终启用）：CDN 性能监控等。
  • 功能性 Cookie（可关闭）：解析与下载服务、播放进度记忆、历史记录；关闭后无法解析与下载音乐。
• 可随时在「设置 → 隐私与协议」修改偏好或撤回同意。
• 所有偏好、历史记录、个人登录 Cookie 均只存储在用户本地浏览器（localStorage），不上传服务器。

九、管理员功能

• 全局账号状态与 VIP 类型、生成登录二维码（自动保存 Cookie）、删除 Cookie（重新扫码）。
• 用户 IP 解析/下载记录：记录每位访问者的 解析/下载 操作（样式：解析|下载 - IP - 歌曲名 - 时间），支持分页查看。

十、接口请求统计

• 后端实时统计各真实业务接口的请求数（仅统计搜索/解析/歌单/专辑/榜单/歌手/评论/下载等业务接口，页面刷新与内部探测不计入）。
• 面板展示：总请求数、不同端点数、最高端点请求数，以及按请求数倒序的端点明细（名称、路径、次数、百分比、最近活动），每 10 秒自动刷新。

十一、接口 API（速览）

接口	方法	说明
/search	POST	搜索（type: 1歌曲/10专辑/100歌手/1000歌单）
/song	POST	单曲解析（url/level/type/account/user_cookie）
/playlist /album	POST	歌单 / 专辑解析
/toplist	POST	官方榜单列表
/artist_songs	POST	歌手信息与热门歌曲
/comments	POST	歌曲评论（id/limit/offset）
/podcast/parse	POST	播客解析（电台/单集链接、短链或 ID；单集附带音频直链）
/podcast/programs	POST	播客单集列表（radio_id/limit/offset/asc 分页）
/podcast/search	POST	播客搜索（keyword/type=all,radio,voice）
/podcast/hot	POST	热门播客与分类列表（cate_id/limit/offset）
/podcast/download	POST	播客单集服务器下载（id/quality/zip，返回 task_id）
/podcast/download/batch_zip	POST	整台播客打包 ZIP（radio_id 或 ids/limit/quality）
/download	POST	下载（含 filename_format/write_meta/meta_fields/lyric_format/zip）
/download/batch_zip	POST	批量下载并打包 ZIP
/account/vip	POST	当前解析账号 VIP 类型与实测可解析音质
/api/topen	GET/POST	接口请求统计
/auth/*	POST	站点账号系统：注册 / 登录 / 退出 / 邮箱验证码 / 免费体验 / 卡密兑换 / 会话查询；/auth/admin/* 为后台管理接口
/admin/*	POST	管理员接口（两步验证登录后的会话鉴权）：二维码登录、Cookie 管理、操作记录
/global/playlists	GET/POST	全局账号歌单列表（收藏歌单 + 「我喜欢的音乐」）
/global/playlist	GET/POST	全局账号歌单详情（使用全局 Cookie，支持私有歌单）
/api/playlist/play	GET/POST	歌单播放 API：返回歌单信息 + 每首歌可播放直链（id/level/limit）；需 &key= 密钥（第 78 条起强制，管理后台「播放API密钥」获取/刷新）
/user/*	POST	个人账号接口（Cookie 由浏览器传入 user_cookie）
/health	GET	健康检查

十二、收藏功能

• 登录个人账号后，歌单/专辑解析结果头部显示「♡ 收藏」按钮，个人歌单列表显示「取消收藏」。
• 使用网易云官方收藏接口真实收藏到个人账号：
  • 歌单：POST /api/playlist/subscribe（id + t=1 收藏 / t=2 取消）
  • 专辑：POST /api/album/sub（id + t=1 收藏 / t=2 取消）
• 收藏成功后个人歌单界面自动刷新，新收藏的歌单立即出现在列表。
• ⚠️ 已知限制：网易云对「歌单订阅」接口有风控（返回 操作过于频繁，请稍后再试）， 数据中心/云服务器 IP 及操作频繁的账号更容易被拦（本工具在阿里云 IP 上验证时即被拦截， 而专辑收藏不受影响）。若遇到该提示，请稍后重试或更换网络环境（家庭宽带等非数据中心 IP）后使用。

十三、账号与权限系统（站点登录 · 按次计费）

• 强制登录：所有解析 / 搜索 / 下载接口需登录后使用，未登录返回 401。
• 按次计费（仅下载）：解析、搜索、在线试听、榜单、播客浏览全部免费；下载消耗次数——单曲下载 1 次，批量打包按歌曲数量扣减（如 100 首歌单打包 = 100 次）；请求失败不扣费；管理员不限次数。
• 未登录：点击解析/下载时弹窗提示「解析功能需要登录后才能使用」并打开登录框（提示 5 秒内不重复弹出）。
• 次数不足预检：歌单 / 专辑 / 歌手 / 个人歌单 / 播客打包下载前自动检查剩余次数，不足时弹出选择框——「仅下载前 N 首（集）」或「取消下载」。
• 次数用尽：弹窗提示「下载次数已用尽」，支持一键跳转个人中心充值。
• 注册：邮箱验证码验证（需管理员先在后台配置 SMTP）；注册成功直接赠送 3 次下载次数，无需领取；注册前须阅读并同意《用户协议》与《隐私政策》（16 秒强制阅读计时）。
• 登录：支持用户名+密码或注册邮箱+密码两种方式；自动识别角色——管理员登录跳转后台管理界面，普通用户跳转个人中心；会话有效期 7 天（活跃自动滚动续期，连续 7 天不访问才过期）。
• 找回密码：登录弹窗「忘记密码？」——通过注册邮箱验证码自助重置（10 分钟有效验证码，重置后全设备下线）；管理员账号不走自助找回。
• 顶号机制：同一账号在新设备登录后，旧设备会话立即失效（强制下线），防止一号多卖。
• 防倒卖封禁：每次登录记录 IP 归属省份，24 小时内出现 ≥3 个不同省份自动封禁；管理员可手动封禁（填写原因展示给用户）与解封；被封账号登录即提示封禁原因。
• 初始管理员：新装实例在服务首次启动时于控制台随机打印初始密码（账号 admin，请立即登录后修改）；新版已升级为两步验证登录：正确的用户名+密码 → 输入绑定邮箱 → 邮箱收取验证码 → 验证通过才可进入后台。
• 导航栏：右上角登录 / 注册按钮，登录后显示用户名首字母头像与剩余次数，点击进入个人中心或后台。
• 次数卡密：管理员后台生成次数卡（3 / 10 / 50 / 100 / 500 / 2000 次或自定义次数，支持前缀 / 备注 / 有效期），用户在个人中心兑换；管理员可对未使用的卡密禁用 / 启用 / 删除（带分页管理），已使用的卡密永久保留兑换凭证。

音频接口多重防护

• 所有接口返回的音频地址替换为服务器签名代理地址，真实 CDN 直链不出现在任何响应中。
• 代理地址采用 HMAC-SHA256 签名 + 36 分钟时效 + 随机 nonce，伪造 / 过期即失效。
• 音频流经服务器中转（支持进度拖动），浏览器不与 CDN 直连；已移除「复制 JSON」「复制直链」入口。

个人中心（普通用户）

• 剩余次数查看、退出登录、卡密充值、公告查看、系统版本与更新日志。

后台管理（管理员）

模块	功能
用户管理	添加用户 / 删除 / 修改剩余次数 / 重置密码 / 禁用启用 / 封禁·解封（显示注册 IP、设备与最近登录省份）/ 查看用户网易云 Cookie，管理员账号受保护不可自锁
全局 Cookie	全局网易云账号扫码登录、删除 Cookie（自前端迁移至后台）
邮箱注册管理	SMTP 服务器 / 端口（默认 587）/ 发件邮箱 / 授权码配置与发信测试
日志管理	成功 / 失败日志 10 条每页分页查看，支持清除；记录封禁、解封、自动封禁、顶号下线、扣费明细等关键事件（不记录普通登录；注册成功因防刷号审计会记录一条）
卡密生成	次数卡密生成（预设 + 自定义次数、前缀、备注、有效期）与使用状态查看
公告设置	公告编辑与弹出策略（每次登录弹出 / 仅一次 / 不弹出）
数据库管理	定时自动备份、备份文件下载、上传与恢复
退出登录 / 返回解析	快速切换后台与解析页

• 全局账号歌单菜单仅管理员登录后可见，普通用户不可查看管理员歌单内容。

十四、Docker 部署要点

• 端口映射 5001:5000（对外 5001；勿用 6000，浏览器会拦截 ERR_UNSAFE_PORT）。
• 持久卷：cookie.txt（全局账号）、user_cookie.txt（兼容）、downloads/（下载文件）、data/（站点数据库与备份）。
• 镜像内已配置阿里云 apk/pip 源加速，并安装 tzdata（TZ=Asia/Shanghai 生效）。
• 详细步骤见 部署文档.md。