chore: 基线快照 —— 纳入 git 版本控制（站点 v2.4.0 / Flask 单体）

在框架迁移与模块拆分前保存当前可运行状态：
- 后端：main.py/auth_routes.py/auth_system.py/music_api.py/music_downloader.py/podcast_api.py/qr_login.py
- 前端：templates/index.html + static/site_auth.js
- 部署：Dockerfile/docker-compose.yml/entrypoint.sh/requirements.txt
敏感数据(data/、cookie.txt)与内部文档(交接文档/新会话引导)按 .gitignore 排除。

功能介绍.md

@@ -0,0 +1,170 @@
+# 云村小助手 · 功能介绍
+
+> 一个基于 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`。