视频通话教程

手机与电脑：双方互译检测

版本 20261002-checks1。每个客户端顶部都有「互译检测」，显示本机与同房间对方的 9 项灯号。绿灯是对应条件已验证；红灯是条件缺失或失败；灰灯是尚未实测。音色接口可用、视频可见均不等于已经能够语音互译。

1. 双方刷新页面并进入同一房间，点击顶部「互译检测」。
2. 点击「检测翻译服务」，向现有 DeepSeek 服务发送两个不同语言方向的短测试句。测试消耗少量 API 额度，不发到聊天室。
3. 各自按「我说」选择说话语言，点击「开启字幕并说一句」。只有收到实际语音识别文字，识别才变绿。
4. 双方轮流说话，对方收到新的字幕后，字幕接收变绿。历史记录不作为本次接收证据。
5. 声音设置中选择「我听」语言和音色，开启译文朗读，再试听。播放结束后 30 秒内点击「我已听到试听声音」；未听到请点击「没有听到声音」。播放回调本身不会把听音确认变绿。

检测包括：安全网页、房间服务器应答、麦克风音轨、音视频连接、语音识别、真实翻译请求、对方实时字幕、目标语言音色、朗读开启与听音确认。麦克风音轨可用不代表采到了有效人声；音视频连接成功不代表已经看到画面，后续识别与听音仍须实测。

手机「暂无匹配声音」会保持红灯。先自动匹配；仍为零时安装对应语言语音包或更换支持系统朗读的浏览器。网页无法凭空提供手机未安装的音色。识别灰灯时确认语言并说话，持续无结果检查浏览器识别服务网络；可先用文字 / 输入法翻译。

检测记录两分钟过期，换房间、语言、声音设置、开关识别或朗读、进入后台、断线后需要重新验证。对方检测超过 10 秒未更新会变为待检测，离开房间后立即清除对方灯号。共享内容仅为本房间灯号，不包含识别内容、密钥或设备详情。双方近期全部通过，才显示双方近期实测通过；不承诺未来网络稳定或固定三秒出声。

手机点开启后仍显示关闭：检查朗读能力（2026-09-16）

截图里的「麦克风已启动但尚未收到识别文字」是语音识别状态，与译文朗读是两个环节。电脑能朗读，不能证明手机浏览器也具备声音接口或英语音色。

本次复现并修正了一个提示错误：当浏览器没有 SpeechSynthesis 朗读能力时，点击开启曾错误显示为「仅显示字幕，朗读已关闭」。现在会显示「朗读不可用 · 查看原因」，并解释当前浏览器未提供系统朗读能力；不会显示假成功。这是代码分支复现，尚不能单凭截图确定真机根因。

1. 手机刷新页面，打开快捷栏齿轮（或「更多 → 字幕与声音」）。
2. 点击「检查本机朗读」。若显示浏览器未提供能力，需要换用提供系统朗读能力的浏览器；单改网页开关无法补齐浏览器接口。
3. 若接口可用，但当前英语匹配0个音色，先点「自动匹配 / 刷新声音」再检查；仍为0时检查系统语音包或换浏览器。
4. 若有匹配音色，点击「试听所选声音」，检查媒体音量、静音、蓝牙输出；再打开自动朗读，接收对方的新字幕。可用「重播」检查上一句。

本次29项客户端回归通过（含不支持接口时点击开启的失败复现与修复）。新增检查只是读取当前设备接口和音色数量，不上传设备信息。版本 20260916-voicecheck2；旧文件备份 /www/backup/webrtc-video/20260916-voicecheck。手机的确切原因仍需要根据检查结果与浏览器名称判断。

手机新版：字幕、声音一键切换

版本 20260915-comfort3。电脑与手机先刷新网页，再加入房间；旧页面可退出后重新打开。

