SyncTube 1.0.0 配置参数详解

目标：逐项讲清 SyncTube 1.0.0 全部 24 个配置参数的语义、默认值与实测行为，给出可直接套用的生产配置模板。全文参数行为均在 Ubuntu 22.04（Node.js v20.18.1）实测验证，权限与限制类结论附实测回显。

一、环境信息

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

• 操作系统：Ubuntu 22.04（x86_64）
• SyncTube：1.0.0（源码 master 分支，钉住提交 7b0ea58，2026-08-23）
• Node.js：v20.18.1（node -v 实测）
• 服务监听端口：4200（默认）
• 源码目录：/opt/synctube
• 服务器内网 IP：192.168.1.10（示例，下文回显中以此代指本机）
• 嵌入源：局域网内另一台服务器 192.168.1.10:8080，由 nginx 提供 sample.mp4 与 stream.m3u8（HLS）测试媒体

node -v   # 确认运行时版本
ls /opt/synctube/default-config.json   # 确认默认配置文件在源码根目录

实测回显：

v20.18.1
/opt/synctube/default-config.json

安装过程（在线/离线两种方案、systemd 托管）见《Ubuntu 22.04 安装 SyncTube 1.0.0 指南》，本文在其产出的运行环境上展开。

二、前置条件

2.1 已运行的服务

SyncTube 的配置全部在进程启动时一次性加载，改配置必须重启进程才生效。先确认服务处于运行状态：

systemctl is-active synctube
curl -s -o /dev/null -w '%{http_code}\n' http://192.168.1.10:4200/

实测回显：

active
200

2.2 两个配置文件的关系

服务端启动时先读 default-config.json，再用 user/config.json 中出现的键逐个覆盖（深合并）。因此升级 SyncTube（git pull 换提交）时，user/ 目录不受影响，个人配置天然保留。

⚠️ 注意：user/config.json 必须放在进程工作目录下的 user/ 里。systemd 单元按《Ubuntu 22.04 安装 SyncTube 1.0.0 指南》配置时 WorkingDirectory=/opt/synctube，即文件路径是 /opt/synctube/user/config.json。放错目录（比如自建的 /etc/synctube/ 或用户主目录）不会报错，但配置完全不生效——这是 SyncTube 配置排障的第一嫌疑点。

三、参数查看与修改方式

3.1 查看当前生效配置

SyncTube 没有 REST API，也没有 show config 类命令行入口。查看运行时生效配置的唯一标准途径是：任意客户端连上 WebSocket 端点（ws://<host>:4200/）后，服务端第一时间推送 Connected 事件，其 config 字段就是当前生效配置的快照。用 Python 一行探测：

python3 - <<'EOF'
import json, websocket
ws = websocket.create_connection("ws://192.168.1.10:4200/", timeout=6)
ev = json.loads(ws.recv())
cfg = ev["connected"]["config"]
print(json.dumps({k: v for k, v in cfg.items() if not isinstance(v, (list, dict))},
                 ensure_ascii=False, indent=1))
ws.close()
EOF

实测回显（默认配置，标量键节选）：

{
 "channelName": "SyncTube",
 "isVerbose": false,
 "maxLoginLength": 20,
 "maxMessageLength": 500,
 "port": 4200,
 "requestLeaderOnPause": false,
 "serverVersion": 2,
 "templateUrl": "https://youtube.com/playlist?list=PL9FiZUDVMu9tc_85frYognMOVFC_-VkSX",
 "totalVideoLimit": 0,
 "unpauseWithoutLeader": false,
 "userVideoLimit": 0,
 "voteSkipRatio": 0.51,
 "youtubePlaylistLimit": 50
}

config 快照里同时包含 salt（服务端随机盐）、permissions（展开后的权限表）、emotes/filters（列表，回显已折叠）——权限表的细节见 5.7 节。

3.2 修改配置的标准流程

三步：写 user/config.json → 重启服务 → 用 3.1 的探测验证。本文以覆盖三个典型参数做全程演示（每个参数的行为实测见对应小节）：

