AI Voice Platform 文档

外观

公网 coturn 部署 ​

本文用于在 Debian 12 公网主机 aliyun 上部署 coturn。coturn 不部署在运行 FreeSWITCH 的 debian12-show 主机；浏览器到 3478/TCP+UDP 和 relay 端口的流量直接进出 aliyun，不经过 FRP。跨组件的 ICE candidate 选择、FreeSWITCH/FRP 配置和无声故障排查见 5G 软电话 WebRTC ICE/TURN 指南。

当前示例使用公网 IP 123.57.205.60、私网 IP 172.21.38.245、realm softphone.ai-voice-platform 和 relay 范围 31000–31040/UDP。复制到其他环境前必须全部按 现场替换。本文继续使用 TURN REST shared secret 和短期凭据，不启用 TLS/TURNS。

1. 部署前检查 ​

先确认以下端口不会和主机上其他服务冲突：

  • 3478/TCP+UDP：STUN、TURN/UDP 和 TURN/TCP；
  • 31000–31040/UDP：coturn relay；
  • FreeSWITCH RTP 使用 30000–30199/UDP，不得与 coturn relay 范围重叠。

在阿里云安全组入方向放行 3478/TCP、3478/UDP 和 31000–31040/UDP。来源地址应按现场 安全策略限制；若客户端来自移动网络且地址不固定，需要允许相应公网来源。不要为 TURN relay 配置 FRP 转发。

2. 安装和配置 ​

在仓库根目录把样例复制到公网主机，然后登录 aliyun：

bash
scp deploy/coturn/turnserver.conf.example aliyun:/tmp/turnserver.conf.example
ssh aliyun

以下命令均在 aliyun 上执行。先安装 Debian 12 的 coturn 包并备份已有配置：

bash
sudo apt-get update
sudo apt-get install -y coturn

STAMP=$(date +%Y%m%d-%H%M%S)
if sudo test -f /etc/turnserver.conf; then
  sudo cp -a /etc/turnserver.conf "/etc/turnserver.conf.bak.$STAMP"
fi
sudo install -d -o turnserver -g turnserver -m 0750 /var/log/coturn
sudo install -o root -g turnserver -m 0640 \
  /tmp/turnserver.conf.example /etc/turnserver.conf
rm -f /tmp/turnserver.conf.example

Debian 包默认以 turnserver 账号运行。因此 /etc/turnserver.conf 使用 root:turnserver 0640，只允许 root 和 coturn 进程读取 shared secret。可用以下命令核对实际 服务账号和权限：

bash
systemctl show coturn -p User -p Group
sudo stat -c '%U:%G %a %n' /etc/turnserver.conf

使用 sudoedit /etc/turnserver.conf 完成以下替换，不要把真实 secret 写入仓库、脚本、命令行 参数或工单：

  • 将 external-ip=123.57.205.60/172.21.38.245 的两侧分别替换为 aliyun 的公网 IP 和 主机网卡实际绑定的私网 IP；
  • 按现场修改 realm；
  • 按容量规划修改 min-port / max-port，并同步修改安全组和主机防火墙；
  • 从密码管理器或密钥系统取得高强度随机值，替换 REPLACE_WITH_SERVER_PRIVATE_SHARED_SECRET，且不要在终端打印该值。

保存后确认占位符已消失。该检查只返回成功或失败，不会输出 secret：

bash
if sudo grep -q 'REPLACE_WITH_SERVER_PRIVATE_SHARED_SECRET' /etc/turnserver.conf; then
  echo 'ERROR: static-auth-secret 仍是占位符' >&2
  exit 1
fi

如果主机启用了 UFW，执行：

bash
sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 31000:31040/udp
sudo ufw status

如果使用 nftables 或其他主机防火墙，应添加等价规则。主机防火墙放行不能替代阿里云安全组 规则，两处必须一致。

Debian 的 /etc/default/coturn 若包含 TURNSERVER_ENABLED 开关，使用 sudoedit /etc/default/coturn 将其设为 TURNSERVER_ENABLED=1。随后启用并启动服务：

bash
sudo systemctl enable --now coturn
sudo systemctl status coturn --no-pager
sudo ss -lntup | grep ':3478'
sudo journalctl -u coturn -n 100 --no-pager
sudo tail -n 100 /var/log/coturn/turnserver.log

