Kopano WebAppの「Kopano Coreに接続できません」エラーを修正する

Kopano WebApp の「Kopano Core に接続できません」エラーを最も迅速に解決するには、実際に問題が発生しているレイヤー ( Kopano Core 自体、WebApp から Core へのエンドポイント、またはWebApp が Core との通信に使用するPHP-MAPI レイヤー)のどれかを特定することです。すべてを再起動すると一時的に問題が解決するように見える場合もありますが、原因が隠蔽され、再発する障害の診断が困難になる可能性があります。

Kopanoの公式WebAppドキュメントによると、WebAppはに依存しておりphp-mapi、そのDEFAULT_SERVER設定によってWebAppがKopano Coreに接続する場所が制御されます。ドキュメントに記載されている選択肢には、ローカルUnixソケット、ポート236のHTTP、ポート237のHTTPSがあります。Kopano WebAppの設定ドキュメントとKopano Core管理者マニュアルを参照してください。

重要なバージョンに関する注意：執筆時点で入手可能なKopanoの公開管理者マニュアルは、多くの最新のLinuxディストリビューションよりも古いものです。そのため、パッケージ名、PHPバージョン、サービスラッパー、ログの場所などが、お使いの環境によって異なる場合があります。以下に説明する接続モデルと構成オプションは、Kopanoが公開しているドキュメントに基づいています。ただし、本番サーバーを変更する前に、ローカルパスとパッケージバージョンを確認してください。

最初に試すべき解決策はどれですか？

一度にすべての変更を加えるのではなく、まずはご自身のシステムに最も合致する症状から着手してください。

1. Kopano Coreは実際に稼働していますか？

WebAppの設定を編集する前に、サーバープロセスを確認してください。systemdベースのディストリビューションでは、以下を使用してください。

sudo systemctl status kopano-server

ユニットが故障しているか非アクティブ状態の場合は、再起動する前に最近のログを確認してください。

sudo journalctl -u kopano-server -n 100 --no-pager

データベース接続エラー、構成解析エラー、権限の問題、ファイルの欠落、または起動エラーを探してください。Kopano の Core ドキュメントには、構成変更には通常、影響を受けるコンポーネントを再起動する必要があると記載されています (例: ) systemctl restart kopano-<component>。また、 は/etc/kopano/server.cfg通常の構成ファイルとして記載されていますkopano-server。KCコンポーネントの構成を参照してください。

サービスが明らかに停止している場合、起動後にクラッシュする場合、または他の Kopano ツールも Core と通信できない場合は、この方法を選択してください。WebAppを先に修正しても、下流の症状に対処するだけです。

トレードオフ：再起動は最も迅速な復旧手段ですが、プロセスがすぐに再び失敗した場合、ジャーナル出力が必要になります。本番システムでは、最も明確な証拠を失わないよう、再起動前に障害の詳細を記録しておきましょう。

2. WebAppは正しいKopano Coreエンドポイントを指していますか？

WebAppでは、キー設定はDEFAULT_SERVERにありますconfig.php。Kopanoの公式WebAppマニュアルには、これらの例が記載されています。

define("DEFAULT_SERVER", "default:");
define("DEFAULT_SERVER", "file:///var/run/kopano/server.sock");
define("DEFAULT_SERVER", "http://localhost:236/kopano");
define("DEFAULT_SERVER", "https://localhost:237/kopano");

ドキュメントに記載されているデフォルト設定は、ローカルソケットにマッピングされますfile:///var/run/kopano/server.sock。WebAppとCoreが同じマシンで実行されている場合は、通常これが最も簡単な選択肢です。別々のマシンで実行されている場合は、ローカルUnixソケットは機能しません。代わりに、アクセス可能なHTTPまたはHTTPSエンドポイントが必要です。Kopanoのパフォーマンスチューニングに関するドキュメントでは、WebAppホストがポート236、またはSSLの場合はポート237を介して別のKopanoサーバーに接続する方法について説明しています。Kopanoのパフォーマンスチューニングとスプリットサーバー構成を参照してください。

ローカルUnixソケット：一般的に、単一ホスト上で最もオーバーヘッドの少ないオプションであり、ローカルWebアプリケーションへのアクセスのためだけにTCPサービスを公開する必要がありません。ただし、ソケットが存在し、Webサーバープロセスがそれを使用できる必要があります。

ポート236でのHTTP：ホスト間でのテストが容易で、セキュリティアーキテクチャが許容する場合、信頼できる内部ネットワークに適しています。ただし、Kopanoトランスポート層ではトラフィックが暗号化されないというトレードオフがあります。

