柠檬影视 lemonTV-Film
Android TV / 电视盒子 + Android 手机 双端 MacCMS 影视客户端
开源免费 · 双端同步维护 · 免部署可用 · NAS 自建支持
当前版本：TV v1.0.6（10006） · 手机 v1.0.1（10001）
各位恩山大佬好！
玩电视盒子、NAS 的朋友，应该都折腾过 苹果 CMS（MacCMS V10） —— 自己在 NAS 或软路由上搭一套影视站，局域网全家看，数据自己掌控。
但 MacCMS 的客户端一直是个痛点：通用播放器不认 MacCMS API；手机版界面小、焦点乱；TV 端很多第三方 App 又只认 m3u8 直链，遇到采集站的 /share/ 分享页 就播不了。
今天分享一款我在用的开源项目：柠檬影视（lemonTV-Film）。现已同时提供 TV 版 与 手机版，核心播放与数据层共用，双端体验一致。
两种用法，按需选择：
① 懒人方案：填一个公开 API 的 MacCMS 地址，不用自己部署，装好就能看
② 折腾方案：NAS / 宝塔 / Docker 自建 MacCMS，数据完全自己掌控
本帖结构：
① 双端版本介绍 + 本次更新亮点
② APP 功能详解（TV / 手机）
③ 界面预览
④ 零部署快速体验（推荐新手先看）
⑤ MacCMS 自建部署教程（NAS / 宝塔 / Docker）
⑥ API 开启与自检
⑦ APP 连接配置
⑧ 常见问题
★ 第一部分：版本信息与本次更新 ★
一、双端版本一览
当前版本：TV v1.0.6（10006） · 手机 v1.0.1（10001）
开源地址：https://github.com/jia070310/lemonTV-Film
下载地址：https://github.com/jia070310/lemonTV-Film/releases
Release 标签说明（重要）：
- TV 版 下载标签：v1.0.6，安装包：LomenTV-release-v1.0.6.apk
- 手机版 下载标签：mobile-v1.0.1，安装包：LomenMobile-release-v1.0.1.apk
- 双端 Release 标签分开，APP 内置更新检测会按平台自动匹配，不会串包
重要说明：
- APP 不内置任何影视源，需要连接 MacCMS 站点才能使用
- 可以 自建 MacCMS，也可以 接入他人已公开 API 的 MacCMS 站点
- 接入前提：目标站点必须 开启了视频采集 API，否则 APP 拉不到数据
- 本帖仅分享开源客户端及使用方法，不提供、不保证任何第三方站点内容
二、v1.0.6 / mobile-v1.0.1 更新亮点（重点）
★ 本次最大改进：第三方播放地址自动解析 ★
很多 MacCMS 采集站返回的播放地址 不是直链，而是类似：
- https://xxx.com/share/xxxxxxxx
这种 /share/ 分享页 或网页中转链接，普通播放器直接播会失败。
v1.0.6 / mobile-v1.0.1 已修复：
- 播放前 自动解析 `/share/` 分享页、网页中转链接 → 真实 m3u8 / mp4 直链
- 支持 MacCMS 站点 playerconfig.js 里配置的解析接口联动
- 解析过程中显示 「正在解析播放地址...」
- 解析失败给出 明确错误提示，支持重试
架构升级：
- TV 与手机 共用 shared + core 核心模块（播放、MacCMS 数据、收藏、历史等）
- 后续新功能可 双端同步维护，减少「TV 修了、手机没修」的情况
TV v1.0.5 → v1.0.6 体验改进（v1.0.6 已包含）：
- 收藏按服务器隔离：切换不同 MacCMS 服务器后，收藏列表与详情页收藏状态对应当前站点，互不影响
- 详情页布局优化：长标题/简介不再挤压「立即播放」「收藏」按钮；顶部留白更合理
- 选集翻页焦点保留：点「上一页」「下一页」后焦点留在分页按钮，连续翻页更方便
- 选集区固定 4 行高度：最后一页集数不足时不再上下跳动
手机 v1.0.0 → v1.0.1：
- 手机版首发（v1.0.0）：MacCMS 接入、推荐/筛选/播放/离线缓存、分享页解析
- v1.0.1：与 TV 统一接入 shared 核心层；解析失败提示与重试体验优化
★ 第二部分：双端功能详解 ★
三、TV 版核心功能（柠檬影视TV）
1. 专为 TV 遥控器优化
- 基于 Jetpack Compose for TV，大屏焦点导航流畅
- 方向键移动焦点，OK 确认，返回键逐级退出
- 播放页左右键快进快退，时长可在设置中调节（15 / 20 / 25 / 30 / 35 秒）
- 首页分类设置弹窗支持 长按 ↓ 快速跳到保存、长按 ↑ 快速回到列表顶部
- 播放中按 菜单键 可快速跳转到首页下方状态栏
2. 首页浏览
- 最近播放：自动记录进度，显示已看/剩余时长，一键续播
- 最新推荐：展示 MacCMS 推荐等级（level=9）内容
- 分类栏目：从 MacCMS 读取全部分类；首次连接默认展示几个顶级大类，界面清爽
- 筛选 / 搜索：筛选页可浏览全部一级分类；支持按类型、地区、年份筛选及搜索历史
- 我的收藏：首页右上角进入；按当前 MacCMS 服务器分别存储
- 分阶段加载：优先展示可见内容，后台补全封面，打开更快
- 卡片骨架加载：先显示卡片框架与片名，封面逐张淡入
3. 播放器（ExoPlayer / Media3）
- 第三方地址解析：分享页 → m3u8/mp4 直链，再播放
- 多线程 HLS 预缓存：m3u8 分片 6 线程并行下载，进度条下方显示预缓存状态
- 记忆续播：可开关；再次打开可选「继续播放」或「从头开始」
- 变速播放：0.25X ~ 2.0X 共 8 档倍速
- 选集切换：播放器内分页选集（每页 20 集），支持上一集 / 下一集
- 智能跳过片头片尾：按 整部剧集 统一配置，对该剧所有集数生效
- 进度条拖拽预览：拖动时显示目标时间点
- 多集播放结束自动跳转下一集
4. 设置中心
资源管理 — 配置 MacCMS 地址、保存、测试连通性
首页设置 — 自定义首页分类显示/排序、清除缓存
播放设置 — 快进快退时长、记忆续播开关、清空播放记录
关于应用 — GitHub 版本更新检测（设置图标红点提示）
四、手机版核心功能（柠檬影视 Mobile）
1. 移动端交互
- 底部导航：首页 / 推荐 / 我的
- 触控操作：滑动浏览、点击选集、手势友好
- 详情页秒开：复用列表缓存，进入详情立即展示海报与简介
2. 首页与浏览
- 最近播放：带进度条，一键续播
- 最新推荐：MacCMS level=9 推荐内容
- 分类栏目：懒加载 + 磁盘缓存，滚动流畅
- 筛选 Tab：多条件筛选，支持「更多」进入完整列表
- 推荐 Tab：快速浏览推荐等级 9 内容；无数据时提示「服务器无推荐影片」
- 搜索：支持搜索历史
3. 详情与离线
- 简介、选集、多播放源切换
- 一键收藏（按当前 MacCMS 服务器隔离，与 TV 逻辑一致）
- 离线缓存：详情页支持离线下载，「我的」中管理缓存
4. 播放器
- 与 TV 版 共用 shared 播放核心
- 第三方分享页自动解析 → m3u8 直链
- HLS 多线程预缓存、变速、选集、跳过片头片尾、记忆续播
- 退出播放页后立即停止后台播放
5. 我的
- 观看历史、收藏、离线下载、缓存管理
- 设置（MacCMS 地址、播放选项）
- 关于与 GitHub 在线更新（Release 标签 mobile-v1.0.x）
★ 第三部分：界面预览 ★
【图1 - TV 首页】
最近播放 + 最新推荐 + 分类栏目；底部导航：首页 / 筛选 / 设置。
【图2 - TV 播放器】
变速、选集、跳过片头片尾；HLS 预缓存状态；分享页解析提示。
【图3 - TV 详情页】
简介、选集、立即播放 / 收藏按钮；长标题布局正常。
【图4 - TV 资源管理】
配置 MacCMS 服务器地址，测试连通性。
【图5 - 手机首页】
底部导航：首页 / 推荐 / 我的；分类栏目懒加载。
【图6 - 手机详情页】
选集、收藏、离线缓存、立即播放。
【图7 - 手机播放器】
变速、选集、跳过片头片尾。
【图8 - 手机「我的」】
观看历史、收藏、离线下载、设置。
★ 第四部分：零部署快速体验 ★
不想自建？填地址就能用！
没有 NAS、不想折腾建站？ 可以直接接入 已公开视频 API 的 MacCMS 站点，3 步搞定，TV 和手机用法完全一样。
五、推荐：公开 API 的 MacCMS 站点
网上有一些 MacCMS 站点已开启 视频采集 API，填入 APP 即可使用，无需自己部署服务器。
示例站点（项目 README 推荐）：
github有推荐的，也有一个收集资源服务器的仓库，仓库地址在README.md介绍里，基本完全够用，自己查找的话，用谷歌搜索maccms采集服务器，有的公开API不符合，有的可以，这些需要在APP测试连通性
说明：以上为第三方公开站点，内容与稳定性由对方维护，与本 APP 及本帖作者无关。若失效可自行搜索其他「MacCMS 公开 API」站点替换。
可用站点需满足：
- 基于 MacCMS V10（或兼容其 API 协议）
- 已开启 视频 API（/api.php/provide/vod 可访问）
- 站点有影视数据（列表、详情、播放地址正常）
浏览器自测：
- https://域名/api.php/provide/vod/?ac=list&pg=1&pagesize=5
正常应返回 JSON/XML，且 code=1，list 中有视频条目。
六、免部署 3 步上手（TV / 手机通用）
第 1 步：下载安装
- TV 版：v1.0.6 Release → 下载 LomenTV-release-v1.0.6.apk
- 手机版：mobile-v1.0.1 Release → 下载 LomenMobile-release-v1.0.1.apk
TV 可用 U 盘 / ADB / 当贝 / 沙发管家等方式安装；手机直接安装 APK 即可。
第 2 步：填入公开站点地址
- 打开 APP → 设置 → 资源管理（手机版在「我的 → 设置」）
- 服务器地址 填写站点根地址，例如：
- 点击 保存配置 → 测试连通性
- 状态显示 已连接，并出现分类数量、MacCMS 版本等信息
地址填写规则：
正确 ✓ https://地址
正确 ✓ http://192.168.0.16:7963
错误 ✗ https://地址/api.php
错误 ✗ https://地址/admin.php
第 3 步：返回首页，直接看
连接成功后返回首页，会自动加载最新推荐、分类栏目等内容。想自定义首页显示哪些分类 → 设置 → 首页设置 → 首页分类设置。
七、免部署 vs 自建，怎么选？
免部署（公开 API 站点）
难度：★ 极低，填地址即用
数据掌控：依赖第三方站点
适合人群：想快速体验、不想折腾
自建（NAS / 宝塔 / Docker）
难度：★★★ 需部署 MacCMS + 开 API
数据掌控：完全自己掌控
局域网速度：通常更快
适合人群：NAS 玩家、长期自用
建议： 先按 免部署方案 体验 APP；满意后再考虑 NAS 自建。
★ 第五部分：MacCMS 自建部署教程 ★
进阶玩家 · NAS / 宝塔 / Docker
柠檬影视通过 MacCMS 的 视频采集 API（api.php/provide/vod）拉取分类、列表、详情与播放地址。
部署好 MacCMS + 开启视频 API = APP 就能用了。 TV 与手机配置方式相同。
八、环境要求
PHP：7.4 ~ 8.1（扩展：mysqli、curl、gd、mbstring、xml）
MySQL：5.7 / 8.0
Web 服务：Nginx 或 Apache
MacCMS：苹果 CMS V10
九、NAS 部署（家庭用户推荐）
群晖 NAS
- 安装 Web Station、**MariaDB/MySQL**、**PHP 7.4+**
- 创建数据库，上传 MacCMS V10 源码到 Web 目录
- 浏览器访问
- http://群晖IP:7963/install.php
- 安装后 务必修改 默认管理员密码
威联通 / 飞牛 / 其他 NAS
思路相同；威联通用户也可直接用 Container Station + Docker。
导入影视数据：后台 采集 → 添加联盟资源/自定义接口 → 执行采集；或后台手动添加测试影片。
十、宝塔 / Docker 部署
宝塔面板：安装 Nginx + MySQL + PHP 7.4 → 新建网站 → 上传 MacCMS V10 → 访问 install.php 安装。
Docker 示例：
- docker run -d \
- --name maccms \
- -p 7963:80 \
- -e MYSQL_HOST=db \
- -e MYSQL_DATABASE=maccms \
- maccms/maccms10:latest
★ 第六部分：开启 API（自建必做）★
使用公开 API 站点的用户可跳过本节
十一、开启「视频 API」（必须）
- 登录后台：http://你的站点/admin.php
- 进入 系统 → 开放API配置
- 确认：视频API → 开启；指定播放组 → 留空；接口授权密码 → 留空
- 保存配置
浏览器自测：
- http://你的IP:7963/api.php/provide/vod/?ac=list&pg=1&pagesize=5
十二、开启「公共 API」（可选，建议开启）
后台 系统 → 开放API配置 → 公共API → 开启
开启后 APP 分类树更准确；不开启也能用，APP 会自动兼容回退。
十三、首页「最新推荐」配置（可选）
APP 首页 最新推荐 读取 MacCMS 推荐等级 level=9 的影片。
后台 视频 → 编辑影片 → 推荐 设为 9 即可。
★ 第七部分：常见问题 ★
十四、连接与数据相关
Q：提示「请先配置 MacCMS 服务器」？
A：设置里保存有效站点地址。
Q：测试连通性失败？
A：检查地址格式、网络；确认视频 API 已开启。
Q：已连接但首页无分类？
A：站点无视频数据；或到首页分类设置里开启至少一个分类。
Q：首页只有几个大类？
A：正常现象，默认只显示顶级分类；筛选页可看全部。
Q：最新推荐为空？
A：该站点未配置推荐等级 9 的数据。
Q：电视访问不了 NAS？
A：确认同网段；电视浏览器先测 http://NAS_IP:端口
十五、播放相关（v1.0.6 重点修复）
Q：有列表但无法播放 / 以前很多片播不了？
A：常见原因是采集站返回 /share/ 分享页 而非 m3u8 直链。v1.0.6 / mobile-v1.0.1 已支持自动解析。请升级到最新版后再试；若仍失败，可能是该播放源本身失效，换片或换播放源。
Q：播放时显示「正在解析播放地址...」很久？
A：正在从分享页提取真实直链，稍等即可；超时会有错误提示，可重试或换播放源。
Q：跳过片头片尾不生效？
A：播放器内 跳过 → 开启开关 → 保存设置（按整部剧集统一配置）。
Q：记忆续播不工作？
A：播放设置里确认「记忆续播功能」已开启。
Q：切换 MacCMS 服务器后收藏乱了？
A：v1.0.5+ 已按服务器隔离收藏，切换站点后只显示当前站点的收藏。
Q：无法检测更新？
A：手动从 GitHub Releases 下载。注意 TV 找 v1.0.x 标签，手机找 mobile-v1.0.x 标签。
★ 第八部分：项目信息与总结 ★
十六、项目信息
项目名称：lemonTV-Film（柠檬影视）
GitHub：https://github.com/jia070310/lemonTV-Film
技术栈：Kotlin + Jetpack Compose（TV / Mobile）+ ExoPlayer Media3 + Room + Hilt
架构：app（TV）+ app-mobile（手机）+ shared（共用业务）+ core（基础层）
版本历史（近期）：
TV v1.0.6 — 双端 shared 核心层；分享页/中转链接自动解析；播放器解析提示
TV v1.0.5 — 收藏按服务器隔离；详情页布局；选集翻页焦点与固定行高
手机 v1.0.1 — 统一 shared 模块；解析错误提示优化
手机 v1.0.0 — 手机版首发：MacCMS 客户端、离线缓存、分享页解析
十七、适合谁用？
✓ 不想折腾、想 填地址就能看 的盒子 / 手机用户
✓ NAS 玩家，自建 MacCMS 家庭影视库
✓ 想要 TV 专用客户端，不想用手机版凑合
✓ 需要 手机 + 电视双端，同一套 MacCMS 数据源
✓ 采集站分享页多、以前播不了的场景（v1.0.6 已大幅改善）
✓ 喜欢开源、可自己改代码的玩家
十八、写在最后
柠檬影视用法很简单：
有公开 API 站点 → 填地址就能用；想长期自用 → NAS 自建 MacCMS。
TV 看大屏，手机随身看，双端共用一套核心，体验一致。
v1.0.6 重点解决了采集站 分享页无法播放 的痛点，如果你以前试过类似客户端但大量片源播不了，建议升级到最新版再试。
欢迎恩山大佬试用反馈！ GitHub 提 Issue 或帖内留言均可。觉得不错帮忙 Star 支持开源～
免责声明：本帖仅分享开源客户端及 MacCMS 使用方法。公开 API 站点为第三方服务，内容与稳定性与本 APP 及作者无关，请用户自行甄别、合法合规使用。本 APP 不内置、不提供任何影视资源。
| 
粤公网安备 44522102000125 增值电信业务经营许可证 粤B2-20192173
发表于 
QQ好友和群
收藏
转播
分享
淘帖
赞
踩
主题置顶卡
沉默卡
变色卡
扫一扫，关注易界动态