mirror of
https://github.com/Rain-kl/OpenFlare.git
synced 2026-11-16 14:54:23 +08:00
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:
@@ -19,6 +19,8 @@ sidebar: false
|
||||
|
||||
### 🛠 修复
|
||||
|
||||
- 修复 Agent 自动注册响应凭证字段不一致导致节点不断重复创建的问题;新增持久化注册重试凭证与退避,响应丢失、并发重试或配置写入失败后仍复用原节点,且不会覆盖管理员修改或恢复已更换的节点凭证。支持目录刷盘的平台会确认原子替换后的目录持久化,失败时阻止使用未确认的注册凭证;接口文档同步列出两种兼容凭证字段。
|
||||
|
||||
- SQLite 文件数据库启动时自动启用 WAL 模式,改善读写并发;数据库导出改用一致性快照,确保包含 WAL 中已提交的数据。
|
||||
|
||||
- 修复 IP 组按规则自动抓取时会收录内网、回环及链路本地等地址的问题;规则测试同步过滤这些地址,历史抓取结果会在下次同步时清理。
|
||||
|
||||
@@ -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
@@ -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
@@ -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
@@ -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: 参数错误
|
||||
|
||||
Reference in New Issue
Block a user