運用ガイド (Operations Guide)

---

Version: v3.11.1

Copyright (c) 2026 Masanori Sakai

Licensed under the MIT License

---

概要

このガイドでは、流星検出システムの日常的な運用方法について説明します。

サンプル画面

運用時に常用するカメラ画面の例です。

目次

• 起動と停止
• アップデート手順
• バージョン別マイグレーション
• 運用スクリプト一覧
• meteor-docker.sh コマンドリファレンス
• ログの監視
• 状態確認
• ディスク容量管理
• トラブルシューティング
• バックアップとリストア
• パフォーマンス監視

---

起動と停止

基本フロー

graph TD
    Start["システム起動"]
    Check1{"streamersファイル<br/>存在確認"}
    Generate["docker-compose.yml<br/>生成"]
    Check2{"docker-compose.yml<br/>存在確認"}
    Build["Dockerイメージ<br/>ビルド"]
    Up["コンテナ起動"]
    Monitor["監視・運用"]
    Stop["コンテナ停止"]
    End["システム停止"]

    Start --> Check1
    Check1 -->|"なし"| Generate
    Check1 -->|"あり"| Check2
    Generate --> Check2
    Check2 -->|"初回"| Build
    Check2 -->|"2回目以降"| Up
    Build --> Up
    Up --> Monitor
    Monitor --> Stop
    Stop --> End

    style Generate fill:#dce6ff
    style Build fill:#e2eafc
    style Up fill:#dbe7f6
    style Monitor fill:#dff6e8

初回起動

# 1. streamersファイルを作成
cp streamers.sample streamers
vim streamers  # RTSP URLを設定

# 昼間画像を指定する場合（任意）
# rtsp://user:pass@192.0.2.25/live | camera1.jpg
# OpenCV がない環境ではマスク生成のみスキップ

# 2. docker-compose.ymlを生成
python generate_compose.py

# WebRTCライブ表示を使う場合
python generate_compose.py --streaming-mode webrtc

# 3. Dockerイメージをビルド
./meteor-docker.sh build

# 4. システムを起動
./meteor-docker.sh start

# 5. 状態を確認
./meteor-docker.sh status

通常起動

# 起動
./meteor-docker.sh start

# ログをリアルタイム表示
./meteor-docker.sh logs

マスク更新（固定カメラ向け）

ダッシュボード上、または単体カメラのWebプレビュー上の「マスク更新」ボタンで、現在フレームから除外マスクを再生成します。 生成されたマスクは /output/masks/<camera>_mask.png に保存され、再起動後も有効です。

ダッシュボードからの個別操作

• スナップショット保存: 各カメラの現在フレームをJPEGでダウンロード
• 再起動: 対象カメラのみ再起動要求（反映まで数秒かかる場合あり）

手動録画（v3.2.0+）

カメラライブ画面（/cameras）から、カメラごとに手動録画を予約・管理できます。

• 録画予約: 開始時刻と録画秒数を指定して予約。開始時刻を空欄にすると即時開始。
• 録画停止: 予約中・録画中の場合に停止ボタンで中断可能。
• 録画ファイルの保存先: ./detections/<camera>/manual_recordings/ 配下に MP4 として保存されます。
• 音声コーデック制限（v3.2.1+）: RTSP ストリームの音声が pcm_alaw の場合、音声トラックを除いた映像のみの MP4 として保存されます。
• サムネイル自動生成（v3.2.1+）: 録画完了後に同名の JPEG サムネイルが自動生成され、検出一覧カレンダーからプレビュー・削除が可能になります。
• 一覧からの削除: 検出一覧に手動録画が表示され、「削除」ボタンで MP4 とサムネイルをまとめて削除できます。

録画状態は GET /camera_recording_status/{index} で確認できます（state: idle / scheduled / recording / completed / stopped）。

WebRTC ライブ表示運用

• --streaming-mode webrtc で生成した構成では、go2rtc コンテナが追加されます。
• go2rtc.yaml の webrtc.candidates は既定でローカル IP を自動検出して設定されます。
• ブラウザ開発者ツールに srflx candidate が見えても、host candidate が同時に返っていて画面表示が RTC なら正常です。

