c3227c179c
감사에서 확정된 잔여 항목을 일괄 처리. 이전 커밋이 증상(스테일 번들)을 고쳤다면 이번에는 그것이 조용히 지나가게 만든 구조를 고친다. 보안 - CSP 도입. 인라인 2블록에 per-request nonce, unsafe-inline 없음. 빌드가 없다는 제약이 nonce를 막지는 않는다. 보안 헤더를 .htaccess 단독에서 PHP로 옮겨 개발/납품이 같아진다. - /logout에 CSRF. SameSite=Lax가 막아주지만, 사고 대응 중 운영자를 콘솔에서 튕겨내는 건 이 제품에선 실제 가용성 공격이라 예외로 둘 이유가 없다. - 잠긴 계정 423 → 401. 아무나 이름을 추측해 5회 실패로 잠근 뒤 423을 계정 실재 확인으로 쓸 수 있었다. 잠금 사실은 감사 로그에 남고, 익명 호출자는 못 읽는다. 엣지 - 큐 flush에 회당 상한. 정전 복구 직후 2000건을 비우는 동안 감지가 멈추던 구간을 없앤다. - 타이머 env 전수 검증. COOLDOWN_S=nan은 dedup을 무력화해 매 틱 발보시켰다. - T2 프레임 스킵(INFER_EVERY). 스킵 틱은 프레임을 읽어 버퍼만 비우고 링버퍼에 넣지 않는다 — 추론이 없으면 얼굴 박스도 없어 그대로 넣으면 증거 스냅샷에 미블러 얼굴이 실린다. T3(모션 게이트)는 의도적으로 미구현: 게이트가 틀리면 '움직이지 않는 쓰러진 작업자'에게 추론이 안 돈다. 실영상 없이 임계값을 정할 수 없다. - systemd 워치독(sd_notify) + 메모리 상한. Restart=always는 죽은 프로세스만 잡고 '살아 있는데 멈춘' 상태는 못 잡는다. UVC 해상도·버퍼 고정(링버퍼 RSS가 웹캠 기본값에 좌우). 테스트 — 감사의 최대 갭 - PDO 통합 테스트가 pdo_sqlite 부재로 통째로 스킵되고 CI도 없어 사실상 한 번도 안 돌았다. `-d extension=pdo_sqlite`로 되살리고 리포트·히트맵·익스포트 집계 SQL을 최초로 실행한다. - 얼굴 블러 테스트가 out is not None만 봤다 — blur()가 무동작이어도 통과. PIPA 대응의 유일한 실행 가능한 증거였는데 아무것도 증명하지 못했다. 디테일 파괴를 단언하도록 교체. - index.php 라우트 테이블 대조(프런트 호출 15개 교차검증), dist↔소스 패리티 테스트, CI 신설(스킵이 하나라도 있으면 실패). - ArraySessionStore.regenerate()가 데이터를 지워 실제 session_regenerate_id(true)와 달랐다. 더블이 실구현과 어긋난 자리 하나를 실제로 잡았다. 프런트 - 이벤트 목록 시그니처 재렌더 스킵 + 포커스 복원. aria-live 영역을 5초마다 통째로 다시 만들어 스크린리더가 200행을 재낭독하고 키보드 포커스가 body로 날아갔다. 같은 패턴이 device-tree.js에는 이미 있었다. - 폴링 중첩 가드(느린 공유호스팅에서 응답 역전), 콜드스타트 실패 표시. 납품 - VERSION 신설, 두 산출물에 version/git_commit/built_at 스탬프. 스테일 번들의 SHA256SUMS는 자기정합적이라 통과한다 — provenance 없이는 하류에서 탐지할 방법이 없다. - deploy/README·env.example을 Hailo 단독 번들 실제와 일치(템플릿이 없는 ONNX를 가리켰다). - 이벤트 보존 정책은 기본 0(영구). 산업안전 기록을 시스템이 임의로 지우지 않는다. 검증: pytest 251 / PHPUnit 162, 스킵 0. CSP nonce 결합은 실제 렌더 경로로 확인. 브라우저 실렌더는 MySQL이 필요해 이 환경에서 미수행.
178 lines
8.6 KiB
Markdown
178 lines
8.6 KiB
Markdown
# Edge deployment (Raspberry Pi 5, air-gapped / 폐쇄망)
|
|
|
|
Offline-installable bundle + systemd unit for the `move-detect` edge daemon.
|
|
The bundle is fully self-contained (all wheels + pose model + source): the Pi
|
|
performs **zero network fetches** at install or run time. The only runtime
|
|
network use is the server POST / config-poll / heartbeat, and even that tolerates
|
|
being offline (events buffer in the local sqlite queue and flush on reconnect).
|
|
|
|
> Scope: the delivered bundle is **Hailo-8 + `yolov8s_pose.hef`**, which
|
|
> `build_offline_bundle.sh` fetches (sha256-pinned) and stages into `models/`.
|
|
> The CPU MoveNet fallback is **not** bundled: its upstream ONNX URL 404s, so
|
|
> `install_offline.sh` configures the unit for whatever backend is actually
|
|
> present and refuses to install if none is. Camera side: USB (UVC) and CSI are
|
|
> both wired; CSI needs `hailo-all`/`picamera2` from the Pi OS image.
|
|
> Device validation for both is `docs/hardware-bringup.md` (still OFF-HW).
|
|
|
|
## Files
|
|
|
|
| File | Runs on | Purpose |
|
|
|------|---------|---------|
|
|
| `bundle/build_offline_bundle.sh` | build machine (has internet) | downloads wheels + model, stages source, emits one tarball |
|
|
| `bundle/install_offline.sh` | the Pi (no internet) | venv + `--no-index` install, systemd unit, service account |
|
|
| `systemd/move-detect-edge.service` | the Pi | the daemon unit (auto-restart, device access, hardening) |
|
|
| `systemd/move-detect-edge.env.example` | the Pi | env template → `/etc/move-detect/edge.env` |
|
|
|
|
## Quick start — Pi with internet (one command)
|
|
|
|
If the Pi itself has internet, skip the offline bundle entirely. Copy the built delivery
|
|
folder onto the Pi — **copy the working tree, not a fresh `git clone`**: the pose model
|
|
`models/yolov8s_pose.hef` is git-ignored (a build artifact), so a clone arrives without it.
|
|
Use `scp -r`/USB from a build machine that has already staged `models/` (see step 1). Then:
|
|
|
|
```bash
|
|
sudo deploy/setup_online.sh
|
|
```
|
|
|
|
It installs the system packages (`python3-picamera2`, and `hailo-all` if present), builds
|
|
the venv, pip-installs the runtime deps, **places the pose model from the delivery's
|
|
`models/`** (it does NOT download models on the Pi — the HEF/ONNX are fetched on the build
|
|
machine per the air-gap rule, `build pulls, target doesn't`), writes `/etc/move-detect/edge.env`
|
|
(prompting for `DEVICE_ID` / `DEVICE_SECRET` / `CAFE24_URL` / `CAMERAS`, or take them from env
|
|
vars), probes every camera, installs the systemd unit, and starts the service. It uses Hailo
|
|
when `models/yolov8s_pose.hef` is present (or pass `HAILO_HEF=/path/to.hef`), else CPU MoveNet
|
|
when `models/movenet_lightning.onnx` + onnxruntime are present. The rest of this doc is the
|
|
**air-gapped** path.
|
|
|
|
### Secret handling (`deploy/device.env`)
|
|
|
|
If you pre-provision with `deploy/device.env`, that file holds this device's **HMAC secret in
|
|
plaintext**. It is gitignored (never committed), but it rides onto the Pi with the "copy the
|
|
working tree" transfer. After a successful install:
|
|
|
|
1. **Delete it:** `shred -u deploy/device.env` (the live secret now lives only in
|
|
`/etc/move-detect/edge.env`, `0640 root:movedetect`). The installer already `chmod 600`s it
|
|
while running, but that is defense-in-depth, not a substitute for removing it.
|
|
2. **Rotate if it was ever exposed** (shared over chat, a shell history, a shared drive):
|
|
update `move_devices.secret` on the server and the `DEVICE_SECRET` in the Pi's
|
|
`/etc/move-detect/edge.env`, then restart the service. A leaked secret lets anyone forge
|
|
signed events/heartbeats for this device.
|
|
|
|
Prefer `device.env` over passing `DEVICE_SECRET=...` on the `sudo` command line, which leaves the
|
|
secret in the shell history.
|
|
|
|
---
|
|
|
|
## 1. Build the bundle (on a machine WITH internet)
|
|
|
|
**Most reliable: build on an aarch64 host** (a Pi 5, or an arm64 CI runner) so the
|
|
downloaded wheels match the target exactly:
|
|
|
|
```bash
|
|
deploy/bundle/build_offline_bundle.sh # native aarch64 wheels
|
|
```
|
|
|
|
From an x86 box you can attempt a cross build (best-effort — onnxruntime/opencv
|
|
wheel tags may not resolve; if it fails, build natively):
|
|
|
|
```bash
|
|
deploy/bundle/build_offline_bundle.sh --cross # target aarch64 / cp311
|
|
```
|
|
|
|
Output: the folder `dist/2_pi_install/` (+ `MANIFEST.txt` listing the bundled
|
|
wheels). Copy the WHOLE FOLDER across the air gap as-is — no archive step.
|
|
Set `MAKE_TARBALL=1` if you would rather transfer one
|
|
`dist/2_pi_install-aarch64-cp311-hailo8.tar.gz` file.
|
|
|
|
## 2. Transfer + install (on the air-gapped Pi)
|
|
|
|
Copy `dist/2_pi_install/` across the gap (USB, one-way transfer, etc.), then:
|
|
|
|
```bash
|
|
# tarball variant only (MAKE_TARBALL=1): tar xzf 2_pi_install-aarch64-cp311-hailo8.tar.gz
|
|
cd 2_pi_install
|
|
sudo ./install_offline.sh
|
|
```
|
|
|
|
The installer: creates the `movedetect` service account (in `video`/`render`/
|
|
`plugdev`/`hailo` groups), lays down source + model under `/opt/move-detect`,
|
|
builds a venv and installs the bundled wheels with `--no-index`, verifies the
|
|
package imports, seeds `/etc/move-detect/edge.env`, and installs the systemd unit.
|
|
|
|
## 3. Configure + start
|
|
|
|
```bash
|
|
sudo nano /etc/move-detect/edge.env # DEVICE_ID, DEVICE_SECRET, CAFE24_URL, ...
|
|
sudo systemctl enable --now move-detect-edge
|
|
journalctl -u move-detect-edge -f
|
|
```
|
|
|
|
`DEVICE_ID`/`DEVICE_SECRET` must match a `move_devices` row in the server (see
|
|
`server/docs/server-deploy.md` §6). `HAILO_HEF` points at the bundled model
|
|
(`/opt/move-detect/models/yolov8s_pose.hef`); the installer sets it for you and
|
|
only falls back to `MOVENET_ONNX` if a MoveNet bundle was built.
|
|
|
|
## 4. Verify the air gap (do this before trusting a build)
|
|
|
|
- [ ] On a host with **networking disabled**, `install_offline.sh` completes —
|
|
the `--no-index` installs prove nothing is fetched. If pip tries to reach
|
|
PyPI, a wheel is missing from the bundle: rebuild (step 1) natively.
|
|
- [ ] Step [4/6] of the installer prints `edge import OK` (cv2 + numpy + requests
|
|
import from the venv; onnxruntime only if a MoveNet bundle was built).
|
|
- [ ] `systemctl status move-detect-edge` is `active (running)`; the log shows
|
|
frames processed and (if the server is reachable) heartbeats.
|
|
- [ ] Pull the network cable → events keep queueing (`QUEUE_DB` grows) → restore
|
|
→ the queue flushes. (End-to-end behavior verified in the edge e2e harness.)
|
|
|
|
## Hailo-8 HAT + CSI camera path (optional, faster)
|
|
|
|
The default bundle runs CPU MoveNet + USB webcam. To use the Hailo-8 accelerator
|
|
and/or a CSI camera, add these SYSTEM packages on the Pi (they are apt packages, not
|
|
pip wheels — the venv sees them because it is created with `--system-site-packages`):
|
|
|
|
```bash
|
|
sudo apt install -y hailo-all python3-picamera2 python3-opencv
|
|
```
|
|
|
|
- `hailo-all` — HailoRT runtime + driver + the Python `hailo_platform` bindings.
|
|
- `python3-picamera2` — CSI camera stack (libcamera).
|
|
|
|
Then place the pose model and switch backends in `/etc/move-detect/edge.env`:
|
|
|
|
```ini
|
|
POSE_BACKEND=hailo
|
|
HAILO_HEF=/opt/move-detect/models/yolov8s_pose.hef # copy the compiled HEF here
|
|
CAMERA_BACKEND=csi
|
|
CSI_DEVICE=0
|
|
```
|
|
|
|
Validate on device per `docs/hardware-bringup.md` before trusting output (the Hailo
|
|
decode is unit-locked, but the HailoRT inference + picamera2 color order are hardware-
|
|
validated). USB webcam stays available anytime via `CAMERA_BACKEND=uvc`.
|
|
|
|
**Multiple cameras at once.** Set `CAMERAS=backend:device:camera_id,...` to run several
|
|
cameras in one daemon — each gets its own detection pipeline and `camera_id`, they share
|
|
the Hailo device (round-robin) and the offline queue, and server zones are routed to the
|
|
matching camera. Example — CSI + USB together:
|
|
|
|
```ini
|
|
CAMERAS=csi:0:cam-01,uvc:0:cam-02
|
|
```
|
|
|
|
Each `camera_id` must match the `camera_id` on that camera's zones in the server.
|
|
|
|
> **Air gap:** `hailo-all` / `python3-picamera2` are the ONE piece this bundle can't
|
|
> carry (Hailo's own driver + apt tree). Pre-install them on the Pi image, or transfer
|
|
> their `.deb`s separately, before running `install_offline.sh`. The pose HEF is
|
|
> likewise supplied out-of-band (compiled from the Hailo Model Zoo).
|
|
|
|
## Not bundled (by design)
|
|
|
|
- **MySQL / the server app** — a separate host; see `server/docs/server-deploy.md`.
|
|
- **HailoRT + picamera2** — Hailo's runtime/driver and the CSI camera stack are Pi
|
|
system packages, installed out-of-band (above). Note the HEF itself **is** bundled
|
|
(`models/yolov8s_pose.hef`); only the driver is not.
|
|
- **`python3-venv`** — `install_offline.sh` runs `python3 -m venv`, which Pi OS Lite
|
|
does not always include. Install it with the Hailo packages, before going air-gapped.
|
|
- **MoveNet ONNX (CPU fallback)** — its upstream URL 404s, so the bundle is Hailo-only.
|
|
If you need the CPU path, supply the ONNX to the build machine and rebuild.
|