CheapSecurity プロジェクト概要

Linux ベースのシングルボードコンピューター（SBC）および USB ウェブカメラ向けに設計された、軽量なセルフホスト型 CCTV ソリューションです。映像データを完全にローカル管理し、低コストかつプライバシーを重視した家庭用監視システムの代替案となります。

プロジェクトの理念

• プライバシー第一: 全データはローカル保存のため、サードパーティクラウドサブスクリプション不要。
• 費用対効果: 既存の廃棄 Linux ボードや USB カメラを活用し、リカレントコストなしでシステム構築。
• ミニマリストなアーキテクチャ: 低消費電力での動作最適化を実現。

メインの特徴

• ハードウェア非依存: 幅広い標準的な USB ウェブカメラとの互換性が高い。
• リソース効率: Raspberry Pi や Orange Pi などの SBC で効率的に動作。
• データ主権: ストレージパス、保存ポリシー、アクセス制御を完全に行える。
• シンプルな展開: 素早いセットアップとメンテナンスが可能。

機能詳細

• Web ダッシュボードでのライブ MJPEG 配信
• フレーム差分による動き検出
• 動き発生前の事前バッファを確保した自動録画
• 動き検出時、スナップショット付きメール通知
• Telegram インテグレーション:
  • 動き検出後の自動ビデオアップロード
  • ボットコマンド:

    /snapshot

    、

    /video <秒数>

    、

    /help

• ナイトモード用低照度強調処理（CLAHE + Brightness/Contrast 調整）
• 録画のバッチ操作（ZIP ダウンロード、削除等）
• ディスク容量管理（年齢ベース、サイズベース、緊急時対応）
• systemd での自動起動
• GNU AGPLv3 ライセンス

要件事項

• Python 3.10 以上
• V4L2 サポート付き OpenCV
• USB ウェブカメラ（デフォルト：

  /dev/video0

  ）
• オプション: Telegram ボットトークン、SMTP クレデンシャル

クイックスタート

OpenCV の確認とインストール

まず、OpenCV が利用可能か確認します。

python3 -c "import cv2; print(cv2.__version__)"

インストールされていない場合は以下から選択してください。

• オプション A: システムパッケージを使用（ARM ボード推奨）
  • Odroid XU4 など、プリビルトパッケージが最適化されているボード向け。
• オプション B: pip を介してインストール（x86/amd64 推奨）
  • GUI が不要なため

    opencv-python-headless

    を使用。

仮想環境の作成とアプリのインストール

方法 A: システム OpenCV を使用 venv 内にシステムの

cv2

を読み込ませるため、システムサイトパッケージを読み込みます。

cd $HOME/CheapSecurity
python3 -m venv venv --system-site-packages
source venv/bin/activate
pip install -e .

方法 B: pip 経由で完結な環境を作成

cd $HOME/CheapSecurity
python3 -m venv venv
source venv/bin/activate
pip install opencv-python-headless
pip install -e .

注意: 一部の古い ARM ボードでは、

opencv-python-headless

のホイールが利用できないか動作が遅いため、その場合はシステムパッケージ（方法 A）を使用してください。

設定の準備

1. Web カメラデバイスの確認: 通常は

   /dev/video0

   です。
2. 設定ファイルのコピーと編集:

   cp config.json.example config.json
   nano config.json
   

   • カメラデバイス、解像度、フレームレートの設定
   • メール通知用 SMTP クレデンシャルの入力
   • Telegram 通知用 ボットトークンとチャット ID の入力

セキュリティ注意:

config.json

は

.gitignore

で管理されているため、絶対に関係ありません。パスワードやトークンは含んでおり、必ず

config.json.example

を編集せず、既存の設定ファイルを更新してください。

1. アプリの実行:

   ./venv/bin/python -m cheapsecurity.app
   

2. ブラウザでのアクセス: ダッシュボード URL にアクセスします。

設定 (

config.json

)

主要な設定項目一覧です。

セクション	キー	説明
camera	device	V4L2 デバイスインデックス（0 = /dev/video0）
camera	width, height, fps	撮影解像度とフレームレート
camera	night_mode	ロー照度強調を有効化
camera	night_mode_*	ナイトモードの詳細設定（FPS、ゲイン、明るさ、コントラスト）
motion	threshold	ピクセル差分閾値（0-255）
motion	min_area	動きトリガー用の最小コンタクト面積（ピクセル単位）
motion	cooldown_seconds	動き終了後の継続録画時間
recording	dir	ビデオ保存先ディレクトリ
recording	codec	FourCC コーデック（MJPG: 低 CPU, mp4v: 小容量）
notifications	enabled	メール通知の有効化
notifications	smtp	SMTP サーバー、ポート、ユーザー名、パスワード
telegram	bot_token, chat_id	Telegram Bot API の認証情報
storage	max_age_days	古い録画を削除する日数（デフォルト 3 日）
storage	max_size_gb	容量超過時の自動削除閾値
web	host, port	ダッシュボードのバインドアドレスとポート
web.auth	username, password	HTTP ベーシック認証情報

