增加emby支持

2026-01-03 01:04:38 +08:00
parent d9dbf4ac83
commit ea636b2307
15 changed files with 2478 additions and 37 deletions
@@ -0,0 +1,287 @@
+# Emby 集成使用指南
+
+## 🎉 实现完成
+
+Emby 已经成功集成到 MoonTVPlus 项目中！所有核心功能都已实现并可以使用。
+
+---
+
+## 📋 已实现的功能
+
+### 1. 核心基础设施
+- ✅ EmbyConfig 类型定义 (`src/lib/admin.types.ts`)
+- ✅ Emby 客户端 (`src/lib/emby.client.ts`)
+
+### 2. API 端点
+- ✅ `/api/emby/list` - 媒体列表（分页）
+- ✅ `/api/emby/detail` - 媒体详情
+- ✅ `/api/emby/cms-proxy/[token]` - CMS API 代理（核心）
+- ✅ `/api/admin/emby` - 管理配置
+
+### 3. 前台集成
+- ✅ 私人影库页面集成 CapsuleSwitch（OpenList ↔ Emby 切换）
+- ✅ 播放页面支持 `source=emby` 参数
+
+### 4. 管理面板
+- ✅ Emby 配置区域（服务器地址、API Key、用户名/密码）
+- ✅ 连接测试功能
+- ✅ 保存配置功能
+
+---
+
+## 🚀 快速开始
+
+### 步骤 1: 配置 Emby
+
+1. 登录管理面板
+2. 找到 **"Emby 媒体库"** 配置区域
+3. 填写以下信息：
+   - **服务器地址**: 你的 Emby 服务器地址（如 `http://192.168.1.100:8096`）
+   - **API Key**（推荐）: 在 Emby 设置中生成 API Key
+   - 或者填写 **用户名** 和 **密码**
+4. 点击 **"测试连接"** 验证配置
+5. 点击 **"保存配置"**
+6. 启用 **"启用 Emby 媒体库"** 开关
+
+### 步骤 2: 访问私人影库
+
+1. 访问 **"私人影库"** 页面
+2. 使用顶部的 **CapsuleSwitch** 切换到 **"Emby"**
+3. 浏览你的 Emby 媒体库
+4. 点击任意视频即可播放
+
+### 步骤 3: TVBOX 订阅（可选）
+
+如果你启用了 TVBOX 订阅功能，Emby 会自动添加到订阅源中：
+
+**订阅地址格式**:
+```
+http://your-domain.com/api/emby/cms-proxy/{TVBOX_SUBSCRIBE_TOKEN}
+```
+
+在 TVBOX 中添加此订阅源，即可在 TVBOX 中浏览和播放 Emby 媒体库。
+
+---
+
+## 🔧 配置说明
+
+### Emby 服务器地址
+
+- 格式: `http://IP:PORT` 或 `https://domain.com`
+- 示例: `http://192.168.1.100:8096`
+- 注意: 确保 MoonTVPlus 服务器能够访问 Emby 服务器
+
+### 认证方式
+
+**方式 1: API Key（推荐）**
+- 在 Emby 设置中生成 API Key
+- 优点: 更安全，不需要存储密码
+- 获取方式: Emby 设置 → 高级 → API Keys
+
+**方式 2: 用户名/密码**
+- 使用 Emby 用户账号
+- 优点: 简单直接
+- 注意: 密码会加密存储在数据库中
+
+---
+
+## 📖 功能特性
+
+### 1. 网页播放
+
+- **统一入口**: 私人影库页面
+- **无缝切换**: CapsuleSwitch 在 OpenList 和 Emby 之间切换
+- **完整支持**: 电影、剧集、季、集
+- **自动播放**: 点击即播，无需额外配置
+
+### 2. CMS-Proxy
+
+Emby 的 CMS-Proxy 将 Emby 媒体库转换为苹果 CMS V10 格式，实现：
+
+- ✅ 网页播放复用现有逻辑
+- ✅ TVBOX 直接支持
+- ✅ 统一接口，降低维护成本
+- ✅ 扩展性强，未来可添加 Jellyfin、Plex 等
+
+### 3. 播放链接
+
+**直接播放**（默认）:
+```
+http://emby-server:8096/Videos/{itemId}/stream?Static=true&api_key={apiKey}
+```
+
+**转码播放**（可选）:
+```
+http://emby-server:8096/Videos/{itemId}/master.m3u8?api_key={apiKey}
+```
+
+---
+
+## 🎯 使用场景
+
+### 场景 1: 家庭媒体中心
+
+- 在家中搭建 Emby 服务器
+- 使用 MoonTVPlus 作为统一的观影入口
+- 在私人影库中浏览和播放 Emby 媒体
+
+### 场景 2: 多源聚合
+
+- OpenList: 云存储媒体
+- Emby: 本地媒体服务器
+- CMS 源: 在线资源
+- 统一在 MoonTVPlus 中管理和播放
+
+### 场景 3: TVBOX 集成
+
+- 在 TVBOX 中添加 Emby 订阅源
+- 在电视上浏览和播放 Emby 媒体
+- 无需单独安装 Emby 客户端
+
+---
+
+## 🔍 故障排查
+
+### 问题 1: 连接测试失败
+
+**可能原因**:
+- Emby 服务器地址错误
+- 网络不通（防火墙、端口未开放）
+- API Key 或用户名/密码错误
+
+**解决方法**:
+1. 检查 Emby 服务器地址是否正确
+2. 确保 MoonTVPlus 服务器能够访问 Emby 服务器
+3. 验证 API Key 或用户名/密码是否正确
+4. 检查 Emby 服务器日志
+
+### 问题 2: 媒体列表为空
+
+**可能原因**:
+- Emby 媒体库为空
+- 用户权限不足
+- 媒体库未扫描完成
+
+**解决方法**:
+1. 在 Emby 中检查媒体库是否有内容
+2. 确保使用的用户有访问媒体库的权限
+3. 等待 Emby 完成媒体库扫描
+
+### 问题 3: 播放失败
+
+**可能原因**:
+- 媒体文件损坏
+- 网络带宽不足
+- 浏览器不支持视频格式
+
+**解决方法**:
+1. 在 Emby 客户端中测试播放
+2. 检查网络连接
+3. 尝试使用其他浏览器
+4. 考虑启用转码
+
+---
+
+## 📊 性能优化
+
+### 1. 缓存策略
+
+- 媒体列表缓存: 减少对 Emby 服务器的请求
+- 播放链接缓存: 提高播放响应速度
+
+### 2. 网络优化
+
+- 使用本地网络: Emby 服务器和 MoonTVPlus 在同一网络
+- 启用转码: 根据网络情况动态调整码率
+
+### 3. 媒体库优化
+
+- 定期清理无效媒体
+- 使用 SSD 存储媒体文件
+- 优化 Emby 服务器配置
+
+---
+
+## 🔐 安全建议
+
+1. **使用 HTTPS**: 在生产环境中使用 HTTPS 访问 Emby
+2. **强密码**: 使用强密码保护 Emby 账号
+3. **API Key**: 优先使用 API Key 而不是用户名/密码
+4. **防火墙**: 限制 Emby 服务器的访问来源
+5. **定期更新**: 保持 Emby 和 MoonTVPlus 更新到最新版本
+
+---
+
+## 🎨 自定义
+
+### 修改播放链接格式
+
+编辑 `src/lib/emby.client.ts` 中的 `getStreamUrl` 方法：
+
+```typescript
+getStreamUrl(itemId: string, direct: boolean = true): string {
+  if (direct) {
+    // 直接播放
+    return `${this.serverUrl}/Videos/${itemId}/stream?Static=true&api_key=${this.apiKey}`;
+  }
+  // 转码播放
+  return `${this.serverUrl}/Videos/${itemId}/master.m3u8?api_key=${this.apiKey}&VideoCodec=h264`;
+}
+```
+
+### 添加媒体库过滤
+
+在 `src/lib/admin.types.ts` 中的 `EmbyConfig` 添加 `Libraries` 字段，然后在 API 中使用：
+
+```typescript
+const result = await client.getItems({
+  ParentId: config.EmbyConfig.Libraries?.[0], // 指定媒体库
+  IncludeItemTypes: 'Movie,Series',
+  // ...
+});
+```
+
+---
+
+## 🚧 已知限制
+
+1. **字幕支持**: 当前版本不支持加载 Emby 字幕（计划中）
+2. **转码设置**: 不支持用户自定义转码参数（计划中）
+3. **多用户**: 不支持不同用户看到不同的媒体库（计划中）
+4. **收藏同步**: 不支持与 Emby 的收藏同步（计划中）
+
+---
+
+## 🔮 未来计划
+
+- [ ] 字幕支持
+- [ ] 转码设置
+- [ ] 多用户支持
+- [ ] 收藏同步
+- [ ] 观看历史同步
+- [ ] Jellyfin 支持（API 与 Emby 类似）
+- [ ] Plex 支持
+
+---
+
+## 📞 支持
+
+如果遇到问题或有建议，请：
+
+1. 查看本文档的故障排查部分
+2. 查看 Emby 服务器日志
+3. 查看 MoonTVPlus 服务器日志
+4. 在 GitHub 上提交 Issue
+
+---
+
+## 🎉 总结
+
+Emby 集成为 MoonTVPlus 带来了强大的本地媒体服务器支持，通过 CMS-Proxy 的设计，实现了：
+
+- ✅ 统一的播放体验
+- ✅ TVBOX 无缝集成
+- ✅ 代码复用和维护简化
+- ✅ 良好的扩展性
+
+享受你的 Emby 媒体库吧！🎬