Claude-51124 22557e7132 docs: 오래된 트러블슈팅 아카이브 및 구조 정리

- 7-8월 초기 구축 문서 12개를 _archive/troubleshooting/2025_07-08_initial_setup/로 이동
- book/300_architecture/390_human_in_the_loop_intent_learning.md를 journey/research/intent_classification/로 이동 (개발 여정 문서)
- 빈 폴더 제거 (journey/assets/*)

2025-11-17 14:06:05 +09:00

3.9 KiB

Raw Blame History

Admin 페이지 서비스 상태 체크 개선

날짜: 2025-07-18
작업자: happybell80 & Claude
저장소: frontend-base

오후 3시 30분

Admin 페이지 서비스 상태 체크 Docker API 방식 개선

배경:

Admin 페이지(https://ro-being.com/admin)에서 서비스 상태가 모두 오류로 표시
Docker 네트워크 격리로 인해 컨테이너 간 HTTP health check 실패
CLAUDE.md에 기록된 개선 방안 구현 필요

문제 분석:

frontend-base backend가 Docker 컨테이너 내부에서 실행
다른 서비스들도 각자 Docker 네트워크에 격리되어 HTTP 접근 불가
nginx, gitea는 호스트에서 systemd로 실행 중

초기 구현 시도:

Docker API를 통한 컨테이너 상태 확인 함수 추가
systemctl을 통한 systemd 서비스 상태 확인 함수 추가
서비스별로 적절한 체크 방식 선택

문제 발생:

첫 배포 후 정상이던 서비스들도 모두 오류 표시
Docker 컨테이너 내부에서 systemctl 사용 불가 (예상된 결과)
Docker 컨테이너 이름 불일치 (frontend-base-backend → frontend-base)

서버 확인 결과:

# 실제 컨테이너 이름
frontend-base (backend가 아님)
rb10508_micro
rb8001
auth-server

# systemd 서비스
nginx
gitea

최종 해결:

systemd 체크 코드 완전 제거
Docker 컨테이너 이름을 실제 이름으로 수정
Docker API로 체크할 서비스 목록 하드코딩:
- rb10508_micro, backend(frontend-base), rb8001, auth-server
nginx, gitea는 HTTP 체크 유지 (172.17.0.1 통해 호스트 접근)

코드 변경 내용:

# admin_routes.py

# systemd 체크 함수 제거
# def check_systemd_service(...) 삭제

# Docker 서비스 목록 수정
docker_services = {
    "rb10508_micro": "rb10508_micro",
    "backend": "frontend-base",  # 실제 컨테이너 이름으로 수정
    "rb8001_8001": "rb8001",
    "auth-server_9000": "auth-server",
}

# systemd 체크 로직 제거
# nginx, gitea는 HTTP로 체크 (기본값)

결과:

모든 서비스 상태 정상 표시
Docker API를 통한 빠른 응답 (1ms)
네트워크 격리 문제 해결

향후 개선 사항:

하드코딩 대신 동적 서비스 감지 필요
- Docker 레이블 기반 자동 감지
- 컨테이너 이름/포트 패턴 매칭
- 성공한 체크 방식 캐싱
확장성 문제 해결 필요
- 새 서비스 추가 시 자동 감지
- 스마트 헬스체크 (Docker → HTTP 폴백)

기술적 성과:

Docker API 활용으로 네트워크 문제 우회
컨테이너 환경의 제약사항 이해 및 해결
서비스별 최적 체크 방식 적용

오후 4시 00분

PostgreSQL과 Neo4j 서비스 추가

문제 발견:

Admin 페이지에서 PostgreSQL과 Neo4j가 표시되지 않음
자동 발견은 되지만 BASE_SERVICES에 정의되지 않아 임시 서비스로 분류

원인 분석:

BASE_SERVICES에 PostgreSQL, Neo4j 없음
서비스 감지 방식의 한계:
- discover_docker_services(): Docker 컨테이너만 감지
- scan_network_ports(): 포트만 발견, 서비스 종류는 모름
- systemd 서비스 감지 기능 없음
실제 상태:
- PostgreSQL: systemd 서비스로 실행 중 (포트 5432)
- Neo4j: systemd 서비스로 실행 중 (포트 7474, 7687)
- Docker 컨테이너가 아니므로 자동 감지 안됨

해결: BASE_SERVICES에 PostgreSQL과 Neo4j 추가:

BASE_SERVICES = {
    # 기존 서비스들...
    "postgresql": {"port": 5432, "url": "http://172.17.0.1:5432", "health_path": "/", "timeout": 5},
    "neo4j": {"port": 7474, "url": "http://172.17.0.1:7474", "health_path": "/db/data/", "timeout": 5}
}

결과:

PostgreSQL과 Neo4j가 기본 서비스로 표시
삭제 불가능한 핵심 서비스로 보호
HTTP health check로 상태 확인 (PostgreSQL은 TCP 연결만 체크)

3.9 KiB Raw Blame History