同步 Gramps Web 和 Gramps Desktop¶

Gramps Web Sync 是 Gramps 的一个插件，用于将您桌面计算机上的 Gramps 数据库与 Gramps Web 同步，包括媒体文件。无论在哪一方进行的更改都会传递到另一方，因此您可以在本地和网络上处理同一个家谱。

像任何同步工具一样，它不是备份：如果您在一方删除了某些内容，另一方也会被删除。请定期备份您的家谱，格式为 Gramps XML。

安装¶

该插件需要运行在 Python 3.10 或更高版本上的 Gramps 6.0。它可以在 Gramps Desktop 中使用，并可以以常规方式安装。本文件描述了该插件的最新版本；如有需要，请使用 Gramps 插件管理器进行更新。

您的桌面和服务器必须运行相同版本的 Gramps。版本的格式为 MAJOR.MINOR.PATCH，MAJOR 和 MINOR 必须匹配。有关如何查找您的服务器正在运行的 Gramps 版本，请参见获取帮助。

服务器要求¶

该插件在连接时会检查您服务器的两个方面，在下载任何内容之前，如果不满足其中任何一项，则会停止并显示消息：

Gramps Web API 版本 3.x。 该插件的此版本适用于 Gramps 6.0，支持 Gramps Web API 3。较旧的服务器需要更新；运行更新 API 主版本的服务器需要更新的 Gramps，而不是更新的插件，因为每个 Gramps 版本线与一个 API 版本配对。您可以在 Gramps Web 的 设置 ▸ 版本信息 下找到服务器的版本。
后台任务队列。 更改在服务器上作为后台任务应用。如果没有任务队列，这将同步运行并在任何真实家谱上超时。

要对远程数据库应用更改，您需要具有编辑者、所有者或管理员角色的帐户。

存储您的密码（可选）¶

安装 keyring（例如 sudo apt install python3-keyring 或 sudo dnf install python3-keyring）以将 API 密码存储在系统的密码管理器中。如果无法使用密钥环，插件会提示并继续运行——您每次都会被要求输入密码。

在 Gramps Snap 包中，系统密钥环因限制而被阻止，直到您连接一次接口。当插件检测到这种情况时，会显示此命令：

snap connect gramps:password-manager-service

在许多 Gnome 桌面配置中，python keyring 的错误意味着您必须创建配置文件 ~/.config/python_keyring/keyringrc.cfg，内容如下：

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

使用¶

该插件在 Gramps 中可通过 工具 ▸ 家谱处理 ▸ Gramps Web Sync 访问。在确认对话框警告将丢弃撤消历史后，同步窗口将打开。在您明确确认之前，不会对您的本地树或服务器应用任何更改。

窗口顶部的条带显示您正在同步的家谱名称、所属帐户和地址，以及上次同步的时间。在底部，显示插件和服务器的 Web API 的版本，这在报告问题时很有用。

连接¶

如果您之前已同步过此家谱，并且您的密码已存储，插件将在打开时立即连接并直接进行比较。否则，它会询问您 Gramps Web 实例的基本 URL（示例：https://mygrampsweb.com/）、您的用户名和密码。

URL 和用户名以明文存储在您的 Gramps 用户目录中。只有在您勾选 记住密码 时，密码才会存储在系统密码管理器中；取消勾选会删除为该服务器存储的任何密码。如果您输入以 http:// 开头的地址而不是 https://，插件会在您输入时警告您，因为您的密码将以明文发送。

您同步的每个服务器都单独存储，并记录其上次同步的时间，因此您可以在两个服务器之间交替，而不会干扰任何一方。每个条目还记录了它上次从哪个本地家谱同步。插件仅在与您打开的树匹配时自动连接；否则，它会显示连接详细信息并等待您按连接。

在没有任何内容被写入时，可以执行两个操作：

更改服务器…，在顶部条带上，返回连接详细信息，以便您可以将此树指向不同的服务器。它会中断正在进行的比较，而不是让您等待完成。
忘记此服务器，在连接窗格上，删除存储的地址、用户名和密码，以及此树上次同步的记录。下次同步将从头开始比较两个树。

审查更改¶

插件比较本地和远程数据库，并显示它建议执行的操作，按更改的数据库分组：

▾ 将在此计算机上更改（7 个对象）
    ▾ 添加 3 个对象
        人物   约翰·史密斯        I0123
    ▾ 更新 4 个对象
        …
▾ 将在服务器上更改（5 个对象）
    …

