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

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 방화벽 규칙 추가

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 상태 체크