# SyncTV 第一版方案

## 1. 产品定位

SyncTV 第一版是一个无注册、无用户体系的同步观影客户端，面向 App 和 Windows 应用。

核心目标：

- 输入房间 Code 即可进入房间。
- 不做账号、昵称、好友、聊天、历史用户等用户体系。
- 不支持本地视频。
- 只支持网络播放源：普通链接、OSS、WebDAV、直播流。
- 客户端负责解码播放，避免网页播放器格式支持弱的问题。
- 后端负责房间状态、同步信令、播放源解析、临时凭据保存，以及必要时的流式转发。
- 支持断线重连，并恢复到房间当前播放进度。

第一版优先把三件事做好：

- 能播。
- 同步准。
- 断线能回来。

## 2. 第一版功能范围

### 2.1 创建和进入房间

用户打开应用后可以创建房间，或输入已有房间 Code 加入房间。

房间可以先没有播放源。第一个加入房间成功的设备自动成为房主。

房主可以配置：

- 播放源类型。
- 播放源地址或配置。
- 是否为直播流。
- 连接方式，默认客户端直连，可手动切换为服务端代理。

创建新房间时服务端生成房间 Code，例如：

```text
A7K29Q
```

### 2.2 加入房间

客户端只需要输入房间 Code。

加入后客户端自动获取：

- 播放源信息。
- 当前播放状态。
- 当前播放进度。
- 是否直播。
- 当前房主设备信息。

不需要用户登录，也不需要设置昵称。

只有房主可以配置或更换播放源。所有房间成员都可以执行播放、暂停、跳转进度、回到直播等播放控制。

播放源连接方式由房主在配置时选择。默认是客户端直连源站，代理模式必须由房主主动打开。

### 2.3 播放控制同步

点播场景支持：

- 播放。
- 暂停。
- 跳转进度。
- 当前进度同步。
- 缓冲后恢复。

直播场景支持：

- 播放。
- 暂停。
- 回到直播。
- 直播延迟同步。

### 2.4 断线重连

客户端 WebSocket 断开后自动重连。

重连时携带：

- 房间 Code。
- 本地设备 ID。

服务端返回最新房间快照，客户端重新计算应播放位置并恢复。

房间无人在线后保留一段时间，建议第一版保留 30 分钟。超过后销毁房间和临时播放源凭据。

## 3. 非目标

第一版不做：

- 注册。
- 登录。
- 昵称。
- 用户资料。
- 好友。
- 聊天。
- 弹幕。
- 房间列表。
- 历史记录。
- 本地视频同步。
- 内置影视内容。
- 完整资源站。

## 4. 技术选型建议

### 4.1 客户端

客户端改为分端开发。

Windows 客户端建议：

- Python。
- PySide6。
- python-vlc。
- PyInstaller 打包 Windows exe。
- 系统播放器逻辑和同步逻辑分离。

移动 App 建议：

- HBuilder/uni-app。
- UI 和房间同步逻辑使用 Vue/uni-app。
- 播放器通过 App 原生插件接 VLC。
- Android 原生插件封装 libVLC。
- iOS 原生插件封装 MobileVLCKit / VLCKit。

分端开发的原因：

- 避免重型桌面工具链问题。
- Windows 端优先把强播放能力跑通。
- App 端通过 HBuilder 快速开发，同时保留原生 VLC 播放能力。
- 客户端共享后端协议，不共享 UI 代码。

选择播放器时需要重点验证：

- mp4。
- mkv。
- flv。
- m3u8。
- dash。
- 常见编码格式。
- 直播流。
- HTTP Header 自定义。
- Cookie / Authorization Header。
- WebDAV URL 播放。
- 字幕和音轨扩展能力。

### 4.2 后端

第一版服务端原则：

- 尽量轻。
- 尽量少模块。
- 尽量少状态。
- 默认不接触视频流。
- 只有房主手动开启代理时才做流式转发。
- 不做用户系统。
- 不做数据库表设计。
- 不做文件存储。

推荐：

- Go。
- 标准库 net/http 或 Gin/Fiber/Echo。
- WebSocket。
- Redis。
- Docker + Nginx。

