IPTV Aggregator 超详细部署指南（小白也能会）
核心目标：零基础在飞牛 NAS（FnOS）上部署自动维护的 IPTV 直播源，支持自动更新、按需求筛选，彻底解决手动找源、源失效问题。
一、前置准备（逐点确认，避免踩坑）
1. 设备要求
必须是安装了 飞牛 OS（FnOS） 的 NAS 设备（如飞牛系列 NAS，确认系统版本≥3.0，过低版本可能不支持 Docker 项目功能）。
NAS 需连接家庭网络，且能 正常访问互联网（爬虫需要抓取公网直播源，断网会导致部署失败）。
2. 工具准备
无需额外下载软件，直接使用 NAS 桌面自带的两个应用：
「文件管理」：用于创建存储目录（存放直播源文件）。
「Docker」：用于部署 IPTV 聚合服务（核心工具，确保已默认安装，未安装可在 NAS 应用商店搜索 “Docker” 安装）。
3. 提前了解的关键概念（新手必看）
Docker 项目（Compose）：打包好的服务集合，一键启动即可，无需手动配置复杂参数。
端口：服务对外的访问入口（默认 50086，若被其他服务占用需修改）。
环境变量：自定义服务规则的参数（如优先省份、更新间隔，后续会详细说明如何修改）。
NAS IP：NAS 在家庭网络中的地址（如 192.168.1.100，后续用于访问直播源，提前记好，可在 NAS 网络设置中查看）。
二、部署步骤（图文级详细，每步附操作截图说明）
第一步：创建存储目录（存放直播源文件，关键！）
打开 NAS 桌面，找到「文件管理」图标，双击打开。
在左侧导航栏中，找到「本地存储」→ 找到或新建「docker」文件夹（若已有则直接进入，无则右键→新建→文件夹，命名为 “docker”，字母全小写）。
进入「docker」文件夹后，右键→新建→文件夹，命名为 “iptv”（字母全小写，不可改其他名称，否则后续服务找不到目录）。
进入「iptv」文件夹后，再次右键→新建→文件夹，命名为 “data”（字母全小写，用于存放生成的直播源文件 iptv.txt）。
最终目录结构确认：docker/iptv/data（必须严格一致，否则数据无法持久化，重启服务后直播源会丢失）。
第二步：创建 Docker 项目（Compose 部署核心步骤）
回到 NAS 桌面，找到「Docker」图标，双击打开（首次打开可能需要加载 2-3 秒，耐心等待）。
打开 Docker 后，点击左侧菜单栏的「项目」（英文：Compose），进入项目管理页面。
点击页面右上角的「创建项目」按钮（蓝色按钮，位置在页面右上角，容易找到）。
弹出创建项目窗口，按以下要求填写：
项目名称：输入 “iptv-auto”（可自定义，但建议用此名称，方便后续管理，字母全小写，无特殊符号）。
路径：点击右侧「浏览」按钮，找到第一步创建的「docker/iptv」文件夹，选中后点击「确定」（路径必须是 docker/iptv，否则服务无法读取配置和存储数据）。
其他默认选项不变（如 “版本” 默认选择 3，无需修改）。
点击「下一步」，进入 Compose 配置编辑页面（核心中的核心，务必仔细）。
第三步：配置 Compose 文件（复制 + 修改，新手也能搞定）
在编辑框中，删除默认的示例代码（若有），将以下完整代码复制粘贴进去（代码中的中文注释可保留，不影响运行）：
yaml
services:
aggregator:
# 官方镜像版本（v2.1 稳定版，不建议修改版本号）
image: yiwanaishare/iptv-aggregator:2.1
# 容器名称（固定，方便后续查看日志和管理）
container_name: iptv-aggregator
# 重启策略：除非手动停止，否则异常退出后自动重启
restart: unless-stopped
# 端口映射：左侧是 NAS 本地端口，右侧是容器内部端口（不可改）
ports:
– “50086:50086” # 若 50086 被占用，修改左侧数字（如 10086:50086）
# 环境变量（用户可根据需求修改，关键配置！）
environment:
# 优先关键词：按“省份,运营商”格式填写，逗号分隔（如“广东,电信”“浙江,移动”）
# 示例：想优先看北京联通的频道，就填 – PRIORITY_KEYWORDS=北京,联通
– PRIORITY_KEYWORDS=山西,联通
# 自动更新间隔：单位小时（建议 6-24 小时，数值越小更新越频繁）
– REFRESH_INTERVAL_HOURS=12
# 时区设置：固定为 Asia/Shanghai（中国时区，不可改）
– TZ=Asia/Shanghai
# 数据卷映射：将容器内的直播源文件同步到 NAS 本地目录
volumes:
– ./data:/app/data # 对应第一步创建的 docker/iptv/data，不可改
按自身需求修改「环境变量」中的配置（其他部分不建议新手修改）：
修改优先关键词：比如你在上海，用的电信网络，就把 PRIORITY_KEYWORDS=山西,联通 改为 PRIORITY_KEYWORDS=上海,电信（省份和运营商可自由组合，如 “江苏，联通”“山东，移动”）。
修改更新间隔：若想每 6 小时更新一次，把 REFRESH_INTERVAL_HOURS=12 改为 REFRESH_INTERVAL_HOURS=6（最小可设 1 小时，太频繁可能占用 NAS 资源）。
修改端口（若冲突）：若后续启动后提示端口被占用，把 ports 中的 50086:50086 改为 10086:50086（左侧数字可自定义，1024-65535 之间均可）。
配置完成后，点击页面右下角的「构建并启动」按钮（蓝色按钮），开始拉取镜像并启动服务。
等待启动：首次启动需要拉取镜像（约 2-5 分钟，取决于网络速度），可在「项目」页面查看状态，显示「运行中」且图标变绿，说明启动成功。
三、验证部署是否成功（关键步骤，确认是否可用）
1. 查看日志，确认爬虫正在工作
打开 Docker → 点击左侧「容器」→ 找到「iptv-aggregator」容器（名称和配置文件中一致）。
点击该容器右侧的「日志」按钮（图标为记事本样式），打开日志页面。
查看日志内容：
若看到 Trigger spider collection… 字样，说明爬虫任务已下发，正在抓取直播源（正常现象）。
此时可点击左侧「容器」中的「iptv-spider」容器（自动生成的），查看其日志，会看到大量刷屏的扫描记录（说明爬虫在疯狂抓取源，耐心等待）。
2. 确认直播源生成（核心验证）
等待 5-10 分钟（爬虫抓取需要时间，若网络慢可等待 15 分钟）。
回到「iptv-aggregator」容器的日志页面，若看到 Playlist generated 或 Saved iptv.txt 字样，说明直播源已生成成功！
辅助验证：打开 NAS 的「文件管理」→ 进入 docker/iptv/data 目录，若能看到「iptv.txt」文件（大小不为 0），说明部署成功（该文件就是直播源列表，可打开查看频道内容）。
四、使用方法（电视 / 播放器导入，直接观看）
1. 获取直播源地址
打开电脑或手机的浏览器（确保和 NAS 在同一家庭网络）。
在地址栏输入：http://你的NAS_IP:50086/iptv（关键！替换成你的 NAS 实际 IP）。
示例：若你的 NAS IP 是 192.168.1.105，端口未修改，则地址为 http://192.168.1.105:50086/iptv。
访问后，浏览器会显示纯文本的频道列表（已按你设置的优先关键词排序，高清频道在前），说明地址有效。
2. 导入电视 / 播放器（支持多种设备，以常见工具为例）
示例 1：TVBox 导入
打开 TVBox 应用 → 点击首页的「设置」→ 找到「播放列表」选项。
选择「添加播放列表」→ 选择「M3U 地址」。
在地址栏粘贴上面获取的直播源地址（如 http://192.168.1.105:50086/iptv），点击「确定」。
等待加载完成，即可看到所有频道，点击即可播放（支持秒切、无广告）。
示例 2：TiviMate 导入
打开 TiviMate → 点击左侧菜单栏的「设置」→ 「播放列表」→ 「添加播放列表」。
选择「从 URL 添加」→ 粘贴直播源地址 → 点击「下一步」。
系统自动加载频道，加载完成后即可观看（可在设置中调整画质、排序）。
示例 3：手机 / 电脑播放器导入（如 VLC）
打开 VLC 播放器 → 点击「媒体」→ 「打开网络串流」。
粘贴直播源地址 → 点击「播放」，即可在手机 / 电脑上观看。
五、常见问题（FAQ）+ 避坑指南（新手必看）
1. 部署后访问地址提示 “无法访问” 或 “接口为空”
原因 1：爬虫未完成首次抓取（最常见）→ 解决方案：耐心等待 5-15 分钟，查看「iptv-aggregator」日志，确认是否有 Playlist generated。
原因 2：NAS IP 输入错误 → 解决方案：在 NAS 网络设置中查看正确的内网 IP（如 192.168.xx.xx），确保浏览器和 NAS 在同一网络。
原因 3：端口冲突 → 解决方案：修改 Compose 配置中的 ports 左侧端口（如改为 10086:50086），重启项目后，访问地址改为 http://NAS_IP:10086/iptv。
2. 日志提示 “Spider 密码错误”
原因：Spider 容器默认密码被修改 → 解决方案：默认密码为 yiwan123，若手动修改过 Spider 后台密码，需在 Compose 配置的「environment」中添加一行 – SPIDER_PASSWORD=你的新密码，重启项目即可。
3. 扫不到源（频道数量为 0）
原因：筛选类型设置错误 → 解决方案：若家里没有组播环境（大部分家庭没有），需在 Compose 配置的「environment」中添加一行 – FILTER_TYPE=hotel（默认是 hotel，若被修改为 multicast 会导致扫不到源），添加后重启项目，重新等待爬虫抓取。
4. 直播源文件 iptv.txt 可以手动修改吗？
不可以！该文件由服务自动生成，每次更新（按设置的间隔）会覆盖手动修改的内容，若需调整频道排序，可修改「PRIORITY_KEYWORDS」关键词，让服务自动优先排序。
5. 如何分享给家人 / 朋友？
若家人和你在同一家庭网络，直接分享 http://NAS_IP:50086/iptv 地址即可。
若想外网访问，需在 NAS 中设置端口映射（路由器转发），但不建议（可能存在安全风险，且直播源可能涉及版权问题）。
六、后续维护与优化
1. 查看更新状态
每次自动更新时，「iptv-aggregator」日志会显示 Start refreshing playlist…，更新完成后显示 Playlist generated，可定期查看日志确认服务正常运行。
2. 修改配置（如更换省份 / 运营商）
打开 Docker → 「项目」→ 找到「iptv-auto」→ 点击右侧「编辑」→ 修改 Compose 中的环境变量 → 点击「保存并重新构建」，服务会重启并应用新配置（重启后需等待 5-10 分钟重新生成直播源）。
3. 停止 / 卸载服务
停止：Docker → 「项目」→ 找到「iptv-auto」→ 点击右侧「停止」。
卸载：先停止服务，再点击「删除」，同时删除 docker/iptv 目录（彻底清理数据）。