1. 手机顶部分为「通话 / 聊天 / 房间大厅」。大厅始终保留空房，切换页面不会退出通话；离开仍使用红色「离开房间」。
2. 通话底部常驻两个独立开关：「开启我的字幕」识别你说的话；「开启译文朗读」朗读对方的新字幕。接收对方字幕无需开启自己的识别。开启朗读会先播放一句准备提示，方便确认手机真的能出声。
3. 「我说」选择自己的说话语言；「我听」选择希望听到的译文语言。改变「我听」不改变对方设置；收到的语言不同时，接收端再翻译，并同步更新浮动字幕。聊天室保留对方原先发送的内容。
4. 听漏了可点击「重播」。即使自动朗读关闭，也能重播当前房间收到的最后一句。离开房间会关闭朗读并清空待播内容，不会带到另一个房间。
5. 点击快捷栏齿轮进入「字幕与声音」。可选自动匹配、女声、男声、具体系统音色、语速、音量；展开更多选项可调音调、优先最新/按顺序播放，以及双语/只看译文/隐藏浮动字幕、字号、停留8/15/30秒。
6. 截图、文件、举手、字幕历史等收进底部「更多」。输入聊天文字时暂时收起底部控件，避免挤占输入空间。手机视频按完整画面显示，自己的识别字幕与收到的字幕分开摆放。

朗读有时没声音：本次修复

• 声音库可能稍后才加载。现在主动刷新并等待；不能把暂时没有声音视为字幕处理完成。
• 部分手机音色只有语言名称，没有男女声标记。「自动匹配」允许这些真实声音；指定男女声则继续严格筛选。没有可用声音时会提示，不用其他语言或变调假装成功。
• 每次播放前恢复暂停的语音引擎；开启时在点击动作内播放准备提示。5秒未收到启动事件时提示重播/换声音。浏览器拒绝、语音包故障和翻译失败都有可见反馈，重播可重试。
• 停止、切换设置、退出房间后，忽略旧播放的迟到回调，避免旧回调影响新声音和麦克风状态。长文本分段播放；优先最新减少积压，顺序模式最多等待3条。
• 切到后台暂停当前朗读，回来后接收新字幕；最后一句仍可手动重播。朗读时暂时暂停本机拾音，结束恢复，避免扬声器回录。想开始识别自己的话时，点「我的字幕」可先中止当前朗读。

如果仍没有声音，先看底部状态，点击「重播」；再进入齿轮 →「自动匹配 / 刷新声音」→「试听所选声音」。检查手机媒体音量、静音状态、蓝牙音频输出与语音包。没有对应语言声音时，需要系统安装该语言语音包或换浏览器。本版使用设备语音合成，未接入云端语音服务，不能保证所有手机都有同样音色。

实际验收范围

28项字幕/朗读/媒体客户端测试通过；本地隔离服务14项聊天、图片、管理等回归检查通过，总计42项。正式服务器28项客户端测试也通过；首页、样式及4个修改脚本与本地SHA-256一致。320像素小屏、390像素手机布局、844×390横屏、桌面布局、聊天输入及大厅切换均检查。测试页未发现浏览器控制台错误。

公网测试：法语文字先翻成英文发送，接收端选择中文后再次翻译、开始朗读并完成，浮动字幕同步为中文。一次首次测试发送方翻译804ms，接收端收到字幕到起声约1.0秒；不含语音识别。另测手动重播、男声试听、声音不存在提示及自动匹配恢复。手机截图为桌面浏览器模拟屏幕，测试采用无摄像头/麦克风模式；不代表已经验证真实手机扬声器、蓝牙或持续语音识别，真机仍需刷新复测。

发布前旧文件备份：/www/backup/webrtc-video/20260915-comfort。只更新视频项目前端与相关测试，没有重启其他服务；原有房间和私有密钥保持原存储方式。验收后测试连接已退出。

浏览器依据：暂停状态需要 resume 恢复；声音库变化事件。

译文朗读基础与首次上线记录

当前手机界面及朗读改进请以手机新版说明为准，以下保留首次上线记录。

