企业官网建设流程全解析

1. 先想清楚：一条 M3U 链接到"能看电视"的频道列表，中间隔了什么

手里只有一条 M3U 链接，播放器打开就是一堆没有台标、没有分组、没有节目单的裸频道，切过去还黑屏——这是绝大多数人第一次接触直播聚合时遇到的真实场景。我这里说的"带节目单的频道列表"，指的是把一条原始 M3U 链接，经过解析、清洗、重新编排，再配上独立的 EPG（电子节目单，标准格式是 XMLTV）后，输出成一份结构清晰、台标齐全、分组合理、能显示"现在播什么 / 接下来播什么"的播放列表。这件事听起来只是"套个壳"，实际上牵扯到播放列表格式规范、节目单时间格式、容器部署、缓存策略、播放端兼容性五条独立的技术链路，任何一环出问题，用户看到的就是黑屏或者一片"暂无节目信息"。

这篇内容适合三类人：一是自己搭了媒体服务器、想把零散直播源整理成一份体面列表的折腾党；二是手里有自建摄像头、自有录制内容、内部演播室推流，想做成局域网内可访问的直播入口的技术同学；三是单纯想搞明白 M3U、M3U8、XMLTV、HLS 这几样东西到底是什么关系的新手。我不打算写"一键脚本复制粘贴就完事"那种东西，因为你迟早会遇到"节目单差 8 小时""台标全部不显示""某几个客户端能播别的不能播"这些坑，而这些问题全部来自对格式细节的误解。

先说清楚一件事：下文所有示例里的流地址、频道名、台标路径，我全部用的是内网占位地址和虚构名称。你要跑通这套东西，内容源必须是自有的——自己拍的、自己录的、自己搭建的推流服务，或者明确获得授权的素材。这一条不是客套话，是这套部署能不能长期稳定跑下去的前提，后面第 7 节我会细说为什么。

1.1 三层结构：源、聚合、播放端

整套链路我在脑子里是切成三层的，这个切法决定了后面所有配置怎么放。

第一层是源。它可能是一条别人给你的 M3U 链接，可能是你自己用 FFmpeg 推到本机目录的 HLS 切片，也可能是一个 RTSP 摄像头通过转封装变成的 HLS 流。这一层的产出物只有一个：一个能被 HTTP 访问到的.m3u8地址。注意是 m3u8 不是 m3u，前者是 HLS 的索引文件（里面是分片列表），后者是播放列表清单（里面是频道列表）。这两个名字太像，是新手第一个混淆点，我在第 2 节会拿具体内容对比。

第二层是聚合。聚合层干三件事：把多来源的频道合并成一份列表、给每个频道补齐元数据（台标、分组、唯一 ID）、把 XMLTV 节目单和这份列表做 ID 对齐。标题里提到的那个开源直播聚合面板就活在这一层。它的价值不在于"能播"，而在于"能管"——你能在面板里看到每个频道的健康状态、能改名字改分组、能挂多份节目单源、能给不同的人发不同的播放列表地址。

第三层是播放端。手机、电视盒子、桌面播放器、浏览器，每个客户端对 M3U 标签的支持程度都不一样。有的认tvg-logo，有的只认#EXTINF后面那个逗号后的名字；有的会自动去拉x-tvg-url，有的必须你手动填节目单地址。所以聚合层输出的时候要"宽容"——该有的标签全给上，别指望客户端帮你补。

为什么要在中间加这么一层，而不是直接把原始 M3U 丢给播放器？因为原始链接你控制不了。它随时可能改地址、加频道、换命名规则，而你的播放端配置是写死在电视盒子里的。加了聚合层之后，盒子永远只认你内网那一个固定地址，源怎么变都不影响终端。

1.2 为什么用 M3U 而不是别的中间格式

有人会问，既然都上聚合层了，为什么不干脆用 JSON 或者数据库，让播放端来查接口？答案很朴素：兼容性。M3U 是近乎所有播放器都认的最低公分母，从十几年前的机顶盒到最新的移动端播放器，全都能读。你换成自定义 JSON，等于要求每个客户端都装你的专用 App，这个成本对家庭场景或者小团队场景完全不划算。

