온프레미스 문제 해결

온프레미스 EKB 배포 문제 해결을 위한 L1 진단 단계

이 가이드는 온프레미스 EKB 배포에서 문제를 해결하기 위한 레벨 1 (L1) 진단 단계를 제공합니다. 이 단계는 컨테이너, 데이터베이스, 서비스, 시스템 리소스와 관련된 일반적인 문제를 식별하는 데 도움이 됩니다.

전제 조건: EKB가 배포된 고객의 VM/서버에 대한 SSH 접근 권한과 Docker 명령 실행 및 컨테이너 로그 접근에 대한 적절한 권한이 필요합니다.

​

컨테이너 상태 확인

​

모든 컨테이너 상태 확인

먼저 실행 중인 컨테이너와 해당 상태를 확인합니다:

# 모든 컨테이너 상태 확인
docker ps -a

# 상태가 포함된 컨테이너 확인
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Health}}"

# 특정 컨테이너 상태 확인
docker ps -a | grep <container_name>

예상 컨테이너:

• web - 프론트엔드 애플리케이션
• api 또는 fastapi_backend - 백엔드 API 서버
• worker 또는 celery_worker - Celery 워커
• redis - Redis 캐시
• rabbitmq - RabbitMQ 메시지 큐
• supabase-studio - Supabase Studio
• supabase-kong - Kong API 게이트웨이
• supabase-auth - 인증 서비스
• supabase-db 또는 postgres - PostgreSQL 데이터베이스
• 기타 Supabase 서비스 (storage, meta 등)

확인 사항:

• 모든 컨테이너가 “Up” 상태여야 합니다
• 어떤 컨테이너도 “Restarting” 또는 “Exited” 상태여서는 안 됩니다
• 해당되는 경우 상태 검사가 “healthy”로 표시되어야 합니다

​

실패한 컨테이너 재시작

컨테이너가 중지되었거나 재시작 중인 경우:

# 특정 컨테이너 재시작
docker restart <container_name>

# 모든 컨테이너 재시작
docker compose restart

# 특정 서비스 재시작
docker compose restart <service_name>

​

백엔드 컨테이너 로그

​

API 컨테이너 로그 확인

백엔드 API 컨테이너 로그에는 오류, 데이터베이스 연결, 서비스 문제에 대한 중요한 정보가 포함되어 있습니다:

# 최근 로그 보기 (최근 100줄)
docker logs --tail 100 api

# 또는 fastapi_backend의 경우
docker logs --tail 100 fastapi_backend

# 실시간으로 로그 따라가기
docker logs -f api

# 타임스탬프와 함께 로그 보기
docker logs -t api

# 특정 시간 이후 로그 보기
docker logs --since 30m api

# 타임스탬프 사이의 로그 보기
docker logs --since "2024-01-01T00:00:00" --until "2024-01-01T23:59:59" api

확인 사항:

• 데이터베이스 연결 오류
• Redis 연결 실패
• RabbitMQ 연결 문제
• 인증 오류
• API 엔드포인트 오류 (500, 503 등)
• 가져오기/내보내기 오류
• 지식 베이스 처리 오류
• 워커 작업 실패

​

워커 컨테이너 로그 확인

워커 컨테이너는 백그라운드 작업 (KB 처리, 임베딩 등)을 처리합니다:

# 워커 로그 확인
docker logs --tail 100 worker

# 또는 celery_worker의 경우
docker logs --tail 100 celery_worker

# 모든 워커 인스턴스 확인
docker ps | grep worker
docker logs <worker_container_name>

확인 사항:

• 작업 실행 오류
• 메모리 문제
• 타임아웃 오류
• 워커의 데이터베이스 연결 오류
• 지식 베이스 동기화 실패
• 임베딩 생성 오류

​

웹 컨테이너 로그 확인

프론트엔드 컨테이너 로그에서 UI 및 API 연결 문제를 확인할 수 있습니다:

# 웹 컨테이너 로그 확인
docker logs --tail 100 web

# 로그 따라가기
docker logs -f web

확인 사항:

