操作文档 · 使用手册

★快速上手（5 步）

第一次接触？照这 5 步，半天内能让房间电视正常播放。

1系统组成

先认识几个名字，后面所有章节都会用到。

地址速记

• 后台（客户机）：http://<服务器IP>:5311 —— 所有日常配置都在这里。
• 云平台（中心）：https://124.222.226.184:5200/console/ —— 管多台客户机、发版本、签授权。

2部署前准备

只需一台迷你主机 + 一个 U 盘。

硬件要求

需要准备的信息

• 服务器 IP：给客户机服务器固定一个内网 IP（如 192.168.1.10），电视和后台都靠它。
• 网络：能访问互联网或酒店内网直播源；若用组播，需交换机支持 IGMP。
• 电视 / 机顶盒：Android 4.4 ~ 14 全兼容（老机顶盒不用换，新电视更流畅），允许安装第三方应用（未知来源）即可。

3离线安装（ISO）

整机安装，不依赖网络，装完即用。

3.1 下载 ISO

到官网「下载」区下载 ys-iptv-installer-<版本>.iso（当前 1.0.904，约 746 MB）。核对官网标称的文件大小/校验值后再写入 U 盘。
开发机本地下载：本地下载

3.2 制作启动 U 盘

• Windows：使用 Rufus 4.15 或 balenaEtcher，选择 ISO 后务必选 DD 模式，直接写入 U 盘（会清空 U 盘数据）。
• Linux / macOS：sudo dd if=ys-iptv-installer-*.iso of=/dev/sdX bs=4M status=progress oflag=sync（把 /dev/sdX 换成 U 盘设备，千万别写错盘）。

3.3 启动并安装

1. 将 U 盘插到迷你主机，开机按 F7 / F11 / F12 / Esc（视品牌）选择从 U 盘启动（UEFI / 传统 BIOS 均支持）。
2. 进入「YanshanIPTV 安装器」文字界面，选择要安装的目标磁盘。
3. 界面会提示「目标磁盘将被清空」，确认后开始写入（约几分钟）。
4. 安装完成自动重启，拔掉 U 盘。首次开机进入「配置控制台」（见下一章）。

3.4 无人值守安装（批量部署用）

批量装机时可在启动菜单的内核命令行追加参数，全程自动、无需人工选盘：

ys.auto=1 ys.disk=/dev/sda ys.hostname=iptv01 ys.password=你的后台密码 \
  ys.vip=192.168.1.10/24 ys.peer=192.168.1.11

4首启配置控制台

装完后主机 显示器上直接出现文字菜单，用键盘操作，重启后仍会出现，随时可配置。

菜单功能

4.5电视端安装与兼容（Android 4.4 ~ 14）

一个 APK 通吃老机顶盒与新型智能电视。

• 版本覆盖：Android 4.4 / 5 / 6 / 7 / 8 / 9 / 10 / 11 / 12 / 13 / 14 —— 同一份安装包。
• 老机优化：硬解优先（MediaCodec）+ 软解兜底、播放器复用（换台不重建解码器）、内存/崩溃自保、界面按屏幕等比缩放。
• 服务器地址：由客户机生成 APK 时自动注入（写进安装包内），电视端不需要手工填 IP；换服务器地址时重新生成并 OTA 下发即可。
• 安装方式：客户机后台「电视 APK」页生成并下载 → U 盘安装或 OTA 升级；也可用「批量刷机(adb)」插件对同网段电视批量安装。
• 设为桌面：安装后可在电视端「系统管理 → 设为默认桌面」把本应用设为开机桌面（部分定制 ROM 需在系统设置里手动选）。

5登录后台与初始化

后台是日常操作的主战场。

1. 浏览器打开 http://<服务器IP>:5311。
2. 使用超级管理员登录。装机时若在控制台改过密码，用新密码；出厂默认密码见交付单（首次登录后请立即修改）。
3. 进入「系统 → 系统设置 / 组织管理」，创建或选择你的组织（酒店 / 小区 / 医院…），并设置行业版本。
4. 按「按版本预置」一键补齐该版本的菜单、服务项、频道分组、皮肤等空缺内容。
5. 到「系统 → 云平台」填绑定码，把本机接入中心云平台（见第 12 章）。

6网络配置

后台「流媒体 → 网卡管理」可视化操作，也可在首启控制台里配。

6.1 网卡管理

• 列表显示所有物理网卡及其 IP、网关、用途、上下线状态。
• 管理口：承载「后台访问地址」的那块网卡，会被标记为「管理口」，不允许停用（避免把自己关在门外）。
• 采集口：给直播源使用，建议不设网关。
• 改 IP 后若 30 秒内未确认，系统会自动回滚，防止配错失联。

