NolanHo

pi-context：一个让 AI 自己管记忆的小工具

Sat, 25 Apr 2026 12:00:00 GMT

pi-context：一个让 AI 自己管记忆的小工具#

我一直在想这件事#

用 Claude Code 久了，你会发现一个规律：前三十分钟最顺，之后越来越钝，到了某个点它会突然”失忆”——早期反复强调的规则不见了，开始问一些明明之前已经答过的问题。

后来知道这叫 compaction。上下文快到 95% 的时候，Claude Code 会把整段历史丢给模型做摘要，然后用摘要替换原始对话。有人跟踪过这个过程：一个跑了 200 分钟的 Agent，压缩完后把最初的访问控制规则忘了——那些规则不在系统提示里，而在对话早期，被当成了可丢弃的细节。

compaction 优化的是”接下来该做什么”，不是”为什么这么做”。决策上下文是压缩的第一批牺牲品。

这件事让我不舒服的地方在于：Agent 对这一切毫无感知。它不知道自己正在膨胀，不知道哪些是噪音，更不知道压缩什么时候来。它就像一个只能 malloc 不能 free 的程序，等着操作系统替它做一次全身麻醉的脑叶切除。

我要的不是更大的窗口。我要的是 Agent 知道自己什么时候该清内存，以及清哪一部分。

后来我在 Kimi CLI 上看到了 d-mail。名字来自《命运石之门》，功能也像时间旅行：Agent 读了一个大文件，发现只有三行有用，就调用 SendDMail 回滚到”读文件之前”的 checkpoint，带一条消息告诉过去的自己：“我读了 error.log，根因是 DB 连接池耗尽。”

这是个精妙的机制。但用它的人很快会发现一个问题：Agent 能”回到过去”，但它不知道自己在哪里。没有一个地图告诉它”我现在在时间线的哪个位置""我可以跳回哪些 checkpoint”。d-mail 给了 Agent 一辆时间机器，但没给导航仪。

然后我看到了 pi-context#

那阵子在翻 Pi Agent 的扩展生态。Pi 是 Mario Zechner 写的一个极简编码 Agent，session 设计很有意思——存储不是线性数组，是一棵树，每个消息是一个节点，通过 id/parentId 链接。Pi 提供了 /tree 命令让人类跳转，但 Agent 看不到这棵树。

有一天在 GitHub 上翻到 pi-context，作者是 ttttmr。README 说实现了”Agentic Context Management”——让 AI 主动管理自己的上下文。

打开源码。代码非常少，核心只有四个文件：

1
src/
2
  index.ts      # 扩展入口
3
  context.ts    # /context 命令的 Token 仪表盘
4
  utils.ts      # 辅助函数
5
skills/
6
  context-management/SKILL.md   # Agent 使用指南

读完之后，我发现它解决了一个我一直很在意但没人做好的问题。

发现一：Session Tree 被翻译成了 Git#

看到 Pi 的 tree 结构，第一反应就是：这和 git 太像了。

每条消息都是一个 commit
跳转到任意节点就是 git checkout
把一堆探索性的对话压缩成 summary，像 squash merge

pi-context 的作者把这个直觉变成了可执行的设计。给 Agent 三个工具：

context_tag：git tag，标记节点
context_log：git log，查看上下文骨架
context_checkout：git checkout，在骨架上跳转

Agent 不需要懂 Pi 内部复杂的树结构。只需要三个操作：打标签、看地图、做跳转。

但有个工程问题：对话多了之后 tree 会非常巨大。让 Agent 直接看完整 tree，它的上下文会先被 tree 本身撑爆。所以必须精简。

pi-context 的解法是只展示骨架。通过一个 isInteresting 函数过滤，只保留五类节点：

ROOT / HEAD（起点和当前位置）
Tags（Agent 主动标记的里程碑）
Summaries（压缩归档点）
Branch Points（发生分支决策的关键路口）
User Messages（用户的原始输入，天然的任务边界）

中间所有的思考过程、工具调用、内部操作都被折叠。Agent 看到的不是流水账，是一份带书签的目录。

1
35d4182f (ROOT)
2
ba87607d USER: 排查超时
3
a8e58e1d AI: 读取了日志
4
37ac65e1 TOOL: cat error.log
5
36c8ea0b SUM: 根因是DB连接池耗尽...     <- 类似一个 squash commit
6
236d45e1 USER: 准备修复
7
a8e58e1d (HEAD) AI: 方案如下...

Agent 决定跳转的时候，就是 git checkout，带一个消息：

1
context_checkout("36c8ea0b", "已确认根因是连接池耗尽，推荐增加到50...")

这个设计让我意识到，上下文管理的本质不是”压缩”，而是降维——把高维的完整对话历史降维到低维的”里程碑空间”，让 Agent 能在不丢失方向感的情况下管理记忆。

Session Tree 结构

发现二：HUD 比地图更重要#

context_log 输出时前置了一个 HUD：

1
[Context Dashboard]
2
• Context Usage:    62.3% (124.6k/200.0k)
3
• Segment Size:     12 steps since last tag 'auth-jwt-start'
4
---------------------------------------------------

Context Usage 告诉 Agent 内存压力。Segment Size 告诉它距离上次标记走了多少步。

这个设计很聪明。Agent 不需要理解”信息密度”是什么，它只需要知道”12 步没标记”意味着该行动了。HUD 把抽象的”上下文健康度”变成了两个可以比较的具体数字。

但让我更感兴趣的是 HUD 背后的设计哲学。pi-context 在 before_agent_start 钩子中向系统提示追加了一段指令：

1
use context-management skill
2
Proactively manage session history with context_tag, context_log, and context_checkout.
3
When history becomes noisy, squash it into a precise carryover summary instead of dragging failed attempts forward.

这段指令不做 API 说明，而是把上下文管理的心智模型写进了 Agent 的行为准则。Agent 被明确告知：你有责任主动管理历史，噪音出现时压缩它，别把失败的尝试拖向未来。

这是一种”认知脚手架”——不是给 Agent 工具，而是教 Agent 建立空间认知：在哪里→要去哪里→怎么去。

Build-Perceive-Navigate 循环

发现三：时间旅行的三段式状态机#

context_checkout 是整个系统最复杂的部分。读源码时注意到，实现横跨了 Pi 的三个生命周期事件：

1
// 1. 工具调用阶段：同步创建新分支
2
async execute(_id, params, ...) {
3
    const nid = await sm.branchWithSummary(tid, enrichedMessage);
4
    CheckoutParams = { ...params, nid, tid, enrichedMessage };
5
    return { content: [{ type: "text", text: "checkout start" }] };
6
}
7

8
// 2. turn_end 阶段：abort 当前回合
9
pi.on("turn_end", async (event, ctx) => {
10
    if (!CheckoutParams) return;
11
    ctx.abort();
12
});
13

14
// 3. agent_end 阶段：执行真正的树导航
15
pi.on("agent_end", async (_event, ctx) => {
16
    if (!CheckoutParams) return;
17
    if (CommandCtx) {
18
        await CommandCtx.navigateTree(CheckoutParams.nid, { summarize: false });
19
    }
20
    CheckoutParams = null;
21
});

展开收起

Pi 的会话管理不允许在工具执行过程中直接改变当前分支。所以必须把”创建分支”和”切换 HEAD”拆成两个不同生命周期的事件。turn_end 的 abort 确保旧上下文不会继续输出污染新状态。

这是一个跨生命周期的分布式状态机。三个事件之间通过模块级变量 CheckoutParams 传递状态——在正常的工程实践里，这种方式看起来有点粗糙。但考虑到 Pi Extension API 的限制，这可能是当时最简洁的方案。

另一个印象深刻的细节是 backupTag：跳转前把当前状态钉上一个标签，原始历史被永久保存在侧枝。Agent 事后如果发现总结里漏掉了关键细节，随时可以 checkout 回去查看。

不是删除，是归档。时间旅行是无损的。

D-Mail 时间旅行

源码里还有一个容易被忽略的细节#

context_tag 的自动去噪让我停下来想了一会儿。

如果 Agent 没有指定 target，pi-context 不会盲目标记当前叶子节点，而是回溯找到最后一个”有意义”的节点。具体做法是：跳过内部工具（如 context_log 自己）产生的 ToolResult，跳过只包含内部工具调用的 Assistant 消息。

这个逻辑背后是对 Agent 实际行为的深刻理解：Agent 在决定打标签之前，通常会先调用 context_log 查看当前状态。如果没有这个去噪逻辑，标签会被钉在 context_log 自己的输出上——一个对业务毫无意义的元操作节点。

这种”自动跳过噪音”的设计，说明作者不只是写了一个工具，而是观察了 Agent 的行为模式之后做的优化。

双向时间旅行#

d-mail 是”回到过去”。但 Session Tree 天然支持双向跳转：每个 SUM 节点都标记了来源，可以从归档的总结再跳回原始分支，也可以从原始分支跳转到另一个未来。

双向时间旅行

这张图模拟了一个修 bug 场景。Agent 在主线 fork 出 fix bug-1 分支，修到一半发现新问题。把分支总结为 SUM: 修复xx 合并回主线，继续走向 release。但 release 上没复现，Agent 又 checkout 回 fix 分支深入排查，最终发现 bug 和某个 feat 有关，生成新的总结。

绿线是”回到过去”——从侧枝合并回主线。紫线是”前往未来”——从侧枝直接生成新的主线节点。只要分支不被垃圾回收，Agent 随时可以在树的空间里自由移动。

session tree 还有个好处：只要不是太久远的分支，都在缓存里。

读完源码后的一些想法#

上下文管理会不会成为 Agent 的”内存管理单元”（MMU）？

现在的 Agent 就像一个没有 MMU 的程序——所有内存 flat 映射，没有分页，没有换入换出。pi-context 做的不是增加内存容量，而是给 Agent 提供了分页和换页的能力。这会不会是未来 Agent 架构的一个标准组件？

Session Tree 是不是一种可操作的长期记忆？

如果把一个 Agent 的所有会话都挂载在一棵巨大的 Session Tree 上，持续通过 summary 把重要内容保留在主线，不重要的内容稀释到久远分支——这本质上就是一种涌现式的长期记忆。重要信息被自然筛选，不重要信息被遗忘，但并未真正删除，只是检索成本变高。

主线 = 工作记忆，侧枝 = 长期记忆。

和 Git 的同步回溯

如果 context_tag 和 context_checkout 能搭配对应的 Git 操作，代码状态和上下文状态可以实现原子级同步回溯。Agent 驱动的重构和实验将拥有真正的 Undo——不是撤销最后一步，而是撤销整个思维过程。

一些不足

context_log 的 HUD 只显示百分比和步数，如果能显示”最近 N 条消息的平均 token 长度”或”工具调用密度”，Agent 可以更精确地判断信息密度。
checkout 后的 summary 是一次无缓存的全量历史调用。如果在每次 ReAct 循环都触发，成本会很高。也许可以在 session 内缓存，或者引入更智能的触发策略。
目前没有”召回”工具——Agent 需要找回某个被归档的具体细节时，只能 checkout 回 backup tag。一个只读的消息召回工具可能会更有用。

最后#

pi-context 的代码不到 600 行，但它触及了一个根本问题：当 Agent 变得越来越长命、越来越复杂，谁来管理它的记忆？

传统的答案是”框架帮它压缩”或”人类帮它切换”。pi-context 的答案是：让 Agent 像管理代码一样管理自己的上下文——打标签、看日志、做 Checkout、写提交信息。

我不知道这个方案在实际业务中能带来多大提升。但从源码设计的精巧程度来看，作者 ttttmr 不仅写了一个工具，而是提出了一种新的范式。这个范式值得被更多人注意到。

https://github.com/ttttmr/pi-context
作者的设计思路原文 https://blog.xlab.app/p/6a966aeb/

终端的语义层叠：几种终端方案的底层原理

Mon, 20 Apr 2026 00:00:00 GMT

Unix 终端不是统一的设备。1970 年代的 VT100 和 2020 年代的 Kitty 在颜色数、光标控制方式、鼠标支持、键盘编码格式上都不同。程序查询 terminfo 数据库，确认自己运行在哪种终端上，然后发送对应的控制序列。

当我发现 Vim 在 tmux 里的颜色比在原生终端里少，鼠标滚轮在不同程序下行为不一致时，才开始理解终端、PTY、multiplexer 之间叠加了多少层语义。选型经历见《我为什么选 WezTerm》。

计算发生在本地时，terminfo 查询和控制序列传输都在同一台机器上完成。计算发生在远程机器上时，网络会断，显示设备在本地。传统工具链把会话管理和显示输入拆分到不同工具；远程开发中，SSH 连接同时承载会话管理和显示输入。

TTY 与终端模拟器#

物理终端#

早期计算机没有图形界面。用户通过物理终端与机器交互——一台独立的硬件设备，有键盘和显示器，通过串口连接到主机。DEC VT100 于 1978 年推出，它定义了大量至今仍在使用的控制序列标准。物理终端内部有自己的处理器和内存，接收键盘输入，向主机发送字符，接收主机返回的控制序列并在屏幕上渲染。

TTY#

TTY 是 Teletypewriter（电传打字机）的缩写。最早的终端确实是电传打字机——一台电动打字机，通过纸带和电话线与计算机通信。Unix 把这类设备抽象为 TTY 设备，在文件系统中表现为 /dev/tty1、/dev/tty2 等。

TTY 的核心功能：接收键盘输入传给连接的进程；接收进程的输出显示在屏幕上；处理基础编辑（行缓冲、回显、中断信号如 Ctrl+C）。

终端模拟器#

个人电脑普及后，终端模拟器取代物理终端——一个软件程序，模拟物理终端的行为。iTerm2、Alacritty、Kitty、macOS 自带的 Terminal.app 都是终端模拟器。

终端模拟器不做计算，只做三件事：接收键盘输入，转换成字节流发给 shell；接收 shell 输出的字节流，解析控制序列，在窗口中绘制字符；维护 scrollback 缓冲区保存历史输出。

shell、terminal emulator、multiplexer 的区别#

shell（bash、zsh、fish）：命令解释器。输入的命令由它解析和执行。shell 不关心字符怎么画到屏幕上，只读写 TTY。
terminal emulator（iTerm2、Alacritty、Kitty）：负责画字符、处理字体颜色、滚动、复制。它创建 PTY master，shell 运行在 PTY slave 上。
terminal multiplexer（tmux、zellij）：在 shell 之上再套一层，管理多个会话、窗口、pane。它持有 PTY master，shell 运行在它创建的 PTY slave 上。

打开 iTerm2 运行 zsh：

1
iTerm2 (terminal emulator)
2
  └── PTY master
3
      └── zsh (shell) 运行在 PTY slave 上

在 iTerm2 里运行 tmux，tmux 里再运行 zsh：

1
iTerm2 (terminal emulator)
2
  └── PTY master (iTerm2 持有)
3
      └── tmux client
4
          └── UNIX socket
5
              └── tmux server
6
                  └── PTY master (tmux server 持有)
7
                      └── zsh (shell) 运行在 PTY slave 上

iTerm2 的 PTY master 连接的是 tmux client，不是 zsh；tmux server 持有另一个 PTY master，zsh 运行在它的 slave 端。

为什么需要 PTY#

物理终端时代，终端直接通过串口连接到主机。软件时代，终端模拟器和 shell 在同一台机器上运行，操作系统需要一种机制让它们通信，同时向 shell 呈现为一个真实的 TTY 设备。

PTY 就是为此设计的：一对虚拟设备（master 和 slave），slave 端对 shell 呈现为 /dev/pts/N 这样的 TTY 设备，master 端由终端模拟器持有。操作系统在内核中转发两端的数据。

PTY 是操作系统提供的虚拟设备对；终端和 shell 通过它转发字节流。shell 不必分辨物理终端和软件终端，终端模拟器也不必关心 shell 内部运行什么程序。

PTY 与网络断裂#

SSH 登录远程机器时，远程 sshd 分配一个 PTY slave，shell 运行在这个 slave 上，master 端通过 SSH 加密通道与本地终端关联。

网络断裂时，sshd 进程退出，它持有的 PTY master 关闭。内核向 PTY slave 发送 SIGHUP。shell 及其子进程默认终止。未显式脱离控制终端的训练任务、agent 进程、长时间运行的编译会在网络抖动时终止。

tmux 的解法：让 daemon 持有 PTY master#

tmux 让独立的 daemon 进程持有 PTY master。SSH 断裂只切断 tmux client 与 daemon 之间的 UNIX domain socket 连接；daemon 继续运行，PTY slave 上的进程不会收到 SIGHUP，继续执行。

UNIX domain socket 是一种进程间通信机制，工作在同一台机器的文件系统命名空间内，不经过网络协议栈。tmux client 和 server 通过这个 socket 交换消息，速度比 TCP socket 快。

terminfo：终端能力的注册表#

Unix 程序用 terminfo 确认终端型号——数据库存储在 /usr/share/terminfo/ 下，每个终端型号有一个条目，记录该终端支持哪些控制指令。

程序启动时读取 $TERM 环境变量，在数据库中找到对应条目，然后决定发送哪种控制序列。比如 Vim 发送”清屏”字节序列之前，会先查 terminfo。

$TERM 的值决定了应用程序认为自己运行在哪种终端上。控制这个变量，就控制了下游程序发送的控制序列。

terminfo 的内部结构#

flowchart LR A[程序启动] --> B[读取 $TERM] B --> C[查询 terminfo /usr/share/terminfo/] C --> D[获取控制序列模板] D --> E[发送 CSI / OSC 到终端] style C fill:#fff2cc

一个 terminfo 条目可以用 infocmp 命令查看：

1
$ infocmp xterm-256color
2
#   Reconstructed via infocmp from file: /usr/share/terminfo/78/xterm-256color
3
xterm-256color|xterm with 256 colors,
4
    am, bce, ccc, km, mc5i, mir, msgr, npc, xenl,
5
    colors#256, cols#80, it#8, lines#24, pairs#32767,
