# iotTurn

**Repository Path**: project_study_all/iotTurn

## Basic Information

- **Project Name**: iotTurn
- **Description**: 商用级 Rust TURN/STUN 服务器
- **Primary Language**: Rust
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-16
- **Last Updated**: 2026-10-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# iotturn

[English](README.en.md) | 简体中文

商用级 Rust TURN/STUN 服务器，内置 **P2P 打洞**、**流量计量与配额控制**、**主从集群** 等能力。

## 特性

- STUN / TURN 协议（RFC 8489 / RFC 8656），UDP / TCP / TLS / DTLS 传输
- IPv4/IPv6 双栈，IPv6 中继（RFC 6156）
- Long-Term Credential 认证（无状态 Nonce）
- 内部 P2P 打洞：候选预收集、并行探测、<300ms 建链、无缝回落中继
- 流量计量与配额控制：流量统计、1GB 级限额（用尽停用：拒绝新分配并断开会话）、3Mbps 级带宽限制
- 主从模式集群：后台一键配置，1 主 N 从
- **Web Admin Console**：内置单页管理后台（仪表盘 / 用户 / 会话 / 集群节点 / 审计）
- **WebRTC 视频通话 Demo**：`/demo` 页，两个标签页经 STUN/TURN 建立通话（支持强制 relay 模式验证中继）
- 管理后台登录保护：连续 5 次密码错误锁定 10 分钟；`iotturn admin-passwd` / `admin-unlock` 可重置密码、立即解锁

## 在线演示

无需部署即可在线体验：

**① WebRTC 通话演示**：**<https://turn.makeiot.cn:8000/demo>**

- 打开**两个标签页**（或两台设备）进入演示页：两端默认自动加入同一房间，也可在两侧填入**相同的房间号**自定义配对（WebSocket 房间信令，跨设备/跨浏览器）；
- 点击「开启摄像头」→「发起呼叫」，媒体经 STUN/TURN 建立通话；页面实时显示链路类型（**P2P 直连** / **TURN 中继**）与 **IPv4/IPv6**；
- 将 ICE 下拉切换为 **relay — 强制全部走 TURN 中继**，即可验证中继链路（页面同步显示 host / srflx / relay 候选计数）。

**② 管理后台演示**：**<https://turn.makeiot.cn:8000/admin/>**

- 登录账号 `admin` / 密码 `123456`：可体验仪表盘、用户管理、会话监控、集群节点、系统设置、审计日志、API 密钥等完整功能；
- 演示环境为公开共享，请勿修改配置与密码；连续 5 次密码错误会锁定 10 分钟（可用 `iotturn admin-unlock` 立即解除）。

**详细介绍**：[`doc.md`](doc.md) —— 完整的功能与架构说明（协议实现 / P2P 打洞 / 配额与集群 / 管理面设计 / 性能数据）。

## 目录结构

```
src/
├── main.rs            # 入口：CLI、配置加载、运行时组装
├── lib.rs             # 库根，模块导出
├── error.rs           # 统一错误类型
├── config.rs          # TOML 配置解析
├── stun/              # STUN 协议编解码（RFC 8489）
│   ├── message.rs     # 消息头 / 事务 ID / 类型编解码
│   ├── attribute.rs   # 属性编解码（含 XOR 地址）
│   └── integrity.rs   # MESSAGE-INTEGRITY / FINGERPRINT
├── transport/         # 传输层：UDP/TCP/TLS/DTLS
│   ├── udp.rs         # UDP（SO_REUSEPORT）
│   ├── tcp.rs         # TURN over TCP
│   ├── tls.rs         # TURNS（TLS 1.3）
│   ├── dtls.rs        # TURNS over DTLS
│   ├── channel.rs     # ResponseChannel 抽象
│   └── framing.rs     # TCP/TLS 帧读取
├── turn/              # TURN 请求分发、处理与中继转发
├── session/           # 会话（Allocation）管理
├── auth/              # Long-Term Credential 认证（无状态 nonce）
├── quota/             # 流量计量与配额（令牌桶）
├── store/             # 用户存储（内存 / JSON / SQLite / MySQL）
├── p2p/               # P2P 打洞（信令 + 探测代理）
├── cluster/           # 主从集群（注册/心跳/调度/重定向）
└── admin/             # 管理 REST API + 配置读写（存储/后台托管/后台路径）+ 审计

tests/                 # 集成测试（协议/数据面/传输/P2P/存储/集群/管理）
config/                # 配置文件（示例、单机、主从）
scripts/               # 协议级验证脚本（verify_*.py）
deploy/                # 部署资产（systemd 单元 / deploy.sh / 主站静态页）
```