6.2 固定 IP 与 DNS

给管理口配静态 IP（如 192.168.1.10/24）、网关（192.168.1.1）和 DNS（如 223.5.5.5），保存后立即生效。建议在路由器上为该 IP 做 DHCP 绑定，避免地址变化。

6.3 VLAN 采集口（先下发，再建采集通道）

直播源很多、物理网口不够时，可以用 VLAN 交换机扩展采集口：每个 VLAN 就是一个独立的采集口（如 enp7s0.101）。常见误区是只在 VLAN 表里保存，没有「下发」，或者只填了网段、没有给 VLAN 配 IP —— 这样在「采集通道」里选它就会提示 「采集线路无效」。

1. 保存 VLAN 表：VLAN ID、物理接口、网段、本接口 IP 都填好。没有 IP 的 VLAN 不会出现在可用采集线路里。
2. 生成计划 → 下发：在 VLAN 页点「生成计划」检查命令，再点「下发」并确认。只保存表格不会创建 enp7s0.101 子接口。
3. 确认下发成功：下发后页面会显示实时 VLAN / 健康状态；如果 30 秒内健康检查失败，系统会自动回滚，先处理交换机 trunk 或 IP 冲突再试。
4. 再建采集通道：到「流媒体 → 采集通道 → 新建采集通道」，采集口下拉里应出现 enp7s0.101，选择后保存即可绑定频道。

7直播频道

后台「内容运营 → 频道」：分组、多源、导入、台标、EPG。

7.1 分组与频道

• 页面按分组展示（含「未分组」虚拟桶）。可新增/重命名/删除分组；重命名会同步更新频道上的分组名。
• 「未分组」也可直接管理：＋频道、建组并移入、全部删除。
• 频道支持批量操作（启用 / 停用 / 删除 / 移动到分组）。

7.2 导入频道（M3U / TXT）

点「导入」→ 选择「文件导入」，粘贴或上传后自动识别格式，无需手选：

导入时可先「预览」，确认无误再入库；同名即多源（同分组下按顺序作优先级，第一个为主源）。

7.3 台标与 EPG

• 「导台标」：批量匹配/上传频道台标，台标会自动按图形面积归一，大小一致。
• 「EPG」：配置节目单来源，电视端可就近显示当前/下一档节目。

7.4 直播回看 / 时移

• 在「内容运营 → 频道」对应频道上勾选回看并设时长（5–60 分钟，步长 5，默认 10）；页面顶部有实时硬盘用量，超过配额会拒绝开启并提示。
• 开启后系统会自动把该频道接入流媒体网关做本地缓冲（网络源也能回看）；关闭即释放。回看采用按需采集——有观众在看时才拉流，无人观看自动停，不会 24 小时常占上游。
• 电视端：直播页左侧频道列里，可回看的频道右侧显示「›」标记；在该频道上按遥控器右键，会在同一行弹出「回看」三级菜单。
• 菜单条目实话实说＝后台设的回看时长（如设 10 分钟 →〔回看10分钟前、回看5分钟前〕；设 5 分钟 →〔回看5分钟前〕）：上下选择、确定从该时间点回放，播到末尾自动接回直播；回看中左右键调时间、返回回直播，右下角显示「正在回看」水印。

7.5 直播 Web 页面（浏览器看直播）

• 入口：后台「流媒体 → 系统总览」右上角 「直播 Web 页面」按钮，点开为新窗口。
• 左侧列出全部频道（可搜索，采集中显示绿点），按「流媒体 → 频道」里的顺序排列，同名频道自动去重；点频道即在右侧播放。
• 播放器支持 全屏（右上按钮或双击画面）；空格/方向键可直接换台（按列表顺序）。
• 该页面是独立页面（不在后台框架内），地址为 http://<客户机IP>:5311/live/，酒店局域网内任意电脑/手机浏览器可直接打开（无需登录）。

8在线影视

后台「在线影视」：数据源、采集、去头去尾。

• 数据源 / 采集：配置影视资源接口，采集影片元数据与播放线路；分类为细分类型（动作片 / 国产剧…），大类自动映射。
• 去头去尾：为影片设置跳过片头/片尾的秒数，电视端播放时自动跳过。
• 电视端「在线影视」：首页推荐/分类、搜索、详情（按线路分组选集）、收藏、续播（本地+服务端同步）。

9界面与皮肤