第一版不建议上 PostgreSQL。房间状态、连接状态、临时播放源和过期时间都放 Redis，开发更快，清理也简单。

Go 更适合服务端保持轻量：单二进制部署，内存占用低，并发连接和流式转发能力好。第一版可以优先使用标准库 net/http，减少框架依赖。

### 4.3 服务模块

后端建议只拆最少模块：

- RoomService：房间创建、加入、房主判定、房间快照、过期清理。
- SyncGateway：WebSocket 连接、播放控制广播、心跳、重连。
- SourceService：播放源保存、直连信息下发、代理 URL 生成。
- StreamProxy：房主手动开启代理时，对 WebDAV/OSS/普通私有链接做流式转发，不落盘存储。

第一版可以先不单独拆 CredentialService、SourceResolver 等细模块，避免服务端过早变重。等代理来源和鉴权方式变多后再拆。

## 5. 播放源设计

第一版支持四类来源。

| 类型 | 示例 | 第一版处理方式 |
| --- | --- | --- |
| 普通链接 | mp4、m3u8、flv、dash | 默认客户端直连，可手动开启代理 |
| OSS | 阿里云 OSS、S3 兼容对象存储 | 默认客户端直连，可手动开启代理 |
| WebDAV | WebDAV 文件 URL | 默认客户端直连，可手动开启代理 |
| 直播流 | m3u8、flv、其他播放器支持协议 | 默认客户端直连，可手动开启代理 |

房主配置播放源时需要有一个明确的连接方式控件：

- 默认：客户端直连。
- 可选：服务端代理。

这个控件可以做成分段按钮或开关，不做自动切换。代理模式涉及服务器带宽成本和隐私边界，必须让房主显式选择。

### 5.1 普通链接

普通链接是最简单的来源。

后端只保存 URL 和基础元信息，客户端直接播放。

需要支持：

- 普通 HTTP/HTTPS URL。
- m3u8。
- flv。
- dash。
- 带必要 Header 的 URL。

### 5.2 OSS

OSS 有两种使用方式。

方式一：用户直接输入公开 URL 或签名 URL。

- 实现简单。
- 客户端直接播放。
- 后端只保存 URL。
- 适合第一版快速落地。

方式二：房主输入 OSS 配置，服务端保存临时凭据，并返回代理播放 URL。

- 更安全。
- 不把 Secret 直接广播给所有客户端。
- 服务端只做流式转发，不下载、不落盘。
- 房间销毁后清理配置。
- 适合稍微完整的第一版。

建议第一版支持方式一和方式二。方式一是默认模式；方式二需要房主手动开启，会增加服务器带宽压力，但不会增加硬盘存储压力。

### 5.3 WebDAV

WebDAV 是第一版需要重点设计的来源，因为它通常需要账号密码。

常见 WebDAV 鉴权方式：

- Basic Auth。
- Digest Auth。
- Cookie。
- Token。

播放器播放 WebDAV 文件时，客户端通常必须具备以下能力之一：

- URL 中包含凭据。
- 播放请求附带 Authorization Header。
- 访问服务端流式代理地址。

所以“WebDAV 的 key 不给客户端还能不能用”的答案是：

> 如果客户端要直接连接 WebDAV，凭据或等价的临时授权信息必须给客户端；不给就不能直连播放。
>
> 如果使用服务端流式代理，客户端不需要拿到原始 WebDAV 凭据；服务端拿到凭据后直接向 WebDAV 拉流，并边读边转发给客户端，不下载、不落盘。

#### 5.3.1 极简方案：凭据下发客户端

创建房间时，房主输入：

- WebDAV 文件 URL。
- 用户名。
- 密码或 Token。

服务端保存房间播放源，并在成员加入房间时下发给客户端。

客户端用这些凭据直接播放。

优点：

- 实现最简单。
- 后端不承担视频流量。
- 播放性能最好。
- 成本最低。

缺点：

- 所有加入房间的客户端都能拿到 WebDAV 凭据。
- 如果房间 Code 泄露，凭据也可能泄露。
- 对安全和隐私不友好。

适用场景：

- 早期内测。
- 用户之间互相信任。
- WebDAV 凭据本身是临时的。
- 产品明确提示风险。

