FileSync

FileSync 是一款基于 WebRTC 技术的开源文件传输工具，旨在实现从一台设备向多台设备实时、安全地发送文件。其核心理念是“服务器只负责握手，数据直接流通”，确保用户隐私的同时打破文件大小和网络环境的限制。

核心功能亮点

1. 极致隐私 (Private)
   • 文件通过加密的 WebRTC 通道直接在浏览器之间传输。
   • 信令服务器仅用于交换连接信息（SDP/ICE），永远看不到或存储您的文件内容。
2. 任意文件大小 (Any Size)
   • 采用流式写入技术，文件到达时直接写入磁盘，而非加载到内存。
   • 无论传输几 MB 还是几 GB 的文件，内存占用始终保持平稳，不会导致浏览器崩溃。
3. 自动恢复 (Auto-Resume)
   • 支持断点续传。如果网络中断，重新连接后会自动从停止的地方继续传输，无需从头开始。
4. 一对多分享 (One-to-Many)
   • 生成房间链接或二维码，即可同时向多台设备发送文件。适合会议分享、家庭多设备同步等场景。
5. 跨网络穿透
   • 优先尝试 P2P 直连以获得最快速度。
   • 若受 NAT 或防火墙限制，自动通过 TURN 服务器中继，确保连接成功率。
6. 零安装、零账户
   • 接收者只需打开链接即可接收，无需注册账号或安装客户端。
   • 支持设置房间密码，保护分享链接的安全性。

自托管指南 (Docker)

FileSync 提供单个 Docker 镜像，部署极其简单。

前提条件

• Docker
• Docker Compose

选项 A：HTTP 模式（仅限本地测试）

⚠️ 注意：HTTP 模式下无法使用高级流式保存 API，大文件可能会缓冲在内存中。不推荐生产环境使用。

1. 下载 deploy/docker-compose.yml。
2. 启动服务：

   docker compose up -d
   

3. 访问 http://localhost。

选项 B：HTTPS 模式（推荐，支持域名）

✅ 优势：启用 HTTPS 后，浏览器可使用 File System Access API，实现真正的大文件流式写入，内存更省，速度更快。

1. 下载 deploy/docker-compose-ssl.yml 和 deploy/Caddyfile。
2. 编辑 Caddyfile，将第一行的 yourdomain.com 替换为你的真实域名。
3. 启动服务：

   docker compose -f docker-compose-ssl.yml up -d
   

4. 访问 https://yourdomain.com。Caddy 会自动处理 SSL 证书申请。

端口与防火墙配置

为了确保 P2P 连接和中继正常工作，需在服务器防火墙开放以下端口：

注：50000–50100 范围主要服务于位于对称 NAT 或严格防火墙后的用户。

技术原理：它是如何工作的？

1. 信令阶段：
   • 用户 A 和用户 B 连接到 FileSync 服务器的 WebSocket (/ws)。
   • 服务器协助交换 SDP（会话描述协议）和 ICE 候选者，帮助双方找到彼此的网络路径。
2. 数据传输阶段：
   • 一旦 P2P 连接建立，文件字节流直接在浏览器之间流动，服务器完全退出数据路径。
   • 若直连失败，数据会通过配置的 TURN 服务器中继，但仍保持加密。
3. 接收端保存策略：
   FileSync 智能选择最佳的保存方式：
   1. File System Access API (首选)：允许用户选择保存位置并流式写入。仅限 HTTPS 下的桌面 Chromium 内核浏览器。
   2. Service Worker：拦截下载请求并流式写入。适用于所有现代 HTTPS 浏览器。
   3. Blob (最后手段)：将整个文件缓冲在内存中再保存。仅在 HTTP 环境下或旧浏览器中使用，因此强烈建议使用 HTTPS。