docs: Admin Dashboard 서비스 헬스체크 시스템 개선 트러블슈팅

journey/troubleshooting/251228_admin_서비스_헬스체크_개선.md

@@ -0,0 +1,97 @@
+# Admin Dashboard 서비스 헬스체크 시스템 개선
+
+**날짜**: 2025-12-28
+**작성자**: Auto
+**관련 파일**: 
+- `admin-dashboard/backend/services/system_service.py`
+- `admin-dashboard/backend/routers/system.py`
+
+---
+
+## 문제 상황
+
+1. **PostgreSQL/Neo4j 오류 표시**: 실제로는 정상 작동 중이지만 헬스체크 실패로 오류 표시
+2. **서비스 목록 불일치**: 존재하지 않는 서비스(rb10508_test) 표시, 실제 실행 중인 서비스 누락
+3. **Neo4j 접근 실패**: Docker 컨테이너에서 호스트 Neo4j 접근 불가
+
+---
+
+## 해결 방안
+
+### 1. PostgreSQL/Neo4j 헬스체크 방식 변경
+
+**파일**: `system_service.py:367-392`
+
+- HTTP 체크 → TCP 소켓 체크로 변경
+- Docker 컨테이너 내부에서 호스트 접근 시 여러 호스트 시도:
+  - `172.17.0.1` → `localhost` → `127.0.0.1` 순서
+
+### 2. Neo4j 방화벽 규칙 추가
+
+```bash
+sudo ufw allow 7474/tcp
+```
+
+- Docker 컨테이너에서 호스트 서비스 접근 시 방화벽 확인 필수
+
+### 3. 서비스 목록 정리
+
+**파일**: `system_service.py:24-31, 340-344`
+
+- 제거: `rb10508_test` (51124 서버에 있음)
+- 추가: `robeing-gateway_8100`, `goosefarm-app_8200`, `auth-server_9000`, `opensearch_9200`, `opensearch_9600`
+- docker_services 매핑: 실제 컨테이너 이름으로 수정
+
+### 4. nginx 설정 유효성 체크 추가
+
+**파일**: `routers/system.py:97-133`
+
+- `config_valid` 필드 추가
+- `nginx -t` 명령 실행하여 설정 검증
+
+### 5. 데이터 정리
+
+- `robeing` 테이블: rb8001 중복 레코드 1개 삭제
+
+---
+
+## 교훈
+
+### Docker 컨테이너에서 호스트 서비스 접근 시 방화벽 확인 필수
+
+**원인**:
+- Docker 컨테이너는 `172.17.0.1`을 통해 호스트에 접근
+- UFW 방화벽이 기본적으로 Docker 네트워크를 차단할 수 있음
+- Neo4j(7474) 포트가 방화벽 규칙에 없어 연결 실패
+
+**방지 방법**:
+1. Docker 컨테이너에서 호스트 서비스 접근 시 방화벽 규칙 확인
+2. 헬스체크 실패 시 방화벽 상태 확인 (`sudo ufw status`)
+3. 필요한 포트는 명시적으로 허용: `sudo ufw allow <포트>/tcp`
+
+### TCP vs HTTP 헬스체크 선택 기준
+
+**원칙**:
+- 데이터베이스 서비스(PostgreSQL, Neo4j): TCP 소켓 체크 사용
+- HTTP 서비스: HTTP 헬스체크 사용
+- Docker 컨테이너 내부에서 호스트 접근 시 여러 호스트 시도
+
+**이유**:
+- 데이터베이스는 HTTP 프로토콜이 아닌 경우가 많음
+- 인증이 필요한 경우 401 응답도 정상으로 간주해야 함
+- Docker 네트워크 격리로 인해 호스트 접근 방식이 다를 수 있음
+
+### 서비스 목록 관리 원칙
+
+**원칙**:
+- 실제 실행 중인 서비스만 모니터링
+- 다른 서버에 있는 서비스는 제거
+- docker_services 매핑은 실제 컨테이너 이름 사용
+
+---
+
+## 참고
+
+- `admin-dashboard/backend/services/system_service.py:367-392` - TCP 소켓 체크 로직
+- `admin-dashboard/backend/routers/system.py:97-133` - nginx 상태 체크
+