# SyncWatch同步观影 v2.2.0

## 直接使用

双击 Release 中的 `SyncWatch-Standard-Server-Portable-v2.2.0-x64.exe`，或选择完整安装版/完整便携版。首次启动时，Windows 防火墙如有提示，请按实际网络允许访问。程序会在 EXE 同目录创建 `SyncWatch同步观影-Data/`，账号、设置、媒体、缩略图、字幕、语音、聊天、缓存和密钥全部保存在这里；把整个程序文件夹移动到另一台电脑或云服务器时，数据会随文件夹一起移动。

程序窗口打开后，从“系统 → 复制局域网地址”复制链接。同一 Wi-Fi 或有线网络内的手机、平板、电脑、笔记本和电视浏览器均可访问。

## 首次设置

1. 每个账户首次登录都要阅读并同意使用协议；同一协议版本接受后不会重复弹出。
2. 服务器设备可在登录页直接选择“服务器超级管理员登录”，初始账号/密码是 `admin/admin888`。首次登录后可直接填写新密码与确认密码，也可点“暂不更改”先进入；系统会保留安全提醒。
3. 普通用户可直接注册，注册时不要求房间号或房间密码；登录时房间号留空会先列出账号拥有或连接过的房间，用户可选择其中一个或进入退出即删除的临时房间。弹窗可暂停 1 小时、1 天、1 周、30 天或永久关闭，也可在账号菜单的“安全设置 → 登录房间提醒”重新开启。
4. 公网访问可直接开启。建议先设置房间密码；服务器也可启用“要求所有房主为房间设置访问密码”策略，启用后未加密房间的房主会收到常驻提醒。
5. 普通账号默认可上传 10 GB 视频；管理员可按权限等级和账号单独调整，值为 `0` 表示不限。

账号是否允许多设备同时登录由管理员按账户设置；超级管理员默认不限设备、建房和上传。密码默认每 7 天要求修改一次，可在服务器设置中改为 0 天以关闭周期限制。密码仅保存 PBKDF2 哈希，管理员只能重置密码，不能查看原密码。

每个注册账号默认可以创建 1 个独立房间并设置房间名称、密码和人数上限。需要更多房间时，可在建房窗口提交额度申请，由服务器管理员审批或直接提高账号额度。普通成员首次加入有密码房间时输入密码，房主未改密码前再次进入会自动授权；超级管理员始终免输房间密码。各房间的成员、聊天、媒体、播放队列、同步进度、灯光和屏幕共享互相隔离。

## 登录和房间操作

### 普通用户

1. 登录页会显示当前设备 IP，点击“复制”可发给服务器管理员核对注册限制。
2. 没有账号时点击“立即注册”，两次密码框都可点击“显示”检查输入。
3. 注册完成后可填写房间号、从“在线房间”下拉框选择、点击“新建房间”，也可把房间号留空进入临时房间；临时房间退出后自动删除，可由房主或管理员转为正式房间。
4. 输入房间号后，下方会立即显示房间名称、当前人数、人数上限和是否需要密码。
5. “查看我连接过和拥有的房间”需要验证账号密码，验证后可选择历史房间或自己拥有的房间进入。
6. 勾选自动登录后，桌面客户端会记住会话；主动退出会立即清理在线状态，不会在房间里留下“正在重连”。
7. “游客模式”只使用与普通房间成员相同的权限，不会因创建临时房间而变成房主；需要创建正式房间或申请建房额度时先注册账号。

### 房主

1. 点击“新建房间”，填写名称、自定义房间号、可选房间密码和人数上限。
2. 房主可配置本房间的播放、上传、删除、屏幕/网页共享、聊天管理、实时语音、公告和成员管理权限。
3. 上传文件或文件夹后，可在“转换进度”查看速度、已用时间和预计完成时间；需要兼容转换时服务器会自动处理。
4. 主动退出房间时必须选择“关闭房间”“删除房间”或“只退出，不关闭房间”。掉线和意外退出不会关闭或删除房间。
5. 主菜单提供明显的“解散房间”入口。删除房间会永久删除本房媒体、聊天、队列和记录，操作前会再次确认。
6. 当前房主可在成员面板的房间号区域直接修改房间号，影片、聊天、队列、历史和在线会话会同步迁移。

### 超级管理员和服务器设备

