インストールと初期化
このガイドでは、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/フォルダにファイルが正しく配置されているか確認