# 更新源并安装 Coturn (建议编译安装以获取最新安全补丁，此处演示包管理器快速部署)
sudo apt update && sudo apt install -y coturn libssl-dev

# 关键：默认安装后服务不会自动启动，需手动配置 systemd
sudo systemctl enable coturn

# ========== 网络监听配置 ==========
# 监听所有接口，生产环境建议绑定具体内网 IP
listening-ip=0.0.0.0
listening-port=3478
tls-listening-port=5349

# 外网 IP 映射 (云服务器 NAT 场景必填，格式: 公网IP/内网IP)
external-ip=203.0.113.25/10.0.0.5

# 端口范围 (需云厂商安全组同步放行)
min-port=49152
max-port=65535

# ========== 认证核心配置 ==========
# 1. 启用 REST API (临时凭证) 模式
use-auth-secret
# 2. 共享密钥 (生产环境必须使用 openssl rand -base64 32 生成高强度随机串)
static-auth-secret=YOUR_SUPER_SECURE_RANDOM_SECRET_KEY_GENERATED_BY_OPENSSL
# 3. Realm 域标识 (需与客户端生成 token 时一致)
realm=yourcompany.com

# 4. 【关键安全项】禁用长期凭证机制，防止降级攻击
# 如果不加此项，攻击者若猜到/泄露了静态账号仍可绕过 REST API
no-auth-secret-required=false  # 确保必须走 auth-secret 逻辑
# 或者显式禁用旧版长期认证 (视版本而定，新版 use-auth-secret 通常隐含此意)
# no-tlsv1
# no-tlsv1_1

# ========== 传输安全加固 ==========
# 强制启用 TLS/DTLS 加密传输 (需准备证书文件)
cert=/etc/ssl/certs/turn_server_cert.pem
pkey=/etc/ssl/private/turn_server_key.pem
# 仅允许加密传输 (视客户端兼容性决定，建议开启)
# allow-tls
# allow-dtls

# ========== 性能与防滥用 ==========
# 最大并发会话数
max-bps=100000000
# 单 IP 最大会话数 (防刷)
max-sessions-per-ip=50
# 总会话上限
total-quota=10000
# 禁用 CLI 明文管理端口 (安全审计硬性要求)
no-cli
# no-tcp-relay  # 如业务仅需 UDP 可关闭 TCP 中继减少攻击面

# ========== 日志审计 ==========
log-file=/var/log/turnserver/turnserver.log
syslog
verbose

import hmac
import hashlib
import base64
import time
import json

# 配置项 (建议存入环境变量或密钥管理系统 KMS)
TURN_SHARED_SECRET = "YOUR_SUPER_SECURE_RANDOM_SECRET_KEY_GENERATED_BY_OPENSSL"
TURN_REALM = "yourcompany.com"
TURN_SERVER = "turn.yourcompany.com:3478"  # 或 turn:203.0.113.25:3478
TURN_TLS_SERVER = "turns.yourcompany.com:5349"
TTL_SECONDS = 86400  # 24小时，高安全场景可缩短至 1-2 小时

def generate_turn_credentials(user_id: str) -> dict:
    """
    生成符合 RFC 8656 标准的 TURN 临时凭证
    :param user_id: 业务系统用户唯一标识 (建议脱敏处理，如 UUID)
    :return: 包含 username, credential, urls, ttl 的字典
    """
    # 1. 计算过期时间戳 (Unix UTC)
    timestamp = int(time.time()) + TTL_SECONDS
    
    # 2. 构造 username: "timestamp:userid"
    # 注意: userid 中不应包含 ':' 字符，建议 Base64UrlEncode 或 UUID
    username = f"{timestamp}:{user_id}"
    
    # 3. HMAC-SHA1 签名 (密钥需为 bytes)
    key = TURN_SHARED_SECRET.encode('utf-8')
    msg = username.encode('utf-8')
    hmac_digest = hmac.new(key, msg, hashlib.sha1).digest()
    
    # 4. Base64 编码得到 credential
    credential = base64.b64encode(hmac_digest).decode('utf-8')
    
    # 5. 返回 ICE 服务器配置格式 (兼容 WebRTC 标准 RTCIceServer)
    return {
        "iceServers": [
            {
                "urls": [
                    f"turn:{TURN_SERVER}?transport=udp",
                    f"turn:{TURN_SERVER}?transport=tcp",
                    f"turns:{TURN_TLS_SERVER}?transport=tcp"  # TLS 优先
                ],
                "username": username,
                "credential": credential,
                "credentialType": "password"  # 标准 WebRTC 字段
            }
        ],
        "ttl": TTL_SECONDS
    }

# Flask/FastAPI 接口示例
# @app.route('/api/turn/credentials')
# def get_turn_creds():
#     user_id = get_current_user_id()  # 从 JWT/Session 获取
#     return jsonify(generate_turn_credentials(user_id))

# 测试 UDP 临时凭证认证及中继连通性
# -u: username, -p: credential, -v: 详细日志, -P: 使用 UDP
turnutils_uclient -u "1715000000:testuser" -p "GENERATED_CREDENTIAL" -v -P turn.yourcompany.com

# 测试 TLS 连通性 (需指定 -T)
turnutils_uclient -u "..." -p "..." -v -T turns.yourcompany.com