#### 5.3.2 代理模式：服务端保存凭据并流式转发

创建房间时，房主提交 WebDAV 配置给后端。

后端：

- 加密保存 WebDAV 凭据。
- 验证文件是否可访问。
- 为房间成员生成代理播放 URL。
- 使用 WebDAV 凭据向源站发起请求。
- 将源站响应以流式方式转发给客户端。
- 不把视频文件下载到服务器硬盘。
- 不做长期缓存。
- 房间过期后删除凭据。

客户端播放：

```text
https://api.example.com/rooms/A7K29Q/source/stream?token=short-lived-token
```

服务端收到请求后使用 WebDAV 凭据去拉取源文件，再把内容边读边转发给客户端。

优点：

- 客户端拿不到原始 WebDAV 密码。
- 可以做房间权限、过期、限速、防盗链。
- 房间销毁后授权自然失效。
- 不承担硬盘存储压力。

缺点：

- 后端要承担视频流量，带宽成本高。
- 需要支持 Range 请求，否则拖动进度会很差。
- 大文件和高并发时压力明显。
- 直播和大码率视频对服务端要求更高。
- 需要处理连接中断、源站限速、响应头透传等转发细节。

这个方案安全性更好，不占用硬盘，但基础设施带宽成本更高。

#### 5.3.3 第一版建议

第一版建议做两个模式，但默认始终是直连模式：

1. 直连模式：客户端直连 WebDAV。
   - 房主输入 WebDAV URL 和凭据。
   - 后端临时保存并下发给房间客户端。
   - 明确这是共享房间凭据，适合可信房间。
   - 这是默认模式。

2. 代理模式：服务端流式转发 WebDAV。
   - 房主输入 WebDAV URL 和凭据。
   - 房主必须手动打开代理模式。
   - 后端保存凭据。
   - 客户端只拿代理播放 URL。
   - 后端支持 Range 请求。
   - 后端不下载、不落盘，只做流式转发。
   - 后端承担带宽和连接压力。

普通 URL 和 OSS 也可以使用同样的代理模式。只要服务端能拿到访问源站所需的 URL、Header、Cookie 或 Secret，就可以向源站发起请求并流式转发给客户端。

## 6. 房间状态模型

Redis 中建议保存房间快照。

点播房间示例：

```json
{
  "roomCode": "A7K29Q",
  "sourceType": "webdav",
  "sourceId": "src_123",
  "isLive": false,
  "playbackState": "playing",
  "positionMs": 128400,
  "serverUpdatedAt": 1780000000000,
  "ownerDeviceId": "dev_abc",
  "onlineCount": 2,
  "expireAt": 1780001800000
}
```

直播房间示例：

```json
{
  "roomCode": "A7K29Q",
  "sourceType": "url",
  "sourceId": "src_456",
  "isLive": true,
  "playbackState": "playing",
  "liveSyncMode": "latency",
  "targetLatencyMs": 3000,
  "serverUpdatedAt": 1780000000000,
  "ownerDeviceId": "dev_abc",
  "onlineCount": 2,
  "expireAt": 1780001800000
}
```

## 7. 同步协议

### 7.1 WebSocket 事件

客户端到服务端：

- createRoom
- joinRoom
- leaveRoom
- play
- pause
- seek
- syncProgress
- syncToLive
- heartbeat
- reconnectRoom

服务端到客户端：

- roomCreated
- roomJoined
- roomSnapshot
- playbackChanged
- progressSynced
- liveSynced
- controllerChanged
- roomExpired
- error

### 7.2 点播同步

控制端执行播放控制时发送事件。

播放事件示例：

```json
{
  "type": "play",
  "roomCode": "A7K29Q",
  "positionMs": 128400,
  "clientSentAt": 1780000000000
}
```

服务端写入：

```json
{
  "playbackState": "playing",
  "positionMs": 128400,
  "serverUpdatedAt": 1780000000120
}
```

其他客户端收到后计算目标进度：

```text
targetPositionMs = positionMs + (clientNowServerTime - serverUpdatedAt)
```

误差处理建议：

- 小于 500ms：不处理。
- 500ms 到 2000ms：短时间微调倍速。
- 大于 2000ms：直接 seek。

