顺雅 Shunya v1.6.9

后台架构

• 页面路由从单文件改为目录式入口 admin/pages/<action>/index.php，零 nginx 配置依赖；新增统一的判定链与引导（front.php / boot.php）
• 下线在线歌厅（房间）功能：移除 pusher 相关代码与后台 service 层

密钥与歌单

• 密钥删除改为级联清理：连带删除名下歌单与歌曲、解除封面引用、解绑域名授权；删除前归属校验前置，确认框如实展示将删除的数据量
• 歌单配置支持导出 / 一键导入：JSON 仅含歌单数据（不含任何密钥信息），导出文件名带密钥名与时间戳
• 歌单同步与编辑保存时自动删除上游已下架的歌曲（两轮确认机制，防误删）

域名与播放器

• 域名授权 / 自动添加检测域名的开关改为按用户独立存储，运行时按密钥主人判定；「自动添加」默认关闭；超管可查看全站用户开关总览
• 修复安装向导在深层路径下的连环 302 重定向（改为根绝对路径，一次到位）
• 修复封面本地化统计范围：超管可见全部用户歌单（带归属标注）并可代为预热，批量入口补归属校验

配置与安装

• config.php 收敛为仅数据库连接段，站点 / 后台 / 接口配置及签名密钥的权威值入库，由统一合并入口读取
• 安装器按新配置结构生成；修复 SQL 模板中极验配置表缺失主键的问题（新装会导致保存失败）
• 全新安装不再携带历史遗留的死字段

顺雅 Shunya v1.6.5

本版聚焦播放器数据缓存与封面本地化两件大事，并修掉一批后台交互问题。

• Redis 播放器数据缓存（新增）：缓存上游解析结果（播放地址 / 歌词 / 封面）、歌单配置 JSON、
  播放器状态（按 IP + 设备校验）。装了 phpredis 走原生、没装走纯 PHP RESP，两条实现契约一致；
  手动开关优先——关掉即不使用；开启时按连通性自动生效 / 自动停用，服务端恢复后自动继续；
  失败一律快速跳过缓存（fail-open），且不会把 PHP 警告写进接口响应
• 封面本地化（新增）：封面按内容寻址存到对象存储，同一张图跨歌单只存一份；删除歌单先释放索引，
  无人使用的图片进回收池、过保留期才真正删除；支持分批预热与旧数据迁移；后台卡片会列出全部歌单
  （本地还没同步到歌曲的显示"本地还没有歌"），预热按实时列表进行
• 播放器：歌词、播放器与提示层重构，沉浸模式，播放状态云同步
• 后台：设置页拆分与无刷新提交；表单提交标记改为隐藏字段，修掉"点保存没反应、配置像回弹"；
  登录态/校验失效时给出明确提示；封面卡片与歌单管理页范围保持一致
• 数据层：增量同步增加结构指纹短路，MySQL / SQLite 双驱动的结构同步与索引、列修补

顺雅 Shunya v1.6.2

域名授权

• 授权行可以绑定到具体密钥：同一账号有多条密钥时，可以让某一条密钥单独授权某个站点，其余密钥不受影响；不绑定（不限）时该账号所有密钥共用这一行。
• 唯一索引由「用户 + 域名」改为「用户 + 密钥 + 域名」，install/sql/mysql.sql 里附了迁移指令（已有安装升级时按注释调整索引即可，老数据保持「不限」不受影响）。
• 客户端取值：绑定当前密钥的行优先，「不限」的行兜底；自动登记的行会记下触发它的那条密钥。
• 后台编辑收紧：按 id 保存时若该行不存在或不属于自己，直接提示「域名不存在，或没有权限修改」，不再退化成按域名新增一行；指定密钥时校验归属，不能指定别人的密钥。

底部让出量（PC / 移动端分开）

