トラブルシューティング

このページではFenfaを実行する際によく発生する問題とその解決策を説明します。

iOSインストール

「インストールできません」 / インストールが失敗する

症状： iOSでインストールボタンをタップすると「インストールできません」が表示されるか、何も起こりません。

原因と解決策：

1. HTTPSが設定されていない。 iOSはOTAインストールに有効なTLS証明書を使用したHTTPSが必要です。自己署名証明書は動作しません。

   • 修正： 有効なTLS証明書を使用したリバースプロキシをセットアップします。プロダクションデプロイを参照してください。
   • テスト用： ngrokを使用してHTTPSトンネルを作成します：ngrok http 8000

2. 間違ったprimary_domain。 マニフェストplistにはprimary_domainに基づいたダウンロードURLが含まれています。これが間違っていると、iOSはIPAを取得できません。

   • 修正： FENFA_PRIMARY_DOMAINをユーザーがアクセスする正確なHTTPS URL（例：https://dist.example.com）に設定します。

3. 証明書の問題。 TLS証明書はドメインをカバーしていてiOSで信頼されている必要があります。

   • 修正： Let's Encryptを使用して無料の信頼された証明書を取得します。

4. IPA署名の期限切れ。 プロビジョニングプロファイルまたは署名証明書が期限切れになっている可能性があります。

   • 修正： 有効な証明書でIPAを再署名して再アップロードします。

UDIDバインディングが機能しない

症状： mobileconfigプロファイルはインストールされるが、デバイスが登録されない。

原因と解決策：

1. コールバックURLに到達できない。 UDIDコールバックURLはデバイスから到達可能でなければなりません。

   • 修正： primary_domainが正しく、デバイスのネットワークからアクセス可能であることを確認します。

2. ノンスの期限切れ。 プロファイルノンスはタイムアウト後に期限切れになります。

   • 修正： mobileconfigプロファイルを再ダウンロードして再試行します。

アップロードの問題

アップロードが401で失敗する

症状： {"ok": false, "error": {"code": "UNAUTHORIZED", ...}}

修正： X-Auth-Tokenヘッダーに有効なトークンが含まれていることを確認します。アップロードエンドポイントはアップロードトークンと管理トークンの両方を受け入れます。

# トークンが機能することを確認
curl -H "X-Auth-Token: YOUR_TOKEN" http://localhost:8000/admin/api/products

アップロードが413（Request Entity Too Large）で失敗する

症状： 大きなファイルのアップロードが413エラーで失敗する。

修正： これは通常Fenfa自体ではなくリバースプロキシの制限です。制限を増やします：

Nginx：

client_max_body_size 2G;

Caddy： Caddyにはデフォルトのボディサイズ制限はありませんが、設定した場合：

dist.example.com {
    request_body {
        max_size 2GB
    }
    reverse_proxy localhost:8000
}

スマートアップロードがメタデータを検出しない

症状： スマートアップロード後にバージョンとビルド番号が空になっている。

修正： スマートアップロードの自動検出はIPAおよびAPKファイルのみで機能します。デスクトップフォーマット（DMG、EXE、DEBなど）の場合は、アップロードリクエストでversionとbuildを明示的に指定してください。

Dockerの問題

コンテナは起動するが管理パネルが空

症状： 管理パネルは読み込まれるがデータが表示されないか空白ページ。

修正： コンテナが実行中でポートマッピングが正しいことを確認します：

docker ps
docker logs fenfa

コンテナ再起動後にデータが失われる

症状： コンテナを再起動すると製品、バリアント、リリースがすべて消える。

修正： 永続ボリュームをマウントします：

docker run -d --name fenfa -p 8000:8000 \
  -v ./data:/data \
  -v ./uploads:/app/uploads \
  fenfa/fenfa:latest

マウントされたボリュームでパーミッション拒否

症状： Fenfaが/dataまたは/app/uploadsに書き込めない。

修正： ホストディレクトリが存在して正しいパーミッションを持っていることを確認します：

mkdir -p data uploads
chmod 777 data uploads  # または適切なUID/GIDを設定

データベースの問題

「database is locked」エラー

症状： 高い並行処理でSQLiteが「database is locked」を返す。

修正： SQLiteは同時読み取りを適切に処理しますが、書き込みをシリアライズします。このエラーは通常、非常に高い書き込み負荷で発生します。解決策：

• 同じデータベースファイルに書き込むFenfaインスタンスが1つだけであることを確認します。
• 複数のインスタンスを実行する場合は、S3ストレージと共有データベースを使用します（または将来のリリースで別のデータベースバックエンドに切り替えます）。

破損したデータベース

症状： FenfaがSQLiteエラーで起動に失敗する。

修正： バックアップから復元します：

# Fenfaを停止
docker stop fenfa

# バックアップを復元
cp /backups/fenfa-latest.db /path/to/data/fenfa.db

# 再起動
docker start fenfa

予防

毎日の自動バックアップをセットアップします。バックアップスクリプトについてはプロダクションデプロイを参照してください。

ネットワークの問題

iOSマニフェストが間違ったURLを返す

症状： iOSマニフェストplistに公開ドメインの代わりにhttp://localhost:8000が含まれている。

修正： FENFA_PRIMARY_DOMAINを公開HTTPSのURLに設定します：

FENFA_PRIMARY_DOMAIN=https://dist.example.com

ダウンロードが遅いまたはタイムアウトする

症状： 大きなファイルのダウンロードが遅いまたは失敗する。

考えられる修正：

• リバースプロキシのタイムアウトを増やす：proxy_read_timeout 600s;（Nginx）
• リクエストバッファリングを無効にする：proxy_request_buffering off;（Nginx）
• 大容量ファイルにはCDN付きのS3互換ストレージの使用を検討する

ヘルプを得る

ここで問題が解決しない場合：

1. 既知の問題についてGitHub Issuesを確認します。
2. コンテナログを確認します：docker logs fenfa
3. 以下の情報を含む新しいイシューを作成します：
   • Fenfaのバージョン（docker inspect fenfa | grep Image）
   • 関連するログ出力
   • 問題を再現する手順