## 快速开始

```bash
# 1. 准备配置（可省略：未提供时启动会提示访问 http://IP:8000/ 进入初始化向导）
cp config/iotturn.toml.example config/iotturn.toml

# 2. 构建管理后台前端（可选：前端在编译期嵌入二进制，未构建则后台页面不可用）
npm --prefix admin_web install
npm --prefix admin_web run build

# 3. 开发运行（前台，Ctrl+C 退出）
cargo run --release -- run --config config/iotturn.toml

# 4. 命令行管理（bt 面板风格：终端输入 iotturn 即进入管理面板）
#    服务器上建议软链到 PATH：
ln -sf "$(pwd)/target/release/iotturn" /usr/local/bin/iotturn
iotturn              # 交互式管理面板：启动/停止/重启/状态/日志/编辑配置/后台路径/端口与 SSL
iotturn start        # 守护模式启动（后台运行，默认）
iotturn status       # 查看服务状态
iotturn log -f       # 实时日志（Ctrl+C 退出查看）
iotturn admin-path   # 查看当前后台访问路径/域名绑定（设置页或 CLI 均可修改）
iotturn admin-path manage   # 修改后台路径（自动改写前端静态路径；旧路径直接 404）
iotturn admin-domain admin.example.com   # 绑定后台访问域名（仅该域名可访问后台）
iotturn admin-port 8443   # 修改后台访问端口（默认 8000；admin-port default 恢复默认）
iotturn admin-ssl off     # 关闭后台 SSL（改明文 HTTP，不建议公网；admin-ssl on 恢复）
iotturn admin-passwd admin '新密码'   # 忘记后台密码自救：重置管理员密码并自动解锁（需重启生效）
iotturn admin-unlock admin            # 立即解除登录锁定（无参数 = 列出当前锁定账号）
```

> - 服务控制优先委托 systemd（存在 `iotturn.service` 时自动用 systemctl/journalctl）；
>   无 systemd 环境下使用**内置守护进程模式**（setsid 后台运行，PID/日志文件与配置文件同目录），
>   `--standalone` 可强制内置守护模式。
> - `iotturn run` 前台运行，供 systemd `ExecStart` / 容器使用；无子命令 + 非交互环境等价 `run`。

## 测试

```bash
cargo test
cargo clippy
# 性能对照（可选）：
cargo run --release --example micro_bench   # 热路径微基准（旧/新实现同进程对照）
cargo run --release --example relay_bench -- <server.exe> --label old --duration 10   # 端到端 TURN 回环压测（吞吐/RTT/每包 CPU）
```

## 文档

- **架构设计与实现说明**：[`doc.md`](doc.md)
- **部署指南**（全新服务器从零部署：上传单个二进制（已含管理后台）→ 配置 → 放行端口 → 运行/升级/FAQ）：[`docs/deployment.md`](docs/deployment.md)
- **硬件对接指南**（设备/固件接入 TURN/STUN/P2P 信令）：[`docs/hardware-integration.md`](docs/hardware-integration.md)
- **更新日志**：[`CHANGELOG.md`](CHANGELOG.md)
- **贡献指南**：[`CONTRIBUTING.md`](CONTRIBUTING.md) ｜ **安全漏洞报告**：[`SECURITY.md`](SECURITY.md)

## 开源许可

本项目采用 **Apache License 2.0** 开源发布，详见 [`LICENSE`](LICENSE)。

