ZViewer

多人同步观影、追番与远程共享平台。

English | 中文

Telegram QQ

强烈推荐使用 Chrome / Edge 等高版本（内核 130+）的 Chromium 内核浏览器访问 ZViewer。

⚠️ 不推荐 Safari 和 Firefox 浏览器——由于其对 MSE / MKV / 浏览器端解码与转码等能力的支持差异，可能出现播放卡顿、部分视频无法解码、字幕提取异常等 bug。

• 功能特性
• 快速开始
• 端口说明
• HTTPS 与证书
• Docker 部署
• GitHub Actions 自动构建
• 本地开发
• 环境变量
• 权限模型
• 视频源
• ZViewerCLI 本地代理
• 常见问题

• 创建或加入房间，与好友同步观看。
• 房主拥有播放控制权：播放、暂停、跳转、倍速。观众可申请控制，房主确认后执行。
• 房主离线时观众自动进入"自主控制模式"，可直接控制播放器；房主重连后自动恢复申请模式。
• 播放记忆：房主短暂断线后，由服务器继续广播当前状态，观众无需中断观看。
• 房主离线超时自动关房（10 分钟）。

• 原生字幕系统：直接解析 SRT / ASS / SSA / VTT / SMI / SUB 并用 HTML/CSS 渲染，不再转换为 WebVTT，样式还原度更高。
• 内嵌字幕浏览器端提取：MKV 容器内的文本字幕轨由浏览器直接解析容器提取（自研 MKV demux，稀疏扫描跳过音视频负载），GB 级大文件秒级出字幕，无需在服务器安装 FFmpeg。
• 浏览器端音频转码（ffmpeg.wasm）：DTS / AC3 / EAC3 等浏览器不兼容音轨可在浏览器内实时转码为 AAC 播放（需管理后台开启全局许可并在添加影片时勾选，默认关闭）。

• 评论面板与弹幕系统：支持 Bilibili 官方弹幕、DandanPlay 弹幕、自定义弹幕轨道。
• 播放状态同步：房主操作实时同步给所有观众。
• 观众可申请暂停或跳转，房主在播放器左上角查看通知并决定是否通过。
• 语音聊天：房主开启后，观众实时收听（固定 128kbps 比特率）。

• 基于 WebRTC 的屏幕共享，支持分享端共享屏幕或视频画面。
• OBS RTMP 推流支持，配合 Node Media Server 提供 HTTP-FLV 拉流（通过后端 /live 代理）。

• Material You (Monet) 动态主题，从壁纸提取色彩生成完整色板。
• 明暗主题切换、自定义背景、玻璃拟态 UI、精简动画模式。

系统首次启动时自动创建超级管理员账号：用户名 root，密码 root。生产环境部署后请立即修改默认密码。

无需安装 Node.js / npm，直接下载 Releases 中的压缩包，解压后运行：

# Windows
start.bat              # 交互菜单
start.bat start        # 启动服务

# Linux
./start.sh             # 交互菜单
./start.sh start       # 启动服务

项目根目录的 start-prod 脚本会自动检测并安装依赖、按需构建、启动服务。

Windows：

.\start-prod.bat              # 交互菜单
.\start-prod.bat start        # 启动（HTTP 前后端）
.\start-prod.bat stop         # 停止服务
.\start-prod.bat status       # 查看状态
.\start-prod.bat cert         # 签发 SSL 证书
.\start-prod.bat https        # 签发证书 + HTTPS 启动

Linux / macOS：

./start-prod.sh               # 交互菜单
./start-prod.sh start
./start-prod.sh stop
./start-prod.sh status

========================================
  ZViewer 服务管理
========================================
  1) 启动服务 (HTTP)
  2) 仅启动后端（可选 HTTP / HTTPS）
  3) 停止服务
  4) 重启服务
  5) 查看状态
  6) 查看日志
  7) 一键签发 SSL 证书
  8) HTTPS 启动（自动签发证书）
  9) 构建前后端（源码版）
  0) 退出

生产模式下，仅 3333 端口对外暴露。后端统一处理 API 请求、前端静态资源、WebSocket 实时通信，并将 /live 路径反向代理到内部 HTTP-FLV 服务，无需额外配置。

证书工具（zviewer-cert，源码为 scripts/generate-cert.js）按地址类型自动选择签发方式：

# 域名 → 自动申请 Let's Encrypt 可信证书
start.bat cert example.com
./start.sh cert example.com

# 公网 IP → 自动申请 Let's Encrypt 可信证书
start.bat cert 1.2.3.4

# 内网 IP → 自签证书
start.bat cert 192.168.1.1

# 强制重新签发
start.bat cert example.com --force

1. 域名已解析到本机公网 IP，或公网 IP 直接指向本机。
2. 本机 80 端口空闲且防火墙/安全组放行（ACME HTTP-01 验证）。
3. 正式环境有速率限制（每域名每周 5 张），调试可用 --staging 测试环境。

证书文件位于 config/ssl/（cert.pem 证书链、key.pem 私钥、acme-account.key ACME 账号）。

HTTPS 模式下后端统一提供前端页面和 API，访问 https://localhost:3333。

Docker 镜像使用 HTTP 模式启动，后端统一托管前端静态文件，不自动签发证书。如需 HTTPS，建议在 Docker 前加一层反向代理（Nginx / Caddy）。

