データベース

yurucommuのデータは、1つのSQLデータベースだけに収まるものではありません。 アカウントや投稿はSQL、画像や動画はオブジェクトストレージ、一時的な状態は キー・バリューストア、非同期配送はキューが担当します。このページでは、 スキーマの全カラムではなく、保存先と更新・復旧の責任範囲を説明します。

保存先ごとの役割

SQLのバックアップだけでは、画像や動画まで含む完全な復旧にはなりません。 反対に、キューは配送中の作業を運ぶ場所であり、投稿や配送結果を保存する データベースの代わりではありません。

ローカルとリモートのActivityPubデータ

このサーバーで作成したアカウントは actors に保存します。ほかのサーバーから取得したプロフィールは actor_cache に保存し、ローカルアカウントとは区別します。リモートプロフィールは 再取得できるキャッシュですが、ローカルアカウントとして扱ってはいけません。

投稿などのActivityPubオブジェクトは、ローカルで作成したものも、 連合で受信したものも objects で扱います。各レコードはActivityPubのURLで識別され、 is_local で作成元を区別します。受信した投稿、アクティビティ、フォロー関係は タイムラインや通知の動作に使われるため、リモート由来という理由だけで 使い捨てのキャッシュとはみなしません。

スキーマの正本

テーブルと索引を更新するSQLの正本は、 @takosjp/yurucommu-core パッケージの migrations/ です。この製品リポジトリはcoreを利用して Workerを組み立てます。Takosumi向けには、ロック済みcoreのSQL本文を 自己完結したバンドルへ生成し、実行時に別のパッケージ取得を必要としない 配布用アーティファクトとして管理します。現在の構造を調べるときは、 利用中の共通パッケージに含まれるSQLとスキーマ定義を確認してください。

適用済みSQLの共通の履歴は yurucommu_migrations です。Cloudflare向けの wrangler.jsonc も、共通パッケージのSQL保存先とこの履歴の名前を指定しています。

マイグレーションを適用する責任

Workerコードの公開と、保存済みデータを変えるマイグレーションは別の作業です。 Workerを更新してもSQLは自動では適用されません。先にコードだけを戻せるのか、 データも復元する必要があるのかを分けて判断してください。

Takosumiなどの管理ホスト

管理経路の正本は deploy/takoform です。 ここにはSQLデータベース、オブジェクトストレージ、KV、2本のキューなど、 Yurucommuが必要とするものが書かれています。実際にどのサービスで実現するかは ホストが決めるため、Cloudflare D1を前提にはしていません。

deploy/takoform/migrations/schema-bundle.json には、ロック済みcoreから生成したSQL本文、SQL一覧、各SQLのハッシュが 1つの自己完結したバンドルとして記録されています。ホストはデータベース リソースのApply中に、このインストールが作成したデータベースを特定し、 選んだバージョンに含まれる一覧を使ってSQLを適用して結果を記録します。 完了するまでデータベースをReadyにしません。 似た名前のデータベースだけを根拠にSQLを実行しません。

Cloudflareへ直接セルフホストする場合

ルートの main.tf または wrangler.jsonc を使う経路では、Cloudflareアカウントを管理する運用者がD1の更新を担当します。 対象データベース、現在の適用履歴、バックアップ、復旧方法を確認してから、 共通パッケージのSQLを適用し、結果を読み返してください。

古い環境にWrangler既定の d1_migrations が残っていることがあります。現在のSQL一覧と先頭から同じ順番で並んでいると 確認できる場合だけ yurucommu_migrations へ履歴をまとめます。途中の欠番、知らない名前、重複がある場合は、 先頭からSQLを再実行せず停止して調査してください。

更新前後に確認すること

1. 管理ホスト経由かCloudflareへの直接導入かを確認し、管理画面や実行結果から 対象データベースを一意に特定する
2. 使用する共通パッケージとSQL一式が、公開するWorkerと対応していることを 確認する
3. 現在の適用履歴を読み、バックアップと隔離した復元先を用意する
4. SQLを適用し、台帳と必要なテーブルを読み返す
5. /readyzを確認し、ログイン、投稿、画像アップロード、 外部配送も試す

途中で失敗した場合は、原因が分からないまま同じSQLを繰り返し実行しません。 適用済みの範囲を確認し、用意した復元手順または追加修正で回復します。

バックアップと復旧

Takosumiのインストール履歴や構成情報のバックアップと、 Yurucommuの投稿やメディアを含むサービスデータのバックアップは別物です。 管理ホストを使う場合も、インストール履歴と構成情報を保存しただけでは YurucommuのSQLデータやオブジェクトを復元できません。

• SQLデータベースとオブジェクトストレージを同じ復旧計画に含める
• 暗号化キーなど、復元後に必要な秘密情報の保管方法を確認する
• 本番を上書きせず、隔離した復元先でデータを読み取れることを試す
• 復元後に認証、投稿、メディア、連合配送を確認する

バックアップの作成方法、保持期間、復元先は、利用するホストやCloudflareの 運用手順に従います。データベースの書き出しファイルが存在するだけで、 復旧できると判断しないでください。

トラブルシューティング

Applyは成功したがテーブルがない

リソースの作成とSQLの適用は別工程です。管理ホストではApply後のSQL更新の 実行結果と対象データベースを確認します。Cloudflareでは Workerを公開しただけでSQL適用済みとは判断せず、 yurucommu_migrations を確認してください。

「すでに存在する」エラーやSQL適用履歴の不一致が出る

yurucommu_migrations と、存在する場合は d1_migrations の両方を読みます。未知の行、重複、途中の欠番があれば自動で埋めず、 使用中の共通パッケージと既存スキーマを照合してください。

/readyzが503になる

応答本文の status と missingBindings を確認します。まず DB、KV、APP_URL、 ENCRYPTION_KEY、認証方法を確認し、DBへの接続はあるのに クエリが失敗する場合は、SQL適用履歴とWorkerが利用する共通パッケージの版を 照合します。

画像だけ保存できない

SQLではなく MEDIA の接続先と権限を確認します。CloudflareではR2、管理ホストでは オブジェクトストレージがこの役割です。DBの復旧後にメディアが欠ける場合も、 同じ接続先とオブジェクトストレージ側の復元結果を確認してください。

投稿は保存できるが外部へ届かない

DELIVERY_QUEUE と DELIVERY_DLQ、 それぞれのキューを処理するWorker、最後の失敗理由を確認します。 SQLデータベースが正常でも、キューの接続や処理が止まっていれば 外部配送は進みません。

接続名とデプロイ経路の詳細は デプロイ、 Cloudflareの設定は Cloudflare設定 を参照してください。