四级渐进学习法 · 终端 Agent · 第 1/9 篇

Daemon 管生死,Worker 管业务。

终端 Agent 是链路的第一跳:双进程互相保命、管道按字节分帧、断点靠 inode 续采、限流靠令牌桶但绝不丢审计证据。四级台阶把这台「终端哨兵」拆到底:三十二句短句建词汇 → 四张图看骨架 → 两个实验室亲手弄坏再修好 → 一支片子讲完一条不丢的一生。

Daemon + Worker 双进程 IPC · 4B 大端长度头 · 单包 1MB 断点续采 inode+offset 令牌桶 EPS 限流 · 审计优先
THE FRAMEWORK

先看地图,再出发THE FRAMEWORK — Agent 在链路的第一跳

全链路七跳,Agent 是第一跳:终端日志 → Agent(本页)→ envoy mTLS → audit-gateway → Kafka → Flink ETL → std topic → StarRocks。它在终端上完成采集、限流、缓存、加密上报,为后面的每一跳把好第一道关。

L1

受控语言

三十二句确定性短句,分四组:双进程、IPC 通信、采集可靠性、限流与指令。一词一义,读完即拥有本页词汇表。

例:「Daemon 只做两件事:保活 Worker、提供 IPC 服务。」
L2

结构图

四张确定性结构图:双进程内部(可点击组件)、断点续采时间线、令牌桶分流、指令生命周期。

例:时间线图里 inode 99307 → 99410 就是 logrotate 前后。
L3

交互网页

两个实验室:令牌桶限流(可调 EPS、断网、补发)+ 崩溃自愈(亲手杀死 Worker 看 Daemon 三秒拉起)。加六题自测与实战参考。

例:把 EPS 拉到 10,看普通日志怎么落缓存。
L4

定制视频

六镜头解说片「一条不丢的一生」:哨兵上岗 → 分家 → 分帧 → 续采 → 限流 → 收尾。分镜与解说骨架已备,成片已交付 · 01:43。

例:一支片子讲完终端哨兵的一生。

Agent 名片(一分钟版)

名称:终端 Agent(Daemon + Worker 双进程)
一句话:终端上的常驻哨兵——不漏采、不重采、限流不丢证据。
三个数字:单包上限 1MB · 心跳间隔 30 秒 · 令牌桶 EPS 限流。
解决三件事:崩溃自愈(双进程)· 断点续采(inode+offset)· 断网不丢(加密磁盘缓存)。

LinuxWindows 服务模式持 client.crtgRPC 上报

一句话主线(背下来,全页都在展开它)

日志文件 → 采集(inode+offset) → 令牌桶(EPS) → 审计优先放行 / 普通超限落缓存 → TLS gRPC 上报 → 失败落本地加密磁盘缓存 → 恢复后按时序补发

L1 CONTROLLED LANGUAGE

受控语言:三十二句讲清终端 Agent简短、确定、一词一义——不靠形容词,只靠事实

以下每句话都来自交接材料(Agent 模块梳理、设计方案 v5)。读不懂的句子,去 L2 找对应的结构图。

双进程

§ 1 · 8 句

IPC 通信

§ 2 · 5 句

采集可靠性

§ 3 · 10 句

限流与指令

§ 4 · 9 句
L2 DIAGRAMS

结构图:Agent 的真实骨架图 1 可点击组件 · 其余三张各讲一个机制

四张图从粗到细:先看双进程全貌,再追一次日志切割下的续采,再看令牌桶怎么分流,最后看一条指令的一生。每张图都是确定性的:同样的输入永远画出同样的结构。