状态必须为 active (running)，且 3478 同时存在 TCP 和 UDP 监听。启动失败时先检查 journalctl、IP 映射、配置文件权限和日志目录权限。

3. 同步应用私有配置 ​

coturn 的 static-auth-secret 必须与 callflow-server 和 callout-server 使用的值完全一致。 只在服务的私有配置、环境变量或密钥系统中注入，不得发给浏览器：

  • CALLFLOW_SERVER_TURN_SHARED_SECRET；
  • CALLOUT_TURN_SHARED_SECRET。

生产私有配置还需把对应 turn.enabled 改为 true，并使 host、port、realm 与 coturn 一致。仓库中的 apps/*/config.json 和 deploy/config/*.config.json 样例继续保持 enabled: false、sharedSecret: ""，不要把生产值写回或提交到仓库。修改后按服务现有部署方式 重启两个后端，使其重新读取私有配置。

4. 验收 ​

4.1 服务端检查 ​

在 aliyun 上执行：

bash
sudo systemctl is-enabled coturn
sudo systemctl is-active coturn
sudo ss -lntup | grep ':3478'
sudo journalctl -u coturn --since '10 minutes ago' --no-pager
sudo tail -n 100 /var/log/coturn/turnserver.log

仅能连接 3478/TCP 只说明控制端口可达，不能证明鉴权、allocation 或 relay UDP 路径可用。

4.2 外网 authenticated allocation ​

在独立外网或 5G 网络的 Debian 测试机安装 coturn 工具，不要在 aliyun 本机回环测试：

bash
sudo apt-get update
sudo apt-get install -y coturn

通过已登录的 GET /api/softphone/ice-config 获取一组尚未过期的短期 username 和 credential。 不要使用或复制 static-auth-secret。用交互读取避免 credential 回显或写入 shell 历史：

bash
read -r -p 'TURN username: ' TURN_USERNAME
read -r -s -p 'TURN credential: ' TURN_CREDENTIAL
printf '\n'
TURN_HOST=123.57.205.60

turnutils_uclient -v -y -u "$TURN_USERNAME" -w "$TURN_CREDENTIAL" \
  -p 3478 "$TURN_HOST"
turnutils_uclient -v -y -t -u "$TURN_USERNAME" -w "$TURN_CREDENTIAL" \
  -p 3478 "$TURN_HOST"

unset TURN_USERNAME TURN_CREDENTIAL TURN_HOST

第一条必须通过 TURN/UDP 完成 authenticated allocation，第二条必须通过 TURN/TCP 完成 authenticated allocation。两次输出或 coturn 日志中的 relayed address 都必须是 123.57.205.60:31000–31040。参数如因 coturn 版本不同而变化，以 turnutils_uclient --help 为准，但不得省略 UDP、TCP 中任何一种。

测试期间同时在 aliyun 检查 allocation、relay socket 和日志：

bash
sudo ss -lunp | grep turnserver
sudo journalctl -u coturn --since '10 minutes ago' --no-pager
sudo tail -n 100 /var/log/coturn/turnserver.log

最终验收还应建立一通新的 5G WebRTC 呼叫，确认浏览器选中的本地 candidate 是 123.57.205.60:310xx relay、DTLS 完成、RTP 收发计数增长且双向有声。详细检查命令见 ICE/TURN 指南的验收章节。

5. 回滚 ​

若新部署或配置变更导致异常，先停止服务，避免继续建立 allocation：

bash
sudo systemctl stop coturn

如果部署前存在备份，用本次记录的时间戳恢复并重新限制权限：

bash
STAMP='REPLACE_WITH_BACKUP_TIMESTAMP'
sudo cp -a "/etc/turnserver.conf.bak.$STAMP" /etc/turnserver.conf
sudo chown root:turnserver /etc/turnserver.conf
sudo chmod 0640 /etc/turnserver.conf
sudo systemctl start coturn
sudo systemctl status coturn --no-pager

若这是首次部署且没有旧配置，保持 coturn 停止，并执行 sudo systemctl disable coturn。同时恢复两个应用后端原有的私有 TURN 配置并重启它们，确保 后端不会继续下发已停用或 shared secret 不匹配的 TURN 地址。回滚后再次确认服务状态和应用 GET /api/softphone/ice-config 的实际响应。

文档与代码在同一仓库维护，现有 Markdown 是唯一内容源。

AI Voice Platform