另外 M3U 是纯文本，可读、可 diff、可版本管理。我习惯把每次清洗后的播放列表提交到本地 Git 仓库，出问题直接git diff看这次改动了哪几个频道，比翻日志快得多。这个习惯是被坑出来的：有一次批量重命名把分组字段写错，两百多个频道全挤进一个分组里，靠的就是 diff 三分钟定位到问题行。

代价是 M3U 没有标准。是的，它没有官方 RFC，#EXTINF后面的属性是社区约定俗成的，tvg-id、tvg-name、tvg-logo、group-title这几个是被广泛支持的，再冷门的属性就各家各话了。所以我的原则是：只用被至少三个主流客户端验证过的属性，其他花活一概不上。

1.3 节目单为什么要走独立链路

节目单和频道列表是两条完全独立的数据流，这个认知很关键。

频道列表告诉你"有哪些台、地址是什么"，节目单告诉你"某个台在某个时间段播什么"。它们之间唯一的连接点是tvg-id和 XMLTV 里<channel id="...">的那个字符串，必须一字不差。频道列表可能一天改三次，节目单可能是每天凌晨批量生成一次，两者生命周期不同，硬绑在一起只会互相拖累。

我在实际部署里把节目单做成独立的静态文件服务：一个epg.xml放在 Web 目录下，定时任务每天生成一次，聚合面板只负责把列表里的tvg-id和它对齐。这样节目单生成失败顶多是"不显示节目信息"，不会导致"整个频道列表打不开"——故障隔离，这是运维的基本盘。

2. 格式解剖：M3U 和 XMLTV 里到底该写什么

这一节是全文的地基。这两个文件格式你要是能吃透，后面 90% 的"莫名其妙不生效"都不会发生。

2.1 M3U 里真正有用的就那几个标签

先看一份最小可用的、带节目单引用的播放列表长什么样：

#EXTM3U x-tvg-url="http://192.168.1.10:8080/epg.xml" #EXTINF:-1 tvg-id="demo.news.hd" tvg-name="示例新闻 HD" tvg-logo="http://192.168.1.10:8080/logo/news.png" group-title="新闻综合",示例新闻 HD http://192.168.1.20:8080/hls/news/index.m3u8 #EXTINF:-1 tvg-id="demo.doc.hd" tvg-name="示例纪实 HD" tvg-logo="http://192.168.1.10:8080/logo/doc.png" group-title="纪实",示例纪实 HD http://192.168.1.20:8080/hls/doc/index.m3u8

第一行#EXTM3U是文件头，必须存在，否则有些播放器直接判定文件非法。x-tvg-url是给客户端的"节目单提示"，理论上客户端读到它就会自己去拉节目单。但别指望它：实测下来，桌面播放器大多认，移动端一半认一半不认，电视盒子基本不认。所以你的分发页面或者配置说明里，必须同时提供"手动填写节目单地址"的路径。

#EXTINF:-1里的-1是时长占位。直播流没有确定时长，业界惯例写-1。写0有的客户端会当成点播处理，写具体秒数更是自找麻烦。

后面那串key="value"是属性区，逗号后面是显示名。这里有个细节值得说：显示名和tvg-name不一致的时候，不同客户端表现不同。我的做法是让两者完全一致，避免歧义。

再往下那行是流地址，必须紧跟在#EXTINF行的下一行，中间不能有空行，不能有注释。空行会被某些解析器当成"条目结束"，导致地址被丢掉。这个坑我见过不止一次，有人手工编辑列表时为了"好看"在每个频道之间加了空行，结果一半频道消失。

2.2 tvg-id 是整条链路的主键

把tvg-id理解成数据库主键，一点都不夸张。它同时被三个地方引用：

命名上我有一套自己的规矩，用点号分层的反向域名风格：

demo.news.hd 自家新闻高清 demo.news.sd 自家新闻标清 demo.doc.hd 自家纪实高清

好处是：一、绝对不会和外部节目单源撞车；二、排序的时候天然按字母聚簇；三、一眼能看出归属和清晰度。千万不要用中文当 ID，看着直观，但一旦某个环节要做 URL 编码或者大小写转换就会炸，而且肉眼极难发现两个看起来一样实则不同的中文 ID。

还有一种常见错误：同一份列表里两个不同频道用了同一个tvg-id。结果是节目单只会挂到第一个匹配上的频道，第二个永远显示"暂无节目信息"。这种问题特别隐蔽，因为两个频道都能正常播放。

