Актуализация страниц о деплое и разработке + мелочи по оформлению

2026-07-23 20:10:36 +08:00
parent 9d817f65d8
commit 0e80f6076e
8 changed files with 93 additions and 83 deletions
@@ -44,7 +44,6 @@ site:
  page-size: 0
  favicon:
  header:
-    title: IPTV Checker
    menu:
      - title: Документация
        url: /docs
@@ -224,10 +223,10 @@ cache:

 Мета-теги `<meta name="description">` и `<meta name="keywords">` для HTML-шаблонов.

-| Поле | Переменная окружения | Описание |
-| --- | --- | --- |
-| `description` | `SITE_META_DESCRIPTION` | Описание сайта в meta-тегах |
-| `keywords` | `SITE_META_KEYWORDS` | Ключевые слова через запятую |
+| Поле          | Переменная окружения    | Описание                     |
+| ------------- | ----------------------- | ---------------------------- |
+| `description` | `SITE_META_DESCRIPTION` | Описание сайта в meta-тегах  |
+| `keywords`    | `SITE_META_KEYWORDS`    | Ключевые слова через запятую |

 ---

@@ -240,15 +239,6 @@ cache:

 ---

-### `site.header.title` { id=site-header-title }
-
-<!-- md:default IPTV Checker -->
-
-Заголовок сайта, отображается в `<title>` и в navbar.
-Переопределяется переменной окружения `SITE_TITLE` (см. [`site.title`](#site-title)).
-
---
-
 ### `site.header.menu` { id=site-header-menu }

 Массив элементов [`Link`](#link) в шапке сайта.
@@ -365,19 +365,20 @@ iptvc serve --check --debug \

 ## Веб-маршруты

-| Метод | Путь | Описание |
-| --- | --- | --- |
-| GET | `/` | Главная страница со списком плейлистов |
-| GET | `/page/{N}` | Страница N списка плейлистов |
-| GET | `/{code}` | Редирект на прямую ссылку плейлиста |
-| GET | `/{code}.m3u[8]` | Редирект на прямую ссылку плейлиста |
-| GET | `/{code}/details` | Страница с описанием плейлиста |
-| GET | `/api` | Редирект на `/api/` (Swagger UI) |
-| GET | `/api/` | Swagger UI с описанием REST API |
-| GET | `/api/openapi.json` | OpenAPI-схема в формате JSON |
-| GET | `/api/playlists` | JSON: массив всех плейлистов |
-| GET | `/api/playlists/{code}` | JSON: информация о плейлисте |
-| GET | `/api/playlists/{code}/channels` | JSON: список каналов плейлиста |
-| GET | `/api/version` | JSON: версии компонентов |
-| GET | `/api/health` | JSON: состояние сервиса |
-| GET | `/api/stats` | JSON: статистика по плейлистам и каналам |
+| Метод | Путь                             | Описание                                 |
+| ----- | -------------------------------- | ---------------------------------------- |
+| GET   | `/`                              | Главная страница со списком плейлистов   |
+| GET   | `/page/{N}`                      | Страница N списка плейлистов             |
+| GET   | `/{code}`                        | Редирект на прямую ссылку плейлиста      |
+| GET   | `/{code}.m3u`                    | Редирект на прямую ссылку плейлиста      |
+| GET   | `/{code}.m3u8`                   | Редирект на прямую ссылку плейлиста      |
+| GET   | `/{code}/details`                | Страница с описанием плейлиста           |
+| GET   | `/api`                           | Редирект на `/api/` (Swagger UI)         |
+| GET   | `/api/`                          | Swagger UI с описанием REST API          |
+| GET   | `/api/openapi.json`              | OpenAPI-схема в формате JSON             |
+| GET   | `/api/playlists`                 | JSON: массив всех плейлистов             |
+| GET   | `/api/playlists/{code}`          | JSON: информация о плейлисте             |
+| GET   | `/api/playlists/{code}/channels` | JSON: список каналов плейлиста           |
+| GET   | `/api/version`                   | JSON: версии компонентов                 |
+| GET   | `/api/health`                    | JSON: состояние сервиса                  |
+| GET   | `/api/stats`                     | JSON: статистика по плейлистам и каналам |
@@ -52,7 +52,11 @@ iptvc/
 │   └── web/
 │       ├── server.go        # Server, Start(), StartBackgroundChecker()
 │       ├── handlers.go      # HTTP-обработчики
+│       ├── views.go         # PlaylistView, ChannelView, PageData
 │       ├── templates.go     # TemplateManager, //go:embed
+│       ├── openapi.go       # OpenAPI-спецификация, Swagger UI
+│       ├── swagger/         # встроенные файлы Swagger UI
+│       ├── static/          # встроенные статические файлы (CSS, JS)
 │       └── views/           # HTML-шаблоны
 │           ├── base.html
 │           ├── list.html
@@ -66,7 +70,8 @@ iptvc/
 ### `app`

 Глобальный контейнер: `Args` (CLI-флаги), `Config` (конфигурация), `Cache` (Redis-клиент).
-`Init()` загружает конфигурацию, инициализирует логгер и подключение к кешу.
+`Init()` загружает конфигурацию и инициализирует логгер.
+`InitCache()` подключается к KeyDB/Redis, если кеш включён.

 ### `app.config`

@@ -86,8 +91,8 @@ iptvc/
 Содержит логику проверки:

 - **`PrepareListsToCheck(files, urls, codes)`** — формирует список плейлистов из файлов, URL и кодов ini-файла.
- **`CheckPlaylists(lists)`** — параллельная проверка плейлистов (семфор `per-routine`), загрузка, парсинг, вызов `CheckChannels` для каждого.
- **`CheckChannels(pls)`** — параллельная проверка каналов (семфор `per-routine`), HTTP-запрос с `Range` header.
+- **`CheckPlaylists(lists)`** — параллельная проверка плейлистов (семфор `max-routines`), загрузка, парсинг, вызов `CheckChannels` для каждого.
+- **`CheckChannels(pls)`** — параллельная проверка каналов (семфор `max-routines`), HTTP-запрос с `Range` header.
 - **`OnPlaylistChecked`** — глобальный callback, вызывается после проверки каждого плейлиста. Используется веб-сервером для обновления in-memory кеша.
 - **`cachePlaylist(pls)`** — сохранение результата в Redis (если включён).

@@ -108,7 +113,7 @@ iptvc/
 - **`Server`** — структура: конфиг, кеш, шаблоны, in-memory кеш (`memCache` с `sync.RWMutex`).
 - **`Start()`** — запуск HTTP-сервера.
 - **`StartBackgroundChecker(opts)`** — фоновая проверка в отдельной горутине.
- **`CheckOptions`** — параметры: Every, Repeat, Random, Files, Urls, Codes.
+- **`CheckOptions`** — параметры: Repeat, Random, Files, Urls, Codes.

 Маршруты (Go 1.22 patterns):

@@ -152,9 +157,8 @@ StartBackgroundChecker:
                        → check status + content type
               → OnPlaylistChecked(pls) → memCache update
               → one-cooldown sleep
-           → all-cooldown sleep
-    sleep(every)
-    if repeat > 0 && iteration >= repeat: stop
+     → all-cooldown sleep
+     if repeat > 0 && iteration >= repeat: stop
 ```

 ## CLI-флаги
@@ -191,10 +195,12 @@ StartBackgroundChecker:

 ### Глобальные (`cmd/root.go`)

-| Флаг            | Поле              | Описание          |
-| --------------- | ----------------- | ----------------- |
-| `--config`      | `Args.ConfigPath` | Путь к config.yml |
-| `-v, --verbose` | `Args.Verbose`    | Подробный лог     |
+| Флаг            | Поле              | Описание            |
+| --------------- | ----------------- | ------------------- |
+| `--config`      | `Args.ConfigPath` | Путь к config.yml   |
+| `-v, --verbose` | `Args.Verbose`    | Подробный лог       |
+| `--debug`       | `Args.Debug`      | Режим отладки       |
+| `--log-level`   | `Args.LogLevel`   | Уровень логирования |

 ## Конфигурация

@@ -17,14 +17,17 @@ make linux

 ## Доступные рецепты Makefile

-| Команда        | Назначение                                                    |
-| -------------- | ------------------------------------------------------------- |
-| `make linux`   | Сборка под Linux (amd64 по умолчанию)                         |
-| `make win`     | Сборка под Windows                                            |
-| `make darwin`  | Сборка под macOS                                              |
-| `make release` | Сборка под все платформы (linux/windows/darwin × amd64/arm64) |
-| `make clean`   | Удаление скомпилированных бинарников                          |
-| `make help`    | Вывод списка доступных рецептов                               |
+| Команда          | Назначение                                                    |
+| ---------------- | ------------------------------------------------------------- |
+| `make linux`     | Сборка под Linux (amd64 по умолчанию)                         |
+| `make win`       | Сборка под Windows                                            |
+| `make darwin`    | Сборка под macOS                                              |
+| `make release`   | Сборка под все платформы (linux/windows/darwin × amd64/arm64) |
+| `make test`      | Запуск всех тестов                                            |
+| `make clear`     | Удаление скомпилированных бинарников                          |
+| `make image`     | Сборка Docker-образа для текущей платформы                    |
+| `make image-all` | Сборка и отправка multi-arch манифеста в registry             |
+| `make help`      | Вывод списка доступных рецептов                               |

 ## Управление архитектурой

@@ -8,22 +8,32 @@ tags: ["iptvc", "docker"]

 ## Сборка

-Образ собирается из [Dockerfile](https://git.axenov.dev/IPTV/iptvc/src/branch/master/Dockerfile) — multi-stage сборка на базе `golang:1.25-alpine` с финальным образом `alpine:3.22`.
+Образ собирается из [Dockerfile](https://git.axenov.dev/IPTV/iptvc/src/branch/master/Dockerfile) на базе `alpine:3.22.5`.
+
+Бинарный файл должен быть предварительно собран через `make linux` — Dockerfile берёт уже готовый бинарь из `bin/linux_${TARGETARCH}/iptvc`.

 ```bash
-docker build -t iptvc ./iptvc
+# Сборка бинарного файла и образа
+make image
+
+# Сборка с указанием архитектуры
+make image GOARCH=arm64
+
+# Сборка с указанием тега
+make image IMAGE_TAG=v1.1.3
 ```

-Можно передать версию через build-arg:
+Целевая архитектура задаётся через `GOARCH`:

 ```bash
-docker build --build-arg IPTVC_VERSION=1.1.3 -t iptvc:v1.1.3 ./iptvc
+make linux GOARCH=arm64
+make image GOARCH=arm64
 ```

-Целевая платформа и архитектура задаются через `GOOS` и `GOARCH`:
+Для публикации multi-arch манифеста в registry:

 ```bash
-docker build --build-arg GOOS=linux --build-arg GOARCH=arm64 -t iptvc:linux-arm64 ./iptvc
+make image-all
 ```

 ## Запуск
@@ -33,13 +43,13 @@ docker build --build-arg GOOS=linux --build-arg GOARCH=arm64 -t iptvc:linux-arm6
 docker run --rm \
    -v ./playlists.ini:/app/playlists.ini \
    -v ./channels.json:/app/channels.json \
-    iptvc check -i playlists.ini --repeat 0 --playlists-all-cooldown 60
+    git.axenov.dev/iptv/iptvc:latest check -i playlists.ini --repeat 0 --playlists-all-cooldown 60

 # Веб-сервер с фоновой проверкой
 docker run --rm -p 8800:8800 \
    -v ./playlists.ini:/app/playlists.ini \
    -v ./channels.json:/app/channels.json \
-    iptvc serve -i playlists.ini -p 8800 --check
+    git.axenov.dev/iptv/iptvc:latest serve -i playlists.ini -p 8800 --check
 ```

 ## Использование в compose
@@ -25,7 +25,7 @@ tags: ["iptvc"]

 ## Запуск релизного образа

-Релизные docker-образы строятся для платформы `linux` и архитектуры `amd64`.
+Релизные docker-образы строятся для платформы `linux` и архитектур `amd64` и `arm64`.

 Найти их можно здесь: <https://git.axenov.dev/IPTV/-/packages/container/iptvc>

@@ -110,28 +110,28 @@ docker compose down

 ## Сборка образа iptvc { id="image" }

-Для публикации образа используйте скрипт `iptvc/build-docker-image.sh`.
-
-Скрипт вычисляет версию из Git, собирает образы с тегами `iptvc:<тег>` и `git.axenov.dev/iptv/iptvc:<тег>`, а затем отправляет registry-тег в registry:
+Для сборки и публикации образа используйте цели Makefile в каталоге `iptvc/`:

 ```bash
 cd iptvc
-./build-docker-image.sh latest
+
+# Сборка одноархитектурного образа (linux/amd64 по умолчанию)
+make image
+
+# Сборка под arm64
+make image GOARCH=arm64
+
+# Сборка с указанием тега
+make image IMAGE_TAG=v1.2.3
 ```

-Для публикации релизного тега:
+Для публикации multi-arch манифеста (linux/amd64 + linux/arm64):

 ```bash
-./build-docker-image.sh v1.2.3
+make image-all
 ```

-По умолчанию скрипт собирает Linux-образ для `amd64`.
-
-Платформу можно изменить переменными окружения:
-
-```bash
-GOOS=linux GOARCH=arm64 ./build-docker-image.sh v1.2.3
-```
+Цель `image-all` всегда отправляет образ в registry — это ограничение `docker buildx`: multi-arch манифест нельзя загрузить в локальный Docker daemon.

 Перед публикацией войдите в registry, если это требуется вашей настройкой:

@@ -140,8 +140,8 @@ docker login git.axenov.dev
 ```

 !!! warning "Рабочее дерево Git"
-    Скрипт переключается на Git-тег, переданный первым аргументом, или на тег, возвращённый `git describe`.
-    Перед запуском сохраните локальные изменения и убедитесь, что нужный тег существует.
+    Версия и коммит вшиваются в бинарь из `git describe` и `git rev-parse` на хосте в момент запуска `make`.
+    Перед сборкой убедитесь, что рабочая копия чистая и находится на нужном теге или коммите.

 ## Обновление { id="update" }

@@ -403,15 +403,15 @@ 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`                       |
+| Задача                        | Как                                                  |
+| ----------------------------- | ---------------------------------------------------- |
+| Запустить сайт                | `./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`](../../common/config/config.md), [переменным окружения](../../common/config/config.md) и [команде `serve`](../commands/serve.md).