IPTV 运营系统 · 帮助文档

1快速开始与首次配置#

一套系统跑在一台 x86 服务器上：接收组播 / 单播 / 摄像头 / 本地片源，转成 HLS 分发，同时提供管理后台、电视端、点播、EPG、SIP 与设备管理。

部署形态

装系统的三条路（任选一条）

装完是什么样

1. 程序与数据：代码放 /opt/iptv，数据放 /var/lib/iptv，注册 systemd 服务 iptv，监听 1090。
2. 默认带 SIP 电话：安装包默认装 Asterisk 并授权后台管理，首次启动自动预置 8 个分机 8001–8008（详见 第 9 章）；不需要可加 --skip-sip。
3. 打开后台：浏览器访问 http://<服务器IP>:1090/admin/，用管理员账号登录，按下面的清单逐项配完。

默认账号

首次配置清单

• 改管理员密码；需要的话在「基础设置」设机顶盒设置密码（默认 1234）。
• 「信源 / VLAN」登记实际使用的网卡，配好 VLAN 子接口。
• 「频道 / 节目」建频道或导入节目源，确认「测试收流」有数据后再启动。
• 「套餐管理」勾选频道组合，「用户管理」建客房账号并分配套餐。
• 「桌面首页」上传品牌 Logo、填欢迎语与天气城市；「APP 升级」上传三个 APK。
• 「备份与恢复」配好邮箱定时备份，至少备份一次 db.json。
• 「授权管理」确认机器码、模块与期限（试用期为首次登录后台起 30 天）。

2后台功能地图#

左侧菜单按业务分组，默认收起，点开一组自动收起其它组。下面是每组能做什么，遇到「这个功能在哪」先查这张表。

3频道与直播信源#

一个频道 = 一个输出 /live/<频道ID>/index.m3u8 + 最多 6 路信源 + 一组切片参数。系统用 ffmpeg 直接转封装（-c copy），不重新编码，CPU 占用很低。

信源地址怎么写

组播能收到是前提

跨网段需要服务器上有 igmpproxy 或 smcroute，或在三层交换机上把组播路由指向服务器。云主机 / VPS 一般不给组播，必须部署在本地网络。

# 在服务器上确认真的收到组播包
sudo tcpdump -i eth0 -n udp port 5000

# 用 ffplay 直接验证某一路能不能播（比后台更快定位）
ffplay -v error udp://239.1.1.1:5000

多 VLAN 接入多路信源

上联口配成 Trunk，在服务器上创建 802.1Q 子接口，然后每个频道绑定自己的信源接口。同一个「组播组:端口」出现在两条 VLAN 上时，内核只会加入一次，绑定接口就是区分它们的唯一办法；不绑就会出现「两个频道画面一模一样」或干脆收不到。

# 例：eth0 承载 VLAN 100 / 200
# 后台「信源 / VLAN」里新增 eth0.100 → 10.0.100.5/24，eth0.200 → 10.0.200.5/24
# 再在频道里把「信源接口」分别选成 eth0.100 / eth0.200

多信源与自动切换

• 每个频道最多 6 路：主用 + 备用 1～5，启动前并发探测，优先选有信号的那一路（不一定从主用开始）。
• 运行中主用断流、卡死（看门狗判定）会自动切下一路；连续两轮全部无信号则自动停台。
• 停台频道每 5 分钟复查一次，信源恢复自动重新开播，电视端频道列表也会跟着回来。
• 电视端只下发当前已启动的频道，停台 / 未启动的频道不显示，避免客人点到黑屏。

批量导入节目源

「频道 / 节目 → 导入节目源」支持粘贴「名称,地址」文本或 M3U，支持 #genre# 分组。系统会逐路 ffprobe 拉流验证（等同 VLC 试播）：有信号的按顺序收录为主用 + 备用，同名频道只追加备用源，全部无信号的频道建号后自动停台等恢复。

重新编号

右上角「重新编号」按广电 / 酒店习惯从 1 连续排：央视频道 → 央视付费 → 卫视 → 地方台 → 港澳台 → 电影 / 体育 / 音乐 / 戏曲 → 点播频道。只改编号与分类，不动信源、不影响正在转发的频道，可重复执行。

启停、监控与播放地址

