Spacedrive Virtual Sidecar SystemVSS深入解析在 VDFS 中以一级可寻址文件管理派生数据【免费下载链接】spacedriveSpacedrive is an open source cross-platform file explorer, powered by a virtual distributed filesystem written in Rust.项目地址: https://gitcode.com/gh_mirrors/sp/spacedriveVirtual Sidecar SystemVSS是 Spacedrive 中管理文件派生数据缩略图、OCR 文本、视频字幕/转写、向量嵌入与 Agent 生成的情报的核心基础设施。本篇文章以任务规格 CORE-008 与用户文档 docs/core/virtual-sidecars.mdx 为骨架结合SidecarManager、SdPath::Sidecar、确定性路径分片与跨设备同步等源码实现完整还原 VSS 的设计原理、数据库模式、生命周期、统一寻址方案与实施路线图读完即可掌握 VSS 的存储布局、API 用法、同步机制及当前实现边界。VSS 是什么为内容而非路径服务的派生数据层传统文件管理器把缩略图、元数据等派生数据散落在缓存目录中与文件路径强绑定文件一旦移动或重命名缓存即失效。VSS 反其道而行——它把派生数据视为与内容content一一对应的可寻址实体并纳入 Spacedrive 的虚拟分布式文件系统VDFS作为第一类对象处理。按任务规格 CORE-008 的定义VSS 负责管理五类派生数据缩略图thumbnails图片/视频的 WebP 预览图OCR 文本从文档中提取的文字内容JSON视频转写与字幕transcripts/subtitlesSRT 等格式嵌入向量embeddings供语义搜索使用的结构化向量数据Agent 生成的情报由智能 Agent 对文件内容分析后产生的衍生信息。V2 设计中sidecar 被集成为原生SdPath::Sidecar枚举变体见 core/src/domain/addressing.rs 第 49-59 行从而获得统一寻址、标准文件操作与跨设备语义——这意味着在 VDFS 的寻址体系里sidecar 与物理文件、云端对象、内容句柄一样是一等公民。三大设计原则用户文档virtual-sidecars.mdx明确了 VSS 的核心原则这些原则直接决定了后续的数据模型与路径设计内容作用域Content-Scopedsidecar 绑定的是文件内容而非路径。同一文件的多份拷贝共享同一组 sidecar绝不重复生成。非破坏性Non-Destructive索引与派生过程中Spacedrive 永远不会修改原始文件。可移植Portable所有托管 sidecar 都存放在.sdlibrary/sidecars目录下整个库可以作为一个整体移动或备份。第三点直接体现在 core/src/service/sidecar_manager.rs 的init_library中每个库初始化时都会执行library_path.join(sidecars)并create_dir_all确保目录存在同时为该库注册一个独立的SidecarPathBuilder第 46-80 行。两类 SidecarManaged 与 ReferenceVSS 将 sidecar 区分为两种类型对应两种完全不同的生命周期维度Managed SidecarReference Sidecar来源Spacedrive 后台任务生成用户已存在的文件被认领为 sidecar存储位置.sdlibrary/sidecars/内留在原始位置不移动典型例子缩略图.webp、视频代理.mp4、OCR.json、字幕.srtLive Photo 的视频分量、RAWJPEG 配对数据库标记rel_path指向托管路径source为sidecar_managersource_entry_id指向原文件 entrysource为referencerel_path为空转换—可调用convert_reference_to_owned()转换为托管Reference sidecar 的价值在于跟踪而不移动索引器发现 RAWJPEG 这类成对文件时只需在sidecars表里建立一条指向原文件的引用记录见 create_reference_sidecar文件保持原位。当用户决定纳入托管体系时convert_reference_to_owned 会把文件rename到确定性路径下并清除source_entry_id、将source标记为converted。确定性文件系统布局与两级十六进制分片VSS 的路径是纯确定性计算的不查数据库仅由content_uuid kind variant format四个要素推导验收标准中明确要求 Deterministic paths work without DB queries。用户文档给出的典型布局如下.sdlibrary/ sidecars/ content/ {h0}/{h1}/{content_uuid}/ thumbs/{variant}.webp proxies/{profile}.mp4 transcript/{variant}.srt ocr/default.json{h0}/{h1}内容 UUID 的前两个字节对byte-pair用于目录分片保证海量 sidecar 下的文件系统性能{content_uuid}sidecar 关联内容实体的唯一标识{variant}变体名如grid2x、1080p或嵌入模型名all-MiniLM-L6-v2每个内容目录下按 kind 分子目录thumbs、proxies、embeddings、ocr、transcript文件名统一为{variant}.{扩展名}。这一布局与源码实现完全吻合。SidecarPathBuildercore/src/ops/sidecar/path.rs中compute_shards()第 33-42 行将 UUID 转为无连字符小写十六进制串取前两个字节对作为h0/h1build()第 45-75 行拼接相对路径content/{h0}/{h1}/{uuid}/{kind_dir}/{variant}.{ext}再在库路径下挂接sidecars前缀得到绝对路径build_content_dir()第 78-89 行与build_manifest_path()第 92-96 行分别支持整目录操作与 manifest 清单文件。源码自带单元测试验证了确定性UUIDabcd1234-5678-90ab-cdef-123456789012的(h0, h1)恒为(ab, cd)完整相对路径恒为content/ab/cd/abcd1234-5678-90ab-cdef-123456789012/thumbs/grid2x.webp第 110-141 行。因此任意设备、任意时刻只要知道内容 UUID 与 sidecar 属性就能在不访问数据库的情况下定位或检验文件。数据库模式内容元数据与设备可用性分离VSS 使用两张表用户文档称之为 VSS 的两张表分别承担全局事实与本地事实sidecars内容作用域的全局元数据实体定义见 core/src/infra/db/entities/sidecar.rs字段包括字段含义content_uuid关联的内容 UUID外键指向content_identitieskind/variant/formatsidecar 类型、变体、存储格式rel_path相对路径托管Reference sidecar 为空字符串source_entry_idReference sidecar 指向的原文件 entrysize/checksum文件大小与校验和statuspending/ready/failedsource来源标记sidecar_manager/reference/convertedversion/created_at/updated_at乐观并发与同步版本控制该表实现了Syncabletrait第 77-148 行通过库同步library sync在所有设备间传播exclude_fields()排除本地相关的id与source_entry_idsync_depends_on()声明依赖content_identitysidecar 必须先于内容存在外键映射将content_uuid映射到content_identities表查询采用updated_at uuid游标分页。sidecar_availability仅记录本设备有什么实体定义见 core/src/infra/db/entities/sidecar_availability.rs以(content_uuid, kind, variant, device_uuid)为键记录has、size、checksum、last_seen_at。该表不参与库同步只反映当前设备本地实际拥有的 sidecar。这种设计带来关键的可扩展性任务规格明确给出了规模估算——桌面端同步全部 sidecar 时约 600 万行手机端选择性同步约 10 万行发现对端设备有什么通过网络查询完成而不是通过数据库同步放大。get_presence()sidecar_manager.rs正是这样实现的先查本地sidecars表构建local: true条目再查sidecar_availability中has true的记录把对端设备 UUID 追加到每个条目的devices列表一次性返回完整的本地 远端存在性视图。Sidecar 生命周期从识别到跨设备同步用户文档将生命周期划分为四步这里结合源码逐一对应1. 识别IdentificationManaged索引器在 Intelligence Queueing Phase 排队生成任务在sidecars表写入pending记录Reference索引器创建带source_entry_id的 sidecar 记录。2. 生成GenerationManaged由后台 Job 产出派生文件并写入确定性路径。当前enqueue_generation()sidecar_manager.rs在ffmpegfeature 开启时会为Thumb类型查找对应 entry 并派发ThumbnailJobThumbnailJob::for_entries(vec![entry_uuid], config)经library.jobs().dispatch()执行OCR、转写等类型目前仅记录日志源码中标注 TODOReference无需生成直接进入 ready 状态。3. 记录RecordingManagedJob 完成调用record_sidecar()第 488-611 行以查询已存在记录则 update、否则 insert的 upsert 语义写入sidecars再通过update_local_availability()更新本机sidecar_availability并经由ResourceManager.emit_resource_events(sidecar, ...)发出资源事件bootstrap 期间跳过以避免刷屏Reference创建即 ready。4. 同步Syncing设备间交换可用性信息缺失 sidecar 优先从对端拉取而非本地重新生成详见下文跨设备同步章节。get_or_enqueue()第 213-257 行实现了惰性物化的核心模式状态机为文件系统已存在 → 直接返回SidecarResult::Ready(相对路径)数据库记录为ready→ 返回 Ready记录为pending→ 返回SidecarResult::Pending记录为failed→ 自动重新入队并返回 Pending无记录 → 插入 pending 记录、派发生成任务返回 Pending。调用方无需关心生成细节只需根据返回的 Ready/Pending 决定立即使用或稍后重试。统一寻址SdPath::Sidecar与sidecar://URIV2 设计把 sidecar 提升为寻址体系的一等成员。在 core/src/domain/addressing.rs 中SdPath枚举新增Sidecar变体第 49-59 行由四元组构成Sidecar { content_id: Uuid, // 源内容 kind: SidecarKind, // thumb / thumbstrip / proxy / embeddings / ocr / transcript / gaussian_splat variant: SidecarVariant, // 如 grid2x、1080p、all-MiniLM-L6-v2 format: SidecarFormat, // webp / mp4 / json / msgpack / txt / ply }类型定义见 core/src/ops/sidecar/types.rsSidecarKind枚举 7 种类型并映射到目录名thumbs、thumbstrips、proxies、embeddings、ocr、transcript、gaussian_splatsSidecarFormat给出扩展名与格式选择指南——WebP 用于图片派生、MP4 用于媒体代理、JSON 用于文本型数据、MessagePack 用于向量嵌入源码注释说明其对 384 维向量比 JSON 小约 6 倍、解析快约 10 倍是达成大规模语义搜索时延目标的关键选择。URI 语法为sidecar://{content_uuid}/{kind_dir}/{variant}.{ext}例如sidecar://550e8400-e29b-41d4-a716-446655440000/thumbs/grid2x.webp。from_uri()解析逻辑addressing.rs将 URI 拆分为 content UUID、kind 目录与文件名从文件名反解 variant 与 formatDisplay实现第 253-266 行则把四元组序列化为同一格式的 URI保证解析-显示-再解析闭环。该模块自带多个 URI 解析测试用例含embeddings/all-MiniLM-L6-v2.msgpack、ocr/default.json等。相应地SdPath::Sidecar的parent()与join()被设计为不可用返回None/panic从语义上防止对 sidecar 执行不合理的路径操作。当前 resolve_sidecar() 仍是占位实现返回SidecarNotFound任务规格将其列为后续 VSS 工作项计划支持检查本地文件系统、查询sidecar_availability远端可用性、必要时入队生成并按阻塞/异步/仅拉取等模式返回解析结果。跨设备同步从可用性发现到 P2P 传输VSS 的跨设备同步由SidecarSyncJob驱动这是已实现程度较高的模块任务定义在 core/src/ops/sidecar/sync_job.rsNAME sidecar_syncRESUMABLE true产出SidecarSyncOutputdiscovered / transferred / failed / total_bytes / duration。协调器 core/src/service/sidecar_sync/coordinator.rs 的discover_missing_sidecars()以status ready为前提条件结合 kind / content UUID / max_count 过滤找出数据库里有但本地没有的 sidecarquery_remote_availability()查询对端plan_transfers()为每个缺失项选定源设备。同步过滤器与模式定义在 core/src/service/sidecar_sync/filters.rsSidecarSyncFilterskinds、content_uuids、max_count、cursor格式content_uuid|kind|variant支持分批游标SidecarSyncModePullMissing拉取缺失、PushNew推送新产物、Bidirectional——当前PullMissing已实现另两种为后续扩展。Job 执行流程分为六个阶段sync_job.rs 第 60-245 行Discovery调用协调器发现缺失 sidecarAvailability Query查询对端可用性与校验和Plan Transfers生成SidecarTransferPlansidecar 源设备Prepare确保{library}/sidecars目录存在Execute直接复用RemoteTransferStrategyops::files::copy::strategy逐条执行传输——源路径构造为SdPath::Sidecar { ... }目的路径为物理路径成功后更新本机sidecar_availabilityhas true失败计入 failedcompleted_indices支持断点续传Emit Events通过ResourceManager为成功传输的 sidecar 发送资源事件驱动前端界面刷新。整个流程体现了传输复用现有 P2P 文件传输基础设施、不重新发明轮子的设计取向对应验收标准 Sidecar transfers reuse P2P file transfer infrastructure也印证了缺什么拉什么而不是整库同步的扩展性策略。当前实现状态与六阶段路线图结合任务规格与源码VSS 的实现状态如下已实现基础设施层sidecars/sidecar_availability两张表的 schema 与查询含 Syncable 实现SidecarManager核心服务core/src/service/sidecar_manager.rsCRUD、presence、get-or-enqueue、reference sidecar、bootstrap scan、事件发射确定性路径计算与两级 hex 分片含单元测试本地 远端存在性查询跨设备同步 Job 与协调器SidecarSyncJob/SidecarSyncCoordinatorSdPath::Sidecar变体、sidecar://URI 解析与展示、序列化/反序列化。未实现集成层任务规格明确列出SdPathResolver 的完整 sidecar 解析当前resolve_sidecar为占位Job 系统完整派发enqueue_generation中 OCR/转写等仅记日志sidecars目录的文件系统 watcherstart_watcher()尚为 TODOsidecar 文件校验和计算bootstrap 扫描时checksum传None实际的缩略图/OCR/转写生成任务全集CLI sidecar 命令族。六阶段路线图任务规格 Implementation StepsPhase 1 SdPath 集成SdPath::Sidecar变体、sidecar://解析与展示、解析/展示单测——当前仓库已落地addressing.rsPhase 2 Resolutionresolve_sidecar()完整实现、阻塞/异步/仅拉取三种模式、对接 SidecarManager、pending/missing 优雅降级Phase 3 OperationsReadAction / FileCopyAction 支持 sidecar、受限 DeleteAction、ListAction 目录列举、禁止 move/rename 的操作校验Phase 4 Job SystemThumbnailGenerationJob、OcrExtractionJob、TranscriptGenerationJob接入索引管线的 Intelligence Queueing 阶段SidecarManager 负责派发Phase 5 Cross-Device Sync可用性摘要交换、sidecar 传输协议、周期同步调度、预取策略当前PullMissing与游标分页已具备雏形Phase 6 CLI SDKsd sidecars命令族、sidecar glob 模式、面向扩展的 SDK API 与示例文档。验收标准与扩展方向任务规格的验收标准可归纳为四组也可作为评估 VSS 完整度的检查清单核心功能索引期间自动生成缩略图文档自动 OCRsidecar://URI 可寻址sidecar 可复制到物理位置可按内容项列出全部 sidecar。跨设备设备间交换可用性缺失 sidecar 可从远端拉取传输复用 P2P 基础设施可用性跟踪随库保持最新。集成扩展可通过 SDK 读写 sidecarCLI 支持 sidecar 操作Action 支持 sidecar 路径Resolver 覆盖全部解析模式。质量确定性路径免数据库查询生成幂等先生成前先检查Reference 可转托管清理策略防止无界增长。在扩展性上任务规格还强调新 kind 无需改动 schema 即可加入——kind/variant/format 均为字符串存储配合SidecarKind的directory()映射即可落地新派生类型如gaussian_splat3D 数据、thumbstrip预览条。结合 types.rs 中对 MessagePack 格式的设计说明VSS 是 Spacedrive 语义搜索与 AI 组织能力的结构化数据底座为按内容共享一份派生数据、全设备按需物化提供了可落地的实现范式。参考与延伸阅读任务规格.tasks/core/CORE-008-virtual-sidecar-system.md设计文档中引用的workbench/core/storage/系列规格不在当前仓库快照内用户文档docs/core/virtual-sidecars.mdx核心服务core/src/service/sidecar_manager.rs路径计算core/src/ops/sidecar/path.rs类型系统core/src/ops/sidecar/types.rs同步 Jobcore/src/ops/sidecar/sync_job.rs同步协调core/src/service/sidecar_sync/coordinator.rs、filters.rs统一寻址core/src/domain/addressing.rs、core/src/ops/addressing.rs数据库实体core/src/infra/db/entities/sidecar.rs、core/src/infra/db/entities/sidecar_availability.rs【免费下载链接】spacedriveSpacedrive is an open source cross-platform file explorer, powered by a virtual distributed filesystem written in Rust.项目地址: https://gitcode.com/gh_mirrors/sp/spacedrive创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考