Telegram セットアップ

1. ボットの作成

Telegram を開き、

@BotFather

にメッセージを送ります。

/newbot

を選択し、表示名とユーザー名を設定してトークンを取得します。

2. チャット ID の取得

ボットとプライベートチャットを作成後、以下の API エンドポイントにアクセスして確認します。

https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

レスポンス内の

"chat":{"id":123456789}

の部分の

id

がチャット ID です。グループの場合は ID は負の値になります。

3. アプリ設定と再起動

取得したトークンと ID を

config.json

に設定後、サービスを再起動します。

sudo systemctl restart cheapsecurity@$(whoami).service

ボットコマンド:

• /snapshot

  — カメラ画像の受信

• /video 10

  — 指定秒数のビデオ録画と送信（例：10 秒）

• /help

  — コマンド一覧表示

動き優先: システムがすでに動き検出により録画中の場合、手動で

/video

を発令しても中断されません。

メール通知設定

Gmail や Google Workspace の場合、通常のパスワードは使用不可です。App Password を作成する必要があります。

1. Google アカウントで2 段階認証を有効化。
2. アプリ用パスワードを作成（

   https://myaccount.google.com/apppasswords

   ）。
   • アプリ種別: Mail
   • デバイス名: Other (Custom name) に「CheapSecurity」と入力。

config.json

の

notifications.smtp.password

には、この App Password（スペースなし）を入力します。

複数の宛先へ送信

"to": [
  "you@gmail.com",
  "family@example.com"
]

ナイトモード

ダッシュボードから切り替え可能です。以下の要素を組み合わせ、低照度環境での可視性を向上させます。

• ソフトウェア強化（CLAHE）
• カメラの明るさ/コントラストブースト

重要: 多くの USB ウェブカメラは V4L2 経由で ISO/ゲイン制御を提供しないため、これらの設定は無視される可能性があります。真の夜間監視にはIR 感応型カメラと IR イリミネータが必要です。

ストレージとクリーンアップ

• 自動削除:

  max_age_days

  経過後や

  max_size_gb

  超え時に最古ファイルを削除（起動時ではなく定期タスクで行うことが推奨）。
• 緊急時対応: ディスク空き容量が

  emergency_free_space_gb

  を下回ると、新しいクリップ開始前に最古の録画を

  emergency_delete_count

  分削除します。

ウェブインターフェース（ダッシュボード）

• ステータスペネル: 解像度、FPS、録画状態、動き検出状況を表示。
• 設定トグル: ナイトモード、メール通知、Telegram アップロード、認証の有効化/無効化。
• 録画リスト管理: チェックボックス付きで以下のバッチ操作が可能。
  • すべて選択
  • Telegram へ送信
  • ZIP でダウンロード
  • 削除

本番環境へのデプロイ

セキュリティ警告: Flask 開発サーバーはインターネット公開に適していません。Gunicorn とリバースプロキシ（HTTPS+認証）を使用してください。

Gunicorn のインストールと実行

cd $HOME/CheapSecurity
source venv/bin/activate
pip install -e .

systemd サービスファイルを作成し、起動します。

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 ワーカーで動作します（カメラ単一プロセスのため）。

セキュリティ: 本番公開時は、必ず Gunicorn の前にHTTPS と認証付きリバースプロキシを配置してください。

プロジェクト構造

CheapSecurity/
├── src/cheapsecurity/      # Python パッケージ
│   ├── app.py              # 開発用ランチャー
│   ├── cctv.py             # 核心機能（検出、録画、通知）
│   ├── web.py              # Flask ダッシュボード
│   └── diagnose.py         # デバッグツール
├── tests/                  # テストスイート
├── config.json             # ローカル設定（絶対に関係ありません！）
├── config.json.example     # 例設定テンプレート
├── pyproject.toml          # パッケージメタデータ
├── cheapsecurity.service   # systemd サービスファイル
└── LICENSE                 # GNU AGPLv3

ライセンス

本プロジェクトは GNU Affero General Public License v3.0 (AGPLv3) の条件下でライセンスされています。