每一行都命名对象，因此您可以知道谁或什么受到影响，而不仅仅是看到 Gramps ID。如果有任何内容将被删除，列表上方会有一条注释，说明有多少对象以及在哪一方。

按应用执行列表中描述的操作。

同步窗口不会阻止 Gramps 的其他部分，因此您可以在列表打开时继续工作。如果您在此期间编辑了受影响的对象，插件会在您按应用时注意到，停止而不更改任何内容，并要求您再次比较。

同步模式¶

同步模式在更改列表上方选择。更改它会重建列表，因为模式决定每个差异的处理方式。

双向同步（默认） – 来自两侧的更改会合并。在两个地方编辑的对象会被合并。
重置服务器以匹配此计算机 – 服务器将匹配此计算机。仅在服务器上更改的内容将被丢弃。
重置此计算机以匹配服务器 – 此计算机将匹配服务器。仅在此处更改的内容将被丢弃。

在 1.5 之前版本中可用的合并模式已被删除。它与双向同步的不同之处在于恢复在一侧删除的对象，而不是传播删除。如果您依赖于它，请使用双向同步并从备份中恢复您想保留的任何内容。

媒体文件¶

媒体文件作为同一确认的一部分处理，而不是作为单独的步骤。如果需要传输任何文件，列表下方的复选框会提供移动它们的选项：

[x] 还转移 12 个媒体文件（4 个下载，8 个上传）

取消勾选以同步对象更改而不触及文件。

在两侧缺失的文件将单独列出，因为对此无能为力：

2 个媒体文件在两侧都缺失，无法转移。

媒体文件同步有两个限制：

如果本地文件的校验和与存储在 Gramps 数据库中的校验和不同（例如，在添加到 Gramps 后编辑的 Word 文件），上传将失败并显示错误消息。
该工具不验证所有本地文件的完整性。如果在为媒体对象存储的路径下存在文件，但与服务器上的文件不同，工具将无法检测到。使用媒体验证插件查找校验和不正确的文件。

如果同步失败¶

如果同步在中途失败——例如，连接中断——插件会报告它已经应用的内容，并提供重试，这将在失败的步骤处恢复，而不是从头开始。远程树的下载副本将被保留，因此重试不会再次下载和比较它。

故障的技术细节可以在 详细信息 展开器后面找到，并提供一个按钮以便于复制以进行错误报告。

故障排除¶

意外更改。 如果插件建议大量删除，请首先检查顶部条带：它命名了您即将写入的服务器上的家谱。将树与持有不同树的服务器同步会产生完全相同的症状。

否则，您未预期的差异可能来自于其中一个数据库的不一致，或来自于您计算机与服务器之间的时钟不同步。检查两个时钟是否正确设置（时区无关紧要，因为该工具使用 Unix 时间戳），并在本地数据库上运行检查和修复工具。作为最后的手段，将您的本地数据库导出为 Gramps XML 并重新导入到一个新的空数据库中。这是一个无损操作，但确保所有数据一致存储。

媒体文件错误。 上传失败通常是由于磁盘上文件的校验和与本地 Gramps 数据库中的校验和不匹配造成的，这在外部编辑的可编辑文件（如办公文档）中很常见。使用 Gramps 媒体验证插件来修正校验和。

权限错误。 检查您的 Gramps Web 用户帐户的角色：只有编辑者、所有者和管理员可以对远程数据库应用更改。

请求帮助¶

如果以上都没有帮助，请通过在 Gramps 论坛的 Gramps Web 类别发布来询问社区。请提供：

Gramps Web Sync 插件的版本，在同步窗口底部显示，旁边是服务器的 Web API 版本（请使用最新发布的版本）
您使用的 Gramps Desktop 版本
Gramps Web 的版本信息，在 设置 ▸ 版本信息 下找到
有关您的 Gramps Web 安装的任何详细信息（自托管、Grampshub 等）
您的 Gramps Web 服务器日志的输出，如果您可以访问它们（使用 Docker 时：docker compose logs --tail 100 grampsweb 和 docker compose logs --tail 100 grampsweb-celery）

如果您被要求提供调试日志，请从命令行启动 Gramps 并启用调试日志，并重现问题：

gramps --debug grampswebsync

背景：插件如何工作¶

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

它不适合

与不是本地数据库直接派生（从数据库副本或 Gramps XML 导出/导入开始）的数据库同步，
合并两个在两侧都有大量更改需要手动处理的数据库。为此，请使用优秀的导入合并工具。

操作原理很简单：

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

最后一次成功同步的时间也会被记录，分别针对每个服务器，并在其比最新相同对象更新时用作 t。

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