DOCS/journey/troubleshooting/260115_postgresql_neo4j_tcp_healthcheck.md

PostgreSQL/Neo4j TCP 소켓 헬스체크 구현

날짜: 2026-01-15 작성자: Auto 관련 파일:

• admin-dashboard/backend/services/system_service.py:32-33, 346-384, 421-423

---

문제 상황

PostgreSQL/Neo4j가 HTTP 체크로 실패하여 Admin Dashboard에서 오류 표시 (실제로는 정상 작동 중)

---

해결 방안

• system_service.py:32-33: PostgreSQL/Neo4j HTTP URL 제거, check_method: "tcp" 추가
• system_service.py:346-384: check_tcp_service() 함수 추가, 여러 호스트 시도 (172.17.0.1 → localhost → 127.0.0.1)
• system_service.py:421-423: check_method == "tcp"인 경우 TCP 체크로 분기 처리

---

구현 완료

• Git 커밋: 4c9f227
• API 테스트: PostgreSQL/Neo4j 모두 check_method: "tcp", status: "healthy" 확인

---

교훈

데이터베이스 서비스는 TCP 소켓 체크 사용

• HTTP 프로토콜이 아닌 서비스는 TCP 소켓 체크 필수
• Docker 컨테이너에서 호스트 접근 시 여러 호스트 시도로 네트워크 격리 문제 완화

브라우저 테스트 시 docs 확인 필수

• 로그인 비밀번호, API 엔드포인트 등 접근 정보는 코드 또는 docs에서 확인 (추측 금지)

---

참고

• plans/251225_admin_dashboard_navigation_structure_refactoring.md
• troubleshooting/251228_admin_서비스_헬스체크_개선.md