OpenFlare/docs/design/agent-design.md

Agent 设计文档

你会学到：Agent 的设计原则、核心功能模块、与 Server 的交互链路，以及如何通过不可变版本模型与三阶段容灾机制来保证配置应用的安全性和可靠性。

---

需求分析

在分布式反向代理与边缘安全网关场景中，Agent 扮演着打通控制面（Server）与数据面（OpenResty）的核心角色。由于 Agent 运行在用户实际的节点服务器上，其设计必须遵循以下核心安全与高可用需求：

1. 主动拉取（Pull 模型）而非被动接收：Server 不直接持有节点的 SSH 秘钥，也不主动发起向节点的入向连接。所有控制指令与配置更新均由 Agent 主动通过心跳（Heartbeat）或长连接（WebSocket）向上拉取。这消除了节点侧的入向防火墙安全隐患，防止了控制通道被劫持。
2. 极低侵入性：Agent 作为一个独立的 Go 二进制进程运行，只与本地 OpenResty 进程进行基于文件的配置重写与信号通知交互，不干涉节点上的其他系统服务。
3. 极强容灾与自愈能力：由于网络抖动、磁盘写满或异常配置等因素极易导致配置同步失败，Agent 必须具备零依赖的本地回滚自愈能力，严防因单次配置失误导致整机服务彻底瘫痪。
4. 纯粹的数据与状态落地：Agent 仅负责承载 Server 渲染好的文件与控制意图落地，不包含复杂的业务逻辑校验、多端租户鉴权等控制面职责，确保了节点侧的高效与轻量。

---

核心功能

Agent 主要由以下核心子模块组成，共同配合完成其完整的生命周期管理：

模块名称	对应目录	功能职责
配置同步	sync/	负责拉取完整配置包，写入文件，触发重载，记录并回报同步状态。
心跳管理	heartbeat/	定期向 Server 上报节点健康状态、资源指标，并获取最新激活版本摘要。
WebSocket	wsclient/	保持与 Server 的长连接，提供秒级实时的配置推送与控制面指令响应。
OpenResty 管控	nginx/	执行 Nginx 配置校验 (openresty -t)、重写、平滑重载 (reload) 及进程自启动。
本地状态库	state/	持久化记录本地应用版本、错误日志及未成功上报的可观测性指标缓冲。
自更新服务	updater/	监听 Server 自更新指令，安全拉取新版本二进制并完成原地热升级。
可观测性	observability/	采集宿主机资源读数、OpenResty 健康/连接，并 tail 访问日志明细上报；不做 UV/TopN/吞吐等业务预聚合。详见 边缘可观测与业务流量统计。
GeoIP 维护	geoipdata/ geoipupdate/	维护并定期更新本地 GeoIP 数据库，为 WAF 地域过滤提供支撑。

---

节点列表与详情查询

节点管理页使用管理员接口 GET /api/v1/d/nodes/page，返回 data: {total, results, page, page_size}。默认每页 20 条，最大 100 条；按数据库 ID 降序排列，可通过 search（名称、节点标识或 IP 的字面子串，最多 256 字节）、status 和 node_type 进行服务端筛选。pending 表示尚未上报心跳，最近 60 秒内上报的节点为 online，其余为 offline；筛选和返回状态使用同一时间基准。未设置类型的旧节点按 edge_node 处理。搜索保留原始 Unicode 字符的字面匹配，同时兼容 ASCII 大小写折叠；SQLite 不保证完整的 Unicode 大小写不敏感匹配。前端使用相同的 256 字节 UTF-8 上限校验去除首尾空白后的搜索词，超限时保留上次有效查询并显示提示，缩短输入后恢复搜索。

配置下发记录仅为当前页节点批量加载；详情页通过 GET /api/v1/d/nodes/{id} 获取单个节点及相同的下发元数据。列表与详情每 15 秒刷新，在后台、离线或请求出错时暂停定时刷新，可通过窗口聚焦、网络恢复或手动刷新重试。筛选或每页数量变化后回到第一页，删除末页最后一条记录后自动回到有效页。同一筛选条件下切页时保留已加载的表格与总数，页码仍显示已加载页，等待响应期间禁用节点编辑、删除和详情入口；改变筛选条件时不会显示上一筛选的节点，请求失败时可手动重试。