YouTube Live配信（v3.3.0+）

streamers ファイルでYouTubeストリームキーを設定したカメラは、ダッシュボードのカメラライブ画面に「YouTube配信」ボタンが表示されます。

配信開始: 「YouTube配信」ボタンをクリック → 確認ダイアログで「OK」 配信停止: 「配信中 LIVE」ボタンをクリック → 確認ダイアログで「OK」

配信状態は10秒間隔で自動更新されます。配信は dashboard コンテナ内の ffmpeg サブプロセスが管理するため、dashboard コンテナを再起動すると配信は停止します。

ストリームキーの変更手順:

1. streamers ファイルのYouTubeキーを更新
2. python3 generate_compose.py --streaming-mode webrtc で再生成
3. ./meteor-docker.sh restart で反映

トラブルシューティング:

• YouTube Studioで「配信が始まらない」→ カメラのRTSPがH.264であることを確認
• 「音声がない」→ dashboard コンテナの ffmpeg が PCMA→AAC 変換を行うので通常は自動対応
• ボタンが表示されない → streamers に youtube:KEY が正しく設定されているか確認

ダッシュボードからの全カメラ一括設定（/settings）

ダッシュボード左サイドバーの「設定」から、複数カメラへ同時に設定反映できます。

• 現在値を取得: 各カメラの /stats.settings を取得
• 全カメラに適用: POST /camera_settings/apply_all を実行

反映タイミング: - 即時反映（再起動不要）: - 検出しきい値、追跡/結合、誤検出抑制（nuisance_*）など - 自動再起動で反映（再ビルド不要）: - sensitivity, scale, buffer, extract_clips

起動時依存項目は output/runtime_settings/<camera>.json に保存され、 コンテナ再起動後も維持されます。 この <camera> は内部名です。CAMERA_NAME_DISPLAY を設定していても、保存ファイル名やディレクトリ名には表示名ではなく内部名が使われます。

停止

# 通常停止（コンテナを削除）
./meteor-docker.sh stop

# データを保持したまま一時停止（再起動が速い）
docker compose stop

再起動

# コンテナを再起動（設定変更時など）
./meteor-docker.sh restart

---

アップデート手順

コードを更新した後にリモートホストへ反映する標準手順です。

パターン1: Pythonファイルのみ変更した場合

コンテナイメージに影響しない変更（テンプレート、設定読み込みロジック等）は コンテナを再ビルドせず docker compose restart で反映できます。

# 1. 最新コードを取得
git pull

# 2. コンテナを再起動（イメージはそのまま）
./meteor-docker.sh restart

パターン2: Dockerfileや requirements.txt を変更した場合

パッケージ追加・Dockerfileの変更は完全な再ビルドが必要です。

# 1. 最新コードを取得
git pull

# 2. docker-compose.yml を再生成（streamers が変わった場合のみ）
python3 generate_compose.py

# 3. 変更対象のサービスを再ビルド（例: dashboard のみ）
docker compose build --no-cache dashboard

# 全サービスを再ビルドする場合
./meteor-docker.sh build

# 4. コンテナを再起動
docker compose up -d

パターン3: streamers ファイルを変更した場合

カメラの追加・削除・YouTube キー変更などは generate_compose.py の再実行が必要です。

# 1. streamers を編集
vim streamers

# 2. docker-compose.yml と go2rtc.yaml を再生成
python3 generate_compose.py

# 3. コンテナを再起動
./meteor-docker.sh restart

!!! note "go2rtc 再起動が必要" go2rtc.yaml を変更した場合は go2rtc コンテナも再起動してください: docker compose restart go2rtc

アップデート後の確認

# コンテナがすべて Up になっているか確認
./meteor-docker.sh status

# ダッシュボードのバージョンを確認
curl -s http://localhost:8080/health | jq .version

# エラーが出ていないか確認
./meteor-docker.sh logs dashboard | grep -i error

---

バージョン別マイグレーション

旧バージョンから更新する際は、以下の手順を必ず起動前に実施してください。各スクリプトは冪等性を保つように設計されています（再実行しても壊れない）。

v3.6.0 → SQLite 化アップデート

