Azure Blob Storage 移行ガイド¶
このガイドでは、広聴AIアプリケーションでAzure Blob Storageを使用してレポートデータを永続化する方法について説明します。restore / upload / health check 用の補助スクリプトの使い分けは Storage Snapshot Operations を参照してください。
目次¶
概要¶
2025-04-08以前に作成されたAzure Container Apps環境では、コンテナが再起動されるとコンテナ内のファイルが失われます。Azure Blob Storageを使用することで、レポートデータを永続的に保存し、コンテナが再起動されても利用可能な状態を維持できます。
環境設定¶
1. 環境変数の設定¶
.envファイルに以下の設定を追加します：
# Storage settings
# ローカル環境では"local"、Azure環境では"azure_blob"を設定
STORAGE_TYPE=azure_blob
# Azure Blob Storageのアカウント名
AZURE_BLOB_STORAGE_ACCOUNT_NAME=your_storage_account_name
# Azure Blob Storageのコンテナ名
AZURE_BLOB_STORAGE_CONTAINER_NAME=your_container_name
注意事項： - ストレージアカウント名は3〜24文字の小文字英数字で、全体で一意である必要があります - コンテナ名は3〜63文字の小文字英数字とハイフンで構成する必要があります
2. Azure Blob Storageの作成¶
既存のAzure環境がある場合は、以下のコマンドでストレージを作成します：
3. ストレージへのアクセス権限の設定¶
ストレージへのアクセス権限を設定するには、以下のスクリプトを実行します：
このスクリプトは、現在ログインしているユーザーに「Storage Blob Data Contributor」ロールを付与します。
4. Blob Storage の疎通確認¶
環境構築後は、通常運用の前に API から Blob Storage へ書き込みと read-back ができることを確認してください。
scripts/test_storage.py では、現在の storage 設定で初期化できること、テストファイルの upload が通ること、同じ blob を download して内容一致することを確認します。
実行時は STORAGE_TYPE, AZURE_BLOB_STORAGE_ACCOUNT_NAME, AZURE_BLOB_STORAGE_CONTAINER_NAME に加え、apps/api/src/config.py が読む ADMIN_API_KEY, PUBLIC_API_KEY, OPENAI_API_KEY も環境変数として必要です。
既存レポートの永続化¶
0. Azure Blob Storage からローカルへ復元¶
storage 側を canonical store として、status / reports / configs / inputs を ローカルファイルシステムへ復元するには以下を使います。
特定レポートだけを落とす場合:
この script も apps/api/src/config.py を読むため、.env または環境変数で ADMIN_API_KEY, PUBLIC_API_KEY, OPENAI_API_KEY, STORAGE_TYPE, AZURE_BLOB_STORAGE_ACCOUNT_NAME, AZURE_BLOB_STORAGE_CONTAINER_NAME を与えてから実行してください。
1. レポートのアップロード¶
既存のレポートをAzure Blob Storageにアップロードするには、以下のスクリプトを使用します：
2. APIコンテナの再起動¶
レポートをアップロードした後、変更を反映させるにはAPIコンテナの再起動が必要です：
再起動後、ブラウザをリロードすると、アップロードしたレポートが表示されます。
トラブルシューティング¶
権限エラー（AuthorizationPermissionMismatch）¶
アップロード時に以下のようなエラーが表示される場合：
これは、ストレージアカウントへのアクセス権限が不足していることを示しています。以下の手順で解決できます：
-
Azure CLIでログインしていることを確認：
-
ストレージへのアクセス権限を付与：
コンテナ再起動後もレポートが表示されない¶
-
ログを確認して問題を特定：
-
環境変数が正しく設定されているか確認：
-
APIコンテナを再起動：
既存の fetch_reports.py について¶
fetch_reports.py は通常運用の safety net から外しました。現行の本線は ReportSyncService による Azure Blob Storage への同期と、起動時の initialize_from_storage() による復元です。public /reports scrape は private / unlisted レポートを扱えず、canonical store としても不適切なため、必要なら tools/scripts/download_reports_from_azure.py で storage から直接復元する方針に切り替えています。