Archived
snowy-yang
8446166120
## 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 逐字段复现——删除巨石后行为回归仍有硬证据。
171 lines
15 KiB
Markdown
171 lines
15 KiB
Markdown
# 云村小助手 · 功能介绍
|
||
|
||
> 一个基于 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`。
|