From ff6002433ec18e5c149a552f79b91ae2feaccf9d Mon Sep 17 00:00:00 2001 From: seo Date: Sun, 7 Jun 2026 01:19:16 +0900 Subject: [PATCH] Expand README from project report --- README.md | 74 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 55 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index c9fca67..5bdf5e1 100644 --- a/README.md +++ b/README.md @@ -2,29 +2,43 @@ 팬 제어, 시스템 모니터링, WiFi 제어, WakeLock, Web Push 알림을 제공하는 PHP 기반 단일 관리 패널입니다. +## 프로젝트 성격 + +Control은 라즈베리파이/리눅스 호스트의 팬과 시스템 상태를 웹에서 관리하기 위한 내부 운영 도구입니다. 로그인 후 대시보드에서 온도, 팬 RPM, PWM, WiFi client, 배터리, notice, dmesg, process 후보, Push 구독 상태를 확인하고 필요한 제어 명령을 실행합니다. + +상태 갱신은 WebSocket을 우선 사용하고, 연결 실패 시 HTTP fallback으로 전환합니다. 팬 정책 적용과 센서 수집은 백그라운드 작업과 API 호출을 통해 DB에 기록됩니다. + ## 주요 기능 -- 로그인 후 팬, 센서, notice, WiFi, WakeLock, Push 구독 상태를 관리합니다. -- 백그라운드 수집과 팬 정책 적용으로 현재 상태를 유지합니다. -- WebSocket으로 상태를 갱신하고, 연결 실패 시 HTTP fallback을 사용합니다. -- Push 구독 등록, 자동 복구, notice 기반 알림 발송을 처리합니다. -- CPU 온도, RP1 온도, 팬 RPM, 팬 효율, CPU 전력, 배터리 상태를 차트로 표시합니다. -- dmesg, 프로세스 CPU/메모리 후보, notice history를 한 화면에서 확인합니다. +- 팬 모드 `auto`, `manual`, `off` 제어 +- PWM slider 기반 수동 팬 제어 +- CPU/RP1 온도, 팬 RPM, 팬 효율, CPU 전력, 배터리 상태 차트 +- WiFi client 목록과 2.4G/5G client 수 표시 +- WiFi/DHCP service restart 버튼 +- System Notice와 process CPU/MEM 후보 표시 +- dmesg 로그 열람 +- Web Push 구독 등록, 자동 복구, 구독 기기 목록 표시 +- WakeLock 버튼으로 대시보드 화면 꺼짐 방지 ## 주요 API -- `public/api.php?action=status` -- `public/api.php?action=collect` -- `public/api.php?action=fan` -- `public/api.php?action=wifi` -- `public/api.php?action=push_devices` -- `public/api.php?action=dmesg` -- `public/api.php?action=delete_push_endpoint` +- `public/api.php?action=status`: 팬, 센서, 시스템, WiFi, history, notice 상태 조회 +- `public/api.php?action=collect`: 센서 snapshot 수집 후 팬 정책 적용 +- `public/api.php?action=fan`: 팬 모드와 PWM 저장/적용 +- `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=delete_push_endpoint`: 현재 endpoint 구독 삭제 +- `public/api.php?action=dmesg`: dmesg 로그 조회 ## 구성 -- `public/index.php`: 관리 화면 +- `public/index.php`: 로그인과 관리 화면 - `public/api.php`: 상태 조회와 조작 API +- `public/assets/app.js`: 대시보드 렌더링, WebSocket, 차트, 조작 이벤트 +- `public/assets/wakelock.js`: Screen Wake Lock API 제어 +- `public/push_subscribe.js`: Push 구독 등록, 삭제, 자동 복구 +- `public/sw.js`: Push service worker - `config/config.php`: DB, 인증, CSRF, Push, shell 실행 공통 함수 - `config/vapid.php`: 외부 secret 기반 VAPID 설정 bridge - `apply_policy.php`: CLI/cron 팬 정책 적용 @@ -35,17 +49,39 @@ - `control_state`: 팬 모드와 PWM 상태 - `sensor_logs`: 온도, RPM, PWM, 배터리, load, memory, disk, uptime - `system_notice_state`: notice 활성 상태와 기준값 +- `system_notice_logs`: notice 발생 이력 - `push_subscriptions`: Web Push 구독 정보 +- `push_event_logs`: Push 수신/클릭/닫힘 이벤트 +- `/home/seo/secret/control.php`: 앱 비밀번호, DB 설정, VAPID key -## Secret +## 처리 흐름 -실행 secret은 `/home/seo/secret/control.php`에서 로드합니다. 이 파일은 저장소에 포함하지 않습니다. +1. 화면 진입 시 로그인 세션과 remember token을 확인합니다. +2. 대시보드는 `status` snapshot을 렌더링합니다. +3. WebSocket 연결이 성공하면 `status` 메시지로 갱신하고, 실패하면 HTTP fallback을 사용합니다. +4. 팬 조작은 상태 저장, 정책 적용, 로그 저장 순서로 처리합니다. +5. Push 등록은 권한 요청과 구독 저장이 끝나면 즉시 상태를 갱신합니다. +6. WakeLock 버튼은 활성 상태를 초록색 버튼으로 표시합니다. -앱 비밀번호, DB 설정, VAPID key는 외부 secret으로 유지합니다. +## 주요 함수/모듈 + +- `collect_snapshot()`: 센서와 fan 상태 snapshot 생성 +- `apply_fan_policy()`: 팬 목표값 계산과 적용 +- `json_out()`: API JSON 응답 표준화 +- `push_subscribe.js`: Push 구독 등록과 복구 +- `assets/wakelock.js`: WakeLock 버튼 상태와 Screen Wake Lock API 제어 + +## 보안 + +- 로그인 세션과 CSRF token을 사용합니다. +- POST 조작 API는 CSRF 검증을 통과해야 합니다. +- sysfs 쓰기와 systemctl 실행 권한은 sudoers 범위로 제한해야 합니다. +- VAPID key와 앱 비밀번호는 저장소 밖 secret 파일로 관리합니다. ## 운영 체크포인트 - 센서 수집 주기와 DB 증가량을 확인합니다. - 하드웨어 또는 OS 변경 후 fan sysfs 경로를 확인합니다. -- VAPID key와 앱 비밀번호는 저장소 밖에서 관리합니다. -- WebSocket 장기 실행 중 DB 연결이 끊길 수 있으므로 reconnect 동작과 로그를 확인합니다. +- WebSocket 장기 실행 중 DB 연결이 끊길 수 있으므로 reconnect 로그를 확인합니다. +- Push 구독 자동 복구가 과도한 반복 등록을 만들지 않는지 확인합니다. +