179 lines
7.7 KiB
Markdown
179 lines
7.7 KiB
Markdown
# p2p-explorer-web - P2P 文件传输工具
|
||
|
||
p2p-explorer-web 是一个基于 WebRTC 的 P2P 远程文件传输、远程文件浏览与实时通信工具。支持在设备间安全、快速地传输文件，并提供远程桌面预览、语音通话和摄像头画面共享等功能，理想情况下无需通过服务器中转数据。
|
||
|
||
在线体验：https://explorer.kuraa.cc
|
||
|
||
## 功能特性
|
||
|
||
- **P2P 流式文件传输** - 基于 WebRTC 的点对点传输，支持大文件分片传输，文件数据不经过服务器
|
||
- **文件夹传输** - 支持完整目录结构的浏览与传输
|
||
- **远程文件浏览** - 可作为远程文件 Web 资源管理器，浏览对方设备的文件系统
|
||
- **本地权限管控** - 支持对本地目录设置读取/写入权限，保护隐私
|
||
- **远程桌面预览** - 实时查看对方桌面画面，支持音频传输与全屏模式
|
||
- **P2P 语音通话** - 端到端加密的实时语音通话，显示通话延迟
|
||
- **摄像头画面共享** - 实时查看对方摄像头画面
|
||
- **剪贴板共享** - 获取对方设备的剪贴板文本内容
|
||
- **ID 连接机制** - 通过简单的 ID 或分享链接即可建立连接
|
||
- **PWA 支持** - 支持安装为独立桌面应用（Service Worker 离线缓存）
|
||
- **无需安装客户端** - 基于浏览器即可使用
|
||
|
||
## 截图
|
||
|
||
| 文件同步 | 桌面预览 | 语音摄像头 |
|
||
| :-------------------------------------------: | :-------------------------------------------: | :---------------------------------------------: |
|
||
| <img src="readme/文件同步.png" width="800" /> | <img src="readme/桌面预览.png" width="800" /> | <img src="readme/语音摄像头.png" width="800" /> |
|
||
|
||
## 架构说明
|
||
|
||
### 数据传输流程
|
||
|
||
```
|
||
┌──────────┐ ┌──────────┐
|
||
│ 设备 A │ ←── WebRTC P2P 直连 ──────→ │ 设备 B │
|
||
└──────────┘ └──────────┘
|
||
↑ ↑
|
||
│ 信令交换（ID 连接） │
|
||
↓ ↓
|
||
┌──────────────────────────────────────────────────┐
|
||
│ PeerJS 信令服务器 (wss://0.peerjs.com) │
|
||
│ STUN/TURN 服务器（NAT 穿透/中继） │
|
||
└──────────────────────────────────────────────────┘
|
||
```
|
||
|
||
- **直连模式**：双方通过 UDP 打洞建立直连，数据传输不经过任何服务器，速度快且安全
|
||
- **中继模式**：当直连失败（如双方都在对称 NAT 后），通过 TURN 服务器中继数据
|
||
|
||
### 需注意的服务
|
||
|
||
| 服务 | 用途 | 数据安全性 |
|
||
| --------------- | ------------------------ | ------------------------------------ |
|
||
| PeerJS 信令 | 交换 ICE 候选信息 | 可信，无本地数据上传 |
|
||
| PeerJS 打洞 | UDP 打洞辅助 | 可信，无数据上传 |
|
||
| STUN 服务器 | 获取公网 IP 及 NAT 类型 | 可信，仅交换网络信息 |
|
||
| TURN 中转服务器 | NAT 穿透失败时的数据中继 | **不可信，所有数据会经过我的服务器** |
|
||
|
||
> 建议：如需传输敏感文件，建议自行 Docker 化部署 STUN/TURN 服务器，保证全链路数据安全。
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- Node.js >= 16
|
||
- Yarn 或 npm
|
||
- 支持 WebRTC 的现代浏览器（Chrome / Edge / Firefox）
|
||
|
||
### 安装与运行
|
||
|
||
```bash
|
||
# 克隆项目
|
||
git clone [项目地址]
|
||
cd p2p-explorer-web
|
||
|
||
# 安装依赖
|
||
yarn install
|
||
|
||
# 启动开发服务器（默认开启 HTTPS，WebRTC 需要安全上下文）
|
||
yarn dev
|
||
```
|
||
|
||
启动后访问 `https://localhost:5173`（注意是 https）。
|
||
|
||
### 构建部署
|
||
|
||
```bash
|
||
# 构建生产版本
|
||
yarn build
|
||
|
||
# 将静态资源拷贝到 dist 目录
|
||
cp -r static dist/
|
||
|
||
# 部署 dist 目录到任意静态文件服务器（需要 HTTPS）
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
### 基本使用
|
||
|
||
1. 设备 A 打开应用，系统自动生成唯一的 Peer ID
|
||
2. 点击 **复制** 按钮复制自己的 ID，或点击 **分享** 一键复制分享链接
|
||
3. 设备 B 在同一页面输入设备 A 的 ID，点击 **连接**
|
||
4. 连接建立后，双方即可互相浏览远程文件目录
|
||
|
||
### 发送文件
|
||
|
||
1. 在左侧 **本地文件区域** 选择要发送的文件或文件夹（支持 Ctrl/Shift 多选）
|
||
2. 点击中部的 **发送** 按钮，文件开始传输
|
||
3. 在底部 **传输列表** 中可查看传输进度、速度和状态
|
||
|
||
### 接收文件
|
||
|
||
1. 在右侧 **远程文件区域** 选择要下载的文件
|
||
2. 点击中部的 **接收** 按钮，选择本地保存位置
|
||
3. 文件自动下载到指定目录
|
||
|
||
### 远程桌面
|
||
|
||
1. 连接成功后，点击状态栏的 **桌面图标** 发起远程桌面请求
|
||
2. 对方确认后即可实时预览其桌面画面
|
||
3. 支持全屏模式和音频开关
|
||
|
||
### 语音通话
|
||
|
||
1. 连接成功后，点击 **电话图标** 发起语音通话
|
||
2. 通话过程中可随时静音/取消静音
|
||
3. 实时显示通话延迟
|
||
|
||
### 摄像头
|
||
|
||
1. 点击 **摄像头图标** 请求查看对方摄像头画面
|
||
2. 再次点击可关闭画面
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
p2p-explorer-web/
|
||
├── src/
|
||
│ ├── pages/
|
||
│ │ ├── file/ # 文件传输主页面
|
||
│ │ │ ├── index.vue # 主页面入口
|
||
│ │ │ ├── item/ # 子组件
|
||
│ │ │ │ ├── clipboard.vue # 剪贴板共享
|
||
│ │ │ │ ├── desptopView.vue # 远程桌面视图
|
||
│ │ │ │ ├── fileIcon.vue # 文件图标
|
||
│ │ │ │ ├── fileItem.vue # 文件列表项
|
||
│ │ │ │ ├── filePermissionSetDialog.vue # 权限设置弹窗
|
||
│ │ │ │ ├── fileReader.vue # 文件阅读器
|
||
│ │ │ │ ├── fileTranserView.vue # 传输列表视图
|
||
│ │ │ │ └── fileView.vue # 文件浏览器视图
|
||
│ │ │ └── utils/ # 工具类
|
||
│ │ │ ├── common.ts # 通用工具函数
|
||
│ │ │ ├── emitter.ts # 事件总线
|
||
│ │ │ ├── fileMgr.ts # 文件管理器
|
||
│ │ │ ├── fileTransfer.ts # 文件传输核心
|
||
│ │ │ ├── peer.ts # P2P 连接管理器
|
||
│ │ │ └── turn.ts # TURN 服务器配置
|
||
│ │ ├── voice/
|
||
│ │ │ └── webrtcVoice.vue # P2P 语音通话
|
||
│ ├── router/
|
||
│ │ └── router.ts # 路由配置
|
||
│ ├── types/ # TypeScript 类型定义
|
||
│ ├── utils/
|
||
│ │ └── pwa.ts # PWA 提示控制
|
||
│ ├── App.vue
|
||
│ └── main.ts
|
||
├── static/ # 静态资源（图标、图片等）
|
||
├── readme/ # README 相关图片
|
||
├── vite.config.ts
|
||
├── tsconfig.json
|
||
└── package.json
|
||
```
|
||
|
||
## 待完成
|
||
|
||
- [ ] Docker 化部署，支持自定义 STUN/TURN 服务器一键部署
|
||
|
||
## 感谢
|
||
|
||
- [PeerJS](https://peerjs.com/) 提供的 WebRTC 简化封装
|