sudo tee /opt/synctube/user/config.json <<'EOF'
{
	"channelName": "我的观影频道",
	"maxMessageLength": 200,
	"requestLeaderOnPause": true
}
EOF
sudo systemctl restart synctube
systemctl is-active synctube

实测回显：

active

💡 技术拓展：配置生效方式常见两种流派——热加载（进程监听配置文件变更，如 Nginx 的 reload、Prometheus 的 /-/reload）与重启生效（启动时读取一次）。SyncTube 属于后者且无热加载信号处理，systemctl restart 是唯一途径；好处是行为可预期（不存在"改了一半"的中间态），代价是重启瞬间断开所有观众的 WebSocket 连接（浏览器会自动重连并恢复进度，实际观影中断约 2~3 秒）。

3.3 覆盖生效验证

重启后重跑 3.1 的探测脚本，实测回显（与默认值不同的键）：

{
 "channelName": "我的观影频道",
 "maxMessageLength": 200,
 "requestLeaderOnPause": true,
 "maxLoginLength": 20,
 ...
}

三个覆盖键全部生效，未覆盖的键保持默认。后文各参数的行为实测均基于这次覆盖后的状态展开。

四、参数总览（24 个顶层键）

default-config.json 顶层共 24 个键，按用途分七类。默认值如下表（与源码 src/Types.hx 的 Config/ServerConfig 类型定义一一对应）：

💡 技术拓展：youtubeApiKey 的默认值是仓库作者内置的公共 Key（default-config.json 明文可见），仅供体验。公共 Key 随源码公开、配额全网共享，随时可能失效——生产环境务必替换为自己的 Key。该值属第三方 API 凭据，本文正文一律以 ${YOUTUBE_API_KEY} 占位，注入方式：

# 在 systemd 单元的 [Service] 段注入后重启，配置文件中引用见 5.5 节
sudo systemctl edit synctube
# 写入：
# [Service]
# Environment=YOUTUBE_API_KEY=你的Key

五、核心参数分类详解

5.1 服务基础参数（port / channelName / maxLoginLength / maxMessageLength）

port（默认 4200）：单进程单端口，HTTP 页面与 WebSocket 同端口承载。端口被占用时服务不会启动失败，而是自动顺延——实测在服务已运行时再启动第二个实例：

> Warning: port 4200 is already in use. Changed to 4201
> Local: http://192.168.1.10:4201

这意味着防火墙/反代要放行的端口必须以实际监听为准，多实例部署时尤其要盯启动日志。

channelName（默认 "SyncTube"）：频道名，出现在浏览器标题与 Connected 推送的 config.channelName。本文覆盖为 我的观影频道 后实测推送值同步变化（3.3 节回显），网页标题栏同步显示新名称。

maxLoginLength（默认 20）：昵称最大字符数。登录昵称超长时服务端直接拒绝（源码 src/server/Main.hx:1346 对 name.length > config.maxLoginLength 返回错误），前端登录框同步限制 maxLength。

maxMessageLength（默认 500）：单条聊天消息最大长度。行为是截断而非拒绝：实测在覆盖为 200 后发送一条 300 字消息，服务端广播回来的文本恰好 200 字（末尾为第 200 个"测"字），前 200 字完整保留。

5.2 频道状态参数（serverChatHistory / totalVideoLimit / userVideoLimit）

serverChatHistory（默认 50）：服务端在内存中保留的最近聊天条数，新观众加入时通过 Connected 的 history 字段一次性下发。超过上限时最老的记录被移出（源码 src/server/Main.hx:758 的 messages.shift()）。实测环境发出 3 条消息后，Connected.history 返回 2 条（最早一条因会话重启清空），未达 50 上限——该参数的上限裁剪逻辑以源码为准，日常用量（小圈子观影）极少触及。

totalVideoLimit（默认 0=不限）：播放列表总条目上限。非 0 时列表满后再添加返回服务端消息 totalVideoLimitError（源码 src/server/Main.hx:780-781）。实测把默认 0 保持不动，全片单可无限增长——公网开放频道建议设为 200~500 防刷。