ポート237でのHTTPS： WebAppとCore間の暗号化された通信が必要な場合に適しています。証明書の設定と検証が必要になります。Kopanoの特別な構成ドキュメントでは、WebAppがHTTPSを使用しDEFAULT_SERVER、場合によってはクライアント証明書を使用する例が示されています。Kopanoの特別なCore構成を参照してください。

3. Unixソケットを使用する場合、それは存在し、Webサーバーからアクセスできますか？

同一ホスト環境での展開の場合、ソケット自体を確認してください。

ls -l /var/run/kopano/server.sock
file /var/run/kopano/server.sock
ss -xl | grep kopano

ファイルが見つからない場合は、その名前で通常のファイルを作成しないでください。ソケットは実行中のKopanoサーバーによって作成されます。したがって、ソケットが見つからない場合は、通常、Coreの起動時の問題、ソケットパスの変更、または設定の不一致が原因です。

ソケットが存在する場合は、その所有権とモードを確認してください。Webサーバーユーザーは、ディレクトリパスを介してソケットにアクセスできる必要があります。ディストリビューションによっては、Webサーバーアカウントはwww-data、、、apacheまたは別のサービス固有のユーザーである場合があります。などの広範なモードで権限エラーを解決することは避けてください。chmod 777これはリスクを高め、サービスが次回ソケットを再作成する際に上書きされる可能性があります。

より良い方法は、WebAppをKopanoによって生成されたソケットの場所に合わせ、ディストリビューションが意図するグループまたはサービス権限を使用することです。サーバーがカスタマイズされている場合は、所有権を変更する前に、コア構成とWebAppエンドポイントを比較してください。

4. Coreは正常なのに、WebAppが接続できないと表示される場合はどうすればよいですか？

次に PHP-MAPI を確認してください。Kopano は WebApp が PHP-MAPI に依存していることを明示的に示しています。WebApp 構成チェックでは、PHP と PHP-MAPI の利用可能性もテストできます。WebApp Config.php のドキュメントをphp-mapi参照してください。

簡単なCLIチェックは以下のとおりです。

php -m | grep -i mapi

ただし、このテストには重要な制約があります。PHPコマンドラインインターフェースは、Apache PHP、PHP-FPM、またはその他のWebサーバー統合と同じ設定を使用していない可能性があります。CLIで肯定的な結果が得られたとしても、それはCLI環境がモジュールを認識していることを示しているにすぎません。

有用なフォローアップチェックには以下が含まれます。

php --ini
php -i | grep -i mapi

次に、それをウェブサーバーまたはFPMプールで使用されているPHP構成と比較します。パッケージが見つからない場合、またはバージョンに互換性がない場合は、ディストリビューションとKopanoリリース用に作成されたリポジトリから、対応するKopano Core/PHP-MAPIパッケージセットをインストールしてください。拡張機能を単に表示させるためだけに、関連性のないPHP-MAPIビルドを混在させないでくださいphp -m。

次の場合にこのルートを選択してください： kopano-serverは正常で、エンドポイントは正しく到達可能ですが、WebApp が PHP 側の接続または構成チェック中に失敗します。

トレードオフ：バイナリの不一致が発生した場合、パッケージの再インストールまたはアップグレードが適切な修復方法となる可能性がありますが、単一のエンドポイントを修正するよりもシステム全体に影響を与えます。まずパッケージのバージョンを確認し、本番環境のアップグレードを適切にスケジュールしてください。

Apache、PHP-FPM、またはKopanoサーバーを再起動する必要がありますか？

構成またはモジュールが実際に変更されたコンポーネントを再起動してください。

• 変更した場合は/etc/kopano/server.cfg、再起動してくださいkopano-server。
• PHP拡張機能をインストールまたは有効化した場合は、WebAppで使用されているPHPサーバー層（Apacheや関連するPHP-FPMサービスなど）を再起動してください。
• WebAppのPHP設定ファイルのみを変更した場合、Coreエンドポイント自体が変更されていない限り、通常はKopano Coreを完全に再起動する必要はありません。

ウェブサービスコマンドの正確な記述方法は、ディストリビューションやPHPパッケージによって異なります。例えばsystemctl restart apache2、systemctl restart httpd`<service>`、`<service>`、`<service>`、またはバージョン管理されたPHP-FPMユニットなどが挙げられます。コマンドをそのままコピーするのではなく、ホスト上で使用されているサービス名を使用してください。

リモートのコアサーバーやファイアウォールについてはどうでしょうか？