class TurnCredentialManager {
  private cache: Map<string, RTCIceServer[]> = new Map();
  private refreshTimers: Map<string, NodeJS.Timeout> = new Map();

  // 核心：获取可用 ICE 配置，自动处理刷新与降级
  async getIceServers(userId: string): Promise<RTCIceServer[]> {
    const cached = this.cache.get(userId);
    if (cached && this.isValid(cached)) return cached;

    // 并发请求 + 竞态控制 (防止并发刷新风暴)
    const lockKey = `turn_lock_${userId}`;
    return await this.withLock(lockKey, async () => {
      // Double Check
      if (this.cache.has(userId) && this.isValid(this.cache.get(userId)!)) {
        return this.cache.get(userId)!;
      }
      const resp = await this.fetchFromBackend(userId); // 含指数退避重试
      this.cache.set(userId, resp.iceServers);
      this.scheduleRefresh(userId, resp.ttl);
      return resp.iceServers;
    });
  }

  // 关键：预刷新不销毁旧连接，WebRTC 栈会自动选优
  private scheduleRefresh(userId: string, ttl: number) {
    const delay = Math.max((ttl - 300) * 1000, 60_000); // 至少 1 分钟后刷新
    this.refreshTimers.set(userId, setTimeout(() => this.refreshSilently(userId), delay));
  }
}

graph TD
    Client[Client SDK] -->|DNS/HTTPDNS| GLB[全局负载均衡 GLB/GeoDNS]
    GLB -->|就近接入| NLB_A[地域A NLB<br/>TCP/UDP 透传]
    GLB -->|就近接入| NLB_B[地域B NLB<br/>TCP/UDP 透传]
    NLB_A --> Coturn_Cluster_A[Coturn Cluster A<br/>3+ Nodes]
    NLB_B --> Coturn_Cluster_B[Coturn Cluster B<br/>3+ Nodes]
    Coturn_Cluster_A -->|共享会话/配额| Redis_Cluster[(Redis Cluster<br/>Sentinel/Cluster Mode)]
    Coturn_Cluster_B -->|跨域复制/只读| Redis_Cluster
    Admin[运维平台] -->|动态下发配置| Coturn_Cluster_A
    Admin -->|动态下发配置| Coturn_Cluster_B

# 1. 启用 Redis 共享状态 (分配端口、带宽配额、封禁 IP 同步)
redis-host=redis-cluster.internal
redis-port=6379
redis-password=${REDIS_PASSWORD}  # 从 KMS 注入
redis-db=0
# 关键：使用 Redis 存储 allocation 状态，实现节点故障秒级切换不丢会话
redis-statsdb
redis-userdb

# 2. 节点唯一标识 (用于集群内诊断)
server-name=turn-node-${HOSTNAME}.yourcompany.com

# 3. 禁用本地文件存储，全靠 Redis
# no-cli (已在上文配置)
# no-stdout-log

infra/turn-cluster/
├── base/
│   ├── deployment.yaml          # Deployment/StatefulSet (含资源限制 requests/limits)
│   ├── service.yaml             # Headless Service (用于 StatefulSet DNS)
│   ├── configmap.yaml           # 非敏感配置模板 (realm, port-range)
│   └── secret.yaml              # 敏感占位 (static-auth-secret, cert, redis-pwd) -> SealedSecret/Vault Agent
├── overlays/
│   ├── prod-cn-beijing/
│   │   ├── kustomization.yaml   # 副本数 6, 资源限制高, 节点亲和性
│   │   └── patch-cert.yaml      # 证书指纹
│   └── prod-cn-shanghai/
│       └── ...
├── monitoring/
│   ├── servicemonitor.yaml      # Prometheus 抓取配置 (端口 3478/5349 metrics)
│   └── prometheus-rules.yaml    # 告警规则 (见下文)
└── scripts/
    ├── cert-renewal.sh          # Cert-manager Hook: 证书续期 -> 滚动重启
    └── secret-rotation.sh       # 密钥轮换: Vault 生成新密钥 -> Patch Secret -> 滚动重启

# 1. 资源利用率
# CPU/内存/网卡吞吐 (Node Exporter)
# 端口池使用率
turn_allocated_ports / turn_max_ports * 100 > 80  # 告警: 端口耗尽风险

# 2. 业务饱和度
# 当前活跃中继会话数
turn_active_allocations
# 单节点带宽利用率
rate(turn_bytes_sent_total[1m]) + rate(turn_bytes_recv_total[1m]) / node_network_speed_bytes > 70%

# 3. 错误与异常 (核心 SLO)
# 认证失败率 (含 401/438/403)
sum(rate(turn_auth_failures_total[5m])) by (instance, error_code) 
  / sum(rate(turn_auth_attempts_total[5m])) by (instance) > 0.05  # 告警: 疑似爆破或密钥不匹配

# 分配失败率 (无端口/带宽耗尽/内部错误)
sum(rate(turn_allocation_failures_total[5m])) by (instance, reason)
  / sum(rate(turn_allocation_requests_total[5m])) by (instance) > 0.01

# 4. 质量体验 (需客户端上报关联)
# TURN 延迟分布 (客户端上报 RTT)
histogram_quantile(0.99, rate(turn_rtt_bucket[5m])) > 300  # 告警: 中继链路质量劣化
# 丢包率 (客户端上报)
sum(rate(turn_packets_lost_total[5m])) / sum(rate(turn_packets_total[5m])) > 0.02