onedrive:基于 Linux/FreeBSD 的 OneDrive 客户端项目

OneDrive Client for Linux

分支7Tags77
文件最后提交记录最后更新时间
13 天前
4 天前
1 个月前
4 天前
4 天前
7 年前
1 年前
1 年前
14 天前
7 年前
2 个月前
4 天前
1 个月前
1 个月前
7 年前
14 天前
1 个月前

OneDrive Client for Linux

版本 发布日期

Linux 测试构建 Linux 冒烟测试 构建 Docker 镜像 Docker 拉取量

端到端测试 - 主分支状态

一款功能齐全、免费且积极维护的 Microsoft OneDrive 客户端,无缝支持 OneDrive 个人版、OneDrive for Business、Microsoft 365(前身为 Office 365)以及 SharePoint 文档库。

该客户端设计追求最大的灵活性和可靠性,功能强大且高度可配置,可在所有主流 Linux 发行版、FreeBSD 和 OpenBSD 上运行。它也可以使用 Docker 或 Podman 部署在容器化环境中。支持单向和双向同步模式,为 Microsoft OneDrive 服务提供安全高效的文件同步,专为桌面和服务器环境量身定制。

项目背景

本项目源于 2018 年初对 skilion 客户端的分支,当时多项拟议的改进和错误修复(包括 Pull Requests #82 和 #314)未被合并,且 skilion 客户端的开发活动已基本停滞。虽然不清楚原开发者是暂时无法参与还是已退出该项目,但错误报告和功能请求在很长一段时间内都未得到回应。2020 年,原开发者(skilion)确认他们无意维护或支持其作品(参考)。

原始的 skilion 仓库 于 2024 年 12 月在 GitHub 上正式归档并设为只读。尽管作为历史参考仍可公开访问,但归档仓库不再维护,无法接受贡献,仅反映代码库的冻结快照。skilion 客户端的最后一次代码更改于 2021 年 11 月合并;然而,在此之前很久,其活跃开发就已显著放缓。因此,skilion 客户端不应再被视为当前或受支持的版本,特别是考虑到自那时以来 Microsoft OneDrive 平台的重大 API 变更和不断发展的要求。

根据 GNU 通用公共许可证 (GPL) 的条款,只要衍生作品保留相同的许可证,分叉和继续开发开源软件是完全允许的。本客户端遵守原始 GPLv3 许可,确保原始项目赋予的相同自由保持不变。

自 2018 年初分叉以来,本客户端已发展成为对原始代码库的彻底重新构想,解决了长期存在的错误,并添加了大量新功能,以更好地支持个人和企业用户从 Linux、FreeBSD 和 OpenBSD 平台与 Microsoft OneDrive 进行交互。

功能特性

广泛的 Microsoft OneDrive 兼容性

  • 适用于 OneDrive 个人版、OneDrive 企业版以及 Microsoft SharePoint 库。
  • 全面支持个人和企业账户间的共享文件夹与文件。
  • 支持单租户和多租户 Microsoft Entra ID 环境。
  • 兼容国家云部署:
    • Microsoft 云美国政府版
    • Microsoft 云德国版
    • 由世纪互联运营的 Azure/Office 365 中国版

灵活的同步模式

  • 双向同步(默认)- 保持本地和远程数据完全一致。
  • 仅上传模式 - 仅上传本地更改;不下载远程更改。
  • 仅下载模式 - 仅下载远程更改;不上传本地更改。
  • 模拟运行模式 - 安全测试配置更改,不修改文件。
  • 安全的冲突处理机制,在确定为最安全的冲突解决策略时,通过创建本地备份将数据丢失降至最低。

客户端过滤与精细同步控制

  • 全面的基于规则的客户端过滤(包含、排除、通配符 *、全局匹配 **)。
  • 过滤特定文件、文件夹或模式,精确定制与 Microsoft OneDrive 同步的内容。
  • 高效的缓存同步状态,以便在大型或复杂同步集时快速决策。

实时监控与在线变更检测

  • 利用原生 WebSocket 支持近乎实时地处理云端变更。
  • Webhook 支持,适用于 WebSocket 不适用的环境(需手动设置)。
  • 通过 inotify 进行实时本地变更监控。

数据安全、恢复与完整性保护

  • 实现 FreeDesktop.org 回收站规范,可恢复因在线删除而在本地删除的项目。
  • 强大的防护措施,防止配置更改后意外的远程删除或覆盖。
  • 可容忍中断的上传和下载,自动恢复传输。
  • 对每个传输的文件进行完整性验证。

现代身份验证支持

  • 标准 OAuth2 原生客户端授权流程(默认),支持基于浏览器的登录、多因素身份验证(MFA)以及现代 Microsoft 账户安全要求。
  • 适用于 Microsoft Entra ID 账户的 OAuth2 设备授权流程,是无头系统、服务器和纯终端环境的理想选择。
  • 通过 D-Bus 使用 Microsoft Identity Device Broker(IDB)实现 Intune 单点登录(SSO),无需手动输入凭据即可实现无缝的企业身份验证。

性能、效率与资源管理

  • 多线程文件传输,显著提升同步速度。
  • 带宽速率限制,可控制网络消耗。
  • 采用状态缓存的高效处理方式,减少 API 流量并提高性能。

桌面集成与用户体验

  • 用于同步事件、警告和错误的 libnotify 桌面通知。
  • 在受支持的文件管理器中将 OneDrive 文件夹注册为侧边栏位置,并配有独特图标。
  • 在图形用户界面(GUI)和无头/服务器环境中均能无缝工作。仅 Intune SSO、通知和侧边栏集成需要 GUI;所有其他功能在无图形支持的情况下仍可正常运行。

尚不支持的功能

  • 上传/下载文件时对文件进行实时加密/解密的能力
  • 支持 Windows“按需”功能,即仅在本地访问文件时才下载文件

外部增强工具

常见问题

请参阅 Frequently Asked Questions

有疑问?

如果您有任何问题或需要澄清某些内容,请在此处发起新的讨论帖。

支持的应用版本

仅为当前应用发布版本或更新的“master”分支版本提供支持。

当前发布版本为:Version

要检查您的版本,请运行:onedrive --version。确保您使用的是当前发布版本,如有需要,请从 master 分支编译最新版本。

如果您使用的是旧版本,必须升级到当前发布版本或更新版本才能获得支持。

文档和配置帮助

OneDrive Client for Linux 包含丰富的文档,涵盖安装、配置选项、高级用法和集成。这些资源旨在帮助新用户快速入门,并让有经验的用户能够完全控制高级行为。如果您要更改配置、在生产环境中运行,或使用 Business/SharePoint 功能,您应该阅读这些文档。所有文档都维护在此存储库的 docs/ 目录中。

入门指南

安装

了解如何在各种系统上安装客户端 — 从发行版软件包到从源代码构建。请阅读安装指南

基本用法与配置

涵盖初始身份验证、默认设置、基本操作说明、常见的“如何操作”问题,以及如何定制应用程序配置。请阅读使用指南

高级配置

应用程序配置选项

每个配置选项的完整参考(包含描述、默认值和示例),用于精确自定义同步行为。请阅读应用程序配置选项指南

高级用法

有关创建多个配置文件、自定义同步规则、守护进程设置、选择性同步、与 Microsoft Windows 双启动等的提示。请阅读高级用法指南

特殊使用场景

企业共享项目

配置 OneDrive 企业版共享项目(文件和文件夹)的同步。请阅读 企业共享项目指南

SharePoint 和 Office 365 库

同步 SharePoint 文档库(企业或教育租户)的说明。请阅读 SharePoint 库指南

国家云支持

针对 Microsoft Cloud Germany 或美国政府云终端等环境的说明。请阅读 国家云部署指南

容器支持

Docker

如何在 Docker 容器中运行 OneDrive 客户端。请阅读 Docker 指南

Podman

如何使用 Podman 运行 OneDrive 客户端。请阅读 Podman 指南

基本故障排除步骤

如果在运行应用程序时遇到任何问题,请在提交错误报告之前遵循以下步骤:

  1. 检查应用程序版本
    运行 onedrive --version 以确认您正在使用的版本。

    • 确保您运行的是最新的 版本
    • 如果您已经在使用最新版本但问题仍然存在,请从 master 分支手动构建客户端,以测试最新代码。这包括对自上次标记版本以来发现的错误的修复。
    • 如果您使用 Docker 或 Podman,请确保您使用的是 'edge' Docker 标签。不要使用 'latest' Docker 标签。
  2. 以详细模式运行
    使用 --verbose 选项可以更清晰地提供有关您所面临问题的详细日志。
    如果您使用 Docker 或 Podman,请使用 ONEDRIVE_VERBOSE 环境变量来增加日志详细程度。

  3. 仅使用 IPv4 测试
    将应用程序配置为仅使用 IPv4 网络连接,然后重新测试。有关帮助,请参阅 'ip_protocol_version' 选项 文档

  4. 使用 HTTP/1.1 和 IPv4 测试
    将应用程序配置为仅通过 IPv4 使用 HTTP/1.1,然后重新测试。有关帮助,请参阅 'force_http_11' 选项 文档

  5. 验证 cURL 和 libcurl 版本
    如果上述步骤无法解决您的问题,请将 curllibcurl 升级到 curl 开发人员提供的最新版本。

  6. 执行 --resync
    在某些情况下,需要使用 --resync 来确保您的数据正确同步。此选项指示客户端删除其本地状态数据库,并根据当前在线的 OneDrive 内容完全重建它。这是一个强大的恢复和重新对齐操作,应谨慎且少量使用。

  7. 提交新问题
    如果完成上述步骤后问题仍然存在,请继续执行下面的报告问题或错误,并提交包含所需详细信息和日志的新问题。

报告问题或缺陷

Important

请确保所遇问题是软件缺陷。对于安装问题、发行版软件包/版本疑问或依赖项问题,请发起讨论,而非提交缺陷报告。

如果您遇到缺陷,可以在 GitHub 上进行报告。在提交新的问题报告之前,请先执行以下步骤:

  1. 完成基本故障排除步骤
    确认您已完成上述部分中的所有步骤。

  2. 搜索现有问题
    检查开放已关闭的问题,看是否存在类似问题,以避免重复提交。

  3. 使用问题模板
    使用问题模板提交新的缺陷报告,并填写所有字段。完整的细节有助于我们重现您的环境和问题。

  4. 生成调试日志
    按照此流程创建调试日志。

    • 如果您担心调试日志中包含个人或商业敏感数据,您可以:
      • 创建一个新的 OneDrive 账户,将客户端配置为使用该账户,使用虚拟数据模拟您的环境,并重现问题;或者
      • 在共享敏感日志之前,提供保密协议(NDA)供签署。
  5. 安全地共享调试日志

    • 不要公开发布调试日志。 调试日志可能包含敏感信息(文件路径、文件名、API 端点、环境信息等)。
    • 通过电子邮件发送日志support@mynas.com.au,并使用可信的电子邮件账户。
    • 发送前将日志归档并设置密码保护(例如,带 AES 加密的 .zip.7z):
      • 示例(带密码的 zip):zip -e onedrive-debug.zip onedrive-debug.log
      • 示例(带密码的 7z):7z a -p onedrive-debug.7z onedrive-debug.log
    • 通过带外(OOB)方式发送密码——不要与归档文件在同一封电子邮件中发送。请通过电子邮件 support@mynas.com.au 安排带外方式(例如,单独的邮件线程、电话/短信或约定的渠道)。
    • 如果您需要签署保密协议(NDA),请将您的 NDA 或保密协议附加到电子邮件中。在交换敏感数据之前,我们会对其进行审核并签署。

错误报告中应包含的内容

提交新的错误报告时,请包含问题模板中要求的所有详细信息,例如:

  • 对问题的清晰描述以及重现步骤
  • 您的操作系统和安装方法
  • OneDrive 账户类型和客户端版本
  • 应用程序配置和 cURL 版本
  • 同步目录位置、系统挂载点和分区类型
  • 完整的调试日志,并按照上述说明安全共享

提供完整的信息能让我们更轻松地理解、重现并快速解决您的问题。

Note

提交错误报告意味着开始协作。为了帮助我们更好地为您提供支持,请:

  • 保持联系,以便在需要时回答问题或提供说明
  • 当针对您的问题创建拉取请求(PR)时,在您自己的环境中测试并确认修复

Tip

缺少详细信息的报告很难调查。提前分享尽可能多的信息,才能最大程度地获得快速且准确的修复。

已知问题

列出常见限制、已知问题、诊断方法和解决方法。请阅读 Known Issues Advice