Olares / LarePass 文件操作指南：上传、下载、删除与本地双向同步

• 云原生
• 后端
• 运维

通过 LarePass 客户端（桌面端与手机端）可以直接管理 Olares 个人云中的文件，所有操作与 Olares 内置的文件管理器应用保持一致体验。本文将覆盖 LarePass 中最常用的四类文件任务：上传、下载、删除，以及桌面端独有的「同步至本地」双向同步能力，并同步结合开源仓库中 文件管理前端实现 与 同步模块实现 讲解其底层工作方式。

开始之前：导入 Olares ID

首次使用 LarePass 桌面端时，需要先粘贴助记词导入 Olares ID，才能访问并管理云端文件。请确保已经备份助记词，避免因设备丢失或更换导致无法恢复账户。

• 桌面端：首次启动后按提示粘贴助记词完成导入，即可进入文件管理界面。
• 手机端：可直接使用 LarePass 创建 Olares ID，或导入已有账户，详见下载与账户设置指南。

上传文件

通过 LarePass 上传的文件会自动同步到同一账户下的 Olares，无需额外配置。也就是说，手机或电脑上的上传操作会立即反映到 Olares 的文件系统中，反向的同步能力见下文「同步文件至本地」。

通过 LarePass 桌面端上传

LarePass 桌面端提供与文件管理器应用相同的上传体验：进入文件页签，选择目标目录后即可上传，文件会自动同步至 Olares。

从源码实现看，桌面端上传依赖一个隐藏的文件选择器输入框uploader-input：

• 选择文件时，调用uploadFiles()，清除webkitdirectory属性后触发click()；
• 选择文件夹时，调用uploadFolder()，为同一输入框设置webkitdirectory属性后触发click()，实现整个目录的上传。

相关实现位于 apps/packages/app/src/api/files/v2/drive/data.ts。上传前，客户端会先向/upload/upload-link/<node>/请求上传链接，并通过/upload/file-uploaded-bytes/<node>/查询已上传字节数，用于支持断点续传与上传进度展示（见 getFileServerUploadLink 与 getFileUploadedBytes）。

通过 LarePass 移动端上传

在手机上可以通过两种方式上传文件：

方式一：直接上传

1. 打开 LarePass，进入文件页签。
2. 选择要上传文件的目标目录。
3. 点击右下角的add_circle，选择上传方式：
   • 文件：从手机存储选择文件，可一次选取多个文件。
   • 图片/视频：从相册选择图片，可一次选取多个图片。
   • 如需先整理目录，可先创建文件夹。
4. 按屏幕提示完成上传。

方式二：通过系统分享菜单上传

1. 打开要分享的文件，进入系统分享菜单。
2. 选择LarePass图标，或在更多操作中选择LarePass，系统会跳转到 LarePass 应用。
3. 在 LarePass 中选择上传目标：
   • Drive：上传到个人 Drive 存储，用于个人使用。
   • Sync：上传到 Sync 存储，便于共享或同步。
4. 根据所选目标位置完成上传。

具体分享步骤因操作系统和浏览器而异。

提示：上传任务同样由统一的传输模块（Transfer）接管。前端源码中以TransferFront.upload标识上传类任务，相关任务面板位于 apps/packages/app/src/pages/Electron/Transfer/TransferTable.vue 和 apps/packages/app/src/pages/Mobile/transfer/FilesTransferPage.vue。

下载文件

在 LarePass 中批量下载文件时，任务会排队执行，你可以随时暂停、继续或取消任务，并能快速定位已下载文件。

:::tip 建议 下载大文件或批量下载时，推荐使用 LarePass 桌面端，以获得更强的下载管理能力和更佳体验。 :::

LarePass 桌面端

1. 打开 LarePass 桌面端。
2. 在文件中选中文件，右键选择下载。

下载任务可在传输>下载中查看或管理。

从源码实现看，桌面端下载会先为每个选中的文件生成一个TransferItem，包含下载地址、文件路径、大小、类型与TransferFront.download标记，然后交给传输队列统一处理（见 getDownloadInfo）。文件原始内容通过raw接口获取，支持inline参数控制内联预览或直接下载（见 getDownloadURL）。

