diff --git a/README.md b/README.md index 56ebc91..fcfebea 100644 --- a/README.md +++ b/README.md @@ -1,73 +1,48 @@ # Seoul -nginx 설정을 기반으로 서비스 바로가기 목록을 구성하는 PHP 대시보드입니다. +nginx 설정을 읽어 웹 서비스 바로가기 목록을 만드는 PHP 대시보드입니다. -## 프로젝트 성격 +서버에 있는 여러 웹 서비스를 한 화면에서 찾기 위해 사용합니다. nginx server block에서 host와 document root를 읽고, 각 root 안의 PHP entry를 찾아 링크로 보여줍니다. -Seoul은 서버에 흩어진 웹 서비스들을 한 화면에서 찾기 위한 시작 페이지입니다. nginx 설정 파일을 읽어 HTTPS server block과 document root를 수집하고, 각 root에서 얕은 PHP entry를 찾아 링크 목록으로 렌더링합니다. +## 사용한 것 -## 주요 기능 +- PHP +- nginx 설정 파일 +- PWA manifest +- Service worker 정리 스크립트 -- nginx 설정 파일 순회 -- HTTPS server block의 host 추출 -- document root에서 `index.php`, `monitor.php` 같은 entry 탐색 -- 자기 자신, 내부 host, IP literal, 변수, 정규식 형태 host 제외 -- 서비스 이름, host, entry path 표시 -- PWA manifest 제공 +## 파일 -## 주요 진입점 +- `index.php`: nginx 설정을 읽고 바로가기 화면을 렌더링합니다. +- `api.php`: WOL 호환 요청만 Control API로 넘깁니다. +- `asset-version.php`: 정적 파일 버전을 JSON으로 내려줍니다. +- `assets/asset-reload.js`: 파일 버전이 바뀌면 캐시를 비우고 화면을 다시 엽니다. +- `manifest.webmanifest`: PWA 설치 정보입니다. +- `sw.js`: 과거 service worker 등록을 정리합니다. -- `index.php`: 바로가기 대시보드 -- `api.php`: `seo.chaegeon.com/api.php?action=wake_lan*` 호환 WOL 엔드포인트 -- `asset-version.php`: 대시보드 파일 묶음의 현재 hash를 내려주는 JSON 엔드포인트 -- `manifest.webmanifest`: PWA manifest -- `sw.js`: 과거 등록된 service worker 정리용 파일 +## 동작 -## 구성 +- `/etc/nginx/nginx.conf`, `/etc/nginx/sites-enabled`, `/etc/nginx/conf.d`를 읽습니다. +- HTTPS server block의 `server_name`과 `root`를 수집합니다. +- 각 document root에서 `index.php`, `monitor.php` 같은 얕은 entry를 찾습니다. +- 자기 자신, 내부 host, IP 주소, 변수 host, 정규식 host는 목록에서 제외합니다. +- 화면에 서비스 이름, host, entry path를 표시합니다. -- `index.php`: nginx 설정 파싱과 HTML 렌더링 -- `api.php`: `wake_lan`, `wake_lan_status` 요청만 `/var/www/control/public/api.php`로 넘기는 호환 파일 -- `manifest.webmanifest`: PWA 설치 정보 -- `sw.js`: 과거 등록된 service worker 정리용 파일 -- `assets/`: 아이콘과 정적 자산 +## 캐시 처리 -`asset-version.php`는 `car/`를 제외한 Seoul 대시보드의 PHP/JS/CSS/manifest/icon 파일을 읽어 전체 버전과 파일별 버전을 만듭니다. `index.php`는 실제 파일 수정 시각과 hash 기반 `v` 값을 정적 파일 경로에 붙입니다. `assets/asset-reload.js`는 전체 버전이나 현재 로드된 script/link의 파일별 `v` 값이 달라지면 Cache Storage를 비우고 service worker 등록을 해제한 뒤 현재 화면을 다시 엽니다. 모바일/삼성 브라우저 호환을 위해 화면 복귀, 온라인 복귀, 터치/클릭 복귀 이벤트도 확인하고, Web Storage 실패 시 쿠키 fallback으로 이전 버전을 비교합니다. `index.php`는 `no-store` 헤더를 내려 문서 자체가 오래 남지 않게 하고, service worker는 더 이상 새로 등록하지 않습니다. - -## 입력 소스 - -- `/etc/nginx/nginx.conf` -- `/etc/nginx/sites-enabled` -- `/etc/nginx/conf.d` -- 각 server block의 document root - -## 처리 흐름 - -1. nginx 설정 경로를 순회합니다. -2. `server_name`과 document root를 수집합니다. -3. document root에서 얕은 PHP entry를 찾습니다. -4. 제외 규칙을 통과한 항목만 링크 목록으로 렌더링합니다. - -## 제외/필터 기준 - -- 자기 자신 또는 중복 host -- 내부 전용 host -- IP literal -- nginx 변수나 정규식 형태 host -- 외부 노출이 부적절한 entry - -## 참고 - -`car/` 디렉터리는 별도 저장소로 관리하므로 이 저장소에서는 제외합니다. +- `asset-version.php`는 PHP, JS, CSS, manifest, icon 파일의 hash를 계산합니다. +- `index.php`는 정적 파일 경로에 버전 값을 붙입니다. +- 파일 버전이 바뀌면 브라우저 캐시와 service worker 등록을 정리한 뒤 현재 화면을 다시 엽니다. +- 문서 응답은 `no-store`로 내려 오래된 화면이 남지 않게 합니다. ## 보안 -- nginx 설정 읽기는 표시용으로만 사용합니다. -- 생성된 host와 link 값은 렌더링 전에 escape합니다. -- 내부 전용 host와 IP literal은 목록에서 제외해 외부 노출 가능성을 낮춥니다. -- `api.php`는 Control API 전체가 아니라 WOL 관련 액션만 받습니다. 인증과 WOL 전용 토큰 검증은 Control 쪽에서 처리합니다. +- nginx 설정은 목록 표시용으로만 읽습니다. +- 화면에 출력하는 host와 link 값은 escape합니다. +- 내부 전용 host와 IP 주소는 목록에서 제외합니다. +- `api.php`는 WOL 관련 액션만 받습니다. 인증과 토큰 검증은 Control 쪽에서 처리합니다. -## 운영 체크포인트 +## 메모 -- nginx 설정 변경 후 목록에 의도한 서비스만 노출되는지 확인합니다. -- 민감하거나 내부 전용 host가 목록에 나오지 않도록 제외 규칙을 유지합니다. -- Car 서비스 명세는 별도 문서와 저장소에서 관리합니다. +- `car/` 디렉터리는 별도 저장소로 관리하므로 이 저장소의 서비스 목록에서는 제외합니다. +- nginx 설정을 바꾼 뒤에는 의도하지 않은 host가 목록에 나오지 않는지 확인합니다.