SyncTube 介绍与选型指南

目标：介绍开源同步观影服务 SyncTube 的定位、架构、功能与部署成本，并给出与 CyTube 等同类方案的横向对比和选型建议。全文结论均已在 Ubuntu 22.04（Node.js 20.18.1）上基于 SyncTube 1.0.0 实测验证。

一、环境信息

本文所有实测结论来自以下环境，读者复现时保持相近版本即可：

• 操作系统：Ubuntu 22.04（x86_64）
• SyncTube：1.0.0（GitHub 仓库 master 分支，钉住提交 7b0ea58，2026-08-23）
• Node.js：v20.18.1（node -v 实测）
• 服务监听端口：4200（默认，可配置）
• 嵌入源：局域网内另一台服务器 192.168.1.10:8080，由 nginx 提供 sample.mp4 与 stream.m3u8（HLS）测试媒体
• 源码目录：/opt/synctube

node -v   # 查看实测 Node.js 版本

实测回显：

v20.18.1

二、软件概述

2.1 定位与出身

SyncTube 是一个**单频道（one-channel）**的自托管同步观影服务：部署一个实例就得到一个"放映厅"，所有打开同一地址的人看到同一进度、同一播放列表，并通过内置聊天室交流。它解决的核心痛点是——异地朋友"同时按播放键永远对不齐"，以及把片源留在自己服务器上而不依赖第三方平台。

项目由开发者 RblSb 维护，采用 Haxe 语言编写、编译为 Node.js 服务端与浏览器端脚本分发。README 注明其原始想法（original idea）来自 Calvin Montgomery 的 sync 项目——也就是另一个老牌同步观影服务 CyTube 的前身，两者算同源分流的不同实现。查询日期为 2026-10-30，数据来自 GitHub API 与仓库页面。

2.2 开源许可与社区活跃度

版本节奏上，SyncTube 不发布正式 Release/Tag，package.json 中版本号长期停留在 1.0.0，更新以 master 分支提交形式滚动发布。因此生产部署建议像本文一样钉住某个具体提交（如 7b0ea58），保证可复现。

2.3 技术栈与部署成本

SyncTube 的部署成本极低，这是它最突出的工程特点：

• 依赖只有一个 npm 包：预编译产物 build/server.js（服务端）与 res/client.js（前端脚本）已直接提交在仓库中，npm ci 仅安装 WebSocket 库 ws；
• 单进程、单端口：一个 Node.js 进程同时提供 HTTP 页面与 WebSocket 同步通道，默认端口 4200；
• 无数据库：管理员、封禁、频道状态均以 JSON 文件保存在 user/ 目录，备份即拷贝。

💡 技术拓展：Haxe 是一种可编译到多种目标语言（JavaScript、C++、Java、Python 等）的高级语言。SyncTube 选择"Haxe 编译到 JavaScript"而不是直接写 Node.js，好处是服务端与浏览器端共享同一套类型定义（如视频条目 VideoItem、消息事件 WsEvent），协议字段改一处两端同步生效；代价是贡献者需要额外学习一门语言。对使用者而言这层完全透明——拿到手的已经是编译好的 build/server.js。

三、核心架构

3.1 单进程单端口架构

SyncTube 启动后只有一个 Node.js 进程监听 4200 端口，同时承担三类职责：

同一端口复用 HTTP 与 WebSocket，意味着部署时只需放行一个端口，反向代理配置也只需一条转发规则。实测启动回显（IP 为本文示例服务器）：

Loading state...
Local:   http://192.168.1.10:4200
Global:  http://182.54.113.29:4200

Local 是局域网地址（发给同网段的自己），Global 是公网出口地址（发给朋友）。

3.2 同步机制：Leader 权威时钟

同步采用 Leader（放映员）模型：拥有 Leader 身份的客户端执行播放/暂停/跳转/倍速，服务器维护一个权威时钟（时间 + 暂停态 + 倍速），所有客户端周期性通过 GetTime 消息校准本地播放器进度。配合要点：

• 任何人点击"Leader"按钮即可申请放映权（受权限配置约束）；
• 非Leader 的 seek/暂停会被忽略，保证全员进度一致；
• 聊天输入 /30、/-21 可快进/回退对应秒数，等价于 Leader 调整。

3.3 状态持久化

服务器的持久化全部落在 user/ 目录下的 JSON 文件，实测文件结构：

💡 技术拓展：管理员口令不是明文存储，服务端首次启动生成随机 salt，存储 sha256(密码 + salt)，WebSocket 登录时客户端同样提交哈希值而非明文。这一设计让 users.json 即便被拷走也无法直接还原口令，属于自托管服务里合理的基础安全水位；更高的加固需求（TLS、防火墙）见《SyncTube 1.0.0 配置参数详解》的 ssl 相关参数。

