Ubuntu OneDrive 同步服务配置指南

作者：Segegs 日期：2025-02-22 环境：Ubuntu 24.10

OneDrive 简介

OneDrive 是微软提供的云存储服务，它提供：

  1. 文件存储和同步

    • 跨设备文件同步
    • 自动相册备份
    • 文件版本控制

  2. 文件共享和协作

    • 文件和文件夹共享
    • 实时协作编辑
    • 权限管理

  3. 安全特性

    • 文件加密
    • 多重身份验证
    • 数据备份和恢复

  4. 集成功能

    • 与 Microsoft 365 集成
    • 支持 Windows、macOS、iOS 和 Android
    • 提供 Web 界面访问

Linux 上的 OneDrive 客户端

微软官方并未提供 Linux 版本的 OneDrive 客户端，但社区开发了一个功能强大的开源客户端，它提供：

  1. 基本功能

    • 文件双向同步
    • 增量同步
    • 文件监控

  2. 高级特性

    • 选择性同步
    • 排除规则
    • 文件名大小写敏感性处理

  3. 系统集成

    • Systemd 服务支持
    • 日志和状态监控
    • 命令行工具

前言

在 Ubuntu 系统上配置 OneDrive 同步服务可能会遇到一些挑战。这篇文章将详细记录整个配置过程，包括遇到的问题和解决方案。

1. 安装 OneDrive 客户端

首先，我们需要安装 OneDrive 客户端。Ubuntu 24.10 的软件仓库已经包含了最新版本的 OneDrive 客户端：

sudo apt update
sudo apt install onedrive

2. 初始配置

2.1 首次运行和授权

运行以下命令启动配置过程：

onedrive

系统会显示一个 URL，需要：

  1. 复制该 URL 到浏览器
  2. 登录 Microsoft 账户
  3. 授权 OneDrive 客户端
  4. 复制生成的代码
  5. 粘贴回终端

注意：如果遇到 SSL 连接问题，可以使用 --force-http-11 参数：

onedrive --force-http-11

2.2 配置同步目录

默认情况下，OneDrive 会同步到 ~/OneDrive 目录。我们可以通过修改配置文件来更改：

  1. 创建配置目录：
mkdir -p ~/.config/onedrive
  1. 编辑配置文件：
nano ~/.config/onedrive/config
  1. 添加基本配置：
sync_dir = "~/OneDrive"
log_dir = "~/.config/onedrive/logs"

3. 配置选择性同步

3.1 创建同步列表

我们只需要同步特定文件夹（Camera Roll 和 Screenshots），创建同步列表：

nano ~/.config/onedrive/sync_list

添加需要同步的文件夹：

Pictures/Camera Roll
Pictures/Screenshots

重要提示：

  • 路径必须完全匹配 OneDrive 上的路径
  • 区分大小写
  • 不要在路径开头添加斜杠
  • 每个路径独占一行

4. 配置系统服务

4.1 启用用户级服务

# 启用服务自动启动
systemctl --user enable onedrive

# 启动服务
systemctl --user start onedrive

4.2 配置用户登录持久化

为确保服务在系统启动时自动运行，需要启用用户登录持久化：

loginctl enable-linger $USER

5. 验证配置

5.1 检查服务状态

systemctl --user status onedrive

5.2 监控同步过程

# 查看实时日志
journalctl --user-unit onedrive -f

# 手动触发同步（用于测试）
onedrive --synchronize --verbose

常见问题解决

1. SSL 连接问题

如果遇到 SSL 连接错误：

  1. 使用 --force-http-11 参数
  2. 更新系统 CA 证书：
sudo update-ca-certificates

2. 同步问题

如果文件不能正确同步：

  1. 检查网络连接
  2. 确认文件路径大小写正确
  3. 查看详细日志：journalctl --user-unit onedrive
  4. 必要时重新同步：
onedrive --resync --resync-auth

实用命令参考

# 查看服务状态
systemctl --user status onedrive

# 启动服务
systemctl --user start onedrive

# 停止服务
systemctl --user stop onedrive

# 重启服务
systemctl --user restart onedrive

# 查看同步日志
journalctl --user-unit onedrive

# 手动同步（测试用）
onedrive --synchronize --verbose

总结

通过以上步骤，我们成功在 Ubuntu 24.10 上配置了 OneDrive 同步服务。关键点是：

  1. 正确处理 SSL 连接问题
  2. 准确配置同步路径
  3. 确保服务自动启动
  4. 启用用户登录持久化

配置完成后，系统会自动同步指定文件夹，无需手动干预。如果遇到问题，可以通过日志快速定位和解决。

参考资料

6. 自动同步配置详解

OneDrive 客户端提供了多种自动同步配置选项，可以根据需求进行调整。

6.1 配置文件详解

编辑配置文件：

nano ~/.config/onedrive/config

常用配置选项：

# 基本设置
sync_dir = "~/OneDrive"                  # 同步目录路径

# 监控设置
monitor_interval = "300"                 # 检查变更的间隔时间（秒）
monitor_fullscan_frequency = "12"        # 每多少次检查执行一次完整扫描

# 日志设置
log_dir = "~/.config/onedrive/logs"      # 日志目录

# 同步行为
no_remote_delete = "true"                # 防止删除云端文件
upload_only = "false"                    # 设为 true 则只上传不下载
download_only = "false"                  # 设为 true 则只下载不上传

# 性能设置
rate_limit = "0"                         # 带宽限制（KB/s），0 表示不限制
skip_file_prefixes = "~,.~,.~lock."      # 跳过特定前缀的文件
skip_file_suffixes = ".tmp,.temp,.swp"   # 跳过特定后缀的文件

