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

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

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

2.1) Nếu MediaMTX API bị 401 Unauthorized

401 nghĩa là request thiếu thông tin xác thực hợp lệ. Khi bật auth trong MediaMTX, bạn cần tạo user có quyền api và cấu hình backend dashboard gửi Basic Auth.

Ví dụ trong mediamtx.yml:

authMethod: internal
authInternalUsers:
  - user: dashboard
    pass: dashboard_password
    ips: ['127.0.0.1', '::1', '192.168.88.0/24']
    permissions:
      - action: api

Sau đó set trực tiếp trong api/data/config.json của dashboard backend:

"mediamtx_api_user": "dashboard",
"mediamtx_api_pass": "dashboard_password"

Trong paths, bạn có thể để dashboard tự thêm path bằng Settings (nhập RTSP URL). Backend sẽ cập nhật trực tiếp file mediamtx.yml.

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

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

Backend chỉ đọc cấu hình từ api/data/config.json (không đọc .env). Chạy lần đầu sẽ tự tạo file này (lưu camera + schedule + các tham số backend). Danh sách camera trong config.json sẽ được backend đồng bộ từ mediamtx.yml. Các thông số kết nối MediaMTX (mediamtx_api_url, mediamtx_webrtc_url, credentials, recordings_dir) do user điền trong dashboard Settings hoặc chỉnh trực tiếp 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)
• mediamtx_api_user / mediamtx_api_pass (nếu bật auth API của MediaMTX)
• recordings_dir (mặc định ./mediamtx/recordings trong project)
• api_port (mặc định 8008)

Các thao tác trong Settings:

• Add Camera: chỉ nhập RTSP URL, backend tự tạo tên camN trong mediamtx.yml
• Delete Camera: xóa path tương ứng trong mediamtx.yml
• MediaMTX record: bật/tắt pathDefaults.record trong mediamtx.yml
• Restart MediaMTX Docker: gọi docker compose -f mediamtx/docker-compose.yml restart mediamtx

3.3 Chạy backend

source api/.venv/bin/activate
python3 -m api.run

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 :8008
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:8008;
  }

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

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
ExecStart=/opt/ipcam-dashboard/api/.venv/bin/python /opt/ipcam-dashboard/api/run.py
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:8008/api/health
• MediaMTX API: curl http://localhost:9997/v3/paths/list
• Frontend: mở http://<orange-pi-ip>/