6
    bel=^G, blink=\E[5m, bold=\E[1m, clear=\E[H\E[2J,
7
    csr=\E[%i%p1%d;%p2%dr, cub=\E[%p1%dD, cud=\E[%p1%dB,
8
    cup=\E[%i%p1%d;%p2%dH, cuu=\E[%p1%dA,
9
    dch=\E[%p1%dP, dl=\E[%p1%dM, ed=\E[J, el=\E[K,
10
    ...

二进制文件包含五个部分：

Header：包含 magic number（0x11A 或 0x21E，标识字节序）、name section 大小、boolean count、number count、string count、string table size
Name section：终端的主名称和别名，以 null 字节分隔
Boolean section：每个标志占 1 byte，值为 0 或 1。例如 am（auto margin，自动换行）、bce（background color erase，清屏时保留背景色）、km（has meta key）
Number section：每个数值占 2 bytes。例如 colors#256（支持颜色数）、cols#80（列数）、lines#24（行数）
String section：每个能力对应 string table 中的一个偏移量，指向实际的控制序列模板。例如 cup（cursor_address，移动光标）、clear（清屏）、smcup/rmcup（进入/退出 alternate screen）、kmous（鼠标支持）、setaf/setab（设置前景/背景颜色）

curses 库（Vim、htop、mutt 等工具的底层）在初始化时读取 $TERM，解析 terminfo 条目；屏幕绘制操作——移动光标、改变颜色、清屏——都使用 terminfo 定义的序列。

tmux 的叠加架构与代价#

tmux 在终端之上再建一个虚拟终端层，让会话在网络断开后继续运行。

tmux server 从 tmux client 接收按键事件，处理后再向应用程序的 PTY slave 写入字节流；应用程序的输出从 PTY master 进入 tmux server，在 screen buffer 中渲染后整屏推送给 client。

TERM 截获与能力降维#

tmux 默认设置 TERM=screen* 或 TERM=tmux-256color。下游程序查询 terminfo，读到的是 tmux 的能力集，而非 iTerm2、Alacritty 或 Kitty 的。

我第一次注意到这个问题，是在一台远程服务器上打开 Vim。本地 iTerm2 支持真彩色（set termguicolors 正常工作），但同一台机器的 tmux session 里，Vim 只能显示 256 色。查了一下，tmux 把 TERM 改成了 screen-256color，Vim 查到的能力集里没有真彩色支持。这就是 TERM 截获的直接后果。

终端控制序列是以 ESC（\x1b，ASCII 27）开头的字节流指令：

flowchart TD A[ESC 0x1b] --> B{下一字节} B -->|"0x5b ["| C[CSI 光标 / 颜色 / 清屏] B -->|"0x5d ]"| D[OSC 剪贴板 / 标题] B -->|"0x4d M"| E[鼠标报告 SGR 1006] B -->|"0x49 I"| F[聚焦事件 获得焦点] B -->|"0x4f O"| G[聚焦事件 失去焦点]

CSI（Control Sequence Introducer）：ESC [ 开头，用于光标移动、颜色设置、清屏。例如 ESC [ 2 J 清屏，ESC [ 31 m 设置红色前景
OSC（Operating System Command）：ESC ] 开头，用于与操作系统交互。例如 ESC ] 52 ; c ; <base64数据> ESC \ 将数据写入系统剪贴板（OSC 52）
鼠标报告：应用程序启用鼠标模式后，终端将点击事件编码为 ESC [ <按钮编码> ; <x> ; <y> M 发送给应用程序（SGR 1006 格式）
聚焦事件：终端获得或失去焦点时，向应用程序发送 ESC [ I 和 ESC [ O

tmux 截断、翻译或降级这些序列：

能力	原生终端支持	经 tmux 后	说明
Kitty 键盘协议	完整修饰键	降级为传统编码	传统终端键盘编码无法区分 Ctrl+i 和 Tab，也无法报告多个修饰键同时按下。Kitty 扩展了编码格式，让程序收到完整的键值和修饰键掩码。tmux 作为中间层无法完整转发这些扩展编码
Sixel 图形	像素数据直传	通常被过滤	DEC 在 1980 年代定义的位图协议，通过 ANSI 序列传输像素数据。tmux 的内部数据结构是字符网格，每个格子存一个字符和颜色属性，无法承载像素矩阵
聚焦事件	原生支持	需额外配置转发	Vim 等编辑器用聚焦事件触发自动保存或状态刷新。tmux 默认不转发这些事件，因为焦点在 tmux client 和 server 之间多了一层传递
Unicode width	终端特定处理	受 tmux 网格限制	East Asian Width 标准对某些字符的宽度定义存在歧义（如某些 emoji）。不同终端采用不同启发式规则。tmux 有自己的网格实现，可能与宿主终端规则不一致

双 buffer 结构#

tmux 维护的 screen buffer 基于字符网格，与宿主终端的 scrollback 无关。

scrollback：终端模拟器（iTerm2、Alacritty）维护的历史输出缓冲区。当屏幕上的内容被新输出推上去后，旧内容进入 scrollback。用户可以用鼠标滚轮、触控板或 Shift+PageUp 回溯查看，用鼠标选中后 Command+C 直接复制到系统剪贴板。
copy-mode：tmux 自己的历史浏览机制。用户按前缀键加左方括号键进入，此时键盘事件被 tmux 消费，而不是发给 pane 内的应用程序。用 tmux 的键位导航：Space 开始选择，Enter 复制到 tmux 内部 buffer。这个 buffer 与系统剪贴板不直接互通；靠 OSC 52 或外部脚本才能把内容复制到系统剪贴板。

flowchart TD A[用户想回看历史输出] --> B{操作方式} B -->|鼠标滚轮 Shift+PageUp| C[宿主终端 scrollback 本地终端模拟器管理 Command+C 原生复制] B -->|前缀键 + 左方括号键 进入 copy-mode| D[tmux screen buffer tmux server 管理 Space 选择 / Enter 复制] style C fill:#e1f5e1 style D fill:#fff2cc

scrollback 由本地终端模拟器管理，copy-mode 由远程 tmux server 管理；数据不互通。

alternate screen 的模拟#

许多全屏 TUI 程序（Vim、less、htop）在启动时请求进入 alternate screen——独立的屏幕缓冲区。退出时切回主屏幕，原来的终端内容仍然可见。ESC [ ? 1049 h 和 ESC [ ? 1049 l 两个控制序列实现这个切换。

tmux server 在自己的 screen buffer 中模拟 alternate screen，不直接转发给宿主终端；鼠标滚动和文本选择由 tmux server 处理。

鼠标事件的多跳转发#

tmux server 先收到 X10 或 SGR 1006 鼠标事件，再决定消费、转发或进入自己的滚动逻辑。应用程序不再直接处理这些事件。

zellij 与 cmux#

zellij 的 modal 输入系统#

zellij 也是 client-server 架构，daemon 持有 PTY master，但在 Rust 中内嵌了一个 WASM 运行时，插件以 WebAssembly 模块形式加载，可以编程访问 pane、tab 和状态栏。

它的输入系统是一个显式的 modal 状态机。同一套输入设备在不同”模式”下执行不同功能。Vim 同样使用 modal 输入——normal mode 下 j 向下移动光标，insert mode 下 j 插入字母 j。用户切错 mode，输入就路由到错误目标。

Ctrl+p → pane mode
Ctrl+t → tab mode
Ctrl+s → scroll mode
PageDown / PageUp 默认挂在 scroll mode 里

像 Codex 这样通过 node-pty 注入 ANSI 序列的 agent 不跟踪 zellij 的 mode 状态。我在 zellij 里运行 Codex 时，它发送的 PageUp 被 zellij 的 scroll mode 拦截，pane 内的程序根本没有收到这个序列。

node-pty 是 Node.js 的一个库，它在操作系统中创建 PTY pair，JavaScript 程序通过它像真实终端一样与 shell 交互：写入字节流，读取输出。Codex 通过它向 shell 发送键盘输入和控制序列，期望目标程序直接消费这些字节。zellij 可能把序列收进自己的 mode 处理，不转发给 pane 内的应用程序。官方文档提到 Unlock-First preset：modal 系统在该 preset 下拦截流向应用程序的输入。

cmux：本地终端与 JSON-RPC 控制#

cmux 用 Ghostty 的 Metal 渲染管线，是一个原生 macOS 终端，提供垂直标签页和 JSON-RPC socket API。

cmux 暴露了一个 socket 接口，外部程序向这个接口发送 JSON 对象来创建窗口、切换标签、查询状态。cmux 控制本地终端，不在远程机器上保持会话存活。

cmux 重启后只还原布局、工作目录和环境变量等元数据；pty 中运行的活跃进程状态不会恢复。

WezTerm：把 multiplexing 做进终端本身#

flowchart LR GUI[WezTerm GUI client 本地渲染] <-->|RPC damage tracking| Mux[wezterm-mux-server 远程或本地] Mux -->|PTY| App[应用程序] style GUI fill:#e1f5e1 style Mux fill:#fff2cc

Domain：本地与远程 pane 的来源标记#

“domain”标记 pane 进程的来源：

local domain：在本地机器启动进程
ssh domain：通过 SSH 连接远程机器，启动 wezterm-mux-server
tls / unix domain：连接已运行的 mux server

GUI 用同一套接口处理所有 domain 的 pane。远程 pane 和本地 pane 由同一个输入分发器处理，没有区别。

Damage tracking：从整屏推流到增量更新#

flowchart TB subgraph tmux ["tmux 整屏推流"] T1[screen buffer 变化] --> T2[序列化整屏字符网格] T2 --> T3[通过 UNIX socket 发送] T3 --> T4[client 重新渲染虚拟屏幕] end subgraph wez ["WezTerm damage tracking"] W1[screen buffer 变化] --> W2{哪些单元格变了?} W2 --> W3[只发送变化的单元格 坐标 + 字符 + 颜色] W3 --> W4[client 更新对应区域] end style tmux fill:#fff2cc style wez fill:#e1f5e1

damage tracking 来自图形渲染：屏幕内容变化时，只重绘变化区域。WezTerm 把它用于终端远程传输。

mux server 维护每个 pane 的内部字符网格。当应用程序输出导致网格中的某些单元格发生变化时，server 只把这些变化的单元格——坐标、字符、颜色属性——打包发送给 GUI client。client 收到后，只更新对应的屏幕区域。

维度	tmux	WezTerm
传输内容	整屏字符流序列化	damage tracking 增量更新
带宽使用	高（每次全屏重绘）	低（只传变化的单元格）
渲染分离	client 负责重新渲染虚拟屏幕	GUI client 只管本地渲染，mux server 管理 pty
交互语义	由 tmux server 二次定义	由 GUI client 直接定义

tmux 的 screen buffer 每次变化时，tmux server 把整个字符网格序列化为字符串，通过 UNIX socket 发送给 client。client 收到后，在自己的虚拟终端状态机中重新渲染。

mux server 管理 pty 和进程；GUI client 用 OpenGL、Metal 或 WebGPU 做本地渲染。两端通过 RPC 交换 damage tracking 更新和输入事件。

TERM 端到端穿透#

在 WezTerm 的远程 domain 中，远程机器上的应用程序看到的 TERM 仍然是 wezterm（或配置的等效值），中间 multiplexer 不会替换它。Kitty 键盘协议、Sixel 图形、Unicode width 的特定行为——只要 WezTerm 原生支持——穿透时不经中间层翻译。

Lua 配置的统一命名空间#

1
return {
2
  ssh_domains = {
3
    {
4
      name = "dev",
5
      remote_address = "myserver",
6
      remote_wezterm_path = "/home/user/.local/bin/wezterm",
7
    },
8
  },
9
  keys = {
10
    {
11
      key = "d",
12
      mods = "CMD",
13
      action = wezterm.action.ShowLauncherArgs { flags = "DOMAINS" },
14
    },
15
  },
16
}

展开收起

ssh_domains 定义远程连接，keys 定义本地键位，flags = "DOMAINS" 弹出的 launcher 同时列出本地和远程 domain。

部署代价#

远程 domain/mux 通常在远程机器上也要部署 WezTerm 二进制文件，配置包含 ssh_domains、multiplexing、remote_wezterm_path 等选项。

AI Agent：输入与输出的精确对应#

AI agent 看不到屏幕，只能凭输出推断状态；输入与输出错位，推断就会出错。

Codex 通过 Node.js 的 node-pty 模块操作伪终端。node-pty 在操作系统中创建 PTY pair，JavaScript 程序像真实终端一样与 shell 交互：写入字节流，读取输出，解析 ANSI 转义序列来推断界面状态。

agent 的输入直达目标程序，屏幕状态与它发送的序列一一对应，输出历史都在同一个 scrollback 里。中间层打断这种对应关系：

鼠标事件被截获：agent 发送的鼠标点击被 tmux copy-mode 消费，目标应用程序毫无感知
滚动语义断裂：agent 期望 PageUp 直接滚动历史输出，zellij 的 modal 系统将其映射为 mode 切换
历史输出歧义：宿主终端的 scrollback 与 tmux pane history 是两个独立的数据结构，agent 读取历史时无法确定面对的是哪一个。

WezTerm 用 damage-tracking RPC 和统一的本地渲染缓存在本地 GUI 中同步 pane 屏幕状态。我在 WezTerm 的远程 domain 里运行 Codex 时，它写入的字节流直达远程 pane，输出历史和本地终端共用一个 scrollback，没有 mode 系统拦截输入。控制序列由单一的 terminfo 定义。

终端 emulator 与 multiplexer 为何分离#

终端模拟器管显示和输入，multiplexer 管会话和窗格，PTY master 与二者在同一台机器上。

计算发生在另一台机器上时，PTY master 位于远程 sshd 进程中，显示设备在本地。SSH 在两端转发数据。网络断开后，本地终端收不到远程输出，multiplexer 无法向本地发送输出。

terminfo 假设程序直接访问本地终端。控制序列跨越网络、穿越多层中间件时，tmux 的字符网格承载不了 Kitty graphics protocol 的像素数据；多层 TERM 翻译后的 Sixel 序列可能解析失败；attach/detach 切换时聚焦事件可能丢失。

WezTerm 从本地 GUI 到远程 pty 使用同一套 terminfo 和同一套 RPC 协议，远程终端是单一设备。

什么时候选什么#

tmux 依赖少、安装广。如果只是需要 SSH 会话保活，不涉及 TERM 截获或 scrollback 分离，它是更轻量的选择。

当本地与计算分离、AI agent 直接操作终端时，部署 wezterm-mux-server 得到统一的 terminfo、单一的 scrollback，控制序列不经中间层截获。这对应了我从 iTerm2 + tmux 切换到 WezTerm 远程 domain 时解决的那些具体问题。

我为什么选 WezTerm

Mon, 20 Apr 2026 00:00:00 GMT

我在 macOS 上操作，计算在远程开发机上完成。训练、实验、长时间运行的 agent 任务都在远程开发机上。网络会断，但任务不能跟着断。

有一次，我在某地方改代码，WiFi 抖动了一下，或者我的位置移动了。SSH 断开，远程机上的训练任务收到 SIGHUP，直接终止。那批数据跑了六个小时。从那以后，远程开发机的会话保活成了硬需求。

flowchart LR A[macOS 本地] -->|SSH| B[远程开发机] B --> C[训练任务] B --> D[agent 任务] B --> E[长时间运行的实验] style A fill:#e1f5e1 style B fill:#fff2cc

过去这类需求默认指向 tmux。SSH 断开后，远程 shell 和进程仍然存活。tmux 保活会话，不管终端交互。

我的工作流约束#

那次事件之后，我列出了四条必须同时满足的条件：

远程任务在网络中断后继续活着
本地交互保持原生终端体验
可以按自己的工作流深度定制
不和 Codex 这类 agent 驱动的终端工作流打架

tmux 保活了会话，但劫持了交互#

tmux 把远程 shell 会话从 SSH 连接里解耦出来。本地断网，session 还在。

tmux 保活进程的同时，还接管了终端交互。

在 tmux 里复制日志时，我要先按前缀键加左方括号键进入 copy-mode，用 Space 开始选择，Enter 复制到 tmux 内部 buffer，再想办法把它弄到系统剪贴板。而在 iTerm2 里，Command+C 直接复制选中的文本。这是两套完全不同的复制语义。

回看历史也一样。在 iTerm2 里，我用鼠标滚轮直接翻历史输出；在 tmux 里，滚轮可能进入 copy-mode，也可能被 pane 内的应用程序消费，取决于 mouse 开关和当前程序状态。宿主终端的 scrollback 和 tmux 的 pane history 是两个独立的数据结构，数据不互通。

Codex 高频刷新界面、持续输出长上下文时，这种双层语义干扰更明显。底层原理见《终端的语义层叠》.

zellij 仍是 multiplexer#

zellij 站在 multiplexer 层，重做了界面和布局。它提供 pane 和 tab，同时把交互做成一套 modal 系统：Ctrl p 进 pane mode，Ctrl t 进 tab mode，Ctrl s 进 scroll mode，连 PageDown / PageUp 默认也挂在 scroll mode 里。

zellij 把终端输入收编进了自己的 mode 体系。Codex 读长输出时发送 PageUp，zellij 却把它映射为 scroll mode 切换，而不是直接滚动历史。agent 期望的输入语义和 zellij 的实际行为对不上。

cmux 是本地终端，不解决远程持久化#

cmux 基于 Ghostty，是原生 macOS 终端，主打垂直标签页、通知提醒环、分屏面板、内置浏览器和 socket API，官网直接把 Claude Code、Codex 当成核心使用对象。

它把 agent 工作流包装成本地终端产品，不管远程会话保活。cmux 重启后只能恢复布局、工作目录、回滚缓冲区这些元数据，活跃的终端应用会话不会恢复。

WezTerm 把远程会话做进终端#

flowchart LR GUI[WezTerm GUI client 本地渲染] <-->|RPC| Mux[wezterm-mux-server 远程或本地] Mux -->|PTY| App[应用程序] style GUI fill:#e1f5e1 style Mux fill:#fff2cc

WezTerm 是 terminal emulator。复制、滚动、文本选择、快捷键发生在终端自己的层，外部 multiplexer 不会先截获它们。它内置了 multiplexer/domain 模型，配置是 Lua。

我第一次注意到 wezterm-mux-server 这个二进制文件时，才意识到 WezTerm 不是在终端外面套了一层 multiplexer，而是把远程会话能力直接做进了终端系统。wezterm connect 连接的是 mux server，wezterm cli 操作的是 mux server，远程 attach/detach 是终端自身的语义，不是额外再套一个 TUI。

它在命令层提供 wezterm connect、wezterm cli、wezterm start —domain … —attach，系统里还有单独的 wezterm-mux-server。wezterm connect 连接 multiplexer，wezterm cli 和 mux server 交互。

“本地 terminal emulator + SSH + 远程 tmux” 把远程会话管理套成额外一层 TUI。WezTerm 把它收进终端自己的 domain/mux 层。

会话持续，网络断开后还能重新 attach
本地接近原生终端，copy mode 和 pane buffer 不会重写交互
配置都在同一个 Lua 脚本里
远程 host 是常驻开发机，服务器上需要安装 WezTerm

这套远程 mux 有成本。配置层里有 ssh_domains、multiplexing、remote_wezterm_path，用全远程 domain/mux 能力，远程机器上通常也要装一份 WezTerm。

WezTerm 不需要外部 multiplexer。terminal emulator 自己处理远程连接，复制、滚动和历史都在同一层。

实际配置#

远程连接、本地键位、domain 切换都在同一个 Lua 配置脚本里：

1
return {
2
  ssh_domains = {
3
    {
4
      name = "dev",
5
      remote_address = "myserver",
6
      remote_wezterm_path = "/home/user/.local/bin/wezterm",
7
    },
8
  },
9
  keys = {
10
    {
11
      key = "d",
12
      mods = "CMD",
13
      action = wezterm.action.ShowLauncherArgs { flags = "DOMAINS" },
14
    },
15
  },
16
}

展开收起

同一个 Lua 脚本里，ssh_domains 定义远程连接，keys 定义本地键位，flags = "DOMAINS" 弹出的 launcher 同时列出本地和远程 domain。

AI Agent 需要什么#

AI agent 读字节流，不读像素。输出和输入对不上，它推断的状态就错。

Codex 通过 Node.js 的 node-pty 模块操作伪终端：它写入字节流，读取输出，解析 ANSI 转义序列来推断界面状态。

agent 写入字节流，目标程序直接接收；屏幕内容与发送的序列一致；输出都在同一个 scrollback 里。这是 agent 推断界面状态的前提。

tmux 和 zellij 都在 agent 和终端之间加了一层，打破了这种对应关系：

鼠标事件被截获：agent 发送的鼠标点击被 tmux copy-mode 消费，目标应用程序毫无感知
滚动语义断裂：agent 发送 PageUp 想滚动历史输出，zellij 的 modal 系统却把它映射为 mode 切换
历史输出歧义：宿主终端的 scrollback 与 tmux pane history 是两个独立的数据结构，agent 读取历史时无法确定面对的是哪一个

WezTerm 的 damage-tracking RPC 和本地渲染缓存在本地 GUI 上保存了 pane 屏幕的副本。agent 操作远程 pane 时，外部 mode 系统不会拦截输入，输出历史都在同一个 scrollback 里，terminfo 定义终端行为。

什么时候选什么#

tmux 预装在大多数服务器上。纯 SSH、低安装成本的场景下，它不会增加部署负担。

WezTerm 更适合我的工作流：本地和计算分离，远程机常驻，任务常常长时间运行，日常交互密度高，同时用 Codex 这类 agent 工具工作。

RL算法笔记 WIP

Sun, 25 Jan 2026 23:02:40 GMT

RL算法笔记 WIP#

最终目标!!!

image

贝尔曼公式 Bellman Equation#

定义#

回报（Return）和价值（Value）

我们定义回报 (Return) 。这是 Agent 从时刻开始，一直持续到未来所能获得的折扣累计奖励：

：执行动作后的即时奖励（reward）。
：折扣因子（Discount Factor）。
注：奖励（reward）是即时的，回报（return）是累计的。

这里面可以用递归的技巧写出：

状态价值函数（State Value）

状态价值函数定义为：在状态下，遵循策略能获得期望回报（average return）。

这里是回报（全局概念）而不是奖励（reward）

动作价值函数（Action Value）

在状态下，遵循策略采取动作，能获得期望回报（average return）。

和 State Value 的差异就是它选择了一个 action

因此：

‍

推导#

基于上述定义，我们将的递归形式代入价值函数的定义，进行展开。

代入递归定义

这里分出来两个期望，分别是下一步的即时 reward 和未来的 return

选定动作后的期望奖励

第一步：由于是个策略函数，输出多个动作，而每个动作都是一个可能性，因此需要拆成对每个动作进行求和，是在状态下，选择动作的概率
第二步：是一个环境反馈项
- 是状态和动作下，环境给予的奖励（reward）
- 自不必说，是这个奖励的概率

‍

这里的遍历性（期望如何展开）在于，在下还能去哪些状态，和 1 一样，我们自然而然的对下一状态进行展开：

这里还存在期望项没有展开完，我们还需要继续进行，而由于 RL 算法一般假设马尔可夫过程，因此在求期望时，是不必要的，因此又可写成：

这里面有个容易注意到的事实（但我来说难以注意），恰好是我们刚刚定义的，其意义是站在状态下的期望回报，只需换成，于是我们写成（又一递归形式）：

但这并非我们想要的项，因为包含，而对于一个站在状态的智能体来说，是只能通过某个动作转换到，因而我们需要把转成如此形式：

分别是状态下，采取动作能够到的概率，以及状态下，策略能够生成动作的概率，其实就是到的所有路径概率之和，最后代回得到：

‍

贝尔曼方程

上面求的所有中间结果代回：

我们发现里面都有，直接提出（求和）：

即时奖励折现后的未来价值

这就是贝尔曼方程

‍

注意这是个递推式，只描述了状态下如何求价值函数，要求解需要对每个状态列出方程组成方程组求解。

‍

其次，把提出写成这样的形式是有一定的妙处的，可以发现是一个策略，而方括号里面都是价值，包括了即时和未来两项，我们回到动作价值的定义，后面就是 Action Value：

‍

矩阵表示#

由于我们上面求出的是个递推式，为了全局求解，我们实际上需要列出方程组，因此先推导矩阵表示，我们回到提出之前，引入记号代表两项

即时奖励部分

未来回报部分

有了这两个记号原来的方程可以简化为：

再写成向量表示：

价值向量 ()：

奖励向量 ()：

转移矩阵 ()：第行第列的元素

于是直接写成：

由于和都是已知的（假设我们知道环境），上面又是线性方程组，可以直接推导解析解：

但实际中解析解通常求不出来，原因如下：

如果很大，矩阵求逆会非常困难，复杂度，而实际问题中，一般都很大
有时我们不知道和是什么，或者难以模拟，被称为 Model-Free 场景

‍

于是我们需要一种迭代求解方法

‍

贝尔曼最优方程 bellman optimal equation#

首先我们定义何为最优，这和博弈论的优势策略是一样的：

我们就说策略优于或等于

基于此，我们要寻找的最优状态价值函数定义为所有可能策略下的最大值：

这就引出几个问题：

这样的策略是否存在？
这样的策略是否唯一？
这样的策略是随机策略还是确定性策略？
如何达到这样的策略？

‍

我们继续用上面矩阵表示的记号，对于任意固定策略，价值函数满足线性方程：

观察上式，实际上的未知变量只有，我们可以看作是：

其中：

这个形式可以用不动点定理，需证明是个收缩映射：

对于任意两个价值向量和，满足：

详细证明略

‍

由此，我们可知解存在，并可以采用迭代方法求解：只需要随机初始化一个，不断应用函数，足够多步后我们能够得到最优的

在 RAG 和 Agentic 搜索下做结果融合的一些思路

Sun, 28 Dec 2025 00:29:49 GMT

在 RAG 和 Agentic 搜索下做结果融合的一些思路#

前言：读 EverMemOS 项目源码时发现里面用了 Reciprocal Rank Fusion（RRF），详细了解后意识到它本质上是一类通用的排序融合方法，在 Hybrid 搜索场景下被广泛采用。本文不展开 EverMemOS 本身，而是借这个契机，单独从 RAG / Agentic 搜索的角度，把多通道结果在融合层如何合成一个统一排序这件事梳理清楚。

1. 为什么在 RAG / Agentic 搜索下需要 Hybrid？#

在真实业务中，单一路径的检索往往难以覆盖所有信息需求，尤其是在 RAG 和 Agentic Search 这类对检索质量高度敏感的系统里更是如此。以用户画像、对话记忆、知识问答等场景为例，我们往往需要同时依赖几种通道：关键词检索负责捕捉原话里的特定词语，向量检索更擅长语义近邻，图检索能揭示实体和实体之间的关系，结构化检索则对表格、数据库中那些字段化的信息更有效。

这些通道各自擅长的是不同类型的相关性：有的更看重字面匹配，有的更看重语义相似，有的更强调上下文和结构。如果只选择其中一种，很容易出现两个极端：要么重要信息根本没有被召回，要么召回了一大堆噪声，排序结果非常不稳定。

在实际系统中，随着业务发展，查询的形态会不断演化：从短句关键词，到含有上下文的长问题，再到多轮对话中的追问和反问。对于 RAG 和 Agentic 搜索来说，这直接表现为：有些问题更依赖关键词的精确命中，有些问题更依赖语义近邻，还有一些问题只有在理解实体关系或结构化字段后才能被合理回答。Hybrid 搜索存在的意义，就是在召回阶段引入多视角，在融合阶段把这些视角下得到的结果汇总成一个相对稳定的排序，让上层的 LLM 或 Agent 不必在碎片化的多路结果上再做一次检索工作。

下面先给出一个简化的架构视图，用来说明召回与融合的分工，然后重点展开融合层可以采用的几种技术路径。

image

2. 整体架构：召回与融合#

在实践中，大家常用的描述是召回 → 融合 → 重排的三层结构。为了把注意力集中在融合层上，可以先把重排暂时放在一边，只保留前两层：召回层负责把各个通道的候选拉齐到桌面上，融合层负责给这一堆候选排出一个大家都能接受的顺序。

如果把整个过程压缩成几步，大致可以理解为：给定一个查询，我们并行地向 BM25、Embedding、图检索等通道发起检索，分别得到若干个形如的列表；随后，在融合层把这些列表合并成一个候选集合，并按某种规则给出最终排序。召回阶段主要受索引结构、向量模型和吞吐约束的影响，而融合阶段则更多关注不同通道之间的博弈关系与整体鲁棒性。

下面先简要看一下召回层的设计要点，然后把主要篇幅留给融合层的方法与理论。

3. 召回层：多通道设计与配额控制#

召回层的目标不是把顺序排好，而是尽量不漏掉潜在相关的文档。典型的设计要点包括：

通道选择：根据业务场景选择 BM25、Embedding、图搜索、结构化检索等通道；
配额控制（budgeting） ：为每个通道分配 Top-K 配额，例如 BM25 取 100 条、Embedding 取 200 条、图搜索取 50 条；
基础去重：在单通道内部做简单去重（按文档 ID）；
召回结果结构化：统一整理为 {doc_id, score, source} 的形式，保留通道来源信息。

在这一层，我们通常不会对分数之间的可比性做过多要求，只需要保证：

每条通道内部的排序是可靠的（分数单调对应名次）；
结果集的规模在可控范围内，方便后续融合和重排。

在实践中，召回层还有几个容易被忽视但很关键的问题：

配额分配是策略问题而不是纯参数问题：不同通道的 Top-K 配额不仅影响召回率，也直接影响后续融合的话语权。例如给 BM25 只 20 条、给向量 500 条，几乎等价于把主导权交给向量通道。
静态配额 vs 动态配额：
- 静态配额实现简单，但对不同 query 形态的适配性有限；
- 动态配额可以基于 query 特征（长度、是否包含实体、是否是导航型等）调整不同通道的配额，更适合复杂业务，但需要更多监控与调参。
候选池大小与下游成本：召回过多会放大后续融合和重排的成本和延迟；召回过少则会直接限制上限。通常需要结合性能预算设定一个全局候选池上限，并按通道、按业务重要性进行切分。

4. 融合层：几种混合技术#

在融合层，我们的目标是把多通道召回得到的候选集合，转化为一个在全局上可比较的排序结果。常见的技术路径大致可以归为三类：

4.1 分数归一化与线性加权#

这是一种最直观的方式。直接在分数空间里做融合，尝试将各通道的分数拉到同一量纲上，再做加权合成：

对每个通道，先做一次归一化，例如：
- min-max 归一化；
- z-score 归一化；
- 基于排序的分位数映射（如将分数映射到的分位区间）。
然后对同一文档来自不同通道的归一化分数求和或加权求和，例如：

其中是第个通道对文档的归一化分数，是对应的权重。

这一类方法的优点是：

实现简单、直观；
能够利用分数幅度的信息，例如特别高的得分。

但在工程上会遇到一些明显问题：

分数分布差异大：不同通道分数的尺度和分布差异明显，归一化方式容易影响结果；
分布随时间漂移：模型或索引配置变化后，分数分布可能随时间漂移，导致线下调好的权重在新场景失效；
权重难以泛化：在缺乏标注数据时，很难稳定地调优，在新场景下常需要重新调参。

因此，分数加权更适合作为有标注、有监控情况下的精细优化手段，而不是零标注场景下的首选方案。在有标注的情况下，我们甚至可以把上面的线性形式视为一个简单的模型：

以用户是否点击 / 转化作为标签；
以各通道的归一化分数作为特征；
用逻辑回归或线性回归学习最优的。

这实质上是一种极简版的 Learning to Rank，但特征空间和模型形式都被限定在每通道一维分数这个极小的空间里，适合作为从启发式到学习式融合的过渡形态。

4.2 基于名次的 RRF 及变体#

为了规避分数不可比的问题，另一类思路是只看名次，不看具体分数。RRF（Reciprocal Rank Fusion）就是其中应用最广的一种，可以理解为一种带平滑项的倒数名次投票制。

我们只关心文档在每个通道中的名次，而不使用原始分数本身。RRF 的打分方式为：

其中：

：第个通道（BM25、Embedding、图搜索等）；
：文档在该通道返回结果中的名次（从 1 开始）；
：平滑常数，控制对长尾名次的衰减程度，实践中常取。

直觉上：

靠前的名次贡献更大；
靠后的名次贡献迅速衰减；
如果某个文档在多个通道中都排在前列，那么它的会显著高于只在单一路通道靠前的文档。

与分数加权相比，RRF 的工程优势在于：

不依赖原始分数的尺度和分布，只需要排序结果；
对极端高分噪声更鲁棒，单通道的异常高分不会轻易压倒其他通道的一致意见；
实现简单，适合作为零标注场景下的默认融合技术。

在 RRF 周边，还可以演化出一些变体：

调整的大小，以控制是只看前几名还是兼顾更多长尾结果；
对不同通道使用不同的权重，例如在求和时乘以；
将 RRF 得分与部分通道的分数归一化结果再做一次线性加权，形成「名次 + 分数」混合方案。

如果从复杂度角度看，RRF 在工程上也比较友好：

设通道数为，每个通道召回条文档，则融合层只需处理规模的候选集合；
计算的成本是线性的，排序成本是，对于多数在线检索场景是可以接受的；
由于只依赖名次，RRF 对于分布漂移的敏感度明显低于分数加权，通常可以作为一个少调参也不容易炸的安全选项。

4.3 规则与级联式 Hybrid#

在许多业务场景中，我们还会引入一些显式规则，将通道间的关系设计为「主-辅」结构，而不是完全对等的融合：

主通道：例如向量检索，负责提供大部分相关结果；
辅通道：例如 BM25 或图搜索，用于弥补主通道在某些问题上的盲区。

典型做法包括：

先使用主通道得到 Top-N 结果；
对于某些缺失类型（如必须包含特定实体的文档），从辅通道补充若干结果；
在融合时给主通道更高的基础优先级，通过规则限定辅通道的插入位置和数量。

image

这类方案的特点是：

可解释性强，便于和业务规则结合；
不强行把所有通道完全「拉平」，而是保留一个明确的主干路径。

在工程上，规则与级联式 Hybrid 往往和 RRF / 分数加权组合使用：

先按主-辅结构过滤、补充候选集合；
再在合并后的候选上应用 RRF 或分数加权进行统一排序。

比起纯算法的融合，规则和级联方案更适合把业务约束显式编码进系统，例如：

对安全 / 合规相关的文档设置硬性优先级，不允许被其它通道结果淹没；
对某些高价值来源（官方文档、权威百科等）在同等相关性下给予额外加分；
在多语言、多区域场景下，通过规则确保结果语言 / 地域与用户匹配。

这些设计通常不适合完全交给模型自动学习，而是需要和产品 / 运营侧共同约定，再通过实验逐步固化到系统中。

4.4 排序聚合视角：RRF 与其它 Rank Fusion#

从更抽象的排序聚合（rank aggregation）或社会选择视角看，我们在做的事情是：给定多个排序器输出的序列，构造一个集体排序。这一问题在信息检索与投票理论中都被系统研究过。

经典的几类排序聚合方法包括：

Borda count：每个排序位置赋予线性递减的分数，例如第 1 名分、第 2 名分等，对所有排序求和后得到最终顺序；
Condorcet 家族方法：将排序问题转化为成对比较，寻找在多数意义下更优的一致排序；
Kemeny optimal 排序：在所有可能的全排序中，找到一个使得与各个输入排序距离之和最小的排序，这个定义在理论上很漂亮，但计算复杂度很高。

RRF 可以看作是一种带有倒数权重核的 Borda 变体：

它不是给第名一个线性分数，而是给一个形式的分数，使得前几名的权重更集中、后面的尾部衰减更快；
平滑常数决定了是只看非常靠前的少数结果，还是兼顾一个较长的前缀，实质上控制了方法的 top-heavy 程度；
与 Kemeny 这类需要全局优化的排序不同，RRF 的计算是局部且可加的，只需遍历一次候选集合即可完成。

与其它 rank fusion 方法相比，RRF 还具备两个在理论与实践上都很有用的性质：

对单调变换不敏感：由于只依赖名次，任何在单个通道内保持排序不变的分数变换（如对数、缩放）都不会影响最终结果；
对共识相关性的显式偏好：只有在多个通道都给出较好名次的文档，才能获得显著更高的得分，这与我们在信息检索中追求的稳定相关结果高度契合。

从更理论的角度看，许多排序聚合方法可以被视为在某种距离度量下逼近 Kemeny 最优排序，即在所有可能的全排序中，寻找一个与各个输入排序距离之和最小的排序。距离常用 Kendall tau，这一度量本质上统计了两个排序之间顺序相反的成对项个数。完全求解 Kemeny 排序是 NP 困难的，因此实际系统往往采用启发式近似。RRF 可以看作是一类强调前几名、一致性导向的启发式，它并不显式最小化某个全局目标，但通过对高名次赋予倒数权重，在直观上偏向那些在多数排序中都靠前的文档，从而在计算复杂度与近似质量之间取得一个工程上可接受的折中。

mem0 源码阅读：一个工程化记忆系统

Tue, 09 Dec 2025 01:26:35 GMT

mem0 源码阅读：一个工程化记忆系统#

最近在系统性看各种 Agent Memory 的实现，学习了不少开源项目和论文，打算写一组文章，输出一些记忆文章。这篇文章准备当做系列里的第一篇（实际上 COLMA 那篇才是第一篇），从相对简单但工程化程度比较完整的 mem0 开始。本文主要从工程视角出发。

1. 记忆系统和 RAG#

先从基线讲起：如果只用最朴素的 RAG 来给对话做记忆，一般会怎么做？

常见做法大概是：

每轮对话结束，把这一轮的文本 append 到某个日志列表里。
定期或每轮把日志切块、做 embedding，写进向量库。
用户下一次提问时，用 query 去向量库做相似度搜索，把 topK 结果当成上下文拼给模型。

如果我们就把这套东西当成“记忆系统”，很快会撞到几个典型问题。

第一是上下文不连贯。现实里的对话是按话题组织的，话题内部高度相关，话题之间又是突变的；而在向量库里，我们只看到一堆碎片化的 chunk。检索拿回来的内容，往往是同一话题被撕成很多段，顺序也乱了。

第二是碎片化和矛盾共存。比如用户连续几次提到“我喜欢 A”，你一直在追加新条目，最后搜出来全是类似的句子；某个时间点用户改口说“其实我现在不喜欢 A 了”，如果没有 update 机制，只能继续 add，新旧偏好会长期并存，最终哪个被模型用到，完全取决于召回运气。

第三是召回不可控。简单的向量搜索 + topK 很难保证那些真正重要、应该进入长期记忆层的内容一定能被抽出来。

这背后其实是一个定义问题：

RAG 更像是在 管理原始对话日志 的检索。
记忆系统更关心的是 长期稳定的语义事实，比如用户是谁、偏好什么、有什么长期目标。

如果把这两件事混在一起，既不好维护，也不方便审计。实践里更合理的做法，是把它们拆开：上层保留一份短期对话上下文，用来回答当前问题；底下再挂一层长期语义记忆，只存经过整理的事实，并且支持更新和回溯。

mem0 就是站在这个位置上，尝试把这层长期记忆做得更像个系统，而不仅仅是一个 append-only 的向量库。

2. mem0 的目标和定位#

从项目本身的定位来看，mem0 算是比较早期、而且工程化程度比较高的一批记忆层开源实现之一。官方 README 里给它的角色很直接：给各种 Agent、聊天机器人和应用提供一层通用的长期记忆服务，可以自托管，也可以用托管平台。

从功能上看，它对外主要暴露一个 Memory 抽象：

Python/TS SDK 和 REST API 都是围绕 Memory / AsyncMemory 这两个类展开；
Memory 底下统一封装了向量库（pgvector、Qdrant 等）、可选的图数据库（Neo4j、Memgraph 等）、LLM、embedding 模型以及一个本地的 history 数据库；
对调用方来说，基本就是围绕 add / search / update / delete / history 这几个方法来用。

从实现上看，mem0 并没有很复杂的算法，亮点更多在工程完整度和边界控制：Memory 这一层的职责划得比较清楚，下层的向量库、图库、LLM 统一走工厂模式，然后加一个 SQLite 的历史记录。

下面是架构图：

3. mem0 Memory 模块总体结构#

从代码结构看，mem0 的入口相当收敛：

无论是 REST API 还是 Python / TS SDK，最后都落到 Memory（同步）或者 AsyncMemory（异步）这两个类上。
这两个类背后，通过工厂模式挂了一整套可插拔组件：embedding 模型、向量库、图数据库、LLM、历史库和遥测。

可以用一张架构图来解释依赖关系：

flowchart LR subgraph ClientSide[客户端 / SDK / 其它服务] U["应用代码 / Agent"] end subgraph ServerSide[Mem0 进程] API["REST API / SDK 调用 server/main.py"] M["Memory / AsyncMemory mem0/memory/main.py"] subgraph Core[核心组件] E["Embedder 向量化模型"] L["LLM 事实抽取 & 决策"] VS["VectorStore 抽象 mem0/vector_stores/*"] G[("GraphStore 抽象 可选")] H[("SQLite History DB mem0/memory/storage.py")] T["Telemetry 事件上报"] end end subgraph Backend[后端存储] VDB[("向量数据库 pgvector / Qdrant / Milvus ...")] GDB[("图数据库 Neo4j / Memgraph / Neptune ...")] end U -->|HTTP / SDK| API API --> M M --> E M --> L M --> VS M --> G M --> H M --> T VS <-->|insert/search/update/delete| VDB G <-->|add/search/get_all/delete_all| GDB

从调用者的角度看，Memory 层对外只暴露了一组方法：add / search / get / update / delete / history。内部则负责：

把 messages 预处理成统一格式。
在 add 时，根据配置选择是直接写，还是推理后再写。
把所有读写请求都带上 user/agent/run 这些过滤条件，做会话隔离。
把每一次变更都记录到 historydb。

在这些方法里，最有意思的是 add()，因为它同时承载了新增、合并、删除三种行为。下面我们单独看 mem0 的流程。

4. add：一个 API 中的多种记忆操作#

在 mem0 里，add() 并不被视作插入一条记录这么简单，而是一个记忆管理入口：

在最简单的配置下，它只是把消息切成若干条，逐条 embedding，写入向量库；这一支和前面说的朴素 RAG 差别不大，mem0 真正有特点的是 infer=True 这条路径。
在 infer=True 时，它则会调用 LLM 先抽出候选事实，再去对齐已有记忆，最后生成一组 ADD / UPDATE / DELETE / NONE 的操作计划。

借助下面这张流程图来讲解一下 add 的整体路径（对应 mem0/memory/main.py 中 Memory.add 及其私有方法）：

flowchart TD subgraph Input[对话输入] MSG["多轮消息 messages"] end subgraph L1[第一阶段: 抽取候选事实] PM["parse_messages 整理成带 role 的纯文本"] SYS["选择抽取 prompt USER / AGENT memory prompt"] LLM1["LLM 调用 #1 抽取 facts"] FACTS["new_retrieved_facts 候选记忆片段"] end subgraph S1[旧记忆检索] EMB1["Embedder.embed(fact, 'add')"] VS1["VectorStore.search 按 user/agent/run 过滤"] OLD["retrieved_old_memory 相关旧记忆列表"] end subgraph L2[第二阶段: 生成操作计划] PROMPT2["get_update_memory_messages 构造函数式指令"] LLM2["LLM 调用 #2 输出 memory actions"] ACTS["new_memories_with_actions {event, text, id, ...}"] end subgraph Exec[执行并落盘] ADDM["_create_memory ADD"] UPDM["_update_memory UPDATE"] DELM["_delete_memory DELETE"] NONE["更新元数据 NONE"] HIST["SQLite history 表 记录 ADD/UPDATE/DELETE"] end MSG --> PM --> SYS --> LLM1 --> FACTS FACTS --> EMB1 --> VS1 --> OLD FACTS --> PROMPT2 OLD --> PROMPT2 --> LLM2 --> ACTS ACTS -->|event=ADD| ADDM --> HIST ACTS -->|event=UPDATE| UPDM --> HIST ACTS -->|event=DELETE| DELM --> HIST ACTS -->|event=NONE| NONE

下面我们单独看 mem0 的流程。

4.1 `infer=False`：直接写入的路径#

在 infer=False 时，add() 的行为基本等价于「带 metadata 的 RAG 写入」：

入口做的第一件事，是通过 _build_filters_and_metadata 构造过滤条件和基础元数据。这里要求调用时至少提供 user_id / agent_id / run_id 之一，用来区分不同会话或不同 Agent。
Memory.add 会把 str / dict / list[dict] 这几种形态的 messages 统一规整成 [{'role': ..., 'content': ...}]，并处理好视觉消息（图片转描述文本）。
然后走 _add_to_vector_store(..., infer=False) 这条支路：遍历每条消息（忽略 role == system），调用 embedding 模型，把得到的向量连同 payload 一起插入向量库。每一次插入同时在 history 表里写一条 event = "ADD" 的记录。

这个分支本身没有什么复杂逻辑，但可以看出，哪怕在最朴素的模式下，mem0 也已经把会话隔离和变更记录做成了默认行为，而不是留给调用方自己维护。

4.2 `infer=True`：LLM 驱动的智能记忆管理#

infer=True 是这套设计的核心。它让 add() 具备了「判断要不要记、记成什么样」的能力，大致可分成几个阶段。

第一步是从多轮对话中提炼出候选事实。

Memory.add 会先调用 parse_messages 把一组 messages 压成带 role 的长文本，形如：

1
system: ...
2
user: ...
3
assistant: ...

然后根据这是用户记忆还是 Agent 记忆选取不同的 system prompt（也允许自定义 fact 抽取 prompt），调用一次 LLM，请求它输出 JSON 格式的 new_retrieved_facts。每一个 fact 都是模型认为「有长期价值」的一句或几句描述，比如用户在上海工作、用户对辛辣食物敏感之类。

第二步是围绕这些 facts 去找旧记忆。

对每个 fact，再做一次 embedding，并带着刚才构造好的 user/agent/run 过滤条件，去向量库做语义搜索。搜索结果去重后，得到一组 retrieved_old_memory，可以理解为「和本次候选事实相关的历史记忆集合」。

第三步是让 LLM 决定具体操作。

这一步会构造一个结构化的 prompt，把「新事实 + 相关旧记忆」一起给 LLM，同时规定输出格式必须是 JSON，其中每个元素都包含：

event：ADD / UPDATE / DELETE / NONE；
text：新记忆文本（ADD/UPDATE 时使用）；
以及在 UPDATE/DELETE 情况下，指向旧记忆的 id。

这一阶段等于是把「合并还是新增还是删除」的策略交给了 LLM 来做语义判断：

如果某个 fact 和已有记忆只是在细节上有补充，就倾向于 UPDATE；
如果代表的是全新的信息，就 ADD；
如果它明确否定了旧记忆，可能会触发 DELETE；
如果模型认为这句话没有长期价值，就给出 NONE。

最后一步是落地这些 actions。

ADD 的情况比较直接：调用 _create_memory 插入向量库，同时在 history 表里写一条 ADD；UPDATE 则需要先从向量库读出旧 payload，构造一个新 payload（保留 created_at 和会话相关字段，只替换 data 和 updated_at），用 update 写回，再记一条 UPDATE 类型的历史记录，里面同时存 old/new 两个版本；DELETE 类似，先 get 出旧内容，之后从向量库删掉，history 里记一条 DELETE 并标记 is_deleted = 1；NONE 则不动向量，只是用 _update_memory_session 之类的方法更新 metadata 里的会话维度。

从整个 pipeline 流程来看，add(infer=True) 的职责可以概括成一句话：在短期对话和长期记忆之间做一次带上下文的筛选与重写，让向量库里存的不是原始聊天，而是已经抽象过的事实集合。

为了方便对照，可以再看一张更概括的流程小图，专门对应 infer=True 模式下的两次 LLM 调用：

flowchart LR subgraph "infer=True 两次调用" A["对话消息 (messages)"] B["LLM 调用 #1：抽取 new_retrieved_facts"] C["向量检索：retrieved_old_memory (按 user/agent/run 过滤)"] D["LLM 调用 #2：生成 actions (ADD/UPDATE/DELETE/NONE)"] E["执行 actions 并写入 history"] end A --> B --> C --> D --> E

这也是为什么在性能上会存在写放大：一次 add 触发了两次 LLM 调用，并且中间还有一轮向量检索。（我测的时候跑的非常慢）

5. search / update / delete：读写路径与边界#

相较于 add()，search / update / delete 这几个接口的逻辑就常规得多，但依然延续了会话隔离和 historydb 这两条主线。

5.1 search：只读、无 LLM 的查询#

Memory.search 的实现是典型的 embedding + 向量检索，没有在这一步再引入额外的 LLM 调用。它的调用序列大致如下：

sequenceDiagram participant C as Client 应用 participant API as REST API / SDK participant M as Memory participant E as Embedder participant VS as Vector Store participant G as Graph Store participant R as Reranker (可选) participant T as Telemetry C->>API: POST /search 或 Memory.search(query,...) API->>M: search(query, user_id/agent_id/run_id, filters, limit,...) M->>M: _build_filters_and_metadata() M->>E: embed(query, "search") E-->>M: 查询向量 M->>VS: search(query, vectors, filters, limit) VS-->>M: 近邻向量列表(含 score, payload) opt 启用图记忆 M->>G: graph.search(query, filters, limit) G-->>M: relations end opt 启用 reranker M->>R: rerank(query, memories, limit) R-->>M: 重排后的 memories end M->>T: capture_event("mem0.search", ...) M-->>API: {"results": memories, "relations"?} API-->>C: HTTP 200 + JSON

可以注意到几点：

search 只涉及向量库和可选的图库，不触碰 historydb，也不修改任何状态。
如果配置了 reranker，会在拿到候选结果后再做一次重排，但依然是纯检索逻辑，不会再去叫 LLM。
图搜索和向量搜索是并行分支，最后把结果合在一起。这和那种先向量检索再扩图邻居的 GraphRAG pipeline 不太一样，更偏向两个视角的独立召回。

这部分实现比较克制：它只负责取回可能相关的记忆，至于这些记忆要如何组织成上下文、是否要翻页拿前后文，mem0 没有规定做法，留给上层 Agent 或业务代码处理。

5.2 update / delete：显式操作与历史记录#

update 和 delete 的行为可以看作是对 add(infer=True) 里 UPDATE / DELETE 分支的显式版本：

update：调用者直接给出 memory_id 和新的 data，Memory 层会做一次 embedding 替换向量，同时读出旧 payload，写入一条 event = "UPDATE" 的历史记录，保留改前和改后的内容。
delete：先从向量库 get 出旧内容，再删除对应向量，最后在历史表记一条 DELETE，把旧内容放进 old_memory 字段，并打 is_deleted = 1。

这两条路径都不再经过 LLM，逻辑相对简单，但和 add(infer=True) 共用同一套 history 机制。

6. historydb：历史日志#

historydb 是 mem0 里存在感很强的一个组件，它不负责存向量，也不参与检索，只负责记录某条记忆从创建到修改再到删除的全过程。

表结构用了一张 SQLite 的 history 表，大致包含：

memory_id：对应向量库里的那条记忆；
old_memory / new_memory：某次变更前后的文本内容（ADD 时 old_memory 为空，DELETE 时 new_memory 为空）；
event：ADD / UPDATE / DELETE；
created_at / updated_at：这条历史记录自身的时间；
is_deleted：是否代表一条删除记录；
actor_id / role：是谁触发了这次操作，以及当时的角色（user / assistant）。

这种设计的直接效果是：

向量库只保存当前状态，不负责记历史版本；
所有「这条记忆经历了什么」的问题，都可以通过 Memory.history(memory_id) 查出来。

换一句话说，mem0 把每条记忆当成了一个有限状态机，状态的转换（ADD → UPDATE* → DELETE）全部写进了一张独立的表。这在需要做审计、回滚、可视化的时候，会比覆盖式更新友好得多。

7. 设计和使用上的一些思考#

读完这部分代码之后，个人有几点想法。

7.1 mem0 更适合作为长期记忆层#

从 add(infer=True) 的设计可以看出，mem0 更偏向长时稳定的语义记忆，而不是每一句话都要写入的日志系统。比如用户只问一句「烤鱼健康吗」，这本身不是 fact，更像是一个即时问题；在这种输入下，LLM 很可能抽不出任何 new_retrieved_facts，最终不会写入记忆。

更典型的情况是几轮对话拼在一起才有意义。比如：

第一轮，用户问“烤鱼健康吗”。
第二轮，又问“草鱼好吃吗”。
聊天上下文里还有一条信息是“今天晚上六点要和同事聚餐”。

人类在这里很容易脑补出一个场景：这个用户大概率在考虑今天晚上要不要吃烤鱼，或者他本身就经常吃这类东西。但在 mem0 现在的实现里，如果你把这几轮拆成一次次 add(infer=True) 调用，模型在每一轮里单独抽事实，很可能认为这几句都不值得记，于是整个片段都进不了长期记忆。这就是我在看代码时感觉比较明显的一点：mem0 的 fact 抽取是一次调用内的，缺少跨多次 add 去拼出一个更大事实的能力。

如果直接把 mem0 接在一个高频群聊后面，每条消息都丢进 add(infer=True)，就容易出现两种极端：要么什么都没记住，要么记了一堆看上去像事实、实际上很散、不形成完整画像的句子。

更合理的做法，是在上层再加一层短期工作记忆（也就是常说的 working memory）：

上层维护最近 N 轮对话，专门用来回答当前轮的问题；
只有当某个阶段性话题结束，或者检测到出现了明确的个人偏好、背景信息、长期目标时，才把这一段对话打包交给 mem0；
mem0 则专注于把这些内容收敛成一组长期事实，并在后续请求里持续维护和更新。

可以用一张概念图来表示这两层之间的关系：

image

在这种架构下，new_retrieved_facts 更像是从短期工作记忆里抽取出来、准备写入长期记忆的候选事实单元，而不是对所有问题的机械记录。

7.2 写入路径存在明显的写放大#

infer=True 这条分支天然带来写放大：一次写入包含两次 LLM 调用和至少一次向量检索。这在低 QPS 的场景下问题不大，但如果想在一个高并发系统里对所有对话都开推理写入，就需要认真评估成本和延迟。

这里可以结合代码简单算一下账：

第一次 LLM 调用发生在 get_fact_retrieval_messages，对整理后的整段对话做一次 fact 抽取；
抽出来的每个 fact 都要走一遍 embedding + VectorStore.search，这一步的复杂度和 fact 个数成正比；
第二次 LLM 调用发生在 get_update_memory_messages 之后，把新旧记忆一起喂给模型，让它产出 actions；
最后根据 actions 分别调用 _create_memory、_update_memory、_delete_memory，并同步写 history。

也就是说，一次 add(infer=True)，在最坏情况下会有：

一次对话级别的 LLM 请求；
N 次向量检索（N 是抽出的 fact 数量）；
再加一次新旧记忆对齐的 LLM 请求。

如果你是给单个用户做个人助理，这个开销未必夸张；但如果把 mem0 接在一个高并发入口（比如一个面向大量用户的客服系统）后面，就不太适合每条消息都同步走这条路径。

更现实的用法，是在应用层做两层区分：

在线链路只依赖短期上下文 + 既有长期记忆的 search，确保延迟可控；
把 add(infer=True) 放到后台队列里，按用户或会话做限流，比如每 N 轮对话或每隔一段时间才触发一次。

从这个角度看，mem0 更接近一个「长期记忆整理服务」，而不是写日志那一层。

7.3 记忆操作强依赖 LLM 的语义判断#

在 add(infer=True) 里，ADD / UPDATE / DELETE / NONE 的决策完全交给了 LLM。好处是接口非常简洁：调用者只需要给一段对话，不必自己写一堆 if/else 去判断是否重复、是否矛盾。

在代码层面，这部分逻辑主要集中在 get_update_memory_messages 和随后的第二次 llm.generate_response 上：

先把刚抽出来的 new facts 和刚刚检索到的旧记忆一起打包成一组 messages，喂给模型；
要求模型输出一个 JSON，里面列出每个新记忆对应哪个旧记忆、打算执行什么事件（event）、使用什么新文本；
后面执行分支里，只是严格按照这个 JSON 决策去走 _create_memory / _update_memory / _delete_memory，并且顺带写 history。

好处是调用方式非常统一：上层永远只调一个 add(infer=True)，所有「要不要记、记成什么样」的问题都丢给 LLM 来裁决。你甚至可以通过换 prompt 或换模型，试着调整它对重复、冲突的敏感程度。

代价则在于：

模型可能过度合并，把一些细节在 UPDATE 时压缩掉；
也可能不够激进，导致类似内容长期共存；
fact 的粒度完全由 prompt 和模型行为决定，目前实现里没有额外的 fact 级别约束机制，也没有在代码里做「防御性」检查，比如限定一次更新只能覆盖哪些字段。

这不是 mem0 独有的问题，所有 LLM 驱动的记忆系统都会遇到。mem0 的选择是把这部分逻辑集中到 add(infer=True) 的一条管线上，至少在工程上是透明的：你可以从 prompt、模型版本和 history 记录三个维度去观测和调参。

7.4 检索策略与上层架构#

前面提到，mem0 在 search 部分并没有引入很复杂的 GraphRAG 流程，而是保持了向量检索加可选 rerank、可选图检索的组合。这带来的一个结果是：

上下文的组织方式完全交给上层决定；
如果想要翻页拿前后文、多轮 search 逐步缩小范围，需要在 Agent 或业务代码里自己实现；
mem0 的职责止步于给你一批可能相关的记忆。

如果不考虑成本，只看怎么把上下文接得更顺，在 mem0 这一层之上大致有两条思路，可以和前面的 search 组合在一起。

第一种是给向量检索结果加一个“翻页”能力。比如拿到某条记忆后，再显式去取它前后若干条，类似现在很多代码 agent 里的 Read 工具，支持 offset / limit：

好处是实现简单，不需要额外的 Agent 结构，直接在应用侧包一层就行；
坏处是 LLM 一旦走偏，它在翻页过程中看到的一堆无关内容，都会被写进对话上下文里，后面的问题也会继续被这些错误上下文污染，很难「撤销」。

第二种是写一个专门的 search agent。主 Agent 不直接操纵翻页，而是把“我要找什么”丢给一个专门的检索 Sub Agent，让它负责在向量库里多次 search / 翻页，最后只把一小段结果（比如若干条记忆加上它自己的中间判断）返回：

好处是主 Agent 看到的是一份已经整理过的结果，过程中的「乱翻页」不会直接污染主对话的历史；
而且 search agent 可以用一个相对便宜的模型，反复调用也不至于太贵；
坏处是系统结构更复杂一些，需要你自己定义好主 Agent 和 search agent 之间的接口，以及错误时如何回退。

如果想把这条线再拉长一点，可以参考 kimi-cli 那种「给自己发 DMail」的做法（命运石之门梗，DenwaRenji 是啥梗？ || DenwaRenji What is the plot?，月之暗面真是个有意思的公司）：当你发现一次 search agent 的决策明显是错的时，不是硬着头皮把错上下文往后拖，而是显式给主 Agent 写一条更正消息，相当于在对话历史里打一个“撤销”标记，后面的推理就可以选择性地忽略这一段错误分支。这个思路用在 mem0 上，基本等价于在长期记忆之上再盖一层“可回滚”的检索历史，让系统有机会在犯错之后把自己从错误上下文里拉出来。

8. 总结#

整体来看，mem0 在把记忆这件事工程化上做了几件比较关键的事：

把 add 设计成一个具备决策能力的入口，在 infer=True 下通过两次 LLM 调用和一次向量检索，把 ADD / UPDATE / DELETE / NONE 合在一条管线里做完。
用一个独立的 SQLite history 表记录所有变更，把每条记忆视作一个可以审计的状态机，也可以说是一种血缘追踪，而不是简单的覆盖式更新。
通过Vector Factory 和 Graph Factory，把底层存储细节屏蔽在统一接口之后，让 Memory 层只关心“存什么、怎么搜”。事实上 mem0 的绝大部分代码都在适配十几种向量库和图数据库上。
在设计上明确区分了长期记忆和短期工作记忆的角色，前者交给 mem0，后者留给上层框架或应用代码。

不管怎么说，mem0 的源码是值得读一遍的，哪怕最后不直接使用这个库，它在接口设计、读写路径、历史记录这些细节上的处理，也是一份相对完整的参考实现，而且比较简单，读完可以根据自己的场景做一些增强。

对 COLMA 认知分层记忆架构的工程化重构与思考

Sun, 07 Dec 2025 03:57:01 GMT

对 COLMA 认知分层记忆架构的工程化重构与思考#

最近阅读了四川大学团队发表的论文《A Scenario-Driven Cognitive Approach to Next-Generation AI Memory》。论文通过脑科学的分析，指出了当前 AI 记忆系统（主要是 RAG 和向量数据库）存在的“静态性”与“割裂性”问题，并创新性地提出了一种基于认知场景驱动的 COLMA（Cognitive Layered Memory Architecture）架构。

先读论文#

现有的 AI 记忆系统通常被简化为“向量数据库 + 检索算法”的组合。这篇论文通过六维评估（包括动态更新、抗灾难性遗忘、多模态整合等）指出，这种架构本质上是静态的数据堆砌，缺乏人脑的动态适应性。为了突破这一瓶颈，作者没有直接堆砌技术栈，而是采用了反向工程的思路，从脑科学反思人类记忆的模式，并基于此推导出了下一代记忆系统的核心需求。

从脑科学看人类记忆#

论文认为，记忆不是单一的存储行为，而是根据不同任务高度动态化的过程：

场景一：毒蘑菇识别（感知与生存级反应）

image

当你由远及近观察一个蘑菇时，你的大脑在毫秒级内整合了颜色、形状（视觉）甚至质感（触觉）。一旦识别出“剧毒”特征，系统会立即触发预警并强行写入长期记忆。

但现有的多模态模型往往将视觉和文本分开存储，且缺乏这种“高优先级写入”的生存机制。因此记忆系统必须具备极低延迟的多模态感知接口和工作记忆集成能力，能够在感知到关键特征时迅速闭环。

场景二：日常回忆（动态重构机制）

image

当你试图回忆“上个月2号做了什么”时，你的大脑并没有直接播放一段录像。你首先会锚定时间（“那天是周几？”），检索碎片线索（“好像开了周会”），然后结合外部提示（查看手机照片）进行迭代式重构（Iterative Reconstruction）。如果发现逻辑不通，大脑会自我否决并重新检索。

而目前的 RAG 检索是一次性的 Key-Value 匹配，缺乏“检索-评估-再检索”的自我修正回路。记忆检索应当是一个生成式重建的过程，包含多轮次的自我验证与修补。

场景三：数学解题（Mathematical Problem-Solving Process）

image

在解决复杂数学题时，人脑通过“系统1”（直觉启发）快速寻找思路，同时利用“系统2”（规则分析）进行严密的逻辑推导。此过程中，工作记忆（Working Memory）负责暂存中间变量，前额叶皮层负责监控逻辑冲突。

但现有记忆缺乏对“中间推理状态”的维护，往往只存结果不存过程。记忆系统必须支持任务分解，并具备双系统验证机制，能够存储“推理链条”而非仅仅是静态知识。

场景四：历史知识更新（冲突消解与再巩固）

image

当新读到的传记（“拿破仑输于情报失误”）与你原本的记忆（“拿破仑输于固执”）发生冲突时，大脑不会简单地覆盖旧数据，而是进行逻辑验证和情感加权。大脑会激活“记忆再巩固”机制，决定是修正旧记忆，还是将新信息作为一个新的分支版本存储。

向量库难以处理这种事实冲突，往往导致检索时出现相互矛盾的信息。所以必须具备冲突检测和记忆再巩固机制，支持知识的动态进化。

COLMA#

基于上述需求，论文提出了 COLMA (Cognitive Layered Memory Architecture)：

image

Layer 1: 物理持久层 (Physical Persistence Layer)

使用 Apache Cassandra 或 HBase。不同于传统的关系型数据库，这一层利用分布式列式存储的高吞吐和 Schema-free 特性，为海量的多模态数据提供坚实的物理底座。它负责解决“存得下”和“写得快”的问题。

Layer 2: 知识分类层 (Knowledge Category Layer)

异构数据统一封装。这是一个融合层。它打破了技术栈的壁垒，将知识图谱（结构化关系）、向量数据库（非结构化语义）和常识库统一在一个层面进行管理。无论是文本、图像向量还是逻辑实体，在此层都被视为可被索引的知识对象，解决了多模态数据割裂的问题。

Layer 3: 协调层 (Coordination Layer)

这一层模拟海马体与新皮层的协同。这是架构的“大脑”。它负责管理短时记忆（Working Memory）、中时记忆和长时记忆之间的动态流转。正如海马体负责将短期经历固化为长期记忆，这一层决定了哪些信息值得被持久化，哪些应当被遗忘，实现了认知资源的优化配置。

Layer 4: 功能层 (Functionality Layer)

提供具体的认知操作接口。这一层向上层暴露了推理 (Reasoning)、回忆 (Recall)、联想 (Association)、预测 (Prediction) 和反思 (Reflection) 等高级能力。它让上层应用不再直接操作 CRUD 接口，而是调用类似“联想”这样的认知指令。

Layer 5: 用户场景层 (User Scenario Layer)

应用场景对接。最顶层，直接对接具体的应用需求（如智能助手、决策代理）。它将业务逻辑翻译为对下层认知功能的调用。

‍

个人碎碎念#

可惜的是这篇论文没有代码，但个人看下来理论到工程也存在一些盲点。

首先是协调层的逻辑贫血问题。论文将协调层定义为模拟海马体功能的模块，负责管理短时记忆向长时记忆的流转。在论文的描述中，这是一个优雅的漏斗，但在真实的工程实现中，如果仅依靠简单的阈值（如访问频率或语义相似度）来决定记忆的去留，这个漏斗很快就会堵塞。如果没有复杂的清洗逻辑，大量的无效对话和冗余信息会被永久写入底层存储，导致存储成本爆炸且检索信噪比下降。所以我认为这里还需要一个做记忆整理的操作。

其次是被动性，因为数据库本身不会思考。论文隐含的交互模型是标准的请求-响应模式：用户提问，系统检索并存储。这也是当前 AI 记忆系统的痛点：被动性。人类的记忆整理往往发生在睡眠或空闲时，是一个主动的后台过程，数据会随着时间推移逐渐混乱，最终变得非常混乱。一个类脑的记忆系统，应该有办法主动唤醒，对碎片化的记忆进行合并和重组。

最后是搜索状态问题。个人认为在复杂的认知任务中，功能之间存在严格的时序依赖和状态共享。例如，往往是先回忆事实，再进行逻辑推导，最后才进行反思修正。如果将它们拆解为无状态的接口，外部调用者就需要维护复杂的上下文状态。再比如说，如果针对同一个会话连续调用两次“反思”，第二次应当基于第一次的结果进行深化，而不是重头再来或者返回一样的结果。因此，功能层内部应该还需要维护认知任务的生命周期和中间状态。

‍

重构#

思考到上面的内容之后，我认为可以重新定义论文中说到的分层，特别是中间三层（持久层、分类层、协调层）的交互逻辑。

Layer 1: 物理持久层#

这一层其实没什么好讨论的，用 Cassandra 还是 HBase 其实是一个工程问题，不过最重要的洞见是它必须存原始数据（论文中也提到生态知觉理论，Ecological Perception Theory，核心思想是环境刺激的直接特征直接形成了初始的知觉表征），也就是作为事实的唯一来源。因为之前许多实践着重于将大模型的处理结果放到这一层，然而经常丢失一部分细节。至于索引那必然是要存的，否则性能很差，不过这个索引并不是语义索引，而是一个性能索引，这就是数据库的事情了，我们不在此详细讨论。

不过很容易想到一个问题，全部都是原始数据的话，上下文会变得特别长，且不符合我们认知的逻辑。起码我们知道，分层记忆是必然的（比如说目前主要包括短期、中期、长期记忆）。所以，处理是必须的，原始数据也是必须的，怎么办？

我想到一种方法是血缘追踪 (Data Lineage)。例如说某条记忆进行重组、合并、分裂、概括等等操作之后，需要保留一个血缘关系，即用一个 prev 指针去指向原来的数据，并将原来的数据标为 dirty（或者 archived），也就是不会作为数据被搜索到，只能溯源。如果上层使用这条操作后的数据之后发现它过于概括（Hallucination 的一种），可以直接溯源找到原始数据，以求真伪或更细节的认知。但时间久了这条链也会变得过长，所以这里面可能还需要引入一定的定期压缩或快照机制，但这属于更后期的优化了。

Layer 2: 知识分类层#

这一层在很多架构图中被画得花里胡哨，但如果剥离掉那些名词，在工程实现上它其实就是一个DAO层。

我不建议在这里做太多的“智能”处理。为什么？因为这一层的核心职责提供抽象原语。很多系统设计失败的原因，就是把业务逻辑下沉得太深，导致想改策略的时候改不动。所以我认为这一层应该做得“薄”一点，它只需要把底层那堆复杂的宽表、图数据库封装成大概几个简单的原子操作：

文字匹配搜索：最朴素的正则或关键词匹配，用于精确查找。
知识图谱遍历：给一个节点，查它的 N 跳邻居。
向量最近邻：给一个 Embedding，找 Top-K。
血缘溯源：这个在上面提到

这一层就是给上面的协调层递砖头的。它不需要知道“为什么要查这个”，它只需要保证“查得快、查得准”。把多模态的差异在这里抹平，对上层暴露统一的接口，这就足够了。

Layer 3: 协调层#

这是我认为整篇论文最关键、但也最需要工程填坑的地方。论文里说这一层负责“动态流转”，听起来很美，但在代码里怎么写？如果只是写几个 if (access_count < 5) move_to_long_term() 这样的阈值判断，那这个系统就太“薄”了，根本撑不起复杂的认知任务。

我认为协调层的本质不应该是简单的流转，而应该是记忆治理。目前的 AI Memory 系统最大的问题是“只进不出”和“被动响应”，时间一长，垃圾数据堆积如山。

所以，这一层必须具备类似 ETL 的能力，它需要主动地去做几件事：

同类合并：发现三条记忆都在说同一件事，就把它们由三个点合成一个点。
去冲突：新记忆说拿破仑高，旧记忆说拿破仑矮，这时候需要基于置信度去做冲突消解，而不是简单的覆盖。
垃圾回收：那些长期没用且与其他节点断连的孤立记忆，该清理就清理。包括上面说到的长链条血缘回溯。

谁来触发这些动作？肯定不能只靠用户请求。我觉得起码要有三种触发器：

事件触发：上一次操作发现数据脏了，异步写个任务到队列里，后台慢慢修。
时间触发：像人睡觉一样，系统闲的时候，Cron Job 起来扫一遍，把碎片化的记忆整理一下。
阈值触发：当检索失败率飙升或者幻觉严重时，强制触发一次深度整理。这里面就包括之前的链长，或者说这个类型应该叫“系统事件”。

Layer 4: 功能层#

到了这一层，其实就是面向大模型的硬封装了。论文里列了推理、回忆、联想、预测、反思这些功能，但在实际调用中，你不能指望外部调用者来维护这些功能之间的状态。

这里最容易被忽视的是序列关系。

比如，“先反思，再预测”。如果你直接调两次接口，第一次反思完了，第二次预测的时候，系统怎么知道你刚才反思了什么？难道要把反思的结果再传一遍？这太低效了。

所以这一层内部必须维护一个Session 级的状态机。

如果传入的是同一个 session_id，系统应该知道当前上下文已经走到了“反思完成”的状态。
这时候再调“预测”，它应该直接利用缓存中的反思结果，或者基于该状态继续推进。
如果我不想要上次的结果，我应该显式地开启新 Session。

这一层存在的意义，就是屏蔽掉下面那些复杂的血缘追踪、索引查询、ETL 治理，给大模型提供一个干净、有状态的认知接口。外部看起来是在调函数，内部其实是在跑一个复杂的认知工作流。

VMware 虚拟机性能优化：CPU Stuck 问题

Sat, 20 Sep 2025 16:59:19 GMT

VMware 虚拟机性能优化：CPU Stuck 问题#

1. 问题#

在 Windows 主机上通过 VMware Workstation Pro 运行 Linux 虚拟机时，即便物理机配置很高，有时也会遇到虚拟机内核报错：watchdog: BUG: soft lockup - CPU#X stuck for XXs!。

该问题通常表现为虚拟机卡顿，或导致 VS Code 远程 SSH 会话中断。

2. 原理：虚拟化架构冲突#

Type-1 Hypervisor (裸金属型)
直接安装在物理硬件上，操作系统（如 Windows）本身都运行在它之上。Windows 自带的 Hyper-V 就是典型的 Type-1。它会优先、且完全地控制 CPU 的硬件虚拟化扩展（AMD-V / Intel VT-x）。
Type-2 Hypervisor (托管型)
作为一款应用程序，安装在操作系统（如 Windows）之上。VMware Workstation 就是典型的 Type-2。在理想情况下，它需要直接访问 CPU 的硬件虚拟化扩展来实现高性能。

当 Windows 系统启用了 Hyper-V（或依赖它的功能，如 WSL2、虚拟机平台），Type-1 的 Hyper-V 就已经霸占了硬件控制权。这迫使 Type-2 的 VMware 降级到一种低性能的软件兼容模式（WHPX）运行，性能和稳定性都大打折扣，从而引发 CPU stuck 等问题。

3. 优化实践#

测试环境与命令：

物理机: Windows 11 Host, AMD R7 5800H, 64GB RAM, NVMe SSD
虚拟机: VMware Workstation Pro, Guest OS 为 Arch Linux (6核, 16GB RAM)
测试命令: sysbench cpu --cpu-max-prime=20000 --threads=6 run

步骤一：关闭 Hyper-V

解除 Hyper-V 对硬件的占用，让 VMware 能直接与硬件通信。

配置方法：
以管理员身份打开 CMD 或 PowerShell，执行以下命令，然后必须重启电脑。

Terminal window

1
bcdedit /set hypervisorlaunchtype off

效果验证：

测试项	Test 1 (Hyper-V 开启)	Test 2 (Hyper-V 关闭)	变化
CPU 速度 (events/sec)	6142.24	6809.48	+10.86%
最大延迟 (max latency)	41.12 ms	4.02 ms	-90.2%

步骤二：绑定专属核心

为虚拟机分配专属的 CPU 核心，消除宿主机其他进程的干扰。

配置方法：

分配核心：在 VMware Pro 中，关闭虚拟机，进入“设置”->“处理器”。将核心数设置为你希望分配的数量（例如，我的物理机有 16 个逻辑核心，我为虚拟机分配 12 个，为 Windows 保留 4 个）。
绑定亲和性：点击“亲和性”按钮，在弹窗中只勾选你想让虚拟机使用的物理 CPU 核心。例如，我只勾选了 CPU 4 到 CPU 15。
提升优先级 (可选) ：启动虚拟机后，在 Windows 任务管理器中找到 vmware-vmx.exe 进程，将其优先级设置为“高”或“实时”。

效果验证：

测试项	Test 2 (仅关闭Hyper-V)	Test 3 (亲和性+优先级)	变化
CPU 速度 (events/sec)	6809.48	10204.25	+49.85%

4. 最终结果#

关键指标	Test 1 (初始状态)	Test 3 (最终优化)	总提升
CPU 速度 (events/sec)	6142.24	10204.25	+66.13%

在绑定了专属核心后，CPU 性能再次暴涨近 50% ！这是因为虚拟机不再需要和宿主机进程争抢 CPU 时间片，并且极大地提高了 CPU 缓存命中率。

‍

K8s 持久化 Pod 控制台日志到节点本地：使用 Fluent Bit

Sat, 30 Aug 2025 20:21:11 GMT

K8s 持久化 Pod 控制台日志到节点本地：一个 Fluent Bit 实战指南#

动机#

在 Kubernetes 的日常使用中，我们通常会把日志接入云服务商或自建的中心化日志系统（如 ELK、Loki）。但在某些场景下，这并不是最佳选择，甚至不可行。

比如，你可能遇到了以下情况：

环境限制：无法将日志上报到外部网络，或者压根就不想依赖外部服务。
简单持久化需求：不需要复杂的搜索和分析，只希望 Pod 销毁后，日志能作为文件留在节点上，方便以后排查。
快速调试需求：在开发测试时，只想快速、直接地看到某个应用的日志，不想经过层层转发和复杂的平台。

针对这些需求，我们可以采用一个更直接的方案：在 K8s 集群里部署一个日志代理，精确抓取特定应用的控制台日志，并把它写入每个节点主机的特定目录下。

本文将通过一个完整的实战案例，介绍如何使用 Fluent Bit（一个轻量级、高性能的日志处理工具）作为 DaemonSet 来实现这个目标。

解决方案架构#

我们的方案由三个核心的 K8s 资源组成，它们协同工作，构成了一条完整的日志采集流水线：

RBAC 权限 (ServiceAccount, ClusterRole, ClusterRoleBinding)：这是“通行证”。Fluent Bit 需要权限查询 K8s API，以获取 Pod 的标签等元数据，否则它就无法分辨日志的来源。
ConfigMap (配置中心)：这是“大脑”。它包含了 Fluent Bit 的所有配置，告诉它该做什么、怎么做。我们在这里定义日志的输入、解析、过滤和输出规则。
DaemonSet (执行者)：这是“工人”。通过 DaemonSet，我们确保每个节点上都运行一个 Fluent Bit Pod，负责采集该节点上所有容器的日志。

原理#

为了让我们的 Fluent Bit 配置更加清晰，我们有必要了解一下 K8s 节点上日志文件的命名规范。当你 SSH 登录到任何一个 K8s 工作节点并查看 /var/log/containers/ 目录时，你会看到一系列遵循严格格式的文件。

这个目录存放着节点上所有容器日志的实际物理文件。

标准格式#

每个日志文件的名称都由几个部分拼接而成，格式如下：

1
<pod_name>_<namespace>_<container_name>-<container_id>.log

让我们来逐一拆解：

<pod_name>: 产生这条日志的 Pod 的完整名称。例如，my-app-7b5d8f9c6c-xyz。
<namespace>: 该 Pod所在的 Kubernetes 命名空间。例如，my-app-ns。
<container_name>: Pod 中产生日志的具体容器的名称。这对于一个 Pod 内有多个容器（例如，一个主应用容器和一个 sidecar 容器）的场景非常重要。
<container_id>: 由容器运行时（如 containerd 或 Docker）分配给该容器的一个唯一哈希值（ID）。这个 ID 确保了即使容器重启（Pod 不变，但容器实例是新的），日志文件也不会发生冲突。

举个例子#

假设我们有一个 Pod，信息如下：

Pod 名称: my-app-7b5d8f9c6c-xyz
命名空间: my-app-ns
容器名称: my-app-container

那么，它在节点上对应的日志文件名称就会是这样的： my-app-7b5d8f9c6c-xyz_my-app-ns_my-app-container-a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2.log

一个有用的快捷方式：`/var/log/pods` 目录#

除了 /var/log/containers/，你可能还会注意到一个名为 /var/log/pods/ 的目录。这个目录提供了一套更具可读性的符号链接（Symbolic Links），方便我们手动查找日志。

它的目录结构是这样的： /var/log/pods/<namespace>_<pod_name>_<pod_uid>/<container_name>/0.log

这里的 0.log 文件就是一个符号链接，它最终指向了 /var/log/containers/ 目录中对应的那个长长的、带有哈希值的实际日志文件。

理解了这个文件结构，我们 Fluent Bit 配置中的 Path /var/log/containers/*.log 就变得非常清晰了：它告诉 Fluent Bit 去监控这个目录下所有符合命名规范的日志文件，从而捕获节点上所有容器的输出。

完整配置清单#

要实现我们的目标，你需要将以下所有 K8s 资源清单整合到一个 YAML 文件中（例如 fluent-bit-daemonset.yaml）。

这个配置文件会创建一个 my-app-ns 命名空间，并部署所有需要的资源。它经过精心设计，能够：

监控节点上所有容器的控制台输出。
为每条日志附加其来源 Pod 的 K8s 标签。
只保留那些带有 app: my-app 标签的 Pod 的日志。
将这些日志的纯净、原始内容（不含任何 JSON 包装或时间戳前缀）写入到每个节点主机的 /var/log/my-app/app.log 文件中。

1
# --- 第 1 部分：RBAC 权限 ---
2
# Fluent Bit 需要从 K8s API 读取 Pod 和 Namespace 元数据的权限。
3
apiVersion: v1
4
kind: ServiceAccount
5
metadata:
6
  name: fluent-bit
7
  namespace: my-app-ns # 替换为你的目标命名空间
8
---
9
apiVersion: rbac.authorization.k8s.io/v1
10
kind: ClusterRole
11
metadata:
12
  name: fluent-bit-read
13
rules:
14
- apiGroups: [""]
15
  resources:
16
  - namespaces
17
  - pods
18
  verbs: ["get", "list", "watch"]
19
---
20
apiVersion: rbac.authorization.k8s.io/v1
21
kind: ClusterRoleBinding
22
metadata:
23
  name: fluent-bit-read
24
roleRef:
25
  apiGroup: rbac.authorization.k8s.io
26
  kind: ClusterRole
27
  name: fluent-bit-read
28
subjects:
29
- kind: ServiceAccount
30
  name: fluent-bit
31
  namespace: my-app-ns # 替换为你的目标命名空间
32
---
33
# --- 第 2 部分：FLUENT BIT 配置 ---
34
apiVersion: v1
35
kind: ConfigMap
36
metadata:
37
  name: fluent-bit-config
38
  namespace: my-app-ns # 替换为你的目标命名空间
39
  labels:
40
    k8s-app: fluent-bit
41
data:
42
  # 主配置文件
43
  fluent-bit.conf: |
44
    [SERVICE]
45
        Flush         5
46
        Log_Level     info
47
        Parsers_File  parsers.conf
48

49
    [INPUT]
50
        # 'tail' 插件是我们的输入源，用于监控文件内容
51
        Name              tail
52
        Tag               kube.*
53
        # 这是 K8s 节点上所有容器日志的标准路径
54
        Path              /var/log/containers/*.log
55
        # 使用下面定义的 'cri' 解析器来提取原始的日志消息
56
        Parser            cri
57
        # 一个数据库文件，用于记录已读取的日志位置，防止重启后重复采集
58
        DB                /var/fluent-bit/db/flb_kube.db
59
        Mem_Buf_Limit     5MB
60

61
    [FILTER]
62
        # 'kubernetes' 过滤器会用 K8s API 中的元数据来丰富日志记录
63
        Name                kubernetes
64
        Match               kube.*
65
        # 将解析出的日志消息合并回主记录中
66
        Merge_Log           On
67
        # 指定合并后日志消息所使用的键名
68
        Merge_Log_Key       log_processed
69

70
    [FILTER]
71
        # 'grep' 过滤器用于筛选来自特定应用的日志
72
        Name                grep
73
        Match               kube.*
74
        # 这是核心过滤逻辑：只保留 'app' 标签为 'my-app' 的日志
75
        Regex               $kubernetes['labels']['app'] ^my-app$ # 将 'my-app' 替换为你的应用标签值
76

77
    [OUTPUT]
78
        # 'file' 输出插件将日志写入文件
79
        Name          file
80
        Match         kube.*
81
        # 日志将被写入到宿主机的这个目录下
82
        Path          /host-logs/
83
        # 指定输出日志文件的名称
84
        File          app.log
85
        # 使用自定义模板来格式化输出
86
        Format        template
87
        Template      {log}
88

89
  # 解析器配置文件
90
  parsers.conf: |
91
    [PARSER]
92
        Name   cri
93
        Format regex
94
        # 这个正则表达式用于剥离容器运行时添加的时间戳和流信息（stdout/stderr），
95
        # 只捕获原始的日志内容并存入 'log' 字段。
96
        Regex  ^(?<time>[^ ]+) (?<stream>stdout|stderr) (?<logtag>[^ ]*) (?<log>.*)$
97
        Time_Key time
98
        Time_Format %Y-%m-%dT%H:%M:%S.%L%z
99
---
100
# --- 第 3 部分：DAEMONSET 部署 ---
101
# 这个 DaemonSet 确保集群中的每个节点上都运行一个 Fluent Bit Pod，
102
# 从而能够采集该节点上所有应用的日志。
103

104
apiVersion: apps/v1
105
kind: DaemonSet
106
metadata:
107
  name: fluent-bit
108
  namespace: my-app-ns # 替换为你的目标命名空间
109
  labels:
110
    k8s-app: fluent-bit
111
spec:
112
  selector:
113
    matchLabels:
114
      k8s-app: fluent-bit
115
  template:
116
    metadata:
117
      labels:
118
        k8s-app: fluent-bit
119
    spec:
120
      # 使用我们在第 1 部分中创建的 Service Account
121
      serviceAccountName: fluent-bit
122
      terminationGracePeriodSeconds: 10
123

124
      # 定义卷，用于将宿主机路径和 ConfigMap 挂载到 Pod 中
125
      volumes:
126
      # 用于从宿主机读取容器日志的卷
127
      - name: varlog
128
        hostPath:
129
          path: /var/log
130
      # 用于容器运行时状态的卷（某些运行时需要）
131
      - name: varlibdockercontainers
132
        hostPath:
133
          path: /var/lib/docker/containers
134
      # 用于将最终的日志文件写入宿主机的卷
135
      - name: host-log-output
136
        hostPath:
137
          path: /var/log/my-app # 替换为你期望的宿主机输出目录
138
          type: DirectoryOrCreate
139
      # 用于从 ConfigMap 挂载配置文件的卷
140
      - name: config
141
        configMap:
142
          name: fluent-bit-config
143
      # 用于在宿主机上存放 Fluent Bit 数据库文件的可写卷
144
      - name: fluent-bit-db
145
        hostPath:
146
          path: /var/lib/fluent-bit/
147
          type: DirectoryOrCreate
148

149
      # 定义 Fluent Bit 容器
150
      containers:
151
      - name: fluent-bit
152
        image: fluent/fluent-bit:latest
153
        # 将上面定义的卷挂载到容器的文件系统中
154
        volumeMounts:
155
        - name: varlog
156
          mountPath: /var/log
157
          readOnly: true
158
        - name: varlibdockercontainers
159
          mountPath: /var/lib/docker/containers
160
          readOnly: true
161
        - name: host-log-output
162
          mountPath: /host-logs
163
        - name: config
164
          mountPath: /fluent-bit/etc/
165
        - name: fluent-bit-db
166
          mountPath: /var/fluent-bit/db/

展开收起

部署与验证#

应用配置：将上面的配置保存为 fluent-bit-daemonset.yaml，然后执行：
Terminal window
```
1
kubectl apply -f fluent-bit-daemonset.yaml
```
检查 DaemonSet 状态：确认 Fluent Bit 的 Pod 已经在你的节点上成功运行。
Terminal window
```
1
kubectl get ds -n my-app-ns
2
# 期望输出中 DESIRED, CURRENT, READY 的数量应该一致
```
验证日志文件： SSH 登录到运行你目标应用 (my-app) 的任一节点，然后查看目标文件：
Terminal window
```
1
tail -f /var/log/my-app/app.log
```
此时，当你与 my-app 应用交互时，应该能在这里看到实时输出的原始日志行。

常见问题排查 (Troubleshooting)#

如果你发现日志文件为空，别慌，这很常见。我们可以按以下步骤排查：

确认源头有日志：你的应用真的在向控制台输出日志吗？我们可以绕过 Fluent Bit，直接用 kubectl 检查。
Terminal window
```
1
# 确保你的应用正在运行并处理流量
2
kubectl logs deployment/my-app -n my-app-ns -f
```
如果这里没输出，那问题就在你的应用本身，而不是日志采集。
确认标签完全匹配：我们的过滤规则依赖精确的标签。检查一下 Pod 是否真的拥有我们指定的标签。
Terminal window
```
1
kubectl get pods -n my-app-ns --show-labels
```
仔细核对 LABELS 列，确保目标 Pod 拥有 app: my-app。任何拼写错误都会导致过滤失败。
检查 Fluent Bit 自身日志：Fluent Bit Pod 在启动或运行时报错了吗？
Terminal window
```
1
kubectl logs -n my-app-ns -l k8s-app=fluent-bit -f
```
常见的错误包括权限不足（RBAC 问题）、配置文件语法错误或无法访问挂载目录。

总结与扩展#

通过上面的步骤，我们就成功构建了一个轻量级、高针对性的 K8s 日志持久化系统。它不依赖任何外部服务，将指定应用的控制台日志以最纯粹的形式保存在了节点本地，完美解决了特定场景下的日志采集需求。

这个方案的真正强大之处在于它的扩展性。通过简单修改 ConfigMap，你可以：

更改过滤规则：采集不同应用或整个命名空间的日志。
更改输出目标：将日志发送到 Elasticsearch、S3、Loki 或其他任何 Fluent Bit 支持的后端，轻松从本地持久化方案升级为中心化日志系统。

arch安装笔记

Thu, 07 Aug 2025 21:28:10 GMT

第一部分：安装流程日志#

1.1 预备操作及网络验证#

在虚拟机中通过 Arch Linux ISO 镜像启动后，进入 Live 环境。首要步骤是验证网络连通性，以确保后续软件包的下载。

Terminal window

1
# 测试与 Arch Linux 官方服务器的连通性
2
ping archlinux.org

确认收到 ICMP 回复后，网络验证通过。

1.2 磁盘分区方案定义与实施#

本节详述使用 cfdisk 交互式工具在目标磁盘 (/dev/sda) 上进行分区的具体操作步骤。本次安装遵循 GPT (GUID Partition Table) 分区方案。

首先，使用 lsblk 命令列出所有块设备，确认您要安装系统的目标磁盘。

Terminal window

1
# 检查磁盘列表和大小，确定目标磁盘符（例如 /dev/sda）
2
lsblk

警告：接下来的操作是破坏性的，请务必确认选择了正确的磁盘。本文档以 /dev/sda 为例。

首先，执行以下命令启动分区工具，并将其指向目标磁盘：

Terminal window

1
cfdisk /dev/sda

该命令将打开一个全屏的交互式界面。后续所有操作均在此界面中通过键盘完成。

选择分区表类型 (Label Type) 若目标磁盘为空盘或无有效分区表，cfdisk 会首先提示选择分区表类型。使用方向键选择 gpt，然后按 Enter 键确认。

创建分区 接下来，根据下表的规划逐一创建分区。在 cfdisk 界面中，通过方向键 ↑/↓ 选择磁盘上的 Free space，然后使用 ←/→ 键选择底部菜单项。

目标分区规划表:

分区设备	规划容量	分区类型	挂载点及用途
`/dev/sda1`	512 MiB	`EFI System`	`/boot/efi` (EFI 系统分区)
`/dev/sda2`	2.5 GiB	`Linux swap`	Swap (交换空间)
`/dev/sda3`	50 GiB	`Linux filesystem`	`/` (根文件系统)
`/dev/sda4`	47 GiB	`Linux filesystem`	预留给 ZFS，本次安装不使用

规划理由:

/dev/sda1 (EFI): 512 MiB 是 UEFI 规范推荐的最小尺寸之一，对于存放多个引导加载程序绰绰有余。
/dev/sda2 (Swap): 2.5 GiB 是基于本虚拟机计划运行的内存大小（例如 2 GiB）设定的，用于休眠或内存压力较大时的补充。
/dev/sda3 (Root): 50 GiB 为操作系统和常用软件提供了充足的空间。
- 创建 /dev/sda1 (EFI System Partition):
  1. 确保选中了磁盘开头的 Free space。
  2. 在底部菜单选择 [ New ] 并按 Enter。
  3. 当提示输入 Partition size 时，键入 512M 并按 Enter。
  4. 此时分区已创建，但类型不正确。在底部菜单选择 [ Type ] 并按 Enter。
  5. 在分区类型列表中，使用方向键找到并选中 EFI System，按 Enter 确认。
- 创建 /dev/sda2 (Linux Swap):
  1. 使用 ↓ 键选中 /dev/sda1 下方的 Free space。
  2. 选择 [ New ]，输入 2.5G 并按 Enter。
  3. 选择 [ Type ]，在列表中找到并选中 Linux swap，按 Enter 确认。
- 创建 /dev/sda3 (Root Filesystem):
  1. 选中剩余的 Free space。
  2. 选择 [ New ]，输入 50G 并按 Enter。
  3. 分区类型默认为 Linux filesystem，符合根分区的要求，无需更改。
- 创建 /dev/sda4 (ZFS Placeholder):
  1. 选中最后剩余的 Free space。
  2. 选择 [ New ]，直接按 Enter 键以使用所有剩余空间（应约为 47 GiB）。
  3. 分区类型同样默认为 Linux filesystem，符合要求。

写入更改并退出 分区规划完成后，界面顶部会显示新规划的分区表，但此时更改仅存在于内存中，尚未写入磁盘。
1. 在底部菜单中选择 [ Write ] 并按 Enter。
2. 程序会要求确认操作，这是最后防止误操作的机会。输入 yes 并按 Enter。
3. 待写入完成后，选择 [ Quit ] 并按 Enter，退出 cfdisk 工具。

完成上述步骤后，可以使用 lsblk 命令检查磁盘分区是否与规划一致，以确认操作成功。

1.3 文件系统格式化与挂载#

对已定义的分区进行格式化，并按照预定结构挂载至 Live 环境的 /mnt 目录。

文件系统创建:

Terminal window

1
# 格式化 EFI 系统分区为 FAT32
2
mkfs.fat -F32 /dev/sda1
3

4
# 初始化 Swap 分区
5
mkswap /dev/sda2
6

7
# 格式化根分区为 ext4
8
mkfs.ext4 /dev/sda3

文件系统挂载:

Terminal window

1
# 激活 Swap 分区
2
swapon /dev/sda2
3

4
# 挂载根分区至 /mnt
5
mount /dev/sda3 /mnt
6

7
# 创建并挂载 EFI 分区
8
mkdir -p /mnt/boot/efi
9
mount /dev/sda1 /mnt/boot/efi

1.4 基础系统安装#

使用 pacstrap 脚本将基础软件包及必要的工具集安装到目标根文件系统 (/mnt)。

Terminal window

1
pacstrap -K /mnt base linux linux-firmware vim networkmanager git sudo

-K 选项会使用 Live 环境的密钥环来初始化新系统的 pacman 密钥环

1.5 核心系统配置#

生成 fstab: 创建文件系统表，用于定义系统启动时的挂载规则。
Terminal window
```
1
genfstab -U /mnt >> /mnt/etc/fstab
```
切换根环境: 使用 arch-chroot 进入新安装的系统内部，以执行系统级别的配置。
Terminal window
```
1
arch-chroot /mnt
```
时区与本地化 (Chroot 环境内):
- 设置系统时区为 Asia/Shanghai。
- 编辑 /etc/locale.gen，启用 en_US.UTF-8 和 zh_CN.UTF-8。
- 执行 locale-gen 生成本地化信息。
- 在 /etc/locale.conf 中设定 LANG=en_US.UTF-8。
主机与网络配置 (Chroot 环境内):
- 在 /etc/hostname 中定义主机名为 arch-vm。
- 相应地更新 /etc/hosts 文件。
设置 Root 密码 (Chroot 环境内):
Terminal window
```
1
passwd
```
安装并配置引导加载程序 (Chroot 环境内):
- 安装 GRUB 及 UEFI 相关工具。
  Terminal window
```
1
pacman -S grub efibootmgr
```
- 执行 GRUB 安装，目标为 x86_64-efi 架构，EFI 目录为 /boot/efi。
  Terminal window
```
1
grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=GRUB
```
- 生成 GRUB 配置文件。
  Terminal window
```
1
grub-mkconfig -o /boot/grub/grub.cfg
```
创建管理员用户 (Chroot 环境内):
- 创建新用户 nolan 并将其加入 wheel 用户组，以备后续提权。
  Terminal window
```
1
useradd -m -G wheel nolan
```
- 为新用户 nolan 设置密码。
- 使用 visudo 编辑 sudoers 配置，解除对 %wheel 组的注释，授予其 sudo 权限。
启用网络服务 (Chroot 环境内):
Terminal window
```
1
systemctl enable NetworkManager
```

1.6 安装收尾与首次启动#

退出 chroot 环境 (exit)。
卸载所有已挂载的分区 (umount -R /mnt)。
重启系统 (reboot)。
在首次启动后，使用 nolan 用户登录，并安装 htop 软件包作为系统初步验证。
Terminal window
```
1
sudo pacman -Syu htop
```

安装流程至此结束。

第二部分：附录：关键技术概念解析#

2.1 磁盘分区方案：GPT 与 MBR#

磁盘分区方案是定义存储设备上分区布局的底层规范。GPT (GUID Partition Table) 是替换传统 MBR (Master Boot Record) 的现代标准。其主要优势在于：突破了 MBR 的 2TB 磁盘容量和 4 个主分区的限制；通过在磁盘两端存储分区表备份，显著提高了数据结构的冗余度和可靠性；原生支持 UEFI 启动模式。

2.2 固件接口与启动模式：UEFI 与 Legacy BIOS#

固件是嵌入在硬件设备中的低级别软件，负责在操作系统接管之前执行硬件初始化。UEFI (Unified Extensible Firmware Interface) 是取代传统 BIOS (Basic Input/Output System) 的现代固件接口规范。

与 BIOS 相比，UEFI 提供模块化设计、64 位寻址能力、图形化界面、网络功能和安全启动 (Secure Boot) 等高级特性。UEFI 规范规定，引导加载程序必须是存放于一个被称为 EFI 系统分区 (ESP) 内的 .efi 可执行文件。该分区必须采用 FAT 文件系统格式，以便固件能够识别和执行。

市面上有很多主板进入后显示图形化界面，用户界面可能标注为”BIOS设置”，但实际上这些现代主板都使用的是UEFI固件。这不应被简单理解为“BIOS加了个皮肤”。真正的区别在于底层架构：传统 BIOS 是一个中断驱动的、16位汇编代码的集合，而 UEFI 是一个更像微型操作系统的、可扩展的 C 语言平台。图形化界面、网络启动等高级功能都是这种现代架构带来的自然产物。

2.3 引导加载程序：GRUB#

引导加载程序 (Bootloader) 是一个在固件完成硬件初始化之后、操作系统内核启动之前的程序。它的核心职责是定位并加载操作系统内核到内存中，然后将执行控制权移交给内核。

GRUB (GRand Unified Bootloader) 是 Linux 生态系统中最常用的引导加载程序之一。在 UEFI 启动流程中，UEFI 固件负责从 ESP 分区加载并执行 GRUB 的 .efi 文件。随后，GRUB 接管控制权，凭借其识别 ext4 等复杂文件系统的能力，从根分区加载 Linux 内核 (vmlinuz-linux) 和初始内存盘 (initramfs-linux.img)，最终启动操作系统。

2.4 根环境切换工具：`arch-chroot`#

chroot (Change Root) 是一项允许进程将其根目录临时更改为文件系统中某个指定目录的操作。在 Arch Linux 安装过程中，此操作是必需的，因为它允许我们在新安装的系统能够独立启动之前，进入其内部环境执行配置命令。

arch-chroot 是 Arch Linux 提供的 chroot 封装脚本。相较于标准 chroot 命令，它额外执行了关键的准备工作，包括：

挂载 API 文件系统：自动将 Live 环境的 /proc、/sys、/dev 等内核接口文件系统挂载到新的根环境中，确保系统工具（如 pacman, grub-install）能够正常工作。
复制 DNS 配置：自动将 Live 环境的 /etc/resolv.conf 复制到新根环境中，保证在 chroot 状态下依然具备网络域名解析能力。

从面试题开始的Golang map

Sat, 28 Jun 2025 11:52:02 GMT

从面试题开始的Golang map#

问题：假设有一个golang的 map[int64]int64 存储了10亿（可以认为是）个用户的信息，key是用户的user id（唯一），估算至少需要多少内存？如果value无意义，退化为集合类型，又可以有什么优化？

理论最小值的估算非常简单，即16GB。但这个 16GB 只是纯粹的数据大小，完全忽略了 Go 为了实现 map 这个高效的哈希表结构而引入的巨大开销（Overhead）。

golang map的真实内存#

要精确计算，我们必须先了解 Go map 的底层结构。其核心是 hmap 和 bmap 两个结构体（源码位于 runtime/map.go）。

1
// A header for a Go map.
2
type hmap struct {
3
    count     int    // map中的元素个数，即 len()
4
    flags     uint8
5
    B         uint8  // buckets 数量的对数，即 buckets 数组的长度 = 2^B
6
    noverflow uint16 // 溢出桶的大约数量
7
    hash0     uint32 // 哈希种子
8

9
    buckets    unsafe.Pointer // 指向 bucket 数组的指针，数组大小为 2^B
10
    oldbuckets unsafe.Pointer // 扩容时，指向旧的 bucket 数组
11
    nevacuate  uintptr        // 扩容进度计数器
12

13
    extra *mapextra // 指向溢出桶等额外信息
14
}
15

16
// A bucket for a Go map.
17
type bmap struct {
18
    // tophash 存储了每个 key 哈希值的高8位
19
    // 用于在 bucket 中快速筛选，避免逐一比较 key
20
    tophash [8]uint8
21
    // tophash 后面紧跟着 8 个 key 和 8 个 value
22
    // keys    [8]keytype
23
    // values  [8]valuetype
24
    // ...
25
    overflow uintptr // 指向下一个溢出桶
26
}

展开收起

map 的核心是一个 bucket 数组。
每个 bucket 通常可以存放 8 个 键值对。
为了保证查询效率，当 map 的负载因子（Load Factor） 超过 6.5 时，就会触发扩容。负载因子即 map元素总数 / bucket总数。

现在，我们可以根据数据结构计算存储 10 亿个元素所需的内存。

Bucket 数量

根据负载因子 6.5，我们需要的最小 Bucket 数为：
Buckets=6.5109 个元素≈153,846,154
由于 Bucket 数量必须是 2 的幂（2B），我们需要找到大于该值的最小 2 的幂。
- 227=134,217,728 (不够)
- 228=268,435,456 (足够)
因此，Go 运行时会为这个 map 分配 228 个 Bucket。

计算各部分内存占用

map 的总内存由 Keys、Values 和结构开销三部分组成。由于 map 预分配了 228 个 bucket，每个 bucket 有 8 个槽位，所以总槽位数为。

存储 Keys 的总空间:
2.147×109 个槽位×8 字节/key≈17.18×109 字节≈16.0 GB
存储 Values 的总空间:
2.147×109 个槽位×8 字节/value≈17.18×109 字节≈16.0 GB
结构开销:
- tophash: 每个槽位 1 字节。
  2.147×109 个槽位×1 字节≈2.15×109 字节≈2.0 GB
- 溢出指针 (overflow pointers): 每个 Bucket 1 个指针（64位系统占8字节）。
  228 个 buckets×8 字节/指针≈2.15×109 字节≈2.0 GB

‍

将以上各项相加：

结论：一个存储 10 亿 int64:int64 的 map，实际需要 36GB 的内存，是理论最小值的 2.5 倍以上。

如果改成集合呢？#

在很多场景中，我们只关心 Key 是否存在，而 Value 本身没有意义，比如用 map 来去重。这时，问题就从一个键值映射（Map）退化成了一个集合（Set） 。

map[int64]struct{}#

你可能会想用 map[int64]bool，但这是一个陷阱。bool 类型虽只占 1 字节，但因内存对齐，在 map 的 bucket 中仍会占据 8 字节的槽位，几乎没有优化效果。正确的姿势是使用空结构体 struct{}。

采用这种方法后，我们之前计算中的 Values 部分（16.0 GB）的开销就直接消失了。

总内存

更优解：bitmap#

其实我们还有一个条件没用到，即key是int64类型，并非普通的哈希表key，那么对于“整数集合”这个特定的问题，存在一种效率极高的数据结构——位图（Bitmap） 。其原理非常简单：用一个 bit 的状态（0 或 1）来表示一个整数是否存在。

如果使用 bitmap，则内存为：

但 bitmap 的问题是，如果user id分布不均衡，或者非常稀疏，在 int64 空间下需要分配非常大的内存：

Roaring Bitmap#

为了解决传统位图的稀疏数据难题，Roaring Bitmap 横空出世。它是一种高度优化的压缩位图，专门为高效存储大量整数集合而设计，早已成为许多大数据框架（如 Spark, Druid）的内置组件。

Roaring Bitmap 将整数空间按高16位和低16位分成不同的chunk块，每个chunk存储个整数。

根据chunk的稀疏程度：

如果整数非常稀疏，就用一个有序数组存储
如果整数非常密集，则使用bitmap

扩展阅读：Consistently faster and smaller compressed bitmaps with Roaring

golang Roaring Bitmap实现：roaring

‍

Python 更新记录

Sun, 01 Jun 2025 18:44:16 GMT

Python 各版本重大更新#

Python 发布策略#

Python的版本采用年度更新策略，每年十月发布新版本，如3.10版本在2020年10月5日发布，3.11版本在2021年10月4日发布。本文旨在记录各重大特性的变更记录，方便使用新特性时参考版本。

python 3.9 2020年10月5日#

字典合并(PEP 584)

1
d1 = {"a": 1, "b": 2}
2
d2 = {"b": 3, "c": 4}
3
merged = d1 | d2  # {'a': 1, 'b': 3, 'c': 4}
4
d1 |= d2          # d1 = {'a': 1, 'b': 3, 'c': 4}

str.removeprefix() 和 str.removesuffix()(PEP 616)

1
s = "hello world"
2
s.removeprefix("hello")  # " world"
3
s.removesuffix("world")  # "hello "

集合泛型(PEP 585)

1
# old
2
import typing.List
3

4
def func(s: typing.List[int]):
5
    pass
6

7
# new
8
def func(s: list[int]):
9
    pass

再也不需要导入typing.List了，直接使用list[int]即可。

PEG解析器(PEP 617) 语法上无影响，主要影响解析器的实现，为后续的一些语法提供支撑。
zoneinfo(PEP 615) 和graphlib

1
import zoneinfo
2

3
tz = zoneinfo.ZoneInfo("Asia/Shanghai")

方便了对时区（包括夏令时）的处理。

graphlib主要增加了TopologicalSorter，用于拓扑排序。

性能优化 Vectorcall 协议(PEP 590)使用范围扩大，范围扩大到range、tuple、set、frozenset、list、dict的调用。

优化了多线程信号处理机制。

提高短ASCII字符串的性能。

python 3.10 2021年10月4日#

结构化模式匹配 (PEP 634, 635, 636): 引入match和case语句，用于模式匹配。

1
def http_error(status):
2
    match status:
3
        case 400:
4
            return "Bad request"
5
        case 404:
6
            return "Not found"
7
        case 418:
8
            return "I'm a teapot"
9
        case _:
10
            return "Something's wrong with the internet"

1
case 401 | 403 | 404:
2
    return "Not allowed"

括号上下文

1
with (
2
    open("file1.txt") as f1,
3
    open("file2.txt") as f2
4
):
5
    # do with f1, f2

使用”|“定义联合类型而不是typing.Union(PEP 604)

1
# old
2
def func(x: typing.Union[int, str]):
3
    pass
4

5
# new
6
def func(x: int | str):
7
    pass

C API int 类型新增了 int.bit_count() 方法。

zip() 函数新增了一个 strict 标志 (PEP 618)，用于强制所有可迭代对象的长度相等。

新增了两个内置函数 aiter() 和 anext()，用于异步迭代。

@staticmethod 和 @classmethod 装饰器得到改进，现在可以继承方法属性并拥有一个新的 wrapped 属性。

新增了 inspect.get_annotations() 函数，用于安全地计算注解，包括对字符串化注解进行反字符串化。

ssl 模块现在要求 OpenSSL 1.1.1 或更新版本，并具有更安全的默认设置。

python 3.11 2022年10月24日#

性能提升
- 与 3.10 相比平均提升 25%（部分场景提升 10-60%）
- 更快的启动速度：通过”冻结导入”实现
- 专门化自适应解释器：运行时识别热点代码，用更快的版本替换通用字节码
- 更廉价、惰性的 Python 帧
- 内联 Python 函数调用
异常处理增强
- 细粒度错误定位 (PEP 657)

1
# 现在错误信息会精确指向问题表达式
2
# 例如：TypeError: unsupported operand type(s) for +: 'int' and 'str'
3
# 错误位置会用 ~^~~ 标记

异常组 (PEP 654)

1
try:
2
    raise ExceptionGroup("多个错误", [
3
        ValueError("值错误"),
4
        TypeError("类型错误")
5
    ])
6
except* ValueError:
7
    print("处理值错误")
8
except* TypeError:
9
    print("处理类型错误")

异常注解 (PEP 678)

1
try:
2
    raise ValueError("原始错误")
3
except ValueError as e:
4
    e.add_note("这是额外的上下文信息")
5
    raise

类型系统增强
- 可变参数泛型 (PEP 646)

1
from typing import TypeVarTuple, TypeVar
2

3
Shape = TypeVarTuple('Shape')
4
T = TypeVar('T')
5

6
class Array(Generic[T, *Shape]):
7
    pass

TypedDict 增强 (PEP 655)

1
from typing import TypedDict, Required, NotRequired
2

3
class Movie(TypedDict):
4
    title: Required[str]
5
    year: Required[int]
6
    rating: NotRequired[float]

Self 类型 (PEP 673)

1
from typing import Self
2

3
class Shape:
4
    def set_scale(self, scale: float) -> Self:
5
        self.scale = scale
6
        return self

标准库更新
- tomllib 模块 (PEP 680)：用于解析 TOML 文件
- asyncio 新增 TaskGroup
- enum 模块增强：新增 StrEnum、ReprEnum 和 EnumType
- re 模块支持原子组和所有格量词

python 3.12 2023年10月2日#

类型系统增强
- 类型参数语法 (PEP 695)

1
# 新的类型别名语法
2
type Point = tuple[float, float]
3

4
# 新的泛型类语法
5
class Vector[T]:
6
    def __init__(self, x: T, y: T):
7
        self.x = x
8
        self.y = y
9

10
# 新的泛型函数语法
11
def first[T](items: list[T]) -> T:
12
    return items[0]

TypedDict 增强 (PEP 692)

1
from typing import TypedDict, Unpack
2

3
class Options(TypedDict):
4
    timeout: int
5
    retries: int
6

7
def process(**options: Unpack[Options]):
8
    pass

@typing.override 装饰器 (PEP 698)

1
from typing import override
2

3
class Parent:
4
    def method(self) -> None:
5
        pass
6

7
class Child(Parent):
8
    @override
9
    def method(self) -> None:
10
        pass

语法增强
- f-string 语法规范化 (PEP 701)

1
# 支持多行表达式
2
f"""
3
{{
4
    'name': 'Alice',
5
    'age': 30
6
}}
7
"""
8

9
# 支持注释
10
f"Value: {value  # 这是一个注释}"
11

12
# 支持任意嵌套
13
f"{f"{f"{value}"}"}"

推导式内联 (PEP 709)

1
# 性能提升的列表推导式
2
squares = [x * x for x in range(1000)]

并发与性能
- 每个解释器独立的 GIL (PEP 684)
- 低影响监控 API (PEP 669)
- 缓冲协议可访问性 (PEP 688)

1
from collections.abc import Buffer
2

3
class MyBuffer:
4
    def __buffer__(self, flags: int) -> Buffer:
5
        # 实现缓冲区协议
6
        pass

标准库更新
- itertools.batched() 新增

1
from itertools import batched
2

3
# 将元素分组为大小为3的元组
4
for batch in batched(range(10), 3):
5
    print(batch)  # (0, 1, 2), (3, 4, 5), (6, 7, 8), (9,)

pathlib.Path 增强

1
from pathlib import Path
2

3
class CustomPath(Path):
4
    def custom_method(self):
5
        pass
6

7
# 新增 walk() 方法
8
for root, dirs, files in Path(".").walk():
9
    pass

sqlite3 模块增强

1
import sqlite3
2

3
# 自动提交模式
4
conn = sqlite3.connect(":memory:", autocommit=True)

错误信息改进
- NameError 提供更智能的建议
- ImportError 提供更精确的导入建议
- 改进的语法错误提示
性能优化
- 推导式执行速度提升（最高2倍）
- re.sub() 和 re.subn() 性能提升（2-3倍）
- asyncio.Task 创建速度提升
- tokenize 模块性能提升（最高64%）
弃用与移除
- 计划在 3.13 中移除的模块：aifc、cgi、crypt 等
- lib2to3 和 2to3 程序被弃用
- 移除 asynchat 和 asyncore 模块
- 移除 distutils 包

python 3.13 2024年10月7日#

交互式解释器 (REPL) 增强
- 基于 PyPy 代码的新 REPL
- 多行编辑支持
- 彩色提示符和回溯信息
- 交互式帮助 (F1)
- 历史记录浏览 (F2)
- 粘贴模式 (F3)
- 直接 REPL 命令支持

1
# 示例：新的 REPL 特性
2
>>> help  # 显示帮助信息
3
>>> exit  # 退出解释器
4
>>> # 支持多行编辑
5
... def hello():
6
...     print("Hello, World!")

错误信息改进
- 彩色回溯信息（可通过环境变量控制）
- 更智能的模块冲突提示
- 关键字参数建议

1
# 示例：改进的错误提示
2
def greet(name, age):
3
    pass
4

5
# 旧版本
6
greet(nam="Alice")  # TypeError: greet() got an unexpected keyword argument 'nam'
7

8
# 新版本
9
greet(nam="Alice")  # TypeError: greet() got an unexpected keyword argument 'nam'. Did you mean 'name'?

实验性特性
- 自由线程 CPython (PEP 703)

1
# 需要特殊构建和运行时标志
2
# 编译时：--enable-free-threading
3
# 运行时：PYTHON_GIL=0 或 -X gil=0
4

5
import threading
6

7
def worker():
8
    # 现在可以真正并行执行
9
    pass
10

11
threads = [threading.Thread(target=worker) for _ in range(4)]
12
for t in threads:
13
    t.start()

即时编译器 (JIT) (PEP 744)

1
# 需要特殊构建和运行时标志
2
# 编译时：--enable-experimental-jit
3
# 运行时：PYTHON_JIT=1
4

5
# JIT 会自动优化热点代码
6
def compute():
7
    result = 0
8
    for i in range(1000000):
9
        result += i
10
    return result

语言特性
- locals() 确定性突变语义 (PEP 667)

1
def example():
2
    x = 1
3
    local_vars = locals()
4
    local_vars['x'] = 2  # 不会影响实际的 x
5
    print(x)  # 输出: 1
6

7
    # 使用 f_locals 进行可靠更新
8
    import sys
9
    frame = sys._getframe()
10
    frame.f_locals['x'] = 2  # 会更新 x
11
    print(x)  # 输出: 2

标准库更新
- argparse 支持弃用选项

1
import argparse
2

3
parser = argparse.ArgumentParser()
4
parser.add_argument('--old-option',
5
                   help='Deprecated. Use --new-option instead.',
6
                   deprecated=True)

base64 模块增强

1
import base64
2

3
# 新增 Z85 编码支持
4
data = b"Hello, World!"
5
encoded = base64.z85encode(data)
6
decoded = base64.z85decode(encoded)

性能优化
- 标准库模块导入时间优化
- textwrap.indent() 性能提升（约30%）
- subprocess 模块优化
移除内容
- 完成 PEP 594 “死电池”移除
  - aifc
  - cgi
  - crypt
  - nntplib
  - telnetlib 等19个模块
- 移除 2to3 工具和 lib2to3 模块
- 移除 tkinter.tix 模块
- 移除 locale.resetlocale() 函数
- 移除 typing.io 和 typing.re 命名空间
- 移除链式 classmethod 描述符支持
移动平台支持
- 新增 iOS 和 Android 的 Tier 3 级别支持

证书签发与自签名证书

Sat, 19 Apr 2025 16:15:50 GMT

证书签发与自签名证书#

密钥生成#

1
一般是ssh/github/WireGuard使用，生成一对公私钥

Terminal window

1
ssh-keygen -t [rsa/ecdsa/ed25519] -f [path] -C "comment"

1
目前RSA不建议使用，又长还不安全，建议使用ed25519,

‍

证书生成#

几个概念和文件解释#

文件
1. .key: 证书对应的私钥文件
2. .crt: CA认证后的文件，即证书
3. .csr: 证书签名请求, 用私钥签名得到的文件
4. .crl: 证书吊销列表
5. .pem; 导出导入证书用的格式, .crt+.key, 使用base64存储
根证书和用户证书: 根证书是信任链顶级, 用户证书是根证书签发的

对于自签证书, 只要根证书是有效的(安装在电脑上), 则由它签发的用户证书就是可信的
.x509: 证书格式标准

生成证书有两种, 自签名和CA签发, 只有CA签发的才有https锁标志, 但是加密功能来说两者等效

自签名证书#

1
下面讲解如何生成自己的证书

根证书生成#

1
首先需要一个根证书，我们自己就是CA

Terminal window

1
mkdir -p ./myca/{certs,crl,newcerts,private}
2
cd myca
3
touch index.txt
4
echo 1000 > serial
5
chmod 700 private

1
目录应该是这样的

Terminal window

1
.
2
├── certs # 证书位置
3
├── crl # 吊销列表
4
├── index.txt # 证书目录
5
├── newcerts # 新证书
6
├── private # 私钥
7
└── serial # 自增的index

准备OpenSSL文件(openssl.cnf)

1
[ ca ]
2
default_ca = CA_default
3

4
[ CA_default ]
5
dir               = /home/nolan/code/myca  # CA 根目录
6
certs             = $dir/certs
7
new_certs_dir     = $dir/newcerts
8
database          = $dir/index.txt
9
serial            = $dir/serial
10
private_key       = $dir/private/ca.key.pem
11
certificate       = $dir/certs/ca.cert.pem
12
default_md        = sha256
13
policy            = policy_loose
14
default_days      = 3650
15
x509_extensions   = v3_ca
16

17
[ policy_loose ]
18
# policy设置
19
# optional指后面的CSR可以不写，supplied需要写
20
# match是必须写且值必须和CA的相同
21
countryName            = optional
22
stateOrProvinceName    = optional
23
organizationName       = optional
24
commonName             = supplied
25

26
[ req ]
27
prompt             = no # 设置为No直接使用下面的默认值，否则交互式询问
28
default_bits        = 4096 # RSA有效，ED25519是没用的
29
distinguished_name  = req_distinguished_name
30
string_mask         = utf8only
31

32
[ req_distinguished_name ]
33
# 证书主题默认值
34
C           = CN # Country Name
35
ST          = Hubei # State or Province Name
36
L           = WuHan # Locality Name
37
O           = Apeiria # Organization Name
38
CN          = Apeiria # Common Name
39

40
[ v3_ca ]
41
# CA:TRUE=CA标识，critical=客户端验证时，不认识就直接拒绝
42
basicConstraints = critical, CA:TRUE
43
# 用途，keyCertSign/cRLSign=签发下级证书/吊销列表，critical=拒绝其他用途
44
keyUsage         = critical, keyCertSign, cRLSign
45
# Subject Key Identifier 扩展，快速找到上级证书
46
subjectKeyIdentifier = hash

展开收起

生成根CA私钥

Terminal window

1
# 签发证书
2
openssl genrsa -out private/ca.key.pem 4096
3
# 用ED25519，上面默认RSA
4
openssl genpkey -algorithm Ed25519 -out private/ca.key.pem
5
chmod 400 private/ca.key.pem

签发根 CA 证书

Terminal window

1
openssl req -config openssl.cnf \
2
  -key private/ca.key.pem \
3
  -new -x509 -days 3650 -sha256 \
4
  -extensions v3_ca \
5
  -out certs/ca.cert.pem
6
chmod 444 certs/ca.cert.pem

验证

Terminal window

1
openssl x509 -in certs/ca.cert.pem -noout -text

1
结果

Terminal window展开收起

1
Certificate:
2
    Data:
3
        Version: 3 (0x2)
4
        Serial Number:
5
            18:09:35:aa:82:e4:6a:e4:8d:d2:35:5d:f2:51:49:83:55:84:5e:e1
6
        Signature Algorithm: ED25519
7
        Issuer: C=CN, ST=Hubei, L=WuHan, O=Apeiria, CN=Apeiria
8
        Validity
9
            Not Before: Apr 19 08:41:35 2025 GMT
10
            Not After : Apr 17 08:41:35 2035 GMT
11
        Subject: C=CN, ST=Hubei, L=WuHan, O=Apeiria, CN=Apeiria
12
        Subject Public Key Info:
13
            Public Key Algorithm: ED25519
14
                ED25519 Public-Key:
15
                pub:
16
                    e5:ac:18:8f:81:7c:d9:e4:59:8d:a3:b0:79:8d:70:
17
                    fb:04:c2:4f:27:7b:34:3c:6b:a6:15:c0:a5:29:46:
18
                    ab:97
19
        X509v3 extensions:
20
            X509v3 Basic Constraints: critical
21
                CA:TRUE
22
            X509v3 Key Usage: critical
23
                Certificate Sign, CRL Sign
24
            X509v3 Subject Key Identifier:
25
                DE:05:5A:55:8B:F6:63:FD:C7:0F:EC:BE:70:7C:55:9E:8A:84:92:1E
26
    Signature Algorithm: ED25519
27
    Signature Value:
28
        57:ba:4b:ba:3d:ea:fa:0d:e1:cf:cc:74:e0:03:9b:f4:94:56:
29
        24:dc:f7:e5:d4:3e:47:21:b5:df:e4:8c:e1:c1:2f:84:46:fc:
30
        4a:90:60:e2:df:77:97:0f:e4:2c:c0:60:92:32:d6:69:0d:40:
31
        fb:14:cb:39:f9:81:7d:cd:aa:08

展开收起

1
最终我们得到了

Terminal window

1
.
2
├── certs
3
│   └── ca.cert.pem # CA证书
4
├── crl
5
├── index.txt
6
├── newcerts
7
├── openssl.cnf
8
├── private
9
│   └── ca.key.pem # CA私钥
10
└── serial

‍

用户证书签发#

1
上面已经有了 CA 和私钥，下面讲解如何签发自己的证书
2

3
生成用户的私钥，其实和CA生成私钥是一样的，私钥并不分是否是CA
4

5
总之需要一个私钥

Terminal window

1
openssl genpkey -algorithm Ed25519 -out nolan.key.pem
2
chmod 400 nolan.key.pem

1
生成CSR，也就是提交给CA的证书签名请求，通过私钥获取到证书

Terminal window

1
openssl req -new -key nolan.key.pem -out nolan.csr.pem

1
这一步需要调整`openssl.cnf`,末尾添加 user_crt 相关配置

1
[ usr_cert ]
2
# 普通用户证书，非 CA
3
basicConstraints        = critical, CA:FALSE
4
# 标识这个证书用作客户端认证
5
keyUsage                = critical, digitalSignature, keyEncipherment
6
extendedKeyUsage        = clientAuth
7
subjectKeyIdentifier    = hash
8
authorityKeyIdentifier  = keyid,issuer

签发证书

Terminal window

1
# -extensions usr_cert 就指定了刚刚的配置
2
openssl ca -config openssl.cnf \
3
  -extensions usr_cert \
4
  -days 3650 \
5
  -notext \
6
  -md sha256 \
7
  -in nolan.csr.pem \
8
  -out certs/nolan.cert.pem

验证

Terminal window

1
openssl x509 -in certs/nolan.cert.pem -noout -text

1
结果

Terminal window展开收起

1
Certificate:
2
    Data:
3
        Version: 3 (0x2)
4
        Serial Number: 4096 (0x1000)
5
        Signature Algorithm: ED25519
6
        Issuer: C=CN, ST=Hubei, L=WuHan, O=Apeiria, CN=Apeiria
7
        Validity
8
            Not Before: Apr 19 09:01:42 2025 GMT
9
            Not After : Apr 17 09:01:42 2035 GMT
10
        Subject: C=CN, ST=Hubei, O=Apeiria, CN=Apeiria
11
        Subject Public Key Info:
12
            Public Key Algorithm: ED25519
13
                ED25519 Public-Key:
14
                pub:
15
                    03:cb:ee:2b:b6:62:0d:4f:86:6b:37:45:f1:c0:ad:
16
                    c8:af:1a:0c:01:5e:6b:ab:c7:a1:ee:5a:46:87:38:
17
                    6b:dc
18
        X509v3 extensions:
19
            X509v3 Basic Constraints: critical
20
                CA:FALSE
21
            X509v3 Key Usage: critical
22
                Digital Signature, Key Encipherment
23
            X509v3 Extended Key Usage:
24
                TLS Web Client Authentication
25
            X509v3 Subject Key Identifier:
26
                DD:0B:04:82:65:DA:6E:76:7A:50:39:AC:C5:E9:9B:9B:35:3F:CC:84
27
            X509v3 Authority Key Identifier:
28
                DE:05:5A:55:8B:F6:63:FD:C7:0F:EC:BE:70:7C:55:9E:8A:84:92:1E
29
    Signature Algorithm: ED25519
30
    Signature Value:
31
        af:6b:79:2b:a4:fb:c3:84:33:9d:9a:3a:02:1a:df:c4:70:ac:
32
        8d:7b:42:bf:e3:b3:63:98:f7:12:db:83:89:b2:0c:3b:c8:7e:
33
        ad:e3:e5:25:00:e3:c7:fb:af:1b:67:70:0c:af:47:3e:39:13:
34
        6e:66:5e:11:c3:6b:3a:c8:95:05

展开收起

‍

Let’s Encrypt 申请#

certbot方法#

Terminal window

1
# 安装certbot ACME
2
sudo apt-get install certbot
3

4
# 验证域名所有权, 并获取证书, 不过需要确保80和443没有占用
5
sudo certbot certonly --standalone

Let’s Encrypt证书有效期一般只有90天, 需要续订

certbot一般会自动设置定时任务自动续订证书, 也可以用下面的命令测试

Terminal window

1
sudo certbot renew --dry-run # 查看续订（dry-run）

‍

OpenSSL常用命令#

解析 pem 证书

Terminal window

1
openssl x509 -in cert.pem -noout -text

验证证书链

Terminal window

1
openssl verify -CAfile ca-chain.pem cert.pem

检查服务器证书

Terminal window

1
openssl s_client -connect axi.moe:443 \
2
  -servername axi.moe -showcerts </dev/null \
3
  2>/dev/null | openssl x509 -noout -text

DEBUG 用，Serve AS TLS

Terminal window

1
openssl s_server -key key.pem -cert cert.pem -accept 8443

k3s 安装笔记

Thu, 17 Apr 2025 00:01:08 GMT

k3s 安装笔记#

k3s 是轻量级单节点集群，当然也可以加入多节点。

集群引导#

单master节点#

Terminal window

1
curl -sfL https://get.k3s.io | sh -
2

3
# 中国区加速
4
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

运行完就安装完成了，需要保证 6443 和 443 端口可用。

安装完，集群默认配置文件在/etc/rancher/k3s/k3s.yaml，如果不想sudo使用的话，可以移动配置文件：

Terminal window

1
mkdir -p ~/.kube
2
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
3
sudo chown $USER:$USER ~/.kube/config

设置环境变量export KUBECONFIG=~/.kube/config

加入agent节点

查看/var/lib/rancher/k3s/server/node-token得到token，加入

Terminal window

1
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC='agent --node-ip=10.0.0.14 --node-name=p4' K3S_URL='master url' K3S_TOKEN='token' sh -
2

3
# 建议指定--node-ip和-node-name，多网卡下自动获取的node-ip可能不对，而node-name一般不太标准

多主节点#

上面的初始化是单master节点的，因为使用的是sqlite，如果要使用多节点，需要在第一台机器上加入--cluster-init，即：

Terminal window

1
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC='server --node-ip=10.0.0.21 --node-name=h1 --flannel-backend=none --disable-network-policy --disable=traefik --cluster-init' sh -
2

3
# --flannel-backend=none --disable-network-policy --disable=traefik
4
# 是禁用自带的CNI和网络配置，为后面的cilium做准备

后面的server节点不需要，即：

Terminal window

1
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC='server --node-ip=10.0.0.24 --node-name=h4 --flannel-backend=none --disable-network-policy --disable=traefik' K3S_URL='https://10.0.0.21:6443' K3S_TOKEN='token' sh -
2

3
# 除此之外的INSTALL_K3S_EXEC参数需要和第一个节点相同，否则无法同步

其他agent加入与server相同，但注意不要INSTALL_K3S_EXEC参数控制网络插件

Terminal window

1
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC='agent --node-ip=10.0.0.14 --node-name=p4' K3S_URL='https://10.0.0.21:6443' K3S_TOKEN='token' sh -

删除#

Terminal window

1
# master
2
/usr/local/bin/k3s-uninstall.sh
3
# agent
4
/usr/local/bin/k3s-agent-uninstall.sh

删除后集群数据并不会完全删除，可能残留有网络插件数据，查阅文档删除即可。

‍

集群网络#

CNI cilium#

由于自带的是flannel+vxlan，性能比较差，一般希望换成cilium，官方文档：

由于cilium是取代了kube-proxy的，这里面还需要处理一下，安装server的时候：

Terminal window

1
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC='--flannel-backend=none --disable-network-policy' sh -
2

3
# 如果不想使用自带的LB，再加入--disable=traefik

来diable network

然后照官方文档安装cilium就可以了

Terminal window

1
 helm install cilium ./cilium --version 1.17.0 \
2
   --namespace cilium \
3
   --set hubble.relay.enabled=true \
4
   --set operator.replicas=1 \
5
   --set hubble.ui.enabled=true \
6
   --create-namespace
7

8
# operator.replicas=1建议只使用1

另外注意的是ip段，cilium默认使用10.0.0.0/8，如果CIDR冲突，需要更改集群IP段，用helm拉下找到CIDR即可，不然cilium修改route后会断网

集群存储#

Longhorn#

按照官网的安装教程来，使用helm，但是需要做一些初始化工作，每个节点都需要达到要求

Terminal window

1
# 基础工具nfs-common
2
sudo apt install -y nfs-common cryptsetup
3

4
# dm_crypt 模块
5
lsmod | grep dm_crypt
6
sudo modprobe dm_crypt
7
sudo echo "dm_crypt" | sudo tee -a /etc/modules # 加入启动列表自动加载
8

9

10
# 关闭multipathd
11
sudo systemctl stop multipathd.socket
12
sudo systemctl disable multipathd.socket
13
sudo systemctl stop multipathd.service
14
sudo systemctl disable multipathd.service

完毕后，安装：

Terminal window

1
helm install longhorn longhorn/longhorn --namespace longhorn-system --create-namespace --version 1.8.0

longhorn自带一个UI来设置所有的values，所以我们不需要改

集群LB#

Ingress Gateway#

安装

Terminal window

1
helm install eg oci://docker.io/envoyproxy/gateway-helm --version v0.0.0-latest -n envoy-gateway-system --create-namespace

Terminal window

1
# 测试
2
kubectl wait --timeout=5m -n envoy-gateway-system deployment/envoy-gateway --for=condition=Available
3
kubectl apply -f https://github.com/envoyproxy/gateway/releases/download/latest/quickstart.yaml -n default

HA Loadbalance#

‍

Terminal window

1
frontend k3s-frontend
2
    bind *:16443 # 这里必须是*，否则没拿到IP的backup节点启动失败
3
    mode tcp
4
    option tcplog
5
    default_backend k3s-backend
6

7
backend k3s-backend
8
    mode tcp
9
    option tcp-check
10
    balance roundrobin
11
    default-server inter 10s downinter 5s
12
    server server-1 10.0.0.21:6443 check
13
    server server-2 10.0.0.22:6443 check
14
    server server-3 10.0.0.24:6443 check

‍

Terminal window展开收起

1
global_defs {
2
  enable_script_security
3
  script_user root
4
}
5

6
vrrp_script chk_haproxy {
7
    script 'killall -0 haproxy' # 测试haproxy进程是否存在
8
    interval 2
9
}
10

11
vrrp_instance haproxy-vip {
12
    interface eth1 # 修改通信网卡
13
    state <STATE> # MASTER, BACKUP, BACKUP
14
    priority <PRIORITY> # 200, 150, 100
15

16
    virtual_router_id 51
17

18
    virtual_ipaddress {
19
        10.0.0.99/24
20
    }
21

22
    track_script {
23
        chk_haproxy
24
    }
25
}

展开收起

其他#

集群调试#

实践中关键数据库一般不会暴露到集群外，如 mysql，假设上面我们只有一个 mysql-ci-service 可用，怎么连上mysql 进行调试呢？

port-forward：使用 kubectl 端口转发：可以转发到 pod 和服务，只转发端口
proxy：通过 k8s api 访问集群服务，但只能访问 http 服务
使用 telepresence：推荐

port-forward#

我们已知上面的service 名称为 mysql-ci-service，端口为 30002，则可以输入：

Terminal window

1
kubectl port-forward service/mysql-ci-service 3306:30002

就把本地端口转发到 service 的 30002，service 再转发到 pod 3306

如果要转发 pod（比如说可能想绕过 service 的负载均衡到达指定 pod），则需要得到 pod 名称，然后输入：

Terminal window

1
kubectl port-forward pod/mysql-6d57fdf866-f492r 3306:3306

proxy#

输入 kubectl proxy 即可使用

telepresence#

telepresence 可以直接拦截本地流量发送到 k8s 上，看起来就好像身处集群中。

telepresence

Terminal window

1
telepresence connect

如果想要拦截云上服务的流量，telepresence 也能做到，详细参考文档。

‍

其他问题#

本地私有仓库配置#

k3s不是在containerd的配置文件中配置本地仓库，而是配置k3s，自动生成containerd的配置文件，假设10.0.0.21:5000上有一个镜像站：

/etc/rancher/k3s/registries.yaml

1
sudo mkdir -p /etc/rancher/k3s
2
# 添加
3
mirrors:
4
  "10.0.0.21:5000":
5
    endpoint:
6
      - "http://10.0.0.21:5000"

然后重启k3s服务

‍

命名空间无法删除的问题#

查看命名空间存在的资源：

Terminal window

1
kubectl api-resources --verbs=list --namespaced -o name | xargs -n 1 kubectl -n <name-of-namespace> get

然后删除对应的资源

k3s 本地存储

Thu, 17 Apr 2025 00:01:08 GMT

k3s 本地存储#

k3s 是轻量级单节点集群，当然也可以加入多节点。

安装#

Terminal window

1
curl -sfL https://get.k3s.io | sh -
2

3
# 中国区加速
4
curl -sfL https://rancher-mirror.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn sh -

运行完就安装完成了，需要保证 6443 和 443 端口可用。

卷和存储#

本地存储#

添加一个 pvc.yaml

1
apiVersion: v1
2
kind: PersistentVolumeClaim
3
metadata:
4
  name: mysql-pvc # pvc的名字，可自定义
5
  namespace: default
6
spec:
7
  accessModes:
8
    - ReadWriteOnce # 只能被单节点读写
9
  storageClassName: local-path # k3s 内置的存储类，如果用 k8s 要自己添加 sc
10
  resources:
11
    requests:
12
      storage: 2Gi

再添加一个使用 pvc 的 deployment：mysql.yaml

1
apiVersion: apps/v1
2
kind: Deployment
3
metadata:
4
  name: mysql
5
spec:
6
  selector:
7
    matchLabels:
8
      app: mysql # 选择 app: mysql 标签的 pod
9

10
  template: # 创建 pod 的模板
11
    metadata:
12
      labels:
13
        app: mysql # 创建 pod 时添加 app: mysql 标签，以便 Deployment 可以识别
14
    spec:
15
      containers:
16
        - image: mysql
17
          name: mysql
18
          env:
19
            - name: MYSQL_ROOT_PASSWORD
20
              value: "123456"
21
          ports:
22
            - containerPort: 3306
23
              name: mysql
24
          volumeMounts:
25
            - name: mysql-volume # 和下面的 volumeMounts 一致才能 bind
26
              mountPath: /var/lib/mysql # mysql的 data 所在位置
27
      volumes:
28
        - name: mysql-volume # 和上面的 volumeMounts 一致才能bind
29
          persistentVolumeClaim:
30
            claimName: mysql-pvc # 和刚刚的pvc保持一致

展开收起

分别使用 kubectl apply 添加，pvc 没有 bind 的时候是 pending 状态，成功之后变成 bound

注意 mysql.yaml 的模板中 version 是 apps/v1，这是资源路径。

如果一直显示 pending 可以使用 kubectl describe pods <container_name> 查看原因，container_name需要 get pods 查看

例如这里一开始搞错了 pvc 名字，修正后 describe 得到成功。

image-20240704151857876

但此时还不能访问 mysql，因为它目前只在集群内部使用

集群服务#

集群内的 pod 需要变成 service 才能使用，有三种类型：

ClusterIP Service：仅限集群内
NodePort Service：集群外
LoadBalancer Service：集群外+负载均衡

NodePort#

NodePort 实际上并不推荐使用，推荐 LoadBalancer

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: mysql-service
5
spec:
6
  selector:
7
    app: mysql
8
  ports:
9
    - protocol: TCP # TCP|UDP
10
      port: 3306 # 客户端访问服务的端口
11
      targetPort: 3306 # 容器端口(mysql)
12
      nodePort: 30000 # 在每个节点都开放30000，并转发到3306，省略则不分配
13
  type: NodePort # ClusterIP|NodePort|LoadBalancer

注意 nodePort 要求30000-32767（可设置）

外部访问服务的路线为：外部—>30000—>3306(service)—>3306(pod)

LoadBalancer#

一般推荐使用 loadbalancer：

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: mysql-lb-service
5
spec:
6
  selector:
7
    app: mysql
8
  ports:
9
    - protocol: TCP
10
      port: 30001
11
      targetPort: 3306
12
  type: LoadBalancer

这时可以直接使用[集群外部IP:端口（30001）]访问。

ClusterIP#

仅限集群内访问的 ClusterIP：

1
apiVersion: v1
2
kind: Service
3
metadata:
4
  name: mysql-ci-service
5
spec:
6
  selector:
7
    app: mysql
8
  ports:
9
    - protocol: TCP # TCP|UDP
10
      port: 30002
11
      targetPort: 3306
12
  type: ClusterIP

运行后得到：

image-20240704161628962

一般来说会得到一个 CLUSTER-IP，这个 IP 不会变（自动路由到对应 pod），除非重启服务。

但推荐使用 Service Name 访问（这里是 mysql-ci-service）。这样 IP 变了也无所谓，此外 ClusterIP 还可以指定 IP。

深入：k8s 服务

本地调试#

实践中关键数据库一般不会暴露到集群外，如 mysql，假设上面我们只有一个 mysql-ci-service 可用，怎么连上mysql 进行调试呢？

port-forward：使用 kubectl 端口转发：可以转发到 pod 和服务，只转发端口
proxy：通过 k8s api 访问集群服务，但只能访问 http 服务
使用 telepresence：推荐

port-forward#

我们已知上面的service 名称为 mysql-ci-service，端口为 30002，则可以输入：

Terminal window

1
kubectl port-forward service/mysql-ci-service 3306:30002

就把本地端口转发到 service 的 30002，service 再转发到 pod 3306

如果要转发 pod（比如说可能想绕过 service 的负载均衡到达指定 pod），则需要得到 pod 名称，然后输入：

Terminal window

1
kubectl port-forward pod/mysql-6d57fdf866-f492r 3306:3306

proxy#

输入 kubectl proxy 即可使用

telepresence#

telepresence 可以直接拦截本地流量发送到 k8s 上，看起来就好像身处集群中。

telepresence

Terminal window

1
telepresence connect

如果想要拦截云上服务的流量，telepresence 也能做到，详细参考文档。

cuda 编程学习：Grid-Block-Thread

Sat, 05 Apr 2025 18:50:43 GMT

cuda 编程学习：Grid-Block-Thread#

cuda的软件层级#

image

cuda的软件逻辑上包含Grid-Block-Thread三级结构，kernel可以理解为一次函数调用，生成一个Grid。

矩阵乘kernel为例编写cuda代码#

调用kernel时，实际上传入了kernel_name<<<grid,block>>>参数。如上图，grid参数控制了一个Grid有多少个Block，block参数控制了一个Block里需要多少Thread，这两个参数都是三维向量，如下方矩阵乘的kernel定义：

1
// 定义线程组织结构
2
// 每个 block 包含 BLOCK_SIZE x BLOCK_SIZE 个线程
3
dim3 block(THREAD_SIZE_X, THREAD_SIZE_Y, THREAD_SIZE_Z);
4
// grid 的维度，根据输出矩阵 C 的尺寸（M x N）确定
5
dim3 grid(grid_size_x, grid_size_y, grid_size_z);
6
// 启动 kernel
7
matrixMulKernel<<<grid, block>>>(A, B, C, M, N, K);

dim block也可以写成，Z方向默认为1

1
dim3 block(THREAD_SIZE_X, THREAD_SIZE_Y);

定义好维度之后，在kernel函数里面就可以通过变量拿到执行thread的信息：

1
int grid_x = gridDim.x; // grid 在x方向的线程块数量
2
int block_y = blockIdx.y;
3
int block_y_dim = blockDim.y; // block在y方向的线程数量
4
int thread_x = threadIdx.x;

如果我们要计算一个矩阵乘，可以这么写，注意B是转置后的矩阵，具有局部性，和数学上的不一样，这是一般矩阵乘编写时的习惯

1
__global__ void matrixMulKernel(const float * __restrict__ A, const float * __restrict__ B, float * __restrict__ C, int m, int n, int k) {
2
  // A[M][K]
3
  // B[N][K]
4
  // C[M][N]
5
    int i = blockIdx.y * blockDim.y + threadIdx.y;
6
    int j = blockIdx.x * blockDim.x + threadIdx.x;
7
    // 每个thread执行一行和一列的计算
8
    if (i < m && j < n) {
9
        float sum = 0.0f;
10
        for (int l = 0; l < k; l++) {
11
            sum += A[i * k + l] * B[j * k + l];
12
        }
13
        C[i * n + j] = sum;
14
    }
15
}

展开收起

调用kernel前后的操作#

调用kernel之前需要做一些准备工作：申请内存，内存拷贝，定义grid和block大小

调用kernel后需要cudaDeviceSynchronize();等待结果，这是因为kernel的调用是异步提交的任务，完成后拷贝内存和释放device内存。

1
void sgemm_cuda(float *A, float *B, float *C, int m, int n, int k) {
2
    // 在设备端分配内存
3
    float *d_A, *d_B, *d_C;
4
    cudaMalloc(&d_A, M * K * sizeof(float));
5
    cudaMalloc(&d_B, K * N * sizeof(float));
6
    cudaMalloc(&d_C, M * N * sizeof(float));
7

8
    // 将数据从主机拷贝到设备
9
    cudaMemcpy(d_A, A, M * K * sizeof(float), cudaMemcpyHostToDevice);
10
    cudaMemcpy(d_B, B, K * N * sizeof(float), cudaMemcpyHostToDevice);
11

12
    // 定义线程组织结构
13
    // 每个 block 包含 BLOCK_SIZE x BLOCK_SIZE 个线程
14
    dim3 block(THREAD_SIZE, THREAD_SIZE);
15
    // grid 的维度，根据输出矩阵 C 的尺寸（M x N）确定
16
    dim3 grid((N + block.x - 1) / block.x, (M + block.y - 1) / block.y);
17

18
    // 启动 kernel，传入矩阵维度 m, n, k
19
    matrixMulKernel<<<grid, block>>>(d_A, d_B, d_C, M, N, K);
20

21
    // 等待 kernel 执行完成
22
    cudaDeviceSynchronize();
23

24
    // 将结果从设备拷贝回主机
25
    cudaMemcpy(C, d_C, M * N * sizeof(float), cudaMemcpyDeviceToHost);
26

27
    // 释放设备和主机内存
28
    cudaFree(d_A);
29
    cudaFree(d_B);
30
    cudaFree(d_C);
31
}

展开收起

‍

cuda实际上的调度#

软件层级是编写kernel代码才会出现的，实际上GPU在计算时只有SM存在，可以理解为CPU的一个core，一个SM可以执行成百上千thread的执行。

GPU在调度kernel的时候，会保证一个Block内的thread被分配到同一个SM（SIMT）。

NVIDIA在调度时，32个thread是一个wrap，wrap才是SM调度和运行的基本单元，一次并行执行相同的指令，一个wrap占用一个SM运行，可以理解为CPU的一个线程。

这样一来，一个block内的thread如果很多，就会有多个wrap，假如是512，则有512/32=16个wrap，这16个wrap的运行是轮流进入SM的，由SM的硬件（wrap schedule）负责调度。

完整代码#

1
#include <stdio.h>
2
#include <stdlib.h>
3
#include <cuda_runtime.h>
4
#include <time.h>
5

6
#define M 1024           // 矩阵 A 的行数，矩阵 C 的行数
7
#define N 512           // 矩阵 B 的列数，矩阵 C 的列数
8
#define K 512           // 矩阵 A 的列数，同时也是矩阵 B 的行数
9
#define BLOCK_SIZE 16
10
#define THREAD_SIZE 16
11

12
int64_t get_current_time_ns() {
13
    struct timespec ts;
14
    clock_gettime(CLOCK_MONOTONIC, &ts);
15
    return ts.tv_sec * 1000000000 + ts.tv_nsec;
16
}
17

18

19
__global__ void matrixMulKernel(const float * __restrict__ A, const float * __restrict__ B, float * __restrict__ C, int m, int n, int k) {
20
    int i = blockIdx.y * blockDim.y + threadIdx.y;
21
    int j = blockIdx.x * blockDim.x + threadIdx.x;
22
    // 每个thread执行一行和一列的计算
23
    if (i < m && j < n) {
24
        float sum = 0.0f;
25
        for (int l = 0; l < k; l++) {
26
            sum += A[i * k + l] * B[j * k + l];
27
        }
28
        C[i * n + j] = sum;
29
    }
30
}
31

32
void sgemm_cpu(const float * __restrict__ A, const float * __restrict__ B, float * __restrict__ C, int m, int n, int k) {
33
    for (int i = 0; i < m; i++) {
34
        for (int j = 0; j < n; j++) {
35
            float sum = 0.0f;
36
            for (int l = 0; l < k; l++) {
37
                sum += A[i * k + l] * B[j * k + l];
38
            }
39
            C[i * n + j] = sum;
40
        }
41
    }
42
}
43

44
void sgemm_cuda(float *A, float *B, float *C, int m, int n, int k) {
45
    // 在设备端分配内存
46
    float *d_A, *d_B, *d_C;
47
    cudaMalloc(&d_A, M * K * sizeof(float));
48
    cudaMalloc(&d_B, K * N * sizeof(float));
49
    cudaMalloc(&d_C, M * N * sizeof(float));
50

51
    // 将数据从主机拷贝到设备
52
    cudaMemcpy(d_A, A, M * K * sizeof(float), cudaMemcpyHostToDevice);
53
    cudaMemcpy(d_B, B, K * N * sizeof(float), cudaMemcpyHostToDevice);
54

55
    // 定义线程组织结构
56
    // 每个 block 包含 BLOCK_SIZE x BLOCK_SIZE 个线程
57
    dim3 block(THREAD_SIZE, THREAD_SIZE);
58
    // grid 的维度，根据输出矩阵 C 的尺寸（M x N）确定
59
    dim3 grid((N + block.x - 1) / block.x, (M + block.y - 1) / block.y);
60

61
    // 启动 kernel，传入矩阵维度 m, n, k
62
    matrixMulKernel<<<grid, block>>>(d_A, d_B, d_C, M, N, K);
63

64
    // 等待 kernel 执行完成
65
    cudaDeviceSynchronize();
66

67
    // 将结果从设备拷贝回主机
68
    cudaMemcpy(C, d_C, M * N * sizeof(float), cudaMemcpyDeviceToHost);
69

70
    // 释放设备和主机内存
71
    cudaFree(d_A);
72
    cudaFree(d_B);
73
    cudaFree(d_C);
74
}
75

76
int main() {
77
    // C = A * B, 注意B的存储模式并非常规的行优先，而是列优先（转置），这是为了局部性
78
    // A[M][K], B[N][K], C[M][N]
79
    float *A = (float*)malloc(M * K * sizeof(float));
80
    float *B = (float*)malloc(K * N * sizeof(float));
81
    float *C = (float*)malloc(M * N * sizeof(float));
82

83
    // 初始化矩阵 A 和 B
84
    for (int i = 0; i < M * K; i++) {
85
        A[i] = (float)rand() / RAND_MAX;
86
    }
87
    for (int i = 0; i < K * N; i++) {
88
        B[i] = (float)rand() / RAND_MAX;
89
    }
90
    for (int i = 0; i < M * N; i++) {
91
        C[i] = 0.0f;
92
    }
93

94
    int64_t start_time = get_current_time_ns();
95
    sgemm_cpu(A, B, C, M, N, K);
96
    int64_t end_time = get_current_time_ns();
97
    printf("sgemm_cpu time: %ld ns = %f ms\n", end_time - start_time, (end_time - start_time) / 1000000.0);
98

99
    start_time = get_current_time_ns();
100
    sgemm_cuda(A, B, C, M, N, K);
101
    end_time = get_current_time_ns();
102
    printf("sgemm_cuda time: %ld ns = %f ms\n", end_time - start_time, (end_time - start_time) / 1000000.0);
103
}

展开收起

Minitorch-1

Fri, 04 Apr 2025 16:15:50 GMT

Minitorch-1 Fundamentals 基础#

Task 0.1 Operators#

第一关是完成一些简单的函数。需要注意下 relu 的定义。

此外还有 xx_back 系列函数，指的是反向传播的求导：，一开始没看懂什么意思。

Task 0.2 Testing and Debuging#

第二关要完成 tests/test_operators.py 下面的测试函数

在做 test_sigmod 的时候遇到精度问题：测试函数递增性的时候怎么都过不了，想出直接排除掉相近的结果，不知道是否可行？

1
if math.fabs(sigmoid(a) - sigmoid(b)) > 1e-6:
2
    assert sigmoid(a) < sigmoid(b) if a < b else sigmoid(a) > sigmoid(b)

Task 0.3 Functional Python 函数式编程#

第三关涉及到 python 的高级特性，因为之前没有用过 python 的高阶用法，有点难度。

map 将第一个函数 作用于 后面的 list，并且每次调用是传递 list 的一个值并修改

1
def square(x: float) -> float:
2
    return x ** 2
3
res = map(square, [1, 2, 3, 4, 5])
4
print(list(res))
5
# [1, 4, 9, 16, 25]

Callable 类型提示：可以理解为限定了参数和返回值的函数

1
from typing import Callable
2

3
# 使用Callable类型提示
4
def operate_on_two_integers(op: Callable[[int, int], int], a: int, b: int) -> int:
5
    return op(a, b)
6

7
# 符合上面的 op 的一个实例
8
def add(x: int, y: int) -> int:
9
    return x + y
10
result = operate_on_two_integers(add, 2, 3)
11
print(result)
12
# 5

Iterable 类型：可以迭代的类型：

1
def print_elements(elements: Iterable) -> None:
2
    for element in elements:
3
        print(element)

最后是装饰器，把一个处理值的函数变成处理 list->list 的函数：

先看返回值，根据返回值写出改返回的函数（如 process），然后再考虑怎么写这个函数内容。

1
def map(fn: Callable[[float], float]) -> Callable[[Iterable[float]], Iterable[float]]:
2
    def process(ls: Iterable[float]) -> Iterable[float]:
3
        return [fn(x) for x in ls]
4
    return process

一旦学会了这种装饰器写法后面的就简单了

Task 0.4 Modules#

第四关是完成一棵树，读一下 class module 和 class parameter 就知道在干嘛了。

主要都是用到递归的写法，不过要稍微注意一下 named_parameters，它有独特的命名规则，写的不是很清楚，需要去 test_module.py 看它需要的命名规则是什么。

Task 0.5 Visualization 可视化#

第五关可以运行一个交互式应用：

Terminal window

1
streamlit run app.py -- 0

不过会报ModuleNotFoundError: No module named 'altair.vegalite.v4'错误，是因为最新版是 v5，没有安装 v4 版本，需要 pip install --upgrade altair==4

成功运行之后发现导入失败：ModuleNotFoundError: No module named 'minitorch'

应该是包未安装，研究发现应该运行：python -m pip install -Ue .这个是更新minitorch 包的命令，从而让 streamlit 可以导入这个包，一开始没有运行：

image-20240711114137559

最后成功：

image-20240711115647859

试了一下 Torch Example的几个简单任务，Module 0还没有 train 的选项，因为我们还没做到，不过这是最初的一步！

nginx

Fri, 04 Apr 2025 16:15:50 GMT

nginx#

安装Nginx#

docker安装#

Terminal window

1
docker run -d --restart=always \
2
--net host \
3
--name nginx \
4
-v ./nginx.conf:/etc/nginx/nginx.conf \
5
-v ./log:/var/log/nginx \ # log
6
-v ./cert:/etc/nginx/cert \ # SSL证书文件, 没有可以去掉
7
-v ./html:/usr/share/nginx/html \
8
nginx:1.24.0

net=host是因为懒得配端口了, 这样好一些

shell启动不够优雅, 建议使用docker compose

1
version: '3.8'
2
services:
3
  nginx:
4
    image: nginx:1.24.0
5
    container_name: nginx
6
    restart: always
7
    network_mode: host
8
    volumes:
9
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
10
      - ./logs:/var/log/nginx:rw
11
      - ./cert:/etc/nginx/cert:ro
12
      - ./html:/usr/share/nginx/html:ro # 一些html或者error.json

注意:

network_mode是linux专用, docker desktop没用
host网络模式不是最佳实践, 如果有确定的后端编排还是一起编排比较合适

apt下载安装启动(不建议)#

为了不找不自在, 还是用docker部署吧!

不建议使用apt安装, 因为会缺少很多模块, 而且版本较老

Terminal window

1
sudo apt install nginx
2
service nginx start # 启动nginx

然后打开80端口查看情况, 如果出现nginx主页说明成功

从源码编译安装并配置SSL模块#

参考: https://developer.aliyun.com/article/766958

先安装好nginx

去官网下载源码: https://nginx.org/en/download.html

建议下载Stable version

解压安装包

Terminal window

1
tar -zxvf <包的名字>

安装SSL模块

到nginx目录下, 输入

Terminal window

1
./configure --prefix=/etc/nginx --with-http_ssl_module

/ect/nginx是你的nginx安装位置, 也可以是/usr/local/nginx

如果用apt安装的话, 为/etc/nginx

如果出现 the HTTP rewrite module requires the PCRE library, 则安装:

Terminal window

1
apt-get install libpcre3 libpcre3-dev

上面的命令是配置ssl模块

用make命令编译, 注意不要使用make install, 会重新安装nginx, 当然, 想重新安装也可以输入

Terminal window

1
make

这里面可能会出现errors, 不用管

如果出现了缺少包依赖的错误, 直接安装即可, 这里提供一些可能出现的:

Terminal window

1
sudo apt-get install libpcre3 libpcre3-dev # 缺少pcre
2
sudo apt-get install openssl libssl-dev # 缺少openssl
3
sudo apt-get install zlib1g-dev # 缺少zlib

将obj的文件复制到nginx上覆盖原来的文件
查看是否安装成功

Terminal window

1
nginx -V

如果出现**—with-http_ssl_module**则成功

nginx文件树#

nginx配置文件在/etc/nginx中

nginx启动时加载nginx.conf

其中有两行:

1
include /etc/nginx/conf.d/*.conf;
2
include /etc/nginx/sites-enabled/*;

意思是引用了这两个目录下的所有文件

其中, sites-enabled 是 sites-available的链接, 把想启动的配置放在这里即可, 同理当想临时关闭某个站点时, 把sites-enabled对应的链接删去即可

当然,也可以在conf.d中放配置文件, 不过不建议

注意: 由于 sites-enabled 有默认的nginx界面,所有访问均会导向默认界面所以要使我们的配置生效, 需要把sites-enabled的链接删去

nginx架构#

nginx 一把梭！（超详细讲解+实操）

配置模板开箱即用#

注意, 需要使用上面的docker-compose.yaml启动, 目录下放这个配置文件(nginx.conf)

1
user nginx;
2
worker_processes  auto;
3

4
error_log  /var/log/nginx/error.log notice; # notice级别
5
pid        /var/run/nginx.pid; # nginx进程id
6

7

8
events {
9
    worker_connections  1024;
10
}
11

12

13
http {
14
    include       /etc/nginx/mime.types;
15
    default_type  application/octet-stream;
16

17
    # --------------------日志 配置---------------------
18
    # 格式:
19
    # remote_addr - remote_user [time_local] "request" status body_bytes_sent "http_referer" "http_user_agent" "http_x_forwarded_for"
20
    # 远程地址       用户名      时间            请求     状态   响应大小         来源网址         用户UA          代理地址
21

22
    # log_format  debug  '$remote_addr - $remote_user [$time_local] "$request" '
23
    #                  '$status $body_bytes_sent "$http_referer" '
24
    #                  '"$http_user_agent" "$http_x_forwarded_for"';
25
    log_format  debug  ' $remote_user [$time_local]  $http_x_Forwarded_for $remote_addr  $request '
26
                      '$http_x_forwarded_for '
27
                      '$upstream_addr '
28
                      'ups_resp_time: $upstream_response_time '
29
                      'request_time: $request_time';
30
    access_log  /var/log/nginx/access.log  debug; # debug级别
31

32
    # --------------------网络 配置---------------------
33
    sendfile        on; # 零拷贝传输(内核和用户)
34
    #tcp_nopush     on; # 优化网络传输，减少网络报文, 把多个小包合并成一个大包发送
35
    keepalive_timeout  65; # 保持长连接的时间, 如果有客户端在65s内没有任何请求, 则关闭连接
36

37
    # --------------------压缩 配置---------------------
38
    # 开启/关闭 压缩机制
39
    gzip on;
40
    # 根据文件类型选择 是否开启压缩机制
41
    gzip_types text/plain application/javascript text/css application/xml text/javascript image/jpeg image/jpg image/gif image/png  application/json;
42
    # 设置压缩级别，越高资源消耗越大越耗时，但压缩效果越好
43
    gzip_comp_level 5;
44
    # 设置是否携带Vary:Accept-Encoding 的响应头
45
    gzip_vary on;
46
    # 处理压缩请求的 缓冲区数量和大小
47
    gzip_buffers 32 64k;
48
    # 对于不支持压缩功能的客户端请求 不开启压缩机制
49
    gzip_disable "MSIE [1-6]\."; # 比如低版本的IE浏览器不支持压缩
50
    # 设置压缩功能所支持的HTTP最低版本
51
    gzip_http_version 1.1;
52
    # 设置触发压缩的最小阈值
53
    gzip_min_length 2k;
54
    # off/any/expired/no-cache/no-store/private/no_last_modified/no_etag/auth 根据不同配置对后端服务器的响应结果进行压缩
55
    gzip_proxied any;
56

57
    # --------------------缓存 配置---------------------
58
    # 指定缓存存放目录为/usr/local/nginx/test/nginx_cache_storage，并设置缓存名称为mycache，大小为64m， 1天未被访问过的缓存将自动清除，磁盘中缓存的最大容量为1gb
59
    proxy_cache_path /usr/local/nginx/test/nginx_cache_storage levels=1:2 keys_zone=mycache:64m inactive=1d max_size=1g;
60

61
    # --------------------限流 配置---------------------
62
    # 对请求速率限流
63
    #limit_req_zone $binary_remote_addr zone=myRateLimit:10m rate=5r/s;
64
    # 对请求连接数限流
65
    limit_conn_zone $binary_remote_addr zone=myConnLimit:10m;
66

67
    # --------------------重定向 配置---------------------
68
    server {
69
      listen 80;
70
      charset utf-8;
71
      server_name www.example.com example.com;
72
      return 301 https://$server_name$request_uri; # 301永久重定向到https
73
    }
74

75
    # --------------------负载均衡 配置---------------------
76
    # upstream backendserver {
77
    #     server 172.30.128.64:8081 fail_timeout=60s max_fails=3; # 60秒内 如果请求某一个应用失败3次，则认为该应用宕机 时间到后再有请求进来继续尝试连接宕机应用且仅尝试 1 次，如果还是失败，则继续等待 60 秒...以此循环，直到恢复
78
    #     server 172.30.128.64:8082;
79
    #     server 172.30.128.64:8083 backup; # 设置8083位备机
80
    # }
81
    upstream backendserver {
82
        server 127.0.0.1:9000;
83
    }
84

85
    # --------------------HTTPS 配置---------------------
86
    server {
87
        #SSL 默认访问端口号为 443
88
        listen 443 ssl;
89
        #填写绑定证书的域名
90
        server_name www.example.com example.com;
91
        #请填写证书文件的相对路径或绝对路径
92
        ssl_certificate /etc/nginx/cert/xxx.pem;
93
        #请填写私钥文件的相对路径或绝对路径
94
        ssl_certificate_key /etc/nginx/cert/xxx.key;
95
        #停止通信时，加密会话的有效期，在该时间段内不需要重新交换密钥
96
        ssl_session_timeout 5m;
97
        #服务器支持的TLS版本
98
        ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
99
        #请按照以下套件配置，配置加密套件，写法遵循 openssl 标准。
100
        ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
101
        #开启由服务器决定采用的密码套件
102
        ssl_prefer_server_ciphers on;
103

104
        # # 指定 username 参数中只要有字母 就不走nginx缓存
105
        # if ($arg_username ~ [a-z]) {
106
        #     set $cache_name "no cache";
107
        # }
108
        # # 前端页面资源
109
        # location  /page {
110
        #   alias  '/usr/local/nginx/test/static/';
111
        #   index index_page.html;
112

113
        #   allow all;
114
        # }
115
        # # 后端服务
116
        # location  /interface {
117
        #   proxy_pass http://backendserver/;
118

119
        #   # 指定哪些错误状态才执行 重试
120
        #   proxy_next_upstream error timeout http_500 http_502 http_503 http_504 http_404;
121

122

123
        #   # 使用名为 mycache 的缓存空间
124
        #   proxy_cache mycache;
125
        #   # 对于200 206 状态码的数据缓存2分钟
126
        #   proxy_cache_valid 200 206 1m;
127
        #   # 定义生成缓存键的规则（请求的url+参数作为缓存key）
128
        #   proxy_cache_key $host$uri$is_args$args;
129
        #   # 资源至少被重复访问2次后再加入缓存
130
        #   proxy_cache_min_uses 3;
131
        #   # 出现重复请求时，只让其中一个去后端读数据，其他的从缓存中读取
132
        #   proxy_cache_lock on;
133
        #   # 上面的锁 超时时间为4s，超过4s未获取数据，其他请求直接去后端
134
        #   proxy_cache_lock_timeout 4s;
135
        #   # 对于请求参数中有字母的 不走nginx缓存
136
        #   proxy_no_cache $cache_name; # 判断该变量是否有值，如果有值则不进行缓存，没有值则进行缓存
137
        #   # 在响应头中添加一个缓存是否命中的状态（便于调试）
138
        #   add_header Cache-status $upstream_cache_status;
139

140
        #   limit_conn myConnLimit 12;
141

142
        # # limit_req zone=myRateLimit burst=5  nodelay;
143
        # # limit_req_status 520;
144
        # # limit_req_log_level info;
145
        # }
146

147
        # # 后端服务
148
        # location  /interface2 {
149
        #   proxy_pass http://backendserver;
150
        #   # 使用名为 mycache 的缓存空间
151
        #   proxy_cache mycache;
152
        #   # 对于200 206 状态码的数据缓存2分钟
153
        #   proxy_cache_valid 200 206 1m;
154
        #   # 定义生成缓存键的规则（请求的url+参数作为缓存key）
155
        #   proxy_cache_key $host$uri$is_args$args;
156
        #   # 资源至少被重复访问2次后再加入缓存
157
        #   proxy_cache_min_uses 3;
158
        #   # 出现重复请求时，只让其中一个去后端读数据，其他的从缓存中读取
159
        #   proxy_cache_lock on;
160
        #   # 上面的锁 超时时间为4s，超过4s未获取数据，其他请求直接去后端
161
        #   proxy_cache_lock_timeout 4s;
162
        #   # 对于请求参数中有字母的 不走nginx缓存
163
        #   proxy_no_cache $cache_name; # 判断该变量是否有值，如果有值则不进行缓存，没有值则进行缓存
164
        #   # 在响应头中添加一个缓存是否命中的状态（便于调试）
165
        #   add_header Cache-status $upstream_cache_status;
166

167
        #   limit_conn myConnLimit 12;
168

169
        # # limit_req zone=myRateLimit burst=5  nodelay;
170
        # # limit_req_status 520;
171
        # # limit_req_log_level info;
172
        # }
173

174
    }
175

176
    # include /etc/nginx/conf.d/*.conf;
177
}

展开收起

配置示例#

修改错误返回值#

有些时候希望返回的不是service unavailable, 希望返回某段json, 可以这样设置

/50x.json是返回的json内容, 也可以返回其他网页

1
server {
2
...
3
error_page 5xx /5xx.json;
4
location = /5xx.json {
5
root /usr/share/nginx/html;
6
internal; # 保证这个路径只能内部请求
7
}
8
...
9
}

websocket配置#

websocket比较特殊, 需要加入upgrade和connection

1
location /api/ws/ {
2
proxy_redirect off;
3
proxy_set_header Upgrade $http_upgrade;
4
proxy_set_header Connection "upgrade";
5
proxy_pass       http://127.0.0.1:9000/api/ws/;
6
}

SSE配置#

SSE配置需要去掉缓存, 不然SSE失效

1
location /api/sse {
2
proxy_redirect off;
3
proxy_pass         http://127.0.0.1:9000/api/sse;
4
proxy_buffering off; # 去掉缓存
5
}

请求速率限流#

1
http{
2
...
3
# 对请求速率限流
4
limit_req_zone $binary_remote_addr zone=myRateLimit:10m rate=5r/s;
5

6
    server{
7
        location /api {
8
            ...
9
            limit_req zone=myRateLimit burst=5 nodelay;
10
            limit_req_status 520; # 返回码
11
            limit_req_log_level info;
12
        }
13
    }
14
}

$binary_remote_addr: 基于客户端IP做限流

zone=myRateLimit:10m 指myRateLimit作为内存区域, 大小10M(16万)IP地址

rate=5r/s 指相同IP每秒最多请求5次(200ms一个请求)
burst=5: 削峰, 如果峰值超过rate(比如说200ms来了两个), 则会用一个大小为burst的队列削峰, 然后慢慢根据rate速率处理, 多余的直接503
nodelay: 如果是nodelay, 则burst削峰会立即处理, 而不是每200ms取一个

nodelay立即处理, 那么nginx怎么控制并发? 是通过处理但不释放的方式控制. 后面的请求会阻塞

一般建议burst和nodelay一起用, 可以处理突发流量

请求连接数限流#

1
http{
2
# 针对ip  对请求连接数限流
3
...
4
limit_conn_zone $binary_remote_addr zone=myConnLimit:10m;
5
...
6

7
    server{
8
       ...
9
       limit_conn myConnLimit 12;
10
    }
11
}

https/SSL#

注意需要http_ssl_module

1
server {
2
#SSL 默认访问端口号为 443
3
listen 443 ssl;
4
#填写绑定证书的域名
5
server_name www.hzznb-xzll.xyz hzznb-xzll.xyz;
6
#请填写证书文件的相对路径或绝对路径
7
ssl_certificate 证书路径;
8
#请填写私钥文件的相对路径或绝对路径
9
ssl_certificate_key 私钥路径;
10
#停止通信时，加密会话的有效期，在该时间段内不需要重新交换密钥
11
ssl_session_timeout 5m;
12
#服务器支持的TLS版本
13
ssl_protocols TLSv1 TLSv1.1 TLSv1.2 TLSv1.3;
14
#请按照以下套件配置，配置加密套件，写法遵循 openssl 标准。
15
ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
16
#开启由服务器决定采用的密码套件
17
ssl_prefer_server_ciphers on;
18
}

展开收起

ssl_certificate: .pem或者/csr文件

ssl_certificate_key: 一般是.key文件

80重定向到443#

1
server_name www.hzznb-xzll.xyz hzznb-xzll.xyz;
2
# 重定向到目标地址
3
return 301 https://$server_name$request_uri;

压缩#

1
http {
2
# 开启/关闭 压缩机制
3
gzip on;
4
# 根据文件类型选择 是否开启压缩机制
5
gzip_types text/plain application/javascript text/css application/xml text/javascript image/jpeg image/jpg image/gif image/png  application/json;
6
# 设置压缩级别，一共9个级别  1-9   ，越高资源消耗越大 越耗时，但压缩效果越好，
7
gzip_comp_level 5;
8
# 设置是否携带Vary:Accept-Encoding 的响应头
9
gzip_vary on;
10
# 处理压缩请求的 缓冲区数量和大小
11
gzip_buffers 32 64k;
12
# 对于不支持压缩功能的客户端请求 不开启压缩机制
13
gzip_disable "MSIE [1-6]\."; # 比如低版本的IE浏览器不支持压缩
14
# 设置压缩功能所支持的HTTP最低版本
15
gzip_http_version 1.1;
16
# 设置触发压缩的最小阈值
17
gzip_min_length 2k;
18
# off/any/expired/no-cache/no-store/private/no_last_modified/no_etag/auth 根据不同配置对后端服务器的响应结果进行压缩
19
gzip_proxied any;
20
}

展开收起

负载均衡#

配置热备#

1
upstream mysvr {
2
server 192.168.10.121:3333 max_fails=2 fail_timeout=2;
3
server 192.168.10.122:3333 backup;
4
}

max_fails: 允许请求失败的最大次数, 超过时返回proxy_next_upstream模块定义的错误
fail_timeout: 经历了max_fails失败后暂停服务的时间

轮询(round-robin)#

1
upstream mysvr {
2
server 127.0.0.1:7878;
3
server 192.168.10.121:3333;
4
}

请求会分别发送到两个服务器, A-B-A-B…

1
upstream mysvr {
2
server 127.0.0.1:7878 weight=1;
3
server 192.168.10.121:3333 weight=2;
4
}

给不同服务器设置权重, 上面会变成A-B-B-A-B-B…

ip_hash#

1
upstream mysvr {
2
server 127.0.0.1:7878;
3
server 192.168.10.121:3333;
4
ip_hash;
5
}

会让相同客户端请求相同的服务器, 实现session等的共享

redis-lua限流脚本

Fri, 04 Apr 2025 16:15:50 GMT

redis-lua 限流脚本#

参考：https://gist.github.com/ptarjan/e38f45f2dfe601419ca3af937fff574d

令牌桶算法(token bucket)#

1
local tokens_key = KEYS[1] -- token键
2
local timestamp_key = KEYS[2] -- 上次更新时间戳
3

4
local rate = tonumber(ARGV[1]) -- 每秒加入令牌数
5
local capacity = tonumber(ARGV[2]) -- 最大容量
6
local now = tonumber(ARGV[3]) -- 当前时间戳
7
local requested = tonumber(ARGV[4]) -- 请求令牌
8

9
local fill_time = capacity/rate -- 填充时间
10
local ttl = math.floor(fill_time*2) -- 填充时间的两倍，避免过期
11

12
-- 获取tokens，过期则相当于充满
13
local last_tokens = tonumber(redis.call("GET", tokens_key))
14
if last_tokens == nil then
15
  last_tokens = capacity
16
end
17

18
local last_refreshed = tonumber(redis.call("GET", timestamp_key))
19
if last_refreshed == nil then
20
  last_refreshed = 0
21
end
22

23
-- 填充
24
local delta = math.max(0, now-last_refreshed)
25
local filled_tokens = math.min(capacity, last_tokens+(delta*rate))
26
local allowed = filled_tokens >= requested
27
local new_tokens = filled_tokens
28
if allowed then
29
  new_tokens = filled_tokens - requested
30
end
31

32
redis.call("SETEX", tokens_key, ttl, new_tokens)
33
redis.call("SETEX", timestamp_key, ttl, now)
34

35
-- new_token是消耗令牌后的tokens
36
return { allowed, new_tokens }

展开收起

并行限制 ZSET实现#

并行限制可以控制同时并行的请求数，使用zset实现：

请求来到时，ZCARD查看count数，如果小于则ZADD添加，否则拒绝。
请求结束时，需要调用ZREM+id删除这个member

1
local key = KEYS[1]
2

3
local capacity = tonumber(ARGV[1]) -- 最大请求数
4
local timestamp = tonumber(ARGV[2]) -- 当前时间戳
5
local id = ARGV[3] -- 请求标识
6

7
local count = redis.call("ZCARD", key)
8
local allowed = count < capacity
9

10
if allowed then
11
  redis.call("ZADD", key, timestamp, id)
12
end
13

14
return { allowed, count }

定点刷新#

还可以实现定点刷新脚本：假定每天凌晨四点刷新

利用redis过期机制刷新，先计算现在与下一个刷新点的时间差，检查key是否存在，如果不存在则SET

存在则DECRBY这个key，那么每天到点后，key过期就会自动刷新值。

NolanHo

pi-context：一个让 AI 自己管记忆的小工具

pi-context：一个让 AI 自己管记忆的小工具#

我一直在想这件事#

然后我看到了 pi-context#

发现一：Session Tree 被翻译成了 Git#

发现二：HUD 比地图更重要#

发现三：时间旅行的三段式状态机#

源码里还有一个容易被忽略的细节#

双向时间旅行#

读完源码后的一些想法#

最后#

终端的语义层叠：几种终端方案的底层原理

TTY 与终端模拟器#

物理终端#

TTY#

终端模拟器#

shell、terminal emulator、multiplexer 的区别#

为什么需要 PTY#

PTY 与网络断裂#

tmux 的解法：让 daemon 持有 PTY master#

terminfo：终端能力的注册表#

terminfo 的内部结构#

tmux 的叠加架构与代价#

TERM 截获与能力降维#

双 buffer 结构#

alternate screen 的模拟#

鼠标事件的多跳转发#

zellij 与 cmux#

zellij 的 modal 输入系统#

cmux：本地终端与 JSON-RPC 控制#

WezTerm：把 multiplexing 做进终端本身#

Domain：本地与远程 pane 的来源标记#

Damage tracking：从整屏推流到增量更新#

TERM 端到端穿透#

Lua 配置的统一命名空间#

部署代价#

AI Agent：输入与输出的精确对应#

终端 emulator 与 multiplexer 为何分离#

什么时候选什么#

我为什么选 WezTerm

我的工作流约束#

tmux 保活了会话，但劫持了交互#

zellij 仍是 multiplexer#

cmux 是本地终端，不解决远程持久化#

WezTerm 把远程会话做进终端#

实际配置#

AI Agent 需要什么#

什么时候选什么#

RL算法笔记 WIP

RL算法笔记 WIP#

贝尔曼公式 Bellman Equation#

定义#

推导#

矩阵表示#

贝尔曼最优方程 bellman optimal equation#

在 RAG 和 Agentic 搜索下做结果融合的一些思路

在 RAG 和 Agentic 搜索下做结果融合的一些思路#

1. 为什么在 RAG / Agentic 搜索下需要 Hybrid？#

2. 整体架构：召回与融合#

3. 召回层：多通道设计与配额控制#

4. 融合层：几种混合技术#

4.1 分数归一化与线性加权#

4.2 基于名次的 RRF 及变体#

4.3 规则与级联式 Hybrid#

4.4 排序聚合视角：RRF 与其它 Rank Fusion#

mem0 源码阅读：一个工程化记忆系统

mem0 源码阅读：一个工程化记忆系统#

1. 记忆系统和 RAG#

2. mem0 的目标和定位#

3. mem0 Memory 模块总体结构#

4. add：一个 API 中的多种记忆操作#

4.1 infer=False：直接写入的路径#

4.2 infer=True：LLM 驱动的智能记忆管理#

5. search / update / delete：读写路径与边界#

5.1 search：只读、无 LLM 的查询#

5.2 update / delete：显式操作与历史记录#

6. historydb：历史日志#

7. 设计和使用上的一些思考#

7.1 mem0 更适合作为长期记忆层#

4.1 `infer=False`：直接写入的路径#

4.2 `infer=True`：LLM 驱动的智能记忆管理#

一个有用的快捷方式：`/var/log/pods` 目录#

2.4 根环境切换工具：`arch-chroot`#