2.3 XMLTV 的时间格式，两个必踩的坑

XMLTV 长这样：

<?xml version="1.0" encoding="UTF-8"?> <tv generator-info-name="own-epg"> <channel id="demo.news.hd"> <display-name lang="zh">示例新闻 HD</display-name> <icon src="http://192.168.1.10:8080/logo/news.png"/> </channel> <programme start="20250601120000 +0800" stop="20250601130000 +0800" channel="demo.news.hd"> <title lang="zh">午间播报</title> <desc lang="zh">本期内容为示例占位，实际请替换为自有节目单。</desc> <category lang="zh">新闻</category> </programme> </tv>

坑一：时间格式必须是YYYYMMDDHHMMSS，不能带横杠、冒号、空格分隔符。2025-06-01 12:00:00这种写法在纯标准解析器里会直接报错或者被忽略，表现就是整个节目单一条都不显示，但文件本身"看起来没问题"。我第一次踩这个坑的时候排查了两个小时，最后是拿xmllint校验才发现的。

坑二：时区后缀不写，默认按 UTC 处理。上面那个+0800是关键。如果你生成节目单的脚本忘了带时区，本地时间 12:00 的节目在客户端上会显示成 20:00，整整差 8 小时。而且这个错特别有迷惑性——节目单有内容，只是全部错位，很多人第一反应是"客户端 bug"，反复重装播放器。

我的做法是在生成脚本里强制用带时区的格式化，绝不用"本地时间直接拼字符串"这种野路子。后面 4.4 节有个可运行的例子。

还有一个不那么明显但很致命的问题：<programme>的channel属性值必须和<channel id="">完全一致，包括大小写。有些播放器是大小写敏感的，demo.news.hd和Demo.News.HD在它眼里是两个频道。

3. 部署实操：从空目录到面板跑起来

好，格式说清楚了，开始动手。这一节我按"一个空目录起步"的节奏走，所有路径、端口、镜像名我全部用占位符，你换成自己的就行。

3.1 目录规划：先想好数据放哪

先把目录结构定死，这个顺序不能反。先跑容器再想数据放哪，最后一定是一堆散落在/var/lib/docker里的孤儿卷。

/srv/live-panel/ ├── docker-compose.yml ├── data/ # 容器持久化目录，权限要给对 │ ├── cache/ # 运行缓存 │ └── config/ # 面板配置 ├── playlist/ # 你手工维护的源列表（只读挂载） │ ├── source-a.m3u │ └── source-b.m3u └── web/ # 对外静态文件：epg.xml、台标 ├── epg.xml └── logo/

几个经验点：

playlist/用只读挂载（:ro）。容器里的程序不需要改它，给了写权限哪天程序出 bug 把你原始源文件覆盖了，哭都来不及。

web/单独拿出来不挂进容器，直接用宿主机上的 Nginx 提供静态服务。理由是台标和节目单都是纯静态文件，走 Nginx 比走应用容器快，还能加缓存头，而且节目单生成脚本挂掉的时候不影响频道列表。

data/的属主一定要提前改好。很多面板容器内部以非 root 用户跑，宿主机上的目录如果属主是 root 且权限是 755，容器里写不进去，表现是"启动成功但配置保存不上"，日志里只有一行看起来无害的权限错误。

3.2 docker-compose 落地

services: live-panel: image: your-registry.example/live-panel:latest # 换成你实际使用的镜像地址 container_name: live-panel restart: unless-stopped ports: - "8080:8080" environment: TZ: Asia/Shanghai PUBLIC_URL: "http://192.168.1.10:8080" PLAYLIST_DIR: "/data/playlist" EPG_URL: "http://192.168.1.10:8080/epg.xml" CACHE_TTL: "300" volumes: - ./data:/data - ./playlist:/data/playlist:ro healthcheck: test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"] interval: 30s timeout: 5s retries: 3 start_period: 20s logging: driver: json-file options: max-size: "10m" max-file: "3"

逐项说为什么这么写：

