# cloudlibrary.koplugin

**Repository Path**: gytwo/cloudlibrary.koplugin

## Basic Information

- **Project Name**: cloudlibrary.koplugin
- **Description**: koreader插件-云端书库，在设备间同步书籍及元数据（书籍标注、阅读进度等）。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# cloudlibrary

#### 插件介绍

koreader插件-云端书库，在设备间同步书籍及元数据（书籍标注、阅读进度等）。

#### 同步原理

1. 本插件直接操作设备原始元数据文件，通过上传/下载/更新元数据文件，实现书籍标注、阅读进度等书籍信息的一次性同步。
2. 同时支持书籍本身的批量上传/下载，实现完整的书库同步。

#### 安装教程

下载解压后直接将cloudlibrary.koplugin文件夹放入设备koreader\plugins目录下

#### 使用说明

![云端书库-菜单](picture/云端书库-菜单.png)

【前提设置】
1. 浏览器界面选择「菜单」→「工具」→「云存储」，添加云存储账号
2. 插件操作：「菜单」→「工具」→「云端书库」→「设置」→选择云端目录，用于存放书籍元数据文件、书籍文件、同步记录文件
   - 书籍云端目录默认取元数据云端目录，也可以额外选择独立的云端目录
   - 不同设备应设置相同的云端目录，否则无法共享
3. 不同设备的本地文档元数据存放位置应当保持一致（「设置」→「文档」→「书籍元数据文件夹」）。默认通常是一致的，但如果某设备更改了该设置，另一设备也应当进行相应更改，否则可能会提示找不到本地元数据文件

【云端命名规则】
- 元数据：可选文件名 / 使用书籍标题（默认） / 使用标题_作者
- 书籍：可选文件名 / 使用书籍标题（默认） / 使用标题_作者
- 注意：不同设备的云端命名规则应当保持一致

【元数据上传备份】
直接上传本地书籍对应的本地元数据文件（.lua格式）至云端，如云端已有同名文件，会直接覆盖
![云端书库-批量上传元数据](picture/云端书库-批量上传元数据.png)

【元数据下载更新】
- 覆盖模式：云端文件直接覆盖本地文件，通过「菜单」→「工具」→「云端书库」→「设置」可以选择是否需要保留本地文档设置
![云端书库-批量下载元数据-覆盖更新](picture/云端书库-批量下载元数据-覆盖更新.png)

- 合并模式：以本地为基础，合并云端特有、更新的信息
   - 阅读标注：保留本地和云端的所有标注（含高亮、划线、书签、笔记等）并进行合并、更新、去重、排序
   - 阅读状态：取优先级更高：已读完>阅读中>未读
   - 阅读进度：取更远值
   - 阅读统计：高亮数、笔记数根据合并结果自动统计
   - 文档设置：保留本地设置
![云端书库-批量下载元数据-合并更新](picture/云端书库-批量下载元数据-合并更新.png)


【元数据下载模式（手动）】
用于快捷切换覆盖/合并模式（不影响自动下载更新模式）

【书籍同步说明】
- 上传时若云端已存在同名文件，会直接覆盖
- 下载时若本地已存在同名文件，会直接跳过（详情可在同步记录中查看），如确需下载，请先删除/重命名本地文件。
![云端书库-批量下载书籍](picture/云端书库-批量下载书籍.png)
![云端书库-批量下载书籍-搜索](picture/云端书库-批量下载书籍-搜索.png)
![云端书库-批量下载书籍-勾选](picture/云端书库-批量下载书籍-勾选.png)
![云端书库-批量下载书籍-勾选2](picture/云端书库-批量下载书籍-勾选2.png)
![云端书库-批量下载书籍-确认](picture/云端书库-批量下载书籍-确认.png)

【批量同步方法】
1. 在文件管理器进入选择模式 → 勾选要同步的书籍 → 点击「菜单」→「工具」→「云端书库」→「元数据同步/书籍同步」
2. 设置快捷手势后可直接通过手势进入选择模式，勾选书籍后再次通过手势直接执行上传/下载

【自动同步设置（仅元数据）】仅针对当前阅读的单本书籍
1. 默认不开启，通过勾选下方具体选项自动开启对应模式。
2. 自动上传备份：编辑标注、关闭书籍、设备休眠时自动上传元数据覆盖云端（可以同时开启，但不建议这么做，推荐选择关闭书籍或设备休眠时自动备份）
3. 自动下载更新：打开书籍时自动从云端下载元数据更新本地（覆盖/合并两种模式）