为兼容现有集成和节点选择器，原 GET /api/v1/d/nodes 仍返回完整数组，未改变含义；选择器尚未迁移为分页搜索。仪表盘仍为全局统计和地图加载全部节点，并使用现有缓存；本次没有截断全局总数或地图数据。分页计数和当前页是独立查询，节点并发增删时可能短暂不一致，下一次刷新会更新。普通列表和类型筛选利用主键及类型索引，状态筛选可使用心跳时间索引；字面子串搜索仍可能扫描匹配候选，未宣称 B-tree 索引能加速任意子串。

---

与 Server 的交互链路

Agent 在生命周期中主要通过 基于 Token 的自动注册 和 心跳/WebSocket 双通道 与控制面通信。

1. 自动注册流程

若 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）。
• WebSocket 通道（实时通信）：在 HTTP 心跳成功后，Agent 自动尝试将连接升级为 WebSocket (/api/v1/agent/ws)。
  • WS 连接建立后，心跳与指标上报全面转移到 WS 管道，降低网络开销。
  • Server 发布或激活新版本时，通过 WS 广播通知 Agent。Agent 收到变更事件后，立即触发同步流程，实现秒级配置生效。
  • 若 WS 链路因网络问题断开，Agent 自动降级为 HTTP 轮询，并采用指数退避机制尝试重建 WS。

3. 交互时序图

sequenceDiagram
    autonumber
    participant Agent as OpenFlare Agent
    participant OR as 本地 OpenResty
    participant Server as OpenFlare Server

    Note over Agent: 首次启动 (无 AccessToken)
    Agent->>Server: 1. 自动注册请求 (携带 discovery_token)
    Server-->>Agent: 2. 颁发 NodeID 与专属 AccessToken (agent_token)
    Note over Agent: 存储 Token 至本地配置文件

    rect rgb(240, 248, 255)
        Note over Agent, Server: HTTP 兜底与 WebSocket 升级
        Agent->>Server: 3. 发送 HTTP Heartbeat (上报系统状态与健康度)
        Server-->>Agent: 4. 返回 ActiveConfig 摘要及 AgentSettings
        Agent->>Server: 5. 发起 WebSocket 升级请求 (/api/v1/agent/ws)
        Server-->>Agent: 6. 升级成功 (建立双向持久实时通道)
    end

    rect rgb(245, 245, 245)
        Note over Agent, Server: 实时配置发布应用链路
        Note over Server: 管理员在 UI 点击发布配置
        Server->>Agent: 7. 通过 WS 广播新配置摘要 (WSMessageTypeActiveConfig)
        Agent->>Server: 8. 请求拉取完整配置详情 (携带目标 Version/Checksum)
        Server-->>Agent: 9. 返回完整配置快照 (Nginx配置、证书、WAF规则等)
        Note over Agent: 备份旧文件，写入新配置至本地临时路径
        Agent->>OR: 10. 执行配置语法校验 (openresty -t)
        OR-->>Agent: 11. 返回语法校验结果 (OK)
        Agent->>OR: 12. 平滑重载信号 (openresty -s reload)
        Agent->>Server: 13. 上报应用成功状态 (Apply Log & ActiveVersion)
    end

---

OpenResty 的管控

Agent 对数据面 OpenResty 的管控实现了端到端的闭环，包含配置落地、语法验证、平滑重载和异常状态捕获：

1. 配置文件的落地组织

同步成功后，Agent 将配置写入 data_dir 下（默认相对路径 etc/nginx/、etc/openflare/、var/lib/openflare/，具体以 agent.json 中 main_config_path、route_config_path、cert_dir、lua_dir、runtime_config_dir、pages_dir 等字段为准）：

