Первые шаги для запуска сайта¶

В этой статье мы шаг за шагом запустим собственный сайт-агрегатор IPTV-плейлистов — от простейшего варианта до полной конфигурации с кешем и тонкой настройкой проверки.

Программа iptvc уже должна быть установлена. Все команды ниже выполняются в терминале из директории, где лежит бинарник.

Шаг 1. Запускаем пустой сайт¶

Минимальный запуск — одна команда:

./iptvc serve

Сайт откроется на http://localhost:8800. Это пустая страница: нет ни одного плейлиста, потому что программе пока неоткуда их взять.

Чтобы изменить порт или хост, не трогая файл конфигурации:

./iptvc serve -p 3000 --host 0.0.0.0

Подробнее об этих флагах — в документации команды serve.

Шаг 2. Добавляем плейлисты¶

Список плейлистов описывается в файле playlists.ini. Создадим его рядом с iptvc:

playlists.ini

[ru]
name = Российские каналы
desc = Основные федеральные каналы
pls = 'https://example.com/ru.m3u'
src = 'https://example.com/ru-playlist'

[movies]
name = Фильмы
pls = 'https://example.com/movies.m3u'

Каждая секция [code] — это плейлист. Код используется в коротких ссылках вида http://localhost:8800/ru. Параметр pls обязателен, остальные — по желанию.

Теперь запустим:

./iptvc serve

Сайт покажет оба плейлиста, но их статус — unknown (неизвестно). Это нормально: программа знает о них, но ещё не проверяла. Чтобы статусы появились, нужно включить фоновую проверку.

Путь к ini-файлу

Если файл лежит не рядом с программой, укажите путь через флаг -i или в config.yml → app.playlists.

Шаг 3. Включаем фоновую проверку¶

Без проверки сайт просто показывает список. Чтобы плейлисты и каналы проверялись автоматически, добавим флаг --check:

./iptvc serve --check

Теперь программа в фоне загружает каждый плейлист, парсит каналы и проверяет их доступность. Результаты сразу попадают в оперативную память и отображаются на сайте.

Можно настроить интервал между циклами проверки:

# пауза 120 секунд между циклами, бесконечно
./iptvc serve --check --playlists-all-cooldown 120

# проверить один раз и остановить
./iptvc serve --check --repeat 1

Если не хочется каждый раз писать --check, можно включить проверку через config.yml:

config.yml

check:
  startOnServe: true

Тогда обычный ./iptvc serve автоматически запустит фоновую проверку.

Шаг 4. Настраиваем внешний вид сайта¶

Сайт можно настроить под себя: заголовок, иконку, навигацию в шапке и ссылки в подвале. Всё это — в секции site файла config.yml.

config.yml

site:
  baseUrl: http://localhost:8800
  repo-url: https://git.axenov.dev/IPTV
  pageSize: 20                       # пагинация по 20 плейлистов на страницу (0 — без пагинации)
  favicon: ./favicon.ico               # путь к иконке
  header:
    title: Мой IPTV                   # заголовок в шапке и вкладке браузера
    menu:
      - title: Документация
        url: /docs
        icon: document-text-outline
      - title: Telegram
        icon: bullhorn-variant-outline
        children:
          - title: Канал
            url: https://t.me/my_channel
            icon: megaphone-outline
          - title: Чат
            url: https://t.me/my_chat
            icon: chatbubbles-outline
  footer:
    links:
      - title: Исходники
        url: https://git.axenov.dev/IPTV
        icon: code-slash-outline
      - title: Мой сайт
        url: https://example.com
        icon: person-outline

Где взять имя иконки?

Откройте галерею иконок на сайте Pictogrammers. Кликнув на нужную иконку, вы увидите её имя. Именно это имя используется в конфигурации iptvc.

Скриншот

baseUrl

Параметр baseUrl используется для формирования внутренних ссылок. Если публикуете сайт на домене, укажите его здесь, например https://my-iptv.ru.

Шаг 5. Добавляем теги каналам¶

Теги помогают посетителям находить каналы по темам: спорт, фильмы, музыка и так далее. Правила описываются в файле channels.json.

channels.json

[
  {
    "tvg-id": "^ru-",
    "tags": ["russian"]
  },
  {
    "title": "спорт",
    "tags": ["sport"]
  },
  {
    "title": "кино|фильм",
    "tags": ["film"]
  }
]

Путь к файлу указывается в config.yml → app.tags или через флаг -t:

./iptvc serve --check -t /path/to/channels.json

Полный список доступных тегов — в справочнике по channels.json.

Шаг 6. Подключаем кеш Valkey¶

По умолчанию результаты проверки хранятся только в оперативной памяти. Если программу перезапустить — все результаты пропадут, и плейлисты снова станут unknown до следующей проверки.

Кеш решает эту проблему: результаты сохраняются в кеше и переживают перезапуск. Включается в config.yml:

config.yml

cache:
  enabled: true
  host: cache
  port: 6379
  ttl: 3600          # секунды (по умолчанию 3600)

Или через переменные окружения:

CACHE_ENABLED=true CACHE_TTL=3600 ./iptvc serve --check

Или через флаги:

./iptvc serve --check --cache-enabled --cache-host 192.168.1.10 --cache-ttl 1800

Valkey, KeyDB или Redis

Valkey — это открытый форк Redis, а KeyDB — ещё один форк. Все они полностью совместимы по протоколу. Подойдёт любой из них. Если кеш включён, но сервер недоступен — сайт продолжит работать, просто без кеширования.