6.2 同步模式选择

OneDrive 客户端支持多种同步模式：

  1. 双向同步（默认）：

    • 本地和云端文件保持同步
    • 任一端的更改都会同步到另一端
    • 配置：不需要特殊设置

  2. 仅上传模式：

    • 本地文件更改会上传到云端
    • 云端更改不会下载到本地
    • 配置：upload_only = "true"

  3. 仅下载模式：

    • 云端文件更改会下载到本地
    • 本地更改不会上传到云端
    • 配置：download_only = "true"

  4. 监控模式：

    • 实时监控文件系统变化
    • 自动同步变更的文件
    • 配置：默认启用，通过 monitor_interval 调整频率

6.3 同步频率调整

可以根据需求调整同步频率：

  1. 检查间隔：

    • monitor_interval = "300" - 每 5 分钟检查一次变更
    • 较小的值会提高同步及时性，但增加系统负载
    • 较大的值会减少系统负载，但同步可能延迟

  2. 完整扫描频率：

    • monitor_fullscan_frequency = "12" - 每 12 次检查执行一次完整扫描
    • 完整扫描会检查所有文件，确保没有遗漏
    • 较小的值会提高同步可靠性，但增加系统负载

6.4 带宽控制

对于网络带宽有限的环境，可以限制 OneDrive 的带宽使用：

rate_limit = "1024"  # 限制为 1024 KB/s (1 MB/s)

6.5 自动重启服务

如果需要确保服务始终运行，可以配置 systemd 服务自动重启：

  1. 创建自定义服务文件：
mkdir -p ~/.config/systemd/user/
cp /usr/lib/systemd/user/onedrive.service ~/.config/systemd/user/
nano ~/.config/systemd/user/onedrive.service
  1. 添加重启策略：
[Service]
Restart=always
RestartSec=60
  1. 重新加载 systemd 配置：
systemctl --user daemon-reload
systemctl --user restart onedrive

6.6 监控同步状态

可以通过以下方式监控同步状态：

  1. 查看服务状态：
systemctl --user status onedrive
  1. 查看实时日志：
journalctl --user-unit onedrive -f
  1. 查看同步统计：
onedrive --display-stats
  1. 查看同步状态：
onedrive --display-sync-status

结论

通过本指南的配置，我们成功在 Ubuntu 24.10 系统上设置了 OneDrive 同步服务，实现了特定文件夹的自动同步。这种配置适用于家庭服务器环境，可以确保重要文件得到及时备份和同步。

通过调整同步频率、带宽限制和同步模式，可以根据具体需求优化同步行为，在同步效率和系统资源使用之间取得平衡。

7. 升级 OneDrive 客户端

随着 OneDrive 客户端的不断更新，可能需要升级到最新版本以获取新功能和修复。以下是从源代码编译安装最新版本的步骤：

7.1 安装编译依赖

sudo apt update && sudo apt install -y build-essential libcurl4-openssl-dev libsqlite3-dev pkg-config git libnotify-dev ldc

7.2 下载和编译源代码

# 克隆仓库并切换到最新版本
cd /tmp
git clone https://github.com/abraunegg/onedrive.git
cd onedrive
git checkout v2.5.4  # 替换为最新版本号

# 配置和编译
./configure
make

7.3 安装新版本

sudo make install

新版本将被安装到 /usr/local/bin/onedrive。

7.4 更新服务配置

由于系统服务仍然使用旧版本，需要创建自定义服务文件：

# 创建用户级服务目录
mkdir -p ~/.config/systemd/user/

# 复制服务文件
cp /usr/lib/systemd/user/onedrive.service ~/.config/systemd/user/

# 编辑服务文件
nano ~/.config/systemd/user/onedrive.service

修改 ExecStart 行：

ExecStart=/usr/local/bin/onedrive --monitor

7.5 重启服务

# 重新加载 systemd 配置
systemctl --user daemon-reload

# 重启服务
systemctl --user restart onedrive

# 检查服务状态
systemctl --user status onedrive

7.6 注意事项

  • 新版本可能会更改配置选项的行为，需要相应调整配置文件
  • 升级后应检查日志确保服务正常运行
  • 如果遇到问题，可以临时回退到旧版本：systemctl --user edit onedrive，将 ExecStart 改回 /usr/bin/onedrive --monitor

7.7 版本升级后的重新同步

在 OneDrive 客户端版本升级后，特别是从 2.4.x 升级到 2.5.x 这样的主要版本升级，可能需要执行重新同步操作以确保客户端状态与 OneDrive 云端保持一致。

# 首先停止服务
systemctl --user stop onedrive

# 执行重新同步（注意：使用 --sync 而不是已弃用的 --synchronize）
/usr/local/bin/onedrive --resync --sync

# 重新启动服务
systemctl --user start onedrive

# 检查服务状态
systemctl --user status onedrive

重新同步注意事项

  • --resync 会删除本地 OneDrive 客户端状态，可能导致本地文件被云端文件覆盖
  • 在执行重新同步前，确保重要的本地文件已备份
  • 如果遇到 “application is already running” 错误，确保先停止所有 OneDrive 进程
  • 新版本中 --synchronize 参数已弃用，应使用 --sync 或 -s 代替

结论

通过本指南的配置，我们成功在 Ubuntu 24.10 系统上设置了 OneDrive 同步服务，实现了特定文件夹的自动同步。这种配置适用于家庭服务器环境，可以确保重要文件得到及时备份和同步。

通过调整同步频率、带宽限制和同步模式，可以根据具体需求优化同步行为，在同步效率和系统资源使用之间取得平衡。