• nginx.conf：主配置文件（替换相关占位符，配置性能参数、Shared Dictionaries 及全局 Server）。
• conf.d/openflare_routes.conf：路由配置文件（由 Agent 生成，包含所有代理网站的 Server 块、证书路径、缓存及速率限制指令）。
• certs/：证书存放目录（文件命名为 {cert_id}.crt 和 {cert_id}.key）。
• lua/waf/ 与 lua/pow/：WAF 及防 CC 挑战所需的专用 Lua 运行时脚本。
• etc/openflare/waf_config.json 与 waf_ip_groups.json：WAF 过滤引擎所需的结构化规则配置文件。
• pages_dir：Pages 静态站点部署目录，默认位于 data_dir/var/lib/openflare/pages。当激活配置引用 Pages 项目时，Agent 按 project_id 请求控制面「最新激活包」（hash + package），以流式方式写入临时文件并执行实际响应上限与 SHA-256 校验，再安全解压到 projects/{project_id}/releases/{hash}。解压后会复核文件数与总字节，绝对防御上限为 2 GiB 包、1,000 个文件、单文件及总量 8 GiB；随后原子切换 current 并立即删除同项目其它历史 release（仅保留最新）。项目内切换激活无需重发主配置；多项目对账时单项目失败不阻塞其它项目。

2. 精细化的重载动作

1. 备份当前配置：在写入新文件之前，Agent 会将现有的配置文件复制到 .backup 临时目录下，保留完整的现场快照。
2. 写入并替换占位符：将最新拉取的模板写入，自动将模板中的绝对路径占位符（如 __OPENFLARE_LUA_DIR__、__OPENFLARE_PAGES_DIR__）替换为本地实际运行路径。
3. 语法校验：调用 openresty -t -c <temp_nginx.conf> 进行严格的语法测试。
4. 平滑重载：若校验通过，将新配置移至正式路径，执行 openresty -s reload。若 OpenResty 处于未启动状态，则使用当前配置拉起进程。
5. 捕获异常：校验或重载失败时，Agent 截获命令标准输出（stderr/stdout）作为失败详情上报。

---

发布与配置应用模型

OpenFlare 采用 不可变配置版本发布模型，而非对节点配置进行在线动态 Patch。

修改规则 -> 预览 / 查看 diff -> 发布 -> 生成完整配置版本 -> 激活版本 -> Agent 拉取 -> 本地应用 -> 上报结果

1. 核心设计原则

• 完整发布：每次发布均是对当前控制面所有启用路由、证书、Pages 部署引用、全局与局部 WAF 规则进行一次性全量编译，生成带唯一 checksum 的完整版本。
• 版本格式：采用 YYYYMMDD-NNN 递增格式，确保版本历史直观、具备单调递增性。
• 全局单激活版本：系统同时只有一个处于 active 状态的全局配置版本。回滚时无需逆向打补丁，只需将历史某个健康版本的状态改为 active，Agent 重新拉取应用即可。

2. 三阶段容灾回滚机制

当 Agent 发现配置应用（或平滑重载）失败时，将自动激活以下三阶段容灾防瘫痪链路：

graph TD
    A[配置应用失败] --> B[第一阶段: 尝试本地备份恢复]
    B -- 备份文件存在 --> C[写入本地备份文件]
    C --> D[执行 openresty -t 校验]
    D -- 校验成功 --> E[reload 恢复旧版本运行]
    D -- 校验失败 --> F[进入第二阶段]
    B -- 无备份 --> F[第二阶段: 写入内置安全兜底配置]
    F --> G[写入兜底 nginx.conf: 仅监听 80 端口]
    G --> H[启用 stub_status 健康检查]
    G --> I[其他路由统一返回 503 且拦截异常配置]
    G --> J[尝试拉起 OpenResty 维持基础存活]
    J --> K[进入第三阶段]
    E --> L[上报 Apply Warning]
    K --> M[本地阻断该异常版本重复应用]
    M --> N[上报 Apply Error 并保留详细报错]