Daemon 守护进程(父) 保活循环monitorLoop 退出自动拉起 IPC 服务端listenIPC · 就绪文件 重启流程优雅关 → 查杀 → 拉新 兜底查杀pkill -P / powershell startWorker · restartWorkerProc · killChild 回收防僵尸 Worker 业务子进程(混合进程) 采集任务inode+offset 断点续采 gRPC 发送限流 · 磁盘缓存队列 指令队列exists / processing 去重 指令消费单协程 · panic 兜底 grpcConn(TLS) · sysinfo · offset 模块 · 优雅停机 IPC 管道 [4B 长度][JSON] Worker 崩溃 → Daemon 检测 → 自动重启 · 业务触发重启:restartCallback → IPC(restart_worker)
图 1 · 双进程内部:Daemon 管生死,Worker 管业务(点击组件查看职责)
点击图中的组件(保活循环 / IPC 服务端 / 采集任务 / 指令队列…),这里显示它的职责与行为。
时间 → messages inode=99307 offset 0 ………………………… 2.4MB(读到 2.4MB) ▲ 点位 logrotate 改名 → messages.1 messages(新) inode=99410 offset 0 ……… 从 0 续读新文件 Agent:把 99307 读到末尾(不漏)→ 切换 99410 从 0 读起(不重)→ 持续推进两个 inode 的 offset Agent 重启后同样按点位继续——路径会变,inode 稳定
图 2 · 断点续采:inode + offset 穿越日志切割与 Agent 重启
审计 / 异常日志 最高优先级 普通日志 量大 · 可延迟 令牌桶 按 EPS 速率生成令牌 令牌 = 带宽额度 优先放行 · 永不丢弃 有令牌 → 放行 无令牌 → 超限 本地加密磁盘缓存 · 恢复后按时序补发 TLS gRPC 批量压缩上报 → envoy :30015(mTLS)
图 3 · 令牌桶分流:限流限的是带宽,不是证据
内存标记(Agent 重启即丢失) 磁盘(重启断电不丢) 指令到达 ① exists 去重 ② 持久化 store ③ 内存队列 ④ processing 去重 ⑤ 单协程执行 panic 兜底 · 回执结果
图 4 · 指令生命周期:先去重、再持久化、再入队、最后单协程消费
L3 INTERACTIVE

交互探索:亲手「弄坏」再修好 Agent两个实验室 + 六题自测 + 实战参考

实验室 A 拨令牌桶:调 EPS、涌入洪峰、断网、补发,看「限流不丢证据」怎么成立。实验室 B 亲手杀死 Worker,看 Daemon 三秒内把它拉回来。玩完做六题自测,对照实战参考收尾。

3a · 两个实验室

可操作 · 可复现

实验室 A · 令牌桶限流

调低 EPS 再点「涌入」,观察审计与普通日志的不同命运;断网后全部落缓存,恢复后按时序补发。

EPS 速率 40 条/秒
点击「涌入」开始实验。每次涌入固定 4 条审计 + 16 条普通;本桶可用令牌 ≈ EPS/10。

缓存队列:0 条

实验室 B · 崩溃自愈

亲手杀死 Worker,看 Daemon 的 monitorLoop 如何检测、回收、拉起、直到 IPC 就绪。

Worker:运行中
崩溃后 3 秒内自动恢复
点击按钮模拟 Worker 崩溃,这里逐行显示 Daemon 的抢救日志。

3b · 概念自测

6 题 · 单选

已答 0 / 6 · 正确 0 · 正确率 0%

1. Agent 双进程模型中,Daemon 的职责是?

Daemon 是父进程:monitorLoop 保活、IPC 服务端、重启流程;采集、gRPC 上报、指令消费全在 Worker。

2. Daemon 与 Worker 的 IPC 怎么解决粘包?单包上限多少?

长度头 4 字节、大端;单包上限 1MB,超了拆包。长度前缀让接收方精确切分,粘包在协议层解决,不必靠超时猜边界。

3. 断点续采的点位依据是?

logrotate 改名换文件时路径会变,inode 稳定;Agent 按 inode + 偏移续采,不漏采也不重采。

4. 端侧 EPS 令牌桶触发限流时,谁的优先级最高?

审计与异常日志优先放行;普通日志超限落本地加密磁盘缓存——限流限的是带宽,不是证据。

5. 断网期间,日志怎么处理?

断网或上报失败时日志落本地加密磁盘缓存,网络恢复后按时序逐条补发——一条不丢。

