hereby Platform

한국어

English

한국어

English

다크 모드

장애 대응 ​

공통 진단 절차 ​

장애 발생 시 다음 순서로 진단합니다:

  1. Docker 컨테이너 상태 확인: docker-compose ps
  2. 로그 확인: docker-compose logs --tail=50 <서비스>
  3. 네트워크 연결 확인: 서비스 간 통신 테스트
  4. 리소스 확인: docker stats --no-stream

데이터베이스 문제 ​

PostgreSQL 컨테이너가 시작되지 않음 ​

증상: docker-compose ps에서 postgres가 Exit 상태

해결:

bash
# 1. 로그 확인
docker-compose logs postgres

# 2. 볼륨 권한 문제인 경우
docker-compose down
docker volume rm hereby-dhub_postgres_data
docker-compose up -d postgres

# 3. 포트 충돌인 경우
lsof -i :5432
# 다른 프로세스가 사용 중이면 종료하거나 .env에서 포트 변경

DANGER

docker volume rm은 모든 데이터를 삭제합니다. 반드시 백업 후 실행하세요.

데이터베이스 연결 실패 ​

증상: API 서버에서 ECONNREFUSED 또는 connection timeout

해결:

bash
# 1. PostgreSQL 실행 상태 확인
docker exec hereby_postgres pg_isready -U hereby_admin

# 2. .env의 연결 정보 확인
cat .env | grep DB_

# 3. Docker 네트워크 확인
docker network ls
docker network inspect hereby-dhub_default

# 4. 컨테이너 재시작
make db-restart

마이그레이션 실패 ​

증상: migration:run 시 오류 발생

해결:

bash
# 1. 현재 마이그레이션 상태 확인
pnpm --filter @hereby/database typeorm migration:show -d src/config/data-source.ts

# 2. 마지막 마이그레이션 되돌리기
pnpm --filter @hereby/database typeorm migration:revert -d src/config/data-source.ts

# 3. 마이그레이션 파일 수정 후 재실행
make db-migrate

API 서버 문제 ​

API 서버가 시작되지 않음 ​

증상: pnpm --filter @hereby/api dev 실행 시 오류

해결:

bash
# 1. 의존성 확인
pnpm install

# 2. 빌드 오류 확인
pnpm --filter @hereby/api build

# 3. 환경 변수 확인
cat .env | grep -E "API_|JWT_|DB_"

# 4. 데이터베이스 연결 확인
docker exec hereby_postgres pg_isready -U hereby_admin

API 응답이 느림 ​

해결:

bash
# 1. 느린 쿼리 확인 (PostgreSQL 셸에서)
SELECT pid, now() - query_start AS duration, query
FROM pg_stat_activity
WHERE state != 'idle'
  AND now() - query_start > interval '1 seconds';

# 2. Redis 상태 확인
docker exec hereby_redis redis-cli info stats

# 3. 리소스 사용량 확인
docker stats --no-stream

Redis 문제 ​

Redis 연결 실패 ​

bash
# 1. Redis 컨테이너 확인
docker-compose ps redis

# 2. 연결 테스트
docker exec hereby_redis redis-cli ping

# 3. 재시작
docker-compose restart redis

Redis 메모리 초과 ​

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

# 캐시 전체 초기화 (주의)
docker exec hereby_redis redis-cli FLUSHALL

프론트엔드 문제 ​

앱이 로드되지 않음 ​

  1. API 서버가 실행 중인지 확인
  2. 브라우저 개발자 도구(F12)에서 콘솔 오류 확인
  3. 네트워크 탭에서 API 요청 실패 확인
  4. CORS 설정 확인 (.env의 CORS_ORIGIN)

인증 오류 (401/403) ​

  1. JWT 토큰 만료 여부 확인
  2. .env의 JWT_SECRET 값이 API 서버와 일치하는지 확인
  3. 브라우저 localStorage 초기화 후 재로그인

빌드 문제 ​

빌드 실패 ​

bash
# 1. 클린 빌드
pnpm clean
pnpm install
pnpm build

# 2. 특정 패키지만 빌드
pnpm --filter @hereby/core build
pnpm --filter @hereby/database build
pnpm --filter @hereby/api build

# 3. 린트 오류 자동 수정
pnpm lint:fix

TypeScript 타입 오류 ​

bash
# 타입 체크만 실행
pnpm --filter @hereby/api type-check

# 의존 패키지 먼저 빌드
pnpm --filter @hereby/core build && pnpm --filter @hereby/database build

긴급 연락처 ​

상황담당연락 방법
DB 장애DBA / IT 관리자-
API 서버 장애개발팀-
보안 인시던트보안 담당자-

INFO

긴급 연락처는 조직별로 설정하세요.