v3.6.0 以降、検出データの正本は $DETECTIONS_DIR/detections.db（SQLite）に移行しました。検出エンジン自体は引き続き detections.jsonl に追記しますが、ダッシュボードは SQLite を参照します。

移行タイミング: v3.6.0 以上のイメージに初めて更新するとき、1度だけ実行

# 仮想環境を有効化（ホスト上で実行。Docker コンテナ内でも可）
source .venv/bin/activate

# 既存 JSONL → SQLite に一括取り込み
python scripts/migrate_jsonl_to_sqlite.py

挙動と安全性:

• INSERT OR IGNORE による冪等実行（何度実行しても重複しない）
• 既存の detections.jsonl は削除されない（ロールバックソースとして保持）
• detection_labels.json があれば同時に SQLite のラベル列へ取り込まれる

ロールバック: SQLite を使わない状態に戻したい場合は $DETECTIONS_DIR/detections.db を削除するだけ。JSONL は残っているため検出データは失われない。

詳細は DETECTION_STORE.md を参照してください。

v3.11.0 → カメラ名インデックス化アップデート

!!! warning "破壊的マイグレーション" migrate_camera_dirs.py はディレクトリ移動と SQLite の UPDATE を伴います。最初の実行は必ず --dry-run を付け、コンテナを停止し、detections/ をバックアップしてから実行してください。

v3.11.0 以降、generate_compose.py は CAMERA{i}_NAME = camera{i} を固定で書き出します。旧 IP 含みの内部名（例: camera1_10_0_1_25）が検出ディレクトリや SQLite に残っている場合は、プロジェクトルート直下の migrate_camera_dirs.py で移行します。

移行タイミング: v3.11.0 以上のイメージに初めて更新するとき、1度だけ実行

# 0. コンテナを停止し、バックアップを取る
./meteor-docker.sh stop
cp -a detections detections.bak_$(date +%Y%m%d_%H%M%S)

# 1. 必ず dry-run で内容を確認
python migrate_camera_dirs.py --dry-run

# 2. 問題なければ本実行（対話確認あり）
python migrate_camera_dirs.py

# 3. 非対話実行する場合
python migrate_camera_dirs.py --yes

# 対象ディレクトリを明示する場合
python migrate_camera_dirs.py --detections-dir /mnt/vol/detections

事前準備（必須）:

• detections/ を tar 等でバックアップする
• コンテナを停止した状態で実行する（書き込み競合を避けるため）

挙動:

• detections/camera{i}_*/ 配下のメディアファイル（.mp4 / .jpg / .png）を detections/camera{i}/ へ rename で移動（同名衝突時は _1, _2 ... のサフィックス付与）
• detections.jsonl はマージ追記（バイナリ単位）
• detections.db の camera 列および clip_path / image_path / composite_original_path / alternate_clip_paths を replace() で旧名→新名へ一括更新
• 実行前に detections.db を detections.db.bak_<timestamp> として自動バックアップ
• 完了後、元の camera{i}_*/ は camera{i}_*.migrated_<timestamp>/ にリネームして残置（動作確認後に手動削除可）

ロールバック手順:

問題が発生した場合は、以下で元の状態に戻せます（タイムスタンプは実行時のものに置換）。

# SQLite DB を戻す
cp detections/detections.db.bak_<timestamp> detections/detections.db

# 元ディレクトリに戻す（必要に応じて）
for d in detections/camera*_*.migrated_<timestamp>; do
    mv "$d" "${d%.migrated_<timestamp>}"
done

# 新しい camera{i} ディレクトリは未処理のまま残るため、事前に撮っておいた
# detections.bak_<日時> から全量復元するのが安全

詳細は CONFIGURATION_GUIDE.md の「カメラ命名規則（v3.11.0+）」節および DETECTION_STORE.md を参照してください。

---

運用スクリプト一覧

scripts/ 配下および一部プロジェクトルートに、検出データの移行・救済・調査を行うスタンドアロンスクリプトが用意されています。詳細な引数・挙動は SCRIPTS_REFERENCE.md を参照してください。