• 域名配置新增 pc_auto / pc_lyrics / pc_player 与 mo_auto / mo_lyrics / mo_player：PC 与移动端各有独立的自动开关、歌词修正与播放器修正，未设置（NULL）时回落旧的 auto / lyrics_bottom / player_bottom，升级后行为与升级前一致；下发的配置同时给出新旧字段，1.6.x 及更早的客户端照旧可用。
• 后台域名页拆成 PC / 移动端两块：每端一个自动开关 + 歌词修正 + 播放器修正（播放器留空表示跟随同端的歌词）；新增「指定密钥」下拉、每端「最近探测」与「填入歌词修正」按钮；表格与卡片两种布局同步改版。
• 探测判定放宽：扫描深度 2 → 4 层，并补一层定向选择器（nav / tablist / tabbar / bottom-nav / dock / toolbar）；底栏高度范围 40–96px → 28–120px；宽度要求 60% → 55%；可点子项 3 → 2，并接受「≥3 个等宽子元素」的纯 div 标签栏；允许离底 ≤24px 的悬浮胶囊；让出值按「视口底部到栏上沿」计算，含离底间隙。
• 客户端每 60 秒（值变化时立即）把实测底栏高度上报一次，新增 inset-report 接口；上报只更新已存在的行，不会凭空多出域名。「最近探测」显示在域名页，可一键填入修正量。
• 播放器本体也吃这个让出量：没有后台默认值时的初始位置、底部百分比定位的越界回退、悬浮播放器的拖拽吸附都会把底栏高度算进去；底栏高度变化（探测到 / 改了修正量 / 转屏 / 单页应用换页）时播放器会重新摆位。
• 宿主页面结构变化的响应更灵敏：探测的 MutationObserver 由 childList 改为 childList + subtree。

移动端沉浸式歌单弹窗

• 修复移动端沉浸式歌单弹窗被抬高、下方露出一条宿主底栏的问题：沉浸层是全屏遮罩，宿主底栏在它下面本来就看不见 —— 弹窗改为贴屏幕底边，底部内边距改用 iOS 安全区 env(safe-area-inset-bottom)。
• PC（≥769px）不受影响，仍是锚定在触发按钮下方的小下拉。

其他

• 删除已被 install/sql/ 取代的结构说明文档 install/schema.md。

顺雅 Shunya v1.6.0

播放器：宿主底部避让

• 新增 modules/core/inset.js 探测宿主固定在底部的导航栏 / 工具条（移动端底部 tab 栏最常见），播放器与歌词框据此把自己抬到它上方，不再压在宿主导航上
• 探测范围收敛到 body 下两层，判定要求真贴底、高度 40~96px、宽度 ≥60% 视口、含 ≥3 个可点子项，并排除播放器自身——悬浮球、cookie 横幅、吸底广告不再被当成底栏
• 差值超过 8px 且连续两次采样一致才生效（迟滞）；首屏 / 窗口变化 / 转屏 / 换页框架 / DOM 变化都会重测，另有 5 秒兜底复测
• 歌词框、玫瑰玻璃面板、歌单浮层统一按同一份底部占用避让；控制台可按域名下发覆盖值与修正量，关掉「自动探测」后完全用固定值，零抖动

播放器：失败提示

• 所有失败原因统一提示，各说各话：缺少 API Key、密钥无效、密钥已停用、请求太频繁、连不上服务器、服务器返回异常、域名未授权、密钥与域名不匹配、后台没有歌单、歌单是空的、歌单加载失败、播放器资源加载失败
• 同一种提示不会叠加，最多同时三条，点一下即可关掉；启动已经失败时不再补一条「后台还没有歌单」把真正原因挤到后面

域名授权

