fix(agent): make discovery enrollment compatible and idempotent (#53)

* fix(agent): make discovery enrollment compatible and idempotent

* fix(agent): confirm enrollment persistence and document token aliases
This commit is contained in:
ArthurKoba
2026-11-07 16:29:47 +03:00
committed by GitHub
parent 1ca03df0ef
commit 72d67c80f2
30 changed files with 1324 additions and 71 deletions
+2
View File
@@ -19,6 +19,8 @@ sidebar: false
### 🛠 修复
- 修复 Agent 自动注册响应凭证字段不一致导致节点不断重复创建的问题;新增持久化注册重试凭证与退避,响应丢失、并发重试或配置写入失败后仍复用原节点,且不会覆盖管理员修改或恢复已更换的节点凭证。支持目录刷盘的平台会确认原子替换后的目录持久化,失败时阻止使用未确认的注册凭证;接口文档同步列出两种兼容凭证字段。
- SQLite 文件数据库启动时自动启用 WAL 模式,改善读写并发;数据库导出改用一致性快照,确保包含 WAL 中已提交的数据。
- 修复 IP 组按规则自动抓取时会收录内网、回环及链路本地等地址的问题;规则测试同步过滤这些地址,历史抓取结果会在下次同步时清理。
+7 -4
View File
@@ -37,10 +37,13 @@ Agent 主要由以下核心子模块组成,共同配合完成其完整的生
Agent 在生命周期中主要通过 **基于 Token 的自动注册** 和 **心跳/WebSocket 双通道** 与控制面通信。
### 1. 自动注册流程
若 Agent 启动时本地 `agent.json` 的 `access_token` 为空,但配置了 `discovery_token`,将触发自动注册流程:
1. Agent 向控制面 `/api/v1/agent/nodes/register` 发送注册请求,携带本地硬件摘要、IP 及主机名。
2. Server 校验 `discovery_token` 有效后,在数据库生成唯一的 `NodeID` 与专属 `AccessToken`(即 `agent_token`)并返回。
3. Agent 将获取的专用 Token 写入本地配置文件,擦除一次性 `discovery_token`,后续所有的通信均基于专属 `AccessToken` 进行鉴权认证。
若 Agent 启动时本地 `agent.json` 的 `agent_token` 为空,但配置了 `discovery_token`,将触发自动注册流程:
1. Agent 在本地状态文件原子保存随机 256 位 `registration_key`,再向控制面 `/api/v1/agent/nodes/register` 发送注册请求,携带该重试凭证、本地硬件摘要、IP 及主机名。支持目录刷盘的平台会在文件刷盘及重命名后刷新所在目录;目录刷盘失败会返回错误,已有凭证也必须在重试时确认目录刷盘成功后才能发送。Windows 保留文件刷盘与替换,但目录持久化仅为尽力而为;上述行为针对所在目录已存在的文件更新,不保证所有文件系统或突然断电场景下的完整持久性。该凭证仅用于注册,不进入心跳、WebSocket 或观测数据,必须与节点 Token 一样保密。
2. Server 校验当前 `discovery_token` 有效后,从重试凭证使用不同的哈希域分别生成 `NodeID` 与专属 Token。相同凭证的重复或并发请求只保留一个节点,不按 IP、主机名或公开 `node_id` 合并,也不会覆盖管理员修改的名称、升级标志等数据。响应以 `agent_token` 为准,同时保留旧的 `access_token` 字段;新版 Agent 能识别两种字段,值冲突时拒绝响应。
3. Agent 原子保存服务端分配的节点 ID 和配置 Token,全部写入成功后才切换运行时鉴权并清空配置中的 `discovery_token`,后续通信均使用节点专属 Token。响应丢失或配置写入失败时,重启仍沿用原重试凭证;状态文件中的重试凭证与节点 ID 不会被旧的后台任务快照覆盖。
4. 注册失败按 3、6、12、24、48、60 秒退避,之后每次至少间隔 60 秒重试(实际请求在下一个心跳定时器周期触发),不再随每次心跳立即注册。成功后重置退避。
若节点 Token 已被清空或更换,旧重试凭证不能取回新 Token 或恢复旧 Token,必须使用管理员分配的节点凭证。物理删除节点不构成永久封禁:持有当前有效 discovery Token 的客户端仍能重新注册。旧版 Agent 不携带 `registration_key`,修复后的响应可使其正常完成注册,但其响应丢失后的重试仍不具备幂等保证。请保留每个实例独立的持久化状态与配置,不要把已初始化的状态目录复制给其他实例。
### 2. 双通道心跳与同步机制
* **HTTP 轮询通道(兜底与探测)**:Agent 默认按设定的 `heartbeat_interval` 间隔发送 POST 心跳包。上报指标的同时获取当前激活版本的摘要信息(Version & Checksum)。
+78 -4
View File
@@ -4443,12 +4443,12 @@ const docTemplate = `{
"summary": "注册或发现 Agent 节点",
"parameters": [
{
"description": "节点上报数据",
"description": "节点上报数据;registration_key 为首次注册重试凭证",
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/agent.NodePayload"
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.RegisterNodeRequest"
}
}
],
@@ -4464,7 +4464,7 @@ const docTemplate = `{
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/agent.RegistrationResponse"
"$ref": "#/definitions/agent.RegistrationResponseDocs"
}
}
}
@@ -14989,12 +14989,15 @@ const docTemplate = `{
}
}
},
"agent.RegistrationResponse": {
"agent.RegistrationResponseDocs": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"agent_token": {
"type": "string"
},
"name": {
"type": "string"
},
@@ -16293,6 +16296,77 @@ const docTemplate = `{
}
}
},
"github_com_Rain-kl_Wavelet_pkg_protocol.RegisterNodeRequest": {
"type": "object",
"properties": {
"access_logs": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeAccessLog"
}
},
"buffered": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.BufferedObservabilityRecord"
}
},
"current_version": {
"type": "string"
},
"edge_health": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeEdgeHealth"
},
"ext_version": {
"type": "string"
},
"health_events": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeHealthEvent"
}
},
"host_metrics": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeMetricSnapshot"
},
"ip": {
"type": "string"
},
"last_error": {
"type": "string"
},
"name": {
"type": "string"
},
"node_id": {
"type": "string"
},
"openresty_message": {
"type": "string"
},
"openresty_status": {
"type": "string"
},
"profile": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeSystemProfile"
},
"registration_key": {
"type": "string"
},
"schema_version": {
"type": "integer"
},
"version": {
"type": "string"
},
"waf_ip_group_checksums": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"github_com_Rain-kl_Wavelet_pkg_protocol.WAFIPGroup": {
"type": "object",
"properties": {
+78 -4
View File
@@ -4436,12 +4436,12 @@
"summary": "注册或发现 Agent 节点",
"parameters": [
{
"description": "节点上报数据",
"description": "节点上报数据;registration_key 为首次注册重试凭证",
"name": "body",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/agent.NodePayload"
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.RegisterNodeRequest"
}
}
],
@@ -4457,7 +4457,7 @@
"type": "object",
"properties": {
"data": {
"$ref": "#/definitions/agent.RegistrationResponse"
"$ref": "#/definitions/agent.RegistrationResponseDocs"
}
}
}
@@ -14982,12 +14982,15 @@
}
}
},
"agent.RegistrationResponse": {
"agent.RegistrationResponseDocs": {
"type": "object",
"properties": {
"access_token": {
"type": "string"
},
"agent_token": {
"type": "string"
},
"name": {
"type": "string"
},
@@ -16286,6 +16289,77 @@
}
}
},
"github_com_Rain-kl_Wavelet_pkg_protocol.RegisterNodeRequest": {
"type": "object",
"properties": {
"access_logs": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeAccessLog"
}
},
"buffered": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.BufferedObservabilityRecord"
}
},
"current_version": {
"type": "string"
},
"edge_health": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeEdgeHealth"
},
"ext_version": {
"type": "string"
},
"health_events": {
"type": "array",
"items": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeHealthEvent"
}
},
"host_metrics": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeMetricSnapshot"
},
"ip": {
"type": "string"
},
"last_error": {
"type": "string"
},
"name": {
"type": "string"
},
"node_id": {
"type": "string"
},
"openresty_message": {
"type": "string"
},
"openresty_status": {
"type": "string"
},
"profile": {
"$ref": "#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeSystemProfile"
},
"registration_key": {
"type": "string"
},
"schema_version": {
"type": "integer"
},
"version": {
"type": "string"
},
"waf_ip_group_checksums": {
"type": "object",
"additionalProperties": {
"type": "string"
}
}
}
},
"github_com_Rain-kl_Wavelet_pkg_protocol.WAFIPGroup": {
"type": "object",
"properties": {
+53 -4
View File
@@ -99,10 +99,12 @@ definitions:
type: string
type: object
type: object
agent.RegistrationResponse:
agent.RegistrationResponseDocs:
properties:
access_token:
type: string
agent_token:
type: string
name:
type: string
node_id:
@@ -955,6 +957,53 @@ definitions:
total_size:
type: integer
type: object
github_com_Rain-kl_Wavelet_pkg_protocol.RegisterNodeRequest:
properties:
access_logs:
items:
$ref: '#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeAccessLog'
type: array
buffered:
items:
$ref: '#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.BufferedObservabilityRecord'
type: array
current_version:
type: string
edge_health:
$ref: '#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeEdgeHealth'
ext_version:
type: string
health_events:
items:
$ref: '#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeHealthEvent'
type: array
host_metrics:
$ref: '#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeMetricSnapshot'
ip:
type: string
last_error:
type: string
name:
type: string
node_id:
type: string
openresty_message:
type: string
openresty_status:
type: string
profile:
$ref: '#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.NodeSystemProfile'
registration_key:
type: string
schema_version:
type: integer
version:
type: string
waf_ip_group_checksums:
additionalProperties:
type: string
type: object
type: object
github_com_Rain-kl_Wavelet_pkg_protocol.WAFIPGroup:
properties:
checksum:
@@ -7020,12 +7069,12 @@ paths:
- application/json
description: 使用节点 access token 重新注册,或使用全局 discovery token 发现新节点;请求头需携带 X-Agent-Token
parameters:
- description: 节点上报数据
- description: 节点上报数据;registration_key 为首次注册重试凭证
in: body
name: body
required: true
schema:
$ref: '#/definitions/agent.NodePayload'
$ref: '#/definitions/github_com_Rain-kl_Wavelet_pkg_protocol.RegisterNodeRequest'
produces:
- application/json
responses:
@@ -7036,7 +7085,7 @@ paths:
- $ref: '#/definitions/response.Any'
- properties:
data:
$ref: '#/definitions/agent.RegistrationResponse'
$ref: '#/definitions/agent.RegistrationResponseDocs'
type: object
"400":
description: 参数错误