スクリプト	配置	用途	冪等性	破壊性
migrate_jsonl_to_sqlite.py	scripts/	v3.6.0+ の初回 SQLite 取り込み	○ [^idem1]	JSONL 非破壊
migrate_camera_dirs.py	プロジェクトルート	v3.11.0+ のカメラ名インデックス化	○ [^idem2]	DB/ディレクトリを書き換え ^destr1
migrate_detection_ids.py	scripts/	検出IDの再発番・付与漏れ補修	○	JSONL を書き換え
rescue_orphan_detection_files.py	scripts/	JSONL に存在しない孤立ファイルを検知・救済	○	--apply 指定時のみ JSONL 追記
import_from_other_system.py	scripts/	別マシンの detections/ を取り込む	○ ^idem3	--apply 指定時のみコピー・DB更新
merge_detection_directories.py	scripts/	2 つの検出ディレクトリを統合	○ [^idem4]	--apply 指定時のみファイル移動 [^destr2]
transfer_detections.py	scripts/	ZIP エクスポート/インポート（TUI）	○ [^idem5]	export は読み込みのみ、import は --apply 指定時のみ書き込み
dump_detections_db.py	scripts/	SQLite の内容をダンプ（table/JSON/CSV）	○	なし（読み取り専用）

[^idem1]: INSERT OR IGNORE により重複行は無視 [^idem2]: --dry-run を明示しない限り本実行する点に注意。自動バックアップ (detections.db.bak_<timestamp>) あり

[^idem4]: --apply までは副作用なし。ただし JSONL は追記ベースで再実行時にも.jsonl ファイルへ追加する設計のため、同じマージを 2 回走らせると一時的に重複行が増える（SQLite 同期時には id で重複排除される） [^idem5]: import 側は --apply 指定時のみ副作用が発生

[^destr2]: --cleanup-source 指定時は空になった元ファイル・ディレクトリも削除

!!! note "migrate_camera_dirs.py の配置について" migrate_camera_dirs.py のみプロジェクトルートに配置されています。これはカメラ名インデックス化が初回アップデート時の 1 回限り・起動前に実行する特殊なオペレーションであるためです。

---

meteor-docker.sh コマンドリファレンス

start - システム起動

./meteor-docker.sh start

動作: - docker compose up -d を実行 - バックグラウンドで全コンテナを起動 - 起動状態を表示

出力例:

[INFO] 流星検出を起動中...
[+] Running 4/4
 ✔ Container meteor-camera1    Started
 ✔ Container meteor-camera2    Started
 ✔ Container meteor-camera3    Started
 ✔ Container meteor-dashboard  Started
[INFO] 起動完了
NAME                 IMAGE                  STATUS
meteor-camera1       meteo-camera1          Up 2 seconds
meteor-camera2       meteo-camera2          Up 2 seconds
meteor-camera3       meteo-camera3          Up 2 seconds
meteor-dashboard     meteo-dashboard        Up 1 second

---

stop - システム停止

./meteor-docker.sh stop

動作: - docker compose down を実行 - 全コンテナを停止・削除 - ネットワークを削除 - 検出結果(./detections/)は保持される

---

restart - 再起動

./meteor-docker.sh restart

動作: - docker compose restart を実行 - 各コンテナを順次再起動 - イメージは再ビルドしない

使用場面: - 設定変更後 - コンテナの動作が不安定な時 - メモリリーク対策

---

status - 状態確認

./meteor-docker.sh status

動作: 1. コンテナ状態を表示 2. リソース使用状況を表示 3. 各カメラの検出結果数を表示

出力例:

=== コンテナ状態 ===
NAME                 STATUS          PORTS
meteor-camera1       Up 2 hours      0.0.0.0:8081->8080/tcp
meteor-camera2       Up 2 hours      0.0.0.0:8082->8080/tcp
meteor-camera3       Up 2 hours      0.0.0.0:8083->8080/tcp
meteor-dashboard     Up 2 hours      0.0.0.0:8080->8080/tcp

=== リソース使用状況 ===
CONTAINER         CPU %    MEM USAGE / LIMIT    MEM %
meteor-camera1    45.2%    312.5MiB / 8GiB      3.82%
meteor-camera2    42.8%    305.1MiB / 8GiB      3.73%
meteor-camera3    44.1%    318.2MiB / 8GiB      3.88%
meteor-dashboard  2.5%     78.3MiB / 8GiB       0.95%