6. 控制指令的两层去重是?

exists 标记已入队等待,processing 标记正在执行。两者都在内存,重启丢失没关系——指令本身持久化在 cmd_queue.store,重启断电不丢。

3c · 实战参考

来自 Agent 模块梳理

心跳字段

每 30 秒一次,走管控通道:终端版本、资源占用、缓存积压、流量状态。它是可用性探针,不是日志通道。

指令持久化

cmd_queue.store 原子写,防 JSON 损坏;单协程顺序消费,panic 有兜底;去重标记在内存、指令在磁盘。

上报协议

TLS 加密 gRPC 批量压缩上报;持 client.crt 做 mTLS;上报失败自动落加密磁盘缓存等待补发。

L4 VIDEO

定制视频:一条不丢的一生六镜头 · 成片已交付 · 01:43· 分镜与解说骨架已备

六镜头讲完终端哨兵的一生:上岗、分家、分帧、续采、限流、收尾。画面里的进程名、报文格式、机制参数与 L1–L3 同源——补片时按分镜直接渲染。

成片 · topic-01-agent.mp4 ✓ 已交付

00:00 开场 · 终端上的哨兵 00:15 双进程 · 崩溃隔离 00:34 IPC · 4 字节长度头 00:51 断点续采 · inode+offset 01:07 按路径 01:28 按 inode + 偏移

规格:1920×1080 · 30fps · 01:43 · H.264 + AAC · 中文配音(zh-CN-Yunxi 逐句合成,每句实测时长均落在自己的字幕窗口内)+ 画面内嵌字幕。底部常驻进度轨随镜头推进点亮。

分镜脚本

6 镜头 · 旁白即片中字幕

镜头 1 · 终端上的哨兵

画面:终端机渐亮,Agent 图标常驻角落,日志行滚过。
旁白:每台终端上住着一位哨兵,叫 Agent。它不睡觉,专管一件事:把日志一条不丢地送出去。

镜头 2 · Daemon 与 Worker 分家

画面:一分为二动画——极简的圆环 Daemon 包裹方块 Worker;Worker 闪红崩溃,圆环三秒拉起新方块。
旁白:它是双身。Daemon 只管保活,Worker 只管干活。干活的会崩,崩了三秒满血。

镜头 3 · 四字节长度头

画面:字节流冲进管道,粘成一团;4 字节头亮起,字节流被精确切成一段段 JSON。
旁白:两个身体靠管道说话。字节流没有边界,四个字节的长度头,就是每句话的尺子。

镜头 4 · inode 与 offset

画面:logrotate 把文件改名,文件名标签撕掉,inode 编号不变;书签沿 offset 尺度推进。
旁白:名字会骗人,编号不会。无论日志怎么切割、Agent 怎么重启,点位永远接得上——不漏,也不重。

镜头 5 · 令牌桶与加密缓存

画面:令牌滴落,审计日志红色通道直行,普通日志灰色通道排队;断网图标亮起,队列沉入加密磁盘。
旁白:洪峰来了先限流。审计证据永远放行,普通日志排队缓存、加密落盘,网回来了按时序补发。

镜头 6 · 收尾:一条不丢

画面:七跳链路整条点亮,第一跳 Agent 图标高亮,一条日志从终端飞向 envoy。
旁白:从终端到审计,第一站就立下规矩:不漏、不重、不丢。这就是终端哨兵的一生。

解说骨架:六个设计决定

镜头 2–5 的旁白依据

① 双进程

崩溃隔离:业务易崩放 Worker,保活极简放 Daemon。

② 4B 长度头

管道字节流会粘包;长度前缀是最小分帧,1MB 防大包。

③ 磁盘指令队列

重启断电不丢指令;原子写防 JSON 损坏。

④ 两层去重

exists 防重复入队、processing 防并发;内存便宜,磁盘兜底。

⑤ 令牌桶

限流限带宽不限证据;审计优先,缓存补发。

⑥ inode+offset

路径会变 inode 稳定;不漏采也不重采。