happybell80
0252dd1a7f
192.168.219.45 → 192.168.0.100 일괄 변경 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
# 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 접근 불가
|
|
|
|
---
|
|
|
|
## 교훈
|
|
|
|
### 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 매핑은 실제 컨테이너 이름 사용
|
|
|
|
### Docker API 제한 및 폴백 원칙
|
|
|
|
**원칙**:
|
|
- Docker API는 같은 서버의 컨테이너만 조회 가능 (다른 서버의 컨테이너는 조회 불가)
|
|
- Docker API 체크 실패 시(`not_found`, `error`) HTTP 헬스체크로 자동 폴백
|
|
- 서버 간 접근 시 URL 폴백: `172.17.0.1` 실패 시 `192.168.0.100`로 재시도
|
|
|
|
**이유**:
|
|
- Docker API는 로컬 Docker 데몬에만 접근 가능하여 원격 서버 컨테이너 조회 불가
|
|
- 서버 간 서비스 체크는 HTTP 헬스체크로만 가능
|
|
- Docker 네트워크 IP(`172.17.0.1`)는 같은 서버 내부에서만 유효, 서버 간 접근은 실제 IP(`192.168.0.100`) 필요
|
|
|
|
---
|
|
|
|
## 참고
|
|
|
|
- `troubleshooting/260115_postgresql_neo4j_tcp_healthcheck.md` - 구현 완료
|
|
|