From 96d17f6e6cbe10e2159aadd8e68c8c2246969336 Mon Sep 17 00:00:00 2001 From: seo Date: Sun, 7 Jun 2026 06:59:16 +0900 Subject: [PATCH] Document control push health timer --- README.md | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 60 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 21a3834..fcd3b3e 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 - System Notice와 process CPU/MEM 후보 표시 - dmesg 로그 열람 - Web Push 구독 등록, 자동 복구, 구독 기기 목록 표시 +- Push 기기 건강 상태 추적과 헬스체크 수동/자동 실행 - WakeLock 버튼으로 대시보드 화면 꺼짐 방지 ## 주요 API @@ -28,6 +29,7 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 - `public/api.php?action=wifi`: 허용된 WiFi/DHCP service 제어 - `public/api.php?action=push_devices`: Push 구독 기기 목록 조회 - `public/api.php?action=push_status`: 브라우저 구독 endpoint의 서버 등록 상태 조회 +- `public/api.php?action=send_push_healthcheck`: 등록된 Push 기기 전체에 상태 확인 알림 발송 - `public/api.php?action=delete_push_endpoint`: 현재 endpoint 구독 삭제 - `public/api.php?action=dmesg`: dmesg 로그 조회 @@ -43,6 +45,7 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 - `config/vapid.php`: 외부 secret 기반 VAPID 설정 bridge - `apply_policy.php`: CLI/cron 팬 정책 적용 - `bin/control_ws.php`: WebSocket 서버 +- `bin/push_healthcheck.php`: 작업스케줄러용 Push 헬스체크 CLI ## 데이터/저장소 @@ -51,9 +54,60 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 - `system_notice_state`: notice 활성 상태와 기준값 - `system_notice_logs`: notice 발생 이력 - `push_subscriptions`: Web Push 구독 정보 -- `push_event_logs`: Push 수신/클릭/닫힘 이벤트 +- `push_event_logs`: Push 발송, 수신, 표시, 클릭, 실패 이벤트 - `/home/seo/secret/control.php`: 앱 비밀번호, DB 설정, VAPID key +## Push 누락 방지 구조 + +Control은 숨은 알림을 반복 발송하는 방식 대신 구독 자동 복구, 실제 수신 이벤트 기록, 발송 실패 추적, 저빈도 헬스체크를 조합합니다. + +### 클라이언트 자동 복구 + +- 대시보드 로드 직후 Push 구독 상태를 확인합니다. +- 화면이 다시 보일 때 구독 상태를 재확인합니다. +- 5분마다 브라우저 구독과 서버 등록 상태를 비교합니다. +- 브라우저 구독이 없으면 VAPID 공개키로 재구독합니다. +- 브라우저 구독은 있으나 서버에 누락되어 있으면 다시 저장합니다. + +### 서버 상태 추적 + +`push_subscriptions`에는 구독 정보와 함께 다음 상태가 저장됩니다. + +- `last_send_success_at`: 서버가 endpoint로 Push 발송에 성공한 시간 +- `last_send_failed_at`: 서버 발송 실패 시간 +- `last_received_at`: Service Worker가 `push` 이벤트를 실제 수신한 시간 +- `last_notification_at`: 알림 표시 성공 시간 +- `last_click_at`: 사용자 알림 클릭 시간 +- `failure_count`: 연속 발송 실패 횟수 +- `last_failure_reason`: 마지막 실패 사유 + +### 상태 판정 + +- `healthy`: 최근 24시간 안에 실제 Push 수신 기록이 있음 +- `watch`: 최근 7일 안에 수신 기록은 있지만 24시간을 초과함 +- `stale`: 서버 발송 성공 기록은 있으나 장기간 실제 수신 기록이 없음 +- `failed`: 연속 발송 실패가 3회 이상 누적됨 +- `pending`: 등록은 되어 있으나 판단할 수 있는 수신/발송 기록이 부족함 + +### 자동 헬스체크 + +이 장치에는 systemd timer가 등록되어 있습니다. + +```bash +control-push-healthcheck.timer +control-push-healthcheck.service +``` + +실행 명령은 다음과 같습니다. + +```bash +/usr/bin/php /var/www/control/bin/push_healthcheck.php --min-hours=24 +``` + +타이머는 활성화 후 10분 뒤 첫 실행하고, 이후 service 실행 기준 24시간마다 실행합니다. 스크립트 내부에서도 `--min-hours=24` 쿨다운을 확인하므로 중복 실행되더라도 24시간 안이면 발송을 건너뜁니다. + +`silent: true`는 소리와 진동을 줄이는 옵션이며 완전히 보이지 않는 알림이 아닙니다. Web Push는 사용자에게 보이는 알림을 전제로 운영합니다. + ## 처리 흐름 1. 화면 진입 시 로그인 세션과 remember token을 확인합니다. @@ -62,6 +116,7 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 4. 팬 조작은 상태 저장, 정책 적용, 로그 저장 순서로 처리합니다. 5. Push 등록은 권한 요청과 구독 저장이 끝나면 즉시 상태를 갱신합니다. 6. WakeLock 버튼은 활성 상태를 초록색 버튼으로 표시합니다. +7. Push 발송, 수신, 표시, 클릭 이벤트를 기록하고 구독 DB의 건강 상태를 갱신합니다. ## 주요 함수/모듈 @@ -69,6 +124,8 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 - `apply_fan_policy()`: 팬 목표값 계산과 적용 - `json_out()`: API JSON 응답 표준화 - `push_subscribe.js`: Push 구독 등록과 복구 +- `push_health_summary()`: 상태별 Push 기기 수 집계 +- `send_push_healthcheck_if_due()`: 쿨다운 기반 헬스체크 알림 발송 - `assets/wakelock.js`: WakeLock 버튼 상태와 Screen Wake Lock API 제어 ## 보안 @@ -84,3 +141,5 @@ Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 - 하드웨어 또는 OS 변경 후 fan sysfs 경로를 확인합니다. - WebSocket 장기 실행 중 DB 연결이 끊길 수 있으므로 reconnect 로그를 확인합니다. - Push 구독 자동 복구가 과도한 반복 등록을 만들지 않는지 확인합니다. +- Push 헬스체크 timer 상태는 `systemctl list-timers --all control-push-healthcheck.timer`로 확인합니다. +- `failed`, `stale` 기기는 알림 권한, 브라우저 데이터 삭제, PWA 재설치 여부를 확인합니다.