release: bump version to 0.42.0

2026-04-28 04:27:18 +08:00
parent eeee788530
commit b4e8afb272
53 changed files with 6863 additions and 87 deletions
--- a/docs/technical/zh/earth-news-live-streams-collector-format.md
+++ b/docs/technical/zh/earth-news-live-streams-collector-format.md
@@ -0,0 +1,187 @@
+# News Live Streams Collector Format
+
+`news_live_streams` 采集器面向“频道目录 JSON”输入，而不是直接抓网页。
+
+这样做的目标是：
+
+- 让后台能够稳定接入世界各地新闻直播源
+- 让 `Earth` 页面电视模块始终消费统一结构
+- 便于后续接入类似 `worldmonitor` 那种 YouTube / HLS / iframe 混合频道目录
+
+## 推荐 JSON 结构
+
+```json
+{
+  "sources": [
+    {
+      "id": "bbc-world-news",
+      "name": "BBC World News",
+      "provider": "BBC",
+      "region": "UK",
+      "language": "en",
+      "source_type": "youtube",
+      "youtube_video_id": "dQw4w9WgXcQ",
+      "youtube_channel": "https://www.youtube.com/@BBCNews",
+      "embed_url": "",
+      "stream_url": "",
+      "homepage_url": "https://www.youtube.com/@BBCNews/live",
+      "poster_url": "",
+      "sort_order": 220,
+      "is_enabled": true,
+      "notes": "Primary English global news channel"
+    },
+    {
+      "id": "france24-en",
+      "name": "France 24 English",
+      "provider": "France 24",
+      "region": "France",
+      "language": "en",
+      "source_type": "hls",
+      "stream_url": "https://example.com/live.m3u8",
+      "homepage_url": "https://www.france24.com/en/live",
+      "sort_order": 230,
+      "is_enabled": true
+    },
+    {
+      "id": "cctv4-page",
+      "name": "CCTV-4 中文国际",
+      "provider": "CCTV",
+      "region": "China",
+      "language": "zh-CN",
+      "source_type": "iframe",
+      "embed_url": "https://tv.cctv.com/live/cctv4/",
+      "homepage_url": "https://tv.cctv.com/live/cctv4/",
+      "sort_order": 10,
+      "is_enabled": true
+    }
+  ]
+}
+```
+
+## 字段约定
+
+- `id`: 唯一标识，建议稳定不变
+- `name`: 频道显示名
+- `provider`: 提供方
+- `region`: 国家或地区
+- `language`: 语言代码
+- `source_type`: `iframe` / `hls` / `video` / `external` / `youtube`
+- `embed_url`: 适合 iframe 内嵌的页面
+- `stream_url`: 直接视频流地址
+- `homepage_url`: 官网或频道页
+- `youtube_video_id`: YouTube 直播视频 ID
+- `youtube_channel`: YouTube 频道 handle 或频道 URL
+- `poster_url`: 封面图，可选
+- `sort_order`: 排序值，越小越靠前
+- `is_enabled`: 是否启用
+- `notes`: 简短备注
+
+## 面板行为约定
+
+- `youtube`
+  - 优先使用 `youtube_video_id`
+  - 无法内嵌时至少保留 `youtube_channel` 或 `homepage_url` 供外部打开
+- `hls` / `video`
+  - 优先走 `stream_url`
+- `iframe`
+  - 优先走 `embed_url`
+- `external`
+  - 不尝试内嵌，只保留外部打开
+
+## 当前实现状态
+
+- 后台设置页可以手工维护频道目录
+- `Earth` 电视模块会合并：
+  - 手工配置源
+  - `news_live_streams` 采集器采集源
+- 当前默认兜底源为 `CCTV-4 中文国际`
+- `news_live_streams` 在未配置 override 时，默认使用 `iptv-org`：
+  - `channels.json`
+  - `streams.json`
+  - `logos.json`
+  并自动筛出新闻类频道目录
+
+## 采集器配置方式
+
+`news_live_streams` 不需要单独新页面，直接复用现有数据源配置：
+
+- `endpoint`
+  - 频道目录 JSON API 地址
+- `auth_type`
+  - `none` / `bearer` / `api_key` / `basic`
+- `headers`
+  - 额外请求头
+- `config`
+  - 采集器请求与解析行为
+
+### 支持的 `config` 字段
+
+```json
+{
+  "timeout": 30,
+  "method": "GET",
+  "params": {
+    "region": "global"
+  },
+  "body_type": "json",
+  "body": {
+    "include_disabled": false
+  },
+  "response_path": "payload.channels"
+}
+```
+
+- `timeout`
+  - 请求超时秒数
+- `method`
+  - `GET` 或 `POST`
+- `params`
+  - 查询参数对象
+- `body_type`
+  - `json` 或 `form`
+- `body`
+  - 配合 `POST` 使用的请求体
+- `json_body`
+  - 显式 JSON 请求体，优先级高于 `body`
+- `form_body`
+  - 显式表单请求体，优先级高于 `body`
+- `response_path`
+  - 返回 JSON 中频道数组所在路径，支持点路径，例如：
+    - `payload.channels`
+    - `data.items`
+    - `result.streams`
+
+### 认证补充
+
+- `bearer`
+  - 使用 `Authorization: Bearer <token>`
+- `api_key`
+  - 默认作为请求头发送
+  - 如果 `auth_config.in = "query"`，则作为 query param 发送
+- `basic`
+  - 使用 HTTP Basic Authorization
+
+## 兼容的响应结构
+
+采集器会优先读取：
+
+- 顶层数组
+- 或这些常见字段下的数组：
+  - `sources`
+  - `streams`
+  - `channels`
+  - `items`
+  - `results`
+  - `data`
+
+同时会兼容这些字段别名：
+
+- `id` / `source_id` / `slug` / `channel_id` / `code`
+- `name` / `title` / `channel` / `display_name`
+- `provider` / `publisher` / `network`
+- `stream_url` / `stream` / `playback_url` / `hls_url` / `m3u8_url`
+- `embed_url` / `embed` / `page_url`
+- `homepage_url` / `source_url` / `website`
+- `language` / `lang` / `locale`
+- `youtube_video_id` / `video_id`
+- `youtube_channel` / `channel_handle`