• 启动 / 停止可以单个操作，也可以「全部启动 / 全部停止」；重启服务器后是否自动起播由「基础设置 → 重启后自动起播」控制。
• 概览页的信源健康度会综合切片产出、转发状态、切源 / 重启次数、停台原因打分，问题频道直接列出来。
• 输出地址：/live/<频道ID>/index.m3u8，在后台可生成带短期令牌的完整可播地址。
• 每次播放签发令牌（默认 3600 秒），绑定「账号 + 频道 + 有效期」，分片地址自动带同一令牌；把地址转给别人会 403。

4EPG 节目单#

给直播频道配「每天循环」的时段表，电视端频道卡片与播放页会自动显示「正在播出」和「下一档」。

三种录入方式

• 逐条新增：开始 / 结束时间 HH:mm、节目名（≤60 字）、可选简介、生效星期（全选=每天，只选周一至周五=工作日）。
• 批量导入：一行一条，08:00-09:30 新闻早班车，用 | 追加简介；09:30~10:00、10:00 至 11:30 都认。可一键「填入示例模板」再改。
• 互联网采集：从 XMLTV 源自动拉真实节目单，适合央视频道、卫视。

互联网 EPG 采集

1. 添加采集源：「EPG 节目单 → 采集源管理 → 添加」，填名称与 XMLTV 地址；支持 .xml.gz 与 GBK 编码，自动跟随重定向。
2. 频道映射：系统按频道名自动匹配（CCTV1 不会误配 CCTV10，CCTV5+ 不会误配 CCTV5）；匹配不上的在「频道映射」里手工指定，改完立即生效。
3. 定时同步：默认每 6 小时（可调 1～72 小时）拉一次，也可「立即同步全部」。只保留最近 1 天到未来 8 天，单源最多 4 万条。

采集到的节目优先展示，手工节目单作为兜底：采集源失效或频道未映射时自动回退到手工表，两者互不覆盖。频道删除重建后，原有映射会自动清理并重新按名称匹配。

5影视点播与转码#

上传影片后系统按文件名自动识别类型、季集与年份，采海报与简介，转码成 HLS，再发布成点播频道或 24 小时轮播频道。

从上传到能看

1. 上传：「影视库 / 点播 → 上传影片」，支持 mp4 / mkv / mov 等，单文件最大 8GB。
2. 自动识别：按文件名判断电影 / 电视剧 / 短剧 / 动漫 / 纪录片 / 综艺与季集年份，剧集自动聚合为「详情 + 选集」。
3. 补元数据：配置 TMDB 后自动采海报、简介、评分、题材；旧片可「重新识别全部影视」补齐。
4. 转码：服务器端 ffmpeg 转 H.264 / AAC 并切片成完整 HLS，进度实时显示。
5. 发布：一键发布为点播频道，或以「轮播模式」循环实时切片成 24 小时频道。播放复用同一条令牌鉴权链路。

转码参数怎么选

不想让某部片出现在点播 APP 里，可以「在点播中隐藏」，它仍可被桌面首页宣传位第 4 块指定推荐。

6用户、套餐与机顶盒绑定#

套餐决定「能看哪些频道」，用户决定「谁在看、几台设备」，绑定决定「这个房间的盒子开机能不能直接进桌面」。

套餐与用户

• 套餐：勾选频道组合、填价格、有效期天数，可上下架。
• 用户：新建账号时初始密码可以留空——留空即「只输账号就能进」，填了密码才能设成「必须密码」。
• 续费 / 禁用 / 删除：禁用会立即让该账号的登录令牌与设备凭证失效。
• 设备数上限：单账号可同时登录几台盒子，超出会提示「请联系前台解绑」。
• 开机直播：勾上后这个账号的盒子启动直接进直播，不显示桌面。

免密登录（账号 + 设备绑定）

盒子第一次输入客房账号（默认不需要密码）时，服务端把本机硬件编码写进这个账号的绑定名单；之后升级、重装、重启都不用再输任何东西，开机直接进桌面。

绑定与解绑

• 「用户管理 → 机顶盒」能看到每台设备的名称、硬件编码、CPU 序列号、绑定时间、最后在线时间 / IP、APP 版本。
• 换盒子：先解绑旧的（单台或全部），新盒子登录一次即绑定；解绑后旧设备凭证立即失效。
• 硬件编码按 CPU 序列号 → SoC 序列号 → 网卡 MAC → ANDROID_ID 的顺序生成，原文经哈希处理，不会把原始序列号暴露给前端。
• 账号被禁用 / 删除时，设备凭证同时失效，绕不过账号状态。

7电视端与三个 APP#