后台「皮肤」：编辑器、按版本做皮肤、云皮肤商城。

9.1 确认当前启用的皮肤

编辑器只代表「正在编辑哪套皮肤」，真正的生效皮肤由组织配置决定。推荐流程：进「皮肤 → 皮肤库」看组织当前启用的皮肤，再进编辑器。

9.2 皮肤编辑器

• 可视化拖拽布局：欢迎页 / 主页分区，元素有文字、按钮、直播视频区、天气、天气图标、公告、时间、底栏（dock）等。
• 底部菜单（dock）：支持「每屏个数」「对齐」「按钮宽」；也可切换九宫格（grid）模式配列数/行距。
• 保存后电视端自动拉取，无需重装。

9.3 按版本做皮肤

皮肤与行业版本隔离：酒店版皮肤只用于酒店版组织。新建皮肤时选择对应的「行业」，切版本时系统会自动启用该版本的默认皮肤。

9.4 云皮肤商城

• 在「皮肤 → 云皮肤商城」可浏览中心上架皮肤，一键应用到本组织。
• 自己设计的皮肤可「提交到商城」，中心审核通过后对所有客户可见。

10内容与应用

后台「内容运营」下的各类内容与应用。

• 广告：开机广告、整屏插播、主页直播框广告、轮播图。可设投放范围（全部/分组/房间/指定设备）、显示时长、播放次数、声音。
• 公告：滚动公告（顶部跑马灯，速度可调）、场景公告、图文/视频/链接公告。
• 客房服务 / 服务项：点单服务、图标（可在图标库更换，未配图标时按服务名自动匹配）。
• 行业模块：小区版（物业费 / 快递代收 / 社区信息）、医院版（病区 / 护理呼叫 / 健康宣教 / 院内订餐）、公寓版（房租 / 包裹）等。
• TV 端界面：菜单编辑区可调整电视底部菜单的按钮、顺序与跳转。

11电视终端

给每台电视装上 App，并让它成为电视桌面。

11.1 生成 TV APK

APK 由本机现场生成，会把本机服务器地址注入进去，并用本客户专属密钥签名（保证后续升级无缝）。

• 控制台菜单「生成 TV APK」；或后台里触发；或命令行：

IPTV_ROOT=/opt/iptv TV_SERVER_URL=http://<服务器IP或VIP>:5311 \
  bash /opt/iptv/current/apkbuild/build-apk.sh

产物在 /opt/iptv/data/uploads/apk/，电视可通过 http://<服务器IP>:5311/files/apk/… 下载安装。

11.2 安装到电视

1. 电视上允许「安装未知来源应用」（部分小米/老安卓电视还需在开发者选项里打开 USB 安装）。
2. 用 U 盘拷贝 APK 安装，或电视浏览器打开下载地址安装。
3. 首次启动会引导「设为默认桌面」；也可在「系统管理」页里点「设为默认桌面」。

11.3 设备与远程操作

• 后台「设备管理」显示在线状态、版本、最后心跳、最近错误。
• 临时分组：把一批房间号组成临时组，可设到期时间，到期自动解散。
• 远程操作：重启、静默卸载软件、查看实时屏幕、下发命令并查看进度与结果。
• 断网/重连：电视端会自动重试并自愈，无需人工重装。

11.4 手机投屏（房间精准）

内置应用「手机投屏」：客人用手机把视频投到本房间的电视上，只能投本房间。

• 视频 App 直接投（主力）：客人连本房间 WiFi → 打开 腾讯视频 / 爱奇艺 / 优酷 / 芒果TV / B站 / 抖音 → 点「投屏」→ 列表里选「客房电视 <房号>」→ 电视上点「接受」即播。
• 扫码兜底：电视端「手机投屏」页会显示二维码（每次打开新生成），客人扫码后可粘贴视频链接或从相册选视频/照片投屏。
• 房间精准与隐私：电视名带房号、电视端必须确认（同一台手机 10 分钟内免二次确认）、 并且只在打开投屏页后的 10 分钟内可被搜索；离开投屏页会自动结束投屏并作废投屏码。
• 房间 WiFi 引导：可在后台「设备管理 → 房间 WiFi」给每台设备单独设 WiFi 名/密码（优先于 「内容运营 → TV端界面」的组织级设置）， 投屏页会把本房间 WiFi 名与密码醒目显示给客人。
• 登录并口说明：目前已支持 iPhone 和安卓手机（手机端 App 的投屏按钮都走 DLNA 标准）。
• 注意：少数片源被版权方限制不允许投屏（App 侧限制，与电视无关）。

