Gramps Web と Gramps Desktop の同期¶

Gramps Web Sync は、デスクトップコンピュータ上の Gramps データベースと Gramps Web をメディアファイルを含めて同期するための Gramps のアドオンです。どちら側で行われた変更ももう一方に反映されるため、同じ家系図をローカルとウェブの両方で作業することができます。

あらゆる同期ツールと同様に、これはバックアップではありません：片方で何かを削除すると、もう片方でも削除されます。Gramps XML 形式で家系図の定期的なバックアップを保持してください。

インストール¶

このアドオンは、Python 3.10 以降で動作する Gramps 6.0 を必要とします。Gramps Desktop で利用可能で、通常の方法でインストールできます。このドキュメントはアドオンの最新バージョンについて説明しています。必要に応じて Gramps アドオンマネージャーを使用して更新してください。

デスクトップとサーバーは同じバージョンの Gramps を実行する必要があります。バージョンは MAJOR.MINOR.PATCH の形式で、MAJOR と MINOR は一致しなければなりません。サーバーが実行している Gramps のバージョンを確認する方法については、ヘルプを取得してください。

サーバー要件¶

アドオンは接続するとすぐにサーバーについて2つのことを確認し、どちらかが満たされていない場合はメッセージを表示して停止します：

Gramps Web API バージョン 3.x。 このアドオンのバージョンは Gramps 6.0 用で、Gramps Web API 3 と連携します。古いサーバーは更新が必要です；新しい API メジャーバージョンを実行しているサーバーは、アドオンではなく新しいバージョンの Gramps が必要です。各 Gramps リリースラインは1つの API バージョンとペアになっています。サーバーのバージョンは Gramps Web の 設定 ▸ バージョン情報 で確認できます。
バックグラウンドタスクキュー。 変更はサーバー上でバックグラウンドタスクとして適用されます。タスクキューがないと、これは同期的に実行され、実際の家系図でタイムアウトします。

リモートデータベースに変更を適用するには、エディター、オーナー、または管理者の役割を持つアカウントが必要です。

パスワードの保存 (オプション)¶

API パスワードをシステムのパスワードマネージャーに保存するために keyring をインストールします（例：sudo apt install python3-keyring または sudo dnf install python3-keyring）。キーニングが使用できない場合、アドオンはその旨を通知し、パスワードを毎回尋ねます。

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:// で始まるアドレスを入力すると、アドオンは入力中に警告を表示します。なぜなら、パスワードが平文で送信されるからです。

同期する各サーバーは別々に保存され、最後に同期された日時の記録とともに保存されるため、2つのサーバーを交互に使用してもどちらにも影響を与えません。各エントリは、最後に同期されたローカル家系図も記録します。アドオンは、それが開いているツリーと一致する場合のみ自動的に接続します。それ以外の場合は接続の詳細を表示し、接続を押すのを待ちます。

何も書き込まれていない間に利用できる2つのアクションがあります：

サーバーを変更…、上部のストリップで接続の詳細に戻り、このツリーを別のサーバーにポイントできます。進行中の比較を中断し、終了を待つ必要はありません。
このサーバーを忘れる、接続ペインで保存されたアドレス、ユーザー名、パスワード、およびこのツリーが最後に同期された日時の記録を削除します。次の同期では、2つのツリーを最初から比較します。

変更の確認¶

アドオンはローカルデータベースとリモートデータベースを比較し、どのデータベースに変更を加えるかを提案するアクションを表示します：

▾ このコンピュータで変更される予定 (7 オブジェクト)
    ▾ 3 オブジェクトを追加
        人物   ジョン・スミス        I0123
    ▾ 4 オブジェクトを更新
        …
▾ サーバーで変更される予定 (5 オブジェクト)
    …

各行にはオブジェクトの名前が表示され、誰または何が影響を受けるかがわかります。削除される予定のオブジェクトがある場合、リストの上に何個のオブジェクトがどちら側で削除されるかのメモが表示されます。

適用を押して、リストに記載された内容を実行します。

同期ウィンドウは Gramps の他の部分をブロックしないため、リストが開いている間も作業を続けることができます。その間に影響を受けるオブジェクトを編集すると、アドオンは適用を押したときにそれに気づき、何も変更せずに停止し、再度比較するように求めます。

同期モード¶

同期モードは変更のリストの上に選択されます。変更するとリストが再構築されます。なぜなら、モードが各差分が何になるかを決定するからです。

双方向同期（デフォルト） – 両側の変更が組み合わされます。両方の場所で編集されたオブジェクトはマージされます。
このコンピュータに合わせてサーバーをリセット – サーバーがこのコンピュータに合わせられます。サーバー上でのみ変更されたものは破棄されます。
サーバーに合わせてこのコンピュータをリセット – このコンピュータがサーバーに合わせられます。ここでのみ変更されたものは破棄されます。