userVideoLimit（默认 0=不限）：单个非管理员用户在列表中的条目数上限，按"该用户仍是作者的有效条目"计数（源码 src/server/Main.hx:784-785 明确排除 client.isAdmin），超限返回 userVideoLimitError。管理员不受限，保证排片治理能力不受自己配的规则拖累。

5.3 Leader 与播放行为参数（requestLeaderOnPause / unpauseWithoutLeader / voteSkipRatio）

SyncTube 的播放控制权集中在 Leader（放映员）手里，这三个参数决定"观众与 Leader 权的交互体验"：

requestLeaderOnPause（默认 false）：开启后，观众在视频播放中点击暂停时，客户端自动先申请 Leader 再暂停（源码 src/client/Player.hx:376-382：hasAutoPause && !main.hasLeader() 时自动 SetLeader）。适合"人人随时暂停讨论"的亲密小圈子；公网频道切勿开启，否则任意观众一点暂停就抢走放映权。本文覆盖为 true 后，Connected.config.requestLeaderOnPause 推送值实测变为 true。

unpauseWithoutLeader（默认 false）：开启后，无 Leader 时观众点击播放不必先申请 Leader，直接接管并继续播放（源码 src/client/Player.hx:336-344 的 allowUnpause = main.hasUnpauseWithoutLeader() 分支）。与上一项组合出三种频道气质：

voteSkipRatio（默认 0.51）：投票跳过当前视频所需的在线人数比例。服务端计算所需票数为 ceil(在线人数 × voteSkipRatio)（源码 src/server/Main.hx:879）。实测单人在线（1 × 0.51 → 1 票）发起 SkipVideo 后立即切条并广播 SkipVideo 事件；多人时未达票数则广播 SkipVideoStats {voted, total, required} 进度。0.51 意味着"过半即切"——派对场景可降到 0.3 让跳片更顺滑，放映制频道可升到 0.8 甚至直接收紧 removeVideo 权限。

5.4 网络与访问控制参数（localAdmins / allowProxyIps / localNetworkOnly / enableCORS / ssl 组合）

localAdmins（默认 true）：来自服务器本机的 HTTP 请求自动按管理员对待（源码 src/server/Main.hx:516：isAdmin = config.localAdmins && req.socket.localAddress == ip）。也就是说在本机上 curl http://127.0.0.1:4200/ 的一些管理性访问不需要口令。反面：把 SyncTube 跑在多人共用登录的跳板机上时，任何本机用户都等效管理员——共享主机上建议改 false。

allowProxyIps（默认 true）：开启后服务端从 X-Forwarded-For 头取第一段作为客户端真实 IP（源码 src/server/Main.hx:429-436），封禁、访客计数都基于该值。放在 Nginx 反代后面必须保持 true，否则封禁封到的是反代 IP（一封全封）；裸机直连公网时可关掉，避免客户端伪造该头绕过封禁。

localNetworkOnly（默认 false）：开关型"内网闸门"。开启后服务只监听 127.0.0.1（源码 src/server/Main.hx:146 localIp = "127.0.0.1"，Main.hx:235 以该地址 listen），外网完全不可达。典型用法：本机跑一个"私人放映厅"，再用反代套认证对外发布。

enableCORS（默认 false）：给 HTTP 响应加跨域头（源码 src/server/HttpServer.hx:93）。SyncTube 页面与接口同源，日常部署用不到；仅当你要在另一个域名的网页里脚本化调用它的 HTTP 接口（如上传接口）时才需要开。

sslKeyPemPath / sslCertPemPath（默认均为空）：两个都填绝对路径且文件存在时，服务端整体切换为 HTTPS/WSS（源码 src/server/Main.hx:252-267：任一缺失仅打一行警告并以 HTTP 启动）。证书签发后填：

{
	"sslKeyPemPath": "/etc/letsencrypt/live/movie.example.com/privkey.pem",
	"sslCertPemPath": "/etc/letsencrypt/live/movie.example.com/fullchain.pem"
}