• 新增 mapi_domains 表与后台「域名」页：域名增删改，每条可单独设置「已授权」「自动探测」、歌词框与播放器的底部修正量、备注
• 新增两个全局开关：「域名授权」（关闭时一律放行，不影响任何现有站点）与「自动添加检测到的域名」（打开时主机名第一次加载播放器就自动登记并放行；只补新行，不会复活手动停用的行）
• 密钥可绑定授权域名：创建密钥时填了域名，这条密钥就只能在那个主机名使用，并同时加进「域名」页设为已授权；绑定了域名的密钥在别的站会被直接拦住并提示原因
• 主机名精确匹配，不做 www 或子域合并；宿主域名从 Referer / Origin 取，取不到时按直连处理不拦
• 升级后访问后台或安装页会自动补齐新表与字段，不需要手动执行 SQL

后台

• 设置页拆分为「站点 / 邮件 / 安全 / 接口 / 存储」五个子页，侧栏分组可折叠并记住展开状态
• 新建密钥改为弹窗：密钥名称（必填，最多 32 字）与授权域名，创建中按钮置灰防重复提交，Esc 或点背板关闭；密钥列表直接显示名称与绑定域名
• 提交表单与切换开关不再整页刷新：确认框、开关、注册通行密钥、清空壁纸全部改为就地更新，页内的测试播放器不会再被刷掉

修复

• MySQL 驱动没有回写自增 ID 与受影响行数，新建记录后拿到的 ID 恒为 0
• 接口失败响应缺少原因码，播放器只能笼统提示「密钥无效」
• 软切换页面后开关第二次点击失效（监听绑在会被替换掉的节点上）

安全

• 在线用户接口补管理员门槛；前端错误上报接口补限流（30 次/分钟）、长度与换行清洗，并改写服务器错误日志，不再落到站内可直接下载的文件
• 「仅管理员可见」的页面名单收敛到一处，避免以后新增页面时漏配
• 移除没有界面入口的调试开关接口与对应脚本

清理

• 删除空占位文件 admin/lib/s3_new.php 与草稿 admin/pages/playlist-detail.php.fixed

顺雅 Shunya v1.5.0

播放器架构

• 拆分为引擎（modules/core）与皮肤（modules/<皮肤>）两层，全站引擎只有一份，皮肤只负责界面与交互
• 皮肤由 skin.json 清单自述，modules/registry.php 统一装载；后台皮肤选择器读的是同一份清单
• 皮肤契约：loadCSS / createWidget / getHTML / _css

新增皮肤：玫瑰玻璃（rose）

• 常驻侧边抽屉卡片，可收起为贴边把柄；停靠边跟随后台设置
• 封面环形播放进度与播放时顺时针旋转（暂停冻结当前角度，不回正）
• 音量按钮呼出滑杆；音量增强 1x / 2x / 3x（2x 绿、3x 黄）
• 歌曲列表改为居中弹窗，从所点击的列表按钮位置放大展开
• 移动端为底部抽屉，可上下拖动并吸附到半屏 / 全屏
• 播放器区域内禁用右键菜单、文本选中与图片拖拽（不影响宿主页面）

皮肤与初始位置

• 新增 mapi_users.player_skin_cfg，按皮肤分别保存各自的初始位置（停靠边 + 垂直百分比）
• 后台音乐配置页把「初始位置」并入每张皮肤卡片，各皮肤互不影响；接口按当前皮肤返回对应位置

嵌入方式

• 统一为 <script src="https://你的域名/api.php?key=你的密钥" defer></script>，密钥改走查询参数
• 旧入口 modules/api.php 与「密钥写在标签属性上」的旧写法不再支持

修复

• 换页框架（Swup/Pjax 等）下播放器重复加载、声音重叠
• 歌词跑马灯在移动端反复抽搐：改为仅在歌词换行时重排，并以固定速度匀速滚动
• 切换皮肤时偶发的停靠方向判反、整屉（含把柄）飞出屏幕导致播放器无法打开
• 后台登录后皮肤设置未恢复到会话，导致随后保存时覆盖数据库中的配置
• 后台皮肤卡片改用事件委托绑定，修复保存或换页后无法选择皮肤
• 歌词框换皮后样式被内核重写而失效，改为随 style 变化自动补回

