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 客户端填上它,实现任意网络环境都能远控。
二、准备工作
你需要:
- 一台有公网 IP 的服务器(Linux,建议 2 核 2G 以上;中继转发视频流,带宽越大越好)
- 一个域名(可选,但强烈建议。文中以
v46.565520.xyz为例,请替换成你自己的) - 服务器已安装 Docker 和 Docker Compose(没有的话先装:
curl -fsSL https://get.docker.com | sh) - 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 优先、中继兜底) |
注意事项:
- 两端都要填:控制端和被控端填写相同的中继配置,改完刷新页面。
- 「Wss / Api 自定义」保持默认关闭——你只是自建中继,前端后端仍用官方的。
- 想验证是否真的走了中继:开启「强制使用中继」后连接一次远控,在服务器上
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)。配置原则:不搞运行时自动探测,所有参数显式硬编码,工业现场级稳定。