=== 検出結果 ===
  camera1: 15件 (最新: 2026-02-02 06:55)
  camera2: 8件 (最新: 2026-02-02 05:32)
  camera3: 12件 (最新: 2026-02-02 07:01)

---

logs - ログ表示

# 全コンテナのログ（リアルタイム）
./meteor-docker.sh logs

# 特定カメラのログ
./meteor-docker.sh logs camera1

# ダッシュボードのログ
./meteor-docker.sh logs dashboard

# Ctrl+Cで終了

ログの色分け: - 白: 通常のメッセージ - 緑: 情報メッセージ [INFO] - 黄: 警告メッセージ [WARN] - 赤: エラーメッセージ [ERROR]

重要なログメッセージ:

# 正常動作
接続成功: 1920x1080 @ 30.0fps
検出開始 (Ctrl+C で終了)

# 流星検出
[06:55:33] 流星検出 #1
  長さ: 135.6px, 時間: 0.44秒
  保存: meteor_20260202_065533.mp4

# 警告
接続失敗: rtsp://...

---

build - イメージ再ビルド

./meteor-docker.sh build

動作: - docker compose build --no-cache を実行 - キャッシュを使わず完全にビルド - 時間がかかる（5-10分程度）

使用場面: - コードを変更した時 - requirements.txtを変更した時 - Dockerfileを変更した時

---

rebuild - ビルドして再起動

./meteor-docker.sh rebuild

動作: - docker compose build --no-cache を実行 - docker compose down で停止 - docker compose up -d で再起動

使用場面: - ビルド結果をすぐ反映したい時 - コンテナを一度止めてクリーンに起動し直したい時

---

generate - docker-compose.yml再生成

# 基本
./meteor-docker.sh generate

# オプション付き
./meteor-docker.sh generate --sensitivity high --enable-time-window true

動作: - generate_compose.py を実行 - streamersファイルから docker-compose.yml を生成

使用場面: - カメラを追加・削除した時 - 設定を一括変更したい時

---

clean - 古い検出結果削除

./meteor-docker.sh clean

動作: - 7日以上前のファイルを削除 - 確認プロンプト表示

出力例:

[WARN] 古い検出結果を削除しますか？ (y/N)
y
[INFO] 7日以上前のファイルを削除しました

---

cleanup - 未使用リソース削除

./meteor-docker.sh cleanup

動作: 1. このプロジェクトの古いDockerイメージを削除 2. 停止中のコンテナを削除 3. ディスク使用状況を表示

出力例:

[INFO] このプロジェクトの古いイメージを削除します...

=== meteo-camera1 の全バージョン ===
REPOSITORY      TAG       IMAGE ID       SIZE
meteo-camera1   latest    abc123def456   450MB
meteo-camera1   <none>    def789ghi012   445MB

[INFO] 1個の未使用イメージを削除しました
[INFO] このプロジェクトの停止中コンテナを削除します...
[INFO] ディスク使用状況:
TYPE            TOTAL     ACTIVE    SIZE
Images          15        4         2.1GB
Containers      4         4         150MB
Local Volumes   2         2         1.5GB

使用場面: - ディスク容量が不足している時 - イメージを何度もビルドした後 - 定期メンテナンス

---

ログの監視

ログの永続化（v3.3.1+）

v3.3.1 以降、すべてのコンテナのログはホスト側の ./logs/ ディレクトリにマウントされます。 コンテナを再ビルド・削除してもログは失われません。

生成されるログファイル

ファイル	内容	ローテーション
logs/dashboard.log	ダッシュボードの Python ログ	10MB × 5世代（Python）
logs/camera1.log（camera2, 3 …）	各カメラコンテナの stdout/stderr	10MB × 5世代（Python）
logs/ffmpeg_youtube_3.log（N はカメラ番号）	YouTube 配信 ffmpeg の出力	起動ごとに追記

Docker コンテナ自体のログ（docker compose logs）は json-file ドライバで 10MB × 3 ファイルに回転します。

ログファイルの確認

# ダッシュボードのログをリアルタイムで確認
tail -f ./logs/dashboard.log

