billd-desk 自建 TURN 中继服务器保姆级教程(0 基础 / Docker 版)

2026-11-17 11826 1

billd-desk 自建 TURN 中继服务器保姆级教程(0 基础 / Docker 版)

本教程记录了一次完整的实战部署过程:在 Linux 服务器上用 Docker 部署 coturn(TURN/STUN 中继服务器),并接入 billd-desk 远程桌面客户端。全程踩过的坑都会标注出来,照着做即可。

一、背景知识:为什么需要中继服务器?

billd-desk 是一款基于 WebRTC 的开源远程桌面软件。WebRTC 建立 P2P 连接时有三种方式:

连接方式 说明 成功率
直连(host) 双方在同一局域网 局域网内可用
打洞(P2P) 双方防火墙/NAT 允许 约 70%~80%
中继(TURN relay) 流量经中继服务器转发 接近 100%

打洞失败时(比如双方都处于严格 NAT 网络下),必须有 TURN 中继服务器兜底,否则部分用户会连不上。自建中继的意义:官方公共中继不稳定、有带宽限制,自己的服务器自己说了算。

我们的目标是:用 Docker 在自己的服务器上跑一个 coturn,让 billd-desk 客户端填上它,实现任意网络环境都能远控。

二、准备工作

你需要:

  1. 一台有公网 IP 的服务器(Linux,建议 2 核 2G 以上;中继转发视频流,带宽越大越好)
  2. 一个域名(可选,但强烈建议。文中以 v46.565520.xyz 为例,请替换成你自己的)
  3. 服务器已安装 Docker 和 Docker Compose(没有的话先装:curl -fsSL https://get.docker.com | sh)
  4. SSH 能登录服务器

2.1 域名解析(可选但建议)

在域名服务商处添加一条 A 记录:

记录类型 主机记录 记录值
A @(或任意子域) 你的服务器公网 IPv4

如果服务器支持 IPv6,再加一条 AAAA 记录指向 IPv6 地址(后文会讲 IPv6 双栈)。

💡 不想配域名?直接用服务器公网 IP 也完全可以,只是客户端里要填 IP。

三、部署 coturn(Docker 方式)

3.1 建立目录和配置文件

SSH 登录服务器,创建工作目录:

mkdir -p /opt/billd-turn && cd /opt/billd-turn

3.2 编写 TURN 配置文件

创建 turnserver.conf:

vi turnserver.conf

完整内容如下(可直接复制,替换 realm 为你的域名):

listening-port=3478
listening-ip=0.0.0.0
listening-ip=::
relay-ip=0.0.0.0
relay-ip=::
realm=123.你的域名.xyz
lt-cred-mech
user=billd:Abc123456x
min-port=49152
max-port=65535
fingerprint
no-cli

逐行解释(了解即可,不用改):

配置项 含义
listening-port=3478 TURN 服务主端口(STUN/TURN 标准端口)
listening-ip=0.0.0.0 监听所有 IPv4 地址
listening-ip=:: 监听所有 IPv6 地址(双栈,没 IPv6 的服务器可删这行)
relay-ip=0.0.0.0 / relay-ip=:: 中继转发流量绑定的地址,同样双栈
realm 认证域,填你的域名
lt-cred-mech 启用长效凭证认证机制
user=billd:Abc123456x 账号:密码,务必改成自己的强密码
min-port / max-port 中继媒体转发使用的 UDP 端口范围
fingerprint 启用指纹校验
no-cli 关闭管理 CLI(容器内没必要开)

⚠️ 大坑警告:coturn 配置不支持行内注释!
listening-ip=:: # 监听 IPv6 这种写法是错的,coturn 会把 :: # 监听 IPv6 整体当作主机名去解析,直接报错 error resolving ... Name or service not known,该行配置失效。
注释只能单独占一行,且以 # 开头。这是本次部署实际踩过的坑。

3.3 编写 docker-compose.yml

创建 docker-compose.yml:

services:
  coturn:
    image: coturn/coturn:latest
    container_name: billd-turn
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./turnserver.conf:/etc/coturn/turnserver.conf:ro

关键点说明:

  • network_mode: host:容器直接使用宿主机网络栈。这是最省心的方案——不用映射几万个 UDP 端口,IPv6 双栈也天然支持。
  • restart: unless-stopped:开机自启、异常自动拉起。
  • 配置文件以只读方式挂载进容器。

3.4 启动

docker compose up -d

3.5 验证启动是否正常

docker logs billd-turn

正常的话应该看到类似日志(重点检查加粗部分):

INFO Listener address to use: 0.0.0.0
INFO Listener address to use: ::          ← 双栈才有这行
INFO Relay address to use: 0.0.0.0
INFO Relay address to use: ::             ← 双栈才有这行
INFO Default realm: 123.你的域名.xyz
INFO relay 0.0.0.0 initialization done
INFO Relay ports initialization done
INFO Total relay threads: 4

再确认端口监听:

ss -tlnp | grep 3478   # TCP,应看到 0.0.0.0:3478 和 [::]:3478
ss -ulnp | grep 3478   # UDP,同上

💡 日志里的 WARNING cannot find certificate file: turn_server_cert.pem 可以忽略——那是 TLS/DTLS 的证书没配。纯 UDP/TCP 的 TURN 不需要证书,不影响使用。

四、放行防火墙/安全组(最容易失败的一步)

TURN 服务器需要放行三类端口:

协议/端口 用途 是否必须
UDP 3478 TURN 主端口 ✅ 必须
TCP 3478 TURN 备用通道 建议
UDP 49152-65535 中继媒体转发 ✅ 必须

4.1 云服务器安全组

到云服务商控制台(阿里云/腾讯云等)→ 安全组 → 添加入站规则:

  • TCP 3478
  • UDP 3478
  • UDP 49152-65535(范围规则直接写 49152-65535)

💡 IPv6 与 IPv4 的安全组规则是两套独立的!如果你配置了 IPv6 双栈,上面的规则要在 IPv6 规则里再加一遍,否则 IPv6 链路不通(这也是本次实战踩过的坑:ss 显示已监听 [::]:3478 但外网 tcpping 不通,根因就是 IPv6 安全组没放行)。

4.2 系统防火墙(如启用)

# firewalld
firewall-cmd --permanent --add-port=3478/{tcp,udp}
firewall-cmd --permanent --add-port=49152-65535/udp
firewall-cmd --reload

# ufw
ufw allow 3478/tcp
ufw allow 3478/udp
ufw allow 49152:65535/udp

4.3 可选:缩小中继端口范围

1.6 万个端口的安全组规则某些平台不支持。此时可把配置改为:

min-port=50000
max-port=51000

然后 docker compose restart,安全组只需放行 UDP 50000-51000(1000 个并发中继会话,个人使用绰绰有余)。

五、连通性测试

5.1 服务器本机测试

tcpping -6 你的域名 3478    # IPv6 TCP
tcpping -4 你的域名 3478    # IPv4 TCP

5.2 浏览器测试(最权威)

打开 WebRTC 官方测试页:
https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/

填写:

字段 值
URI turn:v46.565520.xyz:3478
Username billd
Password Abc123456x

点击 Collect candidates,在结果列表中查找类型为 relay 的行:

组件 | 类型 | 地址 ...
relay | 0 | 你的服务器公网IP:xxxxx | udp | ...

出现 relay 候选 = 中继服务器完全可用。🎉

六、接入 billd-desk 客户端

打开 billd-desk 客户端 → 设置 → 网络,在「中继服务器」部分填写:

客户端字段 填写内容
urls turn:123.你的域名.xyz:3478
username billd
credential Abc123456x
强制使用中继服务器 测试阶段先开启,确认可用后关闭(关闭后走 P2P 优先、中继兜底)

注意事项:

  1. 两端都要填:控制端和被控端填写相同的中继配置,改完刷新页面。
  2. 「Wss / Api 自定义」保持默认关闭——你只是自建中继,前端后端仍用官方的。
  3. 想验证是否真的走了中继:开启「强制使用中继」后连接一次远控,在服务器上 iftop 或 nethogs 观察流量,转发流量明显说明中继在干活。

七、故障排查速查表

现象 可能原因 解决
日志报 error resolving ... Name or service not known 配置写了行内注释 注释单独成行
日志报 Cannot add a listener address :: 行格式错误或宿主机无 IPv6 核对配置;无 IPv6 就删掉 :: 相关行
ss 没有 [::]:3478 IPv6 监听没生效 检查配置,看启动日志有无 ERROR
监听正常但外网不通 云安全组没放行 检查 IPv4 和 IPv6 两套规则
trickle-ice 测试不出 relay 候选 账号密码错 / 端口没通 / UDP 转发段没放行 逐项核对
客户端仍部分场景连不上 两端没都填中继配置 两端都配置并刷新

八、总结清单(Checklist)

  • ☐ 域名解析到服务器(A 记录,可选 AAAA)
  • ☐ turnserver.conf 无行内注释,账号密码已改强密码
  • ☐ docker compose up -d 启动,日志无 ERROR
  • ☐ ss 确认 0.0.0.0 和 [::] 均监听 3478
  • ☐ 安全组放行 TCP 3478 / UDP 3478 / UDP 49152-65535(IPv4 + IPv6 两套)
  • ☐ trickle-ice 测试出现 relay 候选
  • ☐ billd-desk 两端填入中继配置并刷新
  • ☐ 远控连接成功

部署环境参考:Docker + coturn/coturn:latest(Coturn 4.x),宿主机 Linux(host 网络模式),billd-desk 客户端(WebRTC)。配置原则:不搞运行时自动探测,所有参数显式硬编码,工业现场级稳定。

PREV
Charles5.2-中文汉化版