설치 및 초기화
이 가이드는 NetFUNNEL Node.js 에이전트의 설치 및 초기화 과정을 설명합니다.
1단계: 패키지 설치
의존성 추가
package.json에 다음 의존성을 추가합니다. 정확한 주소는 콘솔의 에이전트 탭에서 확인 가능합니다.
{
"dependencies": {
"netfunnel-node-agent": "{{AGENT_URL}}"
}
}
패키지 설치
프로젝트 루트 경로에서 다음 명령어를 실행합니다:
npm install
2단계: Client ID 및 Secret Key 가져오기
- NetFUNNEL 콘솔로 이동
- 우측 상단의 프로필 아이콘 클릭
통합 자격 증명(Integration Credentials) 메뉴 선택Client ID및Secret Key복사
Client ID 및 Secret Key 확인 위치
콘솔 화면 우측 상단의 프로필 아이콘을 클릭한 후, 통합 자격 증명 메뉴에서 확인할 수 있습니다.
3단계: 미들웨어 적용
서버의 요청을 먼저 수신하는 미들웨어에 NetFUNNEL 로직을 적용합니다. Express와 Nuxt 중 프로젝트 구조에 맞는 방식을 선택합니다.
Express 미들웨어 적용 방법
1. 미들웨어 생성
middleware/netfunnel-middleware.ts 파일을 생성합니다:
import { Netfunnel } from 'netfunnel-node-agent';
export function netfunnelMiddleware(req, res, next) {
Netfunnel.run(req, res).then(allowed => {
if (!allowed) {
return res.redirect(302, req._nfRedirect || '/');
}
next();
});
}
2. 앱에 미들웨어 등록
app.ts에서 NetFUNNEL을 초기화하고 미들웨어를 등록합니다:
import express from 'express';
import { router } from './routes.js';
import { netfunnelMiddleware } from './middleware/netfunnel-middleware.js';
import { Netfunnel } from 'netfunnel-node-agent';
const app = express();
const PORT = 3000;
/* NetFUNNEL 전역 초기화 */
Netfunnel.initialize({
clientId: '{{CLIENT_ID}}', // 2단계에서 가져온 Client ID
secretKey: '{{SECRET_KEY}}' // 2단계에서 가져온 Secret Key
});
app.use(netfunnelMiddleware);
app.use('/', router);
app.listen(PORT, () => {
console.log(`[APP] listening on ${PORT} (NetFUNNEL ${Netfunnel.getVersion()})`);
});
NetFUNNEL 미들웨어를 전역으로 등록하여, 모든 요청에 대해 대기열 제어를 적용합니다.
Nuxt 미들웨어 적용 방법
1. 미들웨어 생성
server/middleware/netfunnelAgent.ts 파일을 생성합니다:
import { sendRedirect } from 'h3';
import { Netfunnel } from 'netfunnel-node-agent';
export default defineEventHandler(async event => {
Netfunnel.initialize({
clientId: '{{CLIENT_ID}}', // 2단계에서 가져온 Client ID
secretKey: '{{SECRET_KEY}}' // 2단계에서 가져온 Secret Key
});
console.log('[APP] NetFUNNEL Version:', Netfunnel.getVersion());
const allowed = await Netfunnel.run(event.node.req, event.node.res);
if (!allowed) {
const redirectUrl = (event.node.req as any)._nfRedirect || '/';
console.log(`Redirecting now to: ${redirectUrl}`);
return sendRedirect(event, redirectUrl);
}
});
Nuxt 3에서는 defineEventHandler를 통해 NetFUNNEL 에이전트를 등록합니다. Netfunnel.run() 호출 후 allowed가 false이면 대기실 진입 후 리다이렉트 URL로 이동하며, 그렇지 않으면 라우팅 처리를 계속 진행합니다. Express와 달리 next() 호출이 필요 없습니다.
4단계: 초기화 설정
초기화 설정에 대한 자세한 정보는 초기화 설정 문서를 참조하세요.
기본 초기화 예제
Netfunnel.initialize({
clientId: '{{CLIENT_ID}}',
secretKey: '{{SECRET_KEY}}'
});
5단계: 설치 확인
에이전트가 올바르게 설치되었는지 확인하려면 다음을 확인하세요:
- 패키지 설치 확인:
netfunnel-node-agent패키지가 올바르게 설치되었는지 확인 - 초기화 성공: 서버 시작 시 에러가 발생하지 않아야 합니다
- 미들웨어 적용: 요청이 올바르게 처리되는지 확인
문제 해결
패키지 설치 실패:
package.json의 의존성 경로가 올바른지 확인- 콘솔의 에이전트 탭에서 정확한 URL 확인
- 네트워크 연결 확인
초기화 실패:
clientId와secretKey가 올바르게 설정되었는지 확인- 빈 문자열이 아닌지 확인
미들웨어가 동작하지 않음:
- 미들웨어가 올바르게 등록되었는지 확인
- Express의 경우
app.use()순서 확인 - Nuxt의 경우
server/middleware/폴더에 파일이 올바르게 위치하는지 확인