Шаг 7. Тонкая настройка проверки¶

Когда плейлистов много, полезно управлять параллелизмом, таймаутами и задержками. Все параметры — в секции check файла config.yml.

Параллелизм¶

config.yml

check:
  playlists:
    maxRoutines: 10       # сколько плейлистов проверять одновременно
    perRoutine: 5         # сколько плейлистов в одной процедуре
  channels:
    maxRoutines: 100      # сколько каналов проверять одновременно
    perRoutine: 20        # сколько каналов в одной процедуре

Чем больше значения — тем быстрее проверка, но выше нагрузка на процессор и сеть. Начните со значений по умолчанию и увеличивайте при необходимости.

Таймауты¶

config.yml

check:
  playlists:
    timeout: 10            # секунд на загрузку плейлиста
  channels:
    timeout: 10            # секунд на проверку одного канала
    byteRange: 512        # сколько байт скачать от сервера канала

Если плейлисты или каналы медленные, увеличьте timeout. Если сервер блокирует большие запросы — уменьшите byteRange.

Задержки (cooldown)¶

Чтобы не перегружать серверы-источники, между проверками можно делать паузы. Параметры поддерживают как фиксированное значение, так и диапазон [min, max] — тогда пауза будет случайной при каждом проходе:

config.yml

check:
  playlists:
    allCooldown: 5              # 5 секунд после всех плейлистов
    oneCooldown: [1, 3]         # 1–3 секунды после каждого плейлиста
  channels:
    cooldown: 0                  # 0 секунд после каждого канала

User-Agent¶

Некоторые серверы блокируют запросы без правильного User-Agent. Можно указать один или несколько — тогда при каждом запросе будет выбран случайный:

config.yml

check:
  playlists:
    userAgent:
      - Mozilla/5.0 WINK/1.31.1 (AndroidTV/9) HlsWinkPlayer
      - Mozilla/5.0 (Linux; Android 11) AppleWebKit/537.36
  channels:
    userAgent: Mozilla/5.0 (Linux; Android 11) AppleWebKit/537.36

Все эти параметры можно также задавать через переменные окружения или CLI-флаги — они имеют наивысший приоритет.

Полный пример¶

Соберём всё вместе в одном config.yml:

config.yml

app:
  timezone: GMT+3
  debug: false
  logLevel: info
  playlists: ./playlists.ini
  tags: ./channels.json

server:
  host: 0.0.0.0
  port: 8800

site:
  baseUrl: https://my-iptv.ru
  repo-url: https://git.axenov.dev/IPTV
  pageSize: 20
  favicon: ./favicon.ico
  header:
    title: Мой IPTV
    menu:
      - title: Статус
        url: https://status.my-iptv.ru
        icon: pulse-outline
      - title: Документация
        url: /docs
        icon: document-text-outline
      - title: Telegram
        icon: bullhorn-variant-outline
        children:
          - title: Канал
            url: https://t.me/my_channel
            icon: megaphone-outline
          - title: Чат
            url: https://t.me/my_chat
            icon: chatbubbles-outline
  footer:
    links:
      - title: Исходники
        url: https://git.axenov.dev/IPTV
        icon: code-slash-outline
      - title: Контакты
        url: https://example.com
        icon: person-outline

check:
  startOnServe: true
  playlists:
    userAgent:
      - Mozilla/5.0 WINK/1.31.1 (AndroidTV/9) HlsWinkPlayer
      - Mozilla/5.0 (Linux; Android 11) AppleWebKit/537.36
    timeout: 10
    allCooldown: 5
    oneCooldown: [1, 3]
    maxRoutines: 10
    perRoutine: 5
  channels:
    userAgent: Mozilla/5.0 (Linux; Android 11) AppleWebKit/537.36
    timeout: 10
    byteRange: 512
    cooldown: 0
    maxRoutines: 100
    perRoutine: 20

cache:
  enabled: true
  host: cache
  port: 6379
  ttl: 3600

Запуск:

./iptvc serve

Поскольку startOnServe: true, фоновая проверка запустится автоматически. Кеш включён, так что результаты переживут перезапуск. Сайт доступен на http://0.0.0.0:8800.

Docker¶

Удобно запускать сайт в контейнере. Образ iptvc уже включает бинарник:

compose.yml

services:
  iptvc:
    image: git.axenov.dev/iptv/iptvc:latest
    command: [serve]
    ports:
      - "8800:8800"
    volumes:
      - ./config.yml:/app/config.yml:ro
      - ./playlists.ini:/app/playlists.ini:ro
      - ./channels.json:/app/channels.json:ro
    environment:
      - CHECK_START_ON_SERVE=true
      - CACHE_ENABLED=true
      - CACHE_HOST=cache
      - CACHE_PORT=6379

  cache:
    image: valkey/valkey:latest
    restart: unless-stopped

docker compose up -d

Подробнее об установке образа — в документации по установке.

Краткая шпаргалка¶

Задача	Как
Запустить сайт	`./iptvc serve`
С проверкой плейлистов	`./iptvc serve --check`
На другом порту	`./iptvc serve -p 3000`
С ini-файлом из другого места	`./iptvc serve -i /path/to/playlists.ini`
С кешем	`./iptvc serve --check --cache-enabled`
Один цикл проверки	`./iptvc serve --check --repeat 1`
Пауза 2 минуты между циклами	`./iptvc serve --check --playlists-all-cooldown 120`
Подробные логи	`./iptvc serve --check --verbose`

Полный список параметров — в справочнике по config.yml, переменным окружения и команде serve.