• 빌드 오류
• API 연결 실패
• 환경 변수 문제
• 포트 바인딩 오류

​

데이터베이스 상태

​

PostgreSQL/Supabase 데이터베이스 상태 확인

# 데이터베이스 컨테이너 상태 확인
docker ps | grep -E "(db|postgres|supabase-db)"

# 데이터베이스 컨테이너 로그 확인
docker logs --tail 100 supabase-db

# 또는 postgres 컨테이너의 경우
docker logs --tail 100 postgres

# 데이터베이스 연결 (psql이 가능한 경우)
docker exec -it supabase-db psql -U postgres

# 데이터베이스 연결 확인
docker exec supabase-db psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"

# 데이터베이스 크기 확인
docker exec supabase-db psql -U postgres -c "SELECT pg_size_pretty(pg_database_size('postgres'));"

확인 사항:

• 데이터베이스 컨테이너가 실행 중인지
• 로그에 연결 오류가 없는지
• 데이터베이스가 가득 차지 않았는지 (디스크 공간 확인)
• 활성 연결이 제한 내에 있는지
• 작업을 차단하는 장시간 실행 쿼리가 없는지

​

API에서 데이터베이스 연결 확인

# API 컨테이너에서 데이터베이스 연결 테스트
docker exec api python -c "
import os
from sqlalchemy import create_engine
try:
    engine = create_engine(os.environ.get('DATABASE_URL'))
    conn = engine.connect()
    print('데이터베이스 연결 성공')
    conn.close()
except Exception as e:
    print(f'데이터베이스 연결 실패: {e}')
"

​

데이터베이스 마이그레이션 확인

# 마이그레이션이 최신인지 확인
docker exec api alembic current

# 마이그레이션 이력 확인
docker exec api alembic history

# 보류 중인 마이그레이션 보기
docker exec api alembic heads

​

Redis 상태

​

Redis 컨테이너 확인

# Redis 컨테이너 상태 확인
docker ps | grep redis

# Redis 로그 확인
docker logs --tail 100 redis

# Redis 연결 테스트
docker exec redis redis-cli ping

# 반환값: PONG

# Redis 정보 확인
docker exec redis redis-cli info

# Redis 메모리 사용량 확인
docker exec redis redis-cli info memory

# 연결된 클라이언트 확인
docker exec redis redis-cli info clients

확인 사항:

• Redis가 ping에 응답하는지
• 메모리 사용량이 제한 내에 있는지
• 연결 오류가 없는지
• eviction 오류 (메모리 부족)가 없는지

​

API 컨테이너에서 Redis 테스트

# API에서 Redis 연결 테스트
docker exec api python -c "
import redis
import os
try:
    r = redis.Redis(host='redis', port=6379, decode_responses=True)
    r.ping()
    print('Redis 연결 성공')
except Exception as e:
    print(f'Redis 연결 실패: {e}')
"

​

RabbitMQ 상태

​

RabbitMQ 컨테이너 확인

# RabbitMQ 컨테이너 상태 확인
docker ps | grep rabbitmq

# RabbitMQ 로그 확인
docker logs --tail 100 rabbitmq

# RabbitMQ 관리 콘솔 확인 (접근 가능한 경우)
# 접근: http://<server-ip>:15672
# 기본 자격 증명: user/password

확인 사항:

• 컨테이너가 실행 중인지
• 연결 오류가 없는지
• 큐가 메시지를 처리하고 있는지
• 메시지 백로그가 없는지

​

API에서 RabbitMQ 확인

# RabbitMQ 연결 테스트
docker exec api python -c "
import pika
try:
    connection = pika.BlockingConnection(
        pika.ConnectionParameters('rabbitmq', 5672, '/',
            pika.PlainCredentials('user', 'password'))
    )
    print('RabbitMQ 연결 성공')
    connection.close()
except Exception as e:
    print(f'RabbitMQ 연결 실패: {e}')
"

​

시스템 리소스

​

디스크 공간 확인

디스크 공간 부족은 데이터베이스, 스토리지, 컨테이너 문제를 일으킬 수 있습니다:

# 전체 디스크 사용량 확인
df -h

