一次操作，怎样成为所有人的同一画面

客户端不直接互相修改播放器。播放、暂停、进度和倍速先发送到服务器；服务端完成认证、权限校验、房间状态更新与持久化，再通过 Socket.IO 广播权威结果。客户端按服务器时间和网络延迟校正播放位置。

跟随一次调用查看组件可视化架构下载 Markdown 源文档

桌面与移动端Electron / Android

浏览器客户端HTML / CSS / JS

服务端核心Express + Socket.IO

媒体流水线FFprobe / FFmpeg

本地数据目录config / uploads / secrets

HTTPS 公网入口cloudflared

邮件与可选 AISMTP / relay

拖动旋转 360° · 滚轮缩放 · 方向键微调

播放按钮按下后的完整调用链

下面以“房主点击播放”为例。上传、改权限、发公告和切换房间也遵循同样的可信边界：客户端提出意图，服务端决定结果。

1. 产生意图

房主在 Web、Electron 或 Android WebView 中点击播放。前端收集房间号、媒体 ID、播放位置和客户端时间，不把本地 UI 状态当作最终结果。

2. 建立连接

REST 请求通过 fetch 进入 Express；实时事件通过 Socket.IO/WebSocket 进入同一个 Node.js 服务。公网部署时 HTTPS 请求先经过 Cloudflare Tunnel 或自己的反向代理。

3. 认证与授权

服务端检查会话令牌、设备状态、房间成员身份、房主/管理员角色和具体操作权限。隐藏按钮只是体验层，真正的安全边界始终在服务端。

4. 更新权威状态

权限通过后更新房间的媒体、播放状态、进度、倍速和服务器时间戳。对媒体操作会调用 FFprobe 检测；需要兼容转换时启动 FFmpeg 子进程。

5. 持久化与审计

账号、房间、媒体索引、设置和记录写入服务器数据目录。敏感信息与普通配置分开保存，操作日志记录谁在什么时候对哪个范围做了什么。

6. 广播与校正

Socket.IO 将新的权威状态广播给房间成员。客户端以服务器时间推算当前播放点，对超过阈值的偏差跳转校正，小偏差则通过正常播放消化。

用了什么语言、环境和组件

运行时和平台能力分层组合。GitHub Pages 只承载这套静态文档，不运行服务器、WebSocket、上传或 Tunnel。

网页与实时通信

界面使用原生 HTML、CSS 和 JavaScript；Express 提供页面与 REST API；Socket.IO 负责房间事件、聊天、在线状态、权限变化和同步播放广播。

桌面与移动端

Windows/macOS 使用 Electron 连接网页界面与桌面能力；Android 使用 Java、C++ JNI、WebView 与 Node.js Mobile，前台服务维持手机服务器。

媒体与网络

FFprobe 识别媒体格式和轨道；FFmpeg 生成浏览器兼容版本与缩略图；cloudflared 只在用户开启公网访问时建立 HTTPS Tunnel。

构建与验证

npm/pnpm 管理依赖，Electron Builder 生成桌面成品，Gradle 构建 APK，GitHub Actions 执行 CI、Pages 和平台发布流程。

模块边界和代码入口

开发者先从职责找到入口，再沿调用链阅读；不要在前端重复实现服务端权限或数据规则。

区域	主要路径	职责	验证重点
桌面启动	`electron-pink.js` `electron-main-preload.js`	窗口、托盘、系统能力、打包资源和主进程通信	窗口生命周期、权限、资源路径
服务端	`server/index.js` `server-standalone.js`	Express、Socket.IO、认证、房间、媒体、Tunnel、数据和日志	鉴权、输入校验、并发和持久化
浏览器界面	`public/index.html` `public/js/app.js`	登录、播放器、管理中心、聊天、共享和客户端状态	权限呈现、断线恢复、响应式布局
Android	`mobile/app/src/main`	原生壳、WebView、前台服务、Node.js Mobile 与 ABI 资源	权限、省电、端口和包内运行时
发布与测试	`.github/workflows/` `tests/`	CI、Pages、Windows/macOS 构建、隐私和发布契约	实际产物、架构声明和敏感信息

数据怎样落盘

SyncWatch同步观影-Data/ 是运行数据根目录。它不是源码，也不应提交到 GitHub。

config.json

账号、房间、权限、服务器设置和媒体索引。修改应经过服务端接口，不建议停机外直接手改。

uploads/

用户上传的影片、音频、字幕、图片和文档；备份时必须和媒体索引保持一致。

secrets/

邮件凭据与管理员验证材料。绝不能出现在截图、Issue、日志粘贴或公开仓库。

兼容媒体与日志

兼容文件可由原片重建；日志和崩溃信息用于诊断，但分享前必须删除 IP、令牌、邮箱、姓名和媒体名称。

备份原则：停止服务后复制整个数据目录，或在软件里导出“全部数据与配置”。只保存 config.json 不是完整备份。

不同部署环境分别需要什么

支持平台以 Release 中实际存在的构建为准。macOS 不支持现代 32 位应用，不能把 Windows x86 声明套到所有系统。

场景	需要的环境	启动入口	网络边界
Windows 完整版	成品内置 Electron/Node/FFmpeg/cloudflared	安装快捷方式或独立 EXE	局域网；可选 Tunnel
源码开发	Node.js 22+，推荐 24 LTS；npm 依赖	`npm ci` 后 `npm start`	开发机端口与防火墙
独立服务端	Node.js 或 Release 服务端包	`npm run start:server`	反向代理、HTTPS、WebSocket、Range
Android 服务器	完整 APK 内置 Node.js Mobile	应用内启动前台服务	通知权限、省电策略、移动网络限制
Docker	Node.js 24 Linux 镜像及持久卷	容器启动命令	映射端口与数据卷，Tunnel 可选

查看运行环境教程查看仓库文件地图回到可视化架构下载 Markdown 源文档