1. 电脑和手机先刷新页面，加入房间，点击底部「🔊 译文朗读」。
2. 选择朗读目标语言、女声/男声，再选择设备提供的具体音色；可调语速和音量。先点击「试听所选声音」，再勾选「自动朗读对方的新字幕」。每次重新打开页面默认关闭，避免突然出声。
3. 只朗读对方新发来的字幕，历史字幕不自动播放。对方的译文语言不同于你选择的语言时，会把原文再次交给 DeepSeek 翻译成你指定的语言，不影响对方设置。
4. 建议选择「低延迟 · 本机音色优先」。在线音色只在设备实际提供时可选，不代表固定音质档位；具体音质由操作系统声音决定。语音库没有对应语言或指定男女声时会明确提示，可选「全部声音」试听，或安装系统语音包。不会用变调冒充男女声。
5. 朗读时暂时关闭本机麦克风音轨、暂停字幕识别，防止扬声器声音回录成字幕；结束后恢复原有静音状态。建议戴耳机。需要随时说话时，点击「停止并关闭朗读」。退出房间立即清空朗读队列。

3 秒目标与实测

完整耗时包括说话断句、浏览器语音识别、DeepSeek 翻译、传输和语音合成。以约 3 秒起声为优化目标，不能保证每次达成。界面单独显示「收到字幕→起声」，不包含发送方识别与翻译耗时。为减少积压，最多等待两条，过期内容跳过。

2026-09-15 公网短句测试：DeepSeek 英译中请求约 780 毫秒；接收端收到译文后约 0.1 秒触发朗读开始，并收到完成事件。此测试输入为文字，不是说话到声音的端到端测量。当前测试电脑的中文女声 Huihui、男声 Kangkang 均完成试听；手机截图为 390 像素响应式布局验收，实际手机音色和扬声器效果仍需真机复测。

手机间歇杂音的已知原因与检测

确认旧版把对方的每条字幕当聊天消息，播放一次 880 Hz 提示音，导致字幕持续出现时反复响。新版取消字幕提示音。麦克风请求显式启用回声消除、降噪和自动增益；实际支持情况由浏览器决定。

若还有爆音、断续或回声，在朗读设置展开「杂音与网络检测」，通话中点击检测，可查看约 2 秒音频丢包变化、抖动、往返延迟和麦克风处理状态。检测只读统计，不录音、不上传声音。统计不能证明所有杂音来源；网络较差时先关闭代理比较，回声时降低扬声器音量、两台设备拉开距离并戴耳机。

稳定版本已先备份到 GitHub 标签 backup/stable-20260915-before-voice（提交 06eebed）。服务器私有归档 /www/backup/webrtc-video/stable-06eebed/project-and-config.tgz 已验证可读取；含环境配置，不能公开上传。此次前端修改备份在 /www/backup/webrtc-video/20260915-voice，版本 20260915-voice1。17 项字幕、播放与朗读测试通过。

房间大厅：空房保留、管理员删除（最新规则）

所有已创建房间显示在首页大厅，包含房间号、密码标记、实时人数和空闲/通话中/满员状态。每房最多 2 人；在房间内也可以查看大厅，切换房间前先退出当前房间。

1. 退出、断网、关闭页面只清除在线成员，空房显示 0/2 并保留，可以再次加入。
2. 房间号和房间密码持久保存，视频服务重启后仍在；在线成员不写入文件，因此重启不会出现旧成员残留。
3. 点击大厅「房间管理」，使用管理员身份登录。登录后大厅各房间出现「删除房间」按钮，也可在管理面板输入房间号删除。
4. 普通用户可以创建和加入房间，不能删除房间。服务器会校验管理员令牌、有效期及其所属连接，不能仅凭前端显示绕过权限。
5. 管理员删除需确认，会移出成员并删除该房间与聊天记录。再次重启不会恢复已删除房间。

此规则替代早期版本的「空房自动删除」。升级时旧版本在线房间列表为空，因此没有可迁移的活动房间；已创建默认「视频通话」房间并退出，现以 0/2 保留供使用。

验证：两人容量、断网清人、空房保留、密码保留、应用重启后恢复、非管理员拒绝、管理员删除后重启不恢复均通过；14 项应用冒烟测试通过。公网大厅已显示空闲房间和管理员入口。

当前所有者管理方式

