flor1der/paperless-nextcloud-sync

Paperless-ngx 到 Nextcloud 的 WebDAV 实时同步

该Docker镜像挂载远程WebDAV源，并将/mnt/source的数据实时同步到挂载的WebDAV驱动器。它专为Nextcloud设计，但也被证明可与其他云系统配合使用：

✔ Nextcloud (测试版本 30.0)
✔ ownCloud (测试版本 10.15)
✔ OpenCloud (测试版本 2.3)
✔ web.de smartdrive (2025-05测试)

🧠 项目背景

本项目提供了一种无缝连接Paperless和Nextcloud的方式，克服了其他解决方案中的局限性。它满足以下关键要求：

• 简单快速的配置
• 与远程Nextcloud实例同步
• 创建、删除或修改的文件会显示在Nextcloud的活动Feed中
• PDF文件可通过Nextcloud的搜索功能找到
• 实时同步

[!NOTE]
同步是单向的（Paperless ➔ Nextcloud），以确保Paperless的数据完整性。

📋 准备工作

您可以先配置Paperless文件名处理。

要求

• 对Nextcloud的管理员访问权限，用于调整用户和暴力破解设置
• 专用的Nextcloud账户，具有同步容器的读写权限

Nextcloud中的调整

1. 创建专用账户
   • 也创建一个专用的同步文件夹并在您的Nextcloud中共享
   • 然后将文件夹以只读方式与用户/组共享，以保持数据一致性
2. 暴力破解设置
   • 设置日志级别为Info - 以便在日志中查看限流事件
   • 将容器的IP添加到Nextcloud的白名单中，以防止初始同步期间的限流

[!TIP] 对这个简短描述有疑问？https://github.com/Flo-R1der/paperless-nextcloud-sync/blob/main/documentation/README.md%E3%80%82

📥 安装

🛠️ 设置

1. 使用Docker Compose将容器添加到您的Paperless堆栈：

   yaml
     nc-sync:
       image: docker.xuanyuan.run/flor1der/paperless-nextcloud-sync:latest
       volumes:
         - "/var/lib/docker/volumes/paperless_media/_data/documents/archive:/mnt/source:ro"
         - "./nc-sync_logs/:/var/log/"
       environment:
         WEBDRIVE_URL: $NEXTCLOUD_URL
         WEBDRIVE_USER: $NEXTCLOUD_USER
         WEBDRIVE_PASSWORD: $NEXTCLOUD_PASSWORD
         TZ: Europe/Berlin
       privileged: true
       devices:
         - "/dev/fuse"
   

2. 替换占位符并定义环境变量：

   • 在volumes:下指定文档库的挂载点

   • 填写**WEBDRIVE_URL、WEBDRIVE_USER和WEBDRIVE_PASSWORD**值

     • WEBDRIVE_URL必须是在准备工作中创建的文件夹的WebDAV URL
     • 如果启用了双因素认证，请使用应用密码
     • 如果要使用https://docs.docker.com/compose/how-tos/use-secrets/%EF%BC%8C%E8%AF%B7%E4%BD%BF%E7%94%A8%60WEBDRIVE_PASSWORD_FILE%60%E4%BB%A3%E6%9B%BF%60WEBDRIVE_PASSWORD%60
     点击查看可选设置：

     • 使用DIR_USER、DIR_GROUP、ACCESS_DIR和ACCESS_FILE定义webdrive挂载选项
     • 如果遇到特殊字符的文件名问题，将LC_ALL、LANG和LANGUAGE设置为https://docs.oracle.com/cd/E23824_01/html/E26033/glset.html#glscx%E4%B8%AD%E7%9A%84%E4%BB%BB%E4%BD%95%E5%80%BC
     • 如果日志文件需要保留超过/少于90天，请设置KEEP_LOGFILE_DAYS
     • 有关自定义cron功能，请查看https://github.com/Flo-R1der/paperless-nextcloud-sync/blob/main/README.md#%F0%9F%A7%A9-advanced-functionalities%E9%83%A8%E5%88%86

3. 重启Paperless实例以激活容器

4. 验证容器是否正在运行：

   bash
   docker logs --follow <容器名称>
   

[!TIP] 对这个简短描述有疑问？https://github.com/Flo-R1der/paperless-nextcloud-sync/blob/main/documentation/README.md%E3%80%82

🚀 容器启动

• WebDAV驱动器将被挂载
• 初始同步作为后台作业启动
• 文件监视器实时监控变化
• 如果WebDAV和文件监视器正在运行：容器的健康状态显示"healthy"
• 日志提供有关同步过程的详细信息

✔ 预期结果

• 初始同步上传Nextcloud中不存在、Paperless中更新或已移动/重命名的现有文件
• Paperless中的新文件传输到Nextcloud并显示在活动Feed中：
  !https://github.com/Flo-R1der/paperless-nextcloud-sync/raw/main/documentation/nextcloud-activity_example.png

🧩 高级功能

自定义Cron作业

这需要一些额外的配置，否则cron作业根本无法工作：

• 将此仓库中的https://github.com/Flo-R1der/paperless-nextcloud-sync/blob/main/cronjob%E6%96%87%E4%BB%B6%E5%A4%8D%E5%88%B6%E5%88%B0docker%E4%B8%BB%E6%9C%BA%E4%B8%8A%E7%9A%84%E5%A0%86%E6%A0%88/compose%E7%9B%AE%E5%BD%95%EF%BC%88%E4%BE%8B%E5%A6%82%E4%BD%9C%E4%B8%BA%60nc-sync_cronjobs%60%EF%BC%89
• 编辑文件并对文件运行chown root和chmod 0644
  • 重要：文件末尾需要一个空行！
• 作为卷挂载：- "./nc-sync_cronjobs:/etc/cron.d/cronjobs"

如果需要脚本，也执行相同操作（但使用chmod 0744）

📌 开放主题

• 用更好的解决方案替换初始同步。我使用rsync的测试导致同步期间文件删除，我的脚本避免了这种情况但仍然会产生错误消息（参见https://github.com/Flo-R1der/paperless-nextcloud-sync/blob/main/documentation/container-logs_example.txt%EF%BC%8C%E7%AC%AC20-24%E8%A1%8C%EF%BC%89%E3%80%82**%E5%8F%AA%E6%9C%89%E5%BD%93%E6%82%A8%E6%9C%89%E5%90%88%E9%80%82%E7%9A%84%E8%A7%A3%E5%86%B3%E6%96%B9%E6%A1%88%E6%97%B6%EF%BC%8C%E8%AF%B7%E6%89%93%E5%BC%80issue%EF%BC%81**

喜欢我的工作？

![]([]