LarePass 手机端

1. 打开手机端 LarePass。
2. 在文件中点选文件，点击more_horiz>下载。

下载任务可在传输>下载>进行中中查看、暂停或取消。

同步文件至本地

通过 LarePass 桌面端，你可以将云端的文件（以资料库或文件夹为单位）直接同步到本地电脑。系统会在本地电脑上创建一个对应的同步文件夹；设置完成后，文件将自动实时保持双向同步。

:::tip 注意同步至本地功能仅适用于同步目录下的资料库或文件夹。 :::

目前本地文件同步支持 Windows 和 Mac 设备。库（Library）是组织、同步和共享数字内容的基本单元，也是一个多功能的文件容器，支持多设备同步、实时协作与灵活管理。每位用户都会自动获得一个个人库（My Library）作为起点。

创建库

1. 在同步目录右侧，点击add_circle打开新建库对话框。
2. 输入库名称并点击创建。

在源码层面，新建库对应createLibrary(name)实现，即向repos接口发起 POST 请求，以repoName参数创建资料库（见 apps/packages/app/src/api/files/v2/sync/utils.ts）。

开启同步

1. 打开 LarePass 桌面端，找到同步目录。
2. 将鼠标悬停在想要同步的资料库或文件夹上，点击右侧出现的more_horiz，点击同步至本地。
3. 在同步库弹窗中，设置文件的下载位置，然后点击确认，同步随即开始。

同步完成后，该文件夹图标的左下角会出现一个绿色对勾，表示同步已完成。

管理同步

设置同步后，可以通过以下操作管理文件和控制同步状态：

• 打开本地同步文件夹：将鼠标悬停在资料库或文件夹上，点击more_horiz>打开本地同步文件夹，系统将直接打开该文件夹所在的本地路径。
• 取消同步：如果不再需要同步某个文件夹，点击more_horiz>取消同步。此操作不会删除本地文件，只是停止双向同步过程。
• 暂停所有同步：需要暂时停止数据传输时，点击同步目录右侧的pause_circle，即可一键暂停所有同步任务。

处理同步冲突

在极少数情况下可能出现同步冲突，例如多个设备同时编辑同一文件：

• 第一个完成的编辑会保存到库中。
• 冲突版本会被备份，并以唯一文件名保存，文件名包含编辑者的 Olares ID 和时间戳，格式如test.txt(SFConflict name 2024-04-17-12-12-12)。

关于库的共享、角色权限（所有者/成员、只读/读写）以及退出或删除库的更多说明，可参阅同步和共享文件。

删除文件

:::warning 删除操作不可恢复，请谨慎操作。 :::

LarePass 桌面端

1. 打开 LarePass 桌面端。
2. 在文件中选中文件，右键菜单里点击删除。
3. 在弹窗中确认删除。

LarePass 手机端

1. 打开手机端 LarePass。
2. 在文件中点选文件，点击more_horiz>删除。
3. 在弹窗中确认删除。

从源码实现看，删除操作会按父目录对选中文件分组，然后调用batchDelete批量发起 DELETE 请求（见 batchDeleteFileItems 与 batchDelete）。因此无论选中单个文件还是多个文件，前端都会在一次交互中完成批量删除，且不会提供恢复入口。

与文件管理器应用的一致性

LarePass 中的文件管理与 Olares 文件管理器应用体验一致，不同平台之间仅有细微差异：

• 统一存储视图：Drive（个人存储）与 Sync（同步/共享存储）共享同一套文件操作入口，上传时选择的目标决定了文件落在个人空间还是共享空间。
• 统一的传输队列：上传、下载任务统一进入传输面板管理，支持排队、暂停、继续、取消与历史记录。
• 一致的右键/长按菜单：桌面端使用右键菜单，移动端使用more_horiz更多菜单，但操作项（下载、删除、同步等）保持一致。

如果需要在 LarePass 中下载网络资源（如 Torrent、Hugging Face 模型、媒体链接）直接保存到 Olares，可参考将资源转存到 Olares。若需要了解文件管理器应用自身的更多文件操作，可参阅文件管理器文档。

• 云原生
• 后端
• 运维