A modern and elegant dashboard for network traffic visualization and analysis.
fix(collector): raise agent heartbeat timeout default to 90s (#58)
luoleib523968eecdf
diff --git a/.env.example b/.env.exampleindex 3172b35..405e7a3 100644--- a/.env.example+++ b/.env.example@@ -72,6 +72,10 @@ WS_EXTERNAL_PORT=3002# API_PORT=3001# COLLECTOR_WS_PORT=3002+# Agent 自动健康检查的心跳超时(毫秒,最小 15000;默认 30 秒心跳 × 3,容忍上报延迟)+# 设置在采集器进程的环境中+# AGENT_HEARTBEAT_TIMEOUT_MS=90000+# 采集器 WebSocket 心跳看门狗(检测静默断开的网关连接,见 #74)# WS_HEARTBEAT_INTERVAL_MS=10000 # ping + 活跃检测间隔# WS_HEARTBEAT_TIMEOUT_MS=30000 # 静默超过该时长则强制重连diff --git a/README.md b/README.mdindex 3c6dbd2..f1ab38c 100644--- a/README.md+++ b/README.md@@ -428,6 +428,7 @@ The script will automatically detect and suggest available ports.| Variable | Default | Description || :-- | :-- | :-- |+| `AGENT_HEARTBEAT_TIMEOUT_MS` | `90000` | Collector-side agent heartbeat timeout for automatic health checks in milliseconds (minimum `15000`); defaults to 3 × the agent's 30s heartbeat interval to tolerate delayed reports || `FLUSH_INTERVAL_MS` | `30000` | Buffer flush interval for collector writes || `FLUSH_MAX_BUFFER_SIZE` | `5000` | Max buffer entries before early flush || `REALTIME_MAX_MINUTES` | `180` | Realtime in-memory window size (minutes) |diff --git a/apps/collector/src/modules/backend/backend.service.test.ts b/apps/collector/src/modules/backend/backend.service.test.tsnew file mode 100644index 0000000..cefd6f2--- /dev/null+++ b/apps/collector/src/modules/backend/backend.service.test.ts@@ -0,0 +1,50 @@+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';+import { createTestDatabase, createTestBackend } from '../../__tests__/helpers.js';+import { AuthService } from '../auth/auth.service.js';+import type { StatsDatabase } from '../db/db.js';+import { RealtimeStore } from '../realtime/realtime.store.js';+import { BackendService } from './backend.service.js';++describe('BackendService agent heartbeat health checks', () => {+ let db: StatsDatabase;+ let cleanup: () => void;+ let backendId: number;+ let service: BackendService;++ beforeEach(() => {+ vi.useFakeTimers();+ vi.setSystemTime(new Date('2026-07-01T12:00:00.000Z'));+ ({ db, cleanup } = createTestDatabase());+ backendId = createTestBackend(db, 'test-agent', 'agent://test-agent');+ db.setBackendListening(backendId, true);+ service = new BackendService(db, new RealtimeStore(), new AuthService(db));+ });++ afterEach(() => {+ service.stopHealthChecks();+ cleanup();+ vi.unstubAllEnvs();+ vi.useRealTimers();+ });++ it.each([+ { timeout: undefined, ageMs: 45_000, expected: 'healthy' },+ { timeout: '20000', ageMs: 45_000, expected: 'unhealthy' },+ { timeout: undefined, ageMs: 90_000, expected: 'healthy' },+ { timeout: undefined, ageMs: 90_001, expected: 'unhealthy' },+ { timeout: 'invalid', ageMs: 45_000, expected: 'healthy' },+ { timeout: '1000', ageMs: 15_000, expected: 'healthy' },+ { timeout: '1000', ageMs: 15_001, expected: 'unhealthy' },+ ])('reports $expected for a $ageMs ms old heartbeat with timeout=$timeout', ({ timeout, ageMs, expected }) => {+ vi.stubEnv('AGENT_HEARTBEAT_TIMEOUT_MS', timeout);+ db.upsertAgentHeartbeat({+ backendId,+ agentId: 'test-agent',+ lastSeen: new Date(Date.now() - ageMs).toISOString(),+ });++ service.startHealthChecks();++ expect(service.getHealthStatus(backendId)?.status).toBe(expected);+ });+});diff --git a/apps/collector/src/modules/backend/backend.service.ts b/apps/collector/src/modules/backend/backend.service.tsindex ce433c9..3ccaf7e 100644--- a/apps/collector/src/modules/backend/backend.service.ts+++ b/apps/collector/src/modules/backend/backend.service.ts@@ -568,7 +568,7 @@ export class BackendService {private getAgentHeartbeatTimeoutMs(): number {return Math.max(15_000,- Number.parseInt(process.env.AGENT_HEARTBEAT_TIMEOUT_MS || '30000', 10) || 30_000,+ Number.parseInt(process.env.AGENT_HEARTBEAT_TIMEOUT_MS || '90000', 10) || 90_000,);}diff --git a/docs/agent/install.en.md b/docs/agent/install.en.mdindex 16af44f..693f118 100644--- a/docs/agent/install.en.md+++ b/docs/agent/install.en.md@@ -40,6 +40,8 @@ Optional env:- `NEKO_BIN_LINK_MODE`: `auto|true|false` for symlink into global bin dir (default `auto`)- `NEKO_LINK_DIR`: global bin dir for symlink (default `/usr/local/bin`)+Set `AGENT_HEARTBEAT_TIMEOUT_MS` in the collector process environment to adjust the agent heartbeat timeout for automatic health checks (milliseconds, default `90000`, minimum `15000`). The default allows 3 × the agent's default 30-second heartbeat interval to tolerate delayed reports; this is a collector setting, not an agent install option.+After install, manage agent with:```bashdiff --git a/docs/agent/install.md b/docs/agent/install.mdindex 0781b29..ccc7545 100644--- a/docs/agent/install.md+++ b/docs/agent/install.md@@ -40,6 +40,8 @@ curl -fsSL https://raw.githubusercontent.com/foru17/neko-master/main/apps/agent/- `NEKO_BIN_LINK_MODE`:全局 bin 目录软链模式(`auto|true|false`,默认 `auto`)- `NEKO_LINK_DIR`:软链目标目录(默认 `/usr/local/bin`)+采集器端可设置 `AGENT_HEARTBEAT_TIMEOUT_MS` 调整 Agent 自动健康检查的心跳超时(毫秒,默认 `90000`,最小 `15000`)。默认值为 Agent 默认 30 秒心跳间隔的 3 倍,用于容忍上报延迟;此变量应配置在采集器进程的环境中,而非 Agent 安装命令中。+安装完成后,使用以下命令管理 Agent:```bash