トラブルシューティング

よくある問題とその原因、解決方法です。ほとんどの場合、まずサービスの Logs を確認します。ビルドの出力とアプリ自身の出力が見られます（ログ）。

サーバー

セットアップで接続できない

• 接続がタイムアウトする、拒否される：クラウドプロバイダーのファイアウォールやセキュリティグループで SSH ポートが閉じているか、アドレスやポートが間違っています。セットアップ中は SSH ポートをどこからでも許可し、終わったら閉じて構いません（要件）。
• 認証に失敗する：SSH ユーザーを確認してください。クラウドイメージは root ログインを無効にしていることが多いので、ubuntu、debian、ec2-user を使います。鍵は .pub ファイルではなく秘密鍵で、パスフレーズがないものが必要です（サーバーを追加）。
• sudo がパスワードを求める：ユーザーにパスワードなしの sudo が必要です。または root で接続してください。
• ホスト鍵が変わった：サーバーのフィンガープリントが最初のセットアップ時と異なると、Zenavo は接続を拒否します。意図的にマシンを再インストールしたのなら、サーバーを削除して追加し直してください。そうでなければ、先に原因を確認してください。

インストール中にセットアップが失敗する

サーバーの Status タブにあるセットアップログの最後の数行を確認します。よくある原因：

• ポート 80 または 443 が使用中：Docker、Nginx、Apache などの Web サーバーが使っています。サーバーは Zenavo 専用にするべきです。それらを停止・無効化してから Retry setup を押してください。
• メモリまたはディスクが足りない：メモリ 2 GB 以上、空きディスク 20 GB 以上が必要です（要件）。
• 中国本土でダウンロードがタイムアウトする：ログに、セットアップがどのソースを選んだかが表示されます（中国本土のサーバー）。
• エージェントが接続しない：サーバーから Zenavo コンソールへの送信方向の HTTPS（ポート 443）が必要です。

再試行すると、完了したステップはスキップされます。

サーバーが Offline と表示される

数分間、サーバーのエージェントから Zenavo に応答がありません。サーバー上のプロジェクトは動き続け、止まるのはデプロイとライブデータだけです。マシンが起動しているか、送信方向の HTTPS が通るか、メモリやディスクが不足していないかを確認してください。エージェントが戻れば状態は自動で Running に戻ります。戻らない場合は Settings → Run setup で、動いているものに触れずにエージェントを再インストールできます（サーバーの管理）。

ビルド

言語の検出が間違っている、ビルドプランが検出されない

zbpack はルートディレクトリのファイルを見て判断します。モノレポでは Root directory をアプリのフォルダーにしてください。ビルドを完全に制御したい場合は Dockerfile を追加するか、ZBPACK_BUILD_COMMAND や ZBPACK_START_COMMAND などの zbpack options を設定します（ビルドプラン）。

ビルドが失敗する

Logs → Build Logs を開きます。最後のエラーがたいてい原因です。依存関係の不足、ビルドスクリプトの失敗、ビルドに必要な値の不足などです。Variables タブの変数はそのままではビルドに渡されません。ビルドに必要なものはビルド引数として参照してください。同じビルドをローカルで docker build . してみると、アプリの問題かプラットフォームの問題かを切り分けられます。

ビルドが待たされる、止まる

• ビルドマシン待ち：プランの同時ビルド数を使い切っているか、共有ビルドマシンが混んでいます（ビルドキュー）。
• タイムアウト：プランの最長ビルド時間を超えるとビルドは停止します（使用量と請求）。
• 拒否される：ワークスペースのその月のビルド時間を使い切っています。ビルド済みイメージのデプロイは引き続きできます。

デプロイ

デプロイが healthy にならない

新しいインスタンスは起動したものの、ヘルスチェックに合格していません。古いインスタンスはそのまま応答を続けます。よくある原因：

• アプリが localhost や固定ポートで待ち受けている。 0.0.0.0 と PORT 変数で待ち受けてください（フレームワーク）。
• ポートが違う。 Networking のサービスのポートは、アプリが実際に待ち受けるポートと同じでなければなりません。
• ヘルスチェックのパスが 404 を返す、またはアプリの起動に時間がかかる。パスを直すか、開始猶予時間を延ばしてください。

失敗したデプロイには、最後のチェックの理由とインスタンスの最新ログが表示されます。

サービスがクラッシュを繰り返す、一時停止された

コンテナが起動直後に終了しています。Logs でエラーを確認してください。変数の不足、データベースに接続できない、起動時のクラッシュなどです。メモリの使いすぎで強制終了されたサービスも再起動します。その場合はメモリ上限を上げてください（サービス設定）。クラッシュ上限の回数だけ再起動すると、Zenavo はサービスを一時停止します。原因を直してから再開するか、もう一度デプロイしてください。

イメージ転送のためにデプロイが拒否される

ワークスペースが利用上限に達したか、Free プランに含まれるイメージ転送を使い切っています。動いているサービスはそのまま動き続けます。上限を上げるかプランをアップグレードしてください（イメージ転送と利用上限）。

サービスから別のサービスに接続できない

公開ドメインや localhost ではなく、相手のプライベートホスト名 <hostname>.zenavo.internal と、相手が待ち受けるポートを使ってください。両方のサービスが同じプロジェクトにある必要があります。相手のサービスの Networking タブの Private にアドレスが表示されています（プライベートネットワーク）。

ドメインと HTTPS

証明書がずっと Pending のまま

Let's Encrypt がまだドメインを確認できていません。サービスの Overview で Pending にカーソルを合わせると理由が表示されます。よくある原因：

• DNS レコードがまだサーバーを向いていない。 dig +short app.example.com で確認し、サーバーの IP アドレスが表示されれば OK です。新しいレコードが反映されるまで時間がかかることがあります。
• ポート 80 が閉じている。 Let's Encrypt は HTTP でドメインを確認します。
• Cloudflare のプロキシが有効で、SSL が Flexible になっている。Full (strict) にするか、証明書が発行されるまでプロキシを無効にしてください。

状態はおよそ 1 分ごとに更新されます（ドメインと HTTPS）。

ドメインで 404 やエラーページが表示される

• 404 page not found：ドメインはサーバーに届いていますが、どのサービスにも設定されていません。サービスの Networking タブで設定してください。
• Bad gateway または Service unavailable：ドメインは設定されていますが、サービスが動いていないか、ドメインのルーティング先とは別のポートで待ち受けています。

アカウントとアクセス

サーバーの追加やデプロイができない

まずメールアドレスを確認してください。Zenavo から届いたメールのリンクを開くか、Account settings から再送します（アカウント）。Viewer は何もデプロイ・変更できません。チームの管理者に Member ロールへの変更を依頼してください（チームとロール）。

二要素認証のデバイスをなくした

リカバリーコードでサインインしてください（二要素認証）。リカバリーコードもない場合は、アカウントのメールアドレスから info@zenavo.app に連絡してください。

それでも解決しないときは

プロジェクトまたはサーバーの ID（Settings でコピーできます）、発生した日時、ログの内容を添えて info@zenavo.app にメールしてください。パスワード、鍵、変数の値は絶対に送らないでください。