Show HN: CheapSecurity – Linux SBC向け軽量セルフホスト型CCTV
Show HN: CheapSecurity – Lightweight, Self-Hosted CCTV for Linux SBCs (github.com)
要約
CheapSecurityは、Linuxベースのシングルボードコンピュータ(SBC)と標準USBウェブカメラ向けの軽量なセルフホスト型CCTVソリューションです。ビデオデータを完全に管理下に置くことで、ホームモニタリングのための手頃でプライバシー重視の代替手段を提供します。このプロジェクトは、既存のハードウェアを活用し、クラウドサブスクリプションなしで、低消費電力デバイスでも効率的に動作するように設計されています。
全文翻訳
CheapSecurity
このプロジェクトは、Linuxベースのシングルボードコンピュータ(SBC)および標準USBウェブカメラ向けに設計された、軽量なセルフホスト型CCTVソリューションを提供します。映像データを完全に管理下に置くことで、ホームモニタリングのための手頃でプライバシーを重視した代替手段を提供します。
[画像: CheapSecurityのWebインターフェースプレビュー]
プロジェクトの哲学
- プライバシー最優先:すべての映像をローカルに保存することで、サードパーティのクラウドサブスクリプションの必要性をなくし、データがネットワーク外に出ないことを保証します。
- コスト効率:余っているLinuxボードやUSBウェブカメラなどの既存のハードウェアを活用し、継続的な料金なしで完全に機能する監視システムを構築します。
- ミニマリストアーキテクチャ:ソフトウェアは低電力デバイスで効率的に実行できるように最適化されており、エントリーレベルのハードウェアでも高いパフォーマンスを保証します。
主な機能
- ハードウェア非依存:幅広い標準USBウェブカメラと高い互換性があります。
- リソース効率:Linuxベースのボード(例:Raspberry Pi、Orange Pi、または類似のSBC)に特化して最適化されています。
- データ主権:ストレージパス、保持ポリシー、アクセス方法を完全に制御できます。
- 簡単なデプロイメント:迅速なセットアップと簡単なメンテナンスのために設計されています。
機能
- ライブMJPEGストリームとWebダッシュボード
- フレーム差分によるモーション検知
- プリモーションバッファ付き自動録画
- インタラクティブな録画カレンダー:日付でビデオ録画をフィルタリングし、点滅する赤い日付バッジを表示
- クラウドストレージ連携:
- モーション録画のGoogle Driveへの直接自動アップロード(Google Drive API v3経由)
- モーション録画のOneDriveへの直接自動アップロード(Microsoft Graph API経由)
- AES-256 ZIPアップロード暗号化:
- Telegram、Google Drive、またはOneDriveへのアップロード前に、ビデオクリップやスナップショットを個別に暗号化
- パスワード保護された
.zip形式は、iOS(ファイルアプリ)、Android、macOS、Windowsでネイティブに開けます - 暗号化パスフレーズとチャンネルごとのトグルをダッシュボードまたはTelegramボットから管理
- モーション開始時のスナップショット画像付きメールアラート
- Telegram連携:
- モーション録画後の自動ビデオアップロード(AES-256暗号化
.zip配信をサポート) - ボットコマンド:
/snapshot、/video <秒数>、/encryption、/encrypt_telegram_on/off、/encrypt_gdrive_on/off、/encrypt_onedrive_on/off、/sent、/delete、/delete_range、/id、/telegram_on/off、/email_on/off、/help
- モーション録画後の自動ビデオアップロード(AES-256暗号化
- ナイトモード低照度強化(ソフトウェアCLAHE + 明るさ/コントラストブースト、オプションで第2のIR/ナイトカメラを使用)
- 録画の一括操作:すべて選択、Telegram送信、ZIPダウンロード、削除
- REST API用のインタラクティブなSwagger UI(
/api/で利用可能) - RTSP出力(MediaMTX + FFmpeg経由)(オプション、デフォルト無効)
- ストレージクリーンアップ(期間、合計サイズ、緊急時のディスク容量不足時のクリーンアップ)
systemdによる自動起動対応- GNU AGPLv3ライセンス
要件
- Python 3.10以降
- V4L2サポート付きOpenCV(以下のインストールオプションを参照)
- USBウェブカメラ(デフォルトは
/dev/video0) - オプション:Telegram通知用のTelegramボットトークン
- オプション:メールアラート用のSMTP認証情報
クイックスタート
- OpenCVが利用可能か確認します:
python3 -c "import cv2; print(cv2.__version__)"
OpenCVがインストールされていない場合は、次の2つのオプションがあります:
- オプションA — システムのOpenCVパッケージを使用(ARMボードでは推奨。通常、ボードに最適化されたプリビルドのシステムパッケージがあります)。
- オプションB — pipでOpenCVをインストール(x86/amd64マシンやシステムパッケージがない場合に便利)。GUIは不要なため、
opencv-python-headlessを使用します。
- 仮想環境を作成してアクティベートし、アプリをインストールします:
オプションA:システムのOpenCV(ARM推奨)
これにより、システムサイトパッケージを参照できるvenvが作成されるため、venv内でシステムのcv2が利用可能になります。
cd $HOME/CheapSecurity
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install -e .
オプションB:すべてpipでインストール
システムのOpenCVがない場合や、自己完結型のvenvを好む場合に使用します。
cd $HOME/CheapSecurity
python3 -m venv venv
source venv/bin/activate
pip install opencv-python-headless
pip install -e .
注意: 一部の古いARMボードでは、pipの
opencv-python-headlessホイールが利用できないか、遅い場合があります。その場合は、代わりにディストリビューションのパッケージマネージャーからOpenCVをインストールし、オプションAを使用してください。
- ウェブカメラデバイスを見つけます(通常は
/dev/video0):
v4l2-ctl --list-devices
config.json.exampleをconfig.jsonにコピーして編集します:
cp config.json.example config.json
nano config.json
- カメラデバイス、解像度、フレームレートを設定します。
- メールアラートが必要な場合は、SMTP認証情報を入力します。
- Telegramアップロードが必要な場合は、TelegramボットトークンとチャットIDを入力します。
セキュリティ:
config.jsonは.gitignoreに含まれており、コミットしてはいけません。パスワードやトークンが含まれています。必ずconfig.jsonを編集し、config.json.exampleは編集しないでください。新しい設定を追加した場合は、両方のファイルを更新して例を同期させてください。
- アプリを実行します:
./venv/bin/python -m cheapsecurity.app
- ブラウザでダッシュボードを開きます:
http://<odroid-ip>:5000
設定
config.jsonを編集します:
| セクション | キー | 説明 |
|---|---|---|
camera | device | V4L2デバイスインデックス(0 = /dev/video0) |
camera | width, height, fps | キャプチャ解像度とフレームレート。widthとheightを0または"auto"に設定すると、カメラの最大サポート解像度が自動検出され使用されます。 |
camera | night_mode | 低照度強化/IRカメラ切り替えを有効にする |
camera | night_mode_strength | ソフトウェア強化の強度:low、normal、またはaggressive |
camera | night_device | オプションのナイトビジョン用第2V4L2デバイス(例:/dev/video1の場合は1)。単一カメラを使用する場合はnullに設定します。 |
camera | night_device_width, night_device_height, night_device_fps | オプションのナイトカメラの解像度とFPS(width/heightを0または"auto"に設定して最大解像度にする) |
camera | night_software_enhance | IRカメラフィードにCLAHE/ガンマ補正を適用するかどうか(true/false) |
camera | night_mode_fps | ナイトモードでのターゲットFPS(カメラが無視する場合があります) |
camera | night_mode_gain | ナイトモードでのターゲットアナログゲイン(カメラが無視する場合があります) |
camera | night_mode_brightness | ナイトモードでの明るさブースト |
camera | night_mode_contrast | ナイトモードでのコントラストブースト |
motion | threshold | モーションをトリガーするピクセル差分閾値(0-255) |
motion | min_area | モーションをトリガーする最小輪郭面積(フル解像度ピクセル) |
motion | blur_size | ノイズリダクション用のガウシアンブラーカーネルサイズ(奇数) |
motion | cooldown_seconds | 最後のモーション後、モーションフラグをアクティブに保つ秒数 |
motion | recording_tail_seconds | 最後のモーション後、録画を継続する秒数(ドア開閉/人物侵入のバーストを1つのクリップに結合) |
motion | scale | モーション検出のスケーリングダウンファクター(CPUを節約) |
recording | dir | ビデオが保存される場所 |
recording | max_duration_seconds | 1クリップの最大長 |
recording | pre_buffer_seconds | モーション前にクリップに含まれる秒数 |
recording | codec | 推奨FourCCコーデック(低CPUの場合はMJPG、ファイルサイズが小さい場合はmp4v) |
notifications | enabled | モーション時にメールアラートを送信するかどうか |
notifications | smtp | SMTPサーバー、ポート、ユーザー名、パスワード、TLS |
notifications | from, to, subject | メール送信者/受信者/件名(複数の受信者の場合は["a@...", "b@..."]を使用) |
notifications | min_interval_minutes | アラートメール間の最小間隔 |
telegram | enabled | モーション録画後にビデオをTelegramに送信するかどうか |
telegram | bot_token, chat_id | TelegramボットAPIトークンと宛先チャットID |
telegram | send_video | ビデオファイルを自動アップロードするかどうか |
telegram | min_interval_minutes | Telegramアップロード間の最小間隔 |
telegram | poll_commands | /snapshot、/video、/helpボットコマンドを有効にするかどうか |
cloud | google_drive | Google Drive自動アップロード設定(enabled、client_id、client_secret、refresh_token、オプションのfolder_id) |
cloud | onedrive | Microsoft OneDrive自動アップロード設定(enabled、client_id、client_secret、refresh_token、folder_path) |
encryption | passphrase | ZIPアーカイブを暗号化するために使用される秘密パスフレーズ(AES-256) |
encryption | telegram | TelegramアップロードとスナップショットのAES-256 ZIP暗号化を有効にする(true/false) |
encryption | google_drive | Google DriveアップロードのAES-256 ZIP暗号化を有効にする(true/false) |
encryption | onedrive | OneDriveアップロードのAES-256 ZIP暗号化を有効にする(true/false) |
storage | max_age_days | この日数より古い録画を削除(デフォルト3日=72時間) |
storage | max_size_gb | 合計サイズがこれを超えた場合に最も古いファイルを削除 |
storage | cleanup_interval_minutes | ストレージクリーンアップの実行間隔 |
storage | delete_old_on_startup | falseの場合、アプリ再起動時に古い録画は保持されます |
storage | emergency_free_space_gb | ディスク空き容量がこれより少なくなった場合、新しいクリップの前に古い録画を削除 |
storage | emergency_delete_count | 緊急クリーンアップで削除される最も古い録画の数 |
rtsp | enabled | HTTP MJPEGストリームに加えてRTSPストリームを公開するかどうか |
rtsp | port | RTSPリスナーポート(デフォルト8554) |
rtsp | path | RTSPパス(デフォルトlive) |
rtsp | width, height, fps | RTSPストリームの解像度とフレームレート |
rtsp | mediamtx_binary | MediaMTX実行ファイルへのパス |
rtsp | mediamtx_config | rtsp/mediamtx.ymlへのパス |
web | host, port | ダッシュボードのバインドアドレスとポート |
web | stream_scale | ライブストリームのスケーリングダウンファクター(帯域幅/CPUを節約) |
web.auth | enabled, username, password | オプションのHTTP Basic認証 |
config.jsonから機密情報を除外する
デフォルトでは、すべての認証情報はconfig.jsonに保存されます。ファイルは制限付き(0o600)のパーミッションで作成されますが、環境変数を通じて実際の機密情報をディスクから除外できます。環境変数の値は設定ファイルよりも優先され、ディスクに書き戻されることはありません。
| 機密情報 | 環境変数 |
|---|---|
| Telegramボットトークン | CHEAPSECURITY_TELEGRAM_BOT_TOKEN |
| TelegramチャットID | CHEAPSECURITY_TELEGRAM_CHAT_ID |
| SMTPパスワード | CHEAPSECURITY_SMTP_PASSWORD |
| Google DriveクライアントID | CHEAPSECURITY_GDRIVE_CLIENT_ID |
| Google Driveクライアントシークレット | CHEAPSECURITY_GDRIVE_CLIENT_SECRET |
| Google Driveリフレッシュトークン | CHEAPSECURITY_GDRIVE_REFRESH_TOKEN |
| OneDriveクライアントID | CHEAPSECURITY_ONEDRIVE_CLIENT_ID |
| OneDriveクライアントシークレット | CHEAPSECURITY_ONEDRIVE_CLIENT_SECRET |
| OneDriveリフレッシュトークン | CHEAPSECURITY_ONEDRIVE_REFRESH_TOKEN |
| ZIP暗号化パスフレーズ | CHEAPSECURITY_ENCRYPTION_PASSPHRASE |
| Webダッシュボードパスワード | CHEAPSECURITY_WEB_AUTH_PASSWORD |
systemdユニットの例:
[Service]
Environment="CHEAPSECURITY_TELEGRAM_BOT_TOKEN=123456:ABC..."
Environment="CHEAPSECURITY_ENCRYPTION_PASSPHRASE=your-strong-passphrase"
EnvironmentFile=-/etc/cheapsecurity.env
systemdサービスのリギング
機密情報を環境変数に設定しても、バックエンドは通常のユーザーとして実行されます。プロセスがファイルシステムにアクセスできる範囲を制限するようにサンドボックス化できます。
[Service]
User=cheapsecurity
Group=cheapsecurity
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/home/cheapsecurity/CheapSecurity/recordings
BindReadOnlyPaths=/home/cheapsecurity/CheapSecurity/config.json
これにより、アプリは録画ディレクトリとconfig.jsonへの読み取り専用アクセスに限定されます。注意: 攻撃者がroot権限またはサービスユーザーアカウントを取得した場合、そのユーザーが読み取れるもの(環境変数や認証情報ファイルを含む)はすべて読み取られる可能性があります。最も強力な保護のためには、信頼できるLAN上のHTTPSリバースプロキシの後ろで実行し、OSを最新の状態に保ってください。
Telegram設定
1. ボットの作成
- Telegramを開き、@BotFatherにメッセージを送信します。
/newbotを送信し、プロンプトに従って表示名とユーザー名を選択します。- ボットトークン(
123456789:ABCdefGHIjklMNOpqrsTUVwxyzのような形式)をコピーします。 - このトークンは秘密にしておいてください。誰でもこのトークンでボットを制御できます。
2. チャットIDの取得
- 新しいボットとのプライベートチャットを開始し、任意のメッセージ(例:
/start)を送信します。 - ブラウザで以下のURLを開き、
<YOUR_BOT_TOKEN>を実際のトークンに置き換えます:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
"chat":{"id":123456789を探します。この数値がチャットIDです。getUpdatesが空の場合は、ボットに別のメッセージを送信して更新してください。- グループチャットを使用したい場合は、まずボットをグループに追加し、そこでメッセージを送信してください。グループのチャットIDは負数になります。
- チャットIDを正確にコピーします。グループの場合はハイフン(
-)を含めてください。
3. アプリの設定
config.jsonのtelegramセクションに入力します:
"telegram": {
"enabled": true,
"bot_token": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz",
"chat_id": "123456789",
"send_video": true,
"min_interval_minutes": 5,
"poll_commands": true
}
その後、サービスを再起動します:
sudo systemctl restart cheapsecurity@$(whoami).service
自動アップロード
モーションクリップが保存されると、ビデオはTelegramチャットにアップロードされます。アップロードはmin_interval_minutesによってレート制限されます。
ボットコマンド
設定したチャットから、以下のコマンドを送信します:
/snapshot— 現在のカメラ画像を受信します。/video 10— 10秒間のビデオを録画して送信します(1〜60秒、デフォルト10秒)。/sent— 削除可能な最近のボットメッセージをメッセージIDとともに一覧表示します。/delete <message_id>— チャットからボットメッセージを削除します。/delete last— 最新のボットメッセージを削除します。/delete_range <min_id> <max_id>— 指定範囲内の追跡済みメッセージを削除します(最大100件)。/id— ボットメッセージにこのコマンドで返信すると、そのメッセージIDが表示されます。/telegram_on//telegram_off— 自動Telegramアップロードを有効または無効にします。/email_on//email_off— メール通知を有効または無効にします。/help— コマンド一覧を表示します。
ボットは設定されたchat_idからのメッセージのみに応答します。
モーションが優先されます: システムがモーション検出のために既に録画中の場合、/videoリクエストはそれを中断しません。ボットはモーションビデオが進行中であり、自動的にアップロードされる旨を返信します。
AES-256 アップロード暗号化
CheapSecurityでは、ビデオクリップやスナップショットを公開チャンネル(Telegram、Google Drive、またはOneDrive)にアップロードする前に暗号化できます。
ファイルは、AES-256暗号化を使用した標準のパスワード保護付き.zipアーカイブにパッケージ化されます。
動作概要
| チャンネル | 暗号化ON(パスフレーズ設定済み) | 暗号化OFF |
|---|---|---|
Telegramスナップショット (/snapshot) | AES-256 .zipファイルとして送信(snapshot_TIMESTAMP.zip) | 通常の.jpg写真として送信 |
**Telegramビデオ (/video & モーション) ** | AES-256 .zipファイルとして送信(motion_TIMESTAMP.zip) | 通常の.mp4/.aviビデオとして送信 |
| Google Driveアップロード | AES-256 .zipファイルとしてアップロード | 通常の.aviビデオとしてアップロード |
| OneDriveアップロード | AES-256 .zipファイルとしてアップロード | 通常の.aviビデオとしてアップロード |
| ローカルOdroidの映像 | ダッシュボードでの高速再生のためにOdroidに暗号化せずに保存 | ダッシュボードでの高速再生のためにOdroidに暗号化せずに保存 |
デバイスでのメディアの復号化と再生
暗号化が有効な場合、ダウンロードされたファイルは標準のパスワード保護付き.zipアーカイブです。追加のソフトウェアやWebアプリは不要です!
- iPhone (iOS):TelegramまたはiOSファイルアプリで
.zipファイルをタップし、求められたらパスフレーズを入力し、解凍された.mp4または.jpgをタップしてネイティブに表示します。 - Android:Files by Googleまたはファイルマネージャーで
.zipファイルをタップし、パスフレーズを入力して展開して表示します。 - Mac / Windows / Linux:
.zipファイルをダブルクリック(または7-Zip、WinRAR、Keka、macOS Archive Utilityを使用)し、パスフレーズを入力して、暗号化されていないビデオを再生します。
Telegramボットによる暗号化管理
Telegramボットコマンドを使用して、オンザフライでアップロード暗号化を確認および切り替えることができます:
/encryption— 現在のパスフレーズステータスとチャンネル暗号化状態を表示します。/encrypt_telegram_on//encrypt_telegram_off— Telegram AES-256暗号化を切り替えます。/encrypt_gdrive_on//encrypt_gdrive_off— Google Drive AES-256暗号化を切り替えます。/encrypt_onedrive_on//encrypt_onedrive_off— OneDrive AES-256暗号化を切り替えます。
メールアラート
config.jsonのnotificationsセクションを設定します。モーション開始時のスナップショット画像が添付されます。アラートはmin_interval_minutesによってレート制限されます。
Gmail / Google Workspaceの設定
Googleはもはや「セキュリティの低いアプリ」が通常のGmailパスワードを使用することを許可していません。アプリパスワードを作成する必要があります。
- Googleアカウントで2段階認証プロセスを有効にします:
- アプリパスワードを作成します:
- https://myaccount.google.com/apppasswordsに移動します。
- アプリを選択:メール
- デバイスを選択:その他(カスタム名) — 「CheapSecurity」と入力します。
- 生成をクリックし、16文字のパスワード(例:
abcd efgh ijkl mnop)をコピーします。
config.jsonで以下のように設定します:
"notifications": {
"enabled": true,
"smtp": {
"server": "smtp.gmail.com",
"port": 465,
"username": "you@gmail.com",
"password": "abcdefghijklmnop",
"use_tls": true
},
"from": "you@gmail.com",
"to": "you@gmail.com",
"subject": "CheapSecurity motion alert",
"min_interval_minutes": 5
}
passwordフィールドには、Googleアカウントのパスワードではなく、アプリパスワード(スペースなし)を使用します。- Google Workspaceアカウントの場合、ユーザー名は通常、完全なメールアドレスです。
- アプリは、設定したポートで暗黙的なTLS(
SMTP_SSL)を使用します。Gmailはポート465でこれを許可します。
複数の受信者
"to": [
"you@gmail.com",
"family@example.com"
]
ナイトモード
ナイトモードは2つの方法で機能します:
単一カメラ(ソフトウェア強化)
デフォルトモードは、1つのUSBカメラからの暗いシーンを次のように改善します:
- ソフトウェア強化(ガンマ補正 + LチャンネルのCLAHE)
- カメラの明るさ/コントラストブースト
- カメラがサポートしている場合、FPSの低下とゲイン/ISOの上昇を試みます。
ソフトウェア強化の強度は、ダッシュボードまたはTelegramから選択可能です:low、normal、またはaggressive。
重要: ほとんどのUSBウェブカメラは、V4L2経由でISO/ゲイン/露出制御を公開していないため、FPS/ゲイン調整は無視される可能性があります。結果は通常ノイズが多く、いくらかの環境光がある場合にのみ役立ちます。
デュアルカメラナイトビジョン(ハードウェア/IR)
実際のナイトビジョンのためには、IR感度のUSBカメラやIRカットフィルターが除去されたカメラ、オプションでIRイルミネーターなどを接続できます。camera.night_deviceが設定されている場合、ナイトモードを有効にすると、ビデオソースが自動的にデイカメラからIRカメラに切り替わり、無効にすると元に戻ります。一度に開かれるカメラは1台だけなので、USB帯域幅は倍になりません。
設定例:
"camera": {
"device": 0,
"width": 2560,
"height": 1440,
"fps": 15,
"night_mode": false,
"night_mode_strength": "low",
"night_device": 1,
"night_device_width": 1280,
"night_device_height": 720,
"night_device_fps": 15,
"night_software_enhance": false
}
night_device— IRカメラのV4L2デバイスインデックス(例:/dev/video1の場合は1)。シングルカメラモードの場合はnullに設定します。night_device_width/height/fps— IRカメラの解像度とフレームレート。night_software_enhance— IR画像が既に利用可能な場合はfalseに設定します。CLAHE/ガンマ補正をIRフィードにも適用したい場合はtrueに設定します。
IRカメラが開けない場合、システムはデイカメラにフォールバックし、警告をログに記録します。
cronによるナイトモードのスケジュール設定
Odroid(または任意のLinuxホスト)でcronを使用して、デイカメラとIRカメラを自動的に切り替えることができます。ダッシュボードのREST APIは、CSRFに安全なヘッダーとしてX-Requested-With: XMLHttpRequestを受け入れるため、単純なcurlコマンドで十分です。
認証なしの場合:
# 午後10時にIR/ナイトカメラに切り替え
curl -s -X POST http://192.168.178.41:5000/api/settings/night_mode \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{"enabled": true, "strength": "low"}'
# 午前6時30分にデイカメラに戻す
curl -s -X POST http://192.168.178.41:5000/api/settings/night_mode \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{"enabled": false}'
Basic認証ありの場合:
curl -s -X POST http://192.168.178.41:5000/api/settings/night_mode \
-u admin:YOUR_PASSWORD \
-H "Content-Type: application/json" \
-H "X-Requested-With: XMLHttpRequest" \
-d '{"enabled": true, "strength": "low"}'
crontab(crontab -e)に追加します:
# 午後10時にナイト(IR)カメラに切り替え
0 22 * * * curl -s -X POST http://192.168.178.41:5000/api/settings/night_mode -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" -d '{"enabled": true, "strength": "low"}' > /dev/null 2>&1
# 午前6時30分にデイカメラに戻す
30 6 * * * curl -s -X POST http://192.168.178.41:5000/api/settings/night_mode -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" -d '{"enabled": false}' > /dev/null 2>&1
ヒント: Basic認証を有効にした場合は、crontabに直接貼り付けるのではなく、認証情報を環境変数または小さなラッパースクリプト(
0600パーミッション付き)に保存してください。
ストレージとクリーンアップ
- 録画は
recordings/に保存されます。 max_age_daysより古い録画は、起動時ではなく定期的なクリーンアップ中に削除されます(delete_old_on_startupがtrueの場合は除く)。- ディスク空き容量が
emergency_free_space_gbを下回った場合、新しいクリップを開始する前に、最も古いemergency_delete_count件の録画が削除されます。 max_age_daysより古い録画、またはmax_size_gbを超える録画は、定期的なクリーンアップ中に削除されます。
REST API & Swagger UI
CheapSecurityは、小さなREST APIを公開し、インタラクティブなSwagger UIを以下で提供します:
http://<odroid-ip>:5000/api/
Swaggerページには、すべてのエンドポイントが文書化されており、リクエスト/レスポンスの例が表示されます。ブラウザから直接エンドポイントを試すことができます。
認証
web.auth.enabledがtrueの場合、APIはHTTP Basic認証を使用します。Swaggerでは、Authorizeをクリックしてユーザー名/パスワードを入力します。スクリプトからは、curlで認証情報を含めます:
curl -u admin:changeme http://<odroid-ip>:5000/api/status
CSRF保護
Webダッシュボードは、CSRFチェック(X-Requested-With: XMLHttpRequestヘッダー)でPOSTエンドポイントを保護します。Swagger UIページからのリクエストは自動的に許可されます。独自のスクリプトからは、ヘッダーを追加します:
curl -u admin:changeme \
-H "X-Requested-With: XMLHttpRequest" \
-X POST http://<odroid-ip>:5000/api/settings/night_mode \
-H "Content-Type: application/json" \
-d '{"enabled": true}'
主要なエンドポイント
GET /api/status— 現在のエンジンの状態GET /api/recordings— 保存されたビデオのリストPOST /api/recordings/delete— 選択した録画を削除POST /api/recordings/download— 選択した録画をZIPでダウンロードPOST /api/recordings/telegram— 選択した録画をTelegramに送信POST /api/telegram/delete— 以前に送信したTelegramメッセージをIDで削除POST /api/telegram/delete_range— 指定ID範囲内の追跡済みTelegramメッセージを削除POST /api/settings/{telegram,night_mode,notifications,auth}— 機能の切り替えPOST /api/snapshot— JPEGスナップショットをキャプチャしてダウンロードPOST /api/video— 手動録画を開始(デフォルト10秒、最大60秒)
例:コマンドラインからのスナップショット
curl -u admin:changeme \
-H "X-Requested-With: XMLHttpRequest" \
-X POST http://<odroid-ip>:5000/api/snapshot \
--output snapshot.jpg
例:10秒間の手動録画を開始
curl -u admin:changeme \
-H "X-Requested-With: XMLHttpRequest" \
-X POST http://<odroid-ip>:5000/api/video \
-H "Content-Type: application/json" \
-d '{"seconds": 10}'
Webインターフェース
- ライブストリーム
- ステータスペネル(解像度、FPS、録画状態、モーション状態)
- 設定トグル:ナイトモード、メール通知、Telegramアップロード、組み込みBasic認証
- 各行にチェックボックスと一括操作を備えた録画リスト:
- すべて選択
- Telegramに送信
- 選択したものをダウンロード(ZIP)
- 選択したものを削除
/api/にあるSwagger APIドキュメントへのリンク
RTSP出力の有効化(オプション)
CheapSecurityは、ライブMJPEGストリームをRTSPストリームとして再公開できます。これにより、Webダッシュボードを使用せずに、VLC、IPカメラアプリ、NVR、またはRTSPをサポートする任意のソフトウェアでカメラを視聴できます。
RTSPは、追加のCPU負荷がかかるため、デフォルトで無効になっています。
クイックスタート:RTSPの有効化
- FFmpegとMediaMTXをインストールします(以下のオプションを参照)。
rtsp/mediamtx.ymlがプロジェクトフォルダ内に存在することを確認します。config.jsonで"rtsp": { "enabled": true, ... }を設定します。- サービスを再起動します:
sudo systemctl restart cheapsecurity@$(whoami).service
rtsp://<odroid-ip>:8554/liveをRTSPプレイヤーで開きます。
以下のサブセクションで各ステップを詳細に説明します。
仕組み
- CheapSecurityは、設定されたRTSPポートでローカルのMediaMTXサーバーを起動します。
- FFmpegを起動し、
http://127.0.0.1:5000/video_feedからHTTP MJPEGストリームを読み取ります。 - FFmpegは、ストリームをMediaMTXに
rtsp://127.0.0.1:<port>/<path>として再公開します。 - ネットワーク上の任意のRTSPクライアントが
rtsp://<odroid-ip>:<port>/<path>に接続できます。
1. 依存関係のインストール
FFmpegとMediaMTXが必要です。
注意: 以下のコマンドは
sudoを使用します。ボードのrootアクセスがsu経由の場合は、まずsuを実行し、sudoなしでコマンドを実行してください。
- FFmpegがインストールされていること(
ffmpeg -version)。ビデオ期間の修正にも使用されます。 - MediaMTXはいくつかの方法でインストールできます:
オプションA — 事前ビルド済みバイナリのダウンロード(最速)
ボードに合った静的バイナリをhttps://github.com/bluenviron/mediamtx/releasesからダウンロードします。Odroid XU4(ARMv7)の場合は、ARMv7ビルドを選択します。
wget https://github.com/bluenviron/mediamtx/releases/download/v1.12.0/mediamtx_v1.12.0_linux_armv7.tar.gz
tar -xzf mediamtx_v1.12.0_linux_armv7.tar.gz
sudo install -m 755 mediamtx /usr/local/bin/mediamtx
v1.12.0を最新リリースに置き換えてください。
次に、バンドルされた設定ファイルをプロジェクトにコピーします:
mkdir -p rtsp
cp mediamtx.yml rtsp/mediamtx.yml
リポジトリには既に最小限のrtsp/mediamtx.ymlが含まれており、デフォルト設定で動作します。アップストリームのデフォルトを使用したい場合は、MediaMTXアーカイブからコピーするだけで済みます。
オプションB — Odroid上でソースからMediaMTXをコンパイル
ソースからビルドしたい場合は、Go(≥1.26)をインストールし、ボード上で直接ビルドします:
# ディストリビューションまたはhttps://go.dev/dl/からGoをインストール
sudo apt update
sudo apt install golang-go git
# クローンとビルド
git clone https://github.com/bluenviron/mediamtx /tmp/mediamtx
cd /tmp/mediamtx
go generate ./
CGO_ENABLED=0 go build .
# バイナリのインストール
sudo install -m 755 mediamtx /usr/local/bin/mediamtx
これにより、ネイティブなARMv7 mediamtxバイナリが生成されます。
オプションC — 別のマシンからARMv7用にクロスコンパイル
より高速なx86/amd64マシンでコンパイルし、バイナリをOdroidにコピーしたい場合は、Goのクロスコンパイルを使用します:
git clone https://github.com/bluenviron/mediamtx
cd mediamtx
go generate ./
CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build .
次に、生成されたmediamtxバイナリをOdroidにコピーします。例:
scp mediamtx marco@<odroid-ip>:/tmp/mediamtx
ssh marco@<odroid-ip> "sudo install -m 755 /tmp/mediamtx /usr/local/bin/mediamtx"
Odroid上でも、設定ファイルをコピーします:
mkdir -p rtsp
cp mediamtx.yml rtsp/mediamtx.yml
2. config.jsonでRTSPを有効にする
"rtsp": {
"enabled": true,
"port": 8554,
"path": "live",
"width": 1280,
"height": 720,
"fps": 15,
"mediamtx_binary": "/usr/local/bin/mediamtx",
"mediamtx_config": "rtsp/mediamtx.yml"
}
バンドルされているrtsp/mediamtx.ymlは、RTSPをTCP(rtspTransports: [tcp])で強制します。これはUDPよりもルーターやファイアウォール経由で信頼性が高くなります。ローカルネットワークでUDPを優先する場合は、rtsp/mediamtx.ymlを編集して[udp, tcp]または[udp]に変更してください。
width、height、fpsをボードのCPUに合わせて調整します。解像度とFPSを低くすると負荷が軽減されます。
3. サービスを再起動する
sudo systemctl restart cheapsecurity@$(whoami).service
4. ストリームを視聴する
ストリームURLは次のとおりです:
rtsp://<odroid-ip>:8554/live
例:
- VLC → メディア → ネットワークストリームを開く →
rtsp://<odroid-ip>:8554/liveを貼り付けます。 - ffplay:
ffplay -rtsp_transport tcp rtsp://<odroid-ip>:8554/live
-rtsp_transport tcpフラグは、ルーター/ファイアウォール経由でのUDP RTPの問題を回避します。VLCにも同様の--rtsp-tcpオプションがあります。
- Android IPカメラアプリ — 上記のRTSP URLでカメラを追加します。
- NVR / Home Assistant — カメラソースとして同じRTSP URLを使用します。
5. 動作していることを確認する
ログでMediaMTXとFFmpegを確認します:
sudo journalctl -u cheapsecurity@$(whoami).service -f
次のようなメッセージが表示されるはずです:
RTSPPublisher: MediaMTX ready on port 8554
RTSPPublisher: FFmpeg publisher started
パフォーマンスとトラブルシューティング
- RTSPはHTTP MJPEGストリームから再公開されるため、追加のCPUを使用します。Odroid XU4では、1280×720 @ 15fpsが良好な開始点です。
- HTTP Basic認証が有効な場合、FFmpegは認証なしで
localhostから/video_feedを読み取ることが許可されるため、RTSPは引き続き機能します。 - 他のコンピューターから視聴する場合は、ファイアウォールでポート
8554/tcpが開いていることを確認してください。 - RTSPストリームが表示されない場合は、以下を確認してください:
- MediaMTXバイナリが存在し、実行可能であること。
rtsp/mediamtx.ymlが存在すること。- FFmpegがインストールされていること。
http://<odroid-ip>:5000/video_feedのダッシュボードストリームが機能すること。
- クライアントが接続しても黒い画面/ビデオが表示されない場合は、クライアントがUDPを選択し、RTPパケットがブロックされている可能性があります。クライアントでTCPを強制するか(ffplayでは
-rtsp_transport tcp、VLCでは--rtsp-tcp)、rtsp/mediamtx.ymlでrtspTransports: [tcp]を維持してサービスを再起動してください。
本番環境へのデプロイ
Flaskの開発サーバーをインターネットに公開しないでください。組み込み認証の後ろ、または信頼できる他のリバースプロキシでGunicornを使用してください。
1. Gunicornのインストール
これは既にpyproject.tomlで定義されています:
cd $HOME/CheapSecurity
source venv/bin/activate
pip install -e .
2. systemd + Gunicornでの実行
サービステンプレートをコピーし、ユーザーシェルから有効化します:
sudo cp cheapsecurity.service /etc/systemd/system/cheapsecurity@.service
sudo systemctl daemon-reload
sudo systemctl enable --now cheapsecurity@$(whoami).service
これにより、Gunicornは0.0.0.0:5000に1つのワーカーと4つのスレッドでバインドされ、ダッシュボードとストリームがネットワーク上で直接到達可能になります。カメラは単一のプロセスで開く必要があるため、ワーカーは1つだけ使用されます。
セキュリティ: インターネットに公開する場合は、Gunicornの前にHTTPSと認証を備えたリバースプロキシを配置してください。ローカルでのみアクセスする場合は、組み込み認証を有効にしたままにしてください。
ログを表示します:
sudo journalctl -u cheapsecurity@$(whoami).service -f
プロジェクト構造
CheapSecurity/
├── src/
│ └── cheapsecurity/ # Pythonパッケージ
│ ├── app.py # 開発用ランチャー
│ ├── cctv.py # モーション検出、録画、アラート、Telegramボット
│ ├── web.py # FlaskダッシュボードとAPI
│ ├── wsgi.py # 本番用WSGIエントリーポイント
│ ├── diagnose.py # 診断/トラブルシューティングスクリプト
│ ├── templates/ # HTMLテンプレート
│ └── static/ # CSS/JS
├── tests/ # テストスイート
├── config.json # ローカル設定(gitignore済み、コミットしない)
├── config.json.example # 設定例テンプレート(コミット済み)
├── pyproject.toml # パッケージメタデータと依存関係
├── cheapsecurity.service # systemdテンプレート
├── LICENSE # GNU AGPLv3
└── recordings/ # 保存されたビデオ
トラブルシューティング
録画が表示されなくなった場合:
- サービスが実行中か確認します:
sudo systemctl status cheapsecurity@$(whoami).service
- ログを確認します:
sudo journalctl -u cheapsecurity@$(whoami).service -f
- 診断スクリプトを実行します:
source venv/bin/activate
python -m cheapsecurity.diagnose
- モーションが検出されない場合は、
motion.min_areaを低くしてみてください。
AIフルディスクロージャー
このソフトウェアは、Kimi 2.7およびGemini 3.6 Flashの強力な支援を受けて開発されました。アイデア、テスト、デバッグは人間が主導しました。プロジェクトの構築方法に影響を与えたため、これを公に開示します。AI開発コードに満足できない場合は、このソフトウェアはあなた向けではありません。
ライセンス
このプロジェクトは、GNU Affero General Public License v3.0以降(AGPLv3)の下でライセンスされています。LICENSEを参照してください。