重启后浏览器直接以 https://movie.example.com 访问。更多基于反代的 TLS 收口与防火墙思路见《CyTube 配置参数详解》中同类键的对照（两者键名不同、思路一致）。

5.5 YouTube 集成参数（templateUrl / youtubeApiKey / youtubePlaylistLimit）

templateUrl（默认为官方示例播放列表链接）：添加视频输入框的"模板链接"——点输入框旁的模板按钮时预填的 URL，方便频繁从同一个 YouTube 播放列表取片。纯前端体验项。

youtubeApiKey：YouTube Data API v3 密钥，两处消费：YouTube 播放器取视频元数据（标题/时长）、整表导入 YouTube 播放列表。未配置自有 Key 时用仓库内置公共 Key（见第四节的技术拓展）。注入示例：

# /opt/synctube/user/config.json 中引用注入的环境变量需自行展开后写入：
# "youtubeApiKey": "${YOUTUBE_API_KEY}" ← 直接写这个字符串无效！
# 正确做法：写入前先在 shell 里展开
printf '{\n\t"youtubeApiKey": "%s"\n}\n' "$YOUTUBE_API_KEY" \
  | sudo tee /opt/synctube/user/config.json
sudo systemctl restart synctube

youtubePlaylistLimit（默认 50）：单次导入 YouTube 播放列表的最大条目数，防止误导入上千条的"听歌单"瞬间撑爆播放列表。与 totalVideoLimit 叠加生效（先到者截停）。

5.6 视频缓存参数（cacheStorageLimitGiB / ytDlp）

这两个键组成"服务器端视频缓存"特性：把 YouTube/VK/Vimeo 视频先下载到服务器再推流给观众（省外部带宽、多人观看只拉一次源）。未安装缓存依赖（npm 包 ytdlp-nodejs + 系统 ffmpeg/ffprobe）时整个特性自动关闭，实测默认状态下 Connected 推送的 playersCacheSupport 仅含 ["RawType"]，安装依赖后追加 Youtube/Vk/Vimeo 三类。

cacheStorageLimitGiB（默认 3.0）：缓存目录的磁盘占用上限，服务端按 3.0 × 1024³ 字节换算（源码 src/server/Main.hx:144），超限按 LRU 淘汰旧缓存。小盘 VPS 建议 1~2。

ytDlp（默认 {"channel": "stable", "jsRuntime": "node"}）：内置 yt-dlp 下载器的版本通道（stable）与运行 YouTube 挑战脚本用的 JS 运行时（node）。一般无需改动；遇到 YouTube 风控升级、解析失败时可把 channel 换成 nightly 通道获取更新的 yt-dlp。

5.7 权限参数 permissions（15 项权限 × 四级身份）

permissions 是 SyncTube 最核心的治理参数，默认值原文（default-config.json）：

"permissions": {
	"banned": [],
	"guest": ["writeChat", "addVideo", "removeVideo", "changeOrder", "toggleItemType", "requestLeader", "rewind"],
	"user": ["guest"],
	"leader": ["user"],
	"admin": ["user", "clearChat", "setLeader", "lockPlaylist", "banClient"]
}

两个关键语法：

1. 继承缩写：数组里写 "guest"/"user" 这类身份名，表示"继承该身份的全部权限"。所以默认配置的实际含义是——user = guest 的 7 项，leader = user 的 7 项，admin = user 的 7 项 + 4 项管理权。
2. 运行时展开：Connected 推送的 config.permissions 是展开后的完整列表。实测回显（本文覆盖配置下的真实推送，节选）：

"permissions": {
 "guest":   ["writeChat","addVideo","removeVideo","changeOrder","toggleItemType","requestLeader","rewind"],
 "user":    ["writeChat","addVideo","removeVideo","changeOrder","toggleItemType","requestLeader","rewind"],
 "leader":  ["writeChat","addVideo","removeVideo","changeOrder","toggleItemType","requestLeader","rewind"],
 "admin":   ["clearChat","setLeader","lockPlaylist","banClient","writeChat","addVideo","removeVideo",
             "changeOrder","toggleItemType","requestLeader","rewind"]
}

