docs: 修改 TURN 部署指南并新增环境说明

2026-08-20 09:50:29 +08:00
parent 48dc443a31
commit d65c30a6fb
2 changed files with 270 additions and 25 deletions
--- a/README.md
+++ b/README.md
@@ -1,36 +1,127 @@
-安装 turnserver
+# VibeCoding — WebRTC 远程控制系统

-sudo apt update
-sudo apt install coturn -y
+本仓库为多端单体仓库（monorepo）：1 个 Spring Boot 信令服务器 + 1 个后台管理前端 + 1 个 Android 被控端 + 5 个控制端（Android / iOS / Flutter / Web）+ 1 个独立 ADB 回环工具。

-sudo cp /etc/turnserver.conf /etc/turnserver.conf.bak
-sudo vim /etc/turnserver.conf
+> 标注 **（待填写）** 的项表示尚未确认，请按实际环境补充。

-# 监听
-listening-ip=0.0.0.0
-listening-port=3478
+---

-# 公网 IP（云服务器这里必须填公网 IP，不是内网 IP）
-external-ip=你的公网IP
+## 一、WebRTCSignalServer — 信令服务器（Spring Boot）

-# 认证（WebRTC 必须，否则客户端连不上）
-lt-cred-mech
-user=testuser:testpass
-realm=yourdomain.com # 随便填个域名也行，但不能不填
+| 项目 | 值 |
+|---|---|
+| 工程类型 | Spring Boot 应用（Maven） |
+| 框架版本 | Spring Boot 4.1.0 |
+| 语言 / JDK | Java 25 |
+| IDE | IntelliJ IDEA 2025.3.1 |
+| 运行端口 | 8080 |
+| 外部依赖 | MySQL（JPA 持久化）、Redis（在线状态 / 频控 / nonce / 踢线广播） |
+| 构建命令 | `mvn clean package` / `mvn spring-boot:run` |
+| 配置入口 | `src/main/resources/application.yml`（敏感项走环境变量） |

-# 中继端口范围（TURN 转发媒体用）
-relay-port-range=49152-65535
+## 二、WebRTCSignalServerWeb — 后台管理前端（Vue3 + TS）

-# 日志
-verbose
+| 项目 | 值 |
+|---|---|
+| 工程类型 | Vue 3 SPA（TypeScript，ESM） |
+| Vue | ^3.5.12 |
+| TypeScript | ^5.6.3 |
+| Vite | ^5.4.10 |
+| Pinia / Vue Router | ^2.2.4 / ^4.4.5 |
+| UI 组件库 | Element Plus ^2.8.4 |
+| Node.js | 24.14.1 |
+| 包管理器 | npm |
+| dev 端口 | 5180 |
+| 命令 | `npm run dev` / `npm run build`（含 `vue-tsc --noEmit`）/ `npm run preview` |

-sudo ufw allow 3478/udp
-sudo ufw allow 3478/tcp        # WebRTC 可选但建议
-sudo ufw allow 49152:65535/udp # TURN 中继端口
+## 三、WebRTCControlled — Android 被控端

-sudo systemctl restart coturn
-sudo systemctl enable --now coturn
-systemctl status coturn   # 看是不是 active (running)
+| 项目 | 值 |
+|---|---|
+| 语言 | Java（Java 8） |
+| IDE | Android Studio Panda 4 \| 2025.3.4 Patch 1 |
+| applicationId | `com.ttstd.controlled` |
+| compileSdk | 34 |
+| minSdk | 24 |
+| targetSdk | 34 |
+| Gradle Wrapper | 8.13 |
+| Android Gradle Plugin | 8.13.2 |
+| JDK 版本 | 21 |
+| 签名配置 | 依赖外部 `config.gradle`（`keypub` / `crosshatch` / `zhanxun`），不在仓库内 |
+| 构建命令 | `gradlew.bat assembleDebug`（Windows）/ `./gradlew assembleDebug` |

-turnutils_uclient -v -u testuser -w testpass 你的公网IP
+## 四、WebRTCController — Android 控制端