3.4 WebSocket 消息协议

客户端与服务端的一切交互都通过 JSON 消息完成，消息格式为 {"type": "<事件名>", "<事件名>": {...载荷}}。协议版本 serverVersion=2，服务端定义的事件枚举共 35 个，完整清单如下（这也是《SyncTube 1.0.0 API 使用详解》的主体）：

SyncTube 没有 REST API，程序化操作（机器人、自动化脚本）全部走这条 WebSocket 通道；服务进程另接受 5 条 stdin 终端命令（/addAdmin、/removeAdmin、/replay、/logList、/exit），详见《SyncTube 1.0.0 API 使用详解》。

💡 技术拓展：实时双向通信的常见方案对比——

方案	通信模式	适用场景
HTTP 轮询	客户端定时拉取	实时性要求低、实现最简单
SSE	服务端单向推送	只需下行推送的场景（如通知流）
WebSocket	双工长连接	双向低延迟（聊天、进度同步）

SyncTube 全站交互都选择 WebSocket：进度同步需要毫秒级双向校准，聊天需要服务端广播，一条连接即可承载，本文实测其端点与页面同在 4200 端口。

四、功能特性

4.1 播放器支持面

嵌入源支持由内置播放器类型 PlayerType 决定，共 5 种枚举值：

💡 技术拓展：RawType 直接播放直链视频与 HLS 流——HLS（HTTP Live Streaming）把视频切成若干 .ts 分片并以 .m3u8 播放列表索引，浏览器原生支持；对比整文件渐进式下载的 mp4，HLS 更适合直播与长视频拖动快进。本文实测把 nginx 提供的 http://192.168.1.10:8080/stream.m3u8 加入播放列表，服务端按 RawType 正常接受并广播。

SyncTube 没有显式的"嵌入源白名单"配置项——播放器支持面即嵌入源面，要接入新平台需依赖上游扩展播放器类型。

4.2 播放同步与 Leader 控制

• Leader 拥有全局播放/暂停/seek/倍速控制权，操作实时广播给全员；
• 倍速同步：Leader 调整播放速率，全员跟随；
• 投票跳过：任意用户可发起跳过投票，超过 voteSkipRatio（默认 0.51）即切下一曲；
• 外挂字幕与音轨：支持 vtt/srt/ass 字幕与外部配音音轨挂载。

4.3 播放列表管理

• 条目分临时/永久两种，临时条目播完自动移除；
• 支持插入到指定位置、置顶下一项、单条/全部切换临时态、随机打乱、锁定列表；
• 链接掩码批量添加：foo.com/bar${1-4}.mp4 一次展开 4 个条目；
• YouTube 播放列表可整表导入（需配置 youtubeApiKey，单次上限 youtubePlaylistLimit，默认 50）。

4.4 聊天系统

• 内置 37 个表情包、图片/链接自动渲染（filters 正则过滤链可自定义）；
• 服务端保留最近 serverChatHistory（默认 50）条历史，新加入者可见；
• 聊天命令：/30、/-1h9m54 快进回退、/fb 回退到误操作前、/volume 2.6 调音量、/clear 清屏（管理员全局清）、/help；
• 管理命令：/ban、/unban、/kick、/dump、/crash。

4.5 权限体系

权限按身份四级（banned/guest/user/leader/admin）配置，可分配的权限共 15 项：

默认配置下游客即拥有 writeChat、addVideo、removeVideo、changeOrder、toggleItemType、requestLeader、rewind，开箱即可"人人都能加点播"；收紧策略在《SyncTube 1.0.0 配置参数详解》的 permissions 一节展开。实测将 addVideo 从游客权限移除后，游客添加视频会收到服务端消息 accessError|addVideo，权限拒绝路径有效。

4.6 视频缓存（可选依赖）

安装 ytdlp-nodejs 与系统 ffmpeg/ffprobe 后，可开启"服务器缓存"：YouTube/VK/Vimeo 等视频先下载到本地再播放，默认缓存上限 3.0 GiB（cacheStorageLimitGiB）。未安装时该功能自动关闭，不影响其他功能。实测默认状态下 Connected 推送的 playersCacheSupport 仅含 RawType，安装缓存依赖后会追加 YouTube/VK/Vimeo。

4.7 前端定制

user/res 目录可覆盖任意前端文件（页面、样式、脚本、语言包），配置中的 emotes（表情）与 filters（正则替换）均可增删，便于做出自己的频道风格。

五、快速开始（最小可用示例）

本节给出从零到打开观影页面的最短路径，完整安装说明（含 systemd 托管、卸载）见《Ubuntu 22.04 安装 SyncTube 1.0.0 指南》。