docker run -d \
  --name zviewer \
  --restart unless-stopped \
  -p 3333:3333 \
  -p 3334:3334 \
  -v zviewer-data:/app/config \
  zerowyc0721/zviewer:latest

注：更新流程会替换容器内程序文件后在容器内直接重启后端进程，无需重启整个容器，也不依赖 restart 策略。 建议保留 --restart unless-stopped 以应对后端异常退出（非更新触发）时的自动恢复。

services:
  zviewer:
    image: zerowyc0721/zviewer:latest
    ports:
      - "3333:3333"   # 统一入口（API + WebSocket + 前端页面 + /live HTTP-FLV 代理）
      - "3334:3334"   # RTMP 推流 (OBS)
    volumes:
      - zviewer-data:/app/config
    restart: unless-stopped

volumes:
  zviewer-data:

docker build -t zviewer -f Dockerfile.linux-single .
docker compose -f docker-compose.linux-single.yml up -d

用户通过浏览器访问 http://localhost:3333 即可使用全部功能。OBS 推流地址 rtmp://localhost:3334/live。

/app/config 目录挂载 volume，包含：

每次 push 到 main 分支或打 tag（v*）时，自动完成：

1. 构建 Linux 单文件版 → 上传 artifact + 推送到 Docker Hub（zerowyc0721/zviewer）。
2. 构建 Windows 单文件版 → 上传 artifact。
3. 打 tag 时自动创建 GitHub Release，包含两个平台的压缩包。

管理员可在管理后台通过开关控制是否接收预发布版本更新。

项目使用 npm workspaces，根目录统一安装依赖。

# 安装全部依赖
npm install

# 同时启动前后端开发服务
npm run dev

# 或分别启动
npm run dev:backend
npm run dev:frontend

开发端口：

• 前端：http://localhost:5174（Vite 开发服务器，HMR 热更新）
• 后端：http://localhost:3333（Express + TypeScript，热重载）

前端开发时通过 Vite 代理将 /api、/socket.io、/live 请求转发到后端，无需额外配置 VITE_API_URL。

ZViewer/
├── backend/          # Express 后端（TypeScript + TypeORM + sql.js）
│   └── src/
│       ├── routes/          # REST API 路由
│       ├── services/        # 业务逻辑（B站解析、代理、更新等）
│       ├── modules/         # 模块化架构（房间、观众、同步等）
│       ├── entities/        # TypeORM 实体
│       └── middleware/      # 鉴权中间件
├── frontend/         # React 前端（Vite + Tailwind CSS）
│   └── src/
│       ├── pages/           # 页面组件
│       ├── components/      # 通用 UI 组件
│       ├── modules/         # 功能模块
│       └── store/           # Zustand 状态管理
├── docker/           # Docker 入口脚本
├── packaging/        # 启动脚本模板
├── dist/             # 构建产物
└── build-all.js      # 单文件编译脚本

系统采用四层权限模型：

新用户注册后角色为 guest，状态为 pending。仅 root 可在管理后台审核通过用户，通过后升级为 user。

解析 BV 号或视频链接，支持清晰度切换、大会员专享内容。可在管理后台配置 Bilibili 登录凭证以获取大会员清晰度。支持 ZViewerCLI 本地代理以使用本地 Cookie 获取高画质地址。

• MP4 直链：直接输入可访问的 MP4 视频地址播放。
• WebDAV / FTP / OpenList：在挂载点管理中保存连接配置，浏览目录并播放视频文件。

ZViewerCLI 是一个可选的本地代理客户端，用于解决浏览器端无法直接使用用户 Bilibili Cookie 与高画质地址的问题：

• 使用用户本地 Cookie 解析 Bilibili 视频，获取大会员等高画质地址。
• 在本地代理视频流请求，注入正确的 Referer/Origin/User-Agent，绕过 CDN 防盗链与 CORS 限制。
• 通过 WebSocket 向房间注册，前端自动检测并使用本地代理。

localhost 与内网 IP 使用自签证书，浏览器会提示"证书颁发机构不受信任"。解决方法：

• 将 config/ssl/cert.pem 导入客户端"受信任的根证书颁发机构"；或
• 使用域名或公网 IP 并通过 Let's Encrypt 申请可信证书。

确认反向代理（Nginx 等）已正确配置 WebSocket 升级头：

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

WebRTC 的 getUserMedia 要求 HTTPS 访问。生产环境请配置 SSL 证书。若双方处于严格 NAT 之后，可能需要部署 TURN 服务器（如 coturn）。

后端使用 TypeORM + sql.js（wasm 版 SQLite）持久化，纯 JS 实现、无原生模块——单文件版可在任意平台直接运行，无需编译。数据库文件为标准 SQLite 格式（config/dev.sqlite），可用常规 SQLite 工具查看。

• 检查后端是否正确携带 Referer 等请求头。
• 封面与视频地址通过后端代理获取，避免 CORS 与防盗链问题。
• 大会员专享内容需在后台配置有效的 Bilibili 登录凭证，或使用 ZViewerCLI 本地代理。

系统支持从 GitHub Releases 自动检测并应用更新，也支持手动上传压缩包更新。管理员可在管理后台控制是否接收预发布版（main 分支自动构建）的更新。