+| 项目 | 值 |
+|---|---|
+| 语言 | Java（Java 8） |
+| IDE | Android Studio Panda 4 \| 2025.3.4 Patch 1 |
+| applicationId | `com.ttstd.controller` |
+| compileSdk | 34 |
+| minSdk | 24 |
+| targetSdk | 34 |
+| Gradle Wrapper | 8.13 |
+| Android Gradle Plugin | 8.13.2 |
+| JDK 版本 | 21 |
+| 签名配置 | 同被控端，依赖外部 `config.gradle` |
+| 构建命令 | `gradlew.bat assembleDebug`（Windows）/ `./gradlew assembleDebug` |
+
+## 五、webrtc_controller_flutter — Flutter 控制端（跨平台）
+
+| 项目 | 值 |
+|---|---|
+| 工程类型 | Flutter App（Android + iOS） |
+| Dart SDK | ^3.12.2 |
+| IDE | Android Studio Panda 4 \| 2025.3.4 Patch 1 |
+| Flutter 版本 | （待填写，channel: stable） |
+| Android compileSdk / minSdk / targetSdk | 跟随 Flutter 默认（`flutter.compileSdkVersion` / `flutter.minSdkVersion` / `flutter.targetSdkVersion`，具体值待确认） |
+| Android 编译兼容 | Java 17（jvmTarget 17） |
+| iOS Deployment Target | 13.0 |
+| iOS Swift 版本 | 5.0 |
+| Gradle Wrapper | 8.14 |
+| 依赖管理 | pub（核心：`flutter_webrtc ^1.5.2`） |
+| 命令 | `flutter pub get` / `flutter run` / `flutter analyze` |
+
+## 六、webrtc_controller_ios — 原生 iOS 控制端
+
+| 项目 | 值 |
+|---|---|
+| 工程类型 | iOS App（UIKit + SwiftUI 混合） |
+| 语言 | Swift 5.0 |
+| iOS Deployment Target | 15.0 |
+| Xcode 版本 | 16 |
+| 依赖管理 | Swift Package Manager（无 CocoaPods） |
+| 关键依赖 | WebRTC（SPM 远程包） |
+| 构建方式 | 用 Xcode 打开 `webrtc_controller_ios.xcodeproj` 运行 |
+
+## 七、WebRTCControllerWeb — 网页控制端（Vue3 + JS）
+
+| 项目 | 值 |
+|---|---|
+| 工程类型 | Vue 3 SPA（纯 JavaScript，无 TypeScript） |
+| Vue | ^3.4.21 |
+| Vite | ^5.2.0 |
+| 控制指令编码 | protobufjs ^7.3.2（浏览器原生 WebRTC API） |
+| Node.js | v24.14.1 |
+| 包管理器 | npm |
+| dev 端口 | 5173（`/api` 与 `/ws/signal` 代理到信令服务器） |
+| 命令 | `npm run dev` / `npm run build` / `npm run preview` |
+
+## ~~八、AdbLoopbackController — ADB 回环控制工具（独立）~~
+
+| 项目 | 值 |
+|---|---|
+| 工程类型 | Android App（纯 Java） |
+| 语言 | Java（Java 8） |
+| IDE | Android Studio Panda 4 \| 2025.3.4 Patch 1 |
+| applicationId | `com.ttstd.adbloopback` |
+| compileSdk | 34 |
+| minSdk | 24 |
+| targetSdk | 34 |
+| Gradle Wrapper | 8.13 |
+| Android Gradle Plugin | 8.1.4 |
+| JDK 版本 | 21 |
+| 签名配置 | 依赖外部 `config.gradle`（`keypub`） |
+| 构建命令 | `gradlew.bat assembleDebug`（Windows）/ `./gradlew assembleDebug` |
+
+---
--- a/WebRTCSignalServer/README.md
+++ b/WebRTCSignalServer/README.md
@@ -0,0 +1,154 @@
+# 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` 并同步放行新端口，同时确保客户端信令配置指向新端口。