1. 第一阶段：本地备份回退
   • Agent 尝试从前一步保存的 .backup 目录恢复主配置、路由及证书。
   • 写入备份文件后，重新执行 openresty -t 校验。若成功，重载回退并向 Server 上报 Warning（警告：应用新版本失败，已自动退回历史健康版本）。
2. 第二阶段：内置安全兜底运行
   • 若本地不存在备份配置（如首次部署即配置错误），或者回退备份配置依然校验失败，Agent 将激活最终自愈机制——写入内置安全兜底配置。
   • 安全兜底配置规范：
     • 仅监听 80 端口，不包含任何用户的真实反代路由。
     • 除 /openflare/stub_status 健康监测路由返回正常外，其他一切访问请求统一返回状态码 503 Service Unavailable，响应体固定为 OpenFlare: No Valid Configuration。
     • 尝试以此极简配置拉起 OpenResty。这能够确保 Nginx 进程自身不瘫痪，保留了底层的健康检查与探针通道，防止容器/Pod 因健康检查失败而被调度系统不断销毁重启，同时保护了敏感路由的安全性。
3. 第三阶段：本地配置阻断
   • Agent 会将当前导致崩溃的配置 version + checksum 记录在本地状态库的阻断名单中。
   • 在控制面未激活新的配置（checksum 发生变化）之前，Agent 心跳将阻断对此异常版本的重复同步拉取，防止节点陷入“心跳 -> 拉取崩溃配置 -> 崩溃回滚”的死循环。

3. WAF IP 组运行时异步同步

为了避免高频变动的恶意 IP 黑名单频繁触发主配置的全量发布与 reload（平滑重载对 Nginx 依然有微小的 CPU 与连接开销），IP 组成员采用了与发布版解耦的异步差分同步设计：

• 静态发布快照：发布生成的 waf_config.json 中仅包含规则组对 IP 组的引用关系（即 ip_whitelist_group_ids / ip_blacklist_group_ids），不包含具体的 IP 成员列表。
• 心跳差分对比：Agent 在心跳包中上报本地已缓存 IP 组的 MD5 Checksum 映射表。
• 差分下发：Server 比对当前激活版本引用的 IP 组哈希，仅向 Agent 下发缺失或发生变更的 IP 组成员，写入本地 waf_ip_groups.json，实现极速差分同步。
• WebSocket 实时通知：当 Server 手动更新 IP 组、订阅源自动同步成功、或安全规则自动触发临时封禁时，Server 会立即通过 WebSocket 广播受影响的 IP 组更新包，Agent 接收落地并即时生效，全程无须 reload Nginx。

---

设计约束

为保证数据与控制链路的安全边界，Agent 代码编写与二次开发必须严格遵守以下工程约束：

1. 零特权指令通道：Server 绝对禁止向 Agent 传递任何任意 shell 命令或远程执行脚本（如 exec/eval 等）。所有系统控制原语（如启动、停止、重载、更新）必须硬编码在 Agent 二进制内部。
2. 严格的 Token 过滤与前缀验证：Agent 侧向 Server 请求资源时，接口端点固定以 /api/v1/agent/ 为前缀，并强制携带 X-Agent-Token 进行签名或令牌核验。
3. 节点自治原则：Agent 须具备完备的离线工作能力。在与 Server 失去连接期间，本地 OpenResty 必须依靠本地已落地的配置保持反向代理服务的绝对正常运行。
4. 观测只上报事实：访问日志以明细形式上送；主机指标上报计数器/瞬时读数。禁止在 Agent 内计算业务 UV、Top 域名、24h 已提供数据等结论性指标（由 Server 聚合）。详见 边缘可观测与业务流量统计。
5. Pages 只消费控制面产物：Remote URL、GitHub Release、自动 scanner，以及未来仓库 checkout/build executor 均属于 Server 职责。Agent 不接收外部 URL、访问令牌、仓库凭据或任意 clone/install/build 命令，只拉取已经激活且带完整性元数据的部署包。