-
Notifications
You must be signed in to change notification settings - Fork 0
Home
Lisselde_E edited this page Sep 24, 2026
·
3 revisions
局域网文件实时同步工具：多台设备在同一局域网内，实现目录实时同步、剪贴板互通与文件投递，数据端到端直连，不经过任何中转服务器。
- 产品介绍与下载入口，请见仓库 README。
- 本文档为项目 Wiki，按用途分为「使用手册」与「开发者」两部分。
本仓库同时包含两个版本：标准版 与 Pro（增强版），两版的同步逻辑不同。
- 标准版：采用中心化同步，文件数据经主机转发；提供基础目录双向同步、实时增量与断点续传。主机离线期间无法继续同步。
- Pro：采用去中心化端到端直连（mesh），文件数据不经主机转发；在同步之上提供投递、收集模式与权限管理。主机离线仅影响房间管理，设备间数据面直连不受影响。
| 功能 | 标准版 | Pro |
|---|---|---|
| 基础目录双向同步 | ✓ | ✓ |
| 实时增量 · 断点续传 | ✓ | ✓ |
| 端到端去中心化直连 | — | ✓ |
| 跨设备复制投递 | — | ✓ |
| 收集模式 | — | ✓ |
| 权限管理 | — | ✓ |
| 多平台支持 | Windows / Linux | Windows / Linux |
涉及版本差异的操作说明（如投递、收集模式、权限）会在对应页面标注适用版本。
注意：两版采用完全不同的房间验证逻辑，无法加入同一个房间互通，同一房间内的设备需使用同一版本。
| 页面 | 内容 |
|---|---|
| 快速上手 | 安装、创建房间、加入房间、同步目录与首次同步 |
| 常见问题 FAQ | 高频疑问的解答 |
| 疑难排查 | 多端不同步、文件异常、主机离线、网络分区等问题的排查方法 |
| 投递与收集 | 跨设备复制粘贴、收集模式与读写权限的使用说明 |
| 断点续传 | 传输中断的恢复机制与临时文件说明 |
| 页面 | 内容 |
|---|---|
| 技术栈 | 语言、UI、网络、平台与许可 |
| 架构说明 | 管理面与数据面的双平面设计 |
| 同步逻辑 | 冲突仲裁、版本化拉取槽、字节裁决、删除墓碑与对账兜底 |
| 协议文档 | 控制帧与文件传输帧定义 |
- 主机离线时的行为：因两版同步逻辑不同而存在差异——标准版数据经主机转发，主机离线期间无法继续同步；Pro 的连接端进入静默待机（每 10 秒回探主机），数据面 mesh 直连不受影响，并保持主机最后下发的只读权限。
- 多端同时修改同一文件（Pro）：依据版本向量、逻辑时钟、时间戳、设备标识四层仲裁，最终收敛一致，不丢不重。
- 投递显示「已取消」：接收端主动取消属于显式握手，为正常行为，并非网络故障。
- 已删除文件在其他设备复活（Pro）：删除操作采用墓碑裁决，不会被对账流程重新拉取。
- 同步中断后的恢复：保留临时文件并携带偏移量重连续传（最多 3 次），无需从头开始。
- 加入房间被拒绝：通常为同步逻辑版本号不匹配所致，请升级至最新版本。
详细解答见 常见问题 FAQ。
| 项 | 内容 |
|---|---|
| 语言 | Python 3 |
| UI | PySide6（Qt） |
| 网络 | 原生 socket，全异步（async/await）；数据面为全 mesh 端到端 TCP 直连，管理面以主机为中心 |
| 传输 | 自研协议，分块流式传输并支持断点续传；文件数据端到端直传，不经主机转发 |
| 平台 | Windows / Linux |
| 许可 | GNU GPL v3，免费开源 |
A real-time LAN file synchronization tool. Devices on the same local network can keep folders in sync, share clipboard content, and deliver files to one another, with data transferred directly end-to-end, never through a relay server.
- For the product introduction and download links, see the repository README.
- This documentation is the project Wiki, organized into two parts: "User Guide" and "Developer".
This repository contains two editions: Standard and Pro (enhanced). The sync logic of the two editions differs.
- Standard: centralized sync — file data is forwarded through the host; provides basic two-way folder sync, real-time incremental sync, and breakpoint resume. Syncing cannot continue while the host is offline.
- Pro: decentralized end-to-end direct connections (mesh) — file data never goes through the host; on top of syncing it provides delivery, collection mode, and permission control. A host outage only affects room management; direct data-plane links between devices are unaffected.
| Feature | Standard | Pro |
|---|---|---|
| Basic two-way folder sync | ✓ | ✓ |
| Real-time incremental · resume | ✓ | ✓ |
| End-to-end direct connection | — | ✓ |
| Cross-device copy & paste | — | ✓ |
| Collection mode | — | ✓ |
| Permission control | — | ✓ |
| Multi-platform | Windows / Linux | Windows / Linux |
Instructions that differ between editions (delivery, collection mode, permissions) are marked with the applicable edition on their respective pages.
Note: the two editions use completely different room-verification logic and cannot join the same room to interoperate; devices in the same room must run the same edition.
| Page | Content |
|---|---|
| Getting Started | Installation, creating a room, joining a room, the sync folder, and first sync |
| FAQ | Answers to frequently asked questions |
| Troubleshooting | Resolving out-of-sync ends, file anomalies, host offline, and network partitions |
| Delivery & Collection | Cross-device copy and paste, collection mode, and permission control |
| Resume | Recovery from interrupted transfers and temporary-file notes |
| Page | Content |
|---|---|
| Tech Stack | Language, UI, network, platforms, and license |
| Architecture | Dual-plane design: management plane and data plane |
| Sync Logic | Conflict arbitration, versioned pull slots, byte arbitration, tombstones, and reconcile fallback |
| Protocol | Control frames and file-transfer frame definitions |
- Behavior when the host is offline: this differs between the two editions — Standard forwards data through the host, so syncing cannot continue while the host is offline; Pro connected ends enter silent standby (probing the host every 10 seconds), data-plane mesh links stay unaffected, and they keep the read-only permission last issued by the host.
- Multiple devices modify the same file (Pro): arbitration runs through version vectors, logical clocks, timestamps, and device identifiers; the state converges without loss or duplication.
- Delivery shows "Cancelled": an explicit cancellation by the receiver is normal behavior, not a network failure.
- A deleted file resurrects on other devices (Pro): deletions are handled with tombstones and are never pulled back by reconciliation.
- Recovery from an interrupted sync: the temporary file is kept and transfer resumes with an offset (up to 3 attempts), without starting over.
- Join requests are rejected: usually caused by a mismatch in the sync logic version; please upgrade to the latest release.
See the FAQ for detailed answers.
| Item | Value |
|---|---|
| Language | Python 3 |
| UI | PySide6 (Qt) |
| Network | Raw sockets, fully asynchronous (async/await); full-mesh end-to-end TCP data plane with a host-centered management plane |
| Transfer | Custom protocol with chunked streaming and resume; file data flows directly end-to-end, never through the host |
| Platforms | Windows / Linux |
| License | GNU GPL v3, free and open source |