diff --git a/README.md b/README.md index 4b3498a..4654979 100644 --- 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` | + +--- diff --git a/WebRTCSignalServer/README.md b/WebRTCSignalServer/README.md new file mode 100644 index 0000000..e528eba --- /dev/null +++ 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` 并同步放行新端口，同时确保客户端信令配置指向新端口。