可分配的权限共 15 项：4 个身份占位（banned/guest/user/leader/admin 中的后四个，用于继承引用）+ 11 个功能权限，功能权限全表：

四级身份的行为边界（实测）：

• guest（游客）：默认 7 项权限，开箱即可"人人都能加点播"。实测把 addVideo 从 guest 权限移除并重启后，游客发送 AddVideo 收到 {"type":"ServerMessage","serverMessage":{"textId":"accessError|addVideo"}}，权限拒绝路径有效；
• user（注册用户）：登录口令认证后的身份（group 位标志含 User=2），默认权限与 guest 相同；
• leader：当前放映员，默认权限与 user 相同（Leader 是临时角色而非更高权限层，控制权由服务端 Leader 状态决定，不由 permissions 决定）；
• admin（管理员）：默认 = user 7 项 + clearChat/setLeader/lockPlaylist/banClient 4 项管理权。实测管理员登录成功后 group=10（User=2 + Admin=8），取得 Leader 后 group=14（+Leader=4）；
• banned：默认 []。被封禁用户 group 实测为 3（Banned=1 + User=2），只能看不能说（writeChat 都没有），封禁到期自动恢复。

💡 技术拓展：group 数值是位标志（bitmask），四位从低到高为 Banned=1 / User=2 / Leader=4 / Admin=8，客户端按位与解析身份。对比常见"角色枚举"（0=guest,1=user…）设计，位标志可以用一个整数表达叠加态（如"被封的管理员"=1+8=9），WS 消息里也只需传一个数字——这是协议紧凑性的经典取舍。

5.8 前端定制参数（emotes / filters）

emotes（默认 37 个）：聊天表情包数组，每项 {"name": ":adorable:", "image": "https://...png"}。聊天中输入 :name: 即渲染为图片。指向外链图床（默认全部 imgur），内网环境建议把图片下载到 user/res/ 本地化后改成相对路径。

filters（默认 2 条）：聊天文本的正则替换链，按顺序执行。默认两条分别是：图片直链自动渲染为 <img>（image 规则）、URL 自动渲染为可点击 <a>（url 规则）。可以追加自定义规则实现敏感词替换、Markdown 片段渲染等，例如追加一条把 :star: 渲染为星星图片：

"filters": [
	{"name": "image", "regex": "(https?:\\/\\/[^']*\\.)(png|jpg|gif|jpeg|webp)([^' ,]*)", "flags": "g",
	 "replace": "<a href='$1$2$3' target='_blank' rel='noopener noreferrer'><img src='$1$2$3' class='chat-img'/></a>"},
	{"name": "url", "regex": "(^|[^'])(https?:\\/\\/[^' \t]*)", "flags": "g",
	 "replace": "$1<a href='$2' target='_blank' rel='noopener noreferrer'>$2</a>"},
	{"name": "star", "regex": ":star:", "flags": "g", "replace": "⭐"}
]

⚠️ 注意：filters.replace 注入的是 HTML。自定义规则时不要把用户可控内容包进 <script> 等危险标签——默认两条规则的正则都对 URL 做了边界约束，模仿其写法即可。整体前端（页面/样式/语言包）的深度定制走 user/res/ 目录覆盖机制，不在本参数范畴。

六、生产配置模板

6.1 场景模板：亲友小圈子（2~30 人，国内 VPS 2C4G、普通云盘）

默认配置已经很接近最优——默认"人人可加点播 + 过半投票跳过"正是小圈子氛围。建议只做三点收紧（防失联访客误操作）：

{
	"channelName": "家庭影院",
	"totalVideoLimit": 300,
	"userVideoLimit": 50,
	"serverChatHistory": 100
}

要点：限制列表总量与单人条目数防误刷；聊天历史加倍方便后来者翻聊天记录找片名；其余（含 permissions）保持默认。