バージョン 1.5 より前に利用可能だった マージ モードは削除されました。これは、削除されたオブジェクトを伝播するのではなく、一方で削除されたオブジェクトを復元する点で双方向同期と異なっていました。これに依存していた場合は、双方向同期を使用し、バックアップから保持したいものを復元してください。

メディアファイル¶

メディアファイルは、別のステップではなく、同じ確認の一部として扱われます。転送が必要なファイルがある場合、リストの下にそれらを移動するためのチェックボックスが表示されます：

[x] 12 のメディアファイルも転送する (4 をダウンロード、8 をアップロード)

チェックを外すと、ファイルに触れずにオブジェクトの変更を同期します。

両方の側で欠落しているファイルは別にリストされます。なぜなら、それに対して何もできないからです：

2 のメディアファイルが両方の側で欠落しており、転送できません。

メディアファイルの同期には2つの制限があります：

ローカルファイルが Gramps データベースに保存されているものと異なるチェックサムを持っている場合（これは Gramps に追加された後に編集された Word ファイルなどで発生する可能性があります）、アップロードはエラーメッセージとともに失敗します。
ツールはすべてのローカルファイルの整合性を検証しません。メディアオブジェクトのために保存されたパスの下にファイルが存在するが、サーバー上のファイルと異なる場合、ツールはそれを検出しません。誤ったチェックサムを持つファイルを見つけるには、Media Verify Addon を使用してください。

同期が失敗した場合¶

同期が途中で失敗した場合（例えば、接続が切れた場合）、アドオンは既に適用した内容を報告し、再試行 を提供します。これにより、失敗したステップから再開され、最初からやり直すことはありません。リモートツリーのダウンロードコピーは保持されるため、再試行しても再度ダウンロードして比較することはありません。

失敗の技術的詳細は詳細の展開器の後ろにあり、バグ報告用にコピーするためのボタンがあります。

トラブルシューティング¶

予期しない変更。 アドオンが驚くべき数の削除を提案する場合、まず上部のストリップを確認してください：それは書き込もうとしているサーバー上の家系図の名前を示しています。異なるツリーを持つサーバーに対してツリーを同期すると、まさにこの症状が発生します。

それ以外の場合、予期しない差異は、データベースの一方における不整合や、コンピュータとサーバー間の時計が同期していないことから生じる可能性があります。両方の時計が正しく設定されていることを確認してください（タイムゾーンは関係ありません。ツールは Unix タイムスタンプを使用します）し、ローカルデータベースでチェックと修復ツールを実行してください。最後の手段として、ローカルデータベースを Gramps XML にエクスポートし、新しい空のデータベースに再インポートします。これはロスレス操作ですが、すべてのデータが一貫して保存されることを保証します。

メディアファイルエラー。 アップロードの失敗は、ディスク上のファイルのチェックサムとローカル Gramps データベースのチェックサムが一致しないことが原因であることが多く、これは Gramps の外で編集されたオフィス文書などの編集可能なファイルで発生します。チェックサムを修正するには、Gramps Media Verify Addon を使用してください。

権限エラー。 Gramps Web ユーザーアカウントの役割を確認してください：エディター、オーナー、および管理者のみがリモートデータベースに変更を適用できます。

ヘルプを求める¶

上記のいずれも役に立たない場合は、Gramps フォーラムの Gramps Web カテゴリに投稿してコミュニティに尋ねてください。次の情報を提供してください：

同期ウィンドウの下部に表示される Gramps Web Sync アドオンのバージョン（最新のリリースバージョンを使用してください）
使用している Gramps デスクトップのバージョン
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 のエクスポート/インポートから始まる）でないデータベースとの同期、
両側に多くの変更があり、マージのために手動で注意が必要な2つのデータベースをマージすること。これには優れたインポートマージツールを使用してください。

動作原理はシンプルです：

ローカルデータベースとリモートデータベースを比較します。
差異がある場合、最新の同一オブジェクトのタイムスタンプを確認します。これを t と呼びます。
一方のデータベースに t よりも最近変更されたオブジェクトが存在し、他方には存在しない場合、それは両方に同期されます（新しいオブジェクトと仮定）。
t の前に最後に変更されたオブジェクトが一方のデータベースに存在しない場合、それは両方で削除されます（削除されたオブジェクトと仮定）。
オブジェクトが異なりますが、t の後に一方のデータベースでのみ変更された場合、それを他方に同期します（修正されたオブジェクトと仮定）。
オブジェクトが異なりますが、両方のデータベースで t の後に変更された場合、それらをマージします（競合する変更と仮定）。

最後の成功した同期の時刻も記録され、各サーバーごとに別々に保存され、最新の同一オブジェクトよりも新しい場合は t として使用されます。

このアルゴリズムはシンプルで堅牢であり、同期履歴を追跡する必要がありません。しかし、頻繁に同期する 場合に最も効果的です。