Spacedrive

A file manager built on a virtual distributed filesystem
spacedrive.com · v2 Documentation · Discord

Spacedrive 是一个开源跨平台文件管理器，由 Rust 编写的虚拟分布式文件系统 (VDFS) 驱动。 在单一界面中组织跨设备、云端和平台的文件。一次标记，随处访问。不再为文件位置而烦恼。 ## 问题所在 计算机设计之初是针对单设备世界的。我们今天使用的文件管理器——Finder、Explorer、Files——构建于您的数据仅存于一点的时代：您面前的电脑。 向多设备计算的转变迫使我们进入云生态系统。想要文件随处可用？上传到别人的服务器上。这种便利是有代价的：**数据所有权**。这并非偶然——中心化是实现多设备同步阻力最小的路径。 现在 AI 正在加速这一趋势。云服务提供智能文件分析和语义搜索，但前提是您必须将数据上传到它们的基础设施。随着我们生成的数据日益增加，以及 AI 能力的不断增强，为了获得基本的计算便利，我们正在让渡越来越多的权益。 **现行体系并非为以下世界而构建：** - 您拥有计算和存储资源未充分利用的多种设备 - 本地 AI 模型正变得可与云端替代方案相媲美 - 隐私和数据主权至关重要 - 您不应在便利性和控制权之间做选择 ## 愿景 Spacedrive 是面向下一个计算时代的基础设施。这是一种为多设备环境从头设计的架构——而非修补了离线支持的云服务，而是可以在您需要时扩展到云端的本地优先同步。 随着本地 AI 模型的改进，Spacedrive 将成为能够提供云服务如今所具备的洞察能力的基础架构，但在您已有的硬件上运行，处理从未离开您控制的数据。这是一个长期项目，旨在纠正计算走向中心化的轨迹。 文件浏览器界面是经过深思熟虑的。每个人都懂它。它是几十年来创新最少的领域。而当您将分布式计算、内容感知和本地 AI 融入这一普世皆知的工具时，它拥有最大的潜力。 ## 运作原理 Spacedrive 将文件视为**具有内容标识的第一类对象**，而非路径。您笔记本上的一张照片和 NAS 上的同一张照片会被识别为同一内容。这使得以下功能成为可能： - **内容感知去重** - 跨所有设备追踪冗余 - **语义搜索** - 在数百万条目中毫秒级（100ms 内）找到文件 - **事务性操作** - 在执行前预览冲突、空间节省和结果 - **点对点同步** - 无服务器、无共识协议、无单点故障 - **离线优先** - 无需互联网即可全功能运行，设备重连时同步 文件保留在原地。Spacedrive 只是让它们变得全局可寻址，并赋予丰富的元数据和跨设备智能。 ## 架构 Spacedrive 基于四个核心原则构建： ### 1. 虚拟分布式文件系统 (VDFS) 文件和文件夹成为具有丰富元数据的第一类对象，独立于其物理位置。每个文件获得一个跨设备工作的全局地址 (`SdPath`)。内容感知寻址意味着您可以根据文件包含的内容来引用它们，而不仅仅是它们存储的位置。 ### 2. 内容身份系统 自适应哈希（针对大文件使用 BLAKE3 进行策略性采样）为每段内容创建唯一的指纹。这使得以下功能成为可能： - **去重**：识别跨设备的相同文件 - **冗余追踪**：了解您的备份位置 - **基于内容的操作**：“从任何可用位置复制此文件” ### 3. 事务性操作 每个文件操作在执行前均可预览。查看将会发生的确切情况——空间节省、冲突、预计时间——然后批准或取消。操作成为可经受网络中断和设备重启的持久化作业。 ### 4. 无主同步 无中心协调者的点对点同步。设备特定数据（您的文件系统索引）使用状态复制。共享元数据（标签、评分）使用具有确定性冲突解决的轻量级 HLC 有序日志。无领导者选举，无单点故障。 ## 核心功能 | 功能 | 描述 | | ----------------------- | ---------------------------------------------------------------------------- | | **跨平台** | macOS, Windows, Linux, iOS, Android | | **多设备索引** | 统一查看所有设备上的文件 | | **内容寻址** | 自动查找最佳文件副本（本地优先，然后是局域网，最后是云端） | | **智能去重** | 识别相同文件，无论其名称或位置如何 | | **云集成** | 将 S3, Google Drive, Dropbox 作为第一类卷进行索引 | | **P2P 网络** | 具有自动 NAT 穿透的直接设备连接 (Iroh + QUIC) | | **语义标签** | 基于图谱的标签系统，支持层级、别名和上下文消歧 | | **操作预览** | 在执行前模拟任何操作 | | **离线优先** | 无需互联网即可全功能运行，设备重连时同步 | | **本地备份** | 您自己设备间的 P2P 备份（iOS 照片备份现已提供） | | **扩展系统** | 基于特定领域功能的 WASM 插件 | ## 技术栈 **核心** - **Rust** - 整个 VDFS 实现（约 18.3 万行代码） - **Tokio** - 异步运行时 - **SQLite + SeaORM** - 本地优先数据库，支持类型安全的 ORM 查询 - **Iroh** - 基于 QUIC 传输的 P2P 网络，支持打洞和本地发现 - **BLAKE3** - 用于内容身份的快速加密哈希 - **Wasmer** - 沙箱化的 WASM 扩展运行时 - **Axum** - 用于 Web 和 API 访问的 HTTP/GraphQL 服务器 - **OpenDAL** - 统一云存储抽象 (S3, Google Drive, OneDrive, Dropbox, Azure Blob, GCS) - **Specta** - 从 Rust 自动生成 TypeScript 和 Swift 类型 **加密与安全** - **Ed25519 / X25519** - 签名和密钥交换 - **ChaCha20-Poly1305 / AES-GCM** - 认证加密 - **Argon2** - 密码哈希 - **BIP39** - 用于密钥备份的助记词支持 - **redb** - 用于凭证的加密键值存储 **媒体处理** - **FFmpeg**（通过自定义 `sd-ffmpeg` crate）- 视频缩略图、音频提取 - **libheif** - HEIF/HEIC 图像支持 - **Pdfium** - PDF 渲染 - **Whisper** - 设备端语音识别（Apple 平台使用 Metal 加速） - **Blurhash** - 紧凑图像占位符 **界面**（Web 和桌面端共享） - **React 19** - UI 框架 - **Vite** - 构建工具 - **TypeScript** - 类型安全的前端代码 - **TanStack Query** - 服务器状态管理 - **Zustand** - 客户端状态管理 - **Radix UI** - 无障碍无头组件 - **Tailwind CSS** - 实用优先的样式方案 - **Framer Motion** - 动画 - **React Hook Form + Zod** - 表单管理和验证 - **Three.js / React Three Fiber** - 3D 可视化 - **dnd-kit** - 拖放 - **TanStack Virtual / TanStack Table** - 虚拟化列表和表格 **桌面端** - **Tauri 2** - 跨平台桌面外壳 **移动端** - **React Native** 0.81 + **Expo** - 跨平台移动框架 - **Expo Router** - 基于文件的路由 - **NativeWind** - React Native 的 Tailwind CSS - **React Navigation** - 原生导航堆栈 - **Reanimated** - 原生线程动画 - **sd-mobile-core** - 通过 FFI 的 Rust 核心桥接 **架构模式** - 具有集中式 EventBus 的事件驱动设计 - CQRS：具有预览-提交-验证机制的操作（变更）和查询（读取） - 使用 MessagePack 序列化和检查点的持久化作业 - 具有清晰数据所有权边界的域分离同步 - 通过 `inventory` crate 进行的编译时操作注册 ## 项目结构 ``` spacedrive/ ├── core/ # Rust VDFS implementation │ ├── src/ │ │ ├── domain/ # Core models (Entry, Library, Device, Tag, Volume) │ │ ├── ops/ # CQRS operations (actions & queries) │ │ ├── infra/ # Infrastructure (DB, events, jobs, sync) │ │ ├── service/ # High-level services (network, file sharing, sync) │ │ ├── crypto/ # Key management and encryption │ │ ├── device/ # Device identity and configuration │ │ ├── filetype/ # File type detection and registry │ │ ├── location/ # Location management and indexing │ │ ├── library/ # Library lifecycle and operations │ │ └── volume/ # Volume detection and fingerprinting │ └── tests/ # Integration tests (pairing, sync, file transfer) ├── apps/ │ ├── cli/ # CLI and daemon entry point │ ├── server/ # Headless server for Docker/self-hosting │ ├── tauri/ # Desktop app shell (macOS, Windows, Linux) │ ├── web/ # Web app (Vite, connects to daemon via WebSocket) │ ├── mobile/ # React Native mobile app (Expo) │ ├── api/ # Cloud API server (Bun + Elysia) │ ├── landing/ # Marketing site and docs (Next.js) │ ├── ios/ # Native iOS prototype (Swift) │ ├── macos/ # Native macOS prototype (Swift) │ └── gpui-photo-grid/ # GPUI media viewer prototype ├── packages/ │ ├── interface/ # Shared React UI (used by web and desktop) │ ├── ts-client/ # Auto-generated TypeScript client and hooks │ ├── swift-client/ # Auto-generated Swift client │ ├── ui/ # Shared component library │ └── assets/ # Icons and images ├── crates/ │ ├── crypto/ # Cryptographic primitives │ ├── ffmpeg/ # FFmpeg bindings for video/audio │ ├── images/ # Image processing (HEIF, PDF, SVG) │ ├── media-metadata/ # EXIF/media metadata extraction │ ├── fs-watcher/ # Cross-platform file system watcher │ ├── sdk/ # WASM extension SDK │ ├── sdk-macros/ # Extension procedural macros │ ├── task-system/ # Durable job execution engine │ ├── sd-client/ # Rust client library │ └── ... # actors, fda, log-analyzer, utils ├── extensions/ # WASM extensions (photos, test-extension) └── docs/ # Architecture documentation ``` ## 扩展 Spacedrive 基于 WASM 的扩展系统在保持安全性和可移植性的同时，实现了专业化的功能。 ### 专业扩展 | 扩展 | 用途 | 主要功能 | 状态 | | ------------- | ------------------------------- | --------------------------------------------------------------------------- | ----------- | | **Photos** | AI 驱动的照片管理 | 人脸识别、地点识别、时刻、场景分类 | 开发中 | | **Chronicle** | 研究与知识管理 | 文档分析、知识图谱、AI 摘要 | 开发中 | | **Atlas** | 动态 CRM 与团队知识 | 运行时模式、联系人跟踪、交易管道 | 开发中 | | **Studio** | 数字资产管理 | 场景检测、转录、代理生成 | 计划中 | | **Ledger** | 财务智能 | 收据 OCR、费用跟踪、税务准备 | 计划中 | | **Guardian** | 备份与冗余监控 | 内容身份跟踪、零冗余警报、智能备份建议 | 计划中 | | **Cipher** | 安全与加密 | 密码管理器、文件加密、泄露警报 | 计划中 | ### 开源存档扩展 | 扩展 | 用途 | 提供数据给 | 状态 | | ------------------- | ----------------------- | ------------------------ | ------- | | **Email Archive** | Gmail/Outlook 备份 | Atlas, Ledger, Chronicle | 计划中 | | **Chrome History** | 浏览历史备份 | Chronicle | 计划中 | | **Spotify Archive** | 收听历史 | Analytics | 计划中 | | **GPS Tracker** | 位置时间线 | Photos, Analytics | 计划中 | | **Tweet Archive** | Twitter 备份 | Chronicle, Analytics | 计划中 | | **GitHub Tracker** | 仓库跟踪 | Chronicle | 计划中 | ## 入门指南 ### 前置条件 - **Rust** 1.81+ ([rustup](https://rustup.rs/)) - **Bun** 1.3+ ([bun.sh](https://bun.sh)) - 用于 Tauri 桌面应用 ### 桌面应用 快速开始 Spacedrive 作为守护进程 (`sd-daemon`) 运行，管理您的库和 P2P 连接。Tauri 桌面应用可以启动自己的守护进程实例，或连接到由 CLI 启动的守护进程。 ``` # 克隆 repository git clone https://github.com/spacedriveapp/spacedrive cd spacedrive # 安装 dependencies bun install cargo run -p xtask -- setup # generates .cargo/config.toml with aliases cargo build # builds all core and apps (including the daemon and cli) # 复制 dependencies 到 debug 文件夹 ( 可能仅限 windows ) Copy-Item -Path "apps\.deps\lib\*.dll" -Destination "target\debug" -ErrorAction SilentlyContinue Copy-Item -Path "apps\.deps\bin\*.dll" -Destination "target\debug" -ErrorAction SilentlyContinue # 运行 desktop app (自动启动 daemon) cd apps/tauri bun run tauri:dev ``` ### CLI 快速开始 CLI 可以管理库并运行其他应用连接到的持久化守护进程： ``` # 构建并运行 CLI cargo run -p sd-cli -- --help # 启动 daemon (在后台运行) cargo run -p sd-cli -- daemon start # 创建一个 library cargo run -p sd-cli -- library create "My Library" # 添加一个 location 到 index cargo run -p sd-cli -- location add ~/Documents # 搜索 indexed 文件 cargo run -p sd-cli -- search . # 现在启动 Tauri app - 它将连接到正在运行的 daemon ``` ### 运行测试 Spacedrive 拥有全面的测试套件，涵盖单设备操作和多设备网络场景。 ``` # 运行所有 tests cargo test --workspace # 运行指定 test cargo test test_device_pairing --nocapture # 运行并显示详细 logging RUST_LOG=debug cargo test test_name --nocapture # 仅运行 core tests cargo test -p sd-core ``` 请参阅 [测试指南](https://v2.spacedrive.com/core/testing) 获取以下方面的详细文档： - 集成测试框架 - 多设备子进程测试 - 事件监控模式 - 测试辅助工具和实用程序 所有集成测试均位于 `core/tests/` 中，包括设备配对、同步、文件传输和作业执行测试。 ### 开发命令 ``` # 运行所有 tests cargo test # 运行指定 package 的 tests cargo test -p sd-core # 以 release mode 构建 CLI cargo build -p sd-cli --release # 格式化代码 cargo fmt # 运行 lints cargo clippy ``` ## 隐私与安全 Spacedrive 是**本地优先**的。您的数据留在您的设备上。 - **端到端加密**：所有 P2P 流量通过 QUIC/TLS 加密 - **静态加密**：库可在磁盘上加密 - **无遥测**：开源版本中零跟踪或分析 - **可自托管**：运行您自己的中继服务器和云核心 - **数据主权**：您控制数据的存储位置 可选的云集成 适用于备份和远程访问，但这绝非强制。云服务运行未经修改的 Spacedrive 核心作为标准 P2P 设备——无特殊权限，无自定义 API。 ## 文档 - **[v2 文档](https://v2.spacedrive.com)** - 完整指南和 API 参考 - **[自托管指南](https://v2.spacedrive.com/overview/self-hosting)** - 部署 Spacedrive 服务器 - **[白皮书](whitepaper/spacedrive.pdf)** - 技术架构（编写中） - **[贡献指南](CONTRIBUTING.md)** - 如何贡献 - **[架构文档](docs/core/architecture.md)** - 详细的系统设计 - **[扩展 SDK](docs/sdk.md)** - 构建您自己的扩展 ## 参与其中 - **Star 本仓库**以支持项目 - **加入 [Discord](https://discord.gg/gTaF2Z44f5)** 与开发者和社区交流 - **阅读 [v2 文档](https://v2.spacedrive.com)** 获取指南和 API 参考 - **阅读 [白皮书](whitepaper/spacedrive.pdf)** 了解完整的技术愿景 - **构建扩展** - 查看 [SDK 文档](docs/sdk.md)

标签：HTTP工具, Prisma, Rust, Spacedrive, Tauri, VDFS, WASM, WebAssembly, 个人云, 云存储, 去中心化, 可视化界面, 同步工具, 多设备同步, 开源, 效率工具, 数据所有权, 数据管理, 文件标签, 文件管理器, 文件组织, 网络安全, 网络流量审计, 虚拟分布式文件系统, 资源管理器, 通知系统, 隐私保护