1. 服务器设备登录页可直接选择“服务器超级管理员登录”，填写账号和管理员密码。首次使用 `admin888` 后直接设置新密码和确认密码。
2. 验证成功后停留在管理中心服务器设置页，不填写房间号也不会先进入临时观影房间；只有管理员主动选择房间入口时才进入房间。
3. 超级管理员不能被其他人移出，退出时会立即离线，不会保留重连占位。
4. 管理中心可查看所有账号、设备、IP、在线会话、房间归属、成员、媒体占用、播放状态、权限、注册申请和建房额度申请。
5. 所有房间支持全选和批量删除。恢复出厂和批量删除都要求手工输入“我已知道这个风险”，也可点击旁边的一键粘贴。
6. 注册名额申请提醒可直接跳转到对应审批位置；批准后该 IP 获得一次额外注册名额。
7. 未登录时也可打开顶栏“服务器设置”，直接输入超级管理员账号和密码验证；成功后验证框自动消失，登录页保持可见而观影主界面保持隐藏，管理员可直接修改服务器权限和策略。需要观影时再主动进入指定房间。

## 播放、共享和通知操作

1. 默认清晰度是“原画”。房主选择影片后，成员会按服务器时间同步播放、暂停、进度和音量。
2. 全屏后点击画面可呼出控制；支持横屏、竖屏、手动放大缩小和悬浮播放/画中画。
3. “共享屏幕与声音”用于桌面或应用画面；“共享网页”可粘贴 HTTP/HTTPS 地址，并在原播放器区域向房间展示网页。
4. 表情、文字、语音和公告都会显示发送者。房主、超级管理员和服务器设备可设置屏幕公告的字体、颜色、字号和停留时间。
5. 退出应用窗口时选择“最小化到托盘”“退出程序”“重新启动”或“取消”。选择退出会安全关闭本机服务并释放端口和数据目录锁。

## 主要功能

- 房主同步播放、暂停、前后 10 秒、音量、锁定控制、控制权申请和强制同步；暂停时加入或网络重连后也会恢复当前影片与进度。
- 播放进度按服务器时钟校准，并根据房主真实播放/缓冲状态持续修正；“操作历史”记录房间设置、文件、队列、聊天和播放操作，可在数据未发生冲突时安全回溯。
- 浏览器阻止自动播放时，播放器中央会显示“点击继续同步播放”，点击后即可恢复。
- 全屏时点击画面可呼出聊天、私聊、弹幕和退出按钮；分辨率、编码及 GPU 信息默认隐藏，操作时才短暂显示。
- 视频库支持单文件、整个文件夹和上传中止，并保留文件夹层级；“我的影片”可折叠。另含封面缩略图、时长、分辨率、编码、音轨语言、播放队列、收藏、重命名和文件权限管理。
- 支持 MP4、MKV、WebM 等视频文件；实际解码能力取决于访问设备的浏览器，跨设备观看优先使用 H.264/AAC 编码的 MP4。SRT、ASS、SSA、VTT 字幕会自动匹配同名影片并转换为浏览器字幕。
- 公共聊天、指定成员私聊、房主公告、语音和历史分页；聊天与语音保存在服务器，私聊仅双方可读取，单条语音最大 25 MB。本人可删除自己的消息，房主可删除指定消息、清空指定账号或清空本房间聊天。
- 好友系统支持离线申请、备注与分组、消息常驻提醒、单人/全局免打扰、拒绝好友申请、图片和表情、引用回复、单条/批量删除及送达/已读状态。好友可互相邀请或申请加入当前房间；只有对方批准或主动开启“好友免密加入我的房间”后才会免输房间密码。
- 服务器可维护统一屏蔽词，弹幕、房间聊天、私聊、好友文字和图片说明都会在服务端校验，并向发送者显示命中的词。
- 上传任务可折叠到后台继续处理。服务器默认在上传后自动补建缩略图并生成浏览器兼容版；“我的影片”和“媒体处理进度”会实时显示转换中、等待及已完成数量。关闭路径是顶栏“处理进度” → 取消“上传完成后自动生成浏览器兼容版” → “立即应用”。兼容转换默认同时运行 3 个任务，管理员可在 1-8 之间调整，并可直接打开转换文件目录。
- 顶栏“AI聊天”提供独立的对话、生图和视频工作台，可配置兼容 Responses API / Chat Completions 的 HTTPS 中转地址、模型与接口路径。API 密钥只保存在当前设备，服务端中转会限制请求频率、响应大小并阻止内网地址访问。
- 个人中心、SW 用户 ID、显示名字、邮箱、设备、安全设置、我的影片、收藏和观影历史；用户可修改自己的显示名字，服务器管理员可强制修改、重置密码或删除非房主账号。
- 网络波动提示、无限重连、后台恢复、延迟和同步百分比上报。
- 同一 IP 已经注册时，注册页会一直显示“当前 IP 已注册？申请一次注册名额”，填写准备注册的账号和申请原因即可提交给服务器管理员。
- 关闭 Windows 窗口时，无论作为服务器还是客户端使用，都会选择“最小化到托盘”“退出程序”“重新启动”或“取消”；最小化后服务器与房间继续运行。
- 顶栏实时显示当前界面风格编号和名称；主题选择页同时显示每套风格的编号与名字。
- 房主、超级管理员和服务器设备可发送屏幕公告并设置字体、颜色、字号、停留时间和范围；表情和消息显示发送者。
- 默认清晰度为原画；全屏可切换横屏/竖屏并手动放大缩小，桌面、网页和 Android 支持悬浮播放/画中画。
- 屏幕共享采用低延迟画面帧同步，桌面端在系统和所选来源支持时会同时采集声音；Android 10 及以上客户端使用系统 MediaProjection 原生投屏，支持横竖屏热切换，并会在停止、锁屏、授权撤销、切换服务器或退出应用时自动结束。浏览器或受系统保护的窗口可能只允许共享画面。
- 网页和 Android 手机端在竖屏使用“观影 / 聊天 / 片库 / 成员”四个至少 44px 高的入口，一次只展开一个主模块；四个入口随页面自然滚动，不会固定遮住下方内容。片库和成员以全宽抽屉打开，观影工具在小屏下重排为两列。横屏保留播放器与聊天并排；功能项与 PC 端保持一致。
- 顶栏“生成 APK”会下载本 EXE 内置并经过签名校验的 `SyncWatch同步观影-v2.2.0.apk`。安装后输入电脑端显示的 HTTP 局域网地址或 HTTPS 公网地址，即可使用与网页端一致的房间、播放、聊天、上传、全屏和账户功能。
- Electron 桌面端已配置系统屏幕/窗口选择器与捕获授权。Android APK 支持原生屏幕投放、文件多选、递归文件夹上传、上传中止、麦克风、下载和系统全屏；iPhone/iPad 浏览器目前不开放网页屏幕捕获，可观看共享或上传媒体同步播放。