11.5 直播大修：时间轴重打 + 换台提速

针对运营商组播源里CCTV3/5/6/8/16 等频道时间轴混乱（源端时间基准漂移可达 ±2000 秒）导致的卡顿与音画不同步，网关直播中继按广播级标准重建时间轴：

• 公共偏移重打：视频、音频、PCR 用同一偏移映射到连续时间轴，源里的音画相对关系原样保留（同步性=运营商级）；
• 跳变免疫：只以视频 DTS（单调）检测源跳变，跳变处切段并整体平移，输出严格单调；
• 换台提速：播放器从窗口头部开播（整个窗口为缓冲余量）+ 相邻频道后台预载，连续换台接近瞬切；
• 零转码：全部为包级时间戳操作，不增加 CPU 负担，画面为源的原画质量。

11.5SIP 电话（插件）

客房电视与前台/分机互通；不启用插件时完全沉睡，不影响直播与影视。

• 电视端：客房电视可一键呼叫前台；收到前台或分机来电时，电视显示来电提示，可用遥控器接听 / 拒接 / 挂断；通话结束后自动回到原页面。
• 前台分机：按酒店配置，不写死。后台「酒店设置 → 电话 → 前台分机」填写；电视端「客房服务 → 呼叫前台」拨打该分机。
• 分机：在「插件 → SIP 电话」里配置前台、客房/测试分机；电视分机由设备管理生成（默认房号 + T），支持双振铃。
• 通话记录：后台「SIP 电话 → 通话记录」可查呼入/呼出/未接、时长与挂断原因；默认保留 7 天，支持立即清理。
• 插件安装：插件商店安装「SIP 电话」并启用；首次启用会准备 FreeSWITCH 通话服务（依赖 Docker，可先用「Docker 管理」插件安装 Docker）。
• 占线提示：前台忙线时电视显示「前台占线，请稍后再试」。

12云平台

集中管理多台客户机。入口：https://124.222.226.184:5200/console/

12.1 绑定客户机

1. 云平台登录后生成「绑定码」（16 位）。
2. 客户机后台「系统 → 云平台」填入绑定码，提示绑定成功。
3. 云平台「我的设备」里出现该客户机，显示在线时长、设备数、CPU 温度、程序版本、公网地址等。

12.2 远程控制台

在设备详情里点「Web 页面」，即可免密打开该客户机的后台（链接 30 分钟内有效），无需跑到现场。也可远程查看内核/网关状态。

12.2.1 三种接入方式（按速度从高到低）

公网直连怎么配：

1. 盒子本身就是公网 IP（PPPoE 拨号 / 固定 IP）：不用配置，agent 会自动识别并上报。
2. 酒店用路由器 NAT：先在路由器上做端口映射 TCP 5311 → 盒子内网 IP:5311；再在盒子执行 echo "公网IP或DDNS域名:5311" > /opt/iptv/config/public-addr && systemctl restart cloud-agent。
3. 云平台的设备列表会出现「公网 🌐」、设备详情出现「公网直连 🌐」，点开即免密进入，数据不经过云平台。

12.3 版本下发

在云平台「版本管理」把新系统版本下发给指定客户机（可按行业版本/客户/设备筛选），客户机自动升级，失败会自动回滚（见第 14 章）。

13授权与行业版本

把平台为你的组织生成的授权串（License）导入本机即可启用，支持离线验签。

13.1 行业版本

系统支持酒店版 / 小区版 / 医院版 / 公寓版 / 高端定制版。不同版本的功能模块、术语、皮肤相互隔离，一个版本只能看到该版本的组织与设备。

13.2 申请与导入授权

1. 在授权后台「生成授权」填写版本、客户名、天数、终端数、门店数，得到一串 License。
2. 在客户机后台「系统 → 授权」把 License 粘贴导入即可生效（离线验签）。
3. 到期前可在授权后台「续期」，把新 License 再导入一次。

13.3 免费试用

官网「免费试用」可自助申请 30 天授权（需短信/图形验证），流程：填资料 → 获取验证码 → 得到 License → 导入客户机。

14版本管理与升级

在线升级，自动回滚，不影响正常营业。

14.1 系统版本升级流程

1. 在云平台「版本管理」看到新系统版本，点「下发」（可选适用范围）。
2. 客户机 updater 自动下载 → 校验（sha256 + 签名）→ 解包 → 切换版本 → 重启服务 → 健康检查。
3. 通过则回报「已升级」；失败则自动回滚到上一个版本并回报原因。
4. 在「版本管理 → 明细」逐台查看状态：待下发 / 下载中 / 升级中 / 已升级 / 已回滚 / 失败。