TZ: Asia/Shanghai—— 这一行不是可有可无。节目单时间、日志时间戳全靠它。容器默认是 UTC，你在日志里看到的时间比本地早 8 小时，排查问题时很容易被带偏。我就因为没设这个，把一次"凌晨三点"的失败误判成"下午三点"，多绕了半小时。

PUBLIC_URL—— 聚合面板生成的播放列表地址里，如果写的是容器内部主机名或者127.0.0.1，你把这份列表丢给电视盒子，盒子根本连不上。必须让面板知道"对外应该用哪个地址"。填内网 IP 就行。

CACHE_TTL: 300—— 缓存有效期，单位秒。这个值太小会导致面板频繁回源，源站扛不住；太大则频道变更后要等五分钟才生效。300 秒是我试下来比较舒服的折中，改配置后等一会儿就好。

healthcheck—— 很多面板的healthz端点其实只返回静态 200，不检查内部状态，但至少能区分"进程活着"和"进程死了"。配合restart: unless-stopped，进程崩了能自己拉起来。

logging那两行是必须加的。默认 docker 的 json-file 日志无限增长，一个跑半年的容器能吃掉几十 G 磁盘。我有台机器就是这么被撑爆的，/var/lib/docker满了之后所有容器集体罢工，那个场面挺酸爽。

启动：

cd /srv/live-panel mkdir -p data/cache data/config playlist web/logo sudo chown -R 1000:1000 data # 换成容器内实际运行用户的 UID/GID docker compose up -d docker compose logs -f --tail=50

3.3 反向代理与首屏体验

如果只在局域网内用，直接http://192.168.1.10:8080最省事，别折腾 HTTPS。但如果要跨网段访问，或者你想在同一个域名下统一管理，加一层 Nginx：