5.1 获取代码并启动

sudo apt-get update && sudo apt-get install -y nodejs npm git   # Node.js 14+ 即可
sudo git clone https://github.com/RblSb/SyncTube.git /opt/synctube
cd /opt/synctube && sudo git checkout 7b0ea58   # 钉住实测提交
sudo npm ci                                      # 仅安装 ws 一个依赖
node build/server.js                             # 启动服务

实测启动回显：

Loading state...
Local:   http://192.168.1.10:4200
Global:  http://182.54.113.29:4200

5.2 初始化管理员

首次访问会强制进入初始化页。实测未建管理员时访问首页返回 302 跳转 /setup：

curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://192.168.1.10:4200/

实测回显：

302 redirect=http://192.168.1.10:4200/setup

在 /setup 页面输入用户名（示例 admin）、密码（示例 q1w2e3r4）提交，服务端返回 {"success":true}，管理员写入 user/users.json。之后访问 /setup 会跳回首页：

curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://192.168.1.10:4200/setup

实测回显（已存在管理员时）：

302 redirect=http://192.168.1.10:4200/

5.3 加入频道验证

浏览器打开 http://192.168.1.10:4200/，任意昵称登录即以游客身份进入频道；点击页面下方"+"按钮粘贴视频直链（如 http://192.168.1.10:8080/sample.mp4）即可加入播放列表，点击 Leader 按钮后即可控制全局播放。验证服务端已收到条目，可用任意 WebSocket 客户端向 ws://192.168.1.10:4200/ 发送 {"type":"UpdatePlaylist"}，服务端回推完整播放列表（实测回显节选）：

{
 "type": "UpdatePlaylist",
 "updatePlaylist": {
  "videoList": [
   {
    "author": "admin",
    "duration": 30,
    "isTemp": false,
    "playerType": "RawType",
    "title": "本地测试视频",
    "url": "http://192.168.1.10:8080/sample.mp4"
   }
  ]
 }
}

六、适用场景与限制

6.1 适用场景

• 亲友远程观影：几人到几十人的小圈子，片源自托管（mp4/HLS 直链），不依赖任何第三方平台账号；
• 兴趣社群点播夜：默认权限"人人可加点播 + 投票跳过"天然适合开放型频道，配合权限收紧也能做成管理员排片制；
• 内网教学/演示：局域网内统一播放讲解视频，Leader 控制进度，聊天区提问；
• 低成本常驻服务：单进程、无数据库、JSON 持久化，树莓派级别的小主机即可常驻。

6.2 已知限制

七、同类选型对比

7.1 与 CyTube 的区别

CyTube 是同步观影领域最成熟的开源方案（Node.js 编写，多频道模型）。两者同源（CyTube 前身 sync 是 SyncTube 的原始想法来源），但定位差异明显：

本站已有完整的 CyTube 实战系列，可对照阅读：《CyTube 介绍与选型指南》、《CyTube Docker Compose 部署指南》、《CyTube 配置参数详解》、《CyTube 常用命令与工具详解》。

7.2 其他同类方案

• SaaS 观影平台（watch2gether、Rave 等）：零部署，但片源受平台限制、房间不可自控、有广告与隐私顾虑，不适合"片源在自己手里"的场景；
• 通用媒体服务器 + 一起看插件（Jellyfin/Emby 的 watch party 插件）：适合已经搭好媒体库的家庭，但同步精度与聊天体验弱于专门的同步观影服务；
• 直播推流方案（OBS 推流 + 观看端）：完全单向，无点播、无互动控制权，仅适合"广播式"放映。

7.3 选型建议

• 如果只是小圈子看片、片源自托管、想要十分钟跑起来：选 SyncTube，部署成本最低；
• 如果需要多频道、用户注册、频道由不同人管理：选 CyTube，多频道与账号体系是硬需求时的正解；
• 如果已有 Jellyfin/Emby 媒体库只想加"一起看"：优先试其同步观影插件，不必引入新组件；
• 如果完全不想自托管：只能接受 SaaS 平台的片源与隐私限制。

八、参考链接

• 项目仓库：https://github.com/RblSb/SyncTube（MIT License，本文溯源与实测基于提交 7b0ea58，查询日期 2026-10-30）
• 官方默认频道示例：https://synctube.onrender.com/
• 原始想法来源（Calvin Montgomery 的 sync 项目，CyTube 前身）：https://github.com/calzoneman/sync
• 站内关联文档：《Ubuntu 22.04 安装 SyncTube 1.0.0 指南》、《SyncTube 1.0.0 配置参数详解》、《SyncTube 1.0.0 API 使用详解》