トラブルシューティング

ほとんどの問題は、PHP バージョン、ファイルのパーミッション、データベースの認証情報、ウェブサーバーのリライト設定、またはワーカーの欠如という少数の原因に起因します。このページでは、運営者がよく遭遇する症状とその解決策を一覧にまとめています。迷ったときは、PHP エラーログが最も早く真相に辿り着く手段です。

インストールの問題

「お使いの PHP バージョンはサポートされていません」

TubePress は PHP 8.2 以上が必要であり、他の処理より先に実行されるパース安全なバージョンガードによって強制されます。ホスティングパネルで PHP バージョンを切り替えるか（または vhost をより新しい PHP-FPM ソケットに向けて）リロードしてください。動作要件を参照してください。

「データベースに接続できませんでした」

インストーラーのデータベース設定ステップで、ホスト（通常は localhost または 127.0.0.1）、データベース名、ユーザー名とパスワード、およびそのユーザーが対象データベースへの権限を持っているかを再確認してください。データベースは事前に作成されている必要があります — インストーラーはテーブルを作成しますが、スキーマ自体は作成しません。

インストーラーが設定を書き込めない / 「書き込み不可」エラー

セットアップ中、ウェブサーバーは config/ および storage/ への書き込みアクセスが必要です。これらのディレクトリを PHP ユーザーが書き込み可能にしてから再試行してください。インストールのパーミッションに関するガイダンスを参照してください。

インストールが完了したのに /install が引き続き表示される

インストールが完了すると config/installed.php が書き込まれます。このファイルが存在しない場合、アプリはインストールされていないと判断します。セットアップが完了していれば、このファイルが存在し、インストーラーは自動的にロックされます。config/ が書き込み可能であったか再確認してください。

サイトは読み込まれるが、ページが 404 になる

ホームページは機能するのに他のすべての URL が 404 を返す場合、URL リライトがフロントコントローラーに到達していません。

• Apache — mod_rewrite が有効になっていること、および同梱の .htaccess が有効になるよう AllowOverride All が設定されていることを確認してください。
• Nginx — location / はフロントコントローラーへフォールスルーする必要があります。例: try_files $uri $uri/ /index.php?$query_string;。ウェブサーバーに関するメモは アーキテクチャ を参照してください。

ログインと管理者アクセス

管理者ログインページが見つからない

セキュリティのためにカスタム管理者 URL を設定した場合、パネルは /admin には存在しなくなります — 秘密のパスにのみ応答します。データベースへのアクセス権がある場合は、settings テーブルから復元してください。セキュリティを参照してください。

二要素認証でロックアウトされている

認証アプリを紛失した場合は、データベースでユーザーの TOTP を無効にし（users テーブルの該当カラム）てアクセスを回復してから、再登録してください。詳細は セキュリティ を参照してください。

アップロードとメディア

大きなファイルのアップロードが失敗またはタイムアウトする

PHP の制限 upload_max_filesize と post_max_size を引き上げ、Nginx では client_max_body_size を増加させてください。デモでは高い client_max_body_size を設定することで数ギガバイトのアップロードを可能にしています。大きなファイルを扱う場合はサーバーでも同様の設定をしてください。

動画が再生されない

新しくアップロードされた動画は、トランスコードが完了するまで 処理中 の場合があります。フォーマットがウェブ配信に対応していること、レンディションファイルがストレージに存在すること、およびサーバーが .mp4/.webm に正しい MIME タイプを送信していることを確認してください。プレーヤーを参照してください。

サムネイルまたはプレビューが表示されない

サムネイルおよびプレビューの生成には GD または Imagick 拡張（および動画フレームには FFmpeg）が必要です。これらがインストールされていること、および uploads/ が書き込み可能であることを確認してください。

トランスコードが止まっている

ジョブがキューに溜まったまま完了しない場合:

• トランスコードが実行される場所（ローカルサーバーまたはリモートワーカー）に FFmpeg がインストールされていることを確認してください。
• リモートのトランスコードサーバーを使用している場合は、ワーカーが実行中であること、および API キーが管理者で設定されているものと一致することを確認してください。
• スケジューラーが動作していることを確認してください（下記参照）— ジョブのディスパッチと再試行は pseudo-cron 上で実行されます。

スケジュールされたジョブが実行されない

pseudo-cron はページのレンダリング時にのみ実行されます。アクセスの少ないサイトでは、ハートビートがそれを維持します — heartbeat_enabled が 1 であることを確認してください。無効にしている場合は再度有効にするか、定期的にサイトにアクセスするシステム cron エントリを追加してください。

メールが送信されない

メールと通知で SMTP を設定し、組み込みのテストメール送信ボタンで確認してください。テストが失敗する場合は、SMTP ホスト/ポート/認証情報と、ホストが送信メールを許可しているかを確認してください。メール到達性のために、ドメインに SPF/DKIM を設定してください。

パフォーマンス

大規模なサイトで快適な動作を実現するには: OPcache を有効にし、PHP に十分なメモリを割り当て、MySQL を PHP と同じネットワーク上に置き、CTR の再計算やその他のスケジュールされたタスクを実行し続けてください。TubePress は大規模なライブラリに必要なインデックスとチャンクジョブを同梱しています — メンテナンスを参照してください。

アップデートが失敗する

アップデートが適用されない場合は、コアファイルが PHP ユーザーによって書き込み可能であること、および PHP 8.2+ を使用していることを確認してください。ロールバックできるよう、アップデート前に必ずバックアップを取ってください。アップデートを参照してください。

まだ解決しない場合は?

正確なエラーメッセージと関連するログの行を収集し、ダッシュボードまたは管理画面内のサポートウィジェットからチケットを開いてください。PHP バージョン、ウェブサーバー、実行していた操作など、より多くのコンテキストを含めるほど、早く解決されます。お知らせとサポートを参照してください。