控制端每 3 秒上报一次当前状态，用于校准。

### 7.3 直播同步

直播不以 positionMs 为核心，而以直播延迟为核心。

建议同步字段：

```json
{
  "isLive": true,
  "targetLatencyMs": 3000,
  "playbackState": "playing"
}
```

客户端尽量保持距离直播边缘 3 秒左右。

直播控制：

- play：开始拉流。
- pause：暂停本地播放。
- syncToLive：回到直播边缘或目标延迟。

直播流由于源站、CDN、客户端缓冲策略不同，很难做到毫秒级同步。第一版目标应是让多个客户端处于接近的直播延迟。

## 8. 断线重连恢复

### 8.1 客户端本地保存

客户端本地保存：

```json
{
  "deviceId": "dev_abc",
  "lastRoomCode": "A7K29Q",
  "lastConnectedAt": 1780000000000
}
```

deviceId 是本地随机生成的设备标识。

它不是账号，也不是用户 ID，只用于：

- 断线重连。
- 控制权恢复。
- 同一设备重复连接识别。

### 8.2 重连流程

1. WebSocket 断开。
2. 客户端进入重连状态。
3. 客户端带 roomCode 和 deviceId 重连。
4. 服务端检查房间是否还存在。
5. 服务端返回 roomSnapshot。
6. 客户端重新解析播放源。
7. 点播房间根据 positionMs 和 serverUpdatedAt 恢复。
8. 直播房间恢复到目标直播延迟。

### 8.3 房主和控制权处理

建议第一版规则：

- 第一个加入房间成功的设备成为房主。
- 只有房主可以配置或更换播放源。
- 所有房间成员都可以播放、暂停、跳转进度、回到直播。
- 房主短暂断线 30 秒内，房主身份保留。
- 房主超过 30 秒未恢复，允许当前房间内最早在线的设备成为新房主。
- 房间无人后进入保留期，保留期间房主身份和房间状态仍然存在。

这个规则避免了用户体系，同时保留了“谁能换片”的边界。

## 9. 客户端架构

客户端建议拆成：

- RoomController：创建房间、加入房间、房间状态。
- SocketClient：WebSocket 连接、重连、事件收发。
- PlayerController：播放、暂停、seek、倍速、直播控制。
- SyncEngine：进度计算、误差校正、直播延迟同步。
- SourceManager：播放源初始化、凭据处理、URL 刷新。
- LocalDeviceStore：本地 deviceId 和 lastRoomCode。

## 10. 后端架构

后端第一版建议保持单体服务，不拆微服务。

最小结构：

- HTTP API：创建房间、加入房间、配置播放源、获取房间快照。
- WebSocket Gateway：播放、暂停、seek、直播同步、心跳、断线重连。
- Redis Store：房间状态、连接状态、播放源配置、过期时间。
- Stream Proxy：可选代理入口，只有房主开启代理模式时使用。

代码模块：

- RoomService：房间创建、房间加入、房主判定、快照维护。
- PlaybackService：播放状态写入和广播。
- SourceService：播放源保存、直连信息下发、代理 URL 生成。
- StreamProxyService：WebDAV/OSS/私有链接流式转发，不落盘存储。

暂时不做：

- 用户数据库。
- PostgreSQL。
- 微服务拆分。
- 消息队列。
- 文件存储。
- 复杂权限系统。

Redis Key 示例：

```text
room:A7K29Q
room:A7K29Q:connections
source:src_123
device:dev_abc:last
```

## 11. WebDAV 凭据结论

WebDAV 凭据问题可以概括为一句话：

> 客户端直连 WebDAV 时，客户端必须拿到凭据或等价授权；代理模式下客户端只拿我们服务端的播放 URL，原始凭据由服务端持有。

两种可选做法：

| 方案 | 客户端拿到什么 | 后端流量成本 | 安全性 | 实现难度 |
| --- | --- | --- | --- | --- |
| 直连模式 | 原始凭据或 Basic Auth Header | 低 | 低 | 低 |
| 代理模式 | 服务端代理 URL | 高 | 高 | 中高 |

代理模式的关键点：