当前管理员访问白名单仅允许服务器本机（127.0.0.1 / ::1），所以电脑直接点击网页管理登录会被拒绝。所有者可使用已有宝塔 root 终端管理；下列命令内部读取服务器管理员配置，不输出密码。

cd /www/wwwroot/webrtc-video-chat
node deploy/manage-rooms.cjs list
# 确定删除时，将“房间号”替换为目标房间；包含空格时加引号
node deploy/manage-rooms.cjs delete "房间号" --confirm

删除命令会移出成员并删除对应房间和聊天记录。若需要从电脑网页管理，可明确授权管理电脑的公网 IP 加入管理员白名单，密码仍需验证。

房间文件：/var/lib/webrtc-video/rooms.json，仅保存房间定义，不保存在线成员，权限 600。备份：/www/backup/webrtc-video/20260915-lobby。版本：20260915-lobby1。管理员密码与访问 IP 限制沿用原有服务配置，不在公开教程中展示。

01 · 开始使用

1. 打开首页，在设置中填写昵称。
2. 输入房间号和可选密码，创建房间；另一位参与者选择相同房间加入。
3. 在聊天室发送文字，验证成员列表和消息同步。
4. 通过 HTTPS 或本机 localhost 访问时，允许浏览器使用摄像头和麦克风，再测试静音、摄像头、屏幕共享。
5. 字幕翻译选择 DeepSeek，密钥已经由管理员配置在服务器。按自己的说话语言选择源语言、按希望输出的语言选择目标语言，然后保存设置并开启字幕。

正式域名 HTTPS 已启用，浏览器可在安全上下文中申请媒体权限。首页、聊天室与加密信令已验证；双设备摄像头、麦克风、屏幕共享和跨网络媒体通话仍需实际测试。IP + HTTP 仅保留为基础连通性测试入口。

手机视频正常，但看不到电脑字幕（2026-09-15 修复）

已修复接收显示：旧版把对方双语字幕只放进聊天室，没有显示在手机画面上。新版收到同房间对方的字幕后，自动显示浮动字幕卡，包含说话人、原文和译文；12 秒后隐藏，完整内容继续保留在聊天室。离开房间立即清空，忽略其他房间的迟到字幕。

1. 电脑和手机都刷新网站，再加入同一个房间。
2. 电脑开启「字幕」，选择正确的说话语言和翻译目标语言。
3. 手机只需正常进房：接收电脑字幕无需打开手机「字幕」按钮，也不依赖手机浏览器的语音识别服务。
4. 手机上的「字幕」按钮负责识别手机使用者自己说的话。若提示识别未启动，仍然可以接收电脑字幕；手机自己发言可暂用「文字翻译」及输入法语音输入。国内连续语音识别尚未接入。
5. 用户实测本次黑屏在关闭代理后恢复正常。可使用已验证能通话的直连网络；网页视频连接、浏览器语音识别与文字翻译是不同链路。

本次验证：11 项字幕、文字翻译与播放恢复测试通过，14 项应用冒烟检查通过；公网真实 DeepSeek 翻译经房间转发后，在未开启语音识别的接收页面自动显示，离开房间后隐藏。下图为桌面浏览器模拟手机宽度，并未代替真实手机复测。

媒体自动播放受限时增加「点击播放画面和声音」按钮。应用版本：20260915-media1；回滚副本：/www/backup/webrtc-video/20260915-received-captions。此次只重启视频项目。

双人房间与掉线自动退出

每房最多两人。主动离开及时移除在线成员；设备检测到离线时退出，突然失联由服务器心跳检测，通常约 15 秒确认。网络恢复只连接大厅，需要本人重新加入。每 5 秒及切回页面时校验房间状态。

空房不再删除：0 人房间继续显示在大厅，只有管理员可以删除，完整规则见房间大厅。

历史断网验证：公网不回应心跳的连接约 13.6 秒被移除，两端人数从 2 同步为 1；真实手机还需结合实际网络复测。

手机能视频通话，但字幕一直等待？

视频、聊天、语音识别和文字翻译是不同的连接。视频和房间消息正常，只能证明站点与通话连接已建立；手机一直显示等待语音时，通常还没有拿到识别文字，DeepSeek 还没有收到翻译请求。