# カメラ1のログを確認
tail -f ./logs/camera1.log

# YouTube ffmpeg の出力を確認（カメラ3の場合）
tail -f ./logs/ffmpeg_youtube_3.log

# エラーのみ抽出
grep -i error ./logs/dashboard.log

logs/ ディレクトリの容量管理

各ログは Python の RotatingFileHandler によって自動的に回転します。 最大容量は (10MB × 5世代) × コンテナ数 程度です。

不要になった古いローテートファイル（.log.1〜.log.5）は手動削除できます:

# ローテート済みファイルのみ削除（最新の .log は残す）
rm -f ./logs/*.log.[1-9]

---

ログレベルと内容

検出コンテナのログ

./meteor-docker.sh logs camera1

主要メッセージ:

メッセージ	意味	対応
接続中...	RTSP接続試行中	正常
接続成功: 1920x1080 @ 30.0fps	ストリーム接続成功	正常
検出開始 (Ctrl+C で終了)	検出処理開始	正常
接続失敗: rtsp://...	RTSP接続失敗	要確認
[06:55:33] 流星検出 #1	流星検出	正常
稼働: 60.0分, 検出: 5個	1時間ごとの統計	正常

ダッシュボードのログ

./meteor-docker.sh logs dashboard

主要メッセージ:

Dashboard starting on port 8080
Cameras: 3
  - camera1 (192.0.2.25): http://localhost:8081
  - camera2 (192.0.2.3): http://localhost:8082
  - camera3 (192.0.2.11): http://localhost:8083

Open http://localhost:8080/ in your browser

ログのフィルタリング

# エラーのみ表示
./meteor-docker.sh logs camera1 2>&1 | grep ERROR

# 流星検出のみ表示
./meteor-docker.sh logs camera1 2>&1 | grep "流星検出"

# 最新100行のみ表示
docker compose logs camera1 --tail=100

---

状態確認

Webブラウザで確認

最も簡単な確認方法:

http://localhost:8080/  (ダッシュボード)

確認項目: - ストリーム接続状態（緑●: 正常、赤●: 異常） - 検出処理状態（緑●: 待機中、赤●点滅: 検出中） - 総検出数 - 最近の検出リスト

コマンドラインで確認

# 簡易確認
./meteor-docker.sh status

# 詳細確認
docker compose ps -a
docker stats --no-stream

APIで確認

# カメラ1の統計情報
curl http://localhost:8081/stats | jq

# ダッシュボードの検出一覧
curl http://localhost:8080/detections | jq

---

ディスク容量管理

検出結果のサイズ見積もり

項目	サイズ（1件あたり）
クリップ動画（4秒@30fps）	約2-5MB
コンポジット画像	約200-500KB
JSON行	約200B

1日の見積もり（検出数10件/日の場合）: - クリップあり: 約30-50MB/日 - クリップなし: 約2-5MB/日

容量確認

# 検出結果のディスク使用量
du -sh ./detections/

# カメラ別の使用量
du -sh ./detections/*/

# ファイル数
find ./detections -type f | wc -l

自動クリーンアップの設定

方法1: cronで定期実行

# crontabに追加
crontab -e

# 毎週日曜日の深夜2時に古いファイルを削除
0 2 * * 0 cd /path/to/meteo && find ./detections -type f -mtime +7 -delete

方法2: systemdタイマーで実行

# /etc/systemd/system/meteor-cleanup.service
[Unit]
Description=Meteor Detection Cleanup

[Service]
Type=oneshot
WorkingDirectory=/path/to/meteo
ExecStart=/usr/bin/find ./detections -type f -mtime +7 -delete

# /etc/systemd/system/meteor-cleanup.timer
[Unit]
Description=Meteor Detection Cleanup Timer

[Timer]
OnCalendar=weekly
Persistent=true

[Install]
WantedBy=timers.target

# 有効化
sudo systemctl enable meteor-cleanup.timer
sudo systemctl start meteor-cleanup.timer

手動クリーンアップ

# 7日以上前のファイルを削除（対話型）
./meteor-docker.sh clean

