From 1e74567e482827d1a55b5e0187cbf804dade261a Mon Sep 17 00:00:00 2001 From: Claude-51124 Date: Thu, 15 Jan 2026 16:53:22 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20PostgreSQL/Neo4j=20TCP=20=ED=97=AC?= =?UTF-8?q?=EC=8A=A4=EC=B2=B4=ED=81=AC=20=EA=B5=AC=ED=98=84=20=EC=99=84?= =?UTF-8?q?=EB=A3=8C=20=EB=B0=8F=20=ED=94=8C=EB=9E=9C=20=EB=AC=B8=EC=84=9C?= =?UTF-8?q?=20=EC=97=85=EB=8D=B0=EC=9D=B4=ED=8A=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - troubleshooting 문서 작성 (260115_postgresql_neo4j_tcp_healthcheck.md) - 플랜 문서에서 완료된 섹션 삭제 및 링크 추가 - 서버별 서비스 상태 구분 API: 목록 형식 표시 요구사항 추가 --- ...hboard_navigation_structure_refactoring.md | 33 ++++---------- ...228_admin_서비스_헬스체크_개선.md | 42 +---------------- ...260115_postgresql_neo4j_tcp_healthcheck.md | 45 +++++++++++++++++++ 3 files changed, 55 insertions(+), 65 deletions(-) create mode 100644 journey/troubleshooting/260115_postgresql_neo4j_tcp_healthcheck.md diff --git a/journey/plans/251225_admin_dashboard_navigation_structure_refactoring.md b/journey/plans/251225_admin_dashboard_navigation_structure_refactoring.md index 4d4d399..2a81bd3 100644 --- a/journey/plans/251225_admin_dashboard_navigation_structure_refactoring.md +++ b/journey/plans/251225_admin_dashboard_navigation_structure_refactoring.md @@ -18,40 +18,25 @@ ## 완료된 작업 -→ 상세: `troubleshooting/251225_admin_dashboard_navigation_structure_refactoring.md` +- → 상세: `troubleshooting/251225_admin_dashboard_navigation_structure_refactoring.md` +- → PostgreSQL/Neo4j TCP 헬스체크: `troubleshooting/260115_postgresql_neo4j_tcp_healthcheck.md` --- ## 남은 작업 -### 백엔드 API 서버 구분 지원 -- `get_services_status()`에 서버 필터 파라미터 추가 (`server: Optional[str] = None`) -- 51123 서버 서비스 목록과 51124 서버 서비스 목록 분리 -- 프론트엔드 `loadSystem51123()`, `loadSystem51124()`가 서버별 API 호출하도록 수정 - ---- - -## 즉시 해결 필요 (우선순위: 높음) - -### 1. 서버별 서비스 상태 구분 API 구현 -**파일**: `admin-dashboard/backend/services/system_service.py` +### 서버별 서비스 상태 구분 API 구현 +**파일**: `admin-dashboard/backend/services/system_service.py`, `admin-dashboard/frontend/modules/system.js` - `get_services_status()`에 `server: Optional[str] = None` 파라미터 추가 -- 51123 서버: nginx, gitea, backend, postgresql, neo4j, auth-server -- 51124 서버: rb8001, skill-email, robeing-monitor, ChromaDB -- 프론트엔드 `loadSystem51123()`, `loadSystem51124()`가 서버별 API 호출하도록 수정 +- 서버별 필터링: 51123 서버(nginx, gitea, backend, postgresql, neo4j, auth-server), 51124 서버(rb8001, skill-email, robeing-monitor, ChromaDB) +- 프론트엔드: `loadSystem51123()`, `loadSystem51124()`가 서버별 API 호출하도록 수정 +- 서비스 상태 표시 형식: 카드 형식(`service-grid`) → 목록 형식(테이블/리스트)으로 변경, `response_time_ms`, `check_method`, `host`, `timestamp` 정보 포함 -### 2. PostgreSQL/Neo4j 헬스체크 방식 변경 -**파일**: `admin-dashboard/backend/services/system_service.py:28-29` -- HTTP 체크 → TCP 소켓 체크로 변경 -- PostgreSQL: `socket.connect_ex(('172.17.0.1', 5432))` 사용 -- Neo4j: `socket.connect_ex(('172.17.0.1', 7474))` 사용 -- 참고: `troubleshooting/251228_admin_서비스_헬스체크_개선.md` - -### 3. Nginx 상태 API 개선 +### Nginx 상태 API 개선 **파일**: `admin-dashboard/backend/routers/system.py:97-133` - `get_nginx_status()` 응답에 `config_valid` 필드 추가 -- 프론트엔드에서 `nginxStatusResponse.config_valid` 참조 중 (`app.js:1104`) - `sudo nginx -t` 결과를 `config_valid`에 반영 +- 프론트엔드: `app.js:1104`에서 `nginxStatusResponse.config_valid` 참조 중 --- diff --git a/journey/troubleshooting/251228_admin_서비스_헬스체크_개선.md b/journey/troubleshooting/251228_admin_서비스_헬스체크_개선.md index 65d6594..f035df3 100644 --- a/journey/troubleshooting/251228_admin_서비스_헬스체크_개선.md +++ b/journey/troubleshooting/251228_admin_서비스_헬스체크_개선.md @@ -16,45 +16,6 @@ --- -## 해결 방안 - -### 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 컨테이너에서 호스트 서비스 접근 시 방화벽 확인 필수 @@ -92,6 +53,5 @@ sudo ufw allow 7474/tcp ## 참고 -- `admin-dashboard/backend/services/system_service.py:367-392` - TCP 소켓 체크 로직 -- `admin-dashboard/backend/routers/system.py:97-133` - nginx 상태 체크 +- `troubleshooting/260115_postgresql_neo4j_tcp_healthcheck.md` - 구현 완료 diff --git a/journey/troubleshooting/260115_postgresql_neo4j_tcp_healthcheck.md b/journey/troubleshooting/260115_postgresql_neo4j_tcp_healthcheck.md new file mode 100644 index 0000000..6101da8 --- /dev/null +++ b/journey/troubleshooting/260115_postgresql_neo4j_tcp_healthcheck.md @@ -0,0 +1,45 @@ +# 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`