新增: SFTP直连+网站预览+OSS区域嗅探+热键+BGM播放

2026-05-12 11:06:28 +08:00
parent 545d7a864d
commit 2a363fd729
62 changed files with 6687 additions and 660 deletions
--- a/docs/04-功能迭代/生态链接/03-广播电台.md
+++ b/docs/04-功能迭代/生态链接/03-广播电台.md
@@ -0,0 +1,335 @@
+# 广播电台 / 电视 / 播客 开放平台接入方案备忘录
+
+> 最后更新：2026-05-08 | 用途：U-Desk 生态链接 — 音频流媒体模块可行性评估
+
+---
+
+## 一、平台总览对比
+
+| 平台 | 类型 | 费用 | 中文内容 | 桌面端适配 | 合规性 | 接入难度 | 评级 |
+|------|------|------|----------|------------|--------|----------|------|
+| **Radio Browser API** | 国际电台 | 免费 | 中 | 极高(RESTful) | 高 | 极低 | **A** |
+| **Apple iTunes Search API** | 播客索引 | 免费 | 高 | 极高(HTTP) | 高 | 低 | **A-** |
+| **喜马拉雅开放平台** | 国内音频 | 商务合作 | 极高 | 中低(Web嵌入) | 高 | 高 | B- |
+| **蜻蜓FM开放平台** | 国内音频 | 商务合作 | 极高 | 低 | 高 | 高 | C+ |
+| **CCTV 嵌入** | 电视 | 不定 | 极高 | 中 | 中风险 | 中 | C- |
+| **TuneIn API** | 国际电台 | 不开放 | 低 | 无 | - | - | D |
+| **荔枝FM / 云听** | 国内音频 | 无API | 高 | 无 | - | - | D |
+| **IPTV/电视直播** | 电视 | 无合法方案 | 极高 | 无 | - | - | D |
+
+---
+
+## 二、Radio Browser API（强烈推荐 ⭐⭐⭐）
+
+### 基本信息
+- **官网**：https://www.radio-browser.info
+- **API 地址**：https://api.radio-browser.info
+- **协议**：开源项目（GitLab），可自由用于免费和商业软件
+- **版本**：v0.7.44（2026-05-08 验证：API 在线，`/json/stats` 端点可能已迁移，但核心 station 接口正常）
+- **当前规模**：27,000+ 可用电台 / 80+ 国家 / 59+ 语言
+- **验证状态**：✅ **已验证在线** — `de1.api.radio-browser.info/json/stations/topclick` 返回实时数据（2026-05-08 15:26 UTC）
+
+### 核心能力
+
+#### 列表类接口
+| 接口 | 说明 |
+|------|------|
+| `/json/countries` | 按国家列出电台 |
+| `/json/codecs` | 编码格式列表 (MP3/AAC+/OGG) |
+| `/json/states` | 按州/省列出 |
+| `/json/languages` | 语言列表 (含 ISO 639 代码) |
+| `/json/tags` | 标签/流派列表 (jazz/pop/rock/news) |
+| `/json/stations` | 全部电台列表 |
+
+#### 搜索类接口
+| 接口 | 说明 |
+|------|------|
+| `/json/stations/search` | **高级搜索**：name/country/language/tag/codec/bitrate/geo 多维度组合查询 |
+| `/json/stations/byname/{term}` | 按名称搜索 |
+| `/json/stations/bycountry/{code}` | 按国家搜索 (`CN`=中国) |
+| `/json/stations/bylanguage/{lang}` | 按语言搜索 (`chinese`) |
+| `/json/stations/bytag/{tag}` | 按标签搜索 |
+
+#### 排行类接口
+| 接口 | 说明 |
+|------|------|
+| `/json/stations/topclick` | 最热门电台 |
+| `/json/stations/topvote` | 最高评分电台 |
+| `/json/stations/lastclick` | 最近被点击的 |
+
+#### 交互类接口
+| 接口 | 说明 |
+|------|------|
+| `/json/url/{uuid}` | 点击计数 + 获取播放 URL |
+| `/json/vote/{uuid}` | 为电台投票 |
+| `/json/add` | 添加新电台到数据库 |
+
+#### 运维类接口
+| 接口 | 说明 |
+|------|------|
+| `/json/stats` | 服务器统计 |
+| `/json/servers` | 镜像服务器列表（可自建） |
+| `/json/config` | 服务器配置 |
+
+### 数据结构关键字段
+```json
+{
+    "stationuuid": "唯一ID",
+    "name": "电台名称",
+    "url": "原始流地址",
+    "url_resolved": "已解析的直接播放URL ← 核心字段",
+    "homepage": "电台主页",
+    "favicon": "图标",
+    "tags": ["标签"],
+    "countrycode": "CN",
+    "language": "chinese",
+    "codec": "MP3",
+    "bitrate": 128,
+    "lastcheckok": true,
+    "clickcount": 24小时点击量
+}
+```
+
+### 输出格式
+JSON / XML / CSV / M3U / PLS / XSPF / TTL（7种！）
+
+### U-Desk 集成方式
+```
+Go 后端 → HTTP GET radio-browser API → JSON → Vue 展示电台列表
+                                              ↓ 点击播放
+                                    url_resolved 字段 = 直接可播放的 MP3/AAC 流
+```
+
+- **Go 有现成库**：`goradios`
+- **零成本、零审核、零依赖**
+- 工作量估算：2-3天（含 UI）
+
+### 特别优势
+- 支持按 `countrycode=CN` 筛选中文电台
+- 用户可添加自定义电台（`/json/add`）
+- 可自建镜像服务器（完全自主可控）
+- 支持 M3U/PLS 导出（兼容各类播放器）
+
+---
+
+## 三、Apple iTunes Search API — 播客发现（推荐 ⭐⭐⭐）
+
+### 基本信息
+- **文档**：https://affiliate.itunes.apple.com/resources/documentation/itunes-store-web-service-search-api/ （⚠️ 国内访问可能超时，需翻墙；API 端点本身通常可达）
+- **API 端点**：`https://itunes.apple.com/search` 和 `https://itunes.apple.com/lookup`
+- **费用**：免费（速率限制约 20次/分钟）
+
+### 核心能力
+
+#### 搜索参数
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `term` | 搜索关键词 | `news`, `故事`, `科技` |
+| `media` | 媒体类型 | `podcast` |
+| `entity` | 实体类型 | `podcast`, `podcastAuthor` |
+| `country` | 国家代码 | `cn` |
+| `limit` | 返回数量 | 25 |
+
+#### 使用示例
+```
+# 搜索中文新闻播客
+GET https://itunes.apple.com/search?term=news&country=cn&media=podcast&limit=25
+
+# 搜索特定作者
+GET https://itunes.apple.com/search?term=故事&entity=podcastAuthor&country=cn
+```
+
+#### 返回数据关键字段
+```json
+{
+    "collectionName": "播客名称",
+    "artistName": "作者",
+    "feedUrl": "RSS订阅地址 ← 核心：获取音频的入口",
+    "artworkUrl60": "小封面",
+    "artworkUrl100": "大封面",
+    "releaseDate": "发布日期",
+    "primaryGenreName": "分类"
+}
+```
+
+### 播放流程
+```
+iTunes Search API → 获取 feedUrl (RSS)
+                    ↓
+              解析 RSS XML → 提取 episode 列表
+                              ↓
+                        enclosure URL → 音频播放
+```
+
+### U-Desk 集成方式
+1. Go 后端调用 Search API → 获取播客列表和 RSS 地址
+2. 解析 RSS XML 提取 episode 音频 URL
+3. 前端播放器播放音频流
+4. 实现 20次/分钟速率限制的客户端缓存
+
+### 中文播客覆盖
+- iTunes Podcast 目录包含大量中文播客（大陆/台湾/香港创作者）
+- 覆盖新闻/故事/科技/商业/教育等各领域
+
+### 工作量估算：3-4天（含 RSS 解析逻辑）
+
+---
+
+## 四、喜马拉雅开放平台（备选 ⭐⭐）
+
+### 基本信息
+- **官网**：https://open.ximalaya.com/
+- **定位**：国内最大音频分享平台（纽交所上市）
+- **商务热线**：(021)50179077-8806 / -8803
+
+### 核心能力
+- 音频内容分发 SDK/API
+- 支持移动应用、智能硬件、车载、网页/小程序接入
+- 内容类型：有声书、课程、播客、相声评书、新闻资讯、亲子儿童、景点导览
+- AI 制作专区
+
+### 接入方式
+| 方式 | 说明 |
+|------|------|
+| 移动应用 SDK | Android/iOS/Flutter |
+| 智能硬件 SDK | IoT 设备 |
+| **网页/小程序 JS SDK** | ← U-Desk 的可行路径 |
+
+### 费用模式
+- **商务合作模式**，需"立即入驻"申请后商谈
+- 通常为分成或流量付费模式
+- 有运营中心（内容中心/数据中心/活动中心）
+
+### U-Desk 适配路径
+通过 Wails WebView 加载喜马拉雅 H5/JS SDK 播放器
+- 技术层面工作量：1-2天
+- 商务层面周期不确定（需审批）
+
+### 注意事项
+- 开发者文档页面部分返回 404，生态维护程度一般
+- 但"网页/小程序"接入通道确实存在
+
+---
+
+## 五、蜻蜓FM开放平台（低优先级）
+
+### 基本信息
+- **官网**：https://open.qingting.fm
+- 能力：SDK/API/H5嵌入式播放器
+- 内容：直播流、点播、有声书、相声评书、全国电台
+
+### 问题
+- 主要面向 B 端大客户（车企、智能硬件厂商）
+- 对独立桌面应用开发者门槛较高
+- 文档需入驻后才可查看完整内容
+- Windows 桌面端无原生支持
+
+### 结论：优先级低于喜马拉雅
+
+---
+
+## 六、电视/IPTV（当前不可行）
+
+### CCTV 央视网
+- **无公开开发者 API**
+- 可能存在 iframe 嵌入方案（灰色地带）
+- 版权严格管控，合规风险高
+- 评级：C-（仅作为外部链接实验）
+
+### 各省市 IPTV
+- 三大运营商分别运营，无统一 API
+- 专有传输协议（IGMP/RTP/RTSP），需专用机顶盒
+- **完全不存在合法的桌面端接入途径**
+- 评级：D
+
+### EPG 数据源（国际参考）
+- [epg-guide.com](https://epg-guide.com)：免费 EPG 数据，XMLTV 格式
+- 仅覆盖欧洲（意大利为主），不支持中文电视台
+- 技术成熟但无中文内容，参考价值有限
+
+### 结论：**电视模块暂不纳入 MVP**
+
+---
+
+## 七、荔枝FM / 云听
+
+| 平台 | 状态 | 原因 |
+|------|------|------|
+| 荔枝FM (lizhi.fm) | ❌ 无公开 API | 官网无 developer/open 入口 |
+| 云听 (yunting.fm) | ❌ 服务不稳定 | 访问时 500 错误，且无 API |
+
+---
+
+## 八、最终推荐组合方案
+
+### 第一优先级（MVP 即可上线）
+
+| 平台 | 用途 | 工作量 | 成本 |
+|------|------|--------|------|
+| **Radio Browser API** | 全球网络电台收听 | 2-3天 | 免费 |
+| **iTunes Search API** | 播客发现与播放 | 3-4天 | 免费 |
+
+### 第二优先级（后续迭代）
+
+| 平台 | 用途 | 工作量 | 前置条件 |
+|------|------|--------|----------|
+| **喜马拉雅 Web 嵌入** | 国内有声书/课程 | 1-2天技术 + 商务周期 | 商务合作审批 |
+| **央视网链接** | 电视直播快捷入口 | 0.5天 | 关注版权政策 |
+
+### 不推荐
+- ~~TuneIn~~ — 不开放第三方 API
+- ~~IPTV/电视直播~~ — 无合法接入途径
+- ~~荔枝FM/云听~~ — 无可用 API
+
+---
+
+## 九、U-Desk 广播/播客模块架构建议
+
+```
+U-Desk 生态链接 - 音频流媒体模块
+├── RadioService (Go)
+│   ├── StationSearch()     → Radio Browser /stations/search
+│   ├── TopStations()       → /stations/topclick
+│   ├── StationsByCountry() → /stations/bycountry/CN
+│   ├── StationsByTag()     → /stations/bytag/{tag}
+│   └── PlayStation()       → /json/url/{uuid} → url_resolved 直播流
+│
+├── PodcastService (Go)
+│   ├── SearchPodcasts()    → iTunes Search API (media=podcast)
+│   ├── GetPodcastDetail()  → iTunes Lookup API
+│   ├── ParseFeed()         → RSS XML → episode 列表
+│   └── PlayEpisode()       → enclosure URL → 音频播放
+│
+├── AudioPlayer (Vue Component)
+│   ├── RadioPanel.vue      → 电台浏览/搜索/播放/收藏
+│   ├── PodcastPanel.vue    → 播客发现/订阅/播放/下载
+│   └── MiniPlayer.vue      -> 底部栏迷你播放器
+│
+└── QuickLinks (Vue)
+    └── LinkCard.vue        → 央视网/喜马拉雅等外部链接卡片
+```
+
+### 与文件管理器的融合点
+- 浏览文件时底部迷你播放器持续播放电台/播客
+- 收藏夹统一管理（收藏的电台/播客/文件混合展示）
+- 右键菜单："搜索相关播客内容"
+
+---
+
+## 十、合规要点总结
+
+| 平台 | 合规要求 |
+|------|---------|
+| Radio Browser | 开源协议友好，商用无限制，仅需合理 User-Agent |
+| iTunes API | 遵守 Apple 使用条款（速率限制 + 展示要求） |
+| 喜马拉雅 | 必须走正式商务流程，签订合作协议 |
+| 央视网 | 以外部链接方式最安全，避免深度集成 |
+
+---
+
+*Sources:*
+- *Radio Browser: https://www.radio-browser.info / https://api.radio-browser.info*
+- *iTunes Search API: https://affiliate.itunes.apple.com/resources/documentation/itunes-store-web-service-search-api/*
+- *喜马拉雅开放平台: https://open.ximalaya.com/*
+- *蜻蜓FM开放平台: https://open.qingting.fm*
+- *EPG Guide: https://epg-guide.com*