同步 Gramps Web 和 Gramps Desktop

Gramps Web Sync 是一个 Gramps 的插件，允许将您桌面计算机上的 Gramps 数据库与 Gramps Web 同步，包括媒体文件。

Warning

与任何同步工具一样，请不要将其视为备份工具。一侧的意外删除将传播到另一侧。确保定期创建家庭树的备份（以 Gramps XML 格式）。

Info

文档参考的是最新版本的 Gramps Web Sync 插件。如果需要，请使用 Gramps 插件管理器将插件更新到最新版本。

安装

该插件需要运行在 Python 3.10 或更新版本上的 Gramps 6.0。 它在 Gramps Desktop 中可用，可以 以常规方式安装。

Warn

请确保在桌面上使用的 Gramps 版本与服务器上运行的版本相同。请参阅 获取帮助 部分以了解如何查找服务器上运行的 Gramps 版本。Gramps 版本的格式为 MAJOR.MINOR.PATCH，并且在 Web 和桌面上 MAJOR 和 MINOR 必须相同。

可选步骤：

Gnome 密钥环 bug

目前在 python keyring 中存在一个 bug，影响许多 Gnome 桌面配置。您可能需要创建配置文件 ~/.config/python_keyring/keyringrc.cfg 并将其编辑为如下所示：

[backend]
default-keyring=keyring.backends.SecretService.Keyring

• 安装 keyring（例如 sudo apt install python3-keyring 或 sudo dnf install python3-keyring）以允许安全地将 API 密码存储在系统的密码管理器中。

使用

安装后，该插件在 Gramps 中可用，路径为 工具 > 家谱处理 > Gramps Web Sync。启动后，在确认将丢弃撤消历史的对话框后，向导将引导您完成同步步骤。请注意，在您明确确认之前，不会对您的本地树或服务器应用任何更改。

步骤 1：输入服务器凭据

该工具将询问您 Gramps Web 实例的基本 URL（示例：https://mygrampsweb.com/）、您的用户名和密码。您需要一个至少具有编辑权限的帐户才能将更改同步回远程数据库。用户名和 URL 将以明文形式存储在您的 Gramps 用户目录中，密码仅在安装了 keyring 的情况下存储（见上文）。

步骤 2：审查更改

在确认您的凭据后，该工具将比较本地和远程数据库，并评估是否存在任何差异。如果有，它将显示属于以下类别的对象更改列表（对象可以是人、家庭、事件、地点等）：

• 本地添加
• 本地删除
• 本地修改
• 远程添加
• 远程删除
• 远程修改
• 同时修改（即在两侧）

该工具使用时间戳来评估每个对象的较新一侧（如果您对详细信息感兴趣，请参见下面的“背景”）。

如果更改看起来符合预期，您可以单击“应用”将必要的更改应用于本地和远程数据库。

高级：同步模式

在更改列表下方，您可以选择同步模式。

默认的 双向同步 意味着它将通过复制检测到的更改（本地添加的对象将在远程侧添加等）来对两侧（本地和远程）应用更改。在两侧修改的对象也将合并并在两侧更新。

选项 将远程重置为本地 将确保远程 Gramps 数据库与本地数据库完全相同。任何被检测为“远程添加”的对象将被再次删除，被检测为“远程删除”的对象将再次添加等。不会对本地 Gramps 数据库应用任何更改。

选项 将本地重置为远程 以相反的方式工作，将本地状态设置为远程数据库的状态。不会对远程数据库应用任何更改。

最后，选项 合并 类似于双向同步，因为它修改两个数据库，但它不会删除任何对象，而是恢复仅在一侧删除的所有对象。

步骤 3：同步媒体文件

在 数据库同步后，工具会检查是否有任何新的或更新的媒体文件。如果找到，它将显示一个列表并请求确认上传/下载必要的文件。

请注意媒体文件同步的以下限制：

• 如果本地文件的校验和与存储在 Gramps 数据库中的校验和不同（例如，Word 文件在添加到 Gramps 后被编辑时可能会发生这种情况），上传将失败并显示错误消息。
• 该工具不会检查所有本地文件的完整性，因此如果本地文件存在于存储的媒体对象路径下，但该文件与服务器上的文件不同，工具将无法检测到。请使用媒体验证插件来检测具有不正确校验和的文件。

故障排除

调试日志