# Docker 볼륨의 디스크 사용량 확인
docker system df

# 특정 볼륨 사용량 확인
docker volume inspect <volume_name>

# 디렉토리 크기 확인
du -sh /var/lib/docker/volumes/*
du -sh ./supabase/docker/volumes/*

# 컨테이너 내 디스크 사용량 확인 (데이터베이스용)
docker exec supabase-db df -h

확인 사항:

• 루트 파티션에 충분한 공간이 있는지 (>20% 여유 공간 권장)
• Docker 볼륨이 가득 차지 않았는지
• 데이터베이스 데이터 디렉토리에 공간이 있는지
• Supabase 스토리지에 공간이 있는지

​

메모리 사용량 확인

# 시스템 메모리 확인
free -h

# 컨테이너 메모리 사용량 확인
docker stats --no-stream

# 특정 컨테이너 메모리 확인
docker stats <container_name> --no-stream

확인 사항:

• 시스템에 사용 가능한 메모리가 있는지
• 컨테이너가 메모리 제한에 도달하지 않았는지
• 로그에 OOM (메모리 부족) 킬이 없는지

​

CPU 사용량 확인

# CPU 사용량 확인
top
# 또는
htop

# 컨테이너 CPU 사용량 확인
docker stats --no-stream

​

네트워크 연결

​

컨테이너 네트워크 확인

# Docker 네트워크 확인
docker network ls

# 네트워크 구성 검사
docker network inspect <network_name>

# 컨테이너 간 통신 확인
docker exec api ping -c 3 redis
docker exec api ping -c 3 rabbitmq
docker exec api ping -c 3 supabase-db

​

포트 가용성 확인

# 포트 사용 여부 확인
netstat -tulpn | grep -E "(3001|8001|6379|5672|5432|8000)"

# 또는 ss 사용
ss -tulpn | grep -E "(3001|8001|6379|5672|5432|8000)"

# 컨테이너에서 포트 확인
docker exec api curl -I http://localhost:8001/health

​

환경 변수

​

환경 구성 확인

# 컨테이너의 환경 변수 확인
docker exec api env | grep -E "(DATABASE|REDIS|RABBITMQ|API)"

# .env 파일 확인 (접근 가능한 경우)
cat ./env/.env.server | grep -v "PASSWORD\|SECRET\|KEY"  # 민감한 데이터 제외
cat ./env/.env.web | grep -v "PASSWORD\|SECRET\|KEY"

# docker-compose에서 환경 확인
docker compose config

확인 사항:

• 데이터베이스 연결 문자열이 올바른지
• Redis 및 RabbitMQ 호스트 이름이 올바른지
• API URL이 올바르게 구성되어 있는지
• 필수 환경 변수가 설정되어 있는지
• 변수 이름에 오타가 없는지

​

파일 권한

​

파일 및 디렉토리 권한 확인

# 주요 디렉토리 권한 확인
ls -la ./alignment-project-server
ls -la ./ai-content-creator
ls -la ./supabase/docker/volumes

# Docker 소켓 권한 확인
ls -la /var/run/docker.sock

# 인증서 파일 확인 (HTTPS 사용 시)
ls -la ./certs/

확인 사항:

• 애플리케이션 디렉토리가 읽기 가능한지
• Docker 소켓에 올바른 권한이 있는지
• 볼륨 마운트에 적절한 권한이 있는지
• 인증서 파일에 접근할 수 있는지

​

서비스별 확인

​

지식 베이스 문제

지식 베이스가 업데이트되거나 처리되지 않는 경우:

# KB 처리를 위한 워커 로그 확인
docker logs --tail 200 worker | grep -i "knowledge\|kb\|embedding"

# 임베딩 모델 문제 확인
docker logs api | grep -i "embedding\|model"

# Supabase 스토리지 확인
docker logs supabase-storage

# 파일 업로드 제한 확인
docker exec supabase-db psql -U postgres -c "
SELECT name, file_size_limit 
FROM storage.buckets;
"

​

채팅/에이전트 문제

# 에이전트 오류를 위한 API 로그 확인
docker logs --tail 200 api | grep -i "agent\|chat\|llm"

# 에이전트 작업을 위한 워커 로그 확인
docker logs --tail 200 worker | grep -i "agent\|chat"

​

인증 문제

# 인증 서비스 로그 확인
docker logs --tail 100 supabase-auth

# 인증 문제를 위한 데이터베이스 확인
docker exec supabase-db psql -U postgres -c "
SELECT * FROM auth.users LIMIT 5;
"

​

일반적인 오류 패턴

​

데이터베이스 연결 오류

증상:

• “Connection refused” 오류
• “Too many connections” 오류
• 타임아웃 오류

진단 단계:

1. 데이터베이스 컨테이너 실행 확인: docker ps | grep db
2. 데이터베이스 로그 확인: docker logs supabase-db
3. 연결 제한 확인: docker exec supabase-db psql -U postgres -c "SHOW max_connections;"
4. 활성 연결 확인: docker exec supabase-db psql -U postgres -c "SELECT count(*) FROM pg_stat_activity;"
5. 환경 변수에서 DATABASE_URL 확인

​

Redis 연결 오류

증상:

• Redis에 “Connection refused”
• 캐시 미스
• 세션 문제

진단 단계:

1. Redis 컨테이너 확인: docker ps | grep redis
2. Redis 테스트: docker exec redis redis-cli ping
3. Redis 로그 확인: docker logs redis
4. 환경 변수에서 Redis 호스트 이름 확인

​

워커 작업 실패

증상:

• 작업이 완료되지 않음
• 지식 베이스가 동기화되지 않음
• 백그라운드 작업 실패

진단 단계:

1. 워커 로그 확인: docker logs worker
2. 워커 컨테이너 상태 확인: docker ps | grep worker
3. RabbitMQ 큐 확인: RabbitMQ 관리 콘솔 접근
4. 메모리 문제 확인: docker stats worker

​

스토리지/파일 업로드 문제

증상:

• 파일 업로드 실패
• “File too large” 오류
• 스토리지 할당량 초과

진단 단계:

1. 디스크 공간 확인: df -h
2. Supabase 스토리지 로그 확인: docker logs supabase-storage
3. Supabase 구성에서 파일 크기 제한 확인
4. 스토리지 버킷 구성 확인

​

빠른 진단 스크립트

모든 확인을 한 번에 실행하는 진단 스크립트를 만듭니다:

#!/bin/bash
echo "=== EKB 온프레미스 진단 ==="
echo ""
echo "1. 컨테이너 상태:"
docker ps --format "table {{.Names}}\t{{.Status}}"
echo ""
echo "2. 디스크 공간:"
df -h | grep -E "(Filesystem|/dev/)"
echo ""
echo "3. 메모리:"
free -h
echo ""
echo "4. Redis:"
docker exec redis redis-cli ping 2>/dev/null || echo "Redis 응답 없음"
echo ""
echo "5. 데이터베이스:"
docker exec supabase-db psql -U postgres -c "SELECT version();" 2>/dev/null || echo "데이터베이스 응답 없음"
echo ""
echo "6. 최근 API 오류 (최근 20줄):"
docker logs --tail 20 api 2>/dev/null | grep -i error || echo "최근 오류 없음"
echo ""
echo "=== 진단 완료 ==="

diagnostics.sh로 저장하고 실행 가능하게 만듭니다: chmod +x diagnostics.sh, 그리고 실행합니다: ./diagnostics.sh

​

에스컬레이션 정보

L2 지원으로 에스컬레이션할 때 다음을 제공하세요:

1. 컨테이너 상태: docker ps -a 출력
2. 최근 로그: 해당 컨테이너의 최근 100-200줄
3. 시스템 리소스: df -h 및 free -h 출력
4. 오류 메시지: 로그의 특정 오류 메시지
5. 구성: 설정된 환경 변수 이름 (값이 아닌)
6. 타임라인: 문제가 시작된 시점
7. 영향: 영향을 받는 기능

지원팀 문의: [e-mail]

​

추가 리소스

• 온프레미스 설치 가이드
• Docker 문서