From 755dee6f810f0278226cca015c2f490dbb8169b9 Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Fri, 16 Jan 2026 09:10:59 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20Admin=20Dashboard=20=EC=BA=90=EC=8B=9C?= =?UTF-8?q?=20=EB=AC=B8=EC=A0=9C=20=EB=B0=8F=20Nginx=20=EC=83=81=ED=83=9C?= =?UTF-8?q?=20=EC=B9=B4=EB=93=9C=20=EC=A0=9C=EA=B1=B0=20=ED=8A=B8=EB=9F=AC?= =?UTF-8?q?=EB=B8=94=EC=8A=88=ED=8C=85=20=EB=AC=B8=EC=84=9C=20=EC=B6=94?= =?UTF-8?q?=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...dmin_dashboard_cache_and_nginx_card_fix.md | 70 +++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 journey/troubleshooting/260116_admin_dashboard_cache_and_nginx_card_fix.md diff --git a/journey/troubleshooting/260116_admin_dashboard_cache_and_nginx_card_fix.md b/journey/troubleshooting/260116_admin_dashboard_cache_and_nginx_card_fix.md new file mode 100644 index 0000000..a95cfa9 --- /dev/null +++ b/journey/troubleshooting/260116_admin_dashboard_cache_and_nginx_card_fix.md @@ -0,0 +1,70 @@ +# Admin Dashboard 캐시 문제 및 Nginx 상태 카드 제거 + +**날짜**: 2026-01-16 +**작성자**: admin +**관련 파일**: +- `admin-dashboard/backend/routers/admin_static.py` +- `admin-dashboard/frontend/index.html` +- `admin-dashboard/frontend/modules/system.js` +- `admin-dashboard/backend/services/system_service.py` + +--- + +## 문제 상황 + +### 1. 브라우저 캐시로 인한 반영 실패 +- 15일 구축한 카드/테이블 형식이 브라우저에 반영되지 않음 +- `index.html` 자체에 캐시 방지 헤더가 없어 브라우저가 오래된 HTML을 로드 +- `styles.css`에 버전 파라미터가 없어 CSS 캐시 문제 발생 + +### 2. Nginx 상태 카드 불필요 +- 사용자 요청으로 Nginx 상태 카드 제거 필요 + +### 3. Git 충돌 마커로 인한 앱 시작 실패 +- `system_service.py:389`에 Git 충돌 마커(`>>>>>>>`) 잔존하여 SyntaxError 발생 + +--- + +## 해결 방안 + +### 1. 캐시 방지 헤더 강제 적용 +- `admin_static.py:13-19`: `/admin` 루트 경로 응답에 캐시 방지 헤더 추가 +- `admin_static.py:40-47`: 모든 정적 파일 응답에 `Cache-Control: no-cache, no-store, must-revalidate` 적용 + +### 2. 버전 파라미터 갱신 +- `index.html:10`: `styles.css?v=20260116` 버전 파라미터 추가 +- `index.html:21-25`: 모든 JS 파일 버전 파라미터 `v=20260116`으로 통일 + +### 3. Nginx 상태 카드 제거 +- `index.html:233-247`: `systemSection` 내 Nginx 상태 카드 제거 +- `index.html:303-320`: `system-servicesSection` 내 Nginx 상태 카드 제거 +- `system.js:96-120`: `loadNginxStatus()` 함수에 null 체크 추가 +- `system.js:465-470`: `loadServices()` 함수 내 nginxStatus 처리에 null 체크 추가 + +### 4. Git 충돌 마커 제거 +- `system_service.py:389`: 충돌 마커 제거 + +--- + +## 구현 완료 + +- 커밋: `6dcc781` - 캐시 방지 헤더 및 버전 파라미터 적용 +- 커밋: `b6f6718` - Git 충돌 마커 제거 +- 커밋: `7c21179`, `ca02693` - Nginx 상태 카드 제거 +- 배포: Gitea Actions 자동 배포 완료, 컨테이너 수동 재시작으로 즉시 반영 확인 + +--- + +## 교훈 + +### 캐시 문제 반복 발생 원인 +- **수동 버전 관리의 한계**: JS만 갱신하고 CSS 누락하는 습관적 작업 방식 +- **시스템적 캐시 제어 부재**: HTML 자체에 캐시 방지 헤더가 없어 브라우저가 로컬 캐시 우선 사용 + +### 재발 방지책 +- **시스템적 강제 적용**: `admin_static.py`에서 모든 정적 파일 응답에 캐시 방지 헤더를 강제로 적용 (휴먼 에러 방지) +- **원칙 문서 강화**: `AGENTS.md`에 "정적 자산 수정 시 CSS/JS 버전 파라미터 동시 갱신" 최우선 체크리스트 명시 +- **배포 후 검증**: `curl -I` 명령으로 서버 응답 헤더의 최신화 여부를 사실 기반으로 직접 검증 + +### Git 충돌 마커 관리 +- 배포 전 `grep` 명령으로 충돌 마커(`<<<<<<<`, `=======`, `>>>>>>>`) 검색 필수