# WebRTC 信令服务器 · TURN 部署指南

本项目使用 **coturn** 作为 TURN/STUN 中继服务器，用于解决 WebRTC 在对称型 NAT / 防火墙等复杂网络环境下的连通性问题。

> 当客户端无法直接进行 P2P 连接时，媒体流量将通过 TURN 服务器进行中继转发。

---

## 目录

- [环境说明](#环境说明)
- [一、安装 coturn](#一安装-coturn)
- [二、配置 TURN 服务](#二配置-turn-服务)
- [三、开放防火墙端口](#三开放防火墙端口)
- [四、启动与开机自启](#四启动与开机自启)
- [五、验证连通性](#五验证连通性)
- [配置参数速查](#配置参数速查)
- [常见问题](#常见问题)

---

## 环境说明

| 项目 | 说明 |
| ---- | ---- |
| 操作系统 | Ubuntu / Debian 系（本文以 `apt` 包管理为例） |
| 软件 | `coturn`（TurnServer） |
| 默认监听端口 | `3478` (UDP/TCP) |
| 中继端口范围 | `49152` - `65535` (UDP) |

---

## 一、安装 coturn

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

安装完成后，建议先备份默认配置文件：

```bash
sudo cp /etc/turnserver.conf /etc/turnserver.conf.bak
```

---

## 二、配置 TURN 服务

使用编辑器打开配置文件：

```bash
sudo vim /etc/turnserver.conf
```

将以下内容写入（或按需修改）配置文件：

```ini
# ===== 监听设置 =====
listening-ip=0.0.0.0
listening-port=3478

# ===== 公网 IP =====
# 云服务器此处必须填写公网 IP，切勿填写内网 IP
external-ip=你的公网IP

# ===== 认证（WebRTC 必须开启，否则客户端无法连接）=====
lt-cred-mech
user=testuser:testpass
# realm 可填写任意域名，但不能留空
realm=yourdomain.com

# ===== 中继端口范围（TURN 转发媒体流量使用）=====
relay-port-range=49152-65535

# ===== 日志 =====
verbose
```

> ⚠️ **注意**
> - `external-ip` 必须填写服务器的**公网 IP**，而非内网 IP。
> - `realm` 不能为空，可填写任意域名。
> - `user` 为客户端连接凭证，请在生产环境中替换为强密码。

---

## 三、开放防火墙端口

```bash
# TURN 主服务端口
sudo ufw allow 3478/udp
sudo ufw allow 3478/tcp        # WebRTC 可选但建议开启

# TURN 中继端口范围
sudo ufw allow 49152:65535/udp
```

---

## 四、启动与开机自启

```bash
# 重启服务并设为开机自启
sudo systemctl restart coturn
sudo systemctl enable --now coturn

# 查看运行状态（应为 active (running)）
systemctl status coturn
```

---

## 五、验证连通性

使用 coturn 自带的客户端工具进行连通性测试：

```bash
turnutils_uclient -v -u testuser -w testpass 你的公网IP
```

若输出中包含成功分配中继地址（allocation）的日志，说明 TURN 服务工作正常。

---

## 配置参数速查

| 参数 | 说明 | 默认值 |
| ---- | ---- | ------ |
| `listening-ip` | 监听的网卡 IP | - |
| `listening-port` | 监听端口 | `3478` |
| `external-ip` | 公网 IP（云服务器必填） | - |
| `lt-cred-mech` | 启用长期凭证认证 | 关闭 |
| `user` | 连接账号 `用户名:密码` | - |
| `realm` | 认证域（必填） | - |
| `relay-port-range` | 中继端口范围 | - |
| `verbose` | 输出详细日志 | 关闭 |

---

## 常见问题

**Q：客户端始终无法连接？**

- 确认 `lt-cred-mech` 已开启，且客户端使用的 `user` / `realm` 与服务端一致。
- 确认云服务器的**安全组**与本地 `ufw` 均已放行对应端口。
- 确认 `external-ip` 填写的是公网 IP。

**Q：中继流量不通？**

- 检查 `49152:65535/udp` 端口范围是否在防火墙与云安全组中放行。

**Q：如何修改默认端口？**

- 修改 `listening-port` 并同步放行新端口，同时确保客户端信令配置指向新端口。