hhhge/NeteaseUrl
Archived
1
0 Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity
This repository has been archived on 2026-10-02. You can view files and clone it. You cannot open issues or pull requests or push a commit.
Files
8446166120092d55d6dea254adf8f01736316423
NeteaseUrl/功能介绍.md
T
snowy-yang 8446166120 refactor!: uv 管理环境 + 彻底删除技术债（Flask 与 requests 全部移除） 
## uv 环境管理
- pyproject.toml 声明 dependencies + [dependency-groups].dev，uv.lock 精确锁定
- 删除 requirements.txt / requirements-fastapi.txt / requirements-dev.txt
- .python-version = 3.12；Dockerfile 改用 uv sync --frozen（可复现构建）
- 新增 jinja2（首页渲染）

## 删除 Flask 技术债
- 从 main.py 用 ast 精确剥离 56 个 Flask 节点（路由/中间件/错误处理/启动），
  框架无关的服务层落为 services/runtime.py（MusicAPIService、下载/打包 worker、
  任务监控、缓存清扫），零 Flask 依赖
- 删除 main.py（4527 行）与 auth_routes.py（1050 行）
- auth_system.py 移除会话/请求上下文层（login_session/current_user/login_required/
  admin_required/_client_ip 等），保留数据与业务层
- 新增 core/net.py（IP 解析）、web/auth_state.py（登录锁定/2FA 票据/发码限流）
- FastAPI 侧改直接依赖 services.runtime，不再 import main
- web/app.py 去掉 Flask fallback；入口默认根路径模式（API_PREFIX 可选）

## 删除 requests 技术债
- 新增 core/sync_http.py：requests 风格的同步门面（底层 aiohttp 连接池，
  流式读取经有界队列背压），含 Session/headers/(connect,read) 元组超时兼容
- core/utils、auth_system、podcast_api、music_downloader、services 全部切换
- 实测真实下载 5.2MB 音频完整成功

## 质量门禁归零
- ruff：0 错误（B904 全部修复，不再忽略）
- pyright：0 错误（类型收窄修复）
- pytest：140/140（含 golden 契约回归、root 模式 66 项路径覆盖）
- 真实 uvicorn 启动：/health、/、/static、受保护端鉴权全部正确

新增 tests/golden/responses.json：删除 Flask 前捕获的 32 例响应快照，
FastAPI 逐字段复现——删除巨石后行为回归仍有硬证据。
2026-09-26 11:10:17 +08:00

15 KiB
Raw Blame History

云村小助手 · 功能介绍

一个基于 FastAPI + 原生前端的云村小助手。 支持搜索、单曲/歌单/专辑/歌手解析、官方榜单、个人歌单、多账号体系、批量下载、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。
Reference in new issue View Git Blame Copy Permalink