## 公网访问

只有服务器桌面窗口能看到“公网访问”。

公网访问默认允许直接开启。服务器管理员可按需启用“要求所有房主为房间设置访问密码”：启用后，未设置密码的在线房主会收到常驻提醒，离线房主下次进入时收到提醒；房主完成设置前不能控制播放，但房间内其他成员不会被强制退出。策略关闭时不会强制房间密码。

- 临时模式：自动下载官方 `cloudflared` 并生成 `trycloudflare.com` HTTPS 地址，适合临时聚会测试；地址每次启动会变化。
- 稳定模式：填写 Cloudflare Tunnel 令牌和已绑定的 HTTPS 域名，适合长期使用。令牌只放入子进程环境，不写入配置文件。

若当前网络阻断 Cloudflare Tunnel 出站连接，界面会提示边缘尚未验证。新版会在预检发现“系统出口可用、物理直连不可用”时优先系统网络，并在公网地址验证失败时继续切换备用策略。使用 Clash/FlClash/VPN/TUN Fake-IP 时，如果浏览器可联网但勾选“绕过系统代理”后失败，请取消勾选再重试；仍失败时让 `cloudflared.exe`、`api.trycloudflare.com`、`*.trycloudflare.com` 和 `*.argotunnel.com` 走同一条可用代理规则，或改用固定 Tunnel/自有 HTTPS 域名。

公网链接可以打开但手机视频卡住时，选择“流畅版”并在“处理进度”确认转换已完成。新版会为超过 854×480 或平均码率超过约 1 Mbps 的视频生成约 480P 低带宽版本；播放器本地缓冲不足时暂停强制定位。仍无法推进时记录手机实测下载速度、服务器上行、Tunnel 连接策略、播放器 `readyState`/缓冲区和 Range 请求结果，再按故障手册排查。

## 独立服务器部署

