# 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 简化封装