6.2 场景模板：公网开放频道（Nginx 反代 + TLS，4C8G、100G 盘）

{
	"port": 4200,
	"channelName": "公共观影厅",
	"maxMessageLength": 200,
	"totalVideoLimit": 200,
	"userVideoLimit": 10,
	"requestLeaderOnPause": false,
	"unpauseWithoutLeader": false,
	"localAdmins": false,
	"allowProxyIps": true,
	"voteSkipRatio": 0.6,
	"cacheStorageLimitGiB": 20,
	"permissions": {
		"banned": [],
		"guest": ["writeChat", "requestLeader", "rewind"],
		"user": ["guest"],
		"leader": ["user"],
		"admin": ["user", "addVideo", "removeVideo", "changeOrder", "toggleItemType",
		          "clearChat", "setLeader", "lockPlaylist", "banClient"]
	}
}

与默认的差异全部有明确理由：游客只留"说话/申请放映/拖进度"，点播权收归管理员（排片制，杜绝恶意刷列表）；暂停/播放不自动接管 Leader（防抢权）；localAdmins=false（本机不再隐含管理员，管理动作全部走口令认证）；allowProxyIps=true 配合 Nginx 反代拿到真实客户端 IP；消息限长、投票比例提高；磁盘宽裕给缓存 20 GiB。部署形态（Nginx 反代片段、防火墙）见《Ubuntu 22.04 安装 SyncTube 1.0.0 指南》的配置说明一节，程序化对接（机器人、自动排片）见《SyncTube 1.0.0 API 使用详解》。

七、常见问题

Q1：改了 user/config.json 重启后没生效？

按顺序排查三个嫌疑：① 文件放错目录——必须在进程工作目录下的 user/（systemd 部署即 /opt/synctube/user/config.json），用 ls -l /proc/$(systemctl show -p MainPID --value synctube)/cwd 确认工作目录；② JSON 语法错误（多余逗号、中文引号）——python3 -m json.tool /opt/synctube/user/config.json 能过则语法无恙；③ 只写注释或键名拼写错——SyncTube 对未知键静默忽略，拼错的键不报错也不生效。

Q2：怎么确认某个键当前的真实生效值？

唯一途径是 WS Connected 推送（见 3.1 节脚本）。没有 HTTP 查询接口，也没有日志打印完整配置。

Q3：youtubeApiKey 可以留默认吗？

可以先用（仓库内置公共 Key），但公共 Key 配额全网共享、随时可能耗尽或失效，YouTube 相关功能（元数据、整表导入）会莫名报错。生产替换为自有 Key 并按第四节方式注入。

Q4：permissions 改完游客还能加视频？

先确认重启生效（3.3 节），再确认改的是展开前的正确身份层——例如只想禁游客点播但保留注册用户，应把 guest 收紧、user 继承 guest 后再追加 addVideo。配置是继承语法，Connected 推送里看到的是展开结果，两者对照排查（5.7 节）。

Q5：HTTPS 证书配了却还是 HTTP？

sslKeyPemPath/sslCertPemPath 必须同时指向存在的文件且为绝对路径，任一缺失只在启动日志打一行警告、服务照常以 HTTP 启动（源码 src/server/Main.hx:252-267）。查 journalctl -u synctube -n 10 --no-pager 里的 sslKeyPemPath: absolute file path not found 提示。

Q6：端口顺延了，网页打不开？

port 被占用时服务自动换 4201 等空闲端口（5.1 节实测），此时配置里的 port 与实际监听不一致。要么释放占用端口的进程，要么把配置改成实际端口并重启，防火墙按实际端口放行。

八、参考链接

• SyncTube 仓库：https://github.com/RblSb/SyncTube（本文参数语义与源码行号基于提交 7b0ea58，查询日期 2026-10-30）
• 站内关联文档：《SyncTube 介绍与选型指南》、《Ubuntu 22.04 安装 SyncTube 1.0.0 指南》、《SyncTube 1.0.0 API 使用详解》
• 同类对照：《CyTube 介绍与选型指南》、《CyTube 配置参数详解》