mirror of
https://github.com/MatrixSeven/file-transfer-go.git
synced 2026-05-18 01:57:28 +08:00
支持多人加入/下载
This commit is contained in:
seven
355
README.md
Normal file
355
README.md
Normal file
@@ -0,0 +1,355 @@
|
||||
# 川 - P2P文件传输系统
|
||||
|
||||
一个基于WebRTC技术的点对点文件传输系统，支持无服务器中转的直接文件传输。
|
||||
|
||||
## ✨ 功能特性
|
||||
|
||||
### 🚀 核心功能
|
||||
- **纯P2P传输**：文件直接在浏览器间传输，无需上传到服务器
|
||||
- **取件码机制**：6位随机取件码，简单易用
|
||||
- **实时传输**：支持大文件高速传输，64KB分块优化
|
||||
- **多文件支持**：可同时选择和传输多个文件
|
||||
- **拖拽上传**：支持文件拖拽选择
|
||||
|
||||
### 🛡️ 安全特性
|
||||
- **端到端加密**：WebRTC内置加密，数据传输安全
|
||||
- **临时连接**：传输完成后自动清理连接
|
||||
- **无文件存储**：服务器不存储任何文件内容
|
||||
- **房间隔离**：每个取件码对应独立的传输房间
|
||||
|
||||
### 🌐 技术特性
|
||||
- **WebRTC DataChannel**：高效的浏览器间直连
|
||||
- **国内STUN优化**：使用阿里云、腾讯云等国内STUN服务器
|
||||
- **断线重连**：WebSocket连接自动重连机制
|
||||
- **传输进度**：实时显示文件传输进度
|
||||
- **跨平台兼容**：支持现代浏览器（Chrome、Firefox、Safari、Edge）
|
||||
|
||||
## 🏗️ 系统架构
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
|
||||
│ 发送方浏览器 │◄────────┤ 信令服务器 ├────────►│ 接收方浏览器 │
|
||||
│ │ │ │ │ │
|
||||
│ ┌───────────┐ │ │ ┌──────────┐ │ │ ┌───────────┐ │
|
||||
│ │ 文件选择 │ │ │ │ WebSocket│ │ │ │ 取件码输入│ │
|
||||
│ └───────────┘ │ │ │ 信令 │ │ │ └───────────┘ │
|
||||
│ ┌───────────┐ │ │ └──────────┘ │ │ ┌───────────┐ │
|
||||
│ │ 生成取件码│ │ │ ┌──────────┐ │ │ │ 文件接收 │ │
|
||||
│ └───────────┘ │ │ │ 房间管理 │ │ │ └───────────┘ │
|
||||
│ │ │ └──────────┘ │ │ │
|
||||
└─────────────────┘ └──────────────┘ └─────────────────┘
|
||||
│ │
|
||||
└─────────────────── WebRTC P2P 连接 ──────────────────┘
|
||||
(文件直接传输)
|
||||
```
|
||||
|
||||
## 🛠️ 技术栈
|
||||
|
||||
### 后端
|
||||
- **Go 1.21+**：高性能Web服务器
|
||||
- **Chi Router**：轻量级HTTP路由
|
||||
- **Gorilla WebSocket**：WebSocket连接管理
|
||||
- **标准库**：HTML模板、JSON处理等
|
||||
|
||||
### 前端
|
||||
- **原生JavaScript**：无框架依赖
|
||||
- **WebRTC API**：浏览器P2P通信
|
||||
- **Tailwind CSS**：现代化UI样式
|
||||
- **模块化设计**：分离的JS文件结构
|
||||
|
||||
### 基础设施
|
||||
- **Docker支持**：容器化部署
|
||||
- **Nginx代理**：生产环境反向代理
|
||||
- **STUN服务器**：NAT穿透支持
|
||||
|
||||
## 📁 项目结构
|
||||
|
||||
```
|
||||
chuan/
|
||||
├── cmd/
|
||||
│ └── main.go # 程序入口
|
||||
├── internal/
|
||||
│ ├── handlers/
|
||||
│ │ └── handlers.go # HTTP请求处理
|
||||
│ ├── models/
|
||||
│ │ └── models.go # 数据模型定义
|
||||
│ └── services/
|
||||
│ ├── file_service.go # 文件服务（预留）
|
||||
│ ├── memory_store.go # 内存存储
|
||||
│ ├── p2p_service.go # P2P连接管理
|
||||
│ └── webrtc_service.go # WebRTC服务（预留）
|
||||
├── web/
|
||||
│ ├── static/
|
||||
│ │ ├── css/
|
||||
│ │ │ └── style.css # 样式文件
|
||||
│ │ └── js/
|
||||
│ │ ├── common.js # 通用工具函数
|
||||
│ │ ├── p2p-transfer.js # P2P传输核心逻辑
|
||||
│ │ ├── webrtc-connection.js # WebRTC连接管理
|
||||
│ │ └── file-transfer.js # 文件传输处理
|
||||
│ └── templates/
|
||||
│ ├── base.html # 基础模板
|
||||
│ ├── index.html # 主页面
|
||||
│ ├── upload.html # 上传页面（预留）
|
||||
│ └── video.html # 视频传输页面
|
||||
├── uploads/ # 上传目录（预留）
|
||||
├── bin/
|
||||
│ └── chuan # 编译后的可执行文件
|
||||
├── docker-compose.yml # Docker Compose配置
|
||||
├── Dockerfile # Docker镜像构建
|
||||
├── nginx.conf # Nginx配置
|
||||
├── Makefile # 构建脚本
|
||||
├── deploy.sh # 部署脚本
|
||||
├── go.mod # Go模块定义
|
||||
├── go.sum # Go模块校验
|
||||
└── README.md # 项目文档
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 本地开发
|
||||
|
||||
1. **克隆项目**
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd chuan
|
||||
```
|
||||
|
||||
2. **安装依赖**
|
||||
```bash
|
||||
go mod tidy
|
||||
```
|
||||
|
||||
3. **启动服务**
|
||||
```bash
|
||||
go run cmd/main.go
|
||||
```
|
||||
|
||||
4. **访问应用**
|
||||
```
|
||||
打开浏览器访问: http://localhost:8080
|
||||
```
|
||||
|
||||
### 使用Make命令
|
||||
|
||||
```bash
|
||||
# 运行开发服务器
|
||||
make run
|
||||
|
||||
# 构建可执行文件
|
||||
make build
|
||||
|
||||
# 清理构建文件
|
||||
make clean
|
||||
|
||||
# 运行测试
|
||||
make test
|
||||
```
|
||||
|
||||
### Docker部署
|
||||
|
||||
1. **构建镜像**
|
||||
```bash
|
||||
docker build -t chuan .
|
||||
```
|
||||
|
||||
2. **运行容器**
|
||||
```bash
|
||||
docker run -p 8080:8080 chuan
|
||||
```
|
||||
|
||||
3. **使用Docker Compose**
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## 📖 使用说明
|
||||
|
||||
### 发送文件
|
||||
|
||||
1. 访问主页面
|
||||
2. 点击选择文件或拖拽文件到上传区域
|
||||
3. 点击"生成取件码"按钮
|
||||
4. 分享6位取件码给接收方
|
||||
5. 等待接收方连接并开始传输
|
||||
|
||||
### 接收文件
|
||||
|
||||
1. 访问主页面
|
||||
2. 在"输入取件码"区域输入6位取件码
|
||||
3. 系统自动连接并显示文件列表
|
||||
4. 等待P2P连接建立（显示绿色状态）
|
||||
5. 点击"下载"按钮开始接收文件
|
||||
|
||||
### 传输状态说明
|
||||
|
||||
- 🟡 **等待连接**：正在建立WebSocket连接
|
||||
- 🟢 **P2P已连接**：可以开始文件传输
|
||||
- 🔴 **连接失败**：请检查网络或重试
|
||||
|
||||
## ⚙️ 配置说明
|
||||
|
||||
### 环境变量
|
||||
|
||||
- `PORT`：服务器端口（默认8080）
|
||||
- `HOST`：服务器主机（默认localhost）
|
||||
|
||||
### STUN服务器配置
|
||||
|
||||
系统默认使用以下STUN服务器（按优先级）：
|
||||
|
||||
1. `stun:stun.chat.bilibili.com:3478` - 哔哩哔哩
|
||||
2. `stun:stun.voipbuster.com` - VoIP服务
|
||||
3. `stun:stun.voipstunt.com` - VoIP服务
|
||||
4. `stun:stun.qq.com:3478` - 腾讯QQ
|
||||
5. `stun:stun.l.google.com:19302` - Google（备用）
|
||||
|
||||
## 🔧 高级配置
|
||||
|
||||
### 传输参数优化
|
||||
|
||||
在 `file-transfer.js` 中可调整以下参数：
|
||||
|
||||
```javascript
|
||||
const chunkSize = 65536; // 分块大小（64KB）
|
||||
const transmissionDelay = 1; // 传输间隔（1ms）
|
||||
const maxRetransmits = 3; // 最大重传次数
|
||||
const maxPacketLifeTime = 3000; // 数据包最大生存时间
|
||||
```
|
||||
|
||||
### 连接超时设置
|
||||
|
||||
在 `webrtc-connection.js` 中可调整：
|
||||
|
||||
```javascript
|
||||
const connectionTimeout = 60000; // 连接超时（60秒）
|
||||
```
|
||||
|
||||
## 🐛 故障排除
|
||||
|
||||
### 常见问题
|
||||
|
||||
1. **P2P连接失败**
|
||||
- 检查防火墙设置
|
||||
- 确认浏览器支持WebRTC
|
||||
- 尝试使用不同的STUN服务器
|
||||
|
||||
2. **文件传输中断**
|
||||
- 检查网络连接稳定性
|
||||
- 避免浏览器标签页切换到后台
|
||||
- 大文件传输建议分批进行
|
||||
|
||||
3. **取件码无效**
|
||||
- 确认取件码输入正确（6位大写字母数字）
|
||||
- 检查房间是否已过期（默认1小时）
|
||||
- 确认发送方仍在线
|
||||
|
||||
### 调试模式
|
||||
|
||||
打开浏览器开发者工具（F12），查看Console标签页获取详细日志信息。
|
||||
|
||||
## 🚀 生产部署
|
||||
|
||||
### Nginx配置
|
||||
|
||||
```nginx
|
||||
server {
|
||||
listen 80;
|
||||
server_name your-domain.com;
|
||||
|
||||
location / {
|
||||
proxy_pass http://localhost:8080;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection 'upgrade';
|
||||
proxy_set_header Host $host;
|
||||
proxy_cache_bypass $http_upgrade;
|
||||
proxy_set_header X-Real-IP $remote_addr;
|
||||
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
|
||||
proxy_set_header X-Forwarded-Proto $scheme;
|
||||
}
|
||||
|
||||
location /ws {
|
||||
proxy_pass http://localhost:8080;
|
||||
proxy_http_version 1.1;
|
||||
proxy_set_header Upgrade $http_upgrade;
|
||||
proxy_set_header Connection "Upgrade";
|
||||
proxy_set_header Host $host;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### systemd服务
|
||||
|
||||
创建 `/etc/systemd/system/chuan.service`：
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Chuan P2P File Transfer Service
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=www-data
|
||||
WorkingDirectory=/opt/chuan
|
||||
ExecStart=/opt/chuan/bin/chuan
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
启动服务：
|
||||
```bash
|
||||
sudo systemctl enable chuan
|
||||
sudo systemctl start chuan
|
||||
```
|
||||
|
||||
## 🤝 贡献指南
|
||||
|
||||
1. Fork 项目
|
||||
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
|
||||
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
|
||||
4. 推送到分支 (`git push origin feature/AmazingFeature`)
|
||||
5. 开启 Pull Request
|
||||
|
||||
## 📝 开发计划
|
||||
|
||||
### v1.1 计划功能
|
||||
- [ ] 文件传输加密增强
|
||||
- [ ] 传输速度优化
|
||||
- [ ] 移动端适配改进
|
||||
- [ ] 批量文件操作
|
||||
|
||||
### v1.2 计划功能
|
||||
- [ ] 用户认证系统
|
||||
- [ ] 传输历史记录
|
||||
- [ ] 文件预览功能
|
||||
- [ ] API接口开放
|
||||
|
||||
### v2.0 计划功能
|
||||
- [ ] 视频通话功能完善
|
||||
- [ ] 屏幕共享支持
|
||||
- [ ] 多人会议室
|
||||
- [ ] 云存储集成
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
- [WebRTC](https://webrtc.org/) - 实时通信技术
|
||||
- [Go](https://golang.org/) - 后端开发语言
|
||||
- [Tailwind CSS](https://tailwindcss.com/) - UI样式框架
|
||||
- [Chi Router](https://go-chi.io/) - Go HTTP路由库
|
||||
|
||||
## 📞 联系方式
|
||||
|
||||
- 项目主页：[GitHub Repository]
|
||||
- 问题反馈：[GitHub Issues]
|
||||
|
||||
---
|
||||
|
||||
⭐ 如果这个项目对你有帮助，请给它一个星标！
|
||||
Reference in New Issue
Block a user