DOCS/troubleshooting/250716_frontend_admin_dashboard_improvements.md

Frontend Admin Dashboard 개선 및 문제 해결

날짜: 2025-07-16
문제: Admin 대시보드 서비스 상태 표시 오류 및 Git 활동 미표시
해결 시간: 약 3시간
담당자: happybell

문제 상황

1. 서비스 상태 표시 오류

• 증상: Admin 대시보드에서 서비스 상태가 undefined로 표시
• 원인: API 응답 구조 변경으로 인한 프론트엔드 호환성 문제
• 기존: return services_status (직접 반환)
• 변경: return { "services": services_status, ... } (객체로 감싸서 반환)

2. Git 활동 미표시

• 증상: 최근 Git 활동 섹션이 빈 상태로 표시
• 원인: /host_home/github-migration/ 경로가 존재하지 않음
• 배경: 해당 디렉토리는 SSD 용량 문제로 HDD로 이동되었음

3. UI 레이아웃 문제

• Gitea Runners 섹션이 공간을 차지하나 실제 사용되지 않음
• Git 활동 섹션이 좁아서 저장소명과 커밋 메시지가 잘림

해결 과정

1. 동적 서비스 발견 기능 추가

# 서비스 자동 발견 함수 추가
def discover_docker_services():
    """Docker 컨테이너에서 노출된 포트 발견"""
    # Docker 컨테이너 목록에서 포트 정보 추출
    # 이미 알려진 서비스 제외하고 새로운 서비스만 반환

def add_discovered_service(service_name, port, url=None, health_path="/"):
    """발견된 서비스를 SERVICES에 추가"""
    # 동적으로 서비스 목록 업데이트

새로운 API 엔드포인트:

• GET /admin/services/discover - 수동 서비스 발견
• POST /admin/services/add - 서비스 수동 추가
• DELETE /admin/services/{name} - 서비스 제거
• GET /admin/services/list - 전체 서비스 목록
• GET /admin/services/status?auto_discover=true - 자동 발견 포함 상태 체크

2. Gitea API를 통한 Git 활동 조회

기존 방식 (파일시스템 접근):

repos = [
    "/host_home/github-migration/nginx-infra",
    "/host_home/github-migration/frontend-base",
    ...
]
# subprocess로 git 명령어 실행

새로운 방식 (Gitea API):

GITEA_URL = "http://172.17.0.1:3000"
GITEA_TOKEN = "b18d3b01a802f001f3e2649cbd750008710a1d99"

# Gitea REST API 사용
- /api/v1/repos/{owner}/{repo} - 저장소 정보
- /api/v1/repos/{owner}/{repo}/commits - 최근 커밋

3. UI 레이아웃 개선

변경 전:

[Nginx 상태 (1칸)] [Gitea Runners (1칸)] [Git 활동 (1칸)]

변경 후:

[Nginx 상태 (1칸)] [Git 활동 (2칸 - 확장)]

• Gitea Runners 섹션 제거
• Git 활동을 grid-column: span 2로 확장
• 테이블 형식으로 간소화 (레포당 한 줄)

구현 결과

1. 서비스 상태 API 복구

• 원래 구조로 복구하여 프론트엔드 호환성 유지
• 자동 발견 기능은 별도 엔드포인트로 분리

2. Git 활동 정상 표시

• 5개 주요 저장소의 최근 활동 표시
• 각 저장소별 최근 커밋 메시지와 시간 표시
• API 에러 처리 추가

3. 개선된 레이아웃

• 더 많은 공간 활용으로 가독성 향상
• 긴 저장소명과 커밋 메시지 잘림 문제 해결

기술적 고려사항

1. Gitea API 권한

• 현재 토큰: write:repository 권한만 있음
• 제약사항: /api/v1/user, /api/v1/orgs 접근 불가
• 해결책: 알려진 저장소 목록 하드코딩

2. 네트워크 설정

• Backend 컨테이너 → Gitea: http://172.17.0.1:3000
• Backend 컨테이너 → 호스트 서비스: http://172.17.0.1:{port}
• Docker 네트워크: appnet (external)

3. 자동 발견 성능

• 포트 스캔 시 ThreadPoolExecutor 사용 (50 workers)
• 타임아웃 설정: 1초 (포트 스캔), 5초 (health check)

남은 이슈

rb8001_8001 서비스 timeout

• 포트 8001에서 실행 중인 서비스가 응답하지 않음
• 자동 발견으로 추가되었으나 health check 실패
• 추가 조사 필요:
  • Docker 컨테이너 상태 확인
  • 네트워크 연결 확인
  • 서비스 로그 확인

교훈

1. API 변경 시 호환성 고려

   • 프론트엔드가 기대하는 응답 구조 확인 필수
   • Breaking change는 신중하게 접근

2. 외부 의존성 관리

   • 파일시스템 경로 의존성은 취약함
   • API 기반 접근이 더 안정적

3. 권한 관리

   • API 토큰 권한은 필요한 만큼만 부여
   • 권한 부족 시 대안 방법 준비

관련 커밋

• 8ff8fe5 - 동적 서비스 감지 기능 추가
• 98b2577 - Git 활동 조회를 Gitea API로 대체
• 969cc72 - Gitea Runners 제거 및 Git 활동 확장
• ca2e566 - Git 활동 표시 간소화