- 服务端拿到用户的 key、Cookie、Header 或账号密码。
- 服务端向 WebDAV/OSS/私有源站发起请求。
- 服务端把响应流转发给客户端。
- 服务端不下载完整文件。
- 服务端不做硬盘存储。
- 服务端必须正确支持 Range、Content-Type、Content-Length、Accept-Ranges 等响应头。
- 服务端需要承担带宽、并发连接和转发稳定性压力。

第一版建议：

- 同时支持直连模式和代理模式。
- 房主配置播放源时通过按钮或开关选择连接方式。
- 默认连接方式是客户端直连。
- 代理模式必须由房主主动开启。
- 直连模式适合可信房间和低成本场景。
- 代理模式适合不想把 key 暴露给房间成员的场景。

## 12. 第一版里程碑

### Milestone 1：最小可跑通

- Windows 客户端。
- 轻量 Node.js 服务端。
- Redis 房间状态。
- 房间创建和加入。
- 普通 URL 播放。
- 播放、暂停、seek 同步。
- WebSocket 断线重连。

### Milestone 2：播放源扩展

- m3u8 直播流。
- OSS 签名 URL。
- WebDAV 直连模式。
- HTTP Header 支持。

### Milestone 3：同步体验打磨

- 周期性进度校准。
- 小误差倍速追赶。
- 大误差 seek。
- 直播回到实时。

### Milestone 4：移动端

- App 客户端。
- 复用房间和同步协议。
- 验证播放器内核能力。

### Milestone 5：代理能力增强

- WebDAV/OSS 最小流式代理。
- 凭据加密存储。
- 代理 URL 短期 Token。
- Range 请求和拖动进度优化。
- 源站 Header 透传和错误处理。
- 房间过期自动清理。

## 13. 关键风险

### 13.1 播放器能力风险

不同平台播放器能力不一致，尤其是：

- iOS 对部分格式限制更多。
- Android 机型和系统版本差异大。
- Windows mpv/libVLC 能力较强，但集成和打包需要验证。

第一阶段应优先做播放内核 PoC。

### 13.2 WebDAV 兼容风险

不同 WebDAV 服务差异很大：

- 鉴权方式不同。
- 是否支持 Range 请求不同。
- 是否支持文件直链不同。
- 是否限制 User-Agent 或 Header。

第一版应先支持最常见的 Basic Auth + Range。

### 13.3 服务端流式代理成本风险

如果服务端代理 WebDAV 或 OSS 视频流，所有视频流量都会走后端。

这会带来：

- 高带宽成本。
- 高并发压力。
- 大文件拖动复杂度。
- 直播流转发压力。
- 但不会带来硬盘存储压力，因为代理模式只做流式转发，不下载、不落盘。

因此代理模式适合安全要求更高的房间，但需要配套限流、超时、Range 支持和错误恢复。

### 13.4 直播同步风险

直播流本身缓冲和 CDN 延迟不稳定。

第一版不要承诺毫秒级同步直播，目标是保持相近的直播延迟。

## 14. 推荐第一版决策

建议第一版采用：

- Windows 和 App 分端开发。
- Windows 优先跑通。
- Windows 客户端使用 Python + PySide6 + python-vlc，并用 PyInstaller 打包。
- App 使用 HBuilder/uni-app + 原生 VLC 插件。
- 后端 Go + WebSocket + Redis。
- 服务端保持单体和轻量，不上 PostgreSQL，不拆微服务。
- 普通 URL、OSS、WebDAV、m3u8 直播优先。
- 播放源支持直连和服务端流式代理。
- 默认客户端直连，代理模式由房主手动开启。
- 第一个加入房间的设备为房主。
- 只有房主能配置或更换播放源。
- 所有人都可以播放、暂停、跳转进度、回到直播。
- 房间无人后 30 分钟销毁。

最终第一版交付目标：

> 用户创建或加入房间，第一个加入者成为房主并配置网络播放源；默认由客户端直接获取源站内容，房主也可以手动开启服务端代理；其他设备输入 Code 加入后自动播放同一来源，并同步播放、暂停、跳转；断线后自动回到房间当前进度；支持普通链接、OSS、WebDAV 和直播流；代理模式下服务端拿到 key 后流式转发给客户端，不下载、不落盘。