Skip to content

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.example
index 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.md
index 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.ts
new file mode 100644
index 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.ts
index 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.md
index 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:
```bash
diff --git a/docs/agent/install.md b/docs/agent/install.md
index 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