同一套代码打出三个包：桌面（launcher）、直播（live）、点播（vod），同一签名、单点登录。也可以先用浏览器 TV 端做验收。

浏览器 TV 端

http://<服务器IP>:1090/tv/：方向键移动焦点、OK 确认、返回键回桌面、数字键 1-9 切台。适合装机验收和前台电脑演示。

三个安装包

桌面登录一次，直播 / 点播启动直接拿到令牌；在任意一个 APP 的设置里改服务器地址或重新登录，会同步到另外两个。

遥控器操作

设置密码与服务器地址

• 设置密码 4～8 位数字，默认 1234，后台「基础设置 → 机顶盒设置密码」修改，下次进入立即生效。
• 连续输错 8 次锁定 10 分钟；管理员可在后台看到当前密码。
• 登录页与设置页只显示并只允许改 IP，http:// 与端口由程序固定沿用，客人不会把格式改坏。

升级与开屏

• 后台上传新版 APK 会自动识别包名与版本号，盒子启动或回到桌面时检查更新；可设强制升级、保留 6 个历史版本回滚。
• 直播 / 点播打开时先显示启动画面（背景图 + 0～10 秒读秒），期间首屏数据并行加载，读秒走完且数据就绪才淡出。
• 兼容 Android 4.4 起（minSdk 19）；只认 file:// 安装的老盒子，需要手动装一次较新的版本，之后才能自动升级。

8桌面首页与消息通知#

客房电视第一屏决定观感：品牌、欢迎语、宣传位、天气、热门推荐都在这里配。

桌面首页

• 品牌：上传 Logo、填品牌名称与欢迎语；电视端桌面不显示账号名与套餐，保持干净。
• 宣传位：图片或视频，一屏 4 块轮播，视频静音循环；第 4 块可以指定某部点播影片，按 OK 直接进详情。
• 天气：填城市名，首页显示实时天气与日期时钟。
• 热门推荐：正在热播 / 热门点播，取点播播放热度。
• 直播默认播放：固定频道或上次观看；客房首页进入直播可直接起播。

消息通知（跑马灯）

信息发布

四级栏目 + 图文页，用来放酒店介绍、周边、消防须知、活动通知等；内容独立于点播，不占影视库。

9SIP 电话分机#

后台内置 Asterisk（PJSIP），服务器同时是一台小话务服务器：客房话机 / 软电话注册上来后互相拨分机号，不依赖外部话务商。

安装包已经默认装好

从 1.18 起，服务器安装包（在线一条命令 / 离线包都算）默认安装 Asterisk 并自动执行下面的授权脚本，装完就能开分机。首次启动时如果还没有任何分机，系统会自动预置 8001–8008 共 8 个默认分机，密码在后台「SIP 电话」页可直接查看——话机填上就能注册。

# 一般不需要手动执行；老机器或手动装过 Asterisk 时补一次
sudo bash /opt/iptv/deploy/setup-sipctl.sh

授权脚本会把受限助手装成 /usr/local/sbin/iptv-sipctl（只有 iptv 用户能免密执行），在 pjsip.conf / extensions.conf 末尾追加项目专用 include（自动备份原文件），并启动 Asterisk。配置语法异常会自动回滚。缺 Asterisk 时脚本会自动 apt-get install -y asterisk 补上。

开号与配置

• 「SIP 电话 → 批量开号」：填号段与数量，密码随机或固定，可加备注前缀。
• 指定监听网卡 IP 与端口，多网卡服务器要选客房能访问的那张。
• 话机上填：服务器地址（服务器 IP）、分机号、密码，传输选 UDP，注册成功即亮绿灯。
• 「通话记录」可看主叫 / 被叫 / 时长 / 接通状态，支持筛选、同步、清空与导出 CSV。

10网络、VLAN 与组播#

网络配置都在后台完成，改动写入 netplan，由受限助手执行，不需要手改配置文件。

常用入口

排查组播的固定套路

1. tcpdump -i eth0 -n udp port 5000 看有没有包：没包就是上游 / VLAN / 交换机的问题。
2. 有包但频道起不来：确认组播组与端口没抄错、频道绑定的信源接口正确。
3. 两条 VLAN 同组同端口画面一样：给每个频道分别绑定各自的子接口。
4. 开了 IGMP Snooping 却收不到：交换机上要有 Querier，或把上联口设成组播路由口。

IPv6 与双栈