server { listen 80; server_name media.lan; client_max_body_size 20m; location / { proxy_pass http://127.0.0.1:8080; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-Proto $scheme; proxy_read_timeout 60s; } location /epg.xml { alias /srv/live-panel/web/epg.xml; add_header Cache-Control "public, max-age=600"; } location /logo/ { alias /srv/live-panel/web/logo/; add_header Cache-Control "public, max-age=86400"; expires 1d; } }

这里用 80 端口不是为了"高级"，纯粹是因为几个播放器的地址输入框对端口号的处理很别扭，有的地方冒号会被吞掉，有的不支持非标准端口。少一个端口号，少一堆问题。

/epg.xml和/logo/单独走静态文件，加缓存头。台标基本不变，缓存一天；节目单每天更新，缓存十分钟。这两个缓存头加上之后，播放端切频道时拉取元数据明显快了一截，因为不用每次都回源。

3.4 首次开播的验证顺序，别跳步

我总结了一个固定顺序，每次部署新环境都按这个走，能省掉大量来回试错：

1. 先验源：curl -I那个.m3u8地址，看是不是 200，Content-Type是不是 HLS 类型。这一步不过，后面全白搭。
2. 再验切片：把 m3u8 内容拉下来，随便挑一个分片地址curl -I一下。如果索引 200 但分片 404，说明推流侧的问题，不是播放端的问题。
3. 验播放列表输出：curl http://192.168.1.10:8080/playlist.m3u，确认返回的是文本、有#EXTM3U头、频道数量对得上。
4. 验节目单：curl http://192.168.1.10:8080/epg.xml | head -20，确认能拿到 XML 且编码声明正确。
5. 验 ID 对齐：从播放列表里随便挑一个tvg-id，在 epg.xml 里grep一下，确认能搜到。
6. 最后上客户端。

这个顺序的核心逻辑是从下游往上游排查。反过来做的话，客户端黑屏你根本不知道是源挂了、聚合层没输出、还是节目单格式错导致整个列表被拒。

注意：第 3 步如果返回的播放列表是空的，先看面板日志里有没有"解析 0 个条目"之类的记录。绝大多数情况是源文件里#EXTINF和 URL 之间被塞了空行，或者整个文件用了 Windows 换行符导致解析器第一行就认不出来。

4. 频道数据清洗：让列表从"能用"到"好用"

部署跑起来只是及格线。真正决定这份列表好不好用的，是清洗环节。这一节是我花时间最多的地方，也是本文最想分享的部分。

4.1 命名、分组、排序的规范

先说命名。原始源里的频道名五花八门，有的是"频道A"，有的是"频道A高清"，有的是"频道A HD 1080P 稳定版"。直接拿这个给用户看，体验很差。

我的命名规则是主体名 + 空格 + 清晰度后缀：

示例新闻 HD 示例新闻 SD 示例纪实 HD

清晰度后缀只用HD/SD两种，不要搞1080P720P4K混着来。原因很简单：在手机屏幕上你根本分辨不出 1080 和 720，但列表里多出来的信息会让排列乱七八糟。真有 4K 需求的，单独放一个分组，别混在普通列表里。

分组用group-title，我一般控制在 6 到 10 个组。少于 6 个每组太长，滑起来累；多于 10 个用户找不到东西。一个参考划分：

"测试"这个分组很重要，我强烈建议你留一个。所有新接入的源先扔进去观察几天，稳定了再往正式分组挪。这样用户永远不会看到"某个台突然黑屏"，因为黑屏的台在测试组里就被你干掉了。

排序我按"用户打开第一屏能看到什么"来定。第一屏大概能显示 8 到 12 个频道，所以优先级最高的几个必须排最前面。M3U 是按文件顺序渲染的，没有别的排序机制，顺序就是优先级。

4.2 去重与失效源剔除

去重有两个维度：地址重复和名称重复。

地址重复好处理，URL 完全一样就留一个。名称重复麻烦一点，因为可能是同一个频道的不同清晰度版本。我的规则是：tvg-id相同视为同一频道，保留码率高的那个（通常能从 URL 里的路径或者源文件的其他属性看出端倪），另一个要么删掉，要么改成.sd后缀单独保留。

失效源剔除建议做成常态化的定时任务，而不是一锤子买卖。我的做法是每小时跑一次探测：对每个频道地址发一个HEAD请求，超时 5 秒，连续 3 次失败就标记为不可用，从输出列表里暂时摘掉；恢复后自动加回来。

#!/usr/bin/env bash # 简化版探测脚本，实际使用建议加并发控制和结果落库 while read -r url; do if curl -sS -o /dev/null -m 5 -w "%{http_code}" -I "$url" | grep -qE '^(200|302)$'; then echo "OK $url" else echo "FAIL $url" fi done < urls.txt

这里有个反直觉的经验：不要因为探测失败就永久删除。很多源只是临时抖动，或者探测时刚好在切片切换的瞬间。摘掉和删除是两回事，摘掉还能恢复，删了就得重新找。我吃过这个亏，一次批量清理删了三十多个"失效"频道，第二天一大半自己好了。

4.3 节目单匹配与图标处理

节目单匹配的本质是字符串比对，没有任何智能可言。所以干净的数据比聪明的算法重要得多。

匹配流程我固定成三步：

第一步，从播放列表里抽出所有tvg-id，导出成一个清单文件。第二步，从节目单 XML 里抽出所有<channel id="">，导出成第二个清单。第三步，两个清单做差集，看看谁没匹配上。

没匹配上的无非三种情况：播放列表里的 ID 在节目单里不存在（需要给节目单生成侧补数据）、节目单里的 ID 在播放列表里不存在（可以忽略，或者顺手清掉减小文件体积）、两边的 ID 拼写有细微差异（最常见，靠肉眼比对，建议直接diff两个排序后的清单）。

图标处理有几个务实的建议：

图标统一转成 PNG 或者 SVG，尺寸控制在 200×200 以内。原始来源的图标经常是几百 K 的大图，两百个频道加起来能有好几兆，播放端一次性拉取会明显卡顿。我一般批量压到 20K 以内。

路径统一用绝对 URL，写进tvg-logo属性里。相对路径在部分客户端里会被解析成"相对于播放列表地址"，如果播放列表是通过 API 动态生成的，相对路径基本必然失效。

文件命名跟着tvg-id走，比如demo.news.hd.png。这样脚本能自动匹配，加频道的时候不用手工配置图标路径。

4.4 一个把清洗脚本跑起来的完整例子

下面这个脚本干四件事：解析 M3U、按规则重命名和分组、去重、输出干净的 M3U 和对应的 XMLTV 骨架。用 Python 3，没有第三方依赖。

#!/usr/bin/env python3 import re import hashlib from datetime import datetime, timedelta, timezone from pathlib import Path from xml.sax.saxutils import escape SRC = Path("playlist/source-a.m3u") OUT_M3U = Path("web/playlist.m3u") OUT_EPG = Path("web/epg.xml") LOGO_BASE = "http://192.168.1.10:8080/logo" GROUP_MAP = { "news": "新闻", "doc": "纪实", "life": "生活", "self": "自建", } def parse_m3u(text: str): """解析 M3U，返回 [{attrs, name, url}, ...]""" items, cur = [], None for raw in text.splitlines(): line = raw.strip() if not line: continue if line.startswith("#EXTM3U"): continue if line.startswith("#EXTINF"): attrs = dict(re.findall(r'([\w-]+)="([^"]*)"', line)) name = line.rsplit(",", 1)[-1].strip() cur = {"attrs": attrs, "name": name} elif line.startswith("#"): continue elif cur is not None: cur["url"] = line items.append(cur) cur = None return items def normalize(item): """补齐 tvg-id / 分组 / 图标，缺什么补什么""" url = item["url"] # 用 URL 摘要生成稳定的兜底 ID，避免每次运行结果不同 fallback_id = "self." + hashlib.md5(url.encode()).hexdigest()[:10] tid = item["attrs"].get("tvg-id") or fallback_id item["id"] = tid item["attrs"]["tvg-id"] = tid item["attrs"]["tvg-name"] = item["name"] item["attrs"]["tvg-logo"] = f"{LOGO_BASE}/{tid}.png" if not item["attrs"].get("group-title"): # 从 ID 的第二段推断分组，推断不出来就归到自建 seg = tid.split(".") key = seg[1] if len(seg) > 1 else "self" item["attrs"]["group-title"] = GROUP_MAP.get(key, "自建") return item def dedup(items): seen, out = set(), [] for it in items: if it["id"] in seen: print(f"[skip] 重复 ID: {it['id']} -> {it['name']}") continue seen.add(it["id"]) out.append(it) return out def write_m3u(items, path: Path, epg_url: str): lines = [f'#EXTM3U x-tvg-url="{epg_url}"', ""] for it in items: a = it["attrs"] lines.append( f'#EXTINF:-1 tvg-id="{a["tvg-id"]}" tvg-name="{a["tvg-name"]}" ' f'tvg-logo="{a["tvg-logo"]}" group-title="{a["group-title"]}",{it["name"]}' ) lines.append(it["url"]) path.parent.mkdir(parents=True, exist_ok=True) path.write_text("\n".join(lines) + "\n", encoding="utf-8") print(f"[ok] 写出 {len(items)} 个频道 -> {path}") def write_epg(items, path: Path): tz = timezone(timedelta(hours=8)) now = datetime.now(tz).replace(minute=0, second=0, microsecond=0) start = now.strftime("%Y%m%d%H%M%S +0800") stop = (now + timedelta(hours=1)).strftime("%Y%m%d%H%M%S +0800") buf = ['<?xml version="1.0" encoding="UTF-8"?>', '<tv generator-info-name="own-epg">'] for it in items: buf.append(f' <channel id="{escape(it["id"])}">') buf.append(f' <display-name lang="zh">{escape(it["name"])}</display-name>') buf.append(f' <icon src="{escape(it["attrs"]["tvg-logo"])}"/>') buf.append(" </channel>") for it in items: buf.append( f' <programme start="{start}" stop="{stop}" channel="{escape(it["id"])}">' ) buf.append(' <title lang="zh">占位节目</title>') buf.append(' <category lang="zh">其他</category>') buf.append(" </programme>") buf.append("</tv>") path.parent.mkdir(parents=True, exist_ok=True) path.write_text("\n".join(buf) + "\n", encoding="utf-8") print(f"[ok] 写出节目单 -> {path}") if __name__ == "__main__": raw = SRC.read_text(encoding="utf-8-sig") items = [normalize(x) for x in parse_m3u(raw)] items = dedup(items) write_m3u(items, OUT_M3U, "http://192.168.1.10:8080/epg.xml") write_epg(items, OUT_EPG)

几个实现细节值得单独拎出来说：

encoding="utf-8-sig"—— 读取时用这个，能自动吃掉 BOM 头。Windows 下编辑过的 M3U 经常带 BOM，标准解析器读到\ufeff#EXTM3U会认不出文件头。这个坑很隐蔽，因为文件在编辑器里看起来完全正常。

用 URL 的 MD5 前 10 位做兜底 ID —— 保证同一个地址每次跑出来的 ID 都一样。如果改用自增序号或者时间戳，每次运行 ID 都变，节目单匹配全废。

时区用timezone(timedelta(hours=8))而不是astimezone()依赖系统时区 —— 容器里的时区配置不一定可靠，显式写死最稳。

escape()处理所有写入 XML 的文本 —— 频道名里出现&、<、>的概率比你想象的高，不转义的话整份 XML 直接非法，解析器报错，表现就是"节目单一条都不显示"。

跑起来：

python3 scripts/build_playlist.py xmllint --noout web/epg.xml && echo "XML 校验通过"

xmllint这一步建议写进定时任务里。格式错的 XML 能正常写盘，但播放端一条都读不出来，不做校验的话你永远不知道是生成错了还是客户端不认。

5. 播放端适配与性能调优

聚合层输出对了，不代表用户体验好。真正决定"打开秒开、切换流畅、看半小时不卡"的，是下面这几件事。

5.1 HLS 的刷新节奏与会话保持

HLS 的本质是"不断更新的分片列表"。播放器加载 m3u8 之后，要按#EXT-X-TARGETDURATION的节奏反复重新拉取这个索引文件，才能跟上直播进度。

自建推流的时候，参数配错会直接导致"能播但频繁缓冲"：

ffmpeg -re -i input.mp4 \ -c:v libx264 -preset veryfast -tune zerolatency -g 50 \ -c:a aac -b:a 128k -ar 48000 \ -f hls -hls_time 4 -hls_list_size 6 \ -hls_flags delete_segments+append_list \ -hls_segment_filename "/srv/live-panel/hls/ch1/seg_%05d.ts" \ /srv/live-panel/hls/ch1/index.m3u8

-hls_time 4是分片时长，4 秒是通用折中值。设 2 秒延迟低但请求频繁，设 10 秒请求少但延迟高、拖动体验差。

-hls_list_size 6是索引文件里保留的分片数量。6 个 4 秒分片等于 24 秒窗口，足够播放器缓冲和重连。设太小（比如 3）网络一抖就断流，设太大索引文件变长、启动加载变慢。

-g 50是关键帧间隔。这个值必须和分片时长相匹配：帧率 25fps 的情况下，-g 50等于每 2 秒一个关键帧，能被 4 秒的分片边界整除。如果-g和hls_time不匹配，分片边界落不到关键帧上，播放器切分片时会花屏或者卡顿一下。这个细节很多教程不提，但它是"看着能播、实际卡顿"的头号原因。

delete_segments让 FFmpeg 自动清理过期分片。不加这个参数，跑一天磁盘就满了。

5.2 转码到底要不要开

这是被问得最多的问题。我的答案：能不开就不开。

转码的代价是指数级的。一个 1080p 的流用libx264软转，在中端 CPU 上大概吃掉 1.5 到 2 个物理核。四个频道同时转，一台小主机直接满载，然后所有频道一起卡。表现是"单看一个很流畅，四台设备同时看就集体卡"，很多人以为是带宽问题，其实是 CPU 打满了。

什么情况必须转？源是 H.265 编码但终端只支持 H.264；源的码率太高（比如 8Mbps）而目标是移动网络；源的分辨率超出终端解码能力。这三种是硬需求，绕不开。

其余情况尽量用-c:v copy直接复制视频流，只重封装不重编码：

ffmpeg -re -i rtmp://127.0.0.1/live/ch1 \ -c:v copy -c:a aac -b:a 128k -ar 48000 \ -f hls -hls_time 4 -hls_list_size 6 \ -hls_flags delete_segments \ /srv/live-panel/hls/ch1/index.m3u8

注意音频还是转了一下，因为源音频格式（比如 AC3）在移动端兼容性差，而音频转码的开销几乎可以忽略。视频流原样复制，CPU 占用接近零，一台机器扛十几个频道毫无压力。

如果确实要转，优先考虑硬件编码。带核显的机器用-c:v h264_qsv或者-c:v h264_vaapi，CPU 占用能降一个数量级。代价是画质略差、参数调优更麻烦，但对家庭场景完全够用。

5.3 缓存与请求压力

一个 20 个频道的列表，播放端切一轮就是 20 次索引请求，加上台标和节目单请求，一次完整的"浏览一遍"可能产生上百个请求。如果每个请求都穿透到后端，面板很容易被压垮。

三层缓存我是这么配的：

节目单文件本身建议也做个瘦身。一份几百频道的完整 XMLTV，覆盖七天节目，轻松超过 20MB。移动端拉这个文件要好几秒，体验很差。两个办法：一是只保留 24 到 48 小时的节目，二是用 gzip 压缩。Nginx 加一行gzip_types application/xml text/xml;就能把体积压到原来的五分之一左右。

提示：判断卡顿到底是网络问题还是服务端问题，有个简单办法——在卡顿的客户端上打开同一台机器的其他 HTTP 服务（比如台标图片）。如果图片秒开但视频卡，问题在流不在网；如果图片也慢，先查网络和服务端负载。

6. 常见问题排查实录

这一节全是我自己踩过的坑，按"症状 - 原因 - 处理"整理，遇到问题先扫表。

6.1 症状速查表

6.2 几个特别值得说的坑

换行符问题。这个我必须单独讲，因为它的迷惑性太强。在 Windows 上编辑过的 M3U，行尾是\r\n。有些解析器在切分时只认\n，结果是每行末尾多一个\r，导致 URL 变成http://xxx.m3u8\r。表现是"列表能看到频道名，一点就报错"。用file命令看一眼，或者cat -A看看有没有^M，两秒就能确认。

中文频道名的编码。M3U 文件如果是 GBK 编码，UTF-8 的播放器读出来就是一堆乱码。统一用 UTF-8 无 BOM 保存，别用编辑器默认编码。

播放列表地址和节目单地址不同源。有的播放器在处理x-tvg-url时会受同源策略限制。如果你的播放列表在 8080 端口、节目单在 80 端口，某些客户端会拒绝加载节目单。解决办法是把两者放在同一个域名和端口下，用路径区分。

容器时间不对导致定时任务乱跑。节目单生成脚本跑在容器里，容器时区是 UTC，cron里写的 "每天 6 点" 实际在本地时间下午 2 点执行。结果就是用户上午看的时候，节目单是昨天的。查这个问题的时候先docker exec进去date一下。

同一份列表给所有人用。一开始我图省事，所有设备发同一个播放列表地址。后来发现不同设备能力差太多了：盒子不支持 H.265，手机流量看 8Mbps 直接卡死。正确做法是按终端生成多份列表，面板里一般支持"按能力过滤"或者"多套输出配置"，值得花时间配一下。

7. 使用边界与长期维护

技术聊完了，说几句不那么技术但更重要的。

这套东西能长期稳定跑下去的前提，是你对内容源有清晰的权利边界。我自己的实践范围就三块：自己拍摄的素材、自己搭建的推流服务（比如内网演播室、会议室摄像头）、以及明确获得授权的素材。超出这个范围的，不管技术上多容易实现，都不在我的操作范围内。这不是唱高调，是我见过太多"跑了两周突然整个服务不可用"的例子，原因往往是上游内容本身不具备持续提供的条件，你搭在上面的所有工程都白费。

从维护角度，我建议把整条链路当成一个正经的小系统来对待：目录结构固定下来别乱动，清洗脚本进版本管理，配置文件里所有路径和端口集中在一处，定时任务加日志和失败告警。我现在这套跑了挺长时间，中间出过的最大的问题不是技术问题，是我自己三个月没登录，忘了某个路径改过，排查时对着旧笔记折腾了半天。后来我在仓库根目录放了一个README，就写三件事：怎么启动、日志在哪、出问题先看哪。比任何文档都管用。

最后分享一个我觉得最值的小习惯：每次改完清洗脚本，别直接覆盖生产环境的播放列表，先生成到playlist.next.m3u，用diff对比一下这次到底动了哪些频道。确认没问题再mv覆盖。这个动作只多花十秒，但能挡住 90% 的"手滑把整个列表搞坏"的事故。我现在的流程是脚本跑完自动 diff 并把结果写进日志，哪天列表突然少了二十个频道，翻日志一眼就能看到是哪条规则把它们筛掉了。