14.1.1 增量升级（768 起）

从 1.0.768 起，系统升级会优先使用增量包：只下载相对上一版本有变化的文件，复制当前版本后覆盖并校验完整文件清单。内核 jar 或基础 APK 本身变化较大时仍会下载这些大文件；后台/网关等小改动通常只需十几 MB。

旧版本（766/767 及更早）的 updater 还不支持增量包，必须先完整升级到 768；之后后续版本才走增量。

14.1.2 电视呼叫前台

电视主动呼叫前台时有等待回铃音；前台占线会显示「前台占线，请稍后再试」。前台按 SIP 分机显示名识别，不依赖固定分机号（1000/1006/… 均可）；首页前台电话也跟随该分机。

14.1.3 手动回退

超管在「版本管理」每行点「回退」，按用户分组选择设备，可回退到任意历史版本（包括已停用版本）。回退失败同样自动恢复到操作前版本。

14.2 电视 APK 升级

系统升级成功后，客户机会自动重新生成并登记 TV APK 的新版本，电视下次启动自动提示升级。所有 APK 都用同一客户密钥签名，升级无需卸载。

15主副双备

两台服务器 + 一个 VIP，主机故障时自动接管，电视无感。

15.1 方案

• 主机持有一个虚拟 IP（VIP），电视端出包时统一填 VIP:5311。
• 主机故障时 VIP 自动漂移到备机，备机接管，服务恢复。
• 数据库实时复制（主→备），上传文件单向同步。

15.2 配置

1. 两台机器都装好系统（可用 ys.vip / ys.peer 无人值守预置）。
2. 控制台「系统角色」分别设为主机 / 备机，填相同的 VIP 与复制密码。
3. 在主机执行复制准备；在备机执行全量同步。
4. 用「状态」页确认主机持 VIP、备机只读待命。

16常见问题排查

按顺序排查：先看首启控制台「服务状态」，再看日志。

后台打不开 / 提示服务器内部错误

• 确认服务器已开机、网线和 IP 正确，先 ping 服务器 IP。
• 到显示器上的配置控制台看「服务状态」，若内核/网关未运行，点「修复安装」。
• 超管首次使用需先选择组织；未选组织时部分页面会报错，到「系统设置」选好组织即可。

采集通道提示「采集线路无效」

• 不要在 VLAN 表保存后直接去建采集通道：必须先点 生成计划 → 下发，让系统真正创建 enp7s0.101 这类子接口。
• VLAN 必须配置 本接口 IP（当前界面写作「网关地址」，如 11.11.11.11）；只填「网段」没有 IP，采集通道会判定为无效线路。
• 接采集口的交换机端口必须是 trunk 并放行该 VLAN；否则接口存在也收不到组播。
• 详见 6.3 VLAN 采集口。

直播频道卡顿 / 有声音无画面

• 先确认该源在别的播放器里是否正常（排除源本身问题）。
• 网关会自动校正音视频时间戳并重启卡死的流；稍等 1 分钟再看。
• 高帧率（1080p50）源在弱机顶盒上会卡，可在网关上对该频道做限帧转码。

在线影视返回首页后遥控器没反应

• 属已修复的历史问题；若仍出现，把电视端升级到最新 APK。

电视装不上 / 装完不是桌面

• 小米/老安卓：开启「允许安装未知来源」；部分机型需开发者选项里打开 USB 安装。
• 桌面：App 已声明为桌面，首次按 Home 选「始终」即可；个别定制 ROM 需到「电视设置 → 主屏幕」手动选择。

升级失败 / 提示授权到期

• 升级失败会自动回滚，到云平台「版本管理 → 明细」看具体原因。
• 授权到期：到授权后台续期后重新导入 License。

17附录：目录 / 端口 / 命令

目录结构

/opt/iptv/
  releases/<版本>/    每个版本的完整程序
  current -> releases/<版本>   原子切换的软链
  config/             地址 / 角色 / 密钥 / 发布公钥（升级不动）
  data/              数据库 / 上传 / HLS / 升级工作目录
  logs/              内核 / 网关 / 升级日志
  scripts/apply.sh   换版本钩子（重启服务）

端口

常用命令（在服务器上，可选）

# 查看服务状态
systemctl status yanshan-iptv-backend yanshan-iptv-gateway

# 重启内核 / 网关
systemctl restart yanshan-iptv-backend yanshan-iptv-gateway

# 查看网关日志
tail -n 100 /opt/iptv/logs/gateway.log

联系与支持