后台

• 音乐配置页新增皮肤选择，每张皮肤卡片各自带初始位置控件
• 人员与设置仅对管理员可见，普通用户只看到概览 / 密钥 / 配置；顶部、侧边栏、底部导航共用同一份过滤

清理

• 移除旧版单体皮肤 modules/chiropractic/、路由旧入口 router/embed.js、旧转发壳 modules/api.php

顺雅 Shunya v1.4.2

播放器

• 同一页面可放多个播放器实例：各自的歌曲记忆与位置记忆完全独立，不再互相覆盖
• 初始位置（后台「靠左/靠右 + 垂直百分比」）始终生效；访客拖动过的位置会保留，后台改动后按新设置归位
• 位置增加视口夹取：修复竖直位置每次加载漂移、百分比过小时播放器被顶出屏幕的问题
• 沉浸式歌词在窗口尺寸变化后即时重算居中

歌单与数据

• 远程歌单改为本地快照：新增上游访问与快照落库，歌曲身份改用稳定 song_id
• 后台支持「从上游同步」：只追加新歌、保留本地已排好的顺序，上游已下架的歌曲标记为已下架并在播放器跳过

后台

• 歌单详情页新增歌曲排序（置顶 / 上移 / 下移），只写真正变化的行
• 歌单排序改为事务执行并合并服务端清单，避免漏项与并发错乱
• 歌单详情页的数据处理抽为独立媒介程序
• 导航按角色过滤：普通用户不再看到「人员」「设置」入口（顶部、侧边栏、底部导航统一生效）

结构同步与安装升级

• install/sql/mysql.sql 成为唯一结构来源，新增 DDL 解析（表 / 列 / 索引 / 主键）
• 全新安装与每次访问的增量共用同一套同步：缺表建表、缺列补列、缺索引补索引，并支持索引定义漂移自动重建
• 新增声明式结构变更指令：@sync、@sync-keep-extra、@modify、@drop-column、@drop-index、@drop-table
• 补齐历史缺失索引；新增 admin_theme、mapi_songs.missing 字段

顺雅 Shunya v1.4.0

本次将单体播放器拆分为路由式模块化架构，嵌入入口由 /embed.js 迁移到 modules/api.php。

播放器架构

• 新增 modules/api.php 作为 JavaScript 路由分发器，按 route 参数输出对应的播放器脚本，两种路由都开放跨域并禁用缓存
• route=router 输出模块化播放器启动脚本；route=chiropractic 输出旧版单文件播放器的包装脚本
• 原 embed.js 拆分为 modules/router/ 下的 auth、widget、state、player、ui、drag、immersive、lyrics、theme 九个模块，由启动脚本按顺序加载
• 单个模块加载失败只跳过自身，不影响其余模块继续加载
• 旧版单文件播放器迁移为 modules/chiropractic/embed.js，功能保持不变

嵌入方式

• 嵌入入口由 /embed.js 变更为 /modules/api.php?route=router
• 原有 key、token、api、cdn-aplayer-css、cdn-aplayer-js 属性继续可用
• 仓库根目录不再提供 /embed.js，使用旧地址的页面需改用新入口
• 后台 relay 配置的 embed_js 同步更新，后台的复制嵌入代码与测试播放器均改用新入口

跨域嵌入

• assets/lib/widget.php 在嵌入地址为相对路径时补全为绝对 URL，修复第三方页面跨域嵌入时播放器脚本无法加载的问题
• 播放器脚本地址改用 json_encode 输出，避免地址中的特殊字符截断字符串
• 追加缓存版本参数时兼容地址中已存在的查询串

样式

• 移除 embed.css，播放器样式内联进 modules/router/widget.js 并注入 Shadow DOM，与宿主页面样式继续保持隔离

顺雅 Shunya v1.3.0