如果您在使用 Sync 插件时遇到问题，请通过 从命令行启动 Gramps 并启用调试日志，使用以下选项：

gramps --debug grampswebsync

这将打印许多有助于您识别问题原因的日志语句到命令行。

服务器凭据

如果第一步已经失败，请仔细检查服务器 URL、您的用户名和密码。

权限问题

如果您遇到与权限相关的错误，请检查您的 Gramps Web 用户帐户的用户角色。只有当您是具有编辑者、所有者或管理员角色的用户时，才能对远程数据库应用更改。

意外的数据库更改

如果同步工具检测到您认为没有发生的更改，可能是某个数据库中存在不一致，导致 Gramps 检测到差异，或者您的本地计算机和服务器之间的时间不同步。

请检查两台机器的时钟是否正确设置（请注意，时区无关紧要，因为该工具使用 Unix 时间戳，时间戳与时区无关）。

您还可以在本地数据库上运行检查和修复工具，看看这是否有帮助。

确保本地数据库中的不一致不会导致误报的一个粗暴但有效的方法是将数据库导出为 Gramps XML，并将其重新导入到一个新的空数据库中。这是一个无损操作，但确保所有数据都一致导入。

超时错误

如果您遇到超时错误（例如，通过 HTTP 状态 408 错误或其他包含“超时”一词的错误消息指示），这可能是由于需要同步到远程侧的大量更改以及您的服务器设置造成的。

对于 v1.2.0 之前的同步插件版本和 v2.7.0 之前的 Gramps Web API 版本（请参见 Gramps Web 中的版本信息选项卡），服务器端的同步是在单个请求中处理的，该请求会超时，具体取决于服务器配置，超时可能发生在一到几分钟内。对于大规模同步（例如，在本地数据库中导入数千个对象后，或尝试将完整的本地数据库同步到空的服务器端数据库），这可能太短。

如果您使用的是 v1.2.0 或更高版本的同步插件和 v2.7.0 或更高版本的 Gramps Web API，则服务器端同步由后台工作程序处理，可以运行很长时间（将显示进度条），并且不应发生超时错误。

意外的媒体文件错误

如果上传媒体文件失败，通常是由于磁盘上实际文件的校验和与本地 Gramps 数据库中的校验和不匹配。这通常发生在可编辑文件（如在 Gramps 外部编辑的办公文档）上。请使用 Gramps 媒体验证插件来纠正所有媒体文件的校验和。

请求帮助

如果以上所有方法都无效，您可以通过在 Gramps 论坛的 Gramps Web 类别 中发帖向社区寻求帮助。请确保提供：

• Gramps Web Sync 插件的版本（请使用最新发布的版本）
• 您使用的 Gramps Desktop 的版本
• 按照上述说明启用的 Gramps 调试日志的输出
• Gramps Web 的版本信息（您可以在设置/版本信息下找到）
• 您可以提供的有关 Gramps Web 安装的任何详细信息（自托管、Grampshub 等）
• 如果您可以访问 Gramps Web 服务器日志，请提供其输出（使用 docker 时：docker compose logs --tail 100 grampsweb 和 docker compose logs --tail 100 grampsweb-celery）

背景：插件的工作原理

如果您对插件的实际工作原理感到好奇，可以在本节中找到更多细节。

该插件旨在保持本地 Gramps 数据库与远程 Gramps Web 数据库的同步，以允许本地和远程更改（协作编辑）。

它不适合

• 与不是本地数据库的直接衍生物（从数据库副本或 Gramps XML 导出/导入开始）的数据库同步
• 合并两侧都有大量更改且需要手动处理的两个数据库。请使用优秀的 导入合并工具 来实现这一目的。

该工具的操作原理非常简单：

• 它比较本地和远程数据库
• 如果存在任何差异，它会检查最新相同对象的时间戳，我们称之为 t
• 如果在一个数据库中存在比 t 更新的对象，但在另一个数据库中不存在，则将其同步到两个数据库（假设为新对象）
• 如果在 t 之前最后一次更改的对象在一个数据库中缺失，则在两个数据库中删除（假设为删除对象）
• 如果一个对象不同但在 t 之后仅在一个数据库中更改，则同步到另一个数据库（假设为修改对象）
• 如果一个对象不同但在两个数据库中都在 t 之后更改，则合并它们（假设为冲突修改）

该算法简单而稳健，因为它不需要跟踪同步历史。然而，当您经常同步时，它的效果最佳。