音视频服务部署 | 泡泡 IM 开发文档

本教程用于首次部署一对一语音、视频通话。先按选择安装方式完成 IM 安装，并让自己的域名可以通过 HTTPS 打开管理后台，再按本文配置通话服务。
示例采用 Ubuntu 24.04 / 26.04，与 IM 同一台服务器、同一个域名。普通、宝塔和 Docker 安装均可参考；下面的通话进程和中继服务运行在 Linux 宿主机上。已有通话服务的环境先保留原配置，不直接覆盖。
需要准备以下信息。example.com 和两个示例 IP 均须换成自己的值：
域名的 A 记录应直连服务器公网 IP，通话地址不经过网站 CDN。本文按 IPv4 配置；没有同时配置 IPv6 时，不保留指向其他服务器的 AAAA 记录。云服务器通常填写公网 IP 与私网 IP；公网 IP 直接绑定在网卡上的服务器，两项 IP 填同一个公网地址。
登录服务器后进入 root 会话，在同一终端中依次执行本文命令：
最后一行应正常结束。宝塔或手动上传的证书，请将最后两个变量改成站点实际使用的完整证书链和私钥路径。每个代码块执行成功后再进入下一步；重新登录终端时，需要重新填写这些变量。
云控制台的安全组 / 防火墙，以及服务器自身的防火墙，都要放行。 以下是入站规则；面向公网用户的通话端口需允许用户所在网络访问，不能只允许服务器自己的 IP。
只开放 3478，遗漏 UDP 中继范围，可能出现能呼叫、接听后没有声音或画面的情况。本文的 49160–49260 与后面的中继配置一致；扩容时可调整范围，但必须同时修改服务配置与两层防火墙。出站规则应允许中继向客户端公网地址发送 UDP；通常可保留服务器默认的允许出站策略。
如果服务器已启用 UFW，执行以下命令。SSH 使用其他端口时先替换 22，保留已有 SSH 放行规则：
UFW 显示 inactive 时，上述规则尚未生效，但也没有由 UFW 拦截流量；仍需检查云安全组、宝塔防火墙或其他已启用的防火墙。本教程不要求切换现有防火墙管理方式。
不对公网开放 9193：它只监听 127.0.0.1，由 Nginx 转发。数据库 3306、IM 内部服务 8787 / 6060 / 2060 / 6070 和 Docker 本机入口 8080 也不需要为通话额外开放。服务器经过自建 NAT 或端口映射时，上述公网端口须映射到同一台服务器，UDP 中继范围保留原端口号。
通话连接服务需要 Node.js 22 或以上。以下安装独立运行环境，不依赖宝塔的 Node 项目管理器：
校验应显示 OK，最后输出 v22.23.4。下载来源与版本可在 Node.js 官方发布目录核对。
官方下载较慢时，可在自己的电脑下载同版本、同架构的压缩包与校验文件，上传到服务器后再执行校验和解压。
从已安装的服务端源码中复制配套通话服务文件。以下命令在 tools/ 下定位服务目录，检查文件齐全后复制到 /opt/popoim-rtc/：
文件直接放在该目录内，不再套一层子目录，也不放进网站的 public/。若文件检查失败，先核对 CALL_APP_DIR 是否指向当前交付源码。然后安装锁定依赖：
以下命令只在配置文件不存在时生成一次随机密钥。连接服务、中继服务和后台使用同一份密钥，后续重复部署时保留该文件。
预期输出包含 active 和 {"status":"ok"}。systemd 显示 active 时 Node 可能仍在启动，健康检查会短暂重试，等待端口开始监听。服务由 systemd 分配独立的临时运行账号。持续失败时先查看 journalctl -u popoim-rtc -n 50 --no-pager，确认文件齐全、依赖安装成功及 Node 路径正确。
编辑当前 IM 域名监听 443 的 server 块，加入以下配置，保留原来的 /ws、网站路由与证书配置。同名路由已经存在时替换原配置，不重复添加。
普通安装通常修改 /etc/nginx/sites-available/popoim。Docker 安装修改宿主机的 HTTPS Nginx；宝塔在对应网站的「配置文件」中修改，并使用宝塔管理的 Nginx。此处上游为 127.0.0.1:9193，不是 Docker 的 app 容器地址。
应返回 {"status":"ok"}。出现证书错误时修正域名或证书链，不通过跳过证书校验来继续部署；返回 404 通常是路由加在了其他站点，502 则先检查通话连接服务。这个检查仅说明连接入口可用，中继和实际通话还要继续检查。
下面使用同一份服务密钥，并将公网地址映射到本机网卡地址。中继端口范围必须与第 2 步完全一致。
这里保留了公网中继的访问限制；本文面向公网部署，不把中继开放成访问服务器内网的代理。中继配置项的含义可查阅 coturn 官方配置示例。
中继需要读取有效证书。以下脚本将当前站点证书复制到专用目录；只有证书内容变化时才更新并重启中继。
确认中继为 active，3478 同时有 TCP、UDP 监听，5349 有 TCP 监听，9193 只监听本机。UDP 中继范围在实际通话分配后才使用，空闲时不会显示全部端口监听。
如果证书由 Certbot 自动续期，将同一脚本接入其成功续期钩子：
如果使用宝塔证书，在宝塔「计划任务」添加每天执行一次的 Shell 任务，脚本内容为 /usr/local/sbin/popoim-call-cert，并检查首次执行日志。脚本使用前面填写的站点实际证书路径，证书未变化时不会重启服务。续期方式见 Certbot 官方说明。手动更新证书后也执行一次该脚本。
打开「系统设置 → 音视频通话」，按自己的域名填写：
配图是已部署环境，示例中的域名要换成自己的。需要复制服务密钥时，在自己的服务器终端执行：
只将输出粘贴到后台「服务密钥」，不加 RTC_SECRET= 前缀，不将密钥放入客户端或公开截图。保存后，再到「系统设置 → 功能开关」分别开启语音通话、视频通话。接入自有 App 时，还需按对应 SDK 指引接好配套媒体模块、设备权限和通话界面；后台开关不会替代客户端接入。
先确认以下结果，再用客户端检查声音和画面：
用两个不同账号登录与服务端配套、已接入通话能力的客户端，一台连接 Wi-Fi，另一台使用移动网络，允许麦克风与摄像头，然后依次检查：
同一 Wi-Fi 下能通话，不能替代跨网络检查；健康接口正常也不能证明 UDP 媒体链路可用。测试时通过客户端连接统计确认选中的 ICE 候选类型为 relay，并确认双方持续收到音视频数据，避免直连成功掩盖中继配置错误。依次验证 UDP、TCP 与 TLS 中继，才能覆盖后台填写的三种地址。
以下日志用于排查服务启动、认证与连接错误。coturn 默认日志级别未必逐会话输出分配记录，不能把“没有分配日志”等同于中继失败，也不能仅凭服务 active 或 TLS 握手成功认定媒体可用：
如果当前两台设备始终直连，尚未证明中继链路可用；需在受控测试网络中验证中继后再认定公网部署完成。
服务密钥变更时同步更新三处并重启 popoim-rtc、coturn；这会影响现有通话，应安排维护窗口。日常后台操作见后台配置，接口与客户端接入见音视频通话。