# クリップ動画のみ削除（コンポジット画像は残す）
find ./detections -name "*.mp4" -mtime +7 -delete

# 特定カメラのみ削除
find ./detections/camera1 -type f -mtime +7 -delete

# 手動録画ファイルのみ削除（v3.2.0+）
find ./detections -path "*/manual_recordings/*" -mtime +7 -delete

手動録画ファイルはダッシュボードの検出一覧の「削除」ボタン（DELETE /manual_recording/{path}）でも個別削除できます。

---

トラブルシューティング

トラブルシューティングフロー

graph TD
    Start["問題発生"]
    CheckContainer{"コンテナが<br/>起動している？"}
    CheckLogs["ログを確認"]
    CheckRTSP{"RTSP接続<br/>エラー？"}
    CheckDisk{"ディスク容量<br/>不足？"}
    CheckMemory{"メモリ不足？"}

    FixContainer["docker compose up -d"]
    FixRTSP["RTSP URLとネットワークを確認"]
    FixDisk["古いファイル削除<br/>cleanup実行"]
    FixMemory["コンテナ再起動<br/>スケール調整"]

    Resolved["解決"]
    Support["サポートに連絡"]

    Start --> CheckContainer
    CheckContainer -->|"No"| FixContainer
    CheckContainer -->|"Yes"| CheckLogs
    CheckLogs --> CheckRTSP
    CheckRTSP -->|"Yes"| FixRTSP
    CheckRTSP -->|"No"| CheckDisk
    CheckDisk -->|"Yes"| FixDisk
    CheckDisk -->|"No"| CheckMemory
    CheckMemory -->|"Yes"| FixMemory
    CheckMemory -->|"No"| Support

    FixContainer --> Resolved
    FixRTSP --> Resolved
    FixDisk --> Resolved
    FixMemory --> Resolved

    style Start fill:#f8d7da
    style Resolved fill:#dff6e8
    style Support fill:#ffe3c4

よくある問題と解決方法

1. コンテナが起動しない

症状:

./meteor-docker.sh status
# コンテナが表示されない

原因と対策:

原因	確認方法	対策
docker-compose.ymlがない	ls docker-compose.yml	python generate_compose.py
Dockerデーモン未起動	docker ps	sudo systemctl start docker
ポート競合	lsof -i :8080	ポート番号を変更
イメージ未ビルド	docker images	./meteor-docker.sh build

解決手順:

# 1. docker-compose.ymlを確認
ls -la docker-compose.yml

# 2. Dockerデーモンを確認
docker ps

# 3. エラーログを確認
docker compose up

# 4. 再ビルドして起動
./meteor-docker.sh build
./meteor-docker.sh start

---

2. RTSP接続エラー

症状:

接続失敗: rtsp://...

原因と対策:

# 1. カメラにpingが通るか確認
ping 192.0.2.25

# 2. RTSPポートが開いているか確認
nc -zv 192.0.2.25 554

# 3. ffmpegで直接接続テスト
ffmpeg -i "rtsp://user:pass@192.0.2.25/live" -frames:v 1 test.jpg

# 4. streamersファイルを確認
cat streamers

# 5. 認証情報を確認
# ユーザー名・パスワードが正しいか

チェックリスト: - [ ] カメラの電源が入っているか - [ ] ネットワークケーブルが接続されているか - [ ] IPアドレスが正しいか - [ ] ユーザー名・パスワードが正しいか - [ ] ファイアウォールでポート554が開いているか - [ ] カメラ側のRTSP機能が有効か

---

3. ディスク容量不足

症状:

Error: No space left on device

確認:

# ディスク使用量を確認
df -h

# 検出結果のサイズ
du -sh ./detections/

# Dockerのディスク使用量
docker system df

対策:

# 1. 古い検出結果を削除
./meteor-docker.sh clean

# 2. 未使用Dockerリソースを削除
./meteor-docker.sh cleanup

# 3. クリップ動画を無効化（設定変更）
# docker-compose.ymlで EXTRACT_CLIPS=false

# 4. より積極的なクリーンアップ
docker system prune -a --volumes

---

4. メモリ不足・CPUが高い

症状:

./meteor-docker.sh status
# CPU %が常時90%以上
# MEM %が常時80%以上

