IPCam_OrangePi_Dashboard/INSTALL.md

IPCam Orange Pi Dashboard — INSTALL

Tài liệu này hướng dẫn triển khai trên Orange Pi (Linux). Mục tiêu: MediaMTX chạy như media server, FastAPI chạy như dashboard backend, React build ra static.

0) Mô hình triển khai

A) 1 thiết bị (đơn giản nhất)

• MediaMTX + Dashboard backend + Dashboard frontend chạy cùng máy

B) 2 thiết bị (cùng LAN / cùng lớp mạng)

• Máy A: chạy MediaMTX + lưu recordings
• Máy B: chạy Dashboard backend + frontend
• Máy B sẽ gọi:
  • MediaMTX API của máy A (port 9997) để add/remove camera + bật/tắt recording
  • WebRTC/WHEP của máy A (port 8889 + UDP 8189) để xem live
  • Playback: máy B cần đọc được recordings của máy A (khuyến nghị mount NFS/SMB)

1) Yêu cầu

• Orange Pi chạy Debian/Ubuntu
• MediaMTX đã cài và chạy được
• Python 3.9+ (khuyến nghị 3.10+)
• Node.js 20+ (để build frontend)

2) MediaMTX cấu hình tối thiểu

Trong file mediamtx.yml:

api: yes
apiAddress: :9997

webrtc: yes
webrtcAddress: :8889
webrtcAllowOrigin: '*'

record: yes
recordFormat: fmp4
recordPath: /recordings/%path/%Y-%m-%d_%H-%M-%S-%f
recordPartDuration: 5m

Nếu chạy mô hình 2 thiết bị, đảm bảo MediaMTX trả về đúng IP LAN để client kết nối ICE:

webrtcAdditionalHosts:
  - 192.168.88.10

Trong paths, bạn có thể để dashboard tự thêm path bằng API (Settings → Add Camera).

Tạo thư mục recordings:

sudo mkdir -p /recordings
sudo chown -R $USER:$USER /recordings

Mở firewall/cổng (tuỳ hệ thống):

• 8554/tcp RTSP
• 8889/tcp WebRTC HTTP
• 9997/tcp MediaMTX Control API
• 8189/udp ICE

2.1) Playback khi tách 2 thiết bị (mount recordings)

Vì MediaMTX ghi file recordings trên máy A, nên Dashboard (máy B) cần truy cập được folder này để:

• list file /api/recordings
• serve file /videos/...

Khuyến nghị dùng NFS (Linux-Linux):

Máy A:

sudo apt-get update
sudo apt-get install -y nfs-kernel-server
echo "/recordings 192.168.88.0/24(rw,sync,no_subtree_check)" | sudo tee -a /etc/exports
sudo exportfs -ra

Máy B:

sudo apt-get update
sudo apt-get install -y nfs-common
sudo mkdir -p /recordings
sudo mount -t nfs 192.168.88.10:/recordings /recordings

3) Backend FastAPI

3.1 Cài dependencies

cd IPCam_OrangePi_Dashboard
python3 -m venv api/.venv
source api/.venv/bin/activate
pip install -r api/requirements.txt

3.2 Cấu hình

Chạy backend lần đầu sẽ tự tạo api/data/config.json.

Bạn có thể chỉnh:

• mediamtx_api_url (mặc định http://127.0.0.1:9997)
• mediamtx_webrtc_url (mặc định http://127.0.0.1:8889)
• recordings_dir (mặc định /recordings)

Nếu chạy mô hình 2 thiết bị, set theo IP máy A (MediaMTX), ví dụ:

{
  "mediamtx_api_url": "http://192.168.88.10:9997",
  "mediamtx_webrtc_url": "http://192.168.88.10:8889",
  "recordings_dir": "/recordings",
  "cameras": [],
  "schedule": { "enabled": true, "weekdays_from": "18:00", "weekdays_to": "08:00", "weekend_all_day": true }
}

Hoặc set ENV trước lần chạy đầu tiên để tạo config mặc định:

export MEDIAMTX_API_URL="http://192.168.88.10:9997"
export MEDIAMTX_WEBRTC_URL="http://192.168.88.10:8889"
export RECORDINGS_DIR="/recordings"

Nếu MediaMTX API có auth, export biến môi trường:

export MEDIAMTX_API_USER="..."
export MEDIAMTX_API_PASS="..."

3.3 Chạy backend

source api/.venv/bin/activate
uvicorn api.app.main:app --host 0.0.0.0 --port 8000

4) Frontend (build static)

4.1 Build

cd IPCam_OrangePi_Dashboard
npm install
npm run build

Output nằm ở dist/.

4.2 Serve frontend

Có 2 cách phổ biến:

1. Nginx serve dist/ và reverse proxy /api + /videos về backend :8000
2. Dùng Caddy tương tự

Ví dụ Nginx server block tối thiểu:

server {
  listen 80;
  server_name _;

  root /opt/ipcam-dashboard/dist;
  index index.html;

  location / {
    try_files $uri $uri/ /index.html;
  }

  location /api/ {
    proxy_pass http://127.0.0.1:8000;
  }

  location /videos/ {
    proxy_pass http://127.0.0.1:8000;
  }
}

Nếu chạy mô hình 2 thiết bị, phần Nginx ở máy B không cần proxy tới MediaMTX. Frontend sẽ gọi trực tiếp mediamtx_webrtc_url (máy A).

5) Systemd service (khuyến nghị)

5.1 Backend service

Tạo file /etc/systemd/system/ipcam-dashboard.service:

[Unit]
Description=IPCam Dashboard Backend
After=network.target

[Service]
WorkingDirectory=/opt/ipcam-dashboard
Environment=MEDIAMTX_API_USER=
Environment=MEDIAMTX_API_PASS=
ExecStart=/opt/ipcam-dashboard/api/.venv/bin/uvicorn api.app.main:app --host 0.0.0.0 --port 8000
Restart=always
RestartSec=2

[Install]
WantedBy=multi-user.target

Enable:

sudo systemctl daemon-reload
sudo systemctl enable --now ipcam-dashboard
sudo systemctl status ipcam-dashboard

6) Kiểm tra nhanh

• Backend: curl http://localhost:8000/api/health
• MediaMTX API: curl http://localhost:9997/v3/paths/list
• Frontend: mở http://<orange-pi-ip>/