管理后台前端（`admin_web/`）基于 [TDesign Vue Next Starter](https://github.com/Tencent/tdesign-vue-next-starter)（MIT License）二次开发，
其原始许可文本保留在 [`admin_web/LICENSE`](admin_web/LICENSE)；使用到的第三方依赖许可见下节声明。

## 第三方依赖与代码（License 合规声明）

本项目协议核心（STUN/TURN 编解码、会话/中继、认证、配额、集群、P2P）为**仓库内自研**，
未复制任何现成 TURN 服务器实现（如 coturn / rust-turn）。以下为实际使用的第三方依赖，
全部为 Apache-2.0 / MIT 等宽松开源许可。

### 后端（Rust，见 `Cargo.toml`）

| 分类 | Crate | 用途 |
|---|---|---|
| 异步运行时 | `tokio` | 多线程 runtime、网络、任务调度（`worker_threads = 8`） |
| HTTP/管理面 | `axum 0.8` | 管理 REST API + WebSocket（`/api/v1/*`、`/ws`） |
| Webhook 推送 | `reqwest 0.12` | 事件投递（10s 超时、日志入库） |
| TLS | `rustls 0.23` / `tokio-rustls` / `rustls-pemfile` | TURNS（TLS 1.3）；证书由管理后台“系统设置 → SSL 证书”上传 PEM |
| 证书（仅开发/测试） | `rcgen` | 本地/集成测试与开发回退用自签；**生产 TURNS 默认关闭，未上传正式证书不启用（生产启动路径不会触发自签）** |
| **DTLS** | `webrtc-dtls 0.10` / `webrtc-util 0.9`（webrtc-rs） | TURNS over DTLS 握手（协议复杂，复用开源实现） |
| 协议算法 | `sha1/sha2/hmac/md-5/crc32fast/hex` | STUN 完整性校验 / 指纹 / 短期凭据 |
| 存储 | `rusqlite`(bundled) / `mysql 28` | SQLite / MySQL 用户存储 |
| 工具 | `serde/serde_json/toml/tracing/tracing-subscriber/clap/thiserror/dashmap/socket2/bytes/libc/rand/futures-util` | 序列化、日志、CLI、并发容器、套接字等 |

> `mysql` crate 为同步 IO 驱动；为规避阻塞 tokio worker，所有同步存储调用均经
> `store::run_blocking`（`tokio::task::block_in_place`，见下节）隔离。

### 前端（`admin_web/`）

- **框架**：`vue 3` / `pinia` / `vue-router` / `vue-i18n`
- **UI 组件库**：`tdesign-vue-next` + `tdesign-icons-vue-next`（腾讯开源）
- **管理后台模板**：`admin_web` 基于 **TDesign Starter 0.14（腾讯开源模板）** 二次开发——
  脚手架、布局、路由/i18n/store 骨架沿用其代码（已按模板许可保留版权标识），业务页与后端交互为自行实现
- 其它：`axios`、`@vueuse/core`、`echarts`、`dayjs`、`lodash`、`qs`、`vite` 等
- **API 文档**：Swagger UI 通过 cdnjs CDN 在线加载（`/api/docs`）

## 架构与稳定性说明

- **模块**：`main`（组装）→ `transport`（UDP/TCP/TLS/DTLS）→ `turn`/`session`（协议与会话）
  → `auth`/`quota`/`store`（认证/计量/存储）→ `admin`（管理 API + 控制台 + Swagger）
  → `cluster`（主从）→ `p2p`（打洞）→ `webhook`（事件推送 + 日志）。
- **并发模型**：单进程单二进制，tokio 多线程（固定 8 worker，避免小核数机器 worker 过少）。
  会话管理用 `DashMap` 无锁读；带宽用账号级共享令牌桶；配额执行与流量上报为独立周期任务。
- **同步存储隔离**：`mysql`/`sqlite` 为同步 IO，被 async 任务调用时经
  `store::run_blocking` → `tokio::task::block_in_place` 执行——慢查询只占用当前线程，
  调度器自动补线程，杜绝"一次查询卡死全部 worker"的假死问题；在无 runtime（单测）或
  current_thread runtime 下自动退化为直接执行。
- **事件推送闭环**：Webhook 固定 10s 超时；每次投递（成功/超时/失败）记录
  （发送内容/返回内容/耗时）写入 `webhook_logs`（MySQL）或内存回退。
- **TURNS / wss 证书**：`TlsConfig.enabled` 默认关闭；必须在“系统设置 → SSL 证书”上传
  PEM 证书（服务端校验后写入配置文件同目录 `tls/server.crt|server.key` 并自动启用），
  重启后 TLS（默认 5349）才监听。未上传证书则完全不开启，生产不使用自签名证书。
  注意：TLS 支持 RSA/ECDSA/Ed25519 证书；**DTLS 因 `webrtc-dtls` 仅支持 ECDSA/Ed25519**，
  RSA 证书会仅启用 TLS（DTLS 自动跳过并告警，不影响服务）。
- **生产运维**：`systemd`（Restart=always）；建议自建 `/health` 探活看门狗（失败自动重启）。

## 许可

Apache-2.0