服务端默认双栈监听（::）：服务器有公网 IPv6 时，管理后台、TV 接口、HLS 都能用 http://[IPv6地址]:1090 访问，IPv4 同时可用。FTP 的 PASV 主动模式仅 IPv4，IPv6 客户端走 EPSV。

11存储与磁盘扩容#

直播切片放内存盘，点播文件放磁盘。片子多了先扩存储，不要先删片。

三类存储

扩容点播存储

• 本地磁盘：「存储管理 → 本地磁盘」格式化 / 挂载 / 卸载，挂载后把点播目录指过去。
• 网络磁盘：「存储管理 → 网络磁盘」挂 NFS 或 SMB，适合 80T 级影视库；挂载后同样改点播目录。
• 迁移：改点播切片目录时系统会校验可写并自动迁移已有切片，迁移期间别关机。

12备份、升级与日常巡检#

运维只需要盯三件事：能备份、能升级、出问题能看日志。

备份

• 「系统设置 → 备份与恢复」配 SMTP（支持 SSL），可定时把数据打包发到邮箱，也可立即备份一次。
• 换机器时把 /var/lib/iptv/db.json 与 uploads / apk 目录一起拷过去，最稳。
• 恢复前先停服务，恢复后再启，避免运行中的数据把文件覆盖回去。

升级

升级服务期由签发时的「升级年限」决定，0 表示永久。服务期结束后当前版本照常使用，但不能在线升级到新版本。

巡检与日志

systemctl status iptv          # 服务状态
systemctl restart iptv         # 重启（会重连所有频道）
journalctl -u iptv -f          # 实时日志
journalctl -u iptv -n 200      # 最近 200 行
df -h /var/lib/iptv            # 磁盘余量
free -h                        # 内存（内存盘切片占这里）

• 概览页看信源健康度与即将到期用户，红色频道优先处理。
• 系统监控页看 CPU、内存、每网卡发送速率与在线终端数。
• 服务器需要断电重启时用「服务器电源」远程重启 / 关机，别直接拔电。

13授权与注册#

授权跟机器绑定，不是跟安装包绑定。搞清机器码怎么来，能省掉一大半售后。

机器码与模块

• 机器码：按主机名 + 网卡 MAC + CPU + 内存算出 16 位十六进制，后台「授权管理」可查看与复制。
• 授权模块：桌面 APP、直播、点播、拉流、推流（组播再输出）、投屏，各自独立校验；只签发用到的模块。
• 用户档位：签发时选 210 户 / 510 户 / 无限制，新建用户时校验当前激活账号数，超了返回「已达到授权用户数量上限」。

注册流程

1. 客户把后台显示的机器码发给服务商。
2. 服务商按机器码签发：勾选模块、填使用年限与升级年限（0 = 永久）、选用户档位。
3. 机器每 30 分钟自动拉取一次授权（也可点「获取授权」立即拉），全程不需要导入文件。
4. 需要离线部署时，服务商下载 .lic 注册文件，客户在「授权管理 → 离线导入」导入即可。

试用与持续校验

• 未注册机器自首次登录后台起 30 天试用，全模块可用。
• 已注册机器每 30 分钟拉一次授权并换一次 key（key 有效 20 天）。连续 20 天联系不上授权服务器、授权被吊销或使用期限到期，后台会显示「授权非法 / 已过期」，系统会中断业务并重启，直到恢复合法授权。
• 换新服务器：新机装好后把 db.json 与上传目录拷过去，再按新机器码重新签发。

14远程协助与安全边界#

服务商可以在不打电话问地址的情况下远程看后台；但不管从哪里进来，都要验证这台机器的后台账号密码。

进入方式

账号密码由这台 IPTV 自己校验，与门户账号无关。远程入口依赖机器上「远程云端管理」的管理密钥：在 IPTV 后台「系统设置 → 远程云端管理」复制，交给服务商填到门户对应机器上。密钥重置后旧入口立即失效。

建议的安全基线

• 管理员密码、系统账号密码全部改掉，不要用默认值。
• 远程入口只给运维人员，客人只走客房账号。
• 公网部署时用防火墙收口：只放行后台端口与业务端口，其它一律拒绝。
• 每个客房账号设备数设为 1，贵重场景改成「必须密码」。
• 定期改管理密钥，尤其是人员变动后。

15常见问题速查#

按「现象 → 处理」查，90% 的现场问题都在这张表里。

16术语表#

和集成商、广电、运营商对接时最常出现的词。