独立服务器 ZIP 是源码部署辅助包，不属于正式 Release 固定 26 项资产。使用时解压后编辑 `SyncWatch同步观影-Data/server-config.json`，Windows 双击 `start-server.cmd`；Linux x64 执行 `./start-server.sh` 或优先使用 Docker Compose。直接部署需要 Node.js 22 或更高版本，推荐 Node.js 24 LTS；Docker 镜像已自带 Node.js 24。

Windows Server、Linux、Docker Compose、自定义端口、安全组、域名 HTTPS、Nginx/Caddy WebSocket、内网穿透、QQ 邮箱找回、数据备份迁移和升级步骤，请阅读 [服务器部署与使用教程](server-deployment-guide.md)。该教程也会随独立服务器 ZIP 一起打包。

服务器数据统一位于包根目录的 `SyncWatch同步观影-Data/`。停止服务后请整体复制服务器包目录，不能只复制 `config.json`；QQ 邮箱授权码还依赖 `SyncWatch同步观影-Data/.secrets/mail.key`。运行地址、房主入口和实际监听端口写入 `SyncWatch同步观影-Data/服务器运行信息.txt`。端口可在 `SyncWatch同步观影-Data/server-config.json`、`PORT` 环境变量或 `--port` 参数中设置，优先级依次为命令行、环境变量、配置文件。

## 数据与安全

通过“系统 → 打开数据目录”可定位数据；独立服务器则直接打开包根目录的 `SyncWatch同步观影-Data/`。重要文件包括：

- `config.json`：账号哈希、多房间、权限、媒体、队列和操作历史配置。
- `chat-history.jsonl`：按房间隔离的聊天历史。
- `secrets/admin-password.json`：独立的超级管理员密码哈希。停止服务后删除整个 `secrets/` 会把 `admin` 账号和服务器管理员密码重置为 `admin888`，下次启动会重新创建该文件。
- `uploads/`、`thumbnails/`、`subtitles/`、`voice/`、`trash/`：媒体数据及支持安全回溯的临时回收数据。聊天永久保存在服务器；删除的文件、语音及相关回溯数据保留 30 天，过期后自动清理。

不要删除 `.secrets/`、`config.json` 或 `chat-history.jsonl`；这些文件分别保存邮件加密密钥与主机令牌、账户/房间状态和聊天记录。只有在明确需要恢复 `admin/admin888` 时才删除非隐藏的 `secrets/` 目录。`cache/`、`logs/`、`crash-dumps/` 是桌面端可再生缓存，服务器迁移时可一并复制，也可以在服务停止后清理。

生产依赖及完整构建依赖已通过 `npm audit`，结果为 0 个已知漏洞。EXE 未使用商业代码签名证书，首次运行可能出现 SmartScreen；正式公开分发建议配置代码签名证书。

最终 EXE SHA256：`A10C131DFDC6C8E35130EE5D9BB2BF3FC1998EA3229B8B64ACBDC4A5789D0FFC`。

## 从源代码重新生成 EXE

环境要求：Windows x64、Node.js 24 LTS（包含 npm），以及 Android Studio JBR/JDK、Android SDK 35、Build Tools 35.0.0、已缓存的 Gradle 8.13 与 Android Gradle Plugin 8.11.1。首次准备依赖时需要网络；正式发布脚本会离线构建并校验签名 APK。

```powershell
powershell -ExecutionPolicy Bypass -File .\build-windows.ps1
```

脚本先执行接口、硬化、媒体、Electron、多窗口同步、公网隧道和成品契约，再使用现有发布密钥构建并验证 Android v2.2.0 APK。Windows 与 Android 正式候选直接生成到根目录 `dist/`；缺少真实 macOS ZIP 时完整离线 EXE 会停止构建，不会用空文件或旧包补齐。

- `electron-pink.js`：桌面入口、屏幕捕获、托盘和公网隧道生命周期。
- `server/index.js`：HTTP、Socket.IO、账号、聊天、权限、文件与同步状态。
- `public/`：完全本地化的响应式界面。
- `mobile/`：Android WebView 客户端、离线签名构建脚本及最终 APK；请妥善备份 `.keys`，否则后续版本无法覆盖安装。
- `tests/`：接口、真实媒体、Electron 和隧道验收。
- [技术架构与依赖说明](architecture.md)：桌面端、服务端、前端、Android、数据、依赖版本、构建和测试的详细说明。

版权所有 © xuan