トラブルシューティング

バックエンドに接続できない

まずヘルスチェックを確認します。

curl http://localhost:5001/api/health

ローカル開発では、バックエンドを起動した状態でフロントエンドの Vite 開発サーバーを起動してください。別ホストへ接続する場合は VITE_API_URL と CORS の設定を確認します。

URL からの取得が失敗する

yt-dlp と ffmpeg が実行できること、バックエンドから対象サービスへネットワーク接続できることを確認します。

yt-dlp --version
ffmpeg -version

対象サービスの仕様変更、コンテンツの公開設定、ネットワーク制限でも失敗します。権利と利用規約を確認した上で、エラーログを確認してください。

シークできない、再生が途切れる

ストリーミングには HTTP Range リクエストが必要です。リバースプロキシを置く場合は Range ヘッダーと 206 Partial Content 応答を妨げないように設定します。nginx を使用する場合はストリーミング経路のバッファリング設定も見直してください。

Kubernetes で Pod が起動しない

kubectl get pods -n media-server
kubectl describe pod -n media-server -l component=backend
kubectl logs -n media-server -l component=backend --previous

PersistentVolumeClaim が Pending の場合は、PV の容量・ノード親和性・StorageClass を確認します。ImagePullBackOff の場合はイメージ名、タグ、レジストリの認証情報、ノードからの到達性を確認してください。

Cloudflare Pages のビルドが失敗する

Pages プロジェクトのルートディレクトリを docs、ビルドコマンドを npm run docs:build、出力先を .vitepress/dist に設定します。設定変更後はローカルでも同じコマンドを実行し、Node.js のバージョンと依存関係を確認してください。