当前连续语音字幕使用浏览器 Web Speech API。Chrome 等浏览器可能把音频交给在线识别服务，手机的网络、浏览器版本、麦克风权限和源语言都可能影响结果。手机直连下识别服务可能无法访问，仅凭页面截图不能确定唯一原因。浏览器语音识别说明

1. 先刷新网站，确认源语言与说话语言一致；允许网页使用麦克风。
2. 开启字幕后，界面区分「启动识别」「麦克风已启动」「检测到语音」「收到识别结果」。18 秒无文字时提示排查，45 秒无文字时暂停；连续三次网络错误会停止重试。没有文字时不再显示空黑色字幕框。
3. 手机可点击底栏「文字翻译」，点击输入框，使用手机输入法自带的语音输入，或直接打字。输入法语音能力由手机及其服务提供，本项目不保证每个输入法都支持离线识别。
4. 点击「翻译」先预览；确认后点击「发送双语字幕到房间」。此路径不调用网页 SpeechRecognition，由本站服务器调用 DeepSeek。
5. 要在国内网络下实现更稳定的连续自动语音字幕，需要另外配置国内语音识别服务（如阿里云百炼）。DeepSeek 的 Key 用于文字翻译，不能代替语音识别 Key。当前尚未接入国内语音识别，不应把文字翻译成功视为该功能已完成。

本次验证：14 项字幕与翻译回归测试通过；390 × 844 手机宽度下的弹窗、真实 DeepSeek 译文、预览后发送和历史字幕显示通过。测试使用桌面浏览器模拟手机宽度，未替代真实手机、输入法或国内运营商网络验收。

此次仅更新视频前端与测试文件，未重启服务。回滚副本：/www/backup/webrtc-video/20260915-mobile。

DeepSeek 字幕翻译（2026-09-15 更新）

1. 刷新页面（旧页面可按 Ctrl+F5），进入设置，确认显示「DeepSeek 已配置」。
2. 选择源语言和目标语言，例如中文 → 英语。浏览器识别需要明确的说话语言，原来的「自动检测」不再用于语音识别。
3. 加入房间，点击底部「字幕」。每位发言者在自己的设备开启字幕，允许浏览器麦克风权限；先显示识别原文，再显示 DeepSeek 译文，并共享到房间聊天记录。
4. 不方便使用麦克风时，在设置下方「文字翻译」输入短句并点击翻译；结果也会发到房间。两端语言相同时仅保留原文。
5. 翻译失败时显示原因并保留原文，不再把原文伪装成译文。余额不足、密钥无效、网络超时会有不同提示。

开启字幕后，浏览器语音识别服务处理语音，DeepSeek 处理识别文字。语音识别质量仍受浏览器、网络、口音与收音影响。文字翻译及房间双语收发已实测，真实麦克风连续识别效果需要在各自设备测试。

此次修复了字幕气泡透明、识别结束未重连、临时字幕不显示、重复提交及旧译文覆盖新句的问题。翻译只处理最终识别结果，串行排队并限制积压。离开房间后不再发送尚未完成的字幕。

服务端使用 deepseek-flash 非思考模式，超时 12 秒，每条最多 1200 字。每连接每分钟最多 30 次翻译，整个视频服务每分钟最多 120 次、最多 4 个同时请求。缓存仅保留本连接最近结果一分钟。额度用于控制实时字幕的调用消耗。

管理员环境项：DEEPSEEK_API_KEY、DEEPSEEK_MODEL，保存于 /etc/webrtc-video.env，权限 600。修改后只重启 webrtc-video。密钥不写进网页、仓库或截图。

更新前备份位于 /www/backup/webrtc-video/20260915-deepseek，仅包含本视频项目此次改动文件及私有环境备份。回滚时按需恢复对应文件后重启本服务，不覆盖其他站点。

验证：原有 14 项测试通过；新增 9 项翻译与字幕回归测试在本地和服务器通过。公网中文→英文、英文→中文及双语房间消息收发通过；首次短句翻译实测约 0.9 秒，该数值不包含语音识别时间，也不代表固定延迟。