対策:

# 1. コンテナを再起動（メモリリーク対策）
./meteor-docker.sh restart

# 2. 処理スケールを下げる
python generate_compose.py --scale 0.25

# 3. カメラ数を減らす
# streamersファイルからカメラを削除

# 4. リソース制限を設定
# docker-compose.ymlに追加:
#   deploy:
#     resources:
#       limits:
#         cpus: '0.5'
#         memory: 512M

---

5. ストリームが表示されない

症状: - ダッシュボードでカメラ映像が「接続中...」のまま

確認:

# カメラコンテナが動いているか
./meteor-docker.sh status

# カメラのログを確認
./meteor-docker.sh logs camera1

# ブラウザで直接アクセス
open http://localhost:8081/

対策:

# カメラコンテナを再起動
docker compose restart camera1

# ブラウザのキャッシュをクリア
# Ctrl+Shift+R (強制リロード)

---

バックアップとリストア

バックアップ対象

1. 検出結果: ./detections/
2. 設定ファイル: streamers, docker-compose.yml
3. カスタマイズしたコード: *.py

バックアップ手順

# 日付付きバックアップ
DATE=$(date +%Y%m%d)
tar -czf meteor-backup-${DATE}.tar.gz \
    detections/ \
    streamers \
    docker-compose.yml

# リモートサーバーにコピー
scp meteor-backup-${DATE}.tar.gz user@backup-server:/backups/

# クラウドストレージにアップロード（例: AWS S3）
aws s3 cp meteor-backup-${DATE}.tar.gz s3://my-bucket/backups/

自動バックアップ

# backup.sh
#!/bin/bash
DATE=$(date +%Y%m%d)
BACKUP_DIR="/path/to/backups"
cd /path/to/meteo

tar -czf ${BACKUP_DIR}/meteor-backup-${DATE}.tar.gz \
    detections/ streamers docker-compose.yml

# 30日以上前のバックアップを削除
find ${BACKUP_DIR} -name "meteor-backup-*.tar.gz" -mtime +30 -delete

# crontabに登録
# 0 3 * * * /path/to/backup.sh

リストア手順

# システムを停止
./meteor-docker.sh stop

# バックアップを展開
tar -xzf meteor-backup-20260202.tar.gz

# システムを起動
./meteor-docker.sh start

---

パフォーマンス監視

リアルタイム監視

# Docker stats（リアルタイム）
docker stats

# top風表示
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

# htopで監視
htop

# 検出状況の監視（1分ごと）
watch -n 60 './meteor-docker.sh status'

メトリクス収集

# リソース使用履歴をログに記録
while true; do
    echo "$(date) $(docker stats --no-stream --format 'table {{.Name}}\t{{.CPUPerc}}\t{{.MemPerc}}')" \
        >> /var/log/meteor-stats.log
    sleep 300  # 5分ごと
done

アラート設定例

# alert.sh - CPU使用率90%超えで通知
#!/bin/bash
CPU=$(docker stats --no-stream --format "{{.CPUPerc}}" meteor-camera1 | sed 's/%//')
if (( $(echo "$CPU > 90" | bc -l) )); then
    echo "Alert: Camera1 CPU usage is ${CPU}%" | mail -s "Meteor Alert" admin@example.com
fi

---

定期メンテナンス

日次

# 状態確認
./meteor-docker.sh status

# ログ確認（エラーの有無）
./meteor-docker.sh logs | grep -i error

# ディスク容量確認
df -h

週次

# コンテナ再起動（メモリリーク対策）
./meteor-docker.sh restart

# バックアップ実行
./backup.sh

# ローテート済みログの掃除（任意）
rm -f ./logs/*.log.[1-9]

月次

# 古い検出結果の削除
./meteor-docker.sh clean

# 未使用Dockerリソースの削除
./meteor-docker.sh cleanup

# 検出統計の確認
find ./detections -name "*.mp4" | wc -l

---

関連ドキュメント

• DOCKER_ARCHITECTURE.md - Docker構成の詳細
• CONFIGURATION_GUIDE.md - 設定方法
• SECURITY.md - セキュリティガイド
• API_REFERENCE.md - API仕様