WebAppとKopano Coreが分離されている場合は、WebAppに問題があると判断する前に、まずルーティングと構成済みのリスナーを確認してください。Kopanoのドキュメントでは、HTTPアクセスはポート236、SSLアクセスはポート237で行われると説明されています。そのため、リモート展開では、ローカルのUnixソケット展開にはない、ファイアウォールルール、リスナーバインディング、DNS、TLS証明書、リバースプロキシ、中間ネットワークポリシーなど、いくつかの障害モードが発生します。

HTTPエンドポイントの場合、少なくともWebAppホストからTCPリスナーに到達可能かどうかを確認できます。

nc -vz core.example.net 236

HTTPSの場合、証明書ポリシーに適したツールを使用してTLSエンドポイントを別途検証してください。TCP接続が成功したからといって、Webアプリケーションの認証やMAPI操作が成功するとは限りませんが、接続が失敗した場合は、PHP-MAPIがそのアドレスとポートで設定されたサービスに到達できないことが証明されます。

リバースプロキシを使用する場合は、KopanoのドキュメントでプロキシパスとバックエンドマッピングがWebAppが使用するURLと一致している必要があることに注意してください。公式のCoreマニュアルには、Kopanoトラフィックのプロキシに関するHTTP/1.1の考慮事項も記載されています。Kopano Coreコンポーネント構成を参照してください。

不必要な変更を最小限に抑える実用的な診断手順

1. ステータスを確認してくださいkopano-server。エラーが発生している場合は、まずコアを修正してください。
2. コアログを確認してください。Webアプリが接続するには、データベースまたは構成の障害を解決する必要があります。
3. 検証しますDEFAULT_SERVER。ローカルソケットまたは正しいリモートHTTP/HTTPSエンドポイントと一致していることを確認してください。
4. 実際のソケットまたはネットワークリスナーをテストしてください。これにより、トランスポートの障害とPHPの問題を切り分けることができます。
5. PHP-MAPIをWebランタイムで検証してください。CLIのPHP環境だけに頼らないでください。
6. 影響を受けるサービスのみを再起動してください。その後、Webアプリを再テストし、エラーが解消されない場合はログを確認してください。

この手順は、パッケージの再インストールから始めるよりも安全です。なぜなら、証拠が保持され、各テストが意味のあるものになるからです。また、Kopano Core自体が起動できないときにWebAppやApacheを繰り返し再起動するという、逆のミスも回避できます。

DEFAULT_SERVERを変更することが間違った解決策となるのはどのような場合か？

DEFAULT_SERVERログインページに接続エラーが表示されたからといって、安易に変更しないでください。現在の値が意図したCoreインスタンスを正しく指している場合、変更すると元の問題が隠蔽されたり、ユーザーを誤ったバックエンドに誘導したりする可能性があります。

例えば、default:を に置き換えることhttp://localhost:236/kopanoは、必ずしもアップグレードではありません。これは、ドキュメントに記載されているローカルのデフォルトソケットから TCP にトランスポートを変更するものです。これはデバッグや TCP を必要とするトポロジーでは役立ちますが、セキュリティと運用上の制約も変わります。同一ホスト環境の場合、欠落しているソケットやアクセスできないソケットを修正する方が、別のリスナーを開くよりも多くの場合、よりクリーンな方法です。

エラーが解消されない場合はどうすればよいですか？

その時点で、関係する双方から証拠を収集する。

• DEFAULT_SERVER認証情報や機密情報が削除された、正確な値。
• systemctl status kopano-serverおよび最近のKopanoサーバーのログエントリ。
• ソケットの所有権またはリモートリスナー情報。
• ウェブサーバー実行環境におけるPHPのバージョンとロードされたMAPI拡張機能。
• ログイン失敗時のWebアプリケーション/PHPのエラーログ。

KopanoのWebアプリのドキュメントによると、PHPのエラーログはPHPの設定で有効にできますconfig.phpが、エラーを直接表示するとJSONレスポンスが破損する可能性があるため、表示しないように警告しています。そのため、サーバー側のログの方が診断に適しています。ログの詳細度を上げる前に、公式のWebアプリのログ設定を参照してください。

障害の原因がコアの起動、トランスポート、権限、PHP-MAPI、またはリモートネットワークのいずれにあるかを特定したら、そのレイヤーに対応する最小限の修正を適用してください。「Kopano Coreに接続できません」というエラーを単一のエラーとして扱い、万能な解決策を適用するよりも、この方法の方が信頼性が高くなります。