본문으로 건너뛰기
버전: 4.6.1-saas

문제 해결

NetFUNNEL Node.js Agent 통합에 대한 일반적인 문제, 해결 방법 및 자주 묻는 질문입니다.

설치 문제​

패키지 설치 실패​

증상:

  • npm install 실패
  • 패키지를 찾을 수 없음

해결 방법:

  1. 패키지 경로 확인: package.json의 의존성 경로가 올바른지 확인
  2. 콘솔 확인: 콘솔의 에이전트 탭에서 정확한 URL 확인
  3. 네트워크 연결 확인: 인터넷 연결 상태 확인
  4. npm 캐시 정리: npm cache clean --force 실행 후 재시도

초기화 실패​

증상:

  • 서버 시작 시 에러 발생
  • NetFUNNEL이 초기화되지 않음

해결 방법:

  1. clientId 확인: clientId가 올바르게 설정되었는지 확인
  2. secretKey 확인: secretKey가 올바르게 설정되었는지 확인
  3. 빈 문자열 확인: clientId와 secretKey가 빈 문자열이 아닌지 확인
  4. 초기화 위치: Express의 경우 app.ts에서, Nuxt의 경우 미들웨어에서 초기화하는지 확인

미들웨어 문제​

Express 미들웨어가 동작하지 않음​

증상:

  • 미들웨어가 호출되지 않음
  • NetFUNNEL 로직이 실행되지 않음

해결 방법:

  1. 등록 확인: app.use(netfunnelMiddleware)가 올바르게 호출되었는지 확인
  2. 순서 확인: 다른 미들웨어보다 먼저 등록되었는지 확인
  3. 초기화 확인: Netfunnel.initialize()가 미들웨어 등록 전에 호출되었는지 확인
  4. 경로 확인: 특정 경로에만 적용하려면 app.use('/path', netfunnelMiddleware) 사용

Nuxt 미들웨어가 동작하지 않음​

증상:

  • 미들웨어가 호출되지 않음
  • NetFUNNEL 로직이 실행되지 않음

해결 방법:

  1. 파일 위치 확인: server/middleware/netfunnelAgent.ts에 파일이 올바르게 위치하는지 확인
  2. 파일명 확인: 파일명이 올바른지 확인
  3. 초기화 확인: 미들웨어 내에서 Netfunnel.initialize()가 호출되었는지 확인

트리거 규칙 문제​

트리거 규칙이 매칭되지 않음​

증상:

  • 대기열이 적용되지 않음
  • 규칙에 부합하는 URL에도 대기실이 표시되지 않음

해결 방법:

  1. 규칙 확인: 콘솔에서 트리거 규칙이 올바르게 설정되었는지 확인
  2. URL 확인: 접속한 URL이 규칙의 Value와 일치하는지 확인
  3. Match 옵션 확인: Match 옵션(Equals, Contains, StartsWith, EndsWith)이 올바른지 확인
  4. 대소문자 확인: Aa 옵션(대소문자 구분) 설정 확인
  5. 테스트 기능 사용: 콘솔의 트리거 규칙 테스트 기능으로 URL이 규칙에 부합하는지 확인

대기실이 표시되지 않음​

증상:

  • 규칙에 부합하는 URL에도 대기실이 표시되지 않음
  • 사용자가 직접 진행함

해결 방법:

  1. 세그먼트 활성화: 세그먼트가 활성화되어 있는지 확인
  2. 진입 상태 확인: 진입 상태가 Waiting으로 설정되었는지 확인
  3. 진입 허용수 확인: 테스트를 위해 진입 허용수를 0으로 설정
  4. 규칙 매칭 확인: 트리거 규칙이 올바르게 매칭되는지 확인

네트워크 및 연결 문제​

네트워크 연결 오류​

증상:

  • NetFUNNEL 서버에 연결할 수 없음
  • 요청이 실패함

해결 방법:

  1. 연결 확인: 인터넷 연결 상태 확인
  2. 방화벽: NetFUNNEL 도메인이 차단되지 않았는지 확인
  3. 프록시 설정: 필요한 경우 프록시 구성
  4. 서버 URL 확인: serverUrl 설정이 올바른지 확인

타임아웃 오류​

증상:

  • 요청이 타임아웃됨
  • 응답을 받지 못함

해결 방법:

  1. 네트워크 상태 확인: 네트워크 연결 상태 확인
  2. 서버 상태 확인: NetFUNNEL 서버 상태 확인
  3. 설정 확인: 초기화 설정이 올바른지 확인

로깅 문제​

로그가 출력되지 않음​

증상:

  • printLog: true로 설정했지만 로그가 출력되지 않음

해결 방법:

  1. 설정 확인: printLog: true가 올바르게 설정되었는지 확인
  2. 초기화 확인: Netfunnel.initialize()에서 printLog: true가 설정되었는지 확인
  3. 콘솔 확인: 서버 콘솔에서 로그를 확인

키 관리 문제​

키가 반납되지 않음​

증상:

  • 다음 사용자가 무한정 대기함
  • 대기열이 진행되지 않음

해결 방법:

  1. returnKey 설정 확인: returnKey 설정이 올바른지 확인
  2. 타임아웃 확인: 세그먼트 타임아웃 설정 확인
  3. 서버 로그 확인: 서버 로그에서 키 반납 관련 오류 확인

디버깅 팁​

로그 확인​

디버깅을 위해 printLog: true로 설정하여 로그를 확인할 수 있습니다:

import { Netfunnel } from 'netfunnel-node-agent';

Netfunnel.initialize({
  clientId: '{{CLIENT_ID}}',
  secretKey: '{{SECRET_KEY}}',
  printLog: true  // 디버깅 로그 활성화
});

버전 확인​

에이전트 버전을 확인할 수 있습니다:

import { Netfunnel } from 'netfunnel-node-agent';

console.log('NetFUNNEL Version:', Netfunnel.getVersion());

일반적인 확인 사항​

  1. 초기화 확인: Netfunnel.initialize()가 올바르게 호출되었는지 확인
  2. 미들웨어 등록: Express/Nuxt 미들웨어가 올바르게 등록되었는지 확인
  3. 트리거 규칙: 콘솔에서 트리거 규칙이 올바르게 설정되었는지 확인
  4. 의존성 확인: netfunnel-node-agent 패키지가 올바르게 설치되었는지 확인

관련 문서​