02 · 独立部署配置

1. 先检查端口和目标目录是否空闲，确认已有 Nginx 配置检查通过。
2. 拉取代码，使用官方源安装生产依赖。
3. 配置独立用户、环境变量和 systemd 服务。服务最多使用 512 MB 内存和相当于一个 CPU 核心的额度。
4. 独立 Nginx 站点把 HTTP 页面、Socket.IO 与 PeerJS 统一转发到 3100；保留 WebSocket 升级头。
5. 先检查 Nginx 配置，再平滑重载，最后验证页面、信令和聊天室。

npm install --omit=dev --package-lock=false --registry=https://registry.npmjs.org
systemctl status webrtc-video --no-pager
journalctl -u webrtc-video -n 50 --no-pager
curl -I http://127.0.0.1:3100/
nginx -t

更新或重启只针对 webrtc-video 服务；不要使用批量重启全部服务的命令。

03 · 本次问题与处理

npm 下载依赖返回 404：服务器默认 registry 指向二进制文件镜像路径，不能用来解析 cors 等 npm 包。安装命令增加 --registry=https://registry.npmjs.org，只影响本次命令。

宝塔终端操作超时：先查看截图确认命令是否已输入或执行，避免重复部署。页面文字读取不到终端内容时，用真实终端截图核对结果。

HTTP 页面反复提示 PeerJS network 错误：旧客户端在标准端口留空时会采用 PeerJS 默认 443 端口。已修复为 HTTP 明确使用 80、HTTPS 使用 443，自定义端口保持原值。

网页打开但信令断开：核对代理的 Upgrade、Connection 头，PeerJS 路径为 /peerjs/peerjs/。本项目使用单端口，不需要另开 9000。

跨网络视频无法连接：HTTPS 与信令正常不代表媒体链路一定可用。需要使用两台设备测试；严格 NAT 网络可能需要单独配置 TURN。

04 · 域名与 HTTPS（已完成）

1. DNS A 记录：video → 43.160.236.132。
2. 宝塔「网站 → 反向代理」单独添加 video.shanbo-rig.com，代理地址为 http://127.0.0.1:3100，保留 WebSocket 升级头。
3. 宝塔「SSL → 免费证书 → 申请证书」选择 Let's Encrypt、文件验证，并勾选视频域名。证书已签发且部署成功，当前证书到期日为 2026-12-14；面板自动续签开关已开启。
4. 文件验证目录为 /www/wwwroot/video.shanbo-rig.com/.well-known/acme-challenge/。这不是应用代码目录；保留该目录和宝塔验证配置以支持续签。
5. 在视频站点「设置 → SSL → 当前证书」开启强制 HTTPS。公网 HTTP 已验证返回 301 并跳转同域名 HTTPS。
6. 客户端正式配置设置域名、端口 443 和 secure: true；服务环境设置 PUBLIC_URL=https://video.shanbo-rig.com。
7. 检查配置后平滑重载 Nginx，只重启 webrtc-video。公网 HTTPS、Socket.IO WSS 聊天收发、PeerJS WSS 连接均通过验证。

nginx -t && nginx -s reload
systemctl restart webrtc-video
systemctl is-active webrtc-video
curl -I http://video.shanbo-rig.com/
curl -I https://video.shanbo-rig.com/

域名站点配置：/www/server/panel/vhost/nginx/video.shanbo-rig.com.conf。旧 webrtc-video.conf 仅保留 IP，不重复绑定正式域名。证书由宝塔管理，不要用其他配置模板覆盖现有站点。

接下来可用两台设备打开正式入口，允许各自浏览器的媒体权限，测试摄像头、麦克风与屏幕共享。严格 NAT 网络下可能仍需 TURN。

05 · 截图记录

服务器 14 项冒烟测试全部通过；公网首页、教程、PeerJS ID 接口返回 200，两个客户端的聊天消息收发及两条 WebSocket 信令检查通过。以下为实际部署截图，不包含密码或密钥。