# SyncWatch同步观影 常见错误与报错处理

本文适合第一次部署或遇到报错的用户。先记录：软件版本、平台、启动方式、完整错误文字、发生时间、是否局域网/公网、是否刚修改过端口或权限。提交 Issue 前删除真实姓名、邮箱、IP、令牌、房间链接和媒体文件名。

## 1. 启动与环境

### 未找到内置 cloudflared

完整服务器包应包含 `vendor/cloudflared.exe`。源码启动时可以在“服务器设置 > 公网访问 > 修复 cloudflared”自动从 Cloudflare 官方 Release 下载并校验 SHA-256。仍失败时检查 TCP/UDP 443、7844，关闭 VPN/TUN 的 Fake-IP 接管，或改用自己的 HTTPS 反向代理。

### 端口已被占用 / EADDRINUSE

关闭旧的 SyncWatch 进程，或在服务器设置改成未使用端口。Windows 可运行 `netstat -ano | findstr :5000`，再用任务管理器确认 PID。修改端口后必须重新生成并分享新的局域网地址。

### Node.js、npm 或依赖错误

源码部署需要 Node.js 22+，推荐 Node.js 24 LTS。执行 `node --version`、`npm --version`，然后删除不完整的依赖目录并运行 `npm ci`。不要混用多个 Node 版本的 `node_modules`。

## 2. 登录、房间与权限

### 页面能打开但登录失败

确认服务端进程没有退出；检查浏览器地址是否指向正确端口。首次账号是 `admin` / `admin888`，登录后必须立即改密码。若提示令牌过期，退出并重新登录，不要复制旧 Cookie。

### 成员无法加入房间

先确认房主仍在房间，核对房间号和房间密码，再检查 Windows 防火墙是否允许专用网络。公网访问时检查 Tunnel 状态和 HTTPS 地址。管理员在“日志中心”查看是密码错误、权限拒绝、房间不存在还是 Origin/Host 被安全策略拦截。

### 按钮消失或提示无权限

这是服务端权限结果，不是页面故障。使用有权限的账号重新登录，检查成员所属权限组、房主状态和申请是否已批准。不要通过修改浏览器脚本绕过权限，服务端会再次校验。

## 3. 媒体、上传和同步播放

### 上传卡住或审核后看不到

检查剩余磁盘空间、上传大小策略、文件是否仍在 `uploads/`，以及上传者是否有权限。日志应出现 upload、processing、approval 相关事件。大文件请使用稳定网络，不要在转换期间强制关闭服务器。

### 视频无法播放、黑屏或没有声音

先用原片在本机确认文件有效，再等待 FFprobe 分析。编码可解码不等于适合低速公网：超过 854×480 或平均码率超过约 1 Mbps 时，也要等待 FFmpeg 生成约 480P 的低带宽流畅版并选择它。受 DRM 保护、损坏或没有授权的媒体不能由 SyncWatch 修复。

### 成员不同步、进度反复跳回

房主先暂停，等待所有成员连接稳定，再从当前队列重新播放。检查网络延迟、浏览器后台节流、设备性能和媒体缓冲。服务器是权威时钟，客户端只提交意图，不要同时让多个人反复拖动进度。v2.2.0 在本地缓冲不足时不会反复硬跳转；若仍持续显示“正在定位”，请确认客户端确实加载的是转换后的流畅版 URL。

## 4. Android 与桌面端

### Android 手机服务器启动不了

使用完整 APK，不要使用不含内置 Node.js 的体验版。允许通知、前台服务、网络和文件访问权限，检查端口是否被占用；系统省电策略可能杀死后台服务，请将 SyncWatch 设为不限制电量。

### Android 登录显示 `SOCKET_EVENT_FAILED` 或 `SW-...`

先确认 APK 版本和服务器版本一致，并记录完整错误编号。v2.2.0 修复了部分 Node.js Mobile 18 运行时缺少 `crypto.randomUUID` 时，登录审计/游客账号创建直接抛异常的问题；新版使用 `randomBytes` 生成兼容 UUID。升级 APK 时不要卸载旧应用，使用同一签名覆盖安装并重新启动手机服务器；仍失败时将错误编号、手机系统版本、登录方式（管理员/普通账号/游客）和服务器日志一起提交，禁止公开密码或完整数据目录。

### Windows EXE 被安全软件拦截

从 GitHub Release 下载后核对 SHA-256，确认文件来自本仓库。首次运行时只允许你实际使用的网络类型通过防火墙；不要下载来历不明的“修复版”。

### macOS 无法打开或提示未验证开发者

优先下载真实 macOS runner 生成的 DMG/ZIP。首次打开可在“系统设置 > 隐私与安全性”允许已阻止的应用；屏幕共享、麦克风和摄像头需要单独授权。

## 5. 邮件、公网与备份

### SMTP 测试邮件失败

确认服务器、端口、TLS 和应用专用授权码。QQ 邮箱应使用授权码而不是网页登录密码；保存后点击“发送测试邮件”。如果授权码曾出现在日志或截图中，立即撤销并重新生成。

### 临时公网地址打不开

在“服务器设置 > 公网访问”查看 Tunnel 状态与诊断结果。检查 cloudflared 出站连接、系统代理、VPN/TUN 和房间密码。临时地址不是固定域名，重启后可能变化。

### 临时公网网页能打开，但手机视频卡住

1. 在“处理进度”确认该影片的流畅版已经完成，而不是标签回退到原文件；新版流畅版目标为 854×480、视频约 900 kbps、音频 96 kbps。
2. 对比影片平均码率与手机实际下载速度。服务器还要为每名公网成员提供一份出网上行；实测带宽只略高于码率时仍会频繁缓冲。
3. 打开浏览器网络面板，检查媒体请求是否返回 `206 Partial Content`、`Content-Range` 和持续增长的已缓冲区；连续 Range 超时通常是 Tunnel/代理链路不稳定，不是播放器没有收到同步命令。
4. 若 WebSocket 失败回退 Polling，也要检查登录、聊天或心跳回执是否超时。Clash/FlClash/VPN/TUN 用户让 cloudflared、浏览器和 Cloudflare 域名走同一可用规则，必要时关闭“绕过系统代理”。
5. 对比两处网络时使用同一版本、同一影片、同一房间和相同画质，分别记录 Tunnel 策略、WebSocket/Polling、首尾及随机 Range、`readyState`、`buffered` 和播放推进；不要仅凭临时域名不同判断原因。

### 备份恢复后缺文件

只导入 `config.json` 不等于完整恢复。停止服务器，使用包含媒体的二进制备份，或完整复制 `SyncWatch同步观影-Data/`，确认 `uploads/`、`secrets/`、聊天和缩略图都在，再启动。

## 6. 安全处理原则

不要公开运行数据目录、管理员密码、SMTP 授权码、主机令牌、完整日志、真实 IP 或成员聊天。无法确认原因时先停止公网访问、保留脱敏日志和 SHA-256，再通过 [SECURITY.md](../SECURITY.md) 私密报告安全问题。