在线听书主题（Tingshu）使用说明

版本：1.0.01 ｜ 作者：kuakeba.cn ｜ 宿主：社区（community）

橙红听书门户主题：专辑/章节/主播展示、音频播放器、焦点轮播、排行榜与会员收藏，适合有声书、播客、评书相声、音频节目类内容站。

⚠️ 重要：首次安装会清空社区数据

首次安装 / 卸载后重装本主题时，会自动清空以下社区数据并重置自增 ID：

• 分类（community_category）
• 专辑/文章（community_topic）
• 回复（community_reply）
• 标签（communitytag、communitytopic_tag）

清空后会写入 10 个默认听书分类，并为每个分类生成 10 篇示例专辑（共 100 篇，含自动生成的 PNG 封面）。

• 升级（更新）主题不会清空数据。
• 需要强制重清时：后台「应用中心 → 在线听书主题 → 卸载」→ 再「安装」。
• 操作前请务必备份数据库。

一、安装与启用

1. 将 themes/Tingshu 目录整体上传到项目 themes/ 下。
2. 后台「应用中心 → 模板主题 → 在线听书主题 → 安装」，然后「启用」。
3. 主题依赖「社区」（community）宿主插件，需先安装并启用。

同一站点（host）同一时间只允许启用一个主题；切换主题会自动停用其它同 host 主题。

主题配置入口

启用后，后台左侧「插件列表」下会出现「听书主题设置」菜单，配置页面地址：

/admin/community_tingshu/config

主题文件说明

主题启用/更新时，静态资源会自动同步到 public/static/Tingshu/，前台实际加载的是该目录文件。

二、页面结构

页脚菜单页面与 RSS

页脚固定菜单已全部指向社区单页（/page/<slug>），首次安装会写入以下 10 个页面，可在后台「社区 → 单页」中编辑内容：

• 原「用户体验提升计划」菜单已改为 RSS，指向 /rss.xml。
• /rss.xml 输出最新 30 条专辑，标题、链接、摘要、发布时间及分类均由主题 RSS 控制器生成。
• 单页别名只能使用字母、数字、-、_，且不能包含路由分隔符；如需新增页面请保持 slug 简短。

详情页广告位

专辑详情页右栏“热门有声小说排行”下方预留广告位，已适配 ads 广告插件：

• 启用 ads 插件并配置包含「右侧栏 / ad_right」的广告套餐后，自动显示广告或自助购买卡片。
• 没有广告/套餐时显示“广告位招租”占位卡片，不会整块消失。
• 广告购买弹窗、支付流程依赖插件资源，主题已统一注入 plugin_assets() 并加载 jQuery。

登录与互动

• 顶部登录按钮打开主题原生登录/注册弹窗，支持账号密码、邮箱/短信验证码、图形验证码。
• 未登录时收藏、解锁章节等操作会先弹出登录框，并保留当前页面回跳。
• 登录后头像菜单包含会员中心、我的收藏、听书记录、后台管理与退出登录。

页脚友情链接与自助申请

页脚原“网站地图 / 关于我们”链接行已改为友情链接区块：

• 优先读取 friends 插件中已通过的友链，并读取主题后台「页脚 → 友链」的手动配置（每行 名称|URL）。
• 启用并配置 friends 插件的「开放自助申请」后，友链行末尾显示「申请友链」按钮。
• 游客点击申请会先打开主题登录弹窗；登录后由 friends 插件提交申请、后台审核。
• 未启用 friends 插件时，仅展示主题后台手动配置的友链，不显示申请按钮。

启用方式：后台「应用中心」安装并启用「友情链接（friends）」插件 → 打开「开放自助申请」→ 保存。若需要游客直接申请，可关闭「申请需登录」。

三、主题配置项

后台「听书主题设置」按分组维护：

页脚菜单格式

页脚菜单栏目 每栏第一行为栏目名，下面每行一个菜单：

关于我们|@page:about
联系方式|@page:contact
网站地图|/sitemap.xml

• 栏目之间用空行分隔。
• @page:别名 指向社区单页；也可填写站内相对路径或完整网址。

自定义顶部菜单

支持相对路径、完整网址或 @page:别名，留空时使用主题默认导航。

四、数据采集与示例内容

后台「听书主题设置 → 数据采集」提供：

• 手动采集：按目标分类生成本地示例专辑。
• 重建种子：清空专辑/标签后重新生成默认分类与示例专辑。
• 查看日志：查看最近采集日志。
• 定时采集：配置「启用采集」与「定时密钥」后，在宝塔「计划任务 → Shell 脚本」中添加（建议每 1 小时）：

/www/server/php/82/bin/php /www/wwwroot/你的站点/themes/Tingshu/bin/cron.php

后台设置页会直接给出当前站点 PHP 的完整路径命令，避免宝塔计划任务默认调用低版本 PHP。脚本会自动识别 PHP 8 并切换执行，读取后台的「启用采集 / 目标分类 / 每分类条数」配置。

如需通过 HTTP 触发，可改用：

curl -s "https://你的域名/tingshu-cron?token=你的定时密钥"

建议每 1 小时执行一次，并确保「目标分类」中的关键词能匹配到本地分类名称。

当前采集器按本地分类生成示例专辑数据，用于快速搭建听书站内容结构；「采集源」为预留配置项，不参与远端站点抓取。

站点地图

主题注册了 /sitemap.xml 路由，启用后可直接访问。

五、更新与部署

1. 覆盖上传 themes/Tingshu 到服务器。
2. 后台「应用中心 → 在线听书主题 → 更新」。
3. 若直接覆盖、未走后台更新，请手动处理缓存与静态资源：

  - 删除 runtime/theme_front/Tingshu/

  - 清空 runtime/temp/、runtime/cache/

  - 同步 themes/Tingshu/static/ 到 public/static/Tingshu/

  - 重启 PHP（清理 OPcache）

六、常见问题

1. 前台样式没有更新？

检查 public/static/Tingshu/theme.css 是否与 themes/Tingshu/static/theme.css 一致；不一致时重新同步，并删除 runtime/theme_front/Tingshu/。

2. 浏览器报 ReferenceError: $ is not defined？

签到等插件脚本依赖 jQuery。主题已在 plugin_assets() 之前加载 /static/admin/js/jquery.min.js；若仍报错，清理模板缓存并确认该文件可正常访问。

3. 详情页看不到广告位 / 无法自助购买？

• 确认 ads 广告插件已安装并启用。
• 在后台「广告位」中创建套餐，投放位置需包含「右侧栏 / ad_right」。
• 套餐配置完成后，详情页占位卡片会自动变为广告或“购买广告位”入口。

4. 安装后原有文章不见了？

首次安装会清空分类、专辑、回复、标签并重建种子数据，这是主题设计行为；请从安装前备份恢复。

5. /sitemap.xml 或 /tingshu-cron 访问 404？

主题启用时会自动生成后台路由胶水文件 plugins/Tingshu/routes.php；若缺失，重新启用一次主题即可重新写入。

版本历史