- 注意事项：
  - 自动同步仅在勾选的时机同步相应的书籍元数据，而不是时时刻刻自动同步所有书籍元数据。比如，勾选了关闭书籍时自动上传，那么不论是哪一本书籍，在哪一个路径，只要当前执行的操作是关闭书籍，设备就会自动上传该书籍元数据覆盖云端目录下的元数据文件。
  - 初次使用该插件时，请先将当前设备本地元数据手动批量上传至云端后再开启自动同步。
  - 开启自动同步时，为防止不同设备数据被意外覆盖，请尽量选择合并更新模式。
  - 请确保设备连接网络，否则将无法自动同步。


【额外备份JSON文件】
开启时会在上传时额外将原始元数据文件转换为JSON格式并同原始元数据文件一并上传，JSON格式不是用于不同设备上koreader书籍元数据同步的标准文件，而是为了满足用户对koreader上的标注进行进一步整理的需要，按需开启即可。

【同步记录】
- 每次同步操作都会生成同步记录，可用于排查同步失败问题
- 开启「记录云同步」后，同步记录会自动与云端同步，可查看不同设备上的同步记录（为减少性能消耗，请尽在需要时开启）
- 可通过查看同步记录中的清空按钮和「菜单」→「工具」→「云端书库」→「设置」中的清空云端同步记录分别清空本地和云端同步记录
![云端书库-同步记录-批量下载元数据](picture/%E4%BA%91%E7%AB%AF%E4%B9%A6%E5%BA%93-%E5%90%8C%E6%AD%A5%E8%AE%B0%E5%BD%95-%E6%89%B9%E9%87%8F%E4%B8%8B%E8%BD%BD%E5%85%83%E6%95%B0%E6%8D%AE.png)
- 注意：因为本插件是直接操作设备原有的元数据文件，所以如果设备本地没有元数据文件（如还未曾打开过的书籍、或者初次打开的书籍还没来得及生成元数据文件），就会提示同步失败，未找到本地元数据文件，此时只要重新打开书籍后再进行同步操作即可）


【手势快捷操作】
-分别在阅读界面和文件管理器界面进入「设置」→「手势」→「手势管理」，选择手势后勾选阅读器和文件管理器中的云端书库相应菜单
-结合元数据下载模式设置，实现一个手势下载/批量下载（智能模式）
-省心同步模式：一个手势开启/关闭元数据自动同步（关闭书籍时/设备休眠时自动上传备份当前书籍元数据；打开书籍时自动下载合并更新当前书籍元数据）

![云端书库-快捷手势-文件管理器](picture/云端书库-快捷手势-文件管理器.png)
![云端书库-快捷手势-阅读器](picture/云端书库-快捷手势-阅读器.png)
![云端书库-快捷设置](picture/云端书库-快捷设置.png)
![云端书库-zenui快捷设置](picture/云端书库-zenui快捷设置.png)
![云端书库-zenui快捷设置2](picture/云端书库-zenui快捷设置2.png)

#### 更新说明
cloudlibrary（更名后） 在小红书MetedataSync（更名前） v0.22版本的基础上添加了一些新功能，修复了一些bug：

1.  添加书籍同步功能，可批量上传或下载、删除云端书籍（v1.0）
2.  添加手势快捷操作，可通过手势调出快捷操作、快捷设置（v1.0）
3.  修复通过手势快捷操作时文件浏览器选择模式可能状态混乱的问题（v1.0）
4.  修复合并更新时pdf文档崩溃的问题（v1.0）
5.  修复合并更新时部分标注可能丢失渲染的问题（v1.0）
6.  优化合并更新时笔记更新的问题（v1.0）
7.  添加清空云端同步记录的功能（v1.0）
8.  优化同步记录开启记录云同步后可能格式混乱的问题（v1.0）
9.  取消自动同步上传下载互斥限制，可同时开启自动上传和自动下载 （v1.0）
10. 添加在线更新功能（v1.0）
11. 覆盖更新由完全覆盖改为可选覆盖，可以选择是否需要保留本地文档设置（v1.0）
12. 修复安卓端在线更新崩溃的问题（v1.1）
13. 修复初次打开书籍时同步失败的问题（v1.2）
14. 添加支持设置独立的书籍云端目录（与元数据云端目录分离）（v1.2）
15. 添加前置网络配置检查（v1.3）
16. 添加元数据省心同步模式快捷设置（v1.3）
17. 修正同步记录、元数据等临时文件夹的路径拼接问题（v1.3）
18. 移除调试日志（v1.3）

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request

#### 项目地址

- Gitee : https://gitee.com/gytwo/cloudlibrary.koplugin
- GitHub: https://github.com/gytwo/cloudlibrary.koplugin