l7mp/stunner-auth-server

STUNner TURN认证凭证生成API镜像

镜像概述

本Docker镜像提供REST API服务，专注于生成STUNner TURN服务器的认证凭证。STUNner是高性能STUN/TURN服务器，广泛应用于WebRTC等实时通信场景中的媒体流转发。该镜像通过标准化API接口简化TURN服务认证流程，助力开发者高效管理TURN服务的访问控制机制。

核心功能与特性

• REST API接口：提供HTTP标准接口，支持动态生成TURN认证凭证，兼容主流API调用方式。
• STUNner协议兼容：严格遵循STUNner TURN服务的认证规范，生成的凭证可直接用于STUNner服务器鉴权。
• 凭证生成机制：支持基于长期凭证机制（Long-Term Credential Mechanism）生成用户名及对应密钥，确保认证安全性。
• 轻量级架构：基于精简基础镜像构建，容器启动快速，资源占用低，适合边缘计算环境部署。
• 可配置参数：通过环境变量自定义凭证有效期、密钥算法、日志级别等核心参数，适应不同场景需求。

使用场景与适用范围

• WebRTC应用部署：为基于WebRTC的音视频通话应用提供TURN服务认证支持，解决NAT穿透场景下的媒体流转发问题。
• 动态凭证管理：适用于需要临时或按需生成TURN凭证的场景，避免静态凭证泄露风险。
• STUNner生态集成：作为STUNner TURN服务器的配套组件，在STUNner部署架构中承担认证凭证管理角色。
• 多租户系统：支持为不同用户/租户生成独立凭证，实现TURN服务的精细化访问控制。

使用方法与配置说明

基础部署（docker run）

bash
docker run -d -p 8080:8080 --name stunner-cred-api \
  -e STUNNER_SECRET="your_stunner_shared_secret" \
  -e CREDENTIAL_TTL=3600 \
  -e LOG_LEVEL=info \
  stunner-cred-api:latest

参数说明

• -p 8080:8080：映射容器内API服务端口（默认8080）至主机端口
• STUNNER_SECRET：（必填）STUNner TURN服务器配置的共享密钥，用于凭证签名
• CREDENTIAL_TTL：（可选，默认3600秒）凭证有效期，单位为秒
• LOG_LEVEL：（可选，默认info）日志输出级别，支持debug/info/warn/error

环境变量配置详解

API接口使用说明

生成TURN认证凭证

• 请求地址：/api/v1/credentials
• 请求方法：POST
• 请求头：Content-Type: application/json
• 请求体（可选）：

  json
  {
    "username_prefix": "custom_prefix_"  // 覆盖全局USERNAME_PREFIX配置
  }
  

• 响应示例：

  json
  {
    "status": "success",
    "data": {
      "username": "custom_prefix_1690000000",  // 用户名（含时间戳）
      "credential": "a1b2c3d4e5f6a7b8c9d0",   // TURN认证密钥
      "expires_at": 1690003600,               // 过期时间戳（Unix秒级）
      "ttl": 3600                             // 凭证有效期（秒）
    }
  }
  

docker-compose部署示例

yaml
version: "3.8"
services:
  stunner-cred-api:
    image: stunner-cred-api:latest
    container_name: stunner-cred-api
    ports:
      - "8080:8080"
    environment:
      - STUNNER_SECRET=your_stunner_shared_secret_here
      - CREDENTIAL_TTL=7200  # 凭证有效期2小时
      - LOG_LEVEL=warn
      - USERNAME_PREFIX=webrtc_
      - HMAC_ALGORITHM=sha256
    restart: unless-stopped
    networks:
      - stunner-network

networks:
  stunner-network:
    external: true  # 假设已存在与STUNner服务器共享的网络

注意事项

1. 密钥安全性：STUNNER_SECRET为敏感信息，建议通过Docker Secrets或环境变量加密工具管理，避免明文暴露。
2. 凭证有效期：根据实际业务场景调整CREDENTIAL_TTL，建议设置为1-24小时，平衡安全性与用户体验。
3. HTTPS配置：生产环境中需通过反向代理（如Nginx）为API服务配置HTTPS，防止凭证在传输过程中被窃听。
4. STUNner版本兼容：确保镜像版本与STUNner服务器版本匹配，避免因协议变更导致凭证认证失败。