本次版本移除了账户激活与到期限制，后台页面改为自动签发播放器令牌。

账户与鉴权

• 移除账户激活与到期校验：接口鉴权、widget 配置下发与公告下发不再判断 mapi_users.expire_at，密钥状态正常即可使用
• 后台创建密钥不再要求账户处于有效期，密钥数量仍受 key_limit 配置约束
• 密钥页移除「账户未激活/已过期，现有密钥已被拦截」提示条，创建按钮仅按已用密钥数量判断
• 个人资料页移除账户有效期卡片
• 人员页用户列表移除「状态（正常/已过期）」标签，不再查询到期时间

数据库与安装

• mapi_users 表移除 expire_at 字段，MySQL 与 SQLite 建表语句同步调整
• 安装器创建管理员账号时不再写入固定到期时间
• install/lib/migrations.php 移除 expire_at 迁移项

后台

• 后台页面自动签发播放器令牌：header.php 取首个启用密钥签发 24 小时 JWT 并写入 mapi_token Cookie，内置播放器可直接取用
• 图标集新增 music、disc 两个图标

顺雅 Shunya v1.2.0

后台页面脚本加载

• 配置页与歌单详情页原本内嵌的 <script> 全部抽取为 admin/assets/pc/js/config.js、admin/assets/pc/js/playlist-detail.js，移动端同名文件内容保持一致
• 页面改为只输出数据容器 #config-data、#playlist-detail-data，其中的 csrf、歌单 ID、搜索 Token、接口参数与歌单信息由外置脚本读取，避免切换页面后脚本不再初始化

后台导航

• navigateTo() 增加导航进行中标志，防止重复触发
• 目标页面缺少 .wrap 结构或请求失败时保留当前页面并在控制台输出错误，不再整页跳转
• 导航过程中点击侧栏与底部导航链接不再重复发起请求

密钥与接口

• 歌单详情页密钥恢复为完整显示，并移除多余的复制按钮
• API 的 get-config 在 token 无法解出密钥时改用 token 本身作为密钥，修复未携带 key 参数时取不到配置
• API 限流检查移到配置与函数库加载之后，保证限流函数已可用
• 测试播放器已加载时只刷新按钮状态，不再重复初始化播放器

其他修复

• mapi_token Cookie 的设置由 widget.php 移到 index.php 的 HTML 输出之前，避免响应头已发送导致 Cookie 不生效
• widget.php 同步移除 Cookie 逻辑，入口守卫改为只要求 $RELAY
• helpers.php 移除已废弃的 curl_close() 调用
• 后台背景视频地址解析增加空值与异常处理，非法地址回退为背景图片

顺雅 Shunya v1.1.0

本次为问题修复版本，主要修复后台切换页面后页面脚本未重新加载的问题，并调整密钥的显示方式。

页面脚本加载

• 修复后台在导航切换与表单提交后，页面脚本不再重新加载的问题：页面脚本现在带有 page-js 标识，切换页面后按新页面的脚本地址重新加载，加载完成后才执行内联脚本与初始化逻辑
• 此前切换页面后只有内联脚本会被执行，外部页面脚本仍停留在上一个页面的状态，导致部分交互失效
• PC 端与移动端同步修复，切换页面后播放器按钮状态、调试面板展开与编辑器初始化均能正确完成

密钥显示与复制

• 密钥页、配置页与歌单详情页的密钥改为掩码显示，仅展示前 8 位与后 4 位
• 复制按钮改为从卡片上的 data-api-key 属性读取完整密钥，复制的仍是完整密钥
• 加载测试与嵌入代码按钮改用 data-key 传参，不再把完整密钥直接写进页面的内联脚本

界面样式

• key-card 与新建歌单相关样式从密钥页样式表迁入基础样式与设置页样式表，配置页与歌单详情页可共用同一套卡片样式
• 补充上述组件的深色主题样式
• 双列数据网格调整为三列，宽屏下信息展示更紧凑