CasaOS上のMatrix Synapseに「container is unhealthy」と表示された場合は、無闇に再インストールするのではなく、まずコンテナのログと生成されたhomeserver.yamlを確認してください。Synapseには公式Dockerイメージがありますが、本番用のホームサーバーには、永続的な設定・データ、適切なサーバー名、PostgreSQL、HTTPSとフェデレーションの計画も必要です。
SQLiteはテストには使用できますが、現在のSynapseドキュメントでは、ほぼすべての実運用インストールでPostgreSQLが推奨されています。設定、データベース、権限、または起動時のマイグレーションに失敗すると、コンテナが起動していてもunhealthyのままになることがあります。
公式Synapseイメージを使用する
現在のSynapseインストールガイドでは、ghcr.io/element-hq/synapseが公式コンテナイメージとして案内されています。
初期設定を生成する
永続ディレクトリを作成し、通常の起動前に一度設定を生成します。
mkdir -p /DATA/AppData/synapse
docker run --rm -it -v /DATA/AppData/synapse:/data -e SYNAPSE_SERVER_NAME=matrix.example.com -e SYNAPSE_REPORT_STATS=no ghcr.io/element-hq/synapse:latest generate例のドメインを、今後使用するMatrixサーバー名に置き換えてください。
コンテナがunhealthyになっている理由を確認する
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseYAMLエラー、ファイル不足、権限エラー、データベース接続エラー、または完了していないマイグレーションがないか確認してください。
本番環境ではPostgreSQLを使用する
現在のSynapse PostgreSQLガイドでは、サポートされているデータベース設定が説明されています。PostgreSQLのデータを永続化し、Synapseの状態と併せてバックアップしてください。
計画なしにserver_nameを後から変更しない
Matrix IDは、@user:example.comのようにサーバー名から生成されます。ユーザーを招待する前に、長期的に使用するドメインを決めてください。
実用上はHTTPSが必要
Synapseは通常、HTTP（一般的にはポート8008）で内部的に待ち受けます。コンテナの生のポートを公開するのではなく、クライアントとフェデレーションにはHTTPS対応のリバースプロキシを使用してください。
フェデレーションには追加のDNSとプロキシ設定が必要
他のMatrixサーバーと通信する場合は、公開サーバー名、HTTPS、フェデレーションのディスカバリーを正しく設定してください。ローカル限定のテストなら、構成ははるかに簡単です。
コンテナ以外もバックアップする
homeserver.yaml、署名キー、アップロード済みメディア、PostgreSQLデータベースを保持してください。イメージを再取得しても、ホームサーバーのIDは復元されません。
Dockerトラブルシューティングガイドでは、コンテナをデバッグするための一般的な考え方を説明しています。
永続データフォルダーの所有者を確認する
コンテナログにhomeserver.yaml、署名キー、またはメディアの読み取り時にpermission deniedと表示される場合は、イメージが想定するUID/GIDに合わせて、Synapseのデータディレクトリをマウントしているフォルダーの所有者を修正してください。CasaOSのデータツリー全体を誰でも書き込み可能にすることは避けてください。
ヘルス状態を判断する前にデータベースのマイグレーションを待つ
アップグレード後やPostgreSQLへの初回接続時には、Synapseがスキーマのマイグレーションを実行するために時間がかかる場合があります。コンテナを何度も再起動するのではなく、ログを確認してください。マイグレーションが中断されると、診断が難しくなることがあります。
リバースプロキシの前にローカルAPIをテストする
HTTPS、DNS、フェデレーションを追加する前に、CasaOSホストから内部のSynapse HTTPエンドポイントが応答することを確認してください。ローカルAPIがunhealthyなら、リバースプロキシで修復することはできません。
よくある質問
Synapseがunhealthyになるのはなぜですか？
ログとヘルス出力を確認し、設定、権限、データベース、またはマイグレーションのエラーを探してください。元のスレッドには、検証済みの単一の原因は示されていません。
SQLiteは使用できますか？
テスト用途なら使用できます。現在のSynapseドキュメントでは、ほぼすべての本番インストールでPostgreSQLが推奨されています。
Synapseは内部でどのポートを使用しますか？
一般的なDocker構成では、リバースプロキシの背後でクライアント／サーバーAPIにポート8008を使用します。
Elementは必要ですか？
いいえ。Synapseはホームサーバーであり、Elementは利用可能なクライアント／Webフロントエンドの一つです。
