JasperSao的博客

KV 进化（二）：Snapshot 全量快照 + AOF 增量日志

Sun, 30 Aug 2026 00:00:00 +0800

这篇承接《KV 进化（一）：给 91kvstore 接上一条跳表》。上一阶段完成了第四种存储引擎的接入，这一阶段继续解决一个更实际的问题：服务退出以后，内存中的数据怎样留下来？

本文记录从 AOF 基础闭环，到全量快照，再到通过 AOF_OFFSET 连接二者的完整实现过程。

1. 确立实现模式

项目采用混合持久化模式：

全量快照：保存某一时刻完整的数据集。
AOF 增量日志：每次成功执行写命令后，记录这条命令。

AOF 的基础闭环为：

执行写命令
→ 写入 AOF
→ 服务重启
→ 读取 AOF
→ 重新执行历史命令
→ 恢复内存数据

加入全量快照以后，最终恢复流程变成：

加载全量快照
→ 获得快照对应的 AOF 偏移量
→ 从偏移量开始重放 AOF
→ 恢复出最新数据

2. 建立独立的持久化模块

持久化属于独立的辅助模块，不应该把所有文件操作都堆在 kvstore.c 中，因此新增：

include/persistence.h
src/persistence/aof.c
src/persistence/snapshot.c

其他模块通过：

#include "persistence.h"

使用持久化功能。

头文件中声明了 AOF 对外提供的接口：

int kvs_aof_open(const char *path);
int kvs_aof_append(char **tokens, int count);
int kvs_aof_close(void);
long long kvs_aof_get_offset(void);

为了实现重放，又增加了回调函数类型：

typedef int (*aof_replay_handler)(
 char *msg,
 int length,
 char *response
);

以及 AOF 重放接口：

int kvs_aof_replay(
 const char *path,
 long long offset,
 aof_replay_handler handler
);

快照模块对外提供：

int kvs_snapshot_save(const char *path);

long long kvs_snapshot_load(
 const char *path,
 aof_replay_handler handler
);

aof_replay_handler 是函数指针类型。重放函数读取到一条命令后，可以通过这个函数指针把命令交给 kvs_protocol() 执行。

3. 打开和关闭 AOF

AOF 文件使用一个模块内部的文件指针保存：

static FILE *aof_fp = NULL;

打开文件时使用追加模式：

aof_fp = fopen(path, "a");

"a" 表示 append，也就是从文件末尾追加内容，不会覆盖已有日志。

kvs_aof_open() 需要检查：

path 是否为 NULL
AOF 是否已经打开
fopen() 是否成功

约定返回值：

0 成功
-1 失败

关闭时使用：

int ret = fclose(aof_fp);
aof_fp = NULL;

即使 fclose() 失败，也要把 aof_fp 设置为 NULL。因为调用 fclose() 以后，不应该继续使用原来的文件指针。

4. 把命令追加到 AOF

协议层已经把命令切分到了 tokens 中。例如：

SET name Jasper

切分以后是：

tokens[0] = "SET"
tokens[1] = "name"
tokens[2] = "Jasper"
count = 3

kvs_aof_append() 首先检查：

AOF 文件是否已经打开
tokens 是否为 NULL
count 是否为 2 或 3
对应位置的 token 是否存在

之后使用 fprintf() 把 tokens 重新组合成一条完整命令：

fprintf(aof_fp, "%s %s\n",
 tokens[0], tokens[1]);

或者：

fprintf(aof_fp, "%s %s %s\n",
 tokens[0], tokens[1], tokens[2]);

因此 AOF 文件中的内容类似：

SET persist_key persist_value
MOD persist_key new_value
DEL persist_key

每条命令占一行，这样重放时才能确定不同命令之间的边界。

5. 从缓冲区同步到文件

fprintf() 返回值大于等于 0，只能说明格式化写入没有在这一层报告错误。数据可能仍然位于 C 标准库维护的用户态缓冲区中。

因此先调用：

fflush(aof_fp);

它会把 C 标准库缓冲区中的数据交给操作系统。

但是数据此时仍可能位于操作系统的页缓存中，所以继续调用：

fsync(fileno(aof_fp));

这里涉及两种文件表示：

FILE * C 标准库使用的文件流
fd 操作系统使用的整数文件描述符

fsync() 接收文件描述符，所以需要使用：

fileno(aof_fp)

把 FILE * 转换成对应的 fd。

于是一次追加的顺序是：

fprintf
→ fflush
→ fileno
→ fsync

其中任何一步失败，kvs_aof_append() 都返回 -1。

6. 判断哪些命令需要写入 AOF

AOF 只记录会改变数据的命令：

SET
DEL
MOD

查询命令不需要记录：

GET
EXIST

当前项目中，每个数据结构引擎的命令都按照五个一组排列：

SET GET DEL MOD EXIST

所以可以通过 cmd % 5 判断命令类型：

static int kvs_is_write_command(int cmd)
{
 if (cmd < KVS_CMD_START || cmd >= KVS_CMD_COUNT) {
 return 0;
 }

 switch (cmd % 5) {
 case 0:
 case 2:
 case 3:
 return 1;
 default:
 return 0;
 }
}

对应关系是：

0 → SET
1 → GET
2 → DEL
3 → MOD
4 → EXIST

7. 只有命令执行成功才记录

AOF 的写入位置是在业务命令执行完成、拿到 ret 之后。

原因是：如果命令执行失败，却仍然被写进 AOF，那么下次重启时可能恢复出一个与用户实际操作结果不一致的数据集。

当前判断为：

if (!aof_replaying &&
 ret == 0 &&
 kvs_is_write_command(cmd)) {

 int aof_ret = kvs_aof_append(tokens, count);

 if (aof_ret < 0) {
 fprintf(stderr, "failed to append AOF\n");
 exit(EXIT_FAILURE);
 }
}

三个条件分别表示：

!aof_replaying 当前不是重放阶段
ret == 0 业务命令执行成功
kvs_is_write_command(cmd) 当前是写命令

如果业务数据已经修改成功，但是 AOF 写入失败，服务选择立即退出。否则程序继续运行，就会出现：

内存中修改成功
→ AOF 中没有记录
→ 服务重启
→ 用户的数据丢失

8. AOF 重放

AOF 重放必须放在 KV 引擎初始化之后，因为历史命令最终要重新写进内存数据结构。

同时，重放必须发生在以追加模式打开 AOF 之前。

在只实现 AOF 的阶段，启动顺序是：

初始化 KV 引擎
→ 进入 AOF 重放状态
→ 读取并执行历史 AOF
→ 退出 AOF 重放状态
→ 以追加模式打开 AOF
→ 启动网络服务

aof_replaying 的含义是：

0 → 正常运行，可以记录新的写命令
1 → 正在恢复历史数据，不能写入 AOF

注意，它表示“正在重放”，不是“正在重写”。

它只能在函数外定义一次：

static int aof_replaying = 0;

如果在 kvs_filter_protocol() 内再次定义同名变量，就会发生变量遮蔽。这样主函数修改的是外层变量，而协议处理函数读取的是内部变量，二者不是同一个变量。

9. AOF 重放函数的实际过程

kvs_aof_replay() 使用只读模式打开 AOF：

FILE *fp = fopen(path, "r");

如果文件不存在，说明当前没有历史数据，可以直接返回成功：

if (errno == ENOENT) {
 return 0;
}

之后使用 getline() 每次读取一行：

while ((line_length = getline(&line, &capacity, fp)) != -1) {

假设读取到：

SET persist_key persist_value

之后，通过传入的回调函数执行它：

char response[1024] = {0};

int response_length = handler(
 line,
 (int)line_length,
 response
);

因为调用 kvs_aof_replay() 时传入的是：

kvs_protocol

所以这次调用实际相当于：

kvs_protocol(line, (int)line_length, response);

历史命令因此重新进入原来的协议层和业务层，不需要为重放重新写一套 SET、MOD、DEL 逻辑。

当返回值有效，并且响应为：

OK\r\n

说明这一条历史命令重放成功。否则重放失败，服务不继续启动。

10. AOF 基础闭环

AOF 阶段已经测试：

SET persist_key persist_value
MOD persist_key new_value

服务重启以后执行：

GET persist_key

能够得到：

new_value

同时，重放期间不会把历史命令再次追加到 AOF，所以文件不会随着每次重启产生重复日志。

至此，AOF 的基础闭环完成。但是如果 AOF 中存在大量历史命令，每次重启都从第一条开始执行，恢复时间会越来越长。所以接下来需要实现全量快照。

11. 开始实现全量快照

AOF 保存的是每一次成功执行的写命令，而全量快照保存的是某一个时刻内存中的完整数据集。

例如执行过：

SET name Jasper
MOD name Sao

AOF 中保存的是操作过程：

SET name Jasper
MOD name Sao

而快照只关心最终数据状态：

SET name Sao

因此，保存快照时不能简单复制 AOF。我们需要遍历当前内存中的数据，把每一个有效的 key-value 写进快照文件。

项目中存在多个 KV 引擎：

array
rbtree
hash
skiplist

每一种数据结构的遍历方式不同：

数组需要遍历每一个槽位。
红黑树需要按照节点关系递归遍历。
哈希表需要遍历桶以及桶中的链表。
跳表需要沿着最底层链表遍历。

但是持久化模块不应该知道这些数据结构的内部实现。

所以采用统一的设计：

引擎负责找到 key 和 value
→ 持久化模块负责把 key 和 value 写入文件

12. 定义统一的访问函数

在 kvstore.h 中定义访问函数类型：

typedef int (*kvs_visit_handler)(
 const char *key,
 const char *value,
 void *context
);

这个函数指针表示：

引擎每找到一组 key-value
→ 就调用一次 visitor
→ 把 key、value 和 context 交给 visitor

三个参数分别表示：

key 当前遍历到的键
value 当前遍历到的值
context 调用者额外传入的信息

每一个引擎分别提供自己的遍历函数：

int kvs_array_foreach(
 kvs_array_t *inst,
 kvs_visit_handler visitor,
 void *context
);

int kvs_rbtree_foreach(
 kvs_rbtree_t *inst,
 kvs_visit_handler visitor,
 void *context
);

int kvs_hash_foreach(
 kvs_hash_t *inst,
 kvs_visit_handler visitor,
 void *context
);

int kvs_skiplist_foreach(
 kvs_skiplist_t *inst,
 kvs_visit_handler visitor,
 void *context
);

虽然四个引擎内部的遍历方法不同，但是对外接口的形式相同。

13. foreach 的职责

以数组引擎为例：

int kvs_array_foreach(
 kvs_array_t *inst,
 kvs_visit_handler visitor,
 void *context)
{
 if (inst == NULL ||
 inst->table == NULL ||
 visitor == NULL) {
 return -1;
 }

 for (int i = 0; i < inst->total; i++) {
 if (inst->table[i].key == NULL ||
 inst->table[i].value == NULL) {
 continue;
 }

 int ret = visitor(
 inst->table[i].key,
 inst->table[i].value,
 context
 );

 if (ret < 0) {
 return -1;
 }
 }

 return 0;
}

每一次循环找到一组有效的 key-value，就调用一次：

visitor(key, value, context);

所以遍历函数本身没有耦合具体的文件写入逻辑。它只负责：

找到数据
→ 把数据交给 visitor

真正决定如何使用这些数据的是传进来的 visitor。

14. context 的意义

快照写入函数不只需要 key 和 value，它还需要知道：

应该写入哪个文件。
当前数据来自哪个引擎。
应该使用 SET、RSET、HSET 还是 SSET。

所以定义结构体：

typedef struct snapshot_write_context {
 FILE *fp;
 const char *command;
} snapshot_write_context_t;

这里：

fp 快照文件的文件指针
command 当前引擎对应的写命令

然后把这个结构体的地址作为 void *context 传入遍历函数：

snapshot_write_context_t ctx;

ctx.fp = fp;
ctx.command = "SET";

kvs_array_foreach(
 &global_array,
 snapshot_write_item,
 &ctx
);

此时 &ctx 被转换成了 void *。

进入 snapshot_write_item() 以后，再把它转换回来：

snapshot_write_context_t *ctx =
 (snapshot_write_context_t *)context;

所以 context 并不是“一个数”。它是一个通用指针，这里保存的是 ctx 这个结构体的地址。

15. 把一组 key-value 写进快照

真正负责写入文件的函数是：

static int snapshot_write_item(
 const char *key,
 const char *value,
 void *context)
{
 if (key == NULL ||
 value == NULL ||
 context == NULL) {
 return -1;
 }

 snapshot_write_context_t *ctx =
 (snapshot_write_context_t *)context;

 if (ctx->fp == NULL ||
 ctx->command == NULL) {
 return -1;
 }

 int written = fprintf(
 ctx->fp,
 "%s %s %s\n",
 ctx->command,
 key,
 value
 );

 if (written < 0) {
 return -1;
 }

 return 0;
}

例如数组引擎中存在：

name → Jasper
age → 20

调用两次 snapshot_write_item() 后，快照中会得到：

SET name Jasper
SET age 20

也就是说，每遍历到一个有效数据，就执行一次 snapshot_write_item()。

16. 为什么快照中只保存 SET 类型的命令

快照保存的是当前最终数据集，而不是数据变化的过程。

例如：

SET name Jasper
MOD name Sao
DEL age

最终只剩下：

name → Sao

所以快照只需要保存一条能够重新创建当前数据的命令：

SET name Sao

对于不同引擎，分别使用：

SET 数组引擎
RSET 红黑树引擎
HSET 哈希引擎
SSET 跳表引擎

快照不需要保存 MOD 和 DEL。因为已经被删除的数据不会出现在遍历结果中，而被修改的数据会直接以最终值保存。

17. 保存所有引擎的数据

在 snapshot.c 中访问四个全局引擎：

#if ENABLE_ARRAY
extern kvs_array_t global_array;
#endif

#if ENABLE_RBTREE
extern kvs_rbtree_t global_rbtree;
#endif

#if ENABLE_HASH
extern kvs_hash_t global_hash;
#endif

#if ENABLE_SKIPLIST
extern kvs_skiplist_t global_skiplist;
#endif

然后依次遍历已经启用的引擎：

#if ENABLE_ARRAY
if (result == 0) {
 ctx.command = "SET";

 if (kvs_array_foreach(
 &global_array,
 snapshot_write_item,
 &ctx) < 0) {
 result = -1;
 }
}
#endif

其他引擎对应的命令为：

红黑树 ctx.command = "RSET"
哈希表 ctx.command = "HSET"
跳表 ctx.command = "SSET"

result 用于记录整个快照保存过程是否成功：

0 到目前为止没有失败
-1 某一步已经失败

如果前一个引擎保存失败，后面的引擎就不再继续写。这样可以避免生成一个看起来正常、实际上缺少部分数据的快照。

18. 使用临时文件保存快照

不能直接使用：

fopen(path, "w");

覆盖原来的正式快照。因为如果写到一半时程序崩溃，旧快照已经被破坏，新快照又没有写完整。

所以先生成临时文件路径：

char temp_path[1024];

snprintf(
 temp_path,
 sizeof(temp_path),
 "%s.tmp",
 path
);

例如：

正式文件：snapshot.db
临时文件：snapshot.db.tmp

这里使用 snprintf()，是因为它可以接收缓冲区大小，避免写出的字符串超过 temp_path 的容量。

然后使用 "w" 模式打开临时文件：

FILE *fp = fopen(temp_path, "w");

"w" 表示重新写入。临时文件如果已经存在，原来的内容会被清空。

19. 把快照同步到磁盘

所有引擎遍历完成以后，依次执行：

fflush(fp)
→ fsync(fileno(fp))
→ fclose(fp)

含义与 AOF 相同：

fflush 把 C 标准库缓冲区交给操作系统
fsync 要求操作系统把内容同步到底层存储
fclose 关闭文件

如果任何一步失败：

unlink(temp_path);
return -1;

unlink(temp_path) 的意思是删除失败的临时文件，不是关闭文件。文件已经由 fclose() 负责关闭。

全部成功以后执行：

rename(temp_path, path);

这一步把：

snapshot.db.tmp

替换成：

snapshot.db

因此，快照保存过程是：

写临时文件
→ 确认完整写入
→ 同步到磁盘
→ 关闭临时文件
→ 用临时文件替换正式快照

这样可以尽量避免生成半份快照。

20. 增加 SAVE 命令

在持久化头文件中暴露快照保存接口：

int kvs_snapshot_save(const char *path);

协议层切分完 tokens 后，单独判断：

if (count == 1 && strcmp(tokens[0], "SAVE") == 0) {
 int save_result = kvs_snapshot_save("snapshot.db");

 if (save_result < 0) {
 return sprintf(response, "ERROR\r\n");
 }

 return sprintf(response, "OK\r\n");
}

用户发送：

SAVE

程序就会把当前四个引擎中的完整数据保存到 snapshot.db。

SAVE 本身不是修改 KV 数据的普通业务命令，所以不需要写进 AOF。

21. 快照与 AOF 的重复问题

如果快照已经保存了当前全部数据，而服务启动时又从 AOF 开头执行所有命令，就会出现重复恢复。

例如 AOF 中有：

SET name Jasper
MOD name Sao

快照中已经有：

SET name Sao

启动时先读取快照，内存里已经存在 name。如果又从 AOF 开头执行 SET name Jasper，就可能因为 key 已经存在而失败。

所以快照必须知道：

保存这份快照时，AOF 已经写到了哪个位置。

22. 获取 AOF 当前偏移量

在 AOF 模块中增加：

long long kvs_aof_get_offset(void);

实现过程：

long long kvs_aof_get_offset(void)
{
 if (aof_fp == NULL) {
 return -1;
 }

 off_t offset = ftello(aof_fp);

 if (offset == (off_t)-1) {
 return -1;
 }

 return (long long)offset;
}

off_t 是系统用来表示文件位置和文件大小的类型。

ftello() 返回当前文件位置，也就是 AOF 已经写了多少字节。

假设返回：

表示保存快照时，AOF 的前 189 个字节已经被这份快照包含。

23. 把 AOF 偏移量写进快照

保存快照之前先获取：

long long aof_offset = kvs_aof_get_offset();

然后把它写在快照第一行：

fprintf(fp, "AOF_OFFSET %lld\n", aof_offset);

最终快照类似：

AOF_OFFSET 189
SET persist_key new_value
SET snapshot_array value_array
RSET snapshot_rbtree value_rbtree
HSET snapshot_hash value_hash
SSET snapshot_skiplist value_skiplist

第一行是元数据，不是业务命令。后面的每一行才是用来恢复数据的命令。

24. 加载全量快照

在持久化头文件中增加：

long long kvs_snapshot_load(
 const char *path,
 aof_replay_handler handler
);

这个函数做两件事：

1. 读取并执行快照中的数据命令
2. 返回快照记录的 AOF_OFFSET

使用只读方式打开：

FILE *fp = fopen(path, "r");

如果快照文件不存在，说明以前没有保存过快照：

if (errno == ENOENT) {
 return 0;
}

返回 0 表示：

没有快照数据
→ AOF 应该从第 0 个字节开始重放

25. 读取快照中的偏移量

首先使用 getline() 读取第一行，然后解析：

long long aof_offset = -1;

int parsed = sscanf(
 line,
 "AOF_OFFSET %lld",
 &aof_offset
);

这里：

parsed 成功解析出的字段数量
aof_offset 真正保存偏移量的变量

如果第一行是：

AOF_OFFSET 189

那么：

parsed = 1
aof_offset = 189

如果没有成功读取一个偏移量，或者偏移量小于 0，就说明快照格式错误。

26. 逐行恢复快照数据

读取完第一行以后，继续使用 getline() 循环读取剩余内容：

while ((line_length = getline(&line, &capacity, fp)) != -1) {

getline() 每执行一次，就从文件当前位置读取一行。

读取完成以后，去掉末尾的换行符：

while (line_length > 0 &&
 (line[line_length - 1] == '\n' ||
 line[line_length - 1] == '\r')) {
 line[--line_length] = '\0';
}

然后准备一个响应缓冲区：

char response[1024] = {0};

把快照命令交给协议函数：

int response_length = handler(
 line,
 (int)line_length,
 response
);

因为传进来的 handler 是 kvs_protocol，所以实际效果相当于：

kvs_protocol(line, (int)line_length, response);

例如快照中的：

HSET snapshot_hash value_hash

会重新进入原来的协议解析和哈希引擎处理流程。

response 不会发送给网络客户端，它只用于检查这条恢复命令是否返回：

OK\r\n

所有快照命令恢复成功后，函数返回：

return aof_offset;

27. 让 AOF 从指定位置开始重放

AOF 重放函数的接口改成：

int kvs_aof_replay(
 const char *path,
 long long offset,
 aof_replay_handler handler
);

打开 AOF 后，先执行：

fseeko(fp, (off_t)offset, SEEK_SET);

三个参数表示：

fp 当前 AOF 文件
offset 要跳转到的字节位置
SEEK_SET 从文件开头计算位置

例如：

offset = 189

就表示跳过 AOF 前 189 个字节，只重放后面的增量命令。

这里并不是逐条判断哪些命令应该跳过，而是直接移动文件的读取位置。

28. 最终启动恢复顺序

最终启动过程变成：

初始化所有 KV 引擎
→ 进入恢复状态
→ 加载 snapshot.db
→ 得到 AOF_OFFSET
→ 从该偏移量开始重放 appendonly.aof
→ 退出恢复状态
→ 以追加模式打开 AOF
→ 启动网络服务

代码大致为：

init_kvengine();

aof_replaying = 1;

long long aof_offset = kvs_snapshot_load(
 "snapshot.db",
 kvs_protocol
);

if (aof_offset < 0) {
 aof_replaying = 0;
 fprintf(stderr, "failed to load snapshot\n");
 return -1;
}

int replay_ret = kvs_aof_replay(
 "appendonly.aof",
 aof_offset,
 kvs_protocol
);

aof_replaying = 0;

if (replay_ret < 0) {
 fprintf(stderr, "failed to replay AOF\n");
 return -1;
}

if (kvs_aof_open("appendonly.aof") < 0) {
 fprintf(stderr, "failed to open AOF\n");
 return -1;
}

这里的 aof_replaying 虽然叫做 AOF 重放状态，但是现在它实际上覆盖了整个数据恢复阶段：

加载快照期间 不允许写入 AOF
重放 AOF 期间 不允许写入 AOF

因为快照和 AOF 中的历史命令都会调用 kvs_protocol()。

如果没有这个标志，恢复出来的历史命令又会被当成新的写命令追加到 AOF。

29. 快照与 AOF 最终如何配合

可以把二者理解成：

snapshot.db 保存稳定的历史基础
appendonly.aof 保存快照之后发生的新变化

假设：

AOF 前 189 字节
→ 已经包含在 snapshot.db 中

AOF 第 189 字节以后
→ 是保存快照之后执行的新命令

恢复时：

snapshot.db
→ 恢复保存快照时的完整数据

AOF_OFFSET 之后的 AOF
→ 补上保存快照以后发生的变化

因此最后恢复出的内存状态是：

快照中的完整数据
+
快照之后的增量命令
=
服务退出前的最新数据

30. 最终验证

保存快照时的数据为：

SET persist_key new_value
SET snapshot_array value_array
RSET snapshot_rbtree value_rbtree
HSET snapshot_hash value_hash
SSET snapshot_skiplist value_skiplist

执行：

SAVE

快照记录：

AOF_OFFSET 189

保存完成以后，再执行：

SET after_snapshot from_aof

这条命令没有进入快照，只进入了 AOF 偏移量之后的增量部分。

服务重启以后，输出顺序为：

先执行快照中的五条命令
→ 再执行 SET after_snapshot from_aof
→ 最后开始监听端口

客户端执行：

GET after_snapshot

能够得到：

from_aof

这说明：

全量快照恢复成功
AOF 增量恢复成功
偏移量跳过成功
恢复期间没有重复写入 AOF

31. 当前完成的整体闭环

目前已经完成的混合持久化流程是：

正常运行
→ 成功的写命令立即追加到 AOF
→ 用户执行 SAVE
→ 遍历所有引擎
→ 保存当前完整数据集
→ 在快照中记录 AOF_OFFSET
→ 快照保存后继续记录新的 AOF
→ 服务退出或者崩溃
→ 下次启动先加载快照
→ 再重放 AOF_OFFSET 之后的日志
→ 恢复出最新内存数据
→ 开始对外提供服务

我的理解是：

AOF 负责尽量不丢掉每一次数据变化

快照负责保存某一时刻完整的数据集，
并缩短启动时需要处理的历史范围

AOF_OFFSET 负责把快照和 AOF 连接起来

aof_replaying 负责避免恢复过程再次产生日志

handler 负责让历史命令复用原来的业务处理流程

foreach 负责遍历不同引擎中的有效数据

visitor 负责处理遍历得到的每一组 key-value

context 负责向 visitor 传递文件指针和命令类型

至此，全量快照和 AOF 增量日志已经组成了一个完整的混合持久化闭环。

KV 进化（一）：给 91kvstore 接上一条跳表

Fri, 28 Aug 2026 00:00:00 +0800

这篇不打算深挖跳表算法，而是记录一个外部数据结构如何从“能够独立运行”，一步步变成 91kvstore 中真正可用的存储引擎。

目前这个 KV 存储引擎已经支持三种数据结构：

结构体数组
红黑树
哈希表

那么问题来了：能不能再加入一种新的存储引擎，并且让它像现有的三个引擎一样，通过统一接口和网络命令工作？

这次选择的是——跳表。

最终希望实现这样的效果：

SSET name Jasper
SGET name
SMOD name Sao
SEXIST name
SDEL name

表面上看，只是多写一个 kvs_skiplist.c；但真正有价值的部分并不是手搓跳表，而是研究如何把一个外部数据结构完整地融合进现有项目。

先对跳表有个大致印象

开始之前，我先看了一些简短的跳表介绍，比如这个视频：

B站：跳表相关介绍

现在并不打算深入研究跳表的每一个概率细节，只需要先形成几个基本认知：

跳表的底层仍然是一条有序链表；
它在普通链表上增加了多层索引；
查询时可以从高层快速跳过大量节点；
查找、插入、删除的平均时间复杂度是 O(log n)。

在工程中使用一种数据结构时，确实可以把它当成一个黑盒，但也不能完全不理解。至少要知道：

它需要什么样的输入；
它如何管理内存；
它能提供哪些操作；
它的节点和数据由谁创建、由谁释放。

理解到这个程度，就足够开始融合了。

写跳表之前，我先整理了项目

我多少有点目录洁癖。

原来的 .c、.o、可执行文件和头文件全部堆在项目根目录，看着实在难受。因此没有立刻开始写跳表，而是先参照常见开源项目的结构，把工程重新整理了一遍：

91kvstore/
├── .gitignore
├── .gitmodules
├── Makefile
│
├── clients/
│ ├── go-kvstore.go
│ ├── javakvstore.java
│ ├── js-kvstore.js
│ ├── py-kvstore.py
│ └── rust-kvstore.rs
│
├── include/
│ ├── kvstore.h
│ └── server.h
│
├── src/
│ ├── kvstore.c
│ ├── engines/
│ │ ├── kvs_array.c
│ │ ├── kvs_hash.c
│ │ ├── kvs_rbtree.c
│ │ └── kvs_skiplist.c
│ │
│ └── network/
│ ├── ntyco.c
│ ├── proactor.c
│ └── reactor.c
│
├── tests/
│ └── testcase.c
│
├── third_party/
│ └── NtyCo/ # Git 子模块
│
├── build/ # 编译产物，不提交
│ ├── kvstore.o
│ ├── reactor.o
│ ├── proactor.o
│ ├── ntyco.o
│ ├── kvs_array.o
│ ├── kvs_hash.o
│ ├── kvs_rbtree.o
│ └── kvs_skiplist.o
│
└── bin/ # 可执行文件，不提交
 ├── kvstore
 └── testcase

这样一来，各部分的职责就很直观：

include/ 放公共声明；
src/engines/ 放存储引擎；
src/network/ 放网络模型；
tests/ 放测试程序；
third_party/ 放第三方依赖；
build/ 和 bin/ 只保存编译产物。

规整多了，right？

第一步：把整数跳表改造成字符串 KV

找到的简易跳表实现只支持：

int key;
int value;

但 KV 存储引擎需要的是：

char *key;
char *value;

因此节点最终变成：

typedef struct kvs_skiplist_node {
 char *key;
 char *value;
 struct kvs_skiplist_node **forward;
} kvs_skiplist_node_t;

这里不只是把 int 改成 char * 那么简单。

整数可以直接比较：

node->key < key

字符串必须使用：

strcmp(node->key, key) < 0

同时，字符串不能只保存调用方传进来的地址。节点需要为 key 和 value 单独申请内存并复制内容，否则调用方的字符串失效后，跳表里保存的指针也会失效。

创建一个节点，大致需要依次完成：

为节点结构体申请内存；
为 key 申请内存；
复制 key；
为 value 申请内存；
复制 value；
为每层 forward 指针申请空间。

每一步都可能失败。

如果中途失败，就必须把前面已经申请成功的内存释放掉。否则节点虽然没有创建成功，却会留下内存泄漏。

这部分看起来啰嗦，但它实际上比跳表算法本身更接近真实的 C 工程开发。

第二步：补齐统一接口

原始代码只有插入、查询和展示，但项目中的每个存储引擎都需要提供七个接口：

kvs_skiplist_create
kvs_skiplist_destory
kvs_skiplist_set
kvs_skiplist_get
kvs_skiplist_del
kvs_skiplist_mod
kvs_skiplist_exist

其中比较复杂的是：

set：查找插入位置，并更新多层指针；
get：沿索引层逐级查找；
del：不仅要释放节点，还必须先从每一层中摘除节点。

mod 和 exist 相对简单，因为它们都可以复用内部查询函数：

static kvs_skiplist_node_t *
skiplist_search_node(kvs_skiplist_t *inst, const char *key);

exist 只需要判断查询结果是否为 NULL。

mod 则是在找到节点后，先申请并复制新的 value；成功之后再释放旧 value。这个顺序非常重要：

先申请新内存
 ↓
申请成功
 ↓
释放旧 value
 ↓
替换指针

如果先释放旧 value，再发现新内存申请失败，原来的数据也就丢了。

第三步：统一返回值

接口能工作还不够，它必须遵守现有引擎的返回规则。

最终统一为：

返回值	含义
`0`	操作成功，或者 key 存在
`1`	key 重复，或者 key 不存在
`-1`	参数或实例不合法
`-2`	内存申请失败

具体含义需要结合接口理解。

例如：

kvs_skiplist_set(...)

返回 1 表示 key 已经存在。

而：

kvs_skiplist_del(...)

返回 1 表示 key 不存在。

统一返回规则非常重要，因为协议层并不关心跳表内部发生了什么，它只根据返回值生成响应：

0 → OK
1 → EXIST 或 NO EXIST
< 0 → ERROR

第四步：别让测试变成纯苦力

最开始，每修改一个函数，就在 main() 中增加一堆 if/else，重新编译、运行、检查输出。

写到后面发现，大量测试代码无非是在做：

实际返回值是否等于预期返回值？

于是写了一个辅助函数：

static void check_test(int condition, const char *testName)
{
 if (condition) {
 printf("[PASS] %s\n", testName);
 } else {
 printf("[FAIL] %s\n", testName);
 }
}

测试就能简化为：

result = kvs_skiplist_set(
 skipList,
 "Dad",
 "Jasper"
);

check_test(
 result == 0,
 "set new key"
);

开发接口期间，可以先用 #if 0 屏蔽 main()，每完成一批接口只进行对象文件编译：

gcc -Iinclude \
 -c src/engines/kvs_skiplist.c \
 -o /tmp/kvs_skiplist.o

等全部接口完成后，再临时启用 main()，统一进行一次完整测试。

这样既能及时发现编译错误，也不用每改一个函数就维护一遍测试流程。

第五步：从“能运行”走向“融入项目”

底层接口通过测试，只能说明跳表自己能工作。接下来才是真正的工程融合。

首先，把公共内容移动到 include/kvstore.h：

最大层数定义；
跳表节点类型；
跳表实例类型；
七个公开接口声明。

而这些内部辅助函数仍然留在 .c 文件中，并使用 static 隐藏：

skiplist_create_node
skiplist_random_level
skiplist_search_node

这样外部模块只知道跳表“能做什么”，不需要知道它“具体怎么做”。

接着，把直接使用的：

malloc
free

替换为项目统一封装的：

kvs_malloc
kvs_free

再把：

build/kvs_skiplist.o

加入 Makefile，让跳表参与整个项目的编译与链接。

Makefile 的具体语法还需要继续学习，但目前已经能看懂它最核心的关系：

源文件
 ↓ 编译
对象文件
 ↓ 链接
可执行文件

第六步：创建全局跳表实例

服务器需要一个长期存在的跳表实例，保存所有客户端写入的数据。

因此在 kvs_skiplist.c 中定义：

kvs_skiplist_t global_skiplist;

在 kvstore.c 中声明：

extern kvs_skiplist_t global_skiplist;

这里的 extern 并不会创建第二个跳表，它只是告诉 kvstore.c：

这个变量在其他文件中已经定义，你可以直接使用它。

然后把跳表加入存储引擎生命周期：

kvs_skiplist_create(&global_skiplist);

服务器退出时：

kvs_skiplist_destory(&global_skiplist);

至此，跳表拥有了完整的生命过程：

定义 → 初始化 → 处理请求 → 销毁

第七步：命令协议融合

最后，也是最关键的一步，是让客户端真的能够使用跳表。

加入五条新命令：

SSET
SGET
SDEL
SMOD
SEXIST

项目并不存在一个“当前使用哪个 engine”的开关，而是通过命令前缀直接选择引擎：

SET → array
RSET → rbtree
HSET → hash
SSET → skiplist

例如客户端发送：

SSET Dad Jasper

服务器的处理过程是：

解析 SSET
 ↓
匹配 KVS_CMD_SSET
 ↓
进入 switch 对应分支
 ↓
调用 kvs_skiplist_set()
 ↓
根据返回值生成 OK / EXIST / ERROR

这一步完成后，跳表就不再是一个孤立的 .c 文件，而是真正成为了 KV 存储引擎的一员。

最后：用 testcase 做端到端测试

底层 main() 测试的是跳表接口，而 tests/testcase.c 测试的是完整链路：

测试客户端
 → TCP
 → 网络层
 → 协议解析
 → global_skiplist
 → 跳表接口
 → 协议响应

测试程序会自动发送：

SSET
SGET
SEXIST
SMOD
SDEL

然后将服务器的实际响应与预期结果比较：

相同 → PASS
不同 → FAILED

相比手动输入命令，这种测试不仅省事，还能在后续修改代码时快速确认：跳表功能有没有被意外破坏。

小结

这次表面上是在“增加一个跳表”，实际上完整经历了一个新模块接入现有项目的过程：

选择基础实现
 → 改造成字符串 KV
 → 补齐统一接口
 → 统一返回规则
 → 完成底层测试
 → 暴露公共声明
 → 接入内存管理
 → 接入 Makefile
 → 创建全局实例
 → 接入生命周期
 → 接入命令协议
 → 完成端到端测试

跳表算法当然重要，但这次更重要的收获是：

一个数据结构能独立运行，和它能成为项目中真正可用的一部分，是两件完全不同的事。

前者解决算法问题，后者解决接口、内存、构建、生命周期、协议和测试问题。

而后面这些，才是这次“KV 进化”真正有意思的地方。

KV 存储项目：Hash 接入、多语言客户端与 SkipList 扩展

Wed, 26 Aug 2026 00:00:00 +0800

阅读目标：在已有 Array、RBTree 和统一协议的基础上，重点复盘 Hash 如何真正成为一个可用的 KV 引擎；随后理解多语言客户端与服务端的边界，并按同一套接入模式继续扩展 SkipList。

本文不讲 Hash 数据结构算法本身，重点是 Hash 与现有 KV 项目的融合。

与前三篇的关系

本文承接以下三篇已有笔记：

《KV 存储项目网络层》已经讲过 Reactor、Proactor、NtyCo 和 msg_handler 回调。
《KV 存储项目：协议层与数组存储》已经讲过 TCP 消息边界、token 解析、协议响应和 Array 的五种操作。
《KV 存储项目：客户端测试、压力测试与多引擎扩展》已经讲过 Makefile 基础、测试用例、压力测试、宏开关、5+2 接口以及 RBTree 的接入模式。

因此本文不再重复网络收发、协议解析、Array/RBTree CRUD、通用测试方法和 5+2 的基础概念，只保留理解 Hash 接入所需的连接点。

1. 本阶段增加了什么

项目之前已经完成：

统一网络入口
 → 文本协议解析
 → Array 引擎
 → RBTree 引擎
 → 客户端测试和压力测试

本阶段增加三项能力：

1. 把 Hash 接入现有 KVEngine
2. 用 Go / Java / Node.js / Python / Rust 操作同一个 KV 服务
3. 按相同模式接入 SkipList，并为范围查询做准备

Hash 部分最值得掌握的不是“冲突链表怎样写”，而是：已经有一份 Hash 代码以后，还要修改项目的哪些位置，它才能从客户端真正访问到？

类型与接口声明
 → 编译和链接
 → 全局实例
 → create 初始化
 → 协议命令分发
 → set/get/del/mod/exist
 → 客户端测试
 → destroy 释放

任何一环缺失，Hash 都没有完整融入项目。

2. Hash 在项目中的位置

Hash 接入后，核心关系变成：

 kvs_protocol()
 │
 kvs_filter_protocol()
 │
 ┌─────────────────┼─────────────────┐
 │ │ │
 Array RBTree Hash
 普通命令前缀 R 命令前缀 H 命令前缀
 │ │ │
 global_array global_rbtree global_hash

网络层仍然只调用 kvs_protocol()，不需要为了 Hash 修改 Reactor、Proactor 或 NtyCo。

协议层也不需要知道桶、哈希下标和冲突链表，只负责把 Hash 命令映射到 kvs_hash_set/get/del/mod/exist。

这体现了已有分层设计带来的扩展性：新增存储引擎，主要修改核心层和构建层，不侵入网络层。

3. 第一个接入点：`kvstore.h`

3.1 增加编译开关

#define ENABLE_HASH 1

它应当像 ENABLE_ARRAY、ENABLE_RBTREE 一样，控制以下内容是否参与编译：

Hash 类型定义；
Hash 函数声明与实现；
global_hash；
Hash 协议分支；
Hash 的初始化与销毁。

宏开关的目的不是只隐藏一个结构体，而是完整地装上或拆下整个引擎。

3.2 Hash 实例在项目中的最小理解

typedef struct hashnode_s {
 char *key;
 char *value;
 struct hashnode_s *next;
} hashnode_t;

typedef struct hashtable_s {
 hashnode_t **nodes;
 int max_slots;
 int count;
} kvs_hash_t;

从 KV 项目角度只需知道：

global_hash
├── nodes 桶数组，每个元素是一条冲突链的头指针
├── max_slots 桶数量
└── count 当前键值对数量

nodes 是二级指针，因为它先表示桶数组，再由每个桶元素指向节点：

nodes[0] → node → node → NULL
nodes[1] → NULL
nodes[2] → node → NULL

发生 Hash 冲突时，相同桶下标的节点通过 next 串在一起。这里只把它作为理解资源释放和实例生命周期的前提，不展开 Hash 算法。

3.3 对外仍然使用已有的 5+2 形状

int kvs_hash_create(kvs_hash_t *hash);
void kvs_hash_destroy(kvs_hash_t *hash);
int kvs_hash_set(kvs_hash_t *hash, char *key, char *value);
char *kvs_hash_get(kvs_hash_t *hash, char *key);
int kvs_hash_del(kvs_hash_t *hash, char *key);
int kvs_hash_mod(kvs_hash_t *hash, char *key, char *value);
int kvs_hash_exist(kvs_hash_t *hash, char *key);

5+2 的设计价值和 RBTree 接入方式已在上一篇说明。这里的新增认识是：Hash 内部可以完全不同，但仍然服从项目已经形成的引擎契约。

4. 第二个接入点：Makefile

本阶段开始把每个 .c 文件单独编译成 .o。Hash 必须进入对象文件集合：

OBJS = kvstore.o reactor.o proactor.o kvs_array.o \
 ntyco.o kvs_rbtree.o kvs_hash.o

kvs_hash.o: kvs_hash.c kvstore.h
	$(CC) $(CPPFLAGS) $(CFLAGS) -c kvs_hash.c -o kvs_hash.o

kvstore: $(OBJS)
	$(CC) -o $@ $(OBJS) $(LDFLAGS) $(LDLIBS)

原笔记中的 OBJS 没有 kvs_hash.o。这意味着即使 kvs_hash.c 已经写好，最终的 kvstore 也没有编译、链接 Hash 实现。

建议把参数按职责拆开：

CC = gcc
CPPFLAGS = -I./NtyCo/core
CFLAGS = -Wall -Wextra -g
LDFLAGS = -L./NtyCo
LDLIBS = -luring -lntyco -lpthread -ldl

相对上一篇 Makefile 笔记，本阶段只需新增一个检查点：

每增加一个 KV 引擎，都要确认它的目标文件同时进入编译规则和最终的 OBJS 链接集合。

如果还要分别生成 kvstore、NtyCo 库和 testcase，可设为三个明确目标：

.PHONY: all ntyco clean

all: ntyco kvstore testcase

ntyco:
	$(MAKE) -C NtyCo

testcase 应有自己的对象文件和链接规则，不要与服务端的 main() 混在同一个目标中。

5. 第三个接入点：实例生命周期

5.1 定义全局实例

#if ENABLE_HASH
static kvs_hash_t global_hash;
#endif

它与已有的 global_array、global_rbtree 并列，是 Hash 引擎在当前进程中的状态容器。

5.2 网络服务启动前创建

#if ENABLE_HASH
if (kvs_hash_create(&global_hash) != 0) {
 /* 初始化失败，不能继续提供 Hash 命令 */
}
#endif

必须先创建引擎，再进入网络循环。否则客户端已经能够发来 HSET，协议层却会访问尚未初始化的桶数组。

5.3 网络服务停止后销毁

#if ENABLE_HASH
kvs_hash_destroy(&global_hash);
#endif

完整顺序为：

创建 Array / RBTree / Hash
 ↓
启动所选网络层
 ↓
处理客户端命令
 ↓
网络层退出
 ↓
销毁 Hash / RBTree / Array

如果网络启动函数永不返回，还需要设计退出信号和优雅关闭流程，否则 destroy 虽然写在 main() 中，正常运行时却永远不会执行。

6. 第四个接入点：协议命令

上一篇已经为 RBTree 增加 RSET/RGET/RDEL/RMOD/REXIST。教学阶段为了让多个引擎同时存在，可以继续采用同一规则：

Array	RBTree	Hash	语义
`SET`	`RSET`	`HSET`	新增键值对
`GET`	`RGET`	`HGET`	查询 value
`DEL`	`RDEL`	`HDEL`	删除键值对
`MOD`	`RMOD`	`HMOD`	修改已有 value
`EXIST`	`REXIST`	`HEXIST`	判断 key 是否存在

协议层识别到 HSET 后调用：

kvs_hash_set(&global_hash, tokens[1], tokens[2]);

其余命令同理。协议层负责将引擎内部返回值翻译成项目已有响应：

OK\r\n
EXIST\r\n
NO EXIST\r\n
具体 value\r\n
ERROR\r\n

需要保持的边界是：

协议层：参数数量、命令选择、响应文本
Hash 层：key/value 保存、查询、修改、删除、资源管理

协议层不能直接访问 global_hash.nodes，否则 Hash 内部实现一改，协议代码也必须跟着改，统一接口就失去了意义。

一条 `HSET` 的新增路径

前三篇已经讲过网络路径和 SET 完整路径，此处只看 Hash 分支的差异：

HSET Teacher King
 → 协议层识别 HSET
 → 检查 token 数量为 3
 → kvs_hash_set(&global_hash, "Teacher", "King")
 → 返回内部状态码
 → 协议层生成 OK / EXIST / ERROR

从网络层到 token 切分的部分与以前完全相同，不需要为 Hash 重写。

7. 当前 Hash 代码必须修正的工程问题

这些问题的重点是内存所有权和项目稳定性，而不是 Hash 算法。

7.1 创建后必须把桶数组清零

hash->nodes = kvs_malloc(sizeof(hashnode_t *) * hash->max_slots);
memset(hash->nodes, 0,
 sizeof(hashnode_t *) * hash->max_slots);

kvs_malloc 返回的内存默认包含不确定值。不清零时，第一次读取 hash->nodes[idx] 就可能取得随机地址。

7.2 下标计算应使用实例容量

当前各操作固定使用 MAX_TABLE_SIZE：

int idx = _hash(key, MAX_TABLE_SIZE);

应改为：

int idx = _hash(key, hash->max_slots);

否则 max_slots 字段形同虚设，将来改变容量或扩容时也会出错。

7.3 创建节点失败要逆序回滚

指针模式下，一个节点的申请顺序是：

node → key 副本 → value 副本

如果 value 申请失败，必须释放已经成功申请的 key 和 node。当前代码释放的是本来就为 NULL 的 kvalue，遗漏了前两块内存。

kvs_hash_set() 也要判断 _create_node() 是否返回 NULL，不能直接执行 new_node->next。

7.4 三条释放路径必须一致

开启 ENABLE_KEY_POINTER 后，一个节点拥有三块内存：

node
├── key
└── value

以下三条路径都必须依次释放 key、value、node：

删除桶的头节点；
删除桶内的普通节点；
销毁整张 Hash 表。

当前普通节点删除路径释放完整，但头节点删除和 destroy 只释放了 node，会发生内存泄漏。

7.5 MOD 要先申请，再替换

当前代码先 free(node->value)，然后申请新 value。如果申请失败，旧值已经丢失，节点中还留下悬空指针。

安全顺序是：

申请新 value
 → 复制成功
 → 保存 old_value
 → node->value = new_value
 → free(old_value)

这样内存申请失败时，旧值仍然有效。

7.6 其他接口一致性问题

kvs_hash_mod() 还要检查 value != NULL。
固定数组模式下，strncpy 后必须保证字符串以 \0 结束。
kvs_hash_count() 已实现，但头文件中缺少声明。
destory 应逐步统一为正确拼写 destroy。
kvs_hash_set() 的参数类型建议统一写成 kvs_hash_t *。
exist 的 0=存在、1=不存在 必须与 Array、RBTree 和协议响应保持一致。
销毁后应将 nodes=NULL、max_slots=0、count=0，降低误用风险。

8. 多语言支持：本阶段新增的认识

上一篇已经介绍过 TCP 客户端测试，第二篇也解释过消息边界，因此这里不再重复 socket 收发和粘包、拆包原理。

本阶段要建立的新认识是：

Go、Java、Node.js、Python 和 Rust 并不直接调用 C 的 Hash 函数；它们都是同一个文本协议的客户端。

语言	TCP 客户端 API	发出的内容
Go	`net.Dial`	UTF-8 协议文本
Java	`Socket`	UTF-8 协议文本
Node.js	`net.createConnection`	UTF-8 协议文本
Python	`socket.socket`	UTF-8 协议文本
Rust	`TcpStream`	UTF-8 协议文本

五种语言的差异只在 socket API，服务端看到的都应该是：

HSET Teacher King\r\n
HGET Teacher\r\n

因此“支持第三方语言”的核心不是编写五套服务端适配层，而是稳定以下契约：

服务器地址和端口；
UTF-8 编码；
请求结束标记；
命令名称和参数数量；
响应格式；
连接是单请求、长连接还是支持流水线；
超时与异常处理方式。

原示例中的 IP 地址有两组：172.16.145.132 和 192.168.243.131，实际测试时应统一为配置项。

用同一场景验证五种语言

不要让五份示例各自测试不同命令。它们应执行同一条状态链：

HSET lang:test C → OK
HGET lang:test → C
HMOD lang:test common → OK
HGET lang:test → common
HEXIST lang:test → EXIST
HDEL lang:test → OK
HGET lang:test → NO EXIST

这样验证的是“协议与 Hash 引擎对所有语言行为一致”，而不只是证明五种语言都能建立 TCP 连接。

正式测试还应给每个客户端加入：

send_all/write_all 语义，防止一次发送没有写完；
按 \r\n 或长度字段读取完整响应；
连接和读取超时；
非 UTF-8 或异常响应处理；
失败时返回非零退出码，便于自动化测试发现失败。

9. 课后扩展：把 SkipList 融入 KVEngine

通常称为 Skip List（跳表），不是 SkipTable。

这道动手题可以直接复用 Hash、RBTree 的接入模板：

1. kvstore.h 增加 ENABLE_SKIPLIST
2. 定义 kvs_skiplist_t
3. 声明 SkipList 的 5+2 接口
4. 新增 kvs_skiplist.c
5. Makefile 加入 kvs_skiplist.o
6. 核心层定义 global_skiplist
7. 启动时 create，退出时 destroy
8. 协议层增加 SSET/SGET/SDEL/SMOD/SEXIST
9. 复制已有状态链，编写 SkipList 端到端测试
10. 检查失败回滚、删除和销毁时的内存所有权

这能完成“把 SkipList 当作普通 KV 引擎接入”，但还没有发挥它的有序性。

9.1 范围查询需要扩展 5+2

原有 5+2 只表达单个 key 的操作，不能表达范围查询。可以增加：

int kvs_skiplist_range(
 kvs_skiplist_t *inst,
 const char *start_key,
 const char *end_key,
 kvs_pair_t *out,
 size_t capacity,
 size_t *count
);

协议层增加：

SRANGE user:100 user:200 LIMIT 50

设计范围接口时要明确：

起止 key 是否包含；
key 按字符串还是数值排序；
最大结果数量；
输出缓冲区由谁分配和释放；
大结果集如何分页；
遍历期间发生修改时怎样保证一致性。

Hash 适合精确点查，但没有顺序；SkipList 和 RBTree 保持 key 有序，更适合范围查询。

10. 面试题

10.1 KV 存储为什么常采用单线程执行命令？

首先修正问题前提：KV 存储不是必须使用单线程。

教学项目或某些内存 KV 的核心命令路径采用单线程，主要因为：

非阻塞 I/O 可以让一个事件循环管理大量连接；
内存 KV 的单次操作通常很短；
串行执行避免共享数据上的锁竞争；
不需要频繁进行线程上下文切换；
命令顺序和数据一致性更容易理解与调试。

它的限制也很明显：慢命令会阻塞后续请求，CPU 密集型任务无法充分利用多核，单实例吞吐最终受单核限制。

常见扩展方式是按 key 分片，每个分片由单线程串行执行，多个分片并行利用多核；也可以让网络 I/O、持久化、内存回收由不同线程负责。

结合当前项目回答时还要看所选网络模型：如果多个线程可能同时调用协议处理函数并访问同一个 global_hash，Hash 就需要互斥锁、分片锁或单写者队列。不能因为包含了 pthread.h，就认为数据已经线程安全。

10.2 范围查询应选择什么 KVEngine？

范围查询要求 key 有序：

引擎	范围查询特点
Hash	无序，适合点查，不适合直接做范围查询
SkipList	定位起点后沿底层链表扫描，适合本项目扩展
RBTree	中序遍历有序，也能实现范围查询
B/B+Tree	适合磁盘页和大规模范围扫描
LSM-Tree	适合高写入吞吐的持久化 KV

本项目的课后题应优先使用 SkipList，并在原有 5+2 之外增加 RANGE 接口。

10.3 频繁 malloc/free 时怎样管理 KV 内存？

当前项目已经通过 kvs_malloc/kvs_free 留出了统一入口。后续可以逐步演进：

在包装层统计分配次数、字节数、峰值和泄漏。
对固定大小的节点使用对象池或 slab。
对不同长度的 key/value 使用 size class 和空闲链表。
一次申请大块内存，再切成多个小对象复用。
多线程下使用线程本地缓存或分片内存池，降低锁竞争。
修改 value 时，如果旧缓冲区容量足够就复用；否则先申请新块，成功后再替换。
设置最大内存、淘汰策略并监控碎片率。

内存池解决的是性能和碎片问题，不能替代正确的所有权规则。无论使用系统分配器还是内存池，都必须明确：谁申请、谁持有、谁释放，以及失败时如何回滚。

11. 本阶段的实施顺序

统一 Hash 返回值与其他引擎的语义
 → 修正初始化、失败回滚、MOD 和三条释放路径
 → Makefile 加入 kvs_hash.o
 → 添加 global_hash 的 create/destroy
 → 协议层增加 HSET/HGET/HDEL/HMOD/HEXIST
 → 复用上一篇测试状态链验证 Hash
 → 五种语言运行完全相同的协议用例
 → 按相同模板接入 SkipList
 → 单独设计 RANGE 接口和测试
 → 压测后再决定分片、加锁和内存池方案

总结

本阶段相对于前三篇真正新增的主线是：

Hash 实现
 → 用统一接口包装
 → 进入 Makefile
 → 进入全局生命周期
 → 进入协议分发
 → 被同一测试链验证
 → 通过统一 TCP 协议服务五种语言

最重要的认识是：

项目扩展的重点不是孤立地增加一种数据结构，而是把它组织成符合现有接口、生命周期、协议和测试约定的 KV 引擎。

SkipList 的课后扩展也应遵循同一思路；只有范围查询属于新的业务能力，需要在原有 5+2 之外明确增加接口。

KV 存储项目：客户端测试、压力测试与多引擎扩展

Tue, 25 Aug 2026 00:00:00 +0800

阅读目标：沿着“建立可重复的测试—用压力测试暴露状态问题—在现有协议后接入第二种 KV 引擎”这条主线，回顾项目从数组存储继续向多引擎结构演进的过程。

本文承接 KV 存储项目网络层：统一接入 Reactor、Proactor 与协程和 KV 存储项目：协议层与数组存储。网络层的 Reactor、Proactor、ntyco，以及 kvs_protocol()、token 切分、数组五种操作等内容，前文已经完整讲过，这里只保留理解本阶段所需的连接点。

本文以学习笔记和当前代码为准，重点解释实现过程、测试现象与架构关系，不展开红黑树算法本身。

1. 这一阶段解决什么问题

前一阶段已经形成了一条可以工作的请求链路：

客户端发送文本命令
 ↓
网络层接收数据
 ↓
kvs_protocol() 切分 token
 ↓
kvs_filter_protocol() 识别命令
 ↓
数组引擎执行 SET / GET / DEL / MOD / EXIST
 ↓
协议层生成 OK / EXIST / NO EXIST / value
 ↓
网络层把响应发回客户端

项目能处理命令以后，下一步不只是继续添加代码，而是先回答三个问题：

已有功能能否被稳定、重复地验证？
测试次数增加后，内部状态是否仍然正确？
协议层能否在数组之外接入新的存储引擎？

所以本阶段的主线是：

Makefile 统一构建
 ↓
TCP 客户端实现自动化功能测试
 ↓
重复执行测试并粗测 QPS
 ↓
通过高次数测试定位数组状态问题
 ↓
保留原有数组引擎，接入红黑树引擎
 ↓
用同一组语义测试第二种引擎

这里体现了一种项目迭代思路：先观察当前代码已经处于什么形态，再决定下一项功能应该接入哪一层。

2. 用 Makefile 固定构建过程

随着源文件增加，手工重复输入完整的 gcc 命令会越来越不方便。最初可以直接把编译过程写进 all：

all:
	gcc -o kvstore kvstore.c reactor.c proactor.c kvs_array.c ntyco.c \
		-I ./NtyCo/core/ -L ./NtyCo/ -luring -lntyco

clean:
	rm -rf kvstore

这条命令由四部分组成：

部分	当前内容	作用
编译器	`gcc`	编译并链接 C 程序
target	`kvstore`	最终生成的程序
sources	`kvstore.c` 等	参加编译的源文件
flags	`-I`、`-L`、`-l`	指定头文件、库目录和链接库

把这些部分提取成变量后，Makefile 中各项职责更清楚：

CC=gcc
TARGET = kvstore
SRCS = kvstore.c reactor.c proactor.c kvs_array.c ntyco.c kvs_rbtree.c
INC = -I ./NtyCo/core/
LIBS = -L ./NtyCo/ -luring -lntyco

all:
	$(CC) -o $(TARGET) $(SRCS) $(INC) $(LIBS)

clean:
	rm -rf kvstore

当前阶段加入红黑树后，构建层面的变化很小：在 SRCS 中加入 kvs_rbtree.c。也就是说，存储引擎虽然增加了，但整个项目仍由同一个 target 统一构建。

2.1 NtyCo 是项目的外部依赖

INC 和 LIBS 都引用了 ./NtyCo/：

INC → ./NtyCo/core/ 中的头文件
LIBS → ./NtyCo/ 中的 libntyco

因此，Makefile 描述的是“依赖已经存在时怎样编译”。如果本地没有 NtyCo 目录，还要先完成依赖准备，也就是把对应代码下载到项目约定的位置，再进行编译。

这可以把构建理解成两个阶段：

准备第三方依赖
 ↓
编译当前项目

Makefile 的价值不只在于少输入一条命令，更重要的是把当前项目由哪些文件、头文件路径和库组成固定下来。

3. 客户端测试用例：把人工验证变成固定流程

测试客户端的基本流程很直接：

1. 建立 TCP 连接
2. 发送一条协议命令
3. 接收服务端响应
4. 将实际响应与预期响应比较
5. 一致则 PASS，不一致则 FAILED

测试代码把这五步拆成几个职责单一的函数：

函数	作用
`connect_tcpserver()`	创建 socket，并连接指定 IP 和端口
`send_msg()`	发送一条测试命令
`recv_msg()`	接收服务端返回值
`testcase()`	完成一次“发送—接收—比较”
`array_testcase()`	组织数组引擎的一组功能场景
`rbtree_testcase()`	组织红黑树引擎的一组功能场景

代码中的注释“一个函数只做一件事”在这里得到了体现：网络连接、一次断言和一组业务场景分别由不同函数承担。

3.1 一个测试用例包含什么

testcase() 接收四项信息：

void testcase(int connfd, char *msg, char *pattern, char *casename)

它们分别表示：

参数	含义	示例
`connfd`	已连接的 TCP socket	与 KV 服务端的连接
`msg`	发给服务端的命令	`SET Dad Jasper`
`pattern`	期望得到的响应	`OK\r\n`
`casename`	用于输出的测试名称	`SET-Dad`

测试执行过程可以压缩为：

msg ──send──> KV 服务端
 │
 └── response ──recv──> result
 │
 strcmp(result, pattern)
 │ │
 相同 不同
 │ │
 PASS FAILED

因此，测试用例并不需要知道数组或红黑树内部怎样保存数据。它只站在客户端角度检查协议行为，这正好覆盖了完整链路：

TCP 收发 + 协议解析 + 引擎操作 + 响应生成

4. 一组完整场景不只是“五条命令”

项目一共有五种基础操作：

SET / GET / DEL / MOD / EXIST

但“覆盖五个命令”不等于每个命令只执行一次。当前 array_testcase() 实际组织了九个连续步骤：

顺序	请求	预期响应	验证的状态
1	`SET Dad Jasper`	`OK`	新键可以写入
2	`GET Dad`	`Jasper`	写入后的值可以读出
3	`MOD Dad Sao`	`OK`	已存在的键可以修改
4	`GET Dad`	`Sao`	修改结果已经生效
5	`EXIST Dad`	`EXIST`	已存在的键能被识别
6	`DEL Dad`	`OK`	已存在的键可以删除
7	`GET Dad`	`NO EXIST`	删除后无法再读取
8	`MOD Dad Jasper`	`NO EXIST`	删除后无法再修改
9	`EXIST Dad`	`NO EXIST`	删除后状态确实不存在

这九步不是彼此独立的命令，而是一条状态变化链：

不存在
 │ SET
 ▼
Dad = Jasper
 │ MOD
 ▼
Dad = Sao
 │ DEL
 ▼
不存在

测试在每个关键状态后使用 GET 或 EXIST 进行确认。这样不仅验证命令返回了什么，还验证前一条命令是否真正改变了存储状态。

4.1 测试覆盖的两个方向

当前场景同时覆盖：

正向结果：写入成功、读取成功、修改成功、存在、删除成功；
反向结果：删除后读取、修改和判断存在均返回 NO EXIST。

“尽量覆盖项目所有结果，目标达到 90% 以上”可以理解为：不仅让每个函数运行一次，还要让函数中的主要结果分支都被执行到。对于协议层而言，要关注的结果包括：

OK
EXIST
NO EXIST
ERROR
具体 value

测试用例会贯穿后续项目：新增命令、新增引擎或调整内部结构以后，都可以重复运行同一套预期，确认原有行为仍然成立。这就是回归测试的作用。

5. 从功能测试扩展到压力测试

功能测试回答的是：

一组操作的结果是否正确？

压力测试进一步回答：

同一组操作重复很多次以后，结果是否仍然正确？大约能处理多少请求？

array_testcase_10w() 将九条命令循环执行：

int count = 10000;

for (i = 0; i < count; i++) {
 /* 每轮执行 9 条请求 */
}

所以请求总数为：

10000 轮 × 9 条/轮 = 90000 条请求

计时使用 gettimeofday()：

tv_begin：循环开始时间
tv_end：循环结束时间
time_used：两者相差的毫秒数

宏 TIME_SUB_MS 把秒和微秒的差值统一换算为毫秒：

#define TIME_SUB_MS(tv1, tv2) \
 ((tv1.tv_sec - tv2.tv_sec) * 1000 + \
 (tv1.tv_usec - tv2.tv_usec) / 1000)

QPS 的基本计算关系是：

QPS = 请求总数 ÷ 耗时秒数
 = 请求总数 × 1000 ÷ 耗时毫秒数

这里的“请求总数”应按实际循环次数和每轮命令数计算。数组测试中是 90000；红黑树测试同样是 10000 × 9 = 90000。阅读输出时先统一这个口径，两个引擎的数据才可以放在一起比较。

5.1 三次粗测说明了什么

笔记记录了 9000 次请求附近的三次结果：

测试环境	耗时	粗测 QPS
客户端输出每次 PASS，服务端也打印	477 ms	18867
屏蔽客户端 PASS 输出	415 ms	21686
继续去掉服务端打印	285 ms	31578

三组数据的重点不是得到一个绝对性能结论，而是观察到：

测试总耗时
 = 网络收发耗时
 + 协议处理耗时
 + 引擎操作耗时
 + 客户端打印耗时
 + 服务端打印耗时

当 printf() 位于高频路径中，它也属于被计时的工作。逐步屏蔽打印后，QPS 上升，说明这次粗测测到的是整个端到端过程，而不只是 KV 引擎本身。

5.2 当前 QPS 的准确含义

当前压力客户端只有一个进程、一条 TCP 连接，并且每次都按下面的顺序执行：

send 一条请求
 ↓
等待 recv 一条响应
 ↓
比较结果
 ↓
发送下一条请求

因此当前结果更准确地说是：

单客户端、单连接、串行请求、包含协议校验的端到端吞吐量。

它适合观察同一环境下的相对变化，例如开关日志前后的差异，以及数组与红黑树在相同测试场景下的差异。

6. 为什么小次数正常，高次数却失败

压力测试增加到 90000 次请求后，出现了：

FAILED-> SET-Dad,ERROR!=OK

从客户端场景看，每轮都执行：

SET Dad Jasper
...
DEL Dad

一轮结束时，Dad 已经删除，所以下一轮的 SET Dad Jasper 应该仍然能够成功。实际数据量始终只在 0 和 1 之间变化：

SET 后：1 个元素
DEL 后：0 个元素
SET 后：1 个元素
DEL 后：0 个元素

但是数组实例使用 total 记录有效元素数量。如果插入成功执行 total++，删除成功却没有对应地维护数量，就会形成两套不同的状态：

实际元素数量：0 → 1 → 0 → 1 → 0 ...
total： 0 → 1 → 1 → 2 → 2 ...

循环次数少时，total 还没有触及 KVS_ARRAY_SIZE，现象不明显；循环次数持续增加后，最终会到达容量判断：

if (inst->total >= KVS_ARRAY_SIZE)

于是后续 SET 返回错误。与此同时，查找范围由 total 决定，total 不断增大也会使遍历范围越来越长，所以压力测试还能观察到性能逐渐变化。

6.1 `total` 的核心约定

数组引擎需要维持一个清楚的不变量：

table[0] 到 table[total - 1]：有效元素
table[total] 以及后面的位置：空闲空间
total：当前有效元素数量

按照这个约定：

插入成功 → total++
删除成功 → total--

如果删除数组中间的元素，可以用最后一个有效元素补到删除位置，从而继续保持有效区间连续：

删除前：[Dad, Mom, Son] total = 3
删除 Mom 后出现空位：[Dad, 空, Son]
把最后一个元素移到空位：[Dad, Son, 空]
最终：total = 2

这个问题说明，容量字段不是只在创建时赋值、插入时递增的计数器，而是数据结构状态的一部分。每一种改变元素数量的操作都必须共同维护它。

7. 压力测试进一步暴露的几个语义问题

高次数运行不仅检查容量，还会不断经过删除、查询不存在和修改不存在等分支，因此能把返回值、内存和状态维护问题一起暴露出来。

7.1 删除 value 时的内存顺序

下面这个表达式先执行赋值：

kvs_free(inst->table[i].value = NULL);

它的实际求值顺序是：

inst->table[i].value = NULL
 ↓
kvs_free(NULL)

原来保存在 value 中的地址因此没有被交给 kvs_free()。正确理解“释放后置空”的顺序是：

先把原地址交给 kvs_free
 ↓
再把保存该地址的指针设为 NULL

也就是：

kvs_free(inst->table[i].key);
inst->table[i].key = NULL;

kvs_free(inst->table[i].value);
inst->table[i].value = NULL;

这里要记住的不是某一行写法，而是指针生命周期：地址仍然可达时释放内存，释放完成后再清除悬空指针。

7.2 循环下标与业务状态不是同一种含义

如果同时存在：

int i = 0;

for (int i = 0; i < inst->total; i++) {
 ...
}

for 中的 i 属于内层作用域，会遮蔽外层的 i。循环结束后，外层 i 仍是初始值 0。

更关键的是，即使只保留一个 i，return i 仍然混合了两种概念：

i：遍历到了哪个数组下标
返回值：本次 KV 操作是什么结果

数组为空时尤其容易看清这个区别：

i = 0
total = 0
循环一次都不执行
return i 得到 0

这里的 0 只是下标初始值，并不能说明修改或删除成功。

因此，学习时应把业务状态单独记忆：

返回值	协议层理解
`< 0`	参数或执行错误，生成 `ERROR`
`0`	操作成功，或 `EXIST` 查询确认存在
`> 0`	SET 时表示已存在；DEL/MOD/EXIST 时表示不存在

7.3 两种失败现象来自同一套返回值约定

删除成功后如果返回 1，协议层会按照既定规则生成：

DEL 返回 1 → NO EXIST

于是客户端看到：

FAILED-> DEL-Dad,NO EXIST!=OK

删除以后再执行 MOD，如果数组为空、循环未执行，最后又通过 return i 返回初始值 0，协议层会生成：

MOD 返回 0 → OK

于是客户端看到：

FAILED-> MOD-Dad,OK!=NO EXIST

这两种现象虽然出现在不同命令中，核心都是同一件事：引擎函数的返回值属于内部业务协议，协议层会严格按照该约定翻译成文本响应。

可以把这条关系记成：

引擎内部状态
 ↓
固定返回值
 ↓
kvs_filter_protocol()
 ↓
客户端可见响应
 ↓
testcase() 与预期比较

测试失败信息最终帮助定位到的，不一定是 TCP 层，也可能是更深处的状态维护或返回值语义。

8. 从单一数组引擎扩展为多引擎

前一阶段的协议层只连接数组：

SET / GET / DEL / MOD / EXIST
 ↓
 global_array

本阶段保留已经成型的数组实现，并通过宏加入红黑树：

#define ENABLE_ARRAY 1
#define ENABLE_RBTREE 1

这两个开关控制相关类型、接口、全局实例、协议分支、初始化和销毁代码是否参与编译。这样可以在接入期间让两种引擎同时存在，并分别运行测试。

项目结构由此变成：

 kvs_protocol
 ↓
 kvs_filter_protocol
 ↓
 根据命令选择对应的引擎
 ↙ ↘
 SET/GET/DEL/MOD/EXIST RSET/RGET/RDEL/RMOD/REXIST
 ↓ ↓
 global_array global_rbtree

这里没有改变底层网络。无论使用 Reactor、Proactor 还是 ntyco，网络层仍然只调用同一个 kvs_protocol()。增加的是协议层后面的存储选择。

9. 为什么给红黑树命令增加 `R` 前缀

一条普通的 SET Dad Jasper 只表达了“设置键值”，没有说明数据应该存进数组还是红黑树。

当前阶段采用最直接的区分方法：在协议命令中加入引擎标识。

数组命令	红黑树命令	语义
`SET`	`RSET`	新增 key-value
`GET`	`RGET`	查询 value
`DEL`	`RDEL`	删除 key-value
`MOD`	`RMOD`	修改 value
`EXIST`	`REXIST`	判断 key 是否存在

命令字符串表因此扩展为十项：

const char *command[] = {
 "SET", "GET", "DEL", "MOD", "EXIST",
 "RSET", "RGET", "RDEL", "RMOD", "REXIST"
};

枚举与字符串表保持相同顺序，kvs_filter_protocol() 找到命令编号后，通过 switch 进入对应分支：

RSET
 ↓
KVS_CMD_RSET
 ↓
kvs_rbtree_set(&global_rbtree, key, value)
 ↓
按照返回值生成 OK / EXIST / ERROR

因此，R 前缀在当前阶段承担的是一个简单的路由信息：让协议层知道应该调用哪种引擎。

10. 每种数据结构都遵守“5 + 2”接口

数组引擎已经形成七个接口：

create
destory
set
get
del
mod
exist

可以压缩为：

2 个生命周期操作 + 5 个 KV 操作 = 5 + 2

红黑树接入时也提供相同形态：

int kvs_rbtree_create(kvs_rbtree_t *inst);
void kvs_rbtree_destory(kvs_rbtree_t *inst);
int kvs_rbtree_set(kvs_rbtree_t *inst, char *key, char *value);
char *kvs_rbtree_get(kvs_rbtree_t *inst, char *key);
int kvs_rbtree_del(kvs_rbtree_t *inst, char *key);
int kvs_rbtree_mod(kvs_rbtree_t *inst, char *key, char *value);
int kvs_rbtree_exist(kvs_rbtree_t *inst, char *key);

协议层因此不需要理解旋转、着色、后继节点等红黑树内部细节。它只关心：

用哪个实例
调用哪个 KV 操作
如何解释返回值

这正是本次“加入红黑树”最值得回顾的部分：不是从零推导红黑树算法，而是把已有数据结构包装成项目已经形成的 KV 引擎接口。

同样的思路也可以用于后续哈希引擎：哈希表内部怎样定位 key 属于数据结构实现；接入项目时，仍围绕生命周期和五种 KV 语义组织接口。

11. 红黑树在项目中的最小理解范围

为了理解本项目中的接入，只需要掌握下面几层关系。

11.1 树实例和节点

红黑树实例保存：

typedef struct _rbtree {
 rbtree_node *root;
 rbtree_node *nil;
} rbtree;

其中：

root 指向根节点；
nil 是哨兵节点，用于表示空孩子和空树边界；
nil 初始化为黑色；
创建完成时，root 指向 nil，表示树中还没有 KV 节点。

节点中与 KV 项目直接相关的是：

key → 用于比较和查找
value → 与 key 对应的数据

父节点、左右孩子和颜色则服务于红黑树结构本身。

11.2 五种 KV 操作如何映射到底层树操作

KV 接口	在红黑树中的主要过程
`kvs_rbtree_set()`	为 key/value 分配空间，构造节点并插入树
`kvs_rbtree_get()`	按 key 搜索节点，返回节点的 value
`kvs_rbtree_del()`	搜索节点，删除节点并释放相关空间
`kvs_rbtree_mod()`	搜索节点，替换已有 value
`kvs_rbtree_exist()`	搜索节点，通过是否到达 `nil` 判断存在性

这些包装函数把“树节点操作”转换成与数组引擎一致的“KV 操作”。

11.3 生命周期怎样进入程序主流程

程序启动时，两种引擎分别初始化：

init_kvengine()
 ├─ kvs_array_create(&global_array)
 └─ kvs_rbtree_create(&global_rbtree)

网络服务结束后，再进入统一销毁阶段：

dest_kvengine()
 ├─ kvs_array_destory(&global_array)
 └─ kvs_rbtree_destory(&global_rbtree)

红黑树销毁时需要逐步删除树中的节点，最后处理树实例的哨兵节点。具体采用最小节点、最大节点或其他顺序，是树内部的销毁策略；对项目主线而言，重要的是 destory 与 create 共同构成完整生命周期。

12. 用同一套语义验证红黑树引擎

rbtree_testcase() 与 array_testcase() 的业务顺序保持一致，只是命令增加了 R 前缀：

数组： SET → GET → MOD → GET → EXIST → DEL → GET → MOD → EXIST
红黑树：RSET → RGET → RMOD → RGET → REXIST → RDEL → RGET → RMOD → REXIST

这使测试具有两个层次：

单独验证每个引擎是否满足五种 KV 操作；
验证两种引擎在相同业务场景下是否表现出相同语义。

可以把两组用例看成一份“行为契约”：

初始状态和操作	数组响应	红黑树响应
不存在时 SET	`OK`	`OK`
SET 后 GET	对应 value	对应 value
已存在时 MOD	`OK`	`OK`
已存在时 EXIST	`EXIST`	`EXIST`
已存在时 DEL	`OK`	`OK`
DEL 后 GET/MOD/EXIST	`NO EXIST`	`NO EXIST`

只要对外行为一致，客户端就不需要了解底层究竟使用数组还是红黑树。当前协议用命令前缀显式选择引擎，但测试验证的是二者共同的 KV 语义。

13. 数组与红黑树在当前项目中的角色

本阶段不是简单地用红黑树替换数组，而是让两种实现同时存在：

维度	数组引擎	红黑树引擎
协议命令	五种普通命令	五种 `R` 前缀命令
全局实例	`global_array`	`global_rbtree`
生命周期	`create/destory`	`create/destory`
KV 接口	`set/get/del/mod/exist`	`set/get/del/mod/exist`
内部组织	连续数组区间	根节点、哨兵和树节点
查找方式	在有效区间中遍历	按 key 在树中搜索

真正稳定下来的不是某一种数据结构，而是数据结构外面的项目边界：

协议命令
 ↓
统一的 KV 语义
 ↓
不同引擎各自实现

这也解释了“要什么需求、用什么技术方案实现”的关系：

需求是保存、查询、删除、修改和判断 key；
数组和红黑树是两种实现这些需求的技术方案；
协议层负责把客户端命令路由给具体方案；
测试用例负责确认不同方案满足相同的外部预期。

14. 关于多进程、多线程压力测试的课后思考

当前单连接测试中，每条请求都要等待上一条响应，无法同时给服务端制造多个在途请求。要观察并发场景，可以让多个执行单元各自建立连接并运行同一组测试。

14.1 多进程思路

父进程
 ├─ fork → 子进程 1 → 建立连接 → 重复测试
 ├─ fork → 子进程 2 → 建立连接 → 重复测试
 └─ fork → 子进程 N → 建立连接 → 重复测试

每个子进程拥有自己的客户端 socket 和测试循环。父进程等待所有子进程结束，再汇总：

总请求数 = 进程数 × 每个进程的请求数
整体 QPS = 总请求数 × 1000 ÷ 整体耗时毫秒数

14.2 多线程思路

一个客户端进程
 ├─ 线程 1 → 独立连接 → 重复测试
 ├─ 线程 2 → 独立连接 → 重复测试
 └─ 线程 N → 独立连接 → 重复测试

每个线程使用独立连接时，测试流程和当前代码最接近；主线程统一记录开始与结束时间，并统计所有线程完成的请求总数。

14.3 并发数增加后观察什么

并发测试不只是期待 QPS 一定上升，还要同时观察：

所有响应是否仍然符合预期；
总吞吐量怎样随客户端数量变化；
单次请求延迟是否增加；
服务端采用的网络模型是否能发挥并发处理能力；
打印、网络、协议或存储引擎中的哪一部分先成为主要耗时。

因此，多进程或多线程的意义是改变负载模型：从“一个客户端串行发请求”变成“多个客户端同时发请求”。

15. 这一阶段形成的完整项目画面

把前三个阶段放在一起，可以得到当前项目结构：

测试客户端
 ├─ 功能用例：检查每一步响应
 └─ 压力用例：重复场景、计时、计算 QPS
 │
 ▼
 TCP 网络
 │
 ▼
网络层：Reactor / Proactor / ntyco
 │
 ▼
kvs_protocol()：切分 token
 │
 ▼
kvs_filter_protocol()：识别命令并选择引擎
 ┌────┴────┐
 ▼ ▼
 数组引擎 红黑树引擎
 5 + 2 接口 5 + 2 接口
 │ │
 └────┬────┘
 ▼
 统一返回值与文本响应

Makefile 则从构建角度把这些模块放到一起：

kvstore.c
reactor.c / proactor.c / ntyco.c
kvs_array.c
kvs_rbtree.c
NtyCo 与 liburing
 ↓
 kvstore

16. 最后的复习提纲

16.1 测试主线

connect
 → send command
 → recv response
 → compare pattern
 → PASS / FAILED

16.2 压力测试主线

固定业务场景
 → 重复执行
 → 统计实际请求数
 → 记录总耗时
 → 计算 QPS
 → 从失败轮次和响应反查内部状态

16.3 数组问题定位主线

少量测试正常、增加次数后 SET 返回 ERROR
 → 检查容量条件
 → 检查 total 的增减
 → 发现实际元素已删除但 total 仍增长
 → 恢复“有效元素数量”的统一约定

同时记住：

释放内存：先 free 原地址，再把指针置 NULL
循环下标：只表示位置
函数返回值：表示业务结果
协议响应：由业务返回值翻译得到

16.4 多引擎扩展主线

保留数组成型代码
 → 用 ENABLE_ARRAY / ENABLE_RBTREE 控制编译
 → 为红黑树提供同样的 5 + 2 接口
 → 增加 RSET/RGET/RDEL/RMOD/REXIST
 → 协议层按命令选择实例
 → 用同一套业务场景验证两种引擎

16.5 本阶段最重要的认识

测试用例不是项目完成后的附属代码，而是项目继续迭代时用来确认行为的固定标准。

小次数测试验证基本功能，高次数测试还会验证状态能否长期保持一致。

total、节点数量和指针生命周期都属于数据结构必须维护的内部状态。

数组、红黑树以及后续哈希表可以采用不同内部实现，但都可以通过相同的 KV 语义接入协议层。

本阶段加入红黑树的重点，是把一种已有数据结构组织成项目需要的存储引擎，而不是从零实现红黑树算法。

KV 存储项目：协议层与数组存储

Mon, 24 Aug 2026 00:00:00 +0800

阅读目标：沿着“收到一条命令—解析命令—操作数组—生成响应”这条主线，回顾 KV 项目从 echo 协议发展到实际命令处理的过程。

本文承接 KV 存储项目网络层：统一接入 Reactor、Proactor 与协程。上一篇已经讲过 Reactor、Proactor、ntyco、msg_handler 和网络收发流程，本文不再重复网络层实现，只说明它怎样把请求交给协议层。

本文以笔记和现有代码为准，解释代码在项目中的作用与执行过程，不讨论修改方案。

1. 从网络层进入协议层

上一篇已经完成了网络层。无论底层选择 Reactor、Proactor 还是 ntyco，收到请求后都会调用同一个入口：

kvs_protocol(msg, length, response);

这一篇从这里继续：

网络层收到客户端数据
 ↓
kvs_protocol() 进入协议层
 ↓
kvs_split_token() 切分命令
 ↓
kvs_filter_protocol() 识别命令
 ↓
kvs_array_xxx() 操作 KV 数据
 ↓
把执行结果写入 response
 ↓
网络层发送响应

网络层解决“数据怎样到达”，协议层解决“收到的数据表示什么、应该返回什么”。

2. 为什么 TCP 之上还需要业务协议

假设浏览器请求一个包含数据的网页，业务链路可以是：

浏览器 → NodeServer → KV 存储服务器

NodeServer 与 KV 存储服务器建立 TCP 连接后，还要约定双方发送数据的格式。例如：

SEND: SET Key Value\r\n
RECV: OK\r\n

SEND: GET Key\r\n
RECV: King\r\n

TCP 是公共的传输协议，只负责按顺序传输字节；SET 和 GET 的含义属于项目自己定义的应用层协议，也可以称为业务协议或私有协议。

本项目采用容易观察的文本命令：

SET Key Value
GET Key
DEL Key
MOD Key Value
EXIST Key

其中空格用于分隔命令和参数，响应通过 response 缓冲区交还给网络层。

3. TCP 消息边界：理解协议的前提

TCP 是字节流，一次 send() 不一定对应一次 recv()。

客户端连续发送：

SET Key Value\r\n
SET Key1 Value1\r\n
SET Key2 Value2\r\n

接收方可能一次 recv() 收到多条命令，也可能只收到一条命令的一部分。因此应用层需要自己识别完整消息的边界。

笔记中记录了两种约定边界的思路。

3.1 在包头记录长度

在数据最前面使用固定字节表示后续消息长度：

short length = 0;

recv(fd, &length, 2, 0);
recv(fd, buffer, length, 0);

概念流程是：

先读取固定长度的包头
 ↓
得到消息体长度 length
 ↓
继续读取 length 个字节
 ↓
取得一条完整消息

3.2 使用结束标记

文本协议也可以约定用 \r\n 表示一行结束，再逐行解析命令。

无论采用长度字段还是结束标记，目的都是让接收方能够从连续的 TCP 字节流中还原出一条条完整命令。

ET、LT 对应不同的事件触发方式；它们都能处理多个数据包，具体读取过程属于上一篇网络层的延伸问题。本文继续关注完整命令到达 kvs_protocol() 之后的处理。

4. Redis 协议带来的解析思路

SET Key Value 可以拆成三个 token：

SET
Key
Value

笔记中的 Redis 协议简化示意不仅传输 token 内容，还记录 token 数量和每个 token 的长度：

3\r\n
3\r\n
SET\r\n
3\r\n
Key\r\n
5\r\n
Value\r\n

可以依次理解为：

共有 3 个 token
SET 的长度是 3
Key 的长度是 3
Value 的长度是 5

GET Teacher 则有两个 token：

2\r\n
3\r\n
GET\r\n
7\r\n
Teacher\r\n

对应的读取伪代码是：

readline(fd, buffer);
count = atoi(buffer);

for (int i = 0; i < count; i++) {
 readline(fd, tokenlen);
 readline(fd, token);
}

解析主线是：

读取 token 数量
 ↓
循环读取每个 token 的长度
 ↓
按照长度读取 token 内容
 ↓
组合成一条完整命令

当前项目代码采用更直接的形式：收到 SET Key Value 后，以空格调用 strtok() 进行切分。

5. 文件职责

本次代码可以按职责分为三部分：

kvstore.h
 ├─ 公共宏与函数声明
 ├─ 数组 KV 数据结构
 └─ CRUD 接口

kvstore.c：协议部分
 ├─ 内存接口封装
 ├─ token 切分
 ├─ 命令识别与响应生成
 ├─ KV 引擎初始化
 └─ main

数组存储部分
 ├─ global_array
 ├─ create / destory
 └─ set / get / del / mod / exist

上一篇的 kvs_protocol() 只是把请求复制到响应中；本次代码让它开始解析并执行真实的 KV 命令。

6. `kvstore.h`：数组引擎的数据结构与接口

6.1 编译配置

#define KVS_MAX_TOKENS 128
#define ENABLE_ARRAY 1
#define KVS_ARRAY_SIZE 1024

宏	代码中的含义
`KVS_MAX_TOKENS`	`tokens` 数组容量
`ENABLE_ARRAY`	是否编译数组 KV 引擎
`KVS_ARRAY_SIZE`	KV 数组的容量

6.2 一个 KV 元素

typedef struct kvs_array_item_s {
 char *key;
 char *value;
} kvs_array_item_t;

数组中的每一个元素保存一对指针：

table[i]
 ├─ key → 键字符串
 └─ value → 值字符串

6.3 整个数组实例

typedef struct kvs_array_s {
 kvs_array_item_t *table;
 int idx;
 int total;
} kvs_array_t;

字段	含义
`table`	指向 KV 元素数组
`idx`	数组实例中的索引字段
`total`	当前记录的元素数量

数组引擎向协议层提供以下操作：

int kvs_array_create(kvs_array_t *inst);
void kvs_array_destory(kvs_array_t *inst);
int kvs_array_set(kvs_array_t *inst, char *key, char *value);
char *kvs_array_get(kvs_array_t *inst, char *key);
int kvs_array_del(kvs_array_t *inst, char *key);
int kvs_array_mod(kvs_array_t *inst, char *key, char *value);
int kvs_array_exist(kvs_array_t *inst, char *key);

7. 封装内存分配接口

代码没有让各个数据操作直接依赖 malloc() 和 free()，而是包了一层：

void *kvs_malloc(size_t size) {
 return malloc(size);
}

void kvs_free(void *ptr) {
 free(ptr);
}

其他模块统一使用：

kvs_malloc(size);
kvs_free(ptr);

笔记中的目的，是给内存管理保留统一入口。后续如果跨平台、引入内存池或定制内存分配，只需要从这一层接入，不必改变所有调用位置。

这体现了项目迭代中的一个思路：先通过统一接口隔开业务代码与底层实现。

8. 创建数组实例：`kvs_array_create()`

全局数组实例定义为：

kvs_array_t global_array = {0};

创建函数：

int kvs_array_create(kvs_array_t *inst) {
 if (inst == NULL) return -1;

 if (inst->table) {
 printf("table has been alloced");
 return -1;
 }

 inst->table = kvs_malloc(
 KVS_ARRAY_SIZE * sizeof(kvs_array_item_t)
 );

 if (!inst->table) return -1;

 inst->total = 0;
 return 0;
}

执行过程：

检查 inst
 ↓
检查 table 是否已经指向数组
 ↓
申请 KVS_ARRAY_SIZE 个元素的空间
 ↓
total 设为 0

程序启动时，init_kvengine() 负责初始化它：

int init_kvengine(void) {
#if ENABLE_ARRAY
 memset(&global_array, 0, sizeof(kvs_array_t));
 kvs_array_create(&global_array);
#endif
 return 0;
}

9. `SET`：保存一组 key-value

接口：

int kvs_array_set(kvs_array_t *inst,
 char *key,
 char *value);

主要执行顺序：

检查 inst、key、value
 ↓
检查 total 是否达到数组容量
 ↓
调用 kvs_array_get() 查找 key
 ↓
key 已存在时返回 1
 ↓
分别为 key 和 value 分配内存
 ↓
复制 key 和 value
 ↓
寻找存放位置并写入 table
 ↓
total 加 1，返回 0

代码为字符串申请 strlen(...) + 1 字节：

char *kcopy = kvs_malloc(strlen(key) + 1);
char *kvalue = kvs_malloc(strlen(value) + 1);

多出的一个字节用于字符串结尾的 \0。

返回值在当前协议中的含义：

ret < 0 → 执行错误
ret == 0 → 设置成功
ret > 0 → key 已存在

10. `GET`：按照 key 查找 value

接口：

char *kvs_array_get(kvs_array_t *inst, char *key);

查询过程：

检查 inst 和 key
 ↓
从 table[0] 开始遍历
 ↓
跳过 key 为空的元素
 ↓
strcmp() 比较元素 key 和目标 key
 ↓
找到后返回 value
 ↓
遍历结束仍未找到则返回 NULL

核心比较：

if (strcmp(inst->table[i].key, key) == 0) {
 return inst->table[i].value;
}

因此 kvs_array_get() 的结果可以直接被 SET、GET 和 EXIST 复用。

11. `DEL`：删除 key-value

接口：

int kvs_array_del(kvs_array_t *inst, char *key);

执行主线：

检查 inst 和 key
 ↓
遍历 table
 ↓
strcmp() 找到相同 key
 ↓
释放 key 对应的内存
 ↓
释放 value 对应的内存
 ↓
返回执行结果

协议层按照约定把返回值转换为：

ERROR / OK / NO EXIST

12. `MOD`：修改已有 key 的 value

接口：

int kvs_array_mod(kvs_array_t *inst,
 char *key,
 char *value);

执行主线：

检查 inst、key、value
 ↓
遍历 table 查找 key
 ↓
释放原来的 value
 ↓
按照新字符串长度申请内存
 ↓
复制新的 value
 ↓
把新 value 写回当前元素

MOD 保留原来的 key，只更新与它关联的 value。

13. `EXIST`：复用 GET 判断 key 是否存在

int kvs_array_exist(kvs_array_t *inst, char *key) {
 char *str = kvs_array_get(inst, key);

 if (!str) {
 return 1;
 }
 return 0;
}

返回值含义：

0 → key 存在
1 → key 不存在

这里没有再次编写数组遍历，而是调用 kvs_array_get() 完成查找。

14. 命令字符串与枚举的对应关系

命令字符串表：

const char *command[] = {
 "SET", "GET", "DEL", "MOD", "EXIST"
};

枚举：

enum {
 KVS_CMD_START = 0,
 KVS_CMD_SET = KVS_CMD_START,
 KVS_CMD_GET,
 KVS_CMD_DEL,
 KVS_CMD_MOD,
 KVS_CMD_EXIST,
 KVS_CMD_COUNT,
};

二者按下标形成对应关系：

`cmd`	`command[cmd]`	枚举
0	`SET`	`KVS_CMD_SET`
1	`GET`	`KVS_CMD_GET`
2	`DEL`	`KVS_CMD_DEL`
3	`MOD`	`KVS_CMD_MOD`
4	`EXIST`	`KVS_CMD_EXIST`

协议解析通过同一个 cmd 同时连接字符串表与 switch 分支，所以代码注释强调二者顺序保持对应。

15. `kvs_split_token()`：把命令切成参数

函数入口：

int kvs_split_token(char *msg, char *tokens[])

首先检查参数：

if (msg == NULL || tokens == NULL) return -1;

然后以空格为分隔符调用 strtok()：

int idx = 0;
char *token = strtok(msg, " ");

while (token != NULL) {
 tokens[idx++] = token;
 token = strtok(NULL, " ");
}

return idx;

对于：

SET Key Value

切分结果是：

tokens[0] → "SET"
tokens[1] → "Key"
tokens[2] → "Value"
返回 count = 3

对于：

GET Key

切分结果是：

tokens[0] → "GET"
tokens[1] → "Key"
返回 count = 2

笔记中强调：函数进入时先进行参数判断。完整项目还会逐步形成统一的参数错误、内存错误和协议错误等返回值约定。

16. `kvs_filter_protocol()`：识别命令并生成响应

函数入口：

int kvs_filter_protocol(char **tokens,
 int count,
 char *response);

16.1 查找命令编号

int cmd = KVS_CMD_START;

for (cmd = KVS_CMD_START;
 cmd < KVS_CMD_COUNT;
 cmd++) {
 if (strcmp(tokens[0], command[cmd]) == 0) {
 break;
 }
}

例如 tokens[0] 是 GET，循环最终得到：

cmd = KVS_CMD_GET

随后统一取出参数位置：

char *key = tokens[1];
char *value = tokens[2];

16.2 SET 分支

ret = kvs_array_set(&global_array, key, value);

数组层结果	协议响应
`ret < 0`	`ERROR\r\n`
`ret == 0`	`OK\r\n`
`ret > 0`	`EXIST\r\n`

16.3 GET 分支

char *result = kvs_array_get(&global_array, key);

查询结果	协议响应
`result == NULL`	`NO EXIST\r\n`
找到 value	`value\r\n`

16.4 DEL 分支

ret = kvs_array_del(&global_array, key);

数组层结果	协议响应
`ret < 0`	`ERROR\r\n`
`ret == 0`	`OK\r\n`
`ret > 0`	`NO EXIST\r\n`

16.5 MOD 分支

ret = kvs_array_mod(&global_array, key, value);

数组层结果	协议响应
`ret < 0`	`ERROR\r\n`
`ret == 0`	`OK\r\n`
`ret > 0`	`NO EXIST\r\n`

16.6 EXIST 分支

ret = kvs_array_exist(&global_array, key);

数组层结果	协议响应
`ret == 0`	`EXIST`
`ret != 0`	`NO EXIST\r\n`

kvs_filter_protocol() 的角色可以概括为：把文本命令转换成数组函数调用，再把数组函数的返回值转换成文本响应。

17. `kvs_protocol()`：本篇代码的总入口

int kvs_protocol(char *msg,
 int length,
 char *response) {
 if (msg == NULL || length <= 0 || response == NULL)
 return -1;

 printf("recv: %d: %s\n", length, msg);

 char *tokens[KVS_MAX_TOKENS] = {0};

 int count = kvs_split_token(msg, tokens);
 if (count == -1) return -1;

 return kvs_filter_protocol(tokens, count, response);
}

三个参数分别来自网络层：

参数	含义
`msg`	收到的请求内容
`length`	请求长度
`response`	协议层写入响应的缓冲区

执行主线：

检查参数
 ↓
创建 tokens 数组
 ↓
kvs_split_token(msg, tokens)
 ↓
得到 token 数量 count
 ↓
kvs_filter_protocol(tokens, count, response)
 ↓
执行命令并形成响应

它把上一篇的“网络回调入口”与本篇的“命令解析和数组 CRUD”连接起来。

18. 程序启动与数组引擎接入

main() 先取得端口，再初始化 KV 引擎：

int port = atoi(argv[1]);
init_kvengine();

之后按照 NETWORK_SELECT 启动对应网络层，并继续把 kvs_protocol 作为回调传入：

reactor_start(port, kvs_protocol);
/* 或 */
ntyco_start(port, kvs_protocol);
/* 或 */
proactor_start(port, kvs_protocol);

这里不再展开三种网络模型。只需记住：网络模型可以切换，协议入口和数组引擎的调用主线保持不变。

19. 一条 `SET` 命令的完整路径

客户端发送：

SET name King

代码中的执行过程：

网络层取得 msg
 ↓
kvs_protocol(msg, length, response)
 ↓
kvs_split_token()
 ↓
tokens[0] = "SET"
tokens[1] = "name"
tokens[2] = "King"
 ↓
kvs_filter_protocol()
 ↓
匹配 KVS_CMD_SET
 ↓
kvs_array_set(&global_array, "name", "King")
 ↓
为 key 和 value 分配内存并写入 table
 ↓
response = "OK\r\n"
 ↓
网络层发送响应

20. 一条 `GET` 命令的完整路径

客户端发送：

GET name

执行过程：

kvs_protocol()
 ↓
切分出 "GET" 和 "name"
 ↓
kvs_filter_protocol()
 ↓
匹配 KVS_CMD_GET
 ↓
kvs_array_get(&global_array, "name")
 ↓
遍历 table 并比较 key
 ↓
找到 value = "King"
 ↓
response = "King\r\n"

如果没有找到，则响应：

NO EXIST\r\n

21. 返回值与协议响应是两个层次

数组函数首先返回内部执行结果，例如：

小于 0：错误
等于 0：成功或存在
大于 0：已存在或不存在

协议层再将其转换成客户端能够理解的文本：

OK
ERROR
EXIST
NO EXIST
具体的 value

这与 HTTP 使用 200、404 等状态表达处理结果的思路相似：一个完整项目会逐步形成统一的参数错误、内存分配失败、协议解析失败等返回值标准。

22. 从功能实现到项目架构

笔记给出的迭代顺序是：

先保证功能
 ↓
保证协议统一
 ↓
保证参数统一
 ↓
保证返回值统一

数组法先直接实现了 KV 的基本操作：

SET → 增加 key-value
GET → 查询 value
DEL → 删除 key-value
MOD → 修改 value
EXIST → 判断 key 是否存在

随着代码不断迭代，公共接口、模块边界和返回值规则逐渐稳定，进而形成项目架构。

可以记住两句话：

架构是在软件不断迭代的过程中逐渐产生的。

软件代码可以通过分层设计，将网络收发、协议处理和数据存储分开。

23. 最后的整体记忆

这一阶段最重要的不是分别记住所有函数，而是记住数据在各层之间怎样移动：

客户端文本命令
 ↓
网络层交给 kvs_protocol
 ↓
kvs_split_token 拆出 command / key / value
 ↓
kvs_filter_protocol 匹配命令
 ↓
kvs_array_set/get/del/mod/exist
 ↓
global_array 中的 key-value 数据
 ↓
协议层生成 OK、ERROR、value 等响应
 ↓
网络层发送给客户端

按函数压缩为：

kvs_protocol
 → kvs_split_token
 → kvs_filter_protocol
 → kvs_array_xxx
 → response

KV 存储项目网络层：统一接入 Reactor、Proactor 与协程

Sat, 22 Aug 2026 00:00:00 +0800

阅读目标：先恢复项目的整体认识，再通过带注释的代码块回忆具体实现。

本文只解析现有成品代码，不讨论修改方案。ntyco 只讲如何作为 KV 项目的网络层使用。

1. 先恢复项目的整体画面

这个项目的核心不是分别写了三个独立服务器，而是让三个网络服务器共同使用同一个 KV 协议入口：

 kvstore.c
 main + kvs_protocol
 │
 msg_handler 回调
 │
 ┌──────────────┼──────────────┐
 │ │ │
 reactor.c ntyco.c proactor.c
 epoll 协程 io_uring
 │ │ │
 └──────────────┼──────────────┘
 │
 TCP

三种网络层只负责连接和收发，kvs_protocol() 负责处理消息：

客户端请求
 ↓
网络层收到 msg 和 length
 ↓
kvs_protocol(msg, length, response)
 ↓
返回 response 的长度
 ↓
网络层发送 response

项目目前的 kvs_protocol() 是 echo 协议：把请求复制成响应。这一实现展示的重点，是三种网络模型如何接入同一个 KV 协议回调。

六份文件分成三组：

公共入口与接口
 ├─ kvstore.c
 └─ kvstore.h

Reactor 公共连接定义
 └─ server.h

三种网络层
 ├─ reactor.c
 ├─ proactor.c
 └─ ntyco.c

2. 公共入口：`kvstore.h` 与 `kvstore.c`

2.1 `kvstore.h`：把三种网络层统一成一种调用方式

#ifndef KV_STORE_H
#define KV_STORE_H

/* 三种网络实现的编号，供 NETWORK_SELECT 选择 */
#define NETWORK_REACTOR 0
#define NETWORK_PROACTOR 1
#define NET_WORK_NTYCO 2

/* 当前编译使用 io_uring Proactor 网络层 */
#define NETWORK_SELECT NETWORK_PROACTOR

/*
 * KV 协议回调类型：
 * msg 网络层收到的请求
 * length 请求的实际长度
 * response 协议层写入响应的位置
 * 返回值 网络层需要发送的响应长度
 */
typedef int (*msg_handler)(char *msg, int length, char *response);

/* 三种网络层向 kvstore.c 暴露相同形式的启动函数 */
extern int reactor_start(unsigned short port, msg_handler handler);
extern int ntyco_start(unsigned short port, msg_handler handler);
extern int proactor_start(unsigned short port, msg_handler handler);

/* KV 项目支持的命令名称 */
const char *command[] = {
 "SET", "GET", "DEL", "MOD", "EXIST"
};

/* 响应字符串表，目前未填充 */
const char *response[] = {
};

#endif

这一文件的整体作用可以概括为：

NETWORK_SELECT 决定使用谁
msg_handler 规定协议函数长什么样
三个 start 规定网络层怎样启动
command 列出 KV 命令集合

2.2 `kvstore.c`：选择网络层，并把协议函数交给它

#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include "kvstore.h"

/*
 * 当前是 echo 形式的 KV 协议入口。
 * 网络层把请求传进来，本函数把请求复制成响应。
 */
int kvs_protocol(char *msg, int length, char *response) {
 /* 输出本次请求长度与内容 */
 printf("recv: %d: %s\n", length, msg);

 /* 将收到的 length 个字节复制到响应缓冲区 */
 memcpy(response, msg, length);

 /* 把响应长度交还给网络层 */
 return strlen(response);
}

int main(int argc, char *argv[]) {
 /* 启动形式要求为：./kvstore <port> */
 if (argc != 2) return -1;

 /* 将命令行中的端口字符串转换成整数 */
 int port = atoi(argv[1]);

 /*
 * 编译期选择网络模型。
 * 三个分支都把同一个 kvs_protocol 作为 handler 传入。
 */
#if (NETWORK_SELECT == NETWORK_REACTOR)
 reactor_start(port, kvs_protocol);
#elif (NETWORK_SELECT == NETWORK_NTYCO)
 ntyco_start(port, kvs_protocol);
#elif (NETWORK_SELECT == NETWORK_PROACTOR)
 proactor_start(port, kvs_protocol);
#endif
}

这里最需要记住的不是条件编译本身，而是下面三个调用具有完全相同的含义：

reactor_start(port, kvs_protocol);
ntyco_start(port, kvs_protocol);
proactor_start(port, kvs_protocol);

可以统一读作：

在指定端口启动某个网络后端；以后收到消息时，请调用 kvs_protocol()。

3. Reactor 的连接结构：`server.h`

Reactor 是事件驱动的。一次读事件和下一次写事件不是在同一个函数中连续完成，因此需要 struct conn 保存跨事件存在的连接信息。

#ifndef SERVER_H
#define SERVER_H

/* 每个连接的读、写缓冲区都是 1024 字节 */
#define BUFFER_LENGTH 1024

/* 当前 Reactor 上层启用 KVSTORE 协议 */
#define ENABLE_HTTP 0
#define ENABLE_WEBSOCKET 0
#define ENABLE_KVSTORE 1

/* epoll 事件回调：传入发生事件的 fd */
typedef int (*RCALLBACK)(int fd);

struct conn {
 int fd; // 当前连接的 socket fd

 char rbuffer[BUFFER_LENGTH]; // recv 接收到的请求
 int rlength; // 请求的实际长度

 char wbuffer[BUFFER_LENGTH]; // KV 协议生成的响应
 int wlength; // 响应的实际长度

 RCALLBACK send_callback; // EPOLLOUT 时调用 send_cb

 union {
 RCALLBACK recv_callback; // 客户端 fd 可读时调用 recv_cb
 RCALLBACK accept_callback; // 监听 fd 可读时调用 accept_cb
 } r_action;

 int status; // 连接/协议状态字段

#if 1 // websocket
 char *payload; // WebSocket 数据字段
 char mask[4]; // WebSocket 掩码字段
#endif
};

/* 同一套 Reactor 曾为不同上层协议保留入口 */
#if ENABLE_HTTP
int http_request(struct conn *c);
int http_response(struct conn *c);
#endif

#if ENABLE_WEBSOCKET
int ws_request(struct conn *c);
int ws_response(struct conn *c);
#endif

#if ENABLE_KVSTORE
int kvs_request(struct conn *c);
int kvs_response(struct conn *c);
#endif

#endif

struct conn 可以用一条数据流来理解：

recv(fd)
 ↓
rbuffer + rlength
 ↓ kvs_handler
wbuffer + wlength
 ↓
send(fd)

两个函数指针则决定 epoll 返回事件时执行什么：

监听 fd 的 EPOLLIN → accept_cb
连接 fd的 EPOLLIN → recv_cb
连接 fd的 EPOLLOUT → send_cb

4. Reactor 网络层：`reactor.c`

4.1 Reactor 总体流程

创建 epoll
 ↓
创建 20 个监听 socket，并注册 EPOLLIN
 ↓
epoll_wait
 ├─ 监听 fd 可读 → accept_cb
 ├─ 客户端 fd 可读 → recv_cb → kvs_protocol
 └─ 客户端 fd 可写 → send_cb

4.2 KV 回调和连接表

#define CONNECTION_SIZE 1048576 // 连接表容量
#define MAX_PORTS 20 // 连续监听 20 个端口

/* 计算两次 timeval 之间的毫秒差，用于 accept 统计 */
#define TIME_SUB_MS(tv1, tv2) \
 ((tv1.tv_sec - tv2.tv_sec) * 1000 + \
 (tv1.tv_usec - tv2.tv_usec) / 1000)

#if ENABLE_KVSTORE
/* reactor_start 会把 kvs_protocol 保存到这里 */
static msg_handler kvs_handler;

int kvs_request(struct conn *c) {
 /*
 * 将连接的接收缓冲区交给 KV 层；
 * KV 层把响应写入同一连接的发送缓冲区；
 * 返回值记录到 wlength。
 */
 c->wlength = kvs_handler(
 c->rbuffer,
 c->rlength,
 c->wbuffer
 );
}

int kvs_response(struct conn *c) {
 /* 当前 KV 响应不再进行二次处理 */
}
#endif

int epfd = 0; // epoll 实例 fd
struct timeval begin; // accept 统计起点
struct conn conn_list[CONNECTION_SIZE]; // 用 fd 直接索引连接

4.3 添加和切换 epoll 事件

int set_event(int fd, int event, int flag) {
 struct epoll_event ev;
 ev.events = event; // EPOLLIN 或 EPOLLOUT
 ev.data.fd = fd; // epoll 返回事件时带回这个 fd

 if (flag) {
 /* 新 fd 第一次进入 epoll */
 epoll_ctl(epfd, EPOLL_CTL_ADD, fd, &ev);
 } else {
 /* 已登记 fd 在读、写关注之间切换 */
 epoll_ctl(epfd, EPOLL_CTL_MOD, fd, &ev);
 }
}

这份 Reactor 的主要节奏，就是不断切换同一个客户端的事件：

刚建立连接 → EPOLLIN
收到并处理请求 → EPOLLOUT
发送完响应 → EPOLLIN

4.4 初始化一个客户端连接

int event_register(int fd, int event) {
 if (fd < 0) return -1;

 /* fd 同时也是 conn_list 的下标 */
 conn_list[fd].fd = fd;

 /* 客户端可读和可写时对应的处理函数 */
 conn_list[fd].r_action.recv_callback = recv_cb;
 conn_list[fd].send_callback = send_cb;

 /* 初始化这个连接的输入区域 */
 memset(conn_list[fd].rbuffer, 0, BUFFER_LENGTH);
 conn_list[fd].rlength = 0;

 /* 初始化这个连接的输出区域 */
 memset(conn_list[fd].wbuffer, 0, BUFFER_LENGTH);
 conn_list[fd].wlength = 0;

 /* 新连接加入 epoll，调用处传入的是 EPOLLIN */
 set_event(fd, event, 1);
}

4.5 创建监听 socket

int r_init_server(unsigned short port) {
 /* 创建 IPv4 TCP socket */
 int sockfd = socket(AF_INET, SOCK_STREAM, 0);

 struct sockaddr_in servaddr;
 servaddr.sin_family = AF_INET;
 servaddr.sin_addr.s_addr = htonl(INADDR_ANY); // 0.0.0.0
 servaddr.sin_port = htons(port); // 监听端口

 /* 把 socket 绑定到本机端口 */
 if (bind(sockfd,
 (struct sockaddr *)&servaddr,
 sizeof(struct sockaddr)) == -1) {
 printf("bind failed: %s\n", strerror(errno));
 }

 /* 将 socket 变为监听 socket */
 listen(sockfd, 10);

 return sockfd;
}

4.6 接受客户端

int accept_cb(int fd) {
 struct sockaddr_in clientaddr;
 socklen_t len = sizeof(clientaddr);

 /*
 * fd 是监听 socket；
 * clientfd 是新建立的客户端连接。
 */
 int clientfd = accept(
 fd,
 (struct sockaddr *)&clientaddr,
 &len
 );

 printf("accept finshed: %d,fd:%d\n", clientfd, fd);

 if (clientfd < 0) {
 printf("accept errno: %d --> %s\n",
 errno, strerror(errno));
 return -1;
 }

 /* 新客户端从等待读事件开始 */
 event_register(clientfd, EPOLLIN);

 /* 每当 fd 到达 1000 的整数倍，打印一次时间间隔 */
 if ((clientfd % 1000) == 0) {
 struct timeval current;
 gettimeofday(&current, NULL);

 int time_used = TIME_SUB_MS(current, begin);
 memcpy(&begin, &current, sizeof(struct timeval));

 printf("accept finshed: %d, time_used: %d\n",
 clientfd, time_used);
 }

 return 0;
}

4.7 接收请求并进入 KV 协议

int recv_cb(int fd) {
 /* 本次接收前清空该连接的读缓冲区 */
 memset(conn_list[fd].rbuffer, 0, BUFFER_LENGTH);

 /* 从客户端接收数据 */
 int count = recv(
 fd,
 conn_list[fd].rbuffer,
 BUFFER_LENGTH,
 0
 );

 if (count == 0) {
 /* recv 返回 0：客户端断开 */
 printf("client disconnect: %d\n", fd);
 close(fd);
 epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);
 return 0;
 } else if (count < 0) {
 /* recv 返回负数：打印错误并结束连接 */
 printf("count: %d, errno: %d, %s\n",
 count, errno, strerror(errno));
 close(fd);
 epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);
 return 0;
 }

 /* 保存这次实际收到的请求长度 */
 conn_list[fd].rlength = count;

#if 0
 /* echo 分支：直接把读缓冲复制到写缓冲 */
 conn_list[fd].wlength = conn_list[fd].rlength;
 memcpy(conn_list[fd].wbuffer,
 conn_list[fd].rbuffer,
 conn_list[fd].wlength);
#elif ENABLE_HTTP
 http_request(&conn_list[fd]);
#elif ENABLE_WEBSOCKET
 ws_request(&conn_list[fd]);
#elif ENABLE_KVSTORE
 /* 当前启用的分支：通过 handler 生成 KV 响应 */
 kvs_request(&conn_list[fd]);
#endif

 /* 请求处理完成，下一阶段等待发送 */
 set_event(fd, EPOLLOUT, 0);
 return count;
}

这里完成了项目中最重要的一次跨层调用：

recv_cb
 → kvs_request(&conn_list[fd])
 → kvs_handler(rbuffer, rlength, wbuffer)
 → kvs_protocol

4.8 发送响应

int send_cb(int fd) {
#if ENABLE_HTTP
 http_response(&conn_list[fd]);
#elif ENABLE_WEBSOCKET
 ws_response(&conn_list[fd]);
#elif ENABLE_KVSTORE
 /* KV 分支当前不对 wbuffer 做额外处理 */
 kvs_response(&conn_list[fd]);
#endif

 int count = 0;

 /* wlength 非零时，把 KV 响应发给客户端 */
 if (conn_list[fd].wlength != 0) {
 count = send(
 fd,
 conn_list[fd].wbuffer,
 conn_list[fd].wlength,
 0
 );
 }

 /* 响应阶段结束，再次等待客户端请求 */
 set_event(fd, EPOLLIN, 0);
 return count;
}

4.9 启动 Reactor 主循环

int reactor_start(unsigned short port, msg_handler handler) {
 printf("reactor_entry %d\n", port);

 /* 保存由 main 传入的 kvs_protocol */
 kvs_handler = handler;

 /* 创建 epoll 实例 */
 epfd = epoll_create(1);

 /* 从 port 开始连续建立 20 个监听端口 */
 for (int i = 0; i < MAX_PORTS; i++) {
 int sockfd = r_init_server(port + i);

 /* 监听 fd 可读时执行 accept_cb */
 conn_list[sockfd].fd = sockfd;
 conn_list[sockfd].r_action.recv_callback = accept_cb;

 /* 将监听 fd 加入 epoll */
 set_event(sockfd, EPOLLIN, 1);
 }

 /* accept 性能统计的起始时间 */
 gettimeofday(&begin, NULL);

 while (1) {
 struct epoll_event events[1024] = {0};

 /* 阻塞等待，最多取得 1024 个就绪事件 */
 int nready = epoll_wait(epfd, events, 1024, -1);

 for (int i = 0; i < nready; i++) {
 int connfd = events[i].data.fd;

 /*
 * 监听 fd：read callback 是 accept_cb；
 * 客户端 fd：read callback 是 recv_cb。
 */
 if (events[i].events & EPOLLIN) {
 conn_list[connfd]
 .r_action.recv_callback(connfd);
 }

 /* 客户端可写时调用 send_cb */
 if (events[i].events & EPOLLOUT) {
 conn_list[connfd]
 .send_callback(connfd);
 }
 }
 }
}

把整份 Reactor 压缩成一句话：

epoll 主循环根据 fd 和事件找到回调；读回调接收请求并调用 KV handler，写回调发送 handler 生成的响应。

5. io_uring Proactor 网络层：`proactor.c`

5.1 Proactor 总体流程

准备 ACCEPT 操作
 ↓ submit
等待完成队列 CQ
 ↓
ACCEPT 完成 → 得到 connfd → 准备 RECV
 ↓
READ 完成 → 调 kvs_protocol → 准备 SEND
 ↓
WRITE 完成 → 再次准备 RECV

Reactor 是“事件就绪以后调用 I/O”，这份 io_uring 代码是“先提交具体 I/O，再处理完成结果”。

5.2 操作类型与操作标记

/* 用于区分 CQE 对应哪一种操作 */
#define EVENT_ACCEPT 0
#define EVENT_READ 1
#define EVENT_WRITE 2

struct conn_info {
 int fd; // 操作所属的 socket
 int event; // ACCEPT / READ / WRITE
};

#define ENTRIES_LENGTH 1024 // io_uring 队列项参数
#define BUFFER_LENGTH 1024 // 网络缓冲区长度

/* proactor_start 保存 main 传入的 kvs_protocol */
static msg_handler kvs_handler;

每个 SQE 都通过 user_data 带上 conn_info。CQE 返回以后，程序就知道完成的是谁的什么操作。

5.3 准备 send

int set_event_send(struct io_uring *ring,
 int sockfd,
 void *buf,
 size_t len,
 int flags) {
 /* 从提交队列取得一个 SQE */
 struct io_uring_sqe *sqe = io_uring_get_sqe(ring);

 /* 标记这是 sockfd 的写操作 */
 struct conn_info info = {
 .fd = sockfd,
 .event = EVENT_WRITE,
 };

 /* 将 SQE 填写为 send 请求 */
 io_uring_prep_send(sqe, sockfd, buf, len, flags);

 /* 操作完成时，通过 user_data 找回 fd 和事件类型 */
 memcpy(&sqe->user_data, &info, sizeof(struct conn_info));
}

5.4 准备 recv

int set_event_recv(struct io_uring *ring,
 int sockfd,
 void *buf,
 size_t len,
 int flags) {
 struct io_uring_sqe *sqe = io_uring_get_sqe(ring);

 /* 标记这是 sockfd 的读操作 */
 struct conn_info info = {
 .fd = sockfd,
 .event = EVENT_READ,
 };

 /* 将 SQE 填写为 recv 请求 */
 io_uring_prep_recv(sqe, sockfd, buf, len, flags);

 memcpy(&sqe->user_data, &info, sizeof(struct conn_info));
}

5.5 准备 accept

int set_event_accept(struct io_uring *ring,
 int sockfd,
 struct sockaddr *addr,
 socklen_t *addrlen,
 int flags) {
 struct io_uring_sqe *sqe = io_uring_get_sqe(ring);

 /* 标记这是监听 sockfd 的 accept 操作 */
 struct conn_info info = {
 .fd = sockfd,
 .event = EVENT_ACCEPT,
 };

 /* 将 SQE 填写为 accept 请求 */
 io_uring_prep_accept(sqe, sockfd, addr, addrlen, flags);

 memcpy(&sqe->user_data, &info, sizeof(struct conn_info));
}

三个函数的结构完全一致，只有 prep 函数和 event 类型不同：

准备函数	liburing prep	事件标记
`set_event_accept`	`io_uring_prep_accept`	`EVENT_ACCEPT`
`set_event_recv`	`io_uring_prep_recv`	`EVENT_READ`
`set_event_send`	`io_uring_prep_send`	`EVENT_WRITE`

5.6 创建监听 socket

int p_init_server(unsigned short port) {
 /* 创建 IPv4 TCP socket */
 int sockfd = socket(AF_INET, SOCK_STREAM, 0);

 struct sockaddr_in servaddr;
 servaddr.sin_family = AF_INET;
 servaddr.sin_addr.s_addr = htonl(INADDR_ANY);
 servaddr.sin_port = htons(port);

 /* 绑定端口 */
 if (bind(sockfd,
 (struct sockaddr *)&servaddr,
 sizeof(struct sockaddr)) == -1) {
 printf("bind failed: %s\n", strerror(errno));
 }

 /* 开始监听 */
 listen(sockfd, 10);
 return sockfd;
}

5.7 初始化 io_uring 并准备第一个 accept

int proactor_start(unsigned short port, msg_handler handler) {
 /* 创建监听 socket */
 int sockfd = p_init_server(port);

 /* 保存 kvs_protocol */
 kvs_handler = handler;

 /* 初始化 io_uring 参数 */
 struct io_uring_params params;
 memset(&params, 0, sizeof(params));

 /* 创建提交队列和完成队列 */
 struct io_uring ring;
 io_uring_queue_init_params(
 ENTRIES_LENGTH,
 &ring,
 &params
 );

 /* accept 完成后，内核会填写客户端地址 */
 struct sockaddr_in clientaddr;
 socklen_t len = sizeof(clientaddr);

 /* 在进入循环之前，先准备第一个 accept SQE */
 set_event_accept(
 &ring,
 sockfd,
 (struct sockaddr *)&clientaddr,
 &len,
 0
 );

 /* READ 使用 buffer，KV 输出和 WRITE 使用 response */
 char buffer[BUFFER_LENGTH] = {0};
 char response[BUFFER_LENGTH] = {0};

5.8 提交和取得完成事件

 while (1) {
 /* 把当前已经准备好的 SQE 提交给 io_uring */
 io_uring_submit(&ring);

 /* 至少等待一个操作完成 */
 struct io_uring_cqe *cqe;
 io_uring_wait_cqe(&ring, &cqe);

 /* 一次批量取出最多 128 个完成项 */
 struct io_uring_cqe *cqes[128];
 int nready = io_uring_peek_batch_cqe(
 &ring,
 cqes,
 128
 );

 for (int i = 0; i < nready; i++) {
 struct io_uring_cqe *entry = cqes[i];

 /* 从 user_data 还原这个操作的 fd 和类型 */
 struct conn_info result;
 memcpy(&result,
 &entry->user_data,
 sizeof(struct conn_info));

这里的两个信息来源要分清：

result.fd / result.event
 提交 SQE 时由应用保存
 用来识别“谁的什么操作”

entry->res
 操作完成时由内核返回
 用来表示 accept 的新 fd、recv 长度或 send 结果

5.9 分发 ACCEPT、READ 和 WRITE 完成事件

 if (result.event == EVENT_ACCEPT) {
 /*
 * 当前 accept 已完成；
 * 先准备下一个 accept，保持继续接收新连接。
 */
 set_event_accept(
 &ring,
 sockfd,
 (struct sockaddr *)&clientaddr,
 &len,
 0
 );

 /* accept CQE 的 res 是新客户端 fd */
 int connfd = entry->res;

 /* 为新客户端准备第一次 recv */
 set_event_recv(
 &ring,
 connfd,
 buffer,
 BUFFER_LENGTH,
 0
 );

 } else if (result.event == EVENT_READ) {
 /* recv CQE 的 res 是本次收到的字节数 */
 int ret = entry->res;

 if (ret == 0) {
 /* 客户端关闭连接 */
 close(result.fd);
 } else if (ret > 0) {
 /*
 * buffer + ret 构成请求；
 * response 接收 KV 协议输出；
 * 返回值重新赋给 ret，作为响应长度。
 */
 ret = kvs_handler(buffer, ret, response);

 /* 准备把 KV 响应发送给原客户端 */
 set_event_send(
 &ring,
 result.fd,
 response,
 ret,
 0
 );
 }

 } else if (result.event == EVENT_WRITE) {
 /* send CQE 的 res 是写操作完成结果 */
 int ret = entry->res;

 /* 本轮响应结束，再次等待该客户端请求 */
 set_event_recv(
 &ring,
 result.fd,
 buffer,
 BUFFER_LENGTH,
 0
 );
 }
 }

 /* 告诉 ring：这一批 CQE 已经处理完 */
 io_uring_cq_advance(&ring, nready);
 }
}

把整份 Proactor 压缩成一句话：

每处理一个完成事件，就准备这个连接的下一项操作；READ 完成与 WRITE 准备之间插入一次 KV handler 调用。

6. ntyco 协程网络层：`ntyco.c`

6.1 ntyco 在项目中的结构

ntyco_start
 ↓ 创建
server 协程：socket → bind → listen → accept
 ↓ 每个客户端创建
server_reader 协程：recv → kvs_protocol → send

这里不展开 nty_coroutine_create 和 nty_schedule_run 的内部实现，只观察项目怎样调用框架。

6.2 客户端处理协程

/* ntyco_start 保存 main 传入的 kvs_protocol */
static msg_handler kvs_handler;

void server_reader(void *arg) {
 /* server 创建协程时传入的是 cli_fd 地址 */
 int fd = *(int *)arg;
 int ret = 0;

 while (1) {
 /* 每轮准备一个新的接收缓冲区 */
 char buf[1024] = {0};

 /* 接收这个客户端的请求 */
 ret = recv(fd, buf, 1024, 0);

 if (ret > 0) {
 /* 为本轮响应准备缓冲区 */
 char response[1024] = {0};

 /*
 * buf + ret 是请求；
 * response 是 KV 输出；
 * slength 是响应长度。
 */
 int slength = kvs_handler(buf, ret, response);

 /* 将 KV 响应发送给当前客户端 */
 ret = send(fd, response, slength, 0);

 if (ret == -1) {
 close(fd);
 break;
 }
 } else if (ret == 0) {
 /* 客户端正常关闭连接 */
 close(fd);
 break;
 }
 }
}

与 Reactor、Proactor 相比，协程版本把同一个客户端的处理过程写在一个顺序循环里：

recv(...);
kvs_handler(...);
send(...);

6.3 监听协程

void server(void *arg) {
 /* 还原 ntyco_start 传入的端口 */
 unsigned short port = *(unsigned short *)arg;

 /* 创建 IPv4 TCP 监听 socket */
 int fd = socket(AF_INET, SOCK_STREAM, 0);
 if (fd < 0) return;

 /* 填写本地监听地址 */
 struct sockaddr_in local, remote;
 local.sin_family = AF_INET;
 local.sin_port = htons(port);
 local.sin_addr.s_addr = INADDR_ANY;

 /* 绑定并监听 */
 bind(fd,
 (struct sockaddr *)&local,
 sizeof(struct sockaddr_in));
 listen(fd, 20);

 printf("listen port : %d\n", port);

 while (1) {
 socklen_t len = sizeof(struct sockaddr_in);

 /* 接受一个客户端连接 */
 int cli_fd = accept(
 fd,
 (struct sockaddr *)&remote,
 &len
 );

 /*
 * 每个客户端创建一个 server_reader 协程；
 * 该协程负责此后的 recv、KV 处理和 send。
 */
 nty_coroutine *read_co;
 nty_coroutine_create(
 &read_co,
 server_reader,
 &cli_fd
 );
 }
}

6.4 ntyco 网络层入口

int ntyco_start(unsigned short port, msg_handler handler) {
 /* 保存 kvs_protocol */
 kvs_handler = handler;

 /* 创建负责监听和 accept 的 server 协程 */
 nty_coroutine *co = NULL;
 nty_coroutine_create(&co, server, &port);

 /* 启动 ntyco 调度器 */
 nty_schedule_run();
}

把 ntyco 版本压缩成一句话：

server 协程负责产生连接，每个连接再由一个 reader 协程按顺序完成接收、协议处理和发送。

7. 三种网络层放在一起回顾

7.1 同一阶段的代码对应关系

阶段	Reactor	io_uring Proactor	ntyco
保存 KV 函数	`kvs_handler = handler`	`kvs_handler = handler`	`kvs_handler = handler`
等待连接	监听 fd 的 `EPOLLIN`	提交 `ACCEPT` SQE	`server` 协程调用 `accept`
获得连接	`accept_cb()`	`EVENT_ACCEPT` CQE	`accept()` 返回
等待请求	客户端 fd 的 `EPOLLIN`	提交 `RECV` SQE	reader 协程调用 `recv`
KV 接入点	`kvs_request()`	`EVENT_READ` 分支	`server_reader()`
发送响应	`send_cb()`	提交 `SEND` SQE	reader 协程调用 `send`
继续循环	改回 `EPOLLIN`	WRITE 完成后再提交 RECV	while 回到 recv

7.2 一次请求的三条完整路径

Reactor

epoll_wait
 → EPOLLIN
 → recv_cb
 → conn.rbuffer / conn.rlength
 → kvs_request
 → kvs_protocol
 → conn.wbuffer / conn.wlength
 → EPOLLOUT
 → send_cb
 → EPOLLIN

Proactor

提交 RECV
 → READ CQE
 → buffer / entry->res
 → kvs_protocol
 → response / 响应长度
 → 提交 SEND
 → WRITE CQE
 → 再提交 RECV

ntyco

server_reader 协程
 → recv
 → buf / ret
 → kvs_protocol
 → response / slength
 → send
 → 下一轮 recv

7.3 两种回调不要混淆

/* Reactor 内部的网络事件回调 */
typedef int (*RCALLBACK)(int fd);

/* 三种网络层共同使用的 KV 协议回调 */
typedef int (*msg_handler)(char *msg,
 int length,
 char *response);

它们的层次是：

Reactor 中：
epoll → RCALLBACK → recv_cb → msg_handler → kvs_protocol

Proactor 中：
CQE → EVENT_READ 分支 → msg_handler → kvs_protocol

ntyco 中：
server_reader → msg_handler → kvs_protocol

8. 最后的整体记忆

重新回顾这个项目时，只需要先恢复四个关键词：

NETWORK_SELECT
 决定使用 Reactor、Proactor 还是 ntyco

msg_handler
 把网络层与 KV 协议层连接起来

kvs_protocol
 接收请求、生成响应，当前实现为 echo

网络事件循环
 三种模型分别用 epoll、io_uring、协程完成连接和收发

整个程序的共同主干是：

/* main 把协议函数交给网络层 */
network_start(port, kvs_protocol);

/* 网络层保存函数地址 */
kvs_handler = handler;

/* 网络层收到请求后调用它 */
response_len = kvs_handler(
 request,
 request_len,
 response
);

/* 网络层按返回长度发送响应 */
send(clientfd, response, response_len, 0);

这四步就是六份代码共同围绕的核心。三种网络模型改变的是“请求怎样到达这四步、响应怎样离开这四步”，而 KV 协议入口保持一致。

io_uring（二）：QPS 实测，真的比 epoll 强吗？

Thu, 20 Aug 2026 00:00:00 +0800

一、学习目标

这部分学习主要围绕两个目标展开：

编写一个 TCP 客户端测试工具，对比 epoll 和 io_uring 服务端的性能。
整理网络相关面试题，重点理解 TCP、UDP、建链、断链、并发及分包粘包问题。

二、QPS 测试工具需求

客户端需要支持以下参数：

-n request_num 请求总数
-t thread_num 线程数量
-c connection_num 连接数量
-s server_ip 服务端 IP
-p server_port 服务端端口

使用示例：

./test_qps_tcpclient \
 -s 172.16.145.129 \
 -p 2048 \
 -t 50 \
 -c 100 \
 -n 10000

测试采用 Echo 模型：

客户端向服务端发送一段数据。
服务端将数据原样返回。
客户端比较发送和接收的数据。
数据一致则请求成功，否则失败。
最后统计总耗时和 QPS。

QPS 的计算方式为：

QPS = 完成的请求数 ÷ 耗时（秒）

代码中使用毫秒计时，因此写成：

qps = request_num * 1000 / time_used_ms;

三、测试数据的构造

测试字符串为：

#define TEST_MESSAGE \
"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890abcdefghijklmnopqrstuvwxyz\r\n"

这段字符串的长度正好是 64 字节：

26 个大写字母
+ 10 个数字
+ 26 个小写字母
+ \r\n 两个字符
= 64 字节

通过重复复制，可以构造不同大小的请求：

for (i = 0; i < 2; i++) {
 strcpy(
 wbuffer + i * strlen(TEST_MESSAGE),
 TEST_MESSAGE
 );
}

重复次数与数据长度的关系如下：

重复次数	数据长度
1	64 字节
2	128 字节
4	256 字节
8	512 字节
16	1024 字节

测试大包时，需要关闭服务端和客户端的数据打印，否则终端输出本身会严重影响测试结果。

四、64 bytes 测试

测试 100 万次、每次发送 64 bytes 时，结果如下：

数据长度	服务端模型	成功	失败	耗时	QPS
64 bytes	epoll	1000000	0	5132 ms	194855
64 bytes	io_uring	1000000	0	4400 ms	227272

在 64 bytes 测试中：

epoll QPS：194855
io_uring QPS：227272

io_uring 的 QPS 比 epoll 高约 16.6%。

五、不同数据长度下的测试

1. io_uring 服务端

数据长度	成功	耗时	QPS
128 bytes	1000000	4337 ms	230574
256 bytes	1000000	4268 ms	234301
512 bytes	1000000	4307 ms	232180
1024 bytes	1000000	4390 ms	227790

从结果来看，在 128～1024 bytes 范围内，io_uring 的 QPS 比较稳定，基本维持在 22 万～23 万。

1024 bytes 测试时，笔记中怀疑可能出现“粘包”。

更准确地说，TCP 本身是字节流，没有一条 send() 必须对应一条 recv() 的保证。一次发送的 1024 bytes，可能需要多次 recv() 才能完整读取，因此客户端必须实现循环接收。

2. epoll 服务端——阻塞 I/O

数据长度	成功	耗时	QPS
128 bytes	1000000	74935 ms	13344
256 bytes	1000000	147749 ms	6768
512 bytes	1000000	296207 ms	3376
1024 bytes	1000000	721163 ms	1386

这组结果明显异常：数据长度每增加一倍，耗时几乎也增加一倍，QPS 则接近减半。

问题在于 epoll 服务端使用了阻塞 socket。

epoll 的作用是通知程序某个 fd 当前可读或者可写。但即使 fd 已经可读，也不代表接下来所有的 recv() 都不会阻塞。

尤其是在循环读取时，如果已经把当前到达的数据读完，又调用了一次阻塞式 recv()，整个事件循环就可能停在某一个连接上，导致其他连接无法及时处理。

所以 epoll 一般需要与非阻塞 socket 配合：

epoll 通知 fd 可读
 ↓
循环调用 recv
 ↓
读取当前已经到达的数据
 ↓
recv 返回 EAGAIN
 ↓
处理下一个就绪事件

3. epoll 服务端——非阻塞 I/O

将 socket 设置成非阻塞后重新测试：

数据长度	成功	耗时	QPS
128 bytes	1000000	5198 ms	192381
256 bytes	1000000	5144 ms	194401
512 bytes	1000000	5141 ms	194514
1024 bytes	1000000	5216 ms	191717

修改后，epoll 的 QPS 恢复到约 19 万，并且不再随数据长度增加而大幅下降。

这说明前一组数据反映的主要不是 epoll 本身的性能，而是“epoll 配合阻塞 I/O”造成的异常。

六、epoll 与 io_uring 的完整对比

数据长度	io_uring QPS	epoll QPS
64 bytes	227272	194855
128 bytes	230574	192381
256 bytes	234301	194401
512 bytes	232180	194514
1024 bytes	227790	191717

从测试结果来看：

64 bytes 时，io_uring 比 epoll 高约 16.6%；
128～1024 bytes 时，io_uring 大约比 epoll 高 19%～21%；
所有测试包大小下，io_uring 的 QPS 都高于 epoll；
两种模型在改正 epoll 的阻塞 I/O 问题后，QPS 都没有随着数据大小增加而发生明显下降。

二者的处理思路不同。

epoll

epoll 是就绪通知模型：

先等待 fd 可读或可写
→ 得到就绪事件
→ 应用程序再调用 recv/send

也就是说，epoll 负责告诉应用程序“现在可以尝试进行 I/O”，真正的数据读写仍然由应用程序发起。

io_uring

io_uring 更接近完成通知模型：

应用程序先提交 recv/send 请求
→ 内核执行 I/O
→ I/O 完成后通知应用程序

应用程序可以提前向内核提交 I/O 请求，然后通过完成队列取得结果。

根据本次测试，可以得到以下结论：

在当前服务端实现、当前客户端模型和当前测试环境下，io_uring 的 QPS 全面高于非阻塞 epoll，整体高约 17%～21%。

这个结论应当限定在本次测试条件内，不能仅凭这一轮测试认为所有业务中 io_uring 都一定优于 epoll。

七、业务中的数据包大小

实际业务中可能同时存在小包和大包。

1. 心跳包

客户端和服务端之间通常会存在心跳包。

心跳包只用于检测连接是否仍然存活，因此数据量通常很小，可能只有几个字节。

这类场景更关注：

大量连接的管理能力；
小包的处理效率；
I/O 事件通知和调度开销；
服务端是否能够及时发现断开的连接。

2. 视频和图片传输

视频或者较大的图片需要被拆分成多个数据块。

应用层可以将每一个业务包组织成约 1 KB，再通过协议头标识数据长度、类型和序号。

这类场景除了 QPS，还需要关注：

吞吐量；
单次发送的数据大小；
分包和组包；
内存复制；
慢连接对事件循环的影响。

因此，也可以结合不同数据大小下的测试结果，理解 epoll 和 io_uring 的差别。

3. 百万并发测试

后续还可以使用 io_uring 和 epoll 测试百万并发，包括：

建立相同数量连接所需要的时间；
相同并发连接数下的 QPS；
百万连接下的内存占用；
建链事件的处理能力；
断链事件的处理能力。

断开连接涉及 TCP 协议栈中的状态转换，但应用层仍然需要正确执行 close()、移除连接状态，并释放自己管理的连接资源。

八、QPS 客户端代码详解

1. 测试上下文

struct test_context_s {
 char serverip[16];
 int port;
 int threadnum;
 int connection;
 int requestion;

#if 1
 int failed;
#endif
};

typedef struct test_context_s test_context_t;

这个结构保存测试参数：

serverip：服务端 IPv4 地址；
port：服务端端口；
threadnum：测试线程数；
connection：期望建立的连接数量；
requestion：请求总数；
failed：失败请求数。

requestion 想表达的应该是请求数量，也就是 request_count 或者 requests，只是命名不太准确，不影响程序运行。

serverip 的长度是 16，刚好可以保存最长的 IPv4 字符串和字符串结尾的 \0：

255.255.255.255\0

不过，代码使用的是：

strcpy(ctx.serverip, optarg);

如果传入的参数超过数组长度，就会发生越界写入。

2. 建立 TCP 连接

int connect_tcpserver(
 const char *ip,
 unsigned short port
)

函数首先创建 TCP socket：

int connfd = socket(AF_INET, SOCK_STREAM, 0);

其中：

AF_INET 表示使用 IPv4；
SOCK_STREAM 表示使用 TCP；
返回值 connfd 是连接对应的文件描述符。

然后构造服务端地址：

struct sockaddr_in tcpserver_addr;

memset(
 &tcpserver_addr,
 0,
 sizeof(struct sockaddr_in)
);

清零后设置地址类型：

tcpserver_addr.sin_family = AF_INET;

设置服务端 IP：

tcpserver_addr.sin_addr.s_addr = inet_addr(ip);

inet_addr() 将类似下面的 IPv4 字符串：

172.16.145.129

转换成网络地址。

设置端口：

tcpserver_addr.sin_port = htons(port);

htons() 将端口从主机字节序转换成网络字节序。

最后调用：

int ret = connect(
 connfd,
 (struct sockaddr *)&tcpserver_addr,
 sizeof(struct sockaddr_in)
);

如果连接成功，返回 connfd：

return connfd;

如果连接失败，返回 -1：

if (ret) {
 perror("connect\n");
 return -1;
}

当前代码没有检查 socket() 是否创建失败。

另外，如果 connect() 失败，已经创建的 connfd 没有关闭，会造成文件描述符泄漏。

3. 时间计算

#define TIME_SUB_MS(tv1, tv2) \
 ((tv1.tv_sec - tv2.tv_sec) * 1000 + \
 (tv1.tv_usec - tv2.tv_usec) / 1000)

这个宏用来计算两个 timeval 之间相差的毫秒数：

秒差 × 1000 + 微秒差 ÷ 1000

主函数在线程创建前记录开始时间：

struct timeval tv_begin;
gettimeofday(&tv_begin, NULL);

所有线程结束后记录结束时间：

struct timeval tv_end;
gettimeofday(&tv_end, NULL);

然后计算：

int time_used = TIME_SUB_MS(tv_end, tv_begin);

因此，当前统计结果包含：

创建线程的时间；
建立 TCP 连接的时间；
发送和接收请求的时间；
等待线程退出的时间。

所以当前 QPS 是一轮完整压测的整体 QPS，并不是纯粹的数据收发 QPS。

如果后续需要分别测试建链性能和请求处理性能，就需要把建立连接和发送请求分开计时。

4. 测试消息

#define TEST_MESSAGE \
"ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890abcdefghijklmnopqrstuvwxyz\r\n"

#define RBUFFER_LENGTH 2048
#define WBUFFER_LENGTH 2048

TEST_MESSAGE 是 64 bytes。

读缓冲区和写缓冲区都设置为 2048 bytes。

在当前代码中，WBUFFER_LENGTH 宏并没有被使用，因为写缓冲区直接写成了：

char wbuffer[2048] = {0};

5. 单次请求过程

int send_recv_tcppkt(int fd)

这个函数完成一次请求和响应。

构造发送数据

char wbuffer[2048] = {0};
int i = 0;

for (i = 0; i < 2; i++) {
 strcpy(
 wbuffer + i * strlen(TEST_MESSAGE),
 TEST_MESSAGE
 );
}

由于 TEST_MESSAGE 为 64 bytes，循环两次后，wbuffer 中保存了 128 bytes 数据。

第一次复制的位置是：

wbuffer + 0

第二次复制的位置是：

wbuffer + 64

因此，两段 64 bytes 的数据首尾相连，组成 128 bytes 的请求。

发送数据

int res = send(
 fd,
 wbuffer,
 strlen(wbuffer),
 0
);

如果发送失败：

if (res < 0) {
 exit(1);
}

这里的主要问题是，一次 send() 不保证发送完全部数据。

例如：

send(fd, buffer, 1024, 0);

返回值可能是：

1024：全部发送完成
512：只发送了 512 bytes
-1：发送失败

所以不能只判断 res < 0，还需要判断返回值是否等于预期发送长度。

正确的逻辑应当是：

记录总共需要发送的长度
 ↓
循环调用 send
 ↓
每次根据返回值移动缓冲区指针
 ↓
直到所有字节发送完成

接收数据

char rbuffer[RBUFFER_LENGTH] = {0};

res = recv(
 fd,
 rbuffer,
 RBUFFER_LENGTH,
 0
);

如果返回值小于或者等于 0：

if (res <= 0) {
 exit(1);
}

recv() 的返回值含义是：

大于 0：本次实际读取的字节数
等于 0：对端正常关闭连接
小于 0：读取失败

和 send() 一样，一次 recv() 也不保证读取到完整的响应。

服务端即使完整返回了 1024 bytes，客户端也可能出现：

第一次 recv：读取 300 bytes
第二次 recv：读取 500 bytes
第三次 recv：读取 224 bytes

因此，需要循环接收，直到读取到预期长度。

这正是笔记中“很有必要重新封装一个 recv 和 send”的原因。

比较数据

if (strcmp(rbuffer, wbuffer) != 0) {
 printf(
 "failed: '%s'!='%s'\n",
 rbuffer,
 wbuffer
 );
 return -1;
}

这里通过 strcmp() 比较接收数据和发送数据。

但网络数据本质上是一段带长度的二进制数据，使用 strcmp() 的前提是两个缓冲区都以 \0 结尾。

更稳定的比较方式是根据实际数据长度使用：

memcmp(rbuffer, wbuffer, expected_length);

如果一次 recv() 只读到部分数据，那么当前 strcmp() 会直接认为请求失败，即使剩余数据稍后还能继续收到。

6. 工作线程

static void *test_qps_entry(void *arg)

线程首先取得测试上下文：

test_context_t *pctx =
 (test_context_t *)arg;

原始笔记中出现了：

(test\_context\_t *)arg

如果实际代码中确实包含反斜杠，需要将反斜杠删除。它也可能只是复制代码时产生的 Markdown 转义。

计算每个线程的连接数

int conn_num =
 pctx->connection / pctx->threadnum;

这里理论上表示每个线程需要管理多少个连接。

例如：

连接数：100
线程数：50
每个线程应当管理：2 个连接

但是，conn_num 后面没有被使用。

实际代码只建立了一次连接：

int connfd = connect_tcpserver(
 pctx->serverip,
 pctx->port
);

因此，每个线程只建立一个连接。

这意味着：

-t 50 -c 100

实际建立的不是 100 个连接，而是 50 个连接。

当前代码中的 -c 参数实际上没有生效。

计算每个线程的请求数

int count =
 pctx->requestion / pctx->threadnum;

例如：

请求总数：10000
线程数：50
每个线程：200 次请求

每个线程执行：

while (i++ < count) {
 res = send_recv_tcppkt(connfd);

 if (res != 0) {
 printf("send_recv_tcppkt failed\n");
 pctx->failed++;
 continue;
 }
}

线程中的请求模型为：

发送一次请求
 ↓
阻塞等待响应
 ↓
收到完整响应
 ↓
再发送下一次请求

所以每个连接同一时间最多只有一个未完成请求。

整个客户端能够同时处理的请求数量，实际上接近线程数量，而不是 -c 指定的连接数量。

请求数量不能整除线程数

如果：

-n 10003
-t 50

则：

count = 10003 / 50;

整数除法结果为：

实际发送请求数为：

200 × 50 = 10000

剩余 3 次请求不会发送。

但是，程序最后仍然按照 10003 计算成功数量和 QPS，所以统计结果会不准确。

7. 失败请求统计

失败时执行：

pctx->failed++;

所有线程共享同一个 failed，但这里没有加锁，也没有使用原子变量。

多个线程可能同时执行：

pctx->failed++;

例如，两个线程同时读到：

failed = 10

两个线程都计算得到 11，再分别写回，最终结果可能仍然是 11，而不是正确的 12。

因此，当前失败数具有以下特点：

可以粗略判断是否出现了失败；
不能保证失败数量准确；
多线程同时修改时存在数据竞争。

笔记中提到“数据没有那么重要，只需要知道有失败的可能性”，这种处理可以用于临时测试，但最终版本如果需要准确统计失败数，仍然需要使用锁或者原子操作。

8. 命令行参数解析

主函数通过 getopt() 解析参数：

while (
 (opt = getopt(
 argc,
 argv,
 "s:p:t:c:n:?"
 )) != -1
)

参数含义如下：

-s：服务端 IP
-p：服务端端口
-t：线程数量
-c：连接数量
-n：请求数量

例如：

case 's':
 strcpy(ctx.serverip, optarg);
 break;

读取 IP。

case 'p':
 ctx.port = atoi(optarg);
 break;

读取端口。

case 't':
 ctx.threadnum = atoi(optarg);
 break;

读取线程数量。

case 'c':
 ctx.connection = atoi(optarg);
 break;

读取连接数量。

case 'n':
 ctx.requestion = atoi(optarg);
 break;

读取请求总数。

getopt() 使用了一些全局状态，因此笔记中记录它不是线程安全函数。不过当前代码只在主线程、创建工作线程之前调用，所以不会产生并发调用问题。

9. 创建工作线程

程序首先根据线程数量申请线程 ID 数组：

pthread_t *ptid =
 malloc(
 ctx.threadnum * sizeof(pthread_t)
 );

然后记录开始时间：

struct timeval tv_begin;
gettimeofday(&tv_begin, NULL);

创建工作线程：

for (i = 0; i < ctx.threadnum; i++) {
 pthread_create(
 &ptid[i],
 NULL,
 test_qps_entry,
 &ctx
 );
}

所有线程都接收同一个 ctx 地址：

&ctx

其中：

IP、端口、线程数、连接数和请求数只读；
failed 会被所有线程共同修改。

创建完成后，主线程等待所有工作线程退出：

for (i = 0; i < ctx.threadnum; i++) {
 pthread_join(ptid[i], NULL);
}

只有全部线程执行完毕，主线程才会继续计算总耗时。

10. 统计 QPS

所有线程结束后，记录结束时间：

struct timeval tv_end;
gettimeofday(&tv_end, NULL);

计算总耗时：

int time_used =
 TIME_SUB_MS(tv_end, tv_begin);

最后输出：

printf(
 "success: %d,failed:%d,"
 "time_used:%d,qps:%d\n",
 ctx.requestion - ctx.failed,
 ctx.failed,
 time_used,
 ctx.requestion * 1000 / time_used
);

输出内容包括：

成功请求数；
失败请求数；
总耗时；
QPS。

当前 QPS 使用的是：

ctx.requestion * 1000 / time_used

这里使用了配置的请求数，而不是实际完成的请求数。

如果请求数不能整除线程数，或者中间出现失败，QPS 就不能准确表示真正成功完成的请求数量。

11. 资源释放

主函数结束前释放线程数组：

free(ptid);

但工作线程建立的 TCP 连接没有关闭：

close(connfd);

在线程退出前，应当关闭自己创建的连接。

虽然进程退出时，操作系统最终会回收文件描述符，但如果后续让一个进程连续执行多轮测试，不关闭连接就会逐渐产生资源泄漏。

九、当前客户端的实际测试模型

虽然命令行参数中包含 -c，但当前代码的实际模型是：

主线程
 ├─ 工作线程 1
 │ └─ 一个 TCP 连接
 │ └─ 串行发送请求
 │
 ├─ 工作线程 2
 │ └─ 一个 TCP 连接
 │ └─ 串行发送请求
 │
 ├─ 工作线程 3
 │ └─ 一个 TCP 连接
 │ └─ 串行发送请求
 │
 └─ 其他工作线程
 └─ 每个线程一个 TCP 连接

因此：

实际连接数 = 线程数
每个连接同时只有一个请求
-c 参数没有生效

当前工具比较的是：

多线程、每个线程使用一个阻塞 TCP 连接、请求与响应严格交替时，epoll 和 io_uring 服务端的处理能力。

它还不能测试固定线程数管理大量连接的能力，也不能直接用于百万并发测试。

如果需要让 -c 生效，每个线程就要创建：

connection / threadnum

个连接，并在这些连接之间分配请求。

十、当前代码需要优先处理的问题

按照对测试准确性的影响排序：

-c 参数没有生效，每个线程实际上只建立一个连接。
send() 没有循环处理短写。
recv() 没有循环处理短读。
请求数不能整除线程数时，实际请求数量少于 -n。
failed++ 存在多线程数据竞争。
工作线程结束后没有执行 close(connfd)。
QPS 使用配置的请求数计算，而不是实际完成数。
没有检查 socket()、malloc() 和 pthread_create() 的返回值。
connect() 失败后没有关闭已经创建的 socket。
工作线程中的 exit(1) 会让一个线程的网络错误终止整个压测进程。
如果源代码确实包含 test\_context\_t，需要删除反斜杠。
如果源代码第一行确实是 include<stdio.h>，需要补上 #。

十一、网络面试问题整理

原始笔记目前记录了四个核心问题，没有足够内容整理成十个，因此这里只整理已有内容，不额外补题。

1. TCP 三次握手与四次挥手

三次握手

客户端 服务端

SYN
 ------------------------>

 SYN + ACK
 <------------------------

ACK
 ------------------------>

三次握手需要确认：

客户端能够发送；
服务端能够接收；
服务端能够发送；
客户端能够接收；
双方同步初始序列号。

之所以不能只使用两次握手，是因为服务端发送 SYN + ACK 后，还需要知道客户端是否真正收到了自己的响应。

第三次 ACK 让服务端确认：

客户端已经收到服务端的 SYN
客户端也能够正常接收数据

2. 为什么建链是三次，断链通常是四次

建立连接时，服务端可以把两个操作合并：

确认客户端的 SYN
+
发送自己的 SYN

因此，服务端可以通过一个 SYN + ACK 同时完成这两个操作，最终形成三次握手。

断开连接时：

收到 FIN 后必须先回复 ACK；
但是本端可能还有数据没有发送完；
等剩余数据发送完成后，才能发送自己的 FIN。

因此，ACK 和 FIN 通常不能立即合并，形成四次挥手。

四次挥手

主动关闭方 被动关闭方

FIN
 ------------------------>

 ACK
 <------------------------

 FIN
 <------------------------

ACK
 ------------------------>

TCP 是全双工连接，两个方向需要分别关闭。

一方发送 FIN，只表示自己不再发送数据，并不表示对方也已经没有数据可发。

如果对方收到 FIN 时，刚好也没有剩余数据需要发送，那么 ACK 和 FIN 也可能合并。

3. UDP 的并发如何实现

UDP 没有 TCP 中的：

listen
accept
connection fd

客户端通过：

sendto()

向服务端指定的 IP 和端口发送数据。

服务端通过：

recvfrom()

接收数据，同时得到客户端的 IP 和端口。

假设有 100 万个客户端同时向同一个 UDP 端口发送数据，内核会按照数据报把数据放入 socket 的接收队列。

服务端每次调用 recvfrom() 时，可以获得：

一条 UDP 数据报；
发送方的 IP；
发送方的端口。

因此，不会因为多个客户端共用一个服务端端口，就直接把不同客户端的数据拼接成一条“脏数据”。

应用层可以使用：

客户端 IP + 客户端端口

标识一个逻辑会话。

笔记中提出了一种模拟 TCP 的管理方式：

客户端第一次向服务端发送握手包；
服务端得到客户端的 IP 和端口；
服务端为这个客户端建立逻辑会话；
后续通过会话信息管理双方的数据；
如果需要分散压力，可以使用多个服务端端口或者多个 UDP socket。

例如：

2000 个端口
每个端口管理约 1000 个逻辑连接
总计约 200 万个逻辑连接

但是，不一定需要为每个 UDP 客户端单独分配一个端口。

UDP 的并发数量也不是直接受 65535 个端口限制。多个客户端可以通过不同的来源 IP 和来源端口访问同一个服务端端口。

这一部分需要继续整理成一篇独立的技术笔记：

UDP 的并发实现与应用层会话管理。

4. TCP 和 UDP 有哪些区别

连接方式

TCP 是面向连接的协议。

通信前需要建立连接：

客户端连接 fd ←→ 服务端连接 fd

服务端通过 accept() 为每个客户端创建连接 fd，因此每条 TCP 连接都有独立的连接状态。

UDP 是无连接协议。

客户端不需要先建立 TCP 意义上的连接，可以直接通过 sendto() 发包，服务端通过 recvfrom() 接收。

数据形式

TCP 是字节流协议。

它传输的是连续字节流，本身不保留应用层的消息边界。

UDP 是数据报协议。

每次 sendto() 发送一条 UDP 数据报，接收端通过 recvfrom() 接收一条数据报。UDP 会保留数据报边界，但如果接收缓冲区太小，超出的部分可能被截断。

可靠性和顺序

TCP 提供：

有序传输；
丢包重传；
流量控制；
拥塞控制。

先发送的数据，在连接正常的情况下，会先交付给接收方应用程序。

UDP 本身不保证：

数据一定到达；
数据按照发送顺序到达；
数据不会重复；
丢失的数据会自动重传。

如果业务需要这些能力，就需要在 UDP 的应用层加入：

包 ID；
数据序号；
ACK 确认；
超时重传；
去重；
乱序重排。

例如，把一份大数据拆成多个 UDP 包时，可以在用户空间定义：

消息 ID
分片序号
总分片数量

接收端根据 ID 和序号判断当前收到的是第几个包，并将多个数据包重新组装。

5. TCP 的分包与粘包

TCP 是字节流。

应用层调用一次：

send(fd, buffer, 1024, 0);

并不代表接收端一定通过一次：

recv(fd, buffer, 1024, 0);

得到完整数据。

可能出现：

一次 send → 多次 recv
多次 send → 一次 recv

所以所谓的 TCP 分包和粘包，本质上是应用层没有明确消息边界。

常见解决方法有两种。

方法一：长度字段

在应用数据的头部记录消息体长度：

| 固定长度的消息头 | 消息体 |

例如使用前两个或者前四个字节表示长度：

| 2 bytes 长度 | 实际数据 |

接收端先读取固定长度的消息头：

先循环读取 2 bytes
 ↓
解析出消息体长度
 ↓
再循环 recv
 ↓
读取完整消息体

由于 TCP 保证字节流有序，因此接收端可以按照这个顺序解析数据。

方法二：分隔符

每条消息后面增加一个特殊分隔符，例如：

\r\n\r\n

接收端不断读取数据并放入缓冲区，然后查找分隔符：

收到数据
 ↓
加入接收缓冲区
 ↓
查找 \r\n\r\n
 ↓
找到后切出一条完整消息

如果消息正文中也可能出现相同分隔符，就需要进行转义，或者使用长度字段。

6. TCP 和 UDP 的并发区别

TCP 服务端通常采用：

listen socket
 ↓
accept
 ↓
每个客户端对应一个连接 fd
 ↓
使用 epoll 管理大量连接 fd

TCP 协议栈已经维护了每条连接的状态，因此应用层可以通过不同 fd 区分客户端。

UDP 没有为每个客户端创建独立的连接 fd。

服务端一般根据：

来源 IP
来源端口
应用层会话 ID

管理客户端状态。

因此，不是说 UDP 不能做高并发，而是 UDP 需要在应用层建立自己的会话管理方式。

7. UDP 的使用场景

UDP 更适合以下场景：

实时音视频；
对实时性要求较高的游戏数据；
DNS 等一次请求、一次响应的场景；
能够容忍少量丢包的场景；
由应用层自己控制可靠性的场景。

例如在游戏团战中，玩家位置、技能释放和实时状态对延迟比较敏感。

如果一个旧的位置数据由于重传很晚才到达，这个数据可能已经失去意义。因此，这类实时状态通常更偏向使用 UDP。

但是，“对战游戏没有使用 TCP”这个说法过于绝对。

更合适的理解是：

游戏中强调实时性的位置、动作等消息更倾向使用 UDP；登录、充值、聊天等要求可靠的数据仍然可能使用 TCP。

8. TCP 的使用场景

TCP 更适合：

文件传输；
需要完整交付的数据；
需要严格有序的数据；
HTTP/1.1、HTTP/2 等基于 TCP 的协议；
长连接通信。

文件下载需要保证最终文件完整，因此通常需要可靠传输。

UDP 本身没有拥塞控制和可靠重传。如果使用 UDP 传输文件，应用层就需要自己实现：

丢包检测；
重传；
顺序恢复；
流量控制；
拥塞控制。

TCP 已经提供了这些能力，因此使用 TCP 开发更加直接。

9. 短通信与长连接

DNS 是典型的短请求、短响应场景：

发送一次查询
 ↓
服务端返回查询结果
 ↓
本次通信结束

UDP 不需要建立连接，适合这种简单的请求响应。

“UDP 做短连接”更准确的说法是：

UDP 没有 TCP 意义上的连接，适合短暂的一次性请求响应。

有些业务也会选择 TCP 完成短请求，因为：

TCP 相关框架成熟；
开发更加方便；
不需要自己实现可靠性；
业务本身更重视开发成本和正确性。

TCP 则天然适合需要长期保持通信状态的长连接，但 TCP 并不是只能做长连接。

十二、阶段总结

从传统阻塞 I/O、epoll 再到 io_uring，容易产生一种混沌感。

当前最需要捋清的是三个层次之间的关系：

TCP
提供字节流、连接、可靠传输等协议能力
 ↓
epoll / io_uring
解决应用程序如何高效处理 I/O
 ↓
业务协议
解决消息边界、心跳、会话和错误处理

本轮实验可以得到三个明确认识：

epoll 应当与非阻塞 I/O 配合，否则单个连接可能阻塞整个事件循环。
当前测试中，io_uring 的 QPS 全面高于非阻塞 epoll，整体优势约为 17%～21%。
客户端的连接模型、收发方式和计数准确性，会直接影响测试结果。当前 -c 参数没有生效，循环收发也尚未实现。

十三、面试复盘

面试需要不断复盘。

简历中能够被问到的内容是有限的，每次面试后都应该记录问题，并重新整理问题背后的知识。

原笔记中的经验数据为：

面试时间	个人估计的通过概率
30 分钟	5%
45 分钟	30%
60 分钟	80%

求职过程可以通过两个比例进行观察：

邀面数量 / 投递数量
→ 反映简历的匹配度和成功度

Offer 数量 / 邀面数量
→ 反映技术能力和面试表现

IOCP：Windows 异步机制

Thu, 20 Aug 2026 00:00:00 +0800

一、网络编程要解决什么问题

在 C/S 模式中，服务端通常先执行：

socket -> bind -> listen

客户端也会先创建 socket。各种网络模型前面的准备过程基本相同，主要区别在后续如何处理连接和 I/O。

网络编程中有四件无法预先确定的事情：

客户端什么时候建立连接；
客户端什么时候断开连接；
客户端什么时候发送数据；
数据什么时候能够写入发送缓冲区。

因此，网络编程主要解决四类问题：

连接的建立；
连接的断开；
数据的接收；
数据的发送。

每个 socket 都对应接收缓冲区（receive buffer）和发送缓冲区（send buffer）。write 只负责把数据从用户态复制到内核态的发送缓冲区；数据什么时候到达对端、如何到达对端，属于网络协议栈要解决的问题。

常见的网络模型包括：

阻塞 I/O 模型；
Reactor；
Proactor（IOCP）。

二、阻塞 I/O 与 Reactor

一次 I/O 可以分成两个阶段：

I/O 检测：判断 I/O 是否就绪；
I/O 操作：真正执行 accept、read、write、connect 等操作。

1. 阻塞 I/O

阻塞 I/O 通过阻塞当前线程来等待 I/O 就绪，从而解决“不知道事件什么时候发生”的问题。

阻塞和非阻塞主要描述 I/O 检测阶段：

阻塞：I/O 没有就绪时，线程会等待；
非阻塞：I/O 没有就绪时，函数立即返回。

2. Reactor

Reactor 使用：

I/O 多路复用（检测 I/O）+ 非阻塞 I/O（操作 I/O）

它先注册事件。当事件触发时，系统发出就绪通知，用户层收到通知后，再调用 POSIX I/O 函数完成操作。因此，Reactor 属于：

同步 I/O + 异步事件通知

select、poll、epoll 用于同时检测多路 I/O 是否就绪，它们只负责 I/O 检测；Reactor 则包含 I/O 检测和后续的 I/O 操作。

所以它们的关系是：

Reactor = select/poll/epoll 等 I/O 多路复用 + 非阻塞 I/O 操作

三、IOCP 与 Reactor 的区别

IOCP（I/O Completion Port，I/O 完成端口）是 Windows 提供的一种高效异步 I/O 机制。

Reactor 的过程：

注册事件
 ↓
内核检测到 I/O 就绪
 ↓
用户层收到就绪通知
 ↓
用户层调用 accept/read/write 等函数完成 I/O

这是一种就绪通知。

IOCP 的过程：

用户层投递异步 I/O 请求
 ↓
内核检测并完成 I/O
 ↓
用户层收到完成通知

因此：

Reactor：同步 I/O、异步事件；
IOCP：异步 I/O、异步事件。

两者都是为了解决网络 I/O 问题，因此 IOCP 在整体概念上更接近 Reactor；但 IOCP 并不是 select、poll、epoll 这样的 I/O 多路复用机制。

在 Reactor 中，即使 socket 已经就绪，真正的数据复制仍由用户线程调用 I/O 函数完成。IOCP 则由用户层发起异步操作，由内核完成 I/O；在此期间，用户线程可以处理其他任务。

四、IOCP 的工作原理

网络 I/O 属于外设资源，相关数据需要通过系统调用，由内核进行操作。

IOCP 的基本流程如下：

使用 CreateIoCompletionPort 创建完成端口；
将 socket 与 IOCP 绑定；
投递异步 I/O 操作；
内核进行 I/O 检测和 I/O 操作；
操作完成后，内核把完成信息放入完成队列；
用户层通过 GetQueuedCompletionStatus 取得完成通知。

常见的异步操作包括：

AcceptEx：接受连接；
ConnectEx：主动建立连接；
DisconnectEx：主动断开连接；
WSARecv：接收数据；
WSASend：发送数据。

例如建立连接时：

socket 绑定 IOCP
 ↓
投递 AcceptEx
 ↓
内核完成连接接收
 ↓
GetQueuedCompletionStatus 取得完成通知

与传统 accept 不同，AcceptEx 是预先投递的异步请求。服务器可以在启动时投递多个 AcceptEx，从而并发接收多条连接。

IOCP 与线程池

IOCP 通常会绑定一个线程池。

当线程调用 GetQueuedCompletionStatus 时，该线程会与 IOCP 产生关联。线程退出或关闭后，关联取消；一个线程只能关联一个 IOCP。

GetQueuedCompletionStatus 是阻塞接口：

等待完成队列出现数据
 ↓
取得完成状态
 ↓
在用户态处理完成事件

最后可以使用 CloseHandle 关闭 I/O 完成端口句柄。

五、完成事件如何与连接关联

收到完成通知后，需要知道是哪一条连接、哪一次操作完成了。

1. Reactor 中的关联方式

以 epoll 为例，注册事件时可以把一个值交给内核保存：

ev.data.fd = fd;

也可以关联用户态指针：

ev.data.ptr = user_data;

epoll_wait 返回事件时会带回这个值，因此可以判断是哪一条连接发生了事件。

2. IOCP 中的关联方式

IOCP 有两种关联信息。

第一种是 CreateIoCompletionPort 的第三个参数 CompletionKey。它可以保存一个用户态指针，并在其中记录 socket 等连接信息。

第二种是异步函数最后传入的 OVERLAPPED 指针。可以把 OVERLAPPED 放进自定义结构体：

struct OverlappedPerIO {
 OVERLAPPED overlapped;
 SOCKET socket;
 // 其他与本次 I/O 相关的数据
};

内核使用其中的 OVERLAPPED，用户层则可以在结构体中附加需要关联的数据。

可以这样理解：

CompletionKey：关联连接级信息；
OVERLAPPED*：关联某一次 I/O 操作的信息。

六、重叠 I/O

异步 I/O 是投递请求后无需原地等待，可以由其他线程等待完成通知。

重叠 I/O 是指：无需等待上一个 I/O 完成，就可以继续投递下一个操作，让多个操作同时处于进行状态。

例如，如果每次只投递一个 AcceptEx，完成一次后再投递下一次，那么客户端较多时，建立连接的效率会比较低。服务器可以在启动时投递多个 AcceptEx：

AcceptEx 请求 1 ─┐
AcceptEx 请求 2 ─┼─→ 同时等待多个客户端连接
AcceptEx 请求 3 ─┘

每个重叠 I/O 都使用一个独立的 OVERLAPPED 结构。操作完成后，GetQueuedCompletionStatus 会返回对应的 OVERLAPPED*，用户层据此找到这次操作的上下文。

七、连接断开的判断

客户端主动断开连接时，可以通过以下方式判断。

Reactor

epoll_wait 返回 EPOLLHUP 或 EPOLLRDHUP；
read / recv 返回 0。

IOCP

GetLastError 返回相关错误，例如异常断开时的 ERROR_NETNAME_DELETED；
GetQueuedCompletionStatus 返回的完成字节数 dwBytes == 0。

超时情况下还可能出现 WAIT_TIMEOUT。

八、投递操作

AcceptEx 可以多次投递，以并发接收连接；
WSARecv 涉及接收顺序和线程安全问题；
WSASend 可以多次投递。

io_uring（一）：与 epoll 一较高下

Wed, 19 Aug 2026 00:00:00 +0800

核心目标：能从代码上说清楚 epoll 和 io_uring 的区别，而不是只记 API。

1. 今天最重要的结论

一句话区分：

Reactor / epoll：内核通知“现在可以做 I/O 了”，真正的 accept/recv/send 由应用执行。
Proactor / io_uring：应用先提交 I/O 操作，内核完成后通知“这个操作已经做完了”。

最值得记住的一组对照：

epoll 的 EPOLLIN = 可以读了，但数据还没被应用读出
io_uring 的 READ CQE = 读操作已结束，结果在 cqe->res，数据已进入指定 buffer

epoll 的 EPOLLOUT = 现在可以写，但应用还要调用 send/write
io_uring 的 WRITE CQE = 写操作已结束，cqe->res 表示实际写出的字节数

因此，二者虽然都有“注册/提交 → 等待 → 处理事件”的循环，但事件的含义完全不同：

epoll 返回的是就绪事件。
io_uring 返回的是完成事件。

2. “异步”与“异步 I/O”不是一回事

2.1 一般意义上的异步

发起任务后，不原地等待它结束，当前执行流可以继续做别的事；任务完成后再通过回调、消息、事件或协程恢复等方式取得结果。

例如：把日志写盘任务放入线程池。业务线程只投递任务，工作线程实际调用同步 write()。从业务流程看它是异步的，但底层 write() 本身仍可能是同步 I/O。

2.2 同步 I/O

普通的：

read(fd, buffer, length);
write(fd, buffer, length);
recv(fd, buffer, length, 0);
send(fd, buffer, length, 0);

一次函数调用既发起操作，也返回该次操作的结果。即使 fd 被设为非阻塞，调用者仍然要亲自执行 recv/send；“非阻塞”不自动等于“异步 I/O”。

2.3 epoll 做到的是什么

epoll_wait() 可以高效等待大量 fd 的就绪状态，避免逐个 fd 轮询。它通常与非阻塞 socket 配合，构成 Reactor。

但 epoll 不替应用搬运数据：收到 EPOLLIN 后，代码仍要调用 recv()；收到 EPOLLOUT 后，仍要调用 send()。

2.4 io_uring 做到的是什么

应用把“请替我执行 accept/read/write……”描述成 SQE，提交给内核；操作完成后，内核写入 CQE。应用处理 CQE 时，看到的是操作结果，而不只是“可以开始操作”。

3. io_uring 的两个环

应用准备 SQE → SQ（Submission Queue）→ 内核执行 I/O
 ↓
应用处理结果 ← CQ（Completion Queue）← 内核生成 CQE

SQ / SQE

SQ：提交队列。
SQE：一次待执行 I/O 的描述，例如操作类型、fd、buffer、长度和用户数据。
io_uring_get_sqe()：取得一个可填写的 SQE。
io_uring_prep_accept/read/write(...)：只是在填写 SQE，不会立刻执行 I/O。
io_uring_submit()：把准备好的请求提交给内核。

CQ / CQE

CQ：完成队列。
CQE：一个已经完成的 I/O 结果。
cqe->res：操作结果。成功时通常是新 fd 或字节数；失败时是负的 errno 值。
cqe->user_data：应用提交时附带的标识，用来判断这是哪个连接、哪类操作。
io_uring_cq_advance()：告诉 ring，这批 CQE 已处理，可以回收。

为什么使用环形队列和 mmap

环形队列可以复用固定槽位，减少频繁分配；SQ/CQ 通过 mmap 在用户态和内核态之间共享队列元数据，减少提交、取结果时的额外系统调用和元数据复制。

但要注意：这不代表所有 I/O 数据都天然“零拷贝”。例如普通 socket 接收的数据通常仍需进入应用提供的 buffer。

4. io_uring 三个底层系统调用

io_uring_setup：创建并配置 ring，建立 SQ/CQ 所需资源。
io_uring_enter：提交请求和/或等待完成事件。
io_uring_register：预注册文件、buffer、事件等资源，减少热路径开销；它不是每个普通请求都必须调用。

课堂代码使用的是 liburing 封装：

io_uring_queue_init_params(ENTRIES_LENGTH, &ring, &params);
io_uring_get_sqe(&ring);
io_uring_prep_accept(...);
io_uring_submit(&ring);
io_uring_wait_cqe(&ring, &cqe);

可近似理解为：初始化 ring → 取得请求槽位 → 描述操作 → 提交 → 等结果。

5. 你的 io_uring Echo Server 怎么走

关键入口：

set_event_accept(&ring,sockfd,(struct sockaddr*)&clientaddr,&len,0);

set_event_accept() 做两件事：

用 io_uring_get_sqe() 取得 SQE。
用 io_uring_prep_accept() 填写 accept 请求，并在 user_data 中记录 fd + EVENT_ACCEPT。

此时只是准备请求，并没有等待客户端。

主循环：

io_uring_submit
 ↓ 提交当前准备好的 accept/recv/send 请求
io_uring_wait_cqe
 ↓ 没有完成结果时在这里等待
io_uring_peek_batch_cqe
 ↓ 批量取得已完成操作
根据 user_data 判断 EVENT_ACCEPT
 ↓
再次 set_event_accept，同时为新 clientfd 提交 recv
 ↓
io_uring_cq_advance

你测试时发现程序阻塞在 io_uring_wait_cqe()，这是合理的：

io_uring_prep_accept() 只准备请求，很快返回。
io_uring_submit() 提交请求。
在客户端真正连接前，accept 尚未完成，CQ 中没有结果，所以 wait_cqe() 等待。
客户端连接后，CQE 到达，cqe->res 应是新连接的 client fd（失败则为负数）。

5.1 三种事件不是“就绪事件”，而是操作身份

#define EVENT_ACCEPT 0
#define EVENT_READ 1
#define EVENT_WRITE 2

这里的 EVENT_* 是应用自己定义的标签。准备 SQE 时，代码把 fd + event 写入 sqe->user_data；操作完成后，再从 CQE 的 user_data 还原标签，据此判断完成的是 accept、recv 还是 send。

三种 SQE 的含义：

函数	提交给内核的操作	CQE 到达时 `entries->res` 的含义
`set_event_accept`	接收一个新连接	新连接 fd；负数表示失败
`set_event_recv`	把数据读进指定 buffer	实际读取字节数；0 表示对端关闭；负数表示失败
`set_event_send`	发送指定 buffer 中的数据	实际发送字节数；负数表示失败

5.2 完整状态循环

启动：准备 ACCEPT SQE
 ↓ submit
 ACCEPT 完成
 ├─ entries->res 得到 connfd
 ├─ 再准备一个 ACCEPT，继续接收其他客户端
 └─ 为 connfd 准备 RECV
 ↓ submit
 READ 完成
 ├─ res == 0：对端断开，close(fd)
 └─ res > 0：buffer 中已有数据，准备 SEND
 ↓ submit
 WRITE 完成
 ↓
 再为该 fd 准备 RECV

对单个连接而言，核心循环就是：

RECV 完成 → SEND 完成 → 再次 RECV

这份代码没有额外解析数据，而是把收到的 buffer 原样发送回去，因此它是一个 io_uring Echo Server。

5.3 为什么循环开头的 submit 能提交刚刚准备的操作

在处理 CQE 时调用的 set_event_accept/recv/send() 都只是取得并填写新的 SQE。它们不会立刻执行；本轮处理结束并 cq_advance 后，程序回到 while 开头，由下一次 io_uring_submit() 统一提交。

因此时间顺序是：

本轮处理 CQE → 准备下一批 SQE → advance → 下一轮 submit

这种批量准备、批量提交正是 io_uring 的重要思路。

为什么处理后要再次设置 accept

普通的 io_uring_prep_accept() 描述的是一次 accept 操作。完成一次就消费掉一次请求；若想继续接收连接，需要再准备并提交新的 accept。

这与 epoll 的常规 LT 模式不同：监听 fd 注册 EPOLLIN 后，只要仍处于可读状态，epoll 可以继续报告就绪，无需每完成一次 accept 就重新 EPOLL_CTL_ADD。

为什么必须 advance

CQE 被读取不等于被消费：

io_uring_cq_advance(&ring,nready);

这一步更新 CQ 的消费位置。漏掉它，旧 CQE 会一直被当成尚未处理，表现为循环反复看到同一结果。

6. 你的 Reactor 代码怎么走

6.1 初始化

epoll_create
 ↓
创建 20 个监听 socket（端口 2000～2019）
 ↓
把监听 fd 以 EPOLLIN 加入 epoll
 ↓
进入 epoll_wait 主循环

监听 fd 的回调被设置为 accept_cb：

conn_list[sockfd].r_action.recv_callback = accept_cb;

6.2 建立连接

监听 fd 出现 EPOLLIN
 ↓
主循环调用 accept_cb
 ↓
accept_cb 主动执行 accept()
 ↓
event_register(clientfd, EPOLLIN)

关键点：EPOLLIN 只表示监听 socket 可以执行 accept；真正建立并取出 client fd 的动作仍由 accept() 完成。

6.3 接收数据

clientfd 出现 EPOLLIN
 ↓
调用 recv_cb
 ↓
recv() 把数据读进 rbuffer
 ↓
ws_request() 处理请求
 ↓
把关注事件修改为 EPOLLOUT

如果 recv() 返回 0，说明对端正常断开；返回负数则表示错误。当前代码随后关闭 fd 并从 epoll 删除。

6.4 发送数据

clientfd 出现 EPOLLOUT
 ↓
调用 send_cb
 ↓
ws_response() 生成响应
 ↓
send() 主动发送 wbuffer
 ↓
把关注事件改回 EPOLLIN

整个连接状态近似为：

等待读 EPOLLIN → recv + 处理请求 → 等待写 EPOLLOUT
 ↑ ↓
 └──────── send + 改回读 ──────────┘

7. 逐段对照：Reactor 与 io_uring

阶段	epoll / Reactor	io_uring / Proactor 思路
接收连接	注册监听 fd 的 `EPOLLIN`	提交一个 accept SQE
通知到达	“监听 fd 可以 accept”	“accept 已完成”
新连接 fd	应用调用 `accept()` 得到	从 accept CQE 的 `res` 得到
接收数据	`EPOLLIN` 后应用调用 `recv()`	预先提交 recv/read SQE，完成后 buffer 已有数据
发送数据	`EPOLLOUT` 后应用调用 `send()`	预先提交 send/write SQE，完成后得到实际写入量
事件身份	`events[i].data.fd` + 回调表	`cqe->user_data` 标识 fd/事件/上下文
一次操作结束	修改下一次关注的就绪事件	消费 CQE，再准备下一次 I/O SQE
批量处理	`epoll_wait(..., events, 1024, ...)`	`io_uring_peek_batch_cqe(..., cqes, 128)`

代码上的一一对应：

epoll_ctl ADD/MOD ↔ io_uring_get_sqe + prep_xxx
epoll_wait ↔ io_uring_wait_cqe / peek_batch_cqe
events[i].data.fd ↔ cqe->user_data
EPOLLIN 后 recv ↔ READ CQE 到达时数据已读完
EPOLLOUT 后 send ↔ WRITE CQE 到达时写操作已完成
下一轮 set_event ↔ 下一轮重新准备 SQE
 ↔ io_uring_cq_advance 消费完成项

8. 对学习笔记中三个说法的校正

① “SQE 与 CQE 是同一个节点，共用一块内存”——不准确

SQE 和 CQE 是不同队列中的不同结构：SQE 描述请求，CQE 描述结果。它们通过 user_data 关联。共享内存指的是这些 ring 能被用户态与内核态共同访问，不是 SQE 原地变成 CQE。

② “io_uring_prep_accept 底层调用 register”——不准确

io_uring_prep_accept() 主要是填写 SQE。io_uring_register 是独立的资源注册系统调用，普通 accept 请求不要求每次 register。

③ “mmap 后就没有 copy”——范围过大

mmap 主要减少 SQ/CQ 控制信息在用户态和内核态之间的复制及系统调用开销；普通网络 I/O 的 payload 是否复制，是另一层问题。

9. 最小记忆框架

只背下面四句话：

epoll 给我的是就绪，我还要自己 accept/recv/send。
io_uring 给我的是完成，结果看 cqe->res，身份看 cqe->user_data。
io_uring 的路径是：取 SQE → prep → submit → 等 CQE → 处理 → advance。
普通 io_uring 请求通常是一次性的：完成一次，消费一次，再提交下一次。

DPDK 用户态 TCP 协议栈（四）：并发与自实现 epoll

Tue, 18 Aug 2026 00:00:00 +0800

本篇只围绕一个问题展开：用户态 TCP 协议栈怎样让一个应用线程并发管理多条 TCP 连接？

前三篇已经反复讲过 DPDK 收发、mbuf、Ethernet/IPv4/TCP 解析、三次握手、SEQ/ACK、TCP 状态机和 POSIX Socket。本篇只在它们影响 epoll 逻辑时简要回顾，不再重新逐层讲包头和握手细节。

一、先给出整篇的核心答案

TCP 并发 epoll 的实现可以浓缩成一个闭环：

1. 每条 TCP 连接拥有独立的 stream/TCB 和用户态 fd
2. 应用通过 epoll_ctl 注册“我关心哪些 fd 的哪些事件”
3. 协议栈处理报文时发现某个 fd 已经可读或可写
4. 协议栈调用 epoll 回调，把该 fd 放入就绪队列
5. 回调唤醒阻塞在 epoll_wait 的应用线程
6. epoll_wait 返回就绪 fd，应用执行 accept/recv/send/close
7. 应用重新进入 epoll_wait，继续管理所有连接

epoll 没有让 TCP 报文并行到达，也没有替协议栈处理握手。它解决的是：

当许多连接都可能产生数据时，应用怎样只处理当前已经就绪的连接，而不是为每条连接创建一个长期阻塞的线程。

理解本篇时始终抓住三种对象：

对象	解决的问题
`ng_tcp_stream`	这是谁的连接，当前 TCP 状态和数据是什么
`epitem`	应用是否关注这个 fd，它现在是否就绪
`eventpoll`	一个 epoll 实例管理的整集、就绪集和等待线程

二、只保留必要的旧知识：数据最终从哪里来到哪里去

完整程序有三个长期运行的执行流：

main/lcore：网卡 RX/TX
 ↕ 全局 in/out ring
pkt_process/lcore：Ethernet/IP/TCP 解析、TCP 输出封包
 ↕ 每连接 rcvbuf/sndbuf
tcp_server_entry/lcore：accept、recv、send、epoll_wait

两层 ring 不要混淆：

全局 ring->in/out 传递 rte_mbuf *，用于网卡线程与协议处理线程之间传包。
每个 ng_tcp_stream 的 rcvbuf/sndbuf 传递 TCP fragment，用于协议栈与应用之间传数据。

一段客户端数据的最短路径是：

网卡 RX
→ 全局 in ring
→ ng_tcp_process()
→ 按四元组找到 stream
→ payload 放入 stream->rcvbuf
→ 触发 EPOLLIN
→ nepoll_wait() 返回 connfd
→ 应用 nrecv(connfd)

应用响应的路径相反：

nsend(connfd)
→ fragment 放入 stream->sndbuf
→ ng_tcp_out() 取出并封装 TCP 报文
→ 全局 out ring
→ 网卡 TX

这些收发与报文构造细节在前几篇已有完整说明。本篇真正关心的是中间这一步：

stream 的状态发生变化
→ 怎样让正在等待的应用知道？

三、支持并发的第一前提：连接必须彼此独立

1. 一条连接对应一个 `ng_tcp_stream`

struct ng_tcp_stream {
 int fd;

 uint32_t sip, dip;
 uint16_t sport, dport;
 uint8_t protocol;

 uint32_t snd_nxt;
 uint32_t rcv_nxt;
 NG_TCP_STATUS status;

 struct rte_ring *sndbuf;
 struct rte_ring *rcvbuf;

 pthread_cond_t cond;
 pthread_mutex_t mutex;
};

它是本代码中的简化 TCB。每个客户端都必须拥有独立的：

地址与端口；
TCP 状态；
SEQ/ACK；
接收和发送缓冲区；
用户态 fd；
阻塞与唤醒状态。

因此，TCP 并发的根基不是 epoll，而是连接级状态隔离。如果两条连接共用序列号或接收缓冲区，换成 epoll 也不能让协议栈正确并发。

2. 报文怎样找到自己的 stream

if (iter->sip == sip && iter->dip == dip &&
 iter->sport == sport && iter->dport == dport) {
 return iter;
}

一般网络流用五元组标识；这里已经确定是 TCP，所以搜索时比较四元组。两个客户端连接同一个服务端地址和端口时，客户端 IP 或源端口不同，因此能找到不同的 stream。

3. 监听 stream 和连接 stream

服务端只有一个监听 stream，但可以有许多已连接 stream：

listenfd / LISTEN stream
 ├── connfd A / ESTABLISHED stream A
 ├── connfd B / ESTABLISHED stream B
 └── connfd C / ESTABLISHED stream C

收到 SYN 时，协议栈保留监听 stream，并创建一个新的连接 stream 处理该客户端：

struct ng_tcp_stream *syn = ng_tcp_stream_create(
 iphdr->src_addr, iphdr->dst_addr,
 tcphdr->src_port, tcphdr->dst_port);

LL_ADD(syn, table->tcb_set);
syn->status = NG_TCP_STATUS_SYN_RCVD;

监听对象负责“还能不能接新连接”，连接对象负责“这个客户端的数据和状态”。epoll 后面会分别监听这两类 fd。

四、一连接一线程为什么能工作，又为什么需要 epoll

1. 一连接一线程

最直观的并发方式是：

主线程：不断 naccept()
连接 A：线程 A 阻塞在 nrecv(A)
连接 B：线程 B 阻塞在 nrecv(B)
连接 C：线程 C 阻塞在 nrecv(C)

它适合验证连接表、stream 隔离和收发缓冲区是否支持多个客户端。问题是大部分连接经常没有数据，线程却仍占用栈空间和调度资源。连接数增长时，线程数也同步增长。

2. epoll 的改变

epoll 模型下，应用线程不阻塞在某一个 nrecv(connfd) 上，而是阻塞在“所有已注册 fd 的就绪集合”上：

应用线程：nepoll_wait(A, B, C, ...)

只有 B 有数据
→ nepoll_wait 只返回 B
→ 应用处理 B
→ 再次等待所有连接

所以两种模型的区别不是 TCP 连接数，而是等待位置：

一连接一线程：每个线程等待一个 fd
epoll：一个线程等待一组 fd

五、为什么不能直接调用 Linux 原生 epoll

代码中的 listenfd、connfd 和 epfd 由自己的位图分配：

static int get_fd_frombitmap(void) {
 for (int fd = DEFAULT_FD_NUM; fd < MAX_FD_COUNT; fd++) {
 if (fd_table 中该位空闲) {
 标记为已用;
 return fd;
 }
 }
 return -1;
}

这些整数只在用户态协议栈内部有意义：

用户态 fd
→ get_hostinfo_fromfd(fd)
→ ng_tcp_stream / localhost / eventpoll

Linux 内核没有创建对应的 socket 对象，也不知道 stream->rcvbuf 是否有数据。因此把这种 connfd 传给内核 epoll_ctl()，内核无法监听它。

既然 Socket API 是用户态自己实现的，事件机制也要自己补齐：

nsocket / nbind / nlisten / naccept / nrecv / nsend
 +
nepoll_create / nepoll_ctl / nepoll_wait

六、理解 epoll 的关键：就绪是一种状态

应用关注的不是“是否来过一个包”，而是“现在执行某个操作会不会阻塞”。

1. 监听 fd 可读

监听 fd 的 EPOLLIN 表示：

至少有一条已完成握手的连接可以被 naccept() 取出

它不是说监听 socket 收到了应用 payload，而是说 accept 现在不会阻塞。

2. 连接 fd 可读

连接 fd 的 EPOLLIN 表示：

nrecv() 现在可以取得 payload，或者取得 EOF/关闭信息

因此，收到 FIN 也可以触发 EPOLLIN。应用随后调用 nrecv() 得到 0，知道对端已关闭。

3. 连接 fd 可写

EPOLLOUT 的一般含义是：发送缓冲区有空间，send 不会因为缓冲区已满而阻塞。它不等于“一个数据包已经从网卡发完”。

本节代码重点实现的是 EPOLLIN 链路；要完整支持 EPOLLOUT，还需要定义 sndbuf 从满变为可用时怎样产生通知。

这一点非常重要：

epoll 事件是 Socket 操作条件的变化，不是对每个网络包做一次简单转发。

七、epoll 的两个集合

一个 epoll 实例内部有两份不同用途的集合。

1. 整集：我关注谁

整集保存所有通过 EPOLL_CTL_ADD 注册的 fd。代码用红黑树组织，以 sockfd 为 key：

整集 = {listenfd, connfd_A, connfd_B, connfd_C, ...}

它回答：

这个 fd 是否被注册？
应用对它关心 EPOLLIN 还是 EPOLLOUT？
ADD/DEL/MOD 应该操作哪个节点？

红黑树提供稳定的 O(log n) 查找、插入和删除，并能随注册数量按节点增长。哈希的平均查找更快，但要额外处理桶容量、冲突和扩容。这里选择红黑树的重点是动态集合与稳定性能，并不是红黑树在所有场景都绝对更快。

2. 就绪集：现在谁能处理

就绪集是链表，只保存当前已经产生事件的节点：

整集：{listenfd, A, B, C, D}
就绪集：{B, D}

nepoll_wait() 无须扫描整棵红黑树，只需从就绪链表取出 B、D。

3. 同一个节点同时属于两份集合

struct epitem {
 RB_ENTRY(epitem) rbn;
 LIST_ENTRY(epitem) rdlink;

 int rdy;
 int sockfd;
 struct epoll_event event;
};

一个 epitem 中同时有红黑树节点和链表节点：

rbn：长期挂在整集，表示注册关系
rdlink：就绪时临时挂在就绪链表
rdy：防止同一节点被重复插入就绪链表

节点进入就绪链表后仍保留在红黑树里。应用消费一次就绪事件，不等于取消对这个 fd 的关注；只有 EPOLL_CTL_DEL 才删除注册关系。

4. `eventpoll` 管理整个 epoll 实例

struct eventpoll {
 int fd;

 ep_rb_tree rbr;
 int rbcnt;

 LIST_HEAD(, epitem) rdlist;
 int rdnum;

 pthread_mutex_t mtx;
 pthread_spinlock_t lock;
 pthread_cond_t cond;
 pthread_mutex_t cdmtx;
};

关系可以画成：

epfd
└── eventpoll
 ├── rbr：全部已注册 epitem
 ├── rdlist：当前就绪 epitem
 └── cond：没有就绪事件时，让 nepoll_wait 睡眠

八、三个外部接口怎样组成应用侧逻辑

1. `nepoll_create()`：创建事件管理器

它做的事情不是创建 TCP 连接，而是创建一个 eventpoll：

分配 epfd
→ 分配 eventpoll
→ 初始化红黑树
→ 初始化就绪链表
→ 初始化锁与条件变量
→ 建立 epfd 到 eventpoll 的映射

应用以后通过 epfd 找到这一整套事件管理状态。

2. `nepoll_ctl()`：维护整集

ADD：树中不存在 → 分配 epitem → 插入红黑树
DEL：树中存在 → 从红黑树移除 → 释放 epitem
MOD：树中存在 → 修改关注的事件

因此，nepoll_ctl() 只是在表达应用的兴趣：

“如果这个 fd 以后出现我关心的状态，请通知我。”

注册本身不会凭空制造事件。

3. `nepoll_wait()`：没有事件就睡，有事件就返回

while (ep->rdnum == 0 && timeout != 0) {
 if (timeout > 0)
 pthread_cond_timedwait(&ep->cond, &ep->cdmtx, ...);
 else if (timeout < 0)
 pthread_cond_wait(&ep->cond, &ep->cdmtx);
}

超时语义：

timeout < 0：一直等待；
timeout == 0：立即检查并返回；
timeout > 0：最多等待指定时长。

醒来后，它从就绪链表取出最多 maxevents 个节点，把其中的 epoll_event 复制给应用：

rdlist 中的 epitem
→ events[0...n-1]
→ 返回 nready

至此，epoll 只告诉应用“哪些 fd 可以处理”。真正的 accept/recv/send 仍由应用自己调用。

九、最关键的内部接口：协议栈怎样触发事件

三个 nepoll_* 接口面向应用；epoll_event_callback() 面向协议栈：

int epoll_event_callback(struct eventpoll *ep,
 int sockid, uint32_t event) {
 struct epitem *epi = RB_FIND(..., sockid);
 if (!epi)
 return -1;

 if (epi->rdy) {
 epi->event.events |= event;
 return 1;
 }

 pthread_spin_lock(&ep->lock);
 epi->rdy = 1;
 LIST_INSERT_HEAD(&ep->rdlist, epi, rdlink);
 ep->rdnum++;
 pthread_spin_unlock(&ep->lock);

 pthread_mutex_lock(&ep->cdmtx);
 pthread_cond_signal(&ep->cond);
 pthread_mutex_unlock(&ep->cdmtx);
}

它完成四步：

按 sockid 查整集
→ 把事件记录到对应 epitem
→ 把 epitem 加入就绪链表
→ signal 唤醒 nepoll_wait

如果节点已经在就绪链表中，就不重复插入，只合并事件位：

epi->event.events |= event;

这避免同一个 fd 连续收到多个通知时，在 rdlist 中出现多个相同节点。

epoll 模块在整体架构中的位置

协议栈 epoll 应用

握手完成 ─┐
收到数据 ─┼→ event_callback → rdlist → cond_signal → nepoll_wait
收到 FIN ─┘ ↓
 accept/recv/close

所以 epoll 不是协议栈之外的独立轮询器。它必须由协议栈在状态真正改变的地方主动通知。

十、用三条时间线彻底串起实现

时间线一：新客户端完成连接

① 客户端发送 SYN
② ng_tcp_process 找到 LISTEN stream
③ 为客户端创建新的 stream，进入 SYN_RCVD
④ 协议栈发送 SYN+ACK
⑤ 收到客户端 ACK，新 stream 进入 ESTABLISHED
⑥ 协议栈触发 listenfd 的 EPOLLIN
⑦ nepoll_wait 返回 listenfd
⑧ 应用调用 naccept(listenfd)
⑨ naccept 取出已建立 stream，为它分配 connfd
⑩ 应用用 EPOLL_CTL_ADD 把 connfd 加入 epoll

对应代码的关键通知：

stream->status = NG_TCP_STATUS_ESTABLISHED;

struct ng_tcp_stream *listener =
 ng_tcp_stream_search(0, 0, 0, stream->dport);

epoll_event_callback(table->ep, listener->fd, EPOLLIN);

为什么通知 listener->fd，而不是新连接的 fd？

因为此时应用还没有执行 naccept()，新 stream 还没有分配给应用使用的 connfd。对应用来说，当前可执行的动作是 accept(listenfd)，所以就绪的是监听 fd。

时间线二：已连接客户端发送 payload

① 报文按四元组找到 established stream
② 协议栈复制 payload，构造 fragment
③ fragment 进入 stream->rcvbuf
④ 协议栈触发 stream->fd 的 EPOLLIN
⑤ callback 找到 connfd 对应的 epitem
⑥ epitem 进入 rdlist，唤醒 nepoll_wait
⑦ 应用得到 connfd
⑧ 应用调用 nrecv(connfd)，从该 stream 的 rcvbuf 取数据

关键顺序必须是：

先让数据真正可读
→ 再发布 EPOLLIN

否则应用被唤醒后可能发现 rcvbuf 仍为空。

时间线三：客户端发送 FIN

① 协议栈收到 FIN
② stream 进入 CLOSE_WAIT
③ rcvbuf 中放入长度为 0 的 fragment，表示 EOF
④ 触发 connfd 的 EPOLLIN
⑤ nepoll_wait 返回 connfd
⑥ nrecv(connfd) 返回 0
⑦ 应用 EPOLL_CTL_DEL，然后 nclose(connfd)

这条时间线解释了为什么“关闭”也能通过可读事件交给应用：读取操作已经不会阻塞，只是结果为 EOF。

十一、epoll 服务器循环现在应该怎样读

int epfd = nepoll_create(1);

ev.events = EPOLLIN;
ev.data.fd = listenfd;
nepoll_ctl(epfd, EPOLL_CTL_ADD, listenfd, &ev);

while (1) {
 int nready = nepoll_wait(epfd, events, 128, 5);

 for (int i = 0; i < nready; i++) {
 if (events[i].data.fd == listenfd) {
 int connfd = naccept(listenfd, ...);

 ev.events = EPOLLIN;
 ev.data.fd = connfd;
 nepoll_ctl(epfd, EPOLL_CTL_ADD, connfd, &ev);
 } else {
 int connfd = events[i].data.fd;
 int n = nrecv(connfd, buff, BUFFER_SIZE, 0);

 if (n > 0) {
 nsend(connfd, buff, n, 0);
 } else {
 nepoll_ctl(epfd, EPOLL_CTL_DEL, connfd, NULL);
 nclose(connfd);
 }
 }
 }
}

不要只把它看成一个 API 调用顺序。这个循环其实在处理两类状态机入口：

listenfd 就绪
→ 连接管理路径
→ accept 新连接并将 connfd 注册进 epoll

connfd 就绪
→ 数据路径或关闭路径
→ recv 数据，或者识别 EOF 后移除连接

多个客户端的并发体现在：所有 connfd 都在同一棵红黑树中，但某一时刻只有真正就绪的连接进入 rdlist。

十二、薄弱但非常重要：LT、ET 与“消费事件”

理解整集和就绪集后，还必须区分两种事件语义。

1. LT：Level Triggered，水平触发

只要可读条件仍然成立，就应该继续报告：

rcvbuf 里还有数据
→ fd 仍然可读
→ 下一次 epoll_wait 仍应返回它

应用可以一次只读一部分，剩余数据会让 fd 继续保持就绪。

2. ET：Edge Triggered，边沿触发

只在状态从“不可读”变为“可读”的边沿通知一次：

rcvbuf：空 → 非空
→ 触发一次 EPOLLIN

如果应用没有把数据一直读到 EAGAIN，而 rcvbuf 始终保持非空，就可能没有新的空→非空边沿，因此也不会再次收到通知。

3. 当前学习代码的核心行为

epoll_event_callback() 把节点加入 rdlist；nepoll_wait() 返回后将其移出并清除 rdy。以后再次发生协议栈回调时，节点才能重新加入。

这更接近“协议栈事件通知队列”的实现骨架。要形成严格的 LT 或 ET，还需要把就绪谓词定义清楚：

监听 fd 可读：accept 队列非空
连接 fd 可读：rcvbuf 非空，或存在 EOF/错误
连接 fd 可写：sndbuf 有可用空间

然后选择策略：

LT：epoll_wait 返回事件后，如果谓词仍为真，应保留或重新加入就绪集。
ET：只有谓词从假变真时才入就绪集，应用必须把资源处理到再次变为假。

这部分是自实现 epoll 最容易遗漏的核心：就绪链表只是结果，真正决定事件语义的是状态谓词和重新入队规则。

十三、线程同步：为什么需要三种同步手段

代码中不同锁保护不同对象：

同步对象	主要保护内容
`ep->mtx`	红黑树的 ADD/DEL/MOD
`ep->lock` 自旋锁	短时间修改 `rdlist`、`rdnum`、`rdy`
`ep->cdmtx + cond`	`nepoll_wait` 睡眠与协议栈唤醒

1. 为什么等待必须检查条件

正确思路不是“收到 signal 就相信一定有事件”，而是：

while (ep->rdnum == 0)
 pthread_cond_wait(...);

条件变量可能虚假唤醒，也可能多个等待者竞争同一批事件。醒来后必须重新检查 rdnum。

同理，nrecv() 等待数据时也使用循环检查 rcvbuf，而不是单次 if。

2. 为什么先入就绪集，再 signal

发布顺序是：

修改受保护状态：epitem 进入 rdlist，rdnum++
→ 再 signal

signal 的作用只是提醒等待线程重新检查条件；真正可信的是受锁保护的 rdlist/rdnum。

3. `DEL` 与回调之间的关系

应用关闭连接时会删除 epitem，协议栈线程则可能正在为同一 fd 触发回调。完整实现必须让红黑树查找、节点删除和就绪链表访问遵守一致的生命周期规则，避免回调继续访问已经释放的节点。

这里不展开代码审查，只需记住：并发数据结构除了“查得快”，还要保证节点从注册、就绪到删除期间始终有效。

十四、单 epoll 与多个 epoll

当前代码在创建时执行：

struct ng_tcp_table *table = tcpInstance();
table->ep = ep;

协议栈触发事件时也直接使用：

epoll_event_callback(table->ep, stream->fd, EPOLLIN);

这意味着当前教学实现默认整个 TCP table 只有一个 epoll。它足以展示完整通知链路，但还不能表达：

同一进程创建多个 epoll 实例；
不同 epoll 注册不同连接；
同一个 fd 同时被多个 epoll 关注。

扩展为多个 epoll 时，不能只保留一个 table->ep。需要建立：

epfd → eventpoll

以及

sockfd → 所有注册了该 sockfd 的 epitem/eventpoll

协议栈产生事件后，要找到所有相关订阅者并分别更新它们的就绪集。这实际上把单指针通知扩展成一对多的观察者关系。

十五、多连接 core dump 在本篇中的位置

多连接时暴露 core dump，说明“单连接路径成立”并不等于“所有连接级资源都已正确隔离”。本节笔记直接涉及的一点是：每条 stream 都会创建自己的 DPDK ring，而 DPDK 命名对象需要可区分的名称。

sprintf(sbufname, "sndbuf%x%d", sip, sport);
stream->sndbuf = rte_ring_create(sbufname, ...);

sprintf(rbufname, "bufname%x%d", sip, sport);
stream->rcvbuf = rte_ring_create(rbufname, ...);

这里用客户端 IP 和源端口区分连接 ring。要记住三层不同的身份：

四/五元组：让协议栈把报文分给正确 stream
DPDK ring 名称：让每条 stream 获得独立缓冲对象
用户态 fd：让应用和 epoll 找到正确 stream

本篇不继续展开具体崩溃排查，因为重点是 epoll 的事件闭环。

十六、把全部实现压缩成一张图

 应用线程
 │
 nepoll_ctl ADD │ 注册兴趣
 ▼
 ┌───────────────┐
 │ eventpoll │
 │ │
 │ 红黑树 rbr │ ← 全部注册 fd
 │ 就绪表 rdlist │ ← 当前就绪 fd
 │ cond │ ← 没事件时睡眠
 └───────┬───────┘
 │ nepoll_wait 返回
 ▼
 accept / recv / send / close
 ▲
 │ 用户态 fd → stream
 ┌───────┴────────┐
 │ ng_tcp_stream │
 │ 状态/SEQ/ACK │
 │ rcvbuf/sndbuf │
 └───────▲────────┘
 │
 ng_tcp_process 按四元组定位
 │
 握手完成 / payload 到达 / FIN 到达
 │
 epoll_event_callback
 │
 加入 rdlist + signal

从这张图可以看到，TCP 并发 epoll 不是单独一个数据结构，而是四套映射协作：

报文四元组 → stream
用户态 fd → stream
epfd → eventpoll
eventpoll 中 sockfd → epitem

缺少任何一层，事件都无法从报文准确传递到应用。

十七、最终应掌握的实现逻辑

多连接首先要求每条连接拥有独立 TCB、状态、序列号和收发缓冲区。
报文通过四元组找到 stream，应用通过用户态 fd 找到同一个 stream。
一连接一线程让每个线程阻塞等一个 fd；epoll 让一个线程等待一组 fd。
用户态 fd 不属于内核，因此必须自实现 epoll，不能直接交给 Linux epoll。
红黑树保存“关注谁”，就绪链表保存“现在谁能处理”。
nepoll_ctl() 建立兴趣关系，epoll_event_callback() 发布事件，nepoll_wait() 消费事件。
握手完成触发监听 fd 的 EPOLLIN，因为此时 accept 不再阻塞。
payload 或 FIN 到达触发连接 fd 的 EPOLLIN，因为此时 recv 能返回数据或 EOF。
必须先改变真实就绪状态，再把事件加入就绪集并唤醒等待线程。
LT/ET 的本质不在链表名字，而在就绪谓词以及事件消费后的重新入队规则。
单 epoll 可以用 tcp_table->ep；多个 epoll 需要 fd 到多个订阅者的映射。
epoll 解决应用调度问题，不替代 TCP 状态机，也不能弥补连接状态未隔离的问题。

十八、反刍题

为什么三次握手完成时触发 listenfd，而不是新连接 fd？
为什么 FIN 可以通过 EPOLLIN 通知？
红黑树和就绪链表各自回答什么问题？
为什么一个 epitem 要同时包含 RB_ENTRY 和 LIST_ENTRY？
nepoll_ctl() 注册了一个 fd 后，为什么它不一定立刻出现在就绪链表？
从 payload 到达到 nepoll_wait() 返回，中间依次发生了什么？
如果 rcvbuf 仍有未读数据，LT 和 ET 下一步分别应该怎样表现？
为什么条件变量的等待必须放在 while 中？
为什么发布事件时要先更新 rdlist/rdnum，再调用 signal？
当前的 tcp_table->ep 为什么只能自然表达单 epoll？
如果一个 connfd 被两个 epoll 实例注册，协议栈该怎样分发一次 EPOLLIN？
epoll 已经实现正确，但不同连接仍共用 rcvbuf，并发为什么仍然会失败？

DPDK 用户态协议栈（三）：从 TCP 握手到可靠传输

Mon, 17 Aug 2026 17:35:00 +0800

系列前文：

DPDK 用户态协议栈设计与实现

DPDK 用户态协议栈（二）：从收包到 UDP Echo 与 TCP 握手

前两篇已经讲过 DPDK 的收发路径、mbuf、Ethernet/IPv4/UDP/TCP Header、UDP Echo 和基础 TCP 握手。本篇直接沿着当前代码的执行顺序复习 TCP，并从代码中的 flags、seq、ack、rx_win、tcp_status 延伸到滑动窗口、延迟确认、重传、慢启动和拥塞控制。

一、先看当前代码的 TCP 主线

当前程序的 TCP 数据路径可以概括为：

rte_eth_rx_burst() 从 RX Queue 取包
 ↓
解析 Ethernet Header
 ↓
解析 IPv4 Header
 ↓
next_proto_id == IPPROTO_TCP
 ↓
解析 TCP Header
 ↓
保存源/目的 MAC、IP、端口
 ↓
读取 flags、seq、ack
 ↓
根据 tcp_status 处理 SYN、ACK、PSH
 ↓
必要时构造 TCP 响应并通过 TX Queue 发出

代码中与 TCP 直接相关的全局信息是：

uint8_t global_flags;
uint32_t global_seqnum;
uint32_t global_acknum;

它们分别保存当前收到的 TCP 报文中的：

global_flags ← TCP 控制位
global_seqnum ← 对方本次发送的 SEQ
global_acknum ← 对方本次携带的 ACK

状态机由下面的枚举描述：

typedef enum __USTACK_TCP_STATUS {
 USTACK_TCP_STATUS_CLOSED = 0,
 USTACK_TCP_STATUS_LISTEN,
 USTACK_TCP_STATUS_SYN_RCVD,
 USTACK_TCP_STATUS_SYN_SENT,
 USTACK_TCP_STATUS_ESTABLISHED,
 USTACK_TCP_STATUS_FIN_WAIT_1,
 USTACK_TCP_STATUS_FIN_WAIT_2,
 USTACK_TCP_STATUS_CLOSING,
 USTACK_TCP_STATUS_TIMEWAIT,
 USTACK_TCP_STATUS_CLOSE_WAIT,
 USTACK_TCP_STATUS_LAST_ACK
} USTACK_TCP_STATUS;

uint8_t tcp_status = USTACK_TCP_STATUS_LISTEN;

当前代码主要走的是服务端路径：

LISTEN
 ↓ 收到 SYN
SYN_RCVD
 ↓ 收到第三次握手 ACK
ESTABLISHED
 ↓
接收 TCP 数据

二、代码怎样识别并取得 TCP 报文

主循环先通过 DPDK 批量收包：

struct rte_mbuf *mbufs[BURST_SIZE] = {0};

uint16_t num_recvd = rte_eth_rx_burst(
 global_portid,
 0,
 mbufs,
 BURST_SIZE
);

num_recvd 表示本次从 RX Queue 中取出的报文数量。程序随后遍历每一个 mbuf：

for (i = 0; i < num_recvd; i++) {
 struct rte_ether_hdr *ethhdr =
 rte_pktmbuf_mtod(
 mbufs[i],
 struct rte_ether_hdr *
 );

先判断它是不是 IPv4：

if (ethhdr->ether_type !=
 rte_cpu_to_be_16(RTE_ETHER_TYPE_IPV4)) {
 continue;
}

再取得 IPv4 Header：

struct rte_ipv4_hdr *iphdr =
 rte_pktmbuf_mtod_offset(
 mbufs[i],
 struct rte_ipv4_hdr *,
 sizeof(struct rte_ether_hdr)
 );

最后根据 IPv4 Header 中的协议号进入 TCP 分支：

if (iphdr->next_proto_id == IPPROTO_TCP) {
 struct rte_tcp_hdr *tcphdr =
 (struct rte_tcp_hdr *)(iphdr + 1);
}

在当前实验中，IPv4 Header 按基础 20 字节处理，所以使用 (iphdr + 1) 到达 TCP Header。进一步扩展时，可以根据 IHL 取得真实的 IPv4 Header 长度：

uint16_t ip_hdr_len =
 (iphdr->version_ihl & 0x0f) * 4;

struct rte_tcp_hdr *tcphdr =
 (struct rte_tcp_hdr *)
 ((uint8_t *)iphdr + ip_hdr_len);

这里的层次关系是：

Ethernet Header
IPv4 Header
TCP Header
TCP Payload

三、为什么代码要把地址和端口反过来保存

收到客户端发来的 TCP 包后，服务端回包的方向与收包方向正好相反。

1. MAC 地址交换

rte_memcpy(
 global_smac,
 ethhdr->d_addr.addr_bytes,
 RTE_ETHER_ADDR_LEN
);

rte_memcpy(
 global_dmac,
 ethhdr->s_addr.addr_bytes,
 RTE_ETHER_ADDR_LEN
);

收到包时：

源 MAC = 客户端 MAC
目的 MAC = 服务端 MAC

回包时：

源 MAC = 服务端 MAC
目的 MAC = 客户端 MAC

所以把收到包的目的 MAC 保存为回包源 MAC，把收到包的源 MAC 保存为回包目的 MAC。

2. IP 地址交换

rte_memcpy(&global_sip, &iphdr->dst_addr, sizeof(uint32_t));
rte_memcpy(&global_dip, &iphdr->src_addr, sizeof(uint32_t));

3. TCP 端口交换

rte_memcpy(&global_sport, &tcphdr->dst_port, sizeof(uint16_t));
rte_memcpy(&global_dport, &tcphdr->src_port, sizeof(uint16_t));

最终得到一组回包方向的数据：

global_smac 服务端 MAC
global_dmac 客户端 MAC
global_sip 服务端 IP
global_dip 客户端 IP
global_sport 服务端端口
global_dport 客户端端口

TCP 用下面的四元组区分连接：

源 IP、源端口、目的 IP、目的端口

对于服务端而言，一般写成：

local_ip、local_port、remote_ip、remote_port

四、代码怎样读取 Flags、SEQ 和 ACK

global_flags = tcphdr->tcp_flags;
global_seqnum = ntohl(tcphdr->sent_seq);
global_acknum = ntohl(tcphdr->recv_ack);

1. Flags

tcp_flags 是一个字节，其中每一位代表一个控制标志：

SYN 建立连接并同步初始序列号
ACK ACK 字段有效
PSH 希望接收端尽快把数据交给应用
FIN 本方向没有更多数据需要发送
RST 复位连接
URG Urgent Pointer 有效

一个报文可以同时带多个标志，例如：

SYN | ACK
PSH | ACK
FIN | ACK

所以代码使用按位与判断某一位是否存在：

if (global_flags & RTE_TCP_SYN_FLAG) {
 /* 包含 SYN */
}

2. SEQ 与 ACK 是 32 位字段

global_seqnum = ntohl(tcphdr->sent_seq);
global_acknum = ntohl(tcphdr->recv_ack);

报文使用网络字节序，程序进行加减和比较时使用主机字节序，因此读取时调用 ntohl()。

回包时方向相反：

tcp->sent_seq = htonl(seq);
tcp->recv_ack = htonl(ack);

可以记成：

网络报文 → 主机整数：ntohs / ntohl
主机整数 → 网络报文：htons / htonl

其中：

16 位：端口、Window、部分长度字段
32 位：IPv4 地址、SEQ、ACK

五、结合 `ustack_encode_tcp_pkt()` 看 SYN+ACK 的构造

当前编码函数依次组织 Ethernet、IPv4 和 TCP Header。

1. Ethernet Header

struct rte_ether_hdr *eth =
 (struct rte_ether_hdr *)msg;

rte_memcpy(
 eth->d_addr.addr_bytes,
 global_dmac,
 RTE_ETHER_ADDR_LEN
);

rte_memcpy(
 eth->s_addr.addr_bytes,
 global_smac,
 RTE_ETHER_ADDR_LEN
);

eth->ether_type = htons(RTE_ETHER_TYPE_IPV4);

这一层说明后面的载荷是 IPv4。

2. IPv4 Header

struct rte_ipv4_hdr *ip =
 (struct rte_ipv4_hdr *)(eth + 1);

ip->version_ihl = 0x45;
ip->type_of_service = 0;
ip->total_length = htons(
 total_len - sizeof(struct rte_ether_hdr)
);
ip->packet_id = 0;
ip->fragment_offset = 0;
ip->time_to_live = 64;
ip->next_proto_id = IPPROTO_TCP;
ip->src_addr = global_sip;
ip->dst_addr = global_dip;
ip->hdr_checksum = 0;
ip->hdr_checksum = rte_ipv4_cksum(ip);

total_len 是整个 Ethernet Frame 中由程序填写的长度。IPv4 的 total_length 不包括 Ethernet Header，所以要减去：

sizeof(struct rte_ether_hdr)

3. TCP Header

struct rte_tcp_hdr *tcp =
 (struct rte_tcp_hdr *)(ip + 1);

tcp->src_port = global_sport;
tcp->dst_port = global_dport;

tcp->sent_seq = htonl(12345);
tcp->recv_ack = htonl(global_seqnum + 1);

tcp->data_off = 0x50;

tcp->tcp_flags =
 RTE_TCP_SYN_FLAG |
 RTE_TCP_ACK_FLAG;

tcp->rx_win = htons(TCP_INIT_WINDOWS);

tcp->cksum = 0;
tcp->cksum = rte_ipv4_udptcp_cksum(ip, tcp);

这几行正好对应三次握手第二步：

服务端自己的 SEQ = 12345
确认客户端 SYN 的 ACK = 客户端 SEQ + 1
Flags = SYN | ACK

data_off = 0x50 的高 4 位是 5，表示 TCP Header 长度为：

5 × 4 字节 = 20 字节

本例没有 TCP Options，所以是最基础的 20 字节 TCP Header。

rx_win 是服务端通告给客户端的接收窗口。它是 16 位字段，写入报文时使用 htons()。

六、结合状态机完整理解三次握手

假设：

客户端初始序列号 client_isn = 1234
服务端初始序列号 server_isn = 12345

第一次握手：客户端发送 SYN

客户端 → 服务端

SYN=1
SEQ=1234

代码在 TCP 分支中读取到：

global_flags = RTE_TCP_SYN_FLAG;
global_seqnum = 1234;

随后进入：

if (global_flags & RTE_TCP_SYN_FLAG) {
 if (tcp_status == USTACK_TCP_STATUS_LISTEN) {
 /* 构造 SYN+ACK */
 }
}

第二次握手：服务端回复 SYN+ACK

服务端 → 客户端

SYN=1
ACK=1
SEQ=12345
ACK number=1235

代码中的对应关系：

tcp->sent_seq = htonl(12345);
tcp->recv_ack = htonl(global_seqnum + 1);
tcp->tcp_flags = RTE_TCP_SYN_FLAG | RTE_TCP_ACK_FLAG;

发送后进入：

tcp_status = USTACK_TCP_STATUS_SYN_RCVD;

表示服务端已经发送 SYN+ACK，正在等待客户端确认自己的 SYN。

第三次握手：客户端回复 ACK

客户端 → 服务端

ACK=1
SEQ=1235
ACK number=12346

客户端的 SEQ 变成 1235，是因为它的 SYN 占用了一个序列号。

客户端的 ACK 是 12346，是因为服务端的 SYN 也占用了一个序列号。

代码收到 ACK 后：

if (global_flags & RTE_TCP_ACK_FLAG) {
 if (tcp_status == USTACK_TCP_STATUS_SYN_RCVD) {
 printf("enter established\n");
 tcp_status = USTACK_TCP_STATUS_ESTABLISHED;
 }
}

于是状态变化为：

LISTEN
 ↓ 收到 SYN
SYN_RCVD
 ↓ 收到确认服务端 SYN 的 ACK
ESTABLISHED

在连接数据结构中，可以保存：

iss = 12345 服务端初始发送序列号
irs = 1234 客户端初始发送序列号
snd_una = 12346 服务端最早未确认序号
snd_nxt = 12346 服务端下一个发送序号
rcv_nxt = 1235 服务端下一步期望收到的客户端序号

七、SEQ 的精髓：它是字节序号

TCP 提供的是字节流。SEQ 不是“第几个包”，而是当前 TCP 段中第一个数据字节的编号。

假设服务端当前发送：

SEQ=12345
payload_len=100

那么该段中的 100 个数据字节对应：

12345～12444

下一段新数据从：

SEQ=12445

开始。

如果第二段有 500 字节：

第二段：SEQ=12445，覆盖 12445～12944
第三段：SEQ=12945

所以发送新数据后：

SND.NXT = SND.NXT + payload_len

如果报文还包含 SYN 或 FIN，则它们各自还要消耗一个序列号：

sequence_space_len
 = payload_len
 + (SYN ? 1 : 0)
 + (FIN ? 1 : 0)

ACK 和 PSH 本身不占序列空间。

八、ACK 的精髓：确认连续收到的字节

假设服务端收到客户端的数据：

SEQ=5000
payload_len=1000

数据覆盖：

5000～5999

如果这些字节都按序收到，服务端返回：

ACK=6000

ACK=6000 表示：

6000 以前的连续序列字节已经收到，下一步期望 6000。

因此 ACK 是累计确认。假设发送方连续发送：

[5000, 6000)
[6000, 7000)
[7000, 8000)

接收方可以直接回复：

ACK=8000

一次确认前面三个连续区间。

在代码中，接收端用于生成 ACK 的核心状态可以写成：

conn->rcv_nxt += payload_len;
tcp->recv_ack = htonl(conn->rcv_nxt);

九、一条 TCP 连接为什么有两套 SEQ/ACK

TCP 是全双工协议，两个方向可以同时传输数据：

客户端 ─────客户端数据────→ 服务端
客户端 ←────服务端数据───── 服务端

两个方向分别有自己的序列空间：

客户端发送方向：从 client_isn 开始编号
服务端发送方向：从 server_isn 开始编号

一个 TCP 报文中的两个字段分别表达：

SEQ：我这次发送的数据从哪里开始
ACK：你发送的数据，我连续收到了哪里

使用“北京与广州互相运货”的类比：

北京 → 广州：烤鸭编号是一套序列空间
广州 → 北京：白切鸡编号是另一套序列空间

每辆车都可以同时携带：

SEQ：本车货物的起始编号
ACK：反方向货物已经连续收到的编号
Window：本地仓库还允许对方运来多少货物

所以双方都同时具有发送状态和接收状态。

十、代码怎样定位 TCP Payload

原代码在收到 PSH 后，通过 TCP Header 长度定位数据：

uint8_t hdrlen =
 (tcphdr->data_off >> 4)
 * sizeof(uint32_t);

uint8_t *data =
 (uint8_t *)tcphdr + hdrlen;

data_off 的高 4 位以 4 字节为单位表示 TCP Header 长度：

tcp_hdr_len = (data_off >> 4) × 4

若没有 TCP Options：

data_off 高四位 = 5
TCP Header 长度 = 5 × 4 = 20 字节

TCP payload 长度可以通过 IPv4 总长度计算：

uint16_t ip_total_len = ntohs(iphdr->total_length);
uint16_t ip_hdr_len = (iphdr->version_ihl & 0x0f) * 4;
uint16_t tcp_hdr_len = (tcphdr->data_off >> 4) * 4;

uint16_t payload_len =
 ip_total_len - ip_hdr_len - tcp_hdr_len;

uint8_t *payload =
 (uint8_t *)tcphdr + tcp_hdr_len;

这也解释了 TCP Header 为什么不需要像 UDP Header 那样再放一个长度字段：IPv4 总长度、IPv4 Header 长度和 TCP Header 长度已经能够计算出当前 TCP payload 长度。

PSH 可以理解为“希望接收端尽快把这部分数据交给应用”。处理代码时，是否存在 payload 仍以 payload_len > 0 为准。

十一、从 `rx_win` 理解 TCP 接收窗口

当前构造 TCP Header 时写入：

#define TCP_INIT_WINDOWS 14600

tcp->rx_win = htons(TCP_INIT_WINDOWS);

这个字段是本端向对端通告：

从 ACK 所表示的下一个期望字节开始，
我目前还愿意接收多少字节。

例如服务端回复：

ACK=6000
Window=14600

可以理解为：

6000 以前已经连续收到；
从 6000 开始，当前还能接收 14600 字节。

接收窗口通常与接收缓存关联：

RCV.WND
 = 接收缓存总容量
 - 已收到但应用还没有读取的数据量

如果应用读取很慢，缓存逐渐占满：

RCV.WND 逐渐减小

如果缓存完全占满：

RCV.WND = 0

发送方看到零窗口后，暂停发送新的数据。接收端应用继续读取数据、释放缓存后，再通过 ACK 中的 Window 字段通告新的可用空间。

十二、发送窗口：`SND.UNA` 与 `SND.NXT`

发送端可以把序列空间分成四部分：

已发送已确认 已发送未确认 窗口内尚未发送 当前不能发送
────────────┬────────────────┬──────────────────┬──────────→
 SND.UNA SND.NXT SND.UNA+SND.WND

1. `SND.UNA`

Send Unacknowledged，最早一个尚未被确认的序号。

2. `SND.NXT`

Send Next，下一个新数据应该使用的序号。

3. 在途数据量

flight_size = SND.NXT - SND.UNA

表示已经发送、还没有累计确认的数据量。

4. 收到新 ACK 时窗口滑动

发送端原来是：

SND.UNA=1000
SND.NXT=4000

说明 [1000, 4000) 已发送未确认。

收到：

ACK=3000

之后：

SND.UNA=3000
SND.NXT=4000

[1000, 3000) 已被确认，可以从重传队列和发送缓存中释放；窗口左边界向右移动，这就是“滑动窗口”。

十三、接收窗口与有序交付

接收端维护：

RCV.NXT：下一步期望收到的序号
RCV.WND：从 RCV.NXT 开始还允许接收多少字节

序列空间可以表示为：

已经连续收到 当前接收窗口 窗口之外
───────────────┬─────────────────────────┬────────────→
 RCV.NXT RCV.NXT+RCV.WND

假设依次发送四段：

A：[0, 400)
B：[400, 900)
C：[900, 1600)
D：[1600, 2000)

按序到达

收到 A：

RCV.NXT 从 0 变成 400

收到 B：

RCV.NXT 从 400 变成 900

C 暂时没有到达，D 先到

接收端当前仍缺少从 900 开始的数据，因此：

RCV.NXT 仍为 900
ACK 仍回复 900
D 可以暂存在乱序队列中

当 C 到达后：

C 与已经缓存的 D 连续
RCV.NXT 可以从 900 一次推进到 2000
ACK 回复 2000

对应用程序而言，TCP 仍然按顺序交付：

A → B → C → D

这就是 TCP 利用字节序号、累计 ACK 和乱序缓存实现有序字节流的过程。

十四、延迟确认怎样接入接收逻辑

收到数据后，接收端需要用 ACK 告诉发送端 RCV.NXT。ACK 可以有三种发送方式：

立即发送纯 ACK
延迟一小段时间后发送 ACK
把 ACK 捎带在反方向数据中

延迟确认的主要目标是减少纯 ACK 数量，并等待是否有反方向数据可以一起发送。

可以先用下面的学习模型理解：

收到第一个按序数据段
 → 更新 RCV.NXT
 → 设置 pending_ack
 → 启动 delayed ACK 定时器

定时器到期前又收到一个按序数据段
 → 再次更新 RCV.NXT
 → 立即发送累计 ACK

定时器到期
 → 发送 ACK=RCV.NXT

期间本端正好有数据要发
 → 把 ACK=RCV.NXT 填入数据段
 → 不再额外发送纯 ACK

遇到乱序段时，可以及时回复当前 RCV.NXT，让发送方看到重复 ACK 并发现连续数据中的缺口。

延迟确认属于接收端的 ACK 生成策略；超时重传和快速重传则是发送端恢复丢失数据的策略。

十五、为什么发送过的数据要暂时保存

调用：

rte_eth_tx_burst(
 global_portid,
 0,
 &mbuf,
 1
);

表示把报文提交给 DPDK TX Queue。对于 TCP 来说，提交发送以后还要等待对方 ACK，才能确认该序列范围已经到达。

因此 TCP 需要发送缓存和重传队列：

应用写入数据
 ↓
数据进入发送缓存
 ↓
按 MSS 和窗口切成 TCP 段
 ↓
记录每段的 seq_start、seq_end、发送时间
 ↓
构造 mbuf 并提交 TX
 ↓
等待 ACK
 ↓
收到累计 ACK 后释放已确认的数据

学习版重传项可以记录：

struct tcp_tx_segment {
 uint32_t seq_start;
 uint32_t seq_end;
 uint16_t payload_len;
 uint8_t flags;
 uint64_t first_tx_us;
 uint64_t last_tx_us;
 uint32_t retransmit_count;
};

例如：

重传队列：
[1000, 2000)
[2000, 3000)
[3000, 4000)

收到 ACK=3000 后：

[1000, 2000) 已确认，移除
[2000, 3000) 已确认，移除
[3000, 4000) 继续等待

十六、超时重传：没有收到 ACK 时怎么办

发送一个 TCP 段时，发送端记录发送时间并启动重传定时器。如果在 RTO 到期前没有收到能够确认它的 ACK，就重新发送最早未确认的数据。

发送数据段
 → 保存到重传队列
 → 启动 RTO 定时器
 → 收到新 ACK：推进 SND.UNA，重启或停止定时器
 → RTO 到期：重传最早未确认段

1. RTT

RTT 是数据发出到相应 ACK 返回所经历的往返时间：

send_time ───────────────────── ack_time
 RTT

网络时延会变化，因此不能只用某一次 RTT 作为固定重传时间。

2. SRTT、RTTVAR 与 RTO

TCP 对 RTT 做平滑，并记录波动程度：

SRTT 平滑 RTT
RTTVAR RTT 波动估计
RTO 重传超时时间

核心关系是：

RTO = SRTT + max(G, 4 × RTTVAR)

其中 G 是定时器时钟粒度。

第一次取得 RTT 样本 R 时：

SRTT = R
RTTVAR = R / 2

后续样本继续对两者进行平滑更新，使 RTO 能随网络情况变化。

3. RTO 指数退避

如果重传后仍然没有 ACK：

RTO = RTO × 2

继续超时则继续退避：

1RTO → 2RTO → 4RTO → 8RTO

这样可以避免网络已经拥塞时还以很高频率不断重传。

4. DPDK 主循环中的定时器

定时器处理不能阻塞轮询收包。主循环可以组织为：

while (1) {
 处理 RX burst
 处理到期的 TCP timers
 发送 TX 待发送队列
}

需要处理的 TCP 定时器可以逐步包括：

RTO timer
delayed ACK timer
zero-window persist timer
TIME_WAIT timer

十七、快速重传：通过重复 ACK 更早发现缺口

继续使用下面的序列：

A：[0, 400)
B：[400, 900)
C：[900, 1600) ← 丢失
D：[1600, 2000)
E：[2000, 2400)
F：[2400, 2800)

接收端收到 D、E、F 时，由于 C 仍未到达，连续前缀一直停在 900，于是多次回复：

ACK=900
ACK=900
ACK=900

发送端看到多个重复 ACK，可以在 RTO 之前推断从 900 开始的数据可能丢失。

经典快速重传通常使用：

3 个重复 ACK
 → 重传从 SND.UNA 开始的缺失段

如果握手时协商了 SACK，接收端还能在 TCP Options 中告诉发送端：

[1600, 2800) 已经收到

发送端便能更准确地只补发缺失区间 [900, 1600)。

十八、接收窗口 rwnd 与拥塞窗口 cwnd

发送方决定本轮还能发送多少数据时，要同时考虑两种窗口。

1. rwnd：接收端通告窗口

来源：

tcphdr->rx_win

含义：

对方接收缓存还能容纳多少数据

它解决的是流量控制问题，避免发送速度超过对方应用和接收缓存的处理能力。

2. cwnd：拥塞窗口

cwnd 由发送端本地维护，不直接写在 TCP Header 中。

含义：

根据当前网络状态，允许多少数据处于在途未确认状态

它解决的是拥塞控制问题，避免一次向网络注入过多数据。

3. 两个窗口共同限制发送

send_limit = min(rwnd, cwnd)
flight_size = SND.NXT - SND.UNA
available = send_limit - flight_size

例一：

rwnd = 64 KB
cwnd = 12 KB
flight_size = 8 KB

available = min(64, 12) - 8 = 4 KB

例二：

rwnd = 4 KB
cwnd = 32 KB
flight_size = 3 KB

available = min(4, 32) - 3 = 1 KB

第一个例子受网络拥塞窗口限制，第二个例子受对端接收窗口限制。

十九、慢启动：逐步探测网络容量

连接刚建立时，发送端并不知道路径能容纳多少在途数据，所以用 cwnd 逐步试探。

为了理解增长过程，先假设：

SMSS = 1000 字节
初始 cwnd = 1 × SMSS

第一个 RTT

cwnd=1 MSS
发送 1 个 MSS
收到确认新数据的 ACK
cwnd 增长到约 2 MSS

第二个 RTT

cwnd=2 MSS
发送 2 个 MSS
收到相应 ACK
cwnd 增长到约 4 MSS

第三个 RTT

cwnd=4 MSS
发送 4 个 MSS
cwnd 增长到约 8 MSS

所以慢启动的教学曲线经常写作：

1 → 2 → 4 → 8 → 16

它表示每经过一个 RTT，窗口大致成倍增长。具体实现中，初始窗口可以大于 1 MSS；理解重点是：

慢启动阶段每收到确认新数据的 ACK，cwnd 增加；
一轮 RTT 中 ACK 数量随已发送数据增加，因此整体近似指数增长。

二十、拥塞避免：超过阈值后降低增长速度

TCP 连接还维护：

ssthresh：慢启动阈值

两种阶段的关系是：

cwnd < ssthresh → 慢启动
cwnd > ssthresh → 拥塞避免

慢启动阶段增长较快；进入拥塞避免后，经典算法让 cwnd 每个 RTT 大约增加一个 MSS。

慢启动：近似指数增长
拥塞避免：近似线性增长

用窗口大小表示：

慢启动：1、2、4、8、16
拥塞避免：16、17、18、19、20

实际数值由 ACK、MSS 和算法计算，不一定正好是整数段；这组数字主要用于观察增长形态。

发生 RTO 时

经典学习模型中：

ssthresh = 当前在途数据量的一半，且至少为 2 MSS
cwnd = 1 MSS
重新进入慢启动

发生 3 个重复 ACK 时

说明后续数据仍在到达，发送端执行：

快速重传
调整 ssthresh
进入快速恢复

这几个机制组合起来就是经典 TCP Reno 的核心：

慢启动
拥塞避免
快速重传
快速恢复

二十一、把当前全局状态整理成一条连接的数据结构

目前的全局变量适合单连接实验。为了把已学习的概念放进代码，可以先整理成学习版连接控制块：

struct tcp_connection {
 /* 四元组 */
 uint32_t local_ip;
 uint32_t remote_ip;
 uint16_t local_port;
 uint16_t remote_port;

 USTACK_TCP_STATUS state;

 /* 初始序列号 */
 uint32_t iss;
 uint32_t irs;

 /* 发送方向 */
 uint32_t snd_una;
 uint32_t snd_nxt;
 uint32_t snd_wnd;

 /* 接收方向 */
 uint32_t rcv_nxt;
 uint32_t rcv_wnd;

 /* 重传定时器 */
 uint64_t srtt_us;
 uint64_t rttvar_us;
 uint64_t rto_us;
 uint64_t rto_deadline_us;

 /* 拥塞控制 */
 uint32_t smss;
 uint32_t cwnd;
 uint32_t ssthresh;

 /* 发送缓存、重传队列、接收缓存、乱序队列 */
};

字段与知识点的对应关系：

代码字段	TCP 含义
`state`	当前连接状态
`iss`	本端初始发送序列号
`irs`	对端初始发送序列号
`snd_una`	最早未确认的发送序号
`snd_nxt`	下一个新数据发送序号
`snd_wnd`	对端通告给本端的接收窗口
`rcv_nxt`	本端下一步期望收到的序号
`rcv_wnd`	本端当前可用接收窗口
`srtt_us`	平滑 RTT
`rttvar_us`	RTT 波动估计
`rto_us`	当前重传超时时间
`cwnd`	拥塞窗口
`ssthresh`	慢启动阈值

收到 TCP 报文后，通过四元组找到这条连接：

(local_ip, local_port, remote_ip, remote_port)
 ↓
tcp_connection

每个客户端都有自己的状态、SEQ/ACK、窗口、缓存和定时器。

二十二、ESTABLISHED 状态收到数据时的完整思路

当前代码在看见 PSH 后取得并打印数据：

if (global_flags & RTE_TCP_PSH_FLAG) {
 if (tcp_status == USTACK_TCP_STATUS_ESTABLISHED) {
 uint8_t hdrlen =
 (tcphdr->data_off >> 4)
 * sizeof(uint32_t);

 uint8_t *data =
 (uint8_t *)tcphdr + hdrlen;

 printf("tcp data: %s\n", data);
 }
}

把可靠传输补充进来以后，可以按下面的顺序理解：

收到 ESTABLISHED 状态报文
 ↓
计算 ip_hdr_len、tcp_hdr_len、payload_len
 ↓
读取 SEG.SEQ、SEG.ACK、SEG.WND
 ↓
处理 ACK：推进 snd_una
 ↓
判断 SEG.SEQ 与 rcv_nxt 的关系
 ↓
按序数据写入接收缓存；乱序数据进入乱序队列
 ↓
推进 rcv_nxt
 ↓
根据缓存剩余量更新 rcv_wnd
 ↓
立即 ACK、延迟 ACK，或在反向数据中携带 ACK
 ↓
根据 min(snd_wnd, cwnd) 尝试继续发送

学习版伪代码：

if (conn->state == USTACK_TCP_STATUS_ESTABLISHED) {
 tcp_process_ack(conn, seg_ack, seg_window);

 if (payload_len > 0) {
 if (seg_seq == conn->rcv_nxt) {
 recv_buffer_write(conn, payload, payload_len);
 conn->rcv_nxt += payload_len;

 consume_contiguous_out_of_order_data(conn);
 conn->rcv_wnd = recv_buffer_free_space(conn);

 schedule_or_send_ack(conn);
 } else if (seq_after(seg_seq, conn->rcv_nxt)) {
 queue_out_of_order_data(
 conn,
 seg_seq,
 payload,
 payload_len
 );

 send_ack(conn, conn->rcv_nxt);
 } else {
 send_ack(conn, conn->rcv_nxt);
 }
 }
}

这段伪代码把当前“读取 payload”的路径继续延伸为：

有序接收 + 累计确认 + 乱序缓存 + 接收窗口

二十三、发送数据时的完整思路

当服务端应用有数据需要发送时：

应用数据进入发送缓存
 ↓
读取 snd_wnd 和 cwnd
 ↓
计算当前还能发送多少
 ↓
按 SMSS 切分
 ↓
每段 SEQ = snd_nxt
ACK = rcv_nxt
Window = rcv_wnd
 ↓
保存到重传队列
 ↓
构造 Ethernet + IPv4 + TCP + payload
 ↓
rte_eth_tx_burst()
 ↓
snd_nxt 增加 payload_len
 ↓
启动或维护 RTO 定时器

核心计算：

uint32_t flight_size = conn->snd_nxt - conn->snd_una;
uint32_t send_limit = RTE_MIN(conn->snd_wnd, conn->cwnd);

if (send_limit > flight_size) {
 uint32_t available = send_limit - flight_size;
 uint32_t send_len = RTE_MIN(available, conn->smss);
 /* 构造一个 send_len 字节的数据段 */
}

构造数据段时：

tcp->sent_seq = htonl(conn->snd_nxt);
tcp->recv_ack = htonl(conn->rcv_nxt);
tcp->tcp_flags = RTE_TCP_ACK_FLAG | RTE_TCP_PSH_FLAG;
tcp->rx_win = htons(conn->rcv_wnd);

发送后：

conn->snd_nxt += send_len;

收到累计 ACK 后：

conn->snd_una = seg_ack;

于是发送窗口不断向右滑动。

二十四、用一次完整传输串起所有概念

假设握手结束后：

服务端 snd_una = 12346
服务端 snd_nxt = 12346
服务端 rcv_nxt = 1235
对端通告 snd_wnd = 6000
服务端 cwnd = 3000
SMSS = 1000

1. 计算发送能力

flight_size = 12346 - 12346 = 0
send_limit = min(6000, 3000) = 3000
available = 3000 - 0 = 3000

服务端可以先发送 3 个 1000 字节段：

段 1：SEQ=12346，范围 [12346,13346)
段 2：SEQ=13346，范围 [13346,14346)
段 3：SEQ=14346，范围 [14346,15346)

发送后：

snd_una = 12346
snd_nxt = 15346
flight_size = 3000

2. 对端累计确认

如果三个段都按序收到，对端回复：

ACK=15346

服务端处理后：

snd_una = 15346
snd_nxt = 15346
flight_size = 0

三个段都可以从重传队列中移除。

3. 慢启动增加 cwnd

ACK 确认了新数据，慢启动阶段继续增加 cwnd，下一轮允许更多在途数据，但仍受 snd_wnd 限制。

4. 中间一段丢失

如果第二段丢失，第三段到达，对端连续前缀只能到 13346，因此回复：

ACK=13346

继续收到后续乱序段时仍回复相同 ACK。发送端可以通过重复 ACK 快速重传第二段；如果没有足够的后续 ACK，则由 RTO 定时器最终触发重传。

这一过程把以下概念连在了一起：

SEQ
ACK
滑动窗口
接收窗口
拥塞窗口
慢启动
乱序队列
快速重传
超时重传

二十五、代码与 TCP 知识点对照表

当前代码	对应 TCP 含义	后续实现中保存的位置
`tcphdr->sent_seq`	当前段第一个序列号	`SEG.SEQ`
`tcphdr->recv_ack`	对端累计确认号	`SEG.ACK`
`tcphdr->tcp_flags`	SYN/ACK/PSH/FIN/RST	当前报文状态输入
`tcphdr->rx_win`	报文发送方通告的接收窗口	本端 `snd_wnd`
`tcp->rx_win`	本端向对方通告的接收窗口	本端 `rcv_wnd`
`tcp_status`	当前连接状态	`conn->state`
`global_seqnum + 1`	确认一个 SYN	`conn->rcv_nxt`
`12345`	学习代码中的服务端 ISN	`conn->iss`
`data_off >> 4`	TCP Header 的 32 位字数量	计算 `tcp_hdr_len`
`rte_eth_tx_burst()`	把报文交给 TX Queue	发送路径
`TCP_INIT_WINDOWS`	初始接收窗口示例	`conn->rcv_wnd`
尚未加入	最早未确认序号	`conn->snd_una`
尚未加入	下一个新发送序号	`conn->snd_nxt`
尚未加入	下一个期望接收序号	`conn->rcv_nxt`
尚未加入	重传定时器	`conn->rto_us`
尚未加入	拥塞窗口	`conn->cwnd`
尚未加入	慢启动阈值	`conn->ssthresh`

二十六、整条 TCP 处理路径

flowchart TD
 A["rte_eth_rx_burst 收包"] --> B["解析 Ethernet 和 IPv4"]
 B --> C["定位 TCP Header"]
 C --> D["读取四元组、Flags、SEQ、ACK、Window"]
 D --> E["按四元组查找连接"]
 E --> F{"连接状态"}
 F -->|"LISTEN + SYN"| G["记录客户端 ISN，发送 SYN+ACK"]
 G --> H["进入 SYN_RCVD"]
 F -->|"SYN_RCVD + ACK"| I["确认服务端 SYN"]
 I --> J["进入 ESTABLISHED"]
 F -->|"ESTABLISHED"| K["处理 ACK，推进 SND.UNA"]
 K --> L["释放已确认发送缓存，更新 RTT/RTO/cwnd"]
 F -->|"ESTABLISHED + payload"| M["按 SEQ 处理按序或乱序数据"]
 M --> N["推进 RCV.NXT，更新 RCV.WND"]
 N --> O["发送或延迟 ACK"]
 L --> P["计算 min(rwnd,cwnd)-flight_size"]
 P --> Q["窗口允许时继续发送"]
 Q --> R["数据进入重传队列并提交 TX"]
 S["RTO 定时器"] --> T["超时重传并调整拥塞状态"]
 T --> R

二十七、复习时抓住的主线

第一条：连接状态

LISTEN → SYN_RCVD → ESTABLISHED

状态决定当前收到的 Flags 应该怎样解释。

第二条：字节序列

SEQ 标识本方向发送的数据
ACK 确认反方向连续收到的数据

第三条：发送可靠性

数据发出后保留
ACK 到达后释放
重复 ACK 可触发快速重传
RTO 到期触发超时重传

第四条：有序接收

RCV.NXT 之前已经连续收到
等于 RCV.NXT 的数据可以推进确认号
更大的 SEQ 暂存到乱序队列
缺口补齐后连续交付给应用

第五条：发送数量

rwnd 保护接收端
cwnd 保护网络
实际发送上限取二者较小值

第六条：网络探测

慢启动快速扩大 cwnd
到达 ssthresh 后进入拥塞避免
丢包或超时后降低发送强度

二十八、总结

当前代码用下面几行打开了理解 TCP 的入口：

global_flags = tcphdr->tcp_flags;
global_seqnum = ntohl(tcphdr->sent_seq);
global_acknum = ntohl(tcphdr->recv_ack);

沿着它们继续向下，就是完整的 TCP 传输控制：

Flags 驱动连接状态机
SEQ 给每个方向的数据字节编号
ACK 累计确认已经连续收到的字节
SND.UNA 与 SND.NXT 形成发送滑动窗口
RCV.NXT 与 RCV.WND 管理有序接收和接收缓存
发送缓存保留尚未确认的数据
重复 ACK 与 RTO 负责发现并恢复丢失
rwnd 控制接收端承受能力
cwnd、ssthresh、慢启动和拥塞避免控制网络中的在途数据

因此，从当前代码继续实现 TCP 的核心方向，就是把现在的全局 flags、seq、ack、tcp_status 扩展为每条连接独立的状态、序列空间、窗口、缓存和定时器。

参考规范

DPDK 用户态协议栈（二）：从收包到 UDP Echo 与 TCP 握手

Mon, 17 Aug 2026 00:00:00 +0800

本文承接《dpdk用户态协议栈设计与实现》。本文把重点放在一个新问题上：收到数据以后，怎样在用户态构造一个符合协议的响应包并发送出去？ 为了让代码能够独立读懂，后文会从程序入口开始完整解释执行流程；网络分层等原理知识则只在影响代码理解时说明。

一、本篇要完成什么

上一篇的程序已经可以：

初始化 EAL、mempool 和网口；
通过 rte_eth_rx_burst() 轮询收包；
识别 Ethernet、IPv4、UDP 和 TCP；
打印报文中的地址、端口与数据。

本篇继续完成三件事：

为网口配置 TX Queue，使程序具备发包能力；
实现 UDP Echo：收到 UDP 数据后，构造响应包并原样返回 payload；
实现最小 TCP 服务端：收到 SYN 后回复 SYN+ACK，再接收 ACK 和应用数据。

这里实现的是用于学习协议与验证收发链路的最小原型，不是可投入生产的完整协议栈。

二、用编译期开关隔离增量代码

开发新功能时，可以先用宏把新增代码包起来：

#define ENABLE_SEND 1
#define ENABLE_TCP 1

#if ENABLE_SEND
/* TX Queue、UDP 回包等新增代码 */
#endif

#if ENABLE_TCP
/* TCP 状态机与 TCP 回包代码 */
#endif

这样做的价值不是“上线前把代码删掉”，而是：

新功能出问题时，可快速回退到仅收包版本；
可以分别验证 RX、UDP TX 和 TCP 三部分；
提交 patch 时，新增逻辑的边界更加清楚。

如果功能会长期存在，最终更适合使用构建选项或运行时配置；长期散落大量 #if 会增加维护成本。

三、能收包不等于能发包

仅配置 RX Queue 时，网卡只能供当前程序收包。要发送数据，还需要完成三步：

const uint16_t num_rx_queues = 1;
const uint16_t num_tx_queues = ENABLE_SEND ? 1 : 0;

if (rte_eth_dev_configure(port_id,
 num_rx_queues,
 num_tx_queues,
 &port_conf) < 0) {
 rte_exit(EXIT_FAILURE, "Could not configure port\n");
}

#if ENABLE_SEND
struct rte_eth_txconf txq_conf = dev_info.default_txconf;
txq_conf.offloads = port_conf.txmode.offloads;

if (rte_eth_tx_queue_setup(port_id,
 0,
 512,
 rte_eth_dev_socket_id(port_id),
 &txq_conf) < 0) {
 rte_exit(EXIT_FAILURE, "Could not setup TX queue\n");
}
#endif

if (rte_eth_dev_start(port_id) < 0) {
 rte_exit(EXIT_FAILURE, "Could not start port\n");
}

完整顺序是：

rte_eth_dev_configure
 ↓
rte_eth_rx_queue_setup / rte_eth_tx_queue_setup
 ↓
rte_eth_dev_start
 ↓
rte_eth_rx_burst / rte_eth_tx_burst

`rte_eth_tx_burst()` 的返回值

uint16_t nb_tx = rte_eth_tx_burst(port_id, 0, &tx_mbuf, 1);

if (nb_tx == 0) {
 rte_pktmbuf_free(tx_mbuf);
}

返回值表示实际被 TX Queue 接收的 mbuf 数量：

返回 1：mbuf 的所有权已交给 DPDK/驱动，应用不能立即释放或继续修改；
返回 0：该 mbuf 没有成功入队，仍由应用负责，应重试或释放。

批量发送时，只能释放返回值之后的未发送部分：

uint16_t nb_tx = rte_eth_tx_burst(port_id, 0, tx_pkts, nb_pkts);

for (uint16_t i = nb_tx; i < nb_pkts; i++) {
 rte_pktmbuf_free(tx_pkts[i]);
}

这是 DPDK 发包代码中很重要的内存所有权规则。

四、为什么把收到的 mbuf 直接发出去不是 Echo

最初的尝试是：

rte_eth_tx_burst(port_id, 0, &mbufs[i], 1);

这只是把收到的原始帧再次发出。原包仍然是：

客户端 MAC/IP/Port → 服务端 MAC/IP/Port

而响应包必须是：

服务端 MAC/IP/Port → 客户端 MAC/IP/Port

因此至少要处理：

协议层	响应包需要修改的内容
Ethernet	源 MAC 与目的 MAC 对调
IPv4	源 IP 与目的 IP 对调，重新计算 IPv4 头校验和
UDP	源端口与目的端口对调，重新计算 UDP 校验和
TCP	对调端口，并根据状态设置 Flags、SEQ、ACK 和校验和

以太网 FCS/CRC 通常由网卡在真正发出帧时生成，应用一般不需要在 mbuf 末尾手工追加；但 IPv4、UDP、TCP 的校验和必须由软件计算，或者明确配置硬件 checksum offload。

五、UDP Echo 的数据路径

UDP Echo 的完整过程是：

RX Queue 收到请求
 ↓
检查 Ethernet / IPv4 / UDP 及各层长度
 ↓
保存并对调 MAC、IP、Port
 ↓
从 mempool 分配新的 TX mbuf
 ↓
依次写入 Ethernet、IPv4、UDP Header
 ↓
复制原 UDP payload
 ↓
计算 IPv4 与 UDP checksum
 ↓
rte_eth_tx_burst 发送

为便于学习，草稿使用了全局变量暂存一组通信端点：

uint8_t global_smac[RTE_ETHER_ADDR_LEN];
uint8_t global_dmac[RTE_ETHER_ADDR_LEN];
uint32_t global_sip;
uint32_t global_dip;
uint16_t global_sport;
uint16_t global_dport;

收到请求后，对调方向：

rte_memcpy(global_smac,
 eth->dst_addr.addr_bytes,
 RTE_ETHER_ADDR_LEN);
rte_memcpy(global_dmac,
 eth->src_addr.addr_bytes,
 RTE_ETHER_ADDR_LEN);

global_sip = ip->dst_addr;
global_dip = ip->src_addr;
global_sport = udp->dst_port;
global_dport = udp->src_port;

这些字段本身仍保持网络字节序，写回协议头时不需要再次 hton*()。

不要用全局变量保存真实连接

全局变量只适合单队列、单线程、一次处理一个包的教学程序。多个客户端或多个 lcore 并发时，后一包会覆盖前一包的端点信息。更合理的做法是把地址信息作为函数参数传入，TCP 则使用以四元组为 key 的连接表。

六、构造 UDP 响应包

1. 先算清三种长度

设 UDP payload 长度为 payload_len：

uint16_t udp_len = sizeof(struct rte_udp_hdr) + payload_len;
uint16_t ip_len = sizeof(struct rte_ipv4_hdr) + udp_len;
uint16_t frame_len = sizeof(struct rte_ether_hdr) + ip_len;

三者的含义不同：

udp->dgram_len：UDP Header + UDP payload；
ip->total_length：IPv4 Header + IPv4 payload，不含 Ethernet Header；
mbuf->pkt_len/data_len：本例中的完整 Ethernet 帧长度，不含硬件生成的 FCS。

2. 分配并扩展 mbuf

更稳妥的写法是使用 rte_pktmbuf_append()，而不是只手工改长度字段：

struct rte_mbuf *tx_mbuf = rte_pktmbuf_alloc(mbuf_pool);
if (tx_mbuf == NULL) {
 return -ENOMEM;
}

uint8_t *frame = rte_pktmbuf_append(tx_mbuf, frame_len);
if (frame == NULL) {
 rte_pktmbuf_free(tx_mbuf);
 return -ENOSPC;
}

rte_pktmbuf_append() 会检查尾部空间，并同步更新 data_len 与 pkt_len。

3. 写 Ethernet Header

struct rte_ether_hdr *eth = (struct rte_ether_hdr *)frame;

rte_memcpy(eth->dst_addr.addr_bytes,
 global_dmac,
 RTE_ETHER_ADDR_LEN);
rte_memcpy(eth->src_addr.addr_bytes,
 global_smac,
 RTE_ETHER_ADDR_LEN);
eth->ether_type = rte_cpu_to_be_16(RTE_ETHER_TYPE_IPV4);

不同 DPDK 版本中，成员名可能是 d_addr/s_addr 或 dst_addr/src_addr，应以本机头文件为准。

4. 写 IPv4 Header

struct rte_ipv4_hdr *ip = (struct rte_ipv4_hdr *)(eth + 1);

*ip = (struct rte_ipv4_hdr){0};
ip->version_ihl = RTE_IPV4_VHL_DEF;
ip->total_length = rte_cpu_to_be_16(ip_len);
ip->time_to_live = 64;
ip->next_proto_id = IPPROTO_UDP;
ip->src_addr = global_sip;
ip->dst_addr = global_dip;
ip->hdr_checksum = 0;
ip->hdr_checksum = rte_ipv4_cksum(ip);

version_ihl = 0x45 表示 IPv4，且头部长度为 5 × 4 = 20 字节。使用 RTE_IPV4_VHL_DEF 可读性更好。

total_length 是 16 位多字节字段，写入协议头前必须转为网络字节序。

5. 写 UDP Header 和 payload

struct rte_udp_hdr *udp = (struct rte_udp_hdr *)(ip + 1);

udp->src_port = global_sport;
udp->dst_port = global_dport;
udp->dgram_len = rte_cpu_to_be_16(udp_len);
udp->dgram_cksum = 0;

rte_memcpy(udp + 1, payload, payload_len);

udp->dgram_cksum = rte_ipv4_udptcp_cksum(ip, udp);

这里最容易写错的是复制长度。udp_len 包含 8 字节 UDP Header，因此复制 payload 时必须使用：

payload_len = udp_len - sizeof(struct rte_udp_hdr);

不能把整个 udp_len 字节都从 udp + 1 开始复制，否则会越界读取原报文，并可能越界写入新 mbuf。

6. 一个整理后的编码函数

static int encode_udp_echo(uint8_t *frame,
 const uint8_t *payload,
 uint16_t payload_len)
{
 uint16_t udp_len = sizeof(struct rte_udp_hdr) + payload_len;
 uint16_t ip_len = sizeof(struct rte_ipv4_hdr) + udp_len;

 struct rte_ether_hdr *eth = (struct rte_ether_hdr *)frame;
 rte_memcpy(eth->dst_addr.addr_bytes, global_dmac,
 RTE_ETHER_ADDR_LEN);
 rte_memcpy(eth->src_addr.addr_bytes, global_smac,
 RTE_ETHER_ADDR_LEN);
 eth->ether_type = rte_cpu_to_be_16(RTE_ETHER_TYPE_IPV4);

 struct rte_ipv4_hdr *ip = (struct rte_ipv4_hdr *)(eth + 1);
 *ip = (struct rte_ipv4_hdr){0};
 ip->version_ihl = RTE_IPV4_VHL_DEF;
 ip->total_length = rte_cpu_to_be_16(ip_len);
 ip->time_to_live = 64;
 ip->next_proto_id = IPPROTO_UDP;
 ip->src_addr = global_sip;
 ip->dst_addr = global_dip;
 ip->hdr_checksum = rte_ipv4_cksum(ip);

 struct rte_udp_hdr *udp = (struct rte_udp_hdr *)(ip + 1);
 udp->src_port = global_sport;
 udp->dst_port = global_dport;
 udp->dgram_len = rte_cpu_to_be_16(udp_len);
 udp->dgram_cksum = 0;

 rte_memcpy(udp + 1, payload, payload_len);
 udp->dgram_cksum = rte_ipv4_udptcp_cksum(ip, udp);

 return 0;
}

七、安全取得 UDP payload

草稿中使用：

printf("udp: %s\n", (char *)(udp + 1));

这只能用于确保 payload 末尾带 \0 的演示数据。网络报文是带长度的二进制数据，不保证是 C 字符串。

在不考虑 IPv4 Options 的最小版本中：

uint16_t udp_len = rte_be_to_cpu_16(udp->dgram_len);
if (udp_len < sizeof(struct rte_udp_hdr)) {
 /* malformed packet */
}

uint16_t payload_len = udp_len - sizeof(struct rte_udp_hdr);
uint8_t *payload = (uint8_t *)(udp + 1);

printf("udp: %.*s\n", (int)payload_len, (char *)payload);

真正处理报文前，还要结合 rte_pktmbuf_pkt_len(mbuf) 检查 Ethernet、IP、UDP 声明的长度是否落在 mbuf 实际数据范围内。需要记住：构造包和解析包都必须以显式长度为边界。

打印 IP 和端口

struct in_addr addr = { .s_addr = ip->src_addr };
printf("sip %s:%u --> ", inet_ntoa(addr),
 rte_be_to_cpu_16(udp->src_port));

addr.s_addr = ip->dst_addr;
printf("dip %s:%u\n", inet_ntoa(addr),
 rte_be_to_cpu_16(udp->dst_port));

inet_ntoa() 使用内部静态缓冲区，不适合并发代码；工程中优先使用 inet_ntop()。

UDP 收到一个数据报就可以立即生成一个独立响应。TCP 则必须维护连接状态，因为一个 TCP 报文的正确响应取决于此前发生过什么。

最小服务端路径为：

客户端 DPDK 服务端
 | -------- SYN, seq=x --------> |
 | <--- SYN+ACK, seq=y, ack=x+1 -|
 | -------- ACK, ack=y+1 ------> |
 | | ESTABLISHED
 | ------ PSH+ACK, data --------> |

草稿定义了完整 TCP 状态枚举：

typedef enum {
 USTACK_TCP_STATUS_CLOSED = 0,
 USTACK_TCP_STATUS_LISTEN,
 USTACK_TCP_STATUS_SYN_RCVD,
 USTACK_TCP_STATUS_SYN_SENT,
 USTACK_TCP_STATUS_ESTABLISHED,
 USTACK_TCP_STATUS_FIN_WAIT_1,
 USTACK_TCP_STATUS_FIN_WAIT_2,
 USTACK_TCP_STATUS_CLOSING,
 USTACK_TCP_STATUS_TIME_WAIT,
 USTACK_TCP_STATUS_CLOSE_WAIT,
 USTACK_TCP_STATUS_LAST_ACK
} ustack_tcp_status_t;

当前代码实际只实现了：

LISTEN → SYN_RCVD → ESTABLISHED

因此准确的描述是“完成服务端三次握手的最小实验”，而不是“已经实现 TCP 协议栈”。重传、乱序、滑动窗口、拥塞控制、RST、FIN 四次挥手、TIME_WAIT、TCP Options 和多连接管理都还没有实现。

九、TCP 的 SEQ 与 ACK 应该怎样理解

收到客户端 SYN：

client.seq = x

服务端回复 SYN+ACK：

server.seq = y
server.ack = x + 1

SYN 虽然不携带应用数据，但会占用一个序列号，所以确认号是 x + 1。FIN 同样占用一个序列号。

对于普通数据段：

下一确认号 = 当前 seq + TCP payload 长度

如果同一段还带 SYN 或 FIN，还应分别再加 1。

草稿中的：

tcp->sent_seq = htonl(12345);
tcp->recv_ack = htonl(global_seqnum + 1);

足以演示 SYN+ACK，但 12345 应被视为教学用的初始序列号。真实实现需要为每条连接保存本端/对端序列号，并校验收到的 ACK 是否真正确认了自己发送的 SYN 或数据。

十、构造最小 SYN+ACK

TCP 响应与 UDP 的 Ethernet、IPv4 部分基本相同；区别在 TCP Header：

struct rte_tcp_hdr *tcp = (struct rte_tcp_hdr *)(ip + 1);
*tcp = (struct rte_tcp_hdr){0};

tcp->src_port = global_sport;
tcp->dst_port = global_dport;
tcp->sent_seq = rte_cpu_to_be_32(server_isn);
tcp->recv_ack = rte_cpu_to_be_32(client_seq + 1);
tcp->data_off = (sizeof(struct rte_tcp_hdr) / 4) << 4;
tcp->tcp_flags = RTE_TCP_SYN_FLAG | RTE_TCP_ACK_FLAG;
tcp->rx_win = rte_cpu_to_be_16(TCP_INIT_WINDOW);
tcp->cksum = 0;
tcp->cksum = rte_ipv4_udptcp_cksum(ip, tcp);

几个容易忽略的点：

data_off 的高 4 位表示 TCP Header 占几个 32 位字；基础头 20 字节，所以值为 5 << 4，即 0x50；
rx_win 是多字节字段，应使用网络字节序；
计算 checksum 前，checksum 字段必须先清零；
struct rte_tcp_hdr 最好整体清零，避免未初始化的 cksum、tcp_urp 等字段混入报文；
IPv4 total_length 必须覆盖 IPv4 Header、TCP Header 和 TCP payload。

为什么 UDP 头有长度，而 TCP 头没有

UDP 自身以数据报为边界，因此 Header 中有 dgram_len：

UDP 长度 = UDP Header + UDP payload

TCP 是字节流协议，段长度可以从 IPv4 总长度推导：

TCP 段长度 = IP total_length - IP Header 长度
TCP payload 长度 = TCP 段长度 - TCP Header 长度

对应代码：

uint16_t ip_hdr_len = (ip->version_ihl & 0x0f) * 4;
uint16_t tcp_hdr_len = (tcp->data_off >> 4) * 4;
uint16_t ip_total_len = rte_be_to_cpu_16(ip->total_length);

uint16_t tcp_payload_len =
 ip_total_len - ip_hdr_len - tcp_hdr_len;

因此，TCP 的确认号并不是“长度字段”，但它会随着已经确认的字节数向前推进，体现了 TCP 字节流的位置。

十一、最小 TCP 状态处理

1. LISTEN 收到 SYN

if ((flags & RTE_TCP_SYN_FLAG) &&
 state == USTACK_TCP_STATUS_LISTEN) {
 client_next_seq = rte_be_to_cpu_32(tcp->sent_seq) + 1;
 send_syn_ack(...);
 state = USTACK_TCP_STATUS_SYN_RCVD;
}

2. SYN_RCVD 收到有效 ACK

不能只检查 ACK 位，还应验证确认号：

if ((flags & RTE_TCP_ACK_FLAG) &&
 state == USTACK_TCP_STATUS_SYN_RCVD &&
 rte_be_to_cpu_32(tcp->recv_ack) == server_isn + 1) {
 state = USTACK_TCP_STATUS_ESTABLISHED;
}

3. ESTABLISHED 收到数据

PSH 只是提示接收端尽快把数据交给应用，不是“存在 payload”的唯一判断条件。更可靠的判断是计算 tcp_payload_len > 0：

uint16_t payload_len = get_tcp_payload_len(ip, tcp);

if (state == USTACK_TCP_STATUS_ESTABLISHED && payload_len > 0) {
 const uint8_t *payload = (const uint8_t *)tcp + tcp_hdr_len;
 printf("tcp data: %.*s\n", (int)payload_len,
 (const char *)payload);

 /* 回复 ACK 时：ack = peer_seq + payload_len */
}

草稿能够打印 TCP 数据，但还没有为数据段回复 ACK，也没有处理 FIN；一些客户端因此会持续重传或无法正常关闭连接。

十二、从草稿中提炼出的典型 Bug

1. IPv4 地址只复制了 2 字节

错误版本：

rte_memcpy(&global_sip, &ip->dst_addr, sizeof(uint16_t));

IPv4 地址是 32 位，应复制 sizeof(uint32_t)，或者直接赋值：

global_sip = ip->dst_addr;
global_dip = ip->src_addr;

2. 把 UDP 总长度当成 payload 长度

错误思路：

rte_memcpy(udp + 1, data, udp_len);

正确关系：

payload_len = udp_len - sizeof(struct rte_udp_hdr);
rte_memcpy(udp + 1, data, payload_len);

3. 分配了新 mbuf，却传错发送指针

错误版本：

rte_eth_tx_burst(port_id, 0, &mbufs, 1);

应发送刚构造的单个 mbuf：

rte_eth_tx_burst(port_id, 0, &mbuf, 1);

&mbufs 是整个 RX 指针数组的地址，语义也不正确。

4. 多字节字段漏做字节序转换

典型字段包括：

ip->total_length = rte_cpu_to_be_16(ip_len);
udp->dgram_len = rte_cpu_to_be_16(udp_len);
tcp->sent_seq = rte_cpu_to_be_32(seq);
tcp->recv_ack = rte_cpu_to_be_32(ack);
tcp->rx_win = rte_cpu_to_be_16(window);

MAC 地址和 payload 是字节数组，不需要转换。

5. 不检查 TX 返回值

TX Queue 满时，rte_eth_tx_burst() 可以少发甚至不发。未成功发送的 mbuf 若不释放，会产生内存泄漏。

6. 只看 Flags，不校验状态与序列号

“收到带 ACK 标志的包”不等于三次握手完成。至少还要确认当前状态是 SYN_RCVD，且 ACK 值为服务端初始序列号加 1。

十三、完整代码逐行讲解

这一节按照程序真正的运行顺序，从头文件开始解释，直到收到、解析、构造并发送一个包。代码前面的数字只是讲解用行号，不是源代码的一部分。

1. 头文件分别提供什么

01 #include <stdio.h>
02 #include <stdint.h>
03 #include <errno.h>
04 #include <arpa/inet.h>
05
06 #include <rte_eal.h>
07 #include <rte_ethdev.h>
08 #include <rte_mbuf.h>
09 #include <rte_ether.h>
10 #include <rte_ip.h>
11 #include <rte_udp.h>
12 #include <rte_tcp.h>

第 1 行：提供 printf()。
第 2 行：提供 uint8_t、uint16_t、uint32_t 等定长整数类型。网络协议字段有固定宽度，因此比普通 int 更合适。
第 3 行：提供 ENOMEM、ENOSPC 等错误码。
第 4 行：提供 inet_ntop()、htons() 等网络地址与字节序函数。
第 6 行：提供 rte_eal_init()、rte_exit() 等 DPDK 运行环境接口。
第 7 行：提供网口、RX/TX Queue 和 rte_eth_rx_burst()、rte_eth_tx_burst()。
第 8 行：提供 mempool、mbuf 分配、释放和数据地址转换接口。
第 9～12 行：分别提供 Ethernet、IPv4、UDP、TCP Header 结构体和协议常量。

#include 的作用是把函数声明、结构体定义和宏定义提供给当前 .c 文件。它不会替代链接步骤；编译时仍要通过 DPDK 的 pkg-config 参数链接对应库。

2. 全局端口、mbuf 数量与 Burst 大小

01 static uint16_t global_portid = 0;
02
03 #define NUM_MBUFS 4096
04 #define BURST_SIZE 128

第 1 行：选择 DPDK 端口 0。它表示 DPDK 枚举得到的端口编号，不一定等于 Linux 中的网卡名称或 PCI 地址。
static：这里表示变量只在当前源文件内可见，减少与其他文件同名变量冲突的机会。
第 3 行：mempool 预备 4096 个 mbuf。RX 和新建的 TX 包都会消耗池中的对象。
第 4 行：一次 rte_eth_rx_burst() 最多取回 128 个 mbuf 指针。

NUM_MBUFS 是整个对象池规模，BURST_SIZE 是一次批量操作的上限，两者不是同一概念。

3. 功能开关与发送端点

01 #define ENABLE_SEND 1
02 #define ENABLE_TCP 1
03 #define TCP_INIT_WINDOW 14600
04
05 #if ENABLE_SEND
06 uint8_t global_smac[RTE_ETHER_ADDR_LEN];
07 uint8_t global_dmac[RTE_ETHER_ADDR_LEN];
08 uint32_t global_sip;
09 uint32_t global_dip;
10 uint16_t global_sport;
11 uint16_t global_dport;
12 #endif

第 1 行：控制是否编译发包代码。关闭后可退回仅收包版本。
第 2 行：控制是否编译 TCP 实验代码，可以只验证 UDP。
第 3 行：定义 SYN+ACK 中通告给客户端的接收窗口大小。
第 5～12 行：只有启用发送功能时才定义响应端点。
第 6～7 行：分别保存响应包的源 MAC 与目的 MAC。
第 8～9 行：IPv4 地址是 32 位，因此类型必须是 uint32_t。
第 10～11 行：TCP/UDP 端口是 16 位。

这些变量保存的地址和端口直接来自收到的协议头，所以仍是网络字节序。只有打印或参与主机侧数值计算时，才需要 rte_be_to_cpu_16()、rte_be_to_cpu_32()。

4. 端口默认配置

01 static const struct rte_eth_conf port_conf_default = {
02 .rxmode = {
03 .max_rx_pkt_len = RTE_ETHER_MAX_LEN
04 }
05 };

第 1 行：定义一个网口配置结构体，并用 const 表示运行中不修改它。
.rxmode = { ... }：这是 C 语言的指定初始化器，只填写 rxmode 成员，其余成员自动初始化为 0。
第 3 行：把最大接收包长设为普通 Ethernet 帧允许的范围。

不同 DPDK 版本的 struct rte_eth_conf 字段可能变化。如果本机版本提示 max_rx_pkt_len 不存在，应检查安装版本的头文件和示例，而不是强行照抄字段名。

5. 查询可用端口和设备默认能力

01 static int ustack_init_port(struct rte_mempool *mbuf_pool)
02 {
03 uint16_t nb_ports = rte_eth_dev_count_avail();
04
05 if (nb_ports == 0) {
06 rte_exit(EXIT_FAILURE,
07 "No supported Ethernet device found\n");
08 }
09
10 if (!rte_eth_dev_is_valid_port(global_portid)) {
11 rte_exit(EXIT_FAILURE, "Invalid port id\n");
12 }
13
14 struct rte_eth_dev_info dev_info;
15 int ret = rte_eth_dev_info_get(global_portid, &dev_info);
16 if (ret != 0) {
17 rte_exit(EXIT_FAILURE,
18 "Cannot get device info: %d\n", ret);
19 }

第 1 行：函数接收 mempool 指针，因为 RX Queue 需要知道从哪个池获取接收缓冲区。
第 3 行：查询当前由 DPDK 管理且可用的 Ethernet 端口数量。
第 5～8 行：一个可用端口都没有时直接退出。常见原因包括网卡没有绑定到合适驱动、权限不足或 EAL 参数错误。
第 10 行：即使系统存在端口，也要确认准备使用的 global_portid 有效。
第 14 行：声明设备信息结构体，用于接收驱动默认配置和网卡能力。
第 15 行：读取 0 号端口的信息。
第 16～18 行：检查 API 返回值；不能在查询失败后继续使用未初始化的 dev_info。

6. 配置 RX Queue 与 TX Queue 的数量

01 const uint16_t num_rx_queues = 1;
02
03 #if ENABLE_SEND
04 const uint16_t num_tx_queues = 1;
05 #else
06 const uint16_t num_tx_queues = 0;
07 #endif
08
09 rte_eth_dev_configure(global_portid,
10 num_rx_queues,
11 num_tx_queues,
12 &port_conf_default);
13
14 #if ENABLE_SEND
15 struct rte_eth_txconf txq_conf = dev_info.default_txconf;
16 txq_conf.offloads = port_conf_default.txmode.offloads;
17
18 if (rte_eth_tx_queue_setup(global_portid,
19 0,
20 512,
21 rte_eth_dev_socket_id(global_portid),
22 &txq_conf) < 0) {
23 rte_exit(EXIT_FAILURE, "Could not setup TX queue\n");
24 }
25 #endif

第 1 行：仍然只配置一个 RX Queue。
第 3～7 行：启用发送时创建一个 TX Queue，否则把 TX Queue 数量设为 0。
第 9～12 行：网口配置阶段必须提前声明 RX/TX Queue 的数量。
第 15 行：从设备能力信息中复制驱动提供的默认 TX 配置，避免凭空构造不兼容的参数。
第 16 行：把端口级 TX offload 配置同步给队列。草稿整理前曾写成 rxmode.offloads，此处应与 TX 配置对应。
第 18 行：开始配置 TX Queue。
第 19 行：队列编号为 0，因为当前只创建一个发送队列。
第 20 行：TX 描述符数量为 512，它描述队列容量，不是单次最多只能发送 512 个包。
第 21 行：让队列内存尽量位于网卡所属的 NUMA Socket。
第 22 行：传入刚才复制并调整的 TX 配置。
第 23 行：配置失败就退出，避免程序进入一个必然无法发送的循环。

7. 配置 RX Queue

01 if (rte_eth_rx_queue_setup(global_portid,
02 0,
03 128,
04 rte_eth_dev_socket_id(global_portid),
05 NULL,
06 mbuf_pool) < 0) {
07 rte_exit(EXIT_FAILURE, "Could not setup RX queue\n");
08 }

第 1 行：为指定网口建立接收队列。
第 2 行：队列编号为 0。
第 3 行：配置 128 个 RX 描述符。描述符用于让网卡和驱动追踪接收缓冲区，不等于只创建 128 个 mbuf。
第 4 行：选择网卡所在 NUMA Socket。
第 5 行：传 NULL 表示使用驱动默认 RX Queue 配置。
第 6 行：把前面创建的 mempool 交给 RX Queue。网卡收到包后，驱动会使用池中的 mbuf 承载数据。
第 7 行：队列创建失败就退出。

8. 启动端口并返回

01 if (rte_eth_dev_start(global_portid) < 0) {
02 rte_exit(EXIT_FAILURE, "Could not start port\n");
03 }
04
05 return 0;
06 }

第 1 行：前面的 configure 和 queue setup 只是准备配置，这里才真正启动设备。
第 2 行：启动失败不能进入收发循环。
第 5 行：返回 0 表示端口初始化成功。
第 6 行：结束 ustack_init_port() 函数。

9. `main()` 的参数与 EAL 初始化

01 int main(int argc, char **argv)
02 {
03 int ret = rte_eal_init(argc, argv);
04 if (ret < 0) {
05 rte_exit(EXIT_FAILURE, "Error with EAL init\n");
06 }

第 1 行：argc 是命令行参数数量，argv 是字符串指针数组。
第 3 行：初始化 DPDK EAL。它会处理 lcore、内存、设备等 DPDK 参数。
返回负数表示初始化失败。
返回非负数表示 EAL 消耗掉的命令行参数数量。如果程序还要解析自己的参数，可以使用 argc -= ret; argv += ret; 跳过 EAL 参数。
第 4～5 行：初始化失败时打印错误并结束进程。

EAL 必须先初始化，后面创建 mempool、查询端口和配置设备才有可用的 DPDK 运行环境。

10. 创建 mbuf pool

07 struct rte_mempool *mbuf_pool =
08 rte_pktmbuf_pool_create("mbuf_pool",
09 NUM_MBUFS,
10 0,
11 0,
12 RTE_MBUF_DEFAULT_BUF_SIZE,
13 rte_socket_id());
14
15 if (mbuf_pool == NULL) {
16 rte_exit(EXIT_FAILURE,
17 "Could not create mbuf pool\n");
18 }

第 7 行：声明 mempool 指针，用来保存创建结果。
第 8 行：池名称用于 DPDK 内部查找和调试，同一进程中应保持唯一。
第 9 行：池中创建 NUM_MBUFS 个 mbuf 对象。
第 10 行：per-lcore cache 大小设为 0，逻辑简单，但性能实验中通常会选择合适缓存值。
第 11 行：每个 mbuf 不添加额外的应用私有区。
第 12 行：每个 mbuf 的数据缓冲区使用 DPDK 默认大小。
第 13 行：在当前执行 lcore 所在 NUMA Socket 分配池内存。
第 15～18 行：创建失败时不能继续配置 RX Queue。

11. 初始化网口并进入无限循环

19 ustack_init_port(mbuf_pool);
20
21 while (1) {
22 struct rte_mbuf *mbufs[BURST_SIZE] = {0};

第 19 行：把刚创建的 mempool 交给端口初始化函数，并建立 RX/TX Queue。
第 21 行：DPDK 常使用轮询模式，所以程序持续运行，不断检查 RX Queue。
第 22 行：在栈上创建一个数组，用来保存本次批量取回的 mbuf 指针。数组中不是报文数据本身，而是指向 mbuf 的指针。
= {0} 会把所有数组元素初始化为空指针；虽然接下来有效元素会被 API 覆盖，但初始化有利于调试。

12. 从 RX Queue 批量取包

23 uint16_t num_recvd =
24 rte_eth_rx_burst(global_portid,
25 0,
26 mbufs,
27 BURST_SIZE);
28
29 for (uint16_t i = 0; i < num_recvd; i++) {
30 struct rte_mbuf *rx_mbuf = mbufs[i];
31 uint32_t frame_len = rte_pktmbuf_pkt_len(rx_mbuf);

第 23～27 行：从 0 号端口、0 号 RX Queue 最多取 BURST_SIZE 个包。
返回 0 表示当前没有包，不是错误；while 会立即进入下一轮轮询。
返回值不会大于传入的 BURST_SIZE，所以原草稿中的 num_recvd > BURST_SIZE 棬查没有实际意义。
第 29 行：只遍历 API 确认有效的前 num_recvd 个元素。
第 30 行：为当前包取一个更易读的局部变量名。
第 31 行：读取整个包的实际字节数，后面定位 Header 前必须先检查长度。

13. 检查并定位 Ethernet Header

32 if (frame_len < sizeof(struct rte_ether_hdr)) {
33 rte_pktmbuf_free(rx_mbuf);
34 continue;
35 }
36
37 struct rte_ether_hdr *ethhdr =
38 rte_pktmbuf_mtod(rx_mbuf,
39 struct rte_ether_hdr *);
40
41 if (ethhdr->ether_type !=
42 rte_cpu_to_be_16(RTE_ETHER_TYPE_IPV4)) {
43 rte_pktmbuf_free(rx_mbuf);
44 continue;
45 }

第 32 行：报文连一个 Ethernet Header 都放不下时，不能继续强制转换并读取字段。
第 33 行：当前 mbuf 没有交给 TX，应用仍拥有它，因此需要释放。
第 34 行：跳过当前包，继续处理 Burst 中的下一个包。
第 37～39 行：rte_pktmbuf_mtod() 取得 mbuf 数据起始地址，并转换为 Ethernet Header 指针。
第 41～42 行：EtherType 等于 IPv4 才进入本实验的 IPv4 处理路径。
第 43～44 行：非 IPv4 包当前不处理，但仍必须释放 mbuf。

rte_pktmbuf_mtod() 只是做地址取得与类型转换，不会自动校验数据是否足够长，所以第 32 行不能省略。

14. 检查并定位 IPv4 Header

46 uint32_t min_ipv4_frame =
47 sizeof(struct rte_ether_hdr) +
48 sizeof(struct rte_ipv4_hdr);
49
50 if (frame_len < min_ipv4_frame) {
51 rte_pktmbuf_free(rx_mbuf);
52 continue;
53 }
54
55 struct rte_ipv4_hdr *iphdr =
56 rte_pktmbuf_mtod_offset(
57 rx_mbuf,
58 struct rte_ipv4_hdr *,
59 sizeof(struct rte_ether_hdr));
60
61 uint16_t ip_hdr_len =
62 (iphdr->version_ihl & 0x0f) * 4;
63
64 if (ip_hdr_len < sizeof(struct rte_ipv4_hdr) ||
65 frame_len < sizeof(struct rte_ether_hdr) +
66 ip_hdr_len) {
67 rte_pktmbuf_free(rx_mbuf);
68 continue;
69 }

第 46～48 行：计算 Ethernet Header 加最小 IPv4 Header 需要多少字节。
第 50～53 行：实际帧比这个值短时直接丢弃。
第 55～59 行：从 mbuf 数据起点偏移一个 Ethernet Header，取得 IPv4 Header 地址。
第 61～62 行：IPv4 IHL 位于 version_ihl 的低 4 位，单位是 4 字节。
第 64 行：IHL 小于 20 字节不合法。
第 65～66 行：实际帧必须能容纳 IHL 声明的完整 IPv4 Header。
第 67～68 行：格式不合法就释放并跳过。

当前示例默认 Header 位于 mbuf 的第一个连续数据段。若接收的是 multi-segment mbuf，直接取指针前还要确保所需字节连续，或使用 rte_pktmbuf_read()。

15. 根据 IHL 定位 UDP 或 TCP Header

70 uint8_t *l4 = (uint8_t *)iphdr + ip_hdr_len;
71
72 if (iphdr->next_proto_id == IPPROTO_UDP) {
73 if (frame_len <
74 sizeof(struct rte_ether_hdr) + ip_hdr_len +
75 sizeof(struct rte_udp_hdr)) {
76 rte_pktmbuf_free(rx_mbuf);
77 continue;
78 }
79
80 struct rte_udp_hdr *udphdr =
81 (struct rte_udp_hdr *)l4;
82 /* 进入 UDP Echo 处理 */
83
84 } else if (iphdr->next_proto_id == IPPROTO_TCP) {
85 if (frame_len <
86 sizeof(struct rte_ether_hdr) + ip_hdr_len +
87 sizeof(struct rte_tcp_hdr)) {
88 rte_pktmbuf_free(rx_mbuf);
89 continue;
90 }
91
92 struct rte_tcp_hdr *tcphdr =
93 (struct rte_tcp_hdr *)l4;
94 /* 进入 TCP 状态处理 */
95 }

第 70 行：不能总用 iphdr + 1 找四层 Header，因为 IPv4 可能带 Options；这里使用前面算出的真实 IHL。
第 72 行：next_proto_id 表示 IPv4 payload 使用哪种上层协议。
第 73～78 行：读取 UDP Header 之前，确认帧中至少有 8 字节 UDP Header。
第 80～81 行：把四层起点解释为 UDP Header。
第 84 行：如果不是 UDP，再检查是否为 TCP。
第 85～90 行：TCP 基础 Header 至少 20 字节，读取前同样检查实际长度。
第 92～93 行：把四层起点解释为 TCP Header。

到这里，程序才安全地取得 UDP 或 TCP Header。下面开始解释各协议的响应构造。

16. 收到 UDP 包后保存响应方向

01 if (iphdr->next_proto_id == IPPROTO_UDP) {
02 struct rte_udp_hdr *udphdr =
03 (struct rte_udp_hdr *)((uint8_t *)iphdr + ip_hdr_len);
04
05 rte_memcpy(global_smac,
06 ethhdr->dst_addr.addr_bytes,
07 RTE_ETHER_ADDR_LEN);
08 rte_memcpy(global_dmac,
09 ethhdr->src_addr.addr_bytes,
10 RTE_ETHER_ADDR_LEN);
11
12 global_sip = iphdr->dst_addr;
13 global_dip = iphdr->src_addr;
14 global_sport = udphdr->dst_port;
15 global_dport = udphdr->src_port;

第 1 行：只进入 UDP 分支。
第 2～3 行：把 IPv4 Header 起点加上刚计算出的 ip_hdr_len，定位 UDP Header；这样 IPv4 带 Options 时也不会找错位置。
第 5～7 行：请求包的目的 MAC 是本机 MAC，它应成为响应包的源 MAC。
第 8～10 行：请求包的源 MAC 是客户端 MAC，它应成为响应包的目的 MAC。
第 12～13 行：用直接赋值对调 IPv4 地址，避免误写复制长度。
第 14～15 行：对调 UDP 端口，使响应发回请求客户端。

这里的“对调”不是在原协议头中原地交换，而是先保存响应方向，稍后写入一个新的 TX mbuf。

17. 计算收到的 UDP 数据长度

16 uint16_t udp_len =
17 rte_be_to_cpu_16(udphdr->dgram_len);
18
19 if (udp_len < sizeof(struct rte_udp_hdr)) {
20 rte_pktmbuf_free(mbufs[i]);
21 continue;
22 }
23
24 uint16_t payload_len =
25 udp_len - sizeof(struct rte_udp_hdr);
26
27 uint8_t *payload = (uint8_t *)(udphdr + 1);
28 uint16_t ip_len =
29 sizeof(struct rte_ipv4_hdr) + udp_len;
30 uint16_t frame_len =
31 sizeof(struct rte_ether_hdr) + ip_len;

第 16～17 行：从 UDP Header 读取总长度，并转换为主机字节序，方便做减法和比较。
第 19 行：合法 UDP 长度至少为 8 字节，即一个 UDP Header。
第 20 行：这个示例假定当前分支负责释放收到的 mbuf。若外层统一释放，此处不能再次释放。
第 24～25 行：UDP payload 长度等于 UDP 总长度减去 UDP Header。
第 27 行：udphdr + 1 跨过一个完整的 UDP Header，指向 payload 起始位置。
第 28～29 行：IPv4 总长度由 IPv4 Header 和整个 UDP 数据报组成。
第 30～31 行：完整帧长度再加上 Ethernet Header。

在使用 UDP Header 声明的长度前，还必须确认它没有超过 IPv4 total_length 和 RX mbuf 的实际数据范围。前面的 Header 存在性检查只能证明 UDP Header 本身可读，不能证明对方声明的整个 payload 都真实存在。

18. 为响应包分配 TX mbuf

32 struct rte_mbuf *tx_mbuf =
33 rte_pktmbuf_alloc(mbuf_pool);
34
35 if (tx_mbuf == NULL) {
36 printf("rte_pktmbuf_alloc failed\n");
37 continue;
38 }
39
40 uint8_t *frame =
41 rte_pktmbuf_append(tx_mbuf, frame_len);
42
43 if (frame == NULL) {
44 rte_pktmbuf_free(tx_mbuf);
45 continue;
46 }

第 32～33 行：从创建好的 mempool 中取一个 mbuf，用于保存响应包。
第 35 行：mempool 耗尽时分配会失败，不能继续解引用空指针。
第 40～41 行：在 mbuf 尾部追加 frame_len 字节，并取得可写的数据地址。
第 41 行：rte_pktmbuf_append() 同时更新 data_len 和 pkt_len，比手工写两个长度字段更安全。
第 43～45 行：如果 mbuf 的可用尾部空间不足，释放刚分配的 mbuf。

这里选择“新建 TX mbuf”，优点是 RX 包保持不变，逻辑直观。后续追求性能时，也可以在满足可写、连续性和所有权条件的前提下原地改写 RX mbuf 再发送。

19. 逐层写入 UDP 响应包

47 struct rte_ether_hdr *eth =
48 (struct rte_ether_hdr *)frame;
49
50 rte_memcpy(eth->dst_addr.addr_bytes,
51 global_dmac,
52 RTE_ETHER_ADDR_LEN);
53 rte_memcpy(eth->src_addr.addr_bytes,
54 global_smac,
55 RTE_ETHER_ADDR_LEN);
56 eth->ether_type =
57 rte_cpu_to_be_16(RTE_ETHER_TYPE_IPV4);

第 47～48 行：把帧首地址解释成 Ethernet Header。
第 50～52 行：写目的 MAC，即原请求的源 MAC。
第 53～55 行：写源 MAC，即原请求的目的 MAC。
第 56～57 行：声明 Ethernet payload 是 IPv4。EtherType 是 16 位字段，要使用网络字节序。

接着写 IPv4 Header：

58 struct rte_ipv4_hdr *ip =
59 (struct rte_ipv4_hdr *)(eth + 1);
60 *ip = (struct rte_ipv4_hdr){0};
61
62 ip->version_ihl = RTE_IPV4_VHL_DEF;
63 ip->total_length = rte_cpu_to_be_16(ip_len);
64 ip->time_to_live = 64;
65 ip->next_proto_id = IPPROTO_UDP;
66 ip->src_addr = global_sip;
67 ip->dst_addr = global_dip;
68 ip->hdr_checksum = 0;
69 ip->hdr_checksum = rte_ipv4_cksum(ip);

第 58～59 行：eth + 1 跨过 Ethernet Header，得到 IPv4 Header 地址。
第 60 行：先把整个 Header 清零，避免未初始化字段影响报文和 checksum。
第 62 行：写入 IPv4 与 20 字节基础头长度。
第 63 行：IPv4 总长度不包含 Ethernet Header。
第 64 行：TTL 设置为 64。
第 65 行：声明上层协议为 UDP。
第 66～67 行：写入已经对调好的源/目的 IPv4 地址。
第 68 行：计算 IPv4 Header checksum 前先把 checksum 字段清零。
第 69 行：计算并写入新的 IPv4 Header checksum。

最后写 UDP Header 和 payload：

70 struct rte_udp_hdr *udp =
71 (struct rte_udp_hdr *)(ip + 1);
72
73 udp->src_port = global_sport;
74 udp->dst_port = global_dport;
75 udp->dgram_len = rte_cpu_to_be_16(udp_len);
76 udp->dgram_cksum = 0;
77
78 rte_memcpy(udp + 1, payload, payload_len);
79 udp->dgram_cksum =
80 rte_ipv4_udptcp_cksum(ip, udp);

第 70～71 行：基础 IPv4 Header 后紧跟 UDP Header。
第 73～74 行：写入对调后的端口；它们已经是网络字节序。
第 75 行：UDP 长度包括 UDP Header 和 UDP payload。
第 76 行：计算 UDP checksum 前先清零。
第 78 行：只复制 payload_len，不能复制包含 UDP Header 的 udp_len。
第 79～80 行：使用 IPv4 伪首部、UDP Header 和 payload 计算 UDP checksum。

20. 发送 UDP 响应并处理所有权

81 uint16_t nb_tx =
82 rte_eth_tx_burst(global_portid,
83 0,
84 &tx_mbuf,
85 1);
86
87 if (nb_tx == 0) {
88 rte_pktmbuf_free(tx_mbuf);
89 }
90 }

第 81～85 行：请求 0 号 TX Queue 发送一个 mbuf。
第 84 行：参数必须是 &tx_mbuf，即“mbuf 指针数组的首地址”。只有一个包时，单个指针的地址可以充当长度为 1 的数组。
第 85 行：本次希望发送 1 个包。
第 87 行：若返回 0，说明驱动没有接管这个 mbuf。
第 88 行：发送失败时所有权仍属于应用，所以由应用释放。
若返回 1，不能在这里释放；后续由驱动在发送完成后回收。

外层还必须释放没有转交给 TX 的 RX mbuf。若选择原地改写 RX mbuf 并成功发送，则该 RX mbuf 的所有权已经交给 TX，不能再按接收包释放一次。

21. TCP 状态与每条连接需要保存的数据

草稿中使用一个全局状态：

01 uint8_t tcp_status = USTACK_TCP_STATUS_LISTEN;
02 uint32_t global_seqnum;
03 uint32_t global_acknum;
04 uint32_t server_isn = 12345;

第 1 行：服务端从监听状态开始。
第 2 行：保存收到报文的 SEQ，转换为主机字节序后便于加减。
第 3 行：保存收到报文的 ACK。
第 4 行：教学代码使用固定初始序列号；真实实现应生成合适的 ISN。

这些字段实际上都属于一条 TCP 连接。支持多个客户端时，应把它们放入连接控制块：

struct tcp_control_block {
 uint32_t local_ip;
 uint32_t remote_ip;
 uint16_t local_port;
 uint16_t remote_port;
 uint32_t snd_nxt;
 uint32_t rcv_nxt;
 ustack_tcp_status_t state;
};

前四项构成连接四元组，收到 TCP 包后用四元组查找对应状态，而不是共享一个全局 tcp_status。

22. 收到 TCP 包并读取关键字段

01 } else if (iphdr->next_proto_id == IPPROTO_TCP) {
02 struct rte_tcp_hdr *tcphdr =
03 (struct rte_tcp_hdr *)(iphdr + 1);
04
05 global_sip = iphdr->dst_addr;
06 global_dip = iphdr->src_addr;
07 global_sport = tcphdr->dst_port;
08 global_dport = tcphdr->src_port;
09
10 uint8_t flags = tcphdr->tcp_flags;
11 uint32_t peer_seq =
12 rte_be_to_cpu_32(tcphdr->sent_seq);
13 uint32_t peer_ack =
14 rte_be_to_cpu_32(tcphdr->recv_ack);

第 1 行：进入 TCP 分支。
第 2～3 行：教学版本仍假设 IPv4 Header 固定为 20 字节。
第 5～8 行：对调 IP 和端口，准备构造服务端响应。
第 10 行：TCP Flags 只有一个字节，不需要字节序转换。
第 11～12 行：SEQ 是 32 位字段，转换为主机字节序后保存。
第 13～14 行：ACK 同样转换为主机字节序。

TCP 响应同样需要保存 MAC 方向：

rte_memcpy(global_smac,
 ethhdr->dst_addr.addr_bytes,
 RTE_ETHER_ADDR_LEN);
rte_memcpy(global_dmac,
 ethhdr->src_addr.addr_bytes,
 RTE_ETHER_ADDR_LEN);

第一段把收到包的目的 MAC 保存为响应源 MAC；第二段把收到包的源 MAC 保存为响应目的 MAC。

23. LISTEN 状态收到 SYN

15 if ((flags & RTE_TCP_SYN_FLAG) != 0 &&
16 tcp_status == USTACK_TCP_STATUS_LISTEN) {
17
18 uint32_t ack_to_peer = peer_seq + 1;
19 send_syn_ack(server_isn, ack_to_peer);
20 tcp_status = USTACK_TCP_STATUS_SYN_RCVD;
21 }

第 15 行：使用按位与检查 SYN 标志是否存在，因为一个 TCP 包可以同时带多个 Flags。
第 16 行：只有监听状态才把这个 SYN 当作新连接请求。
第 18 行：SYN 占用一个序列号，因此响应 ACK 为客户端 SEQ+1。
第 19 行：构造并发送 SYN | ACK 报文。
第 20 行：发送后进入 SYN_RCVD，等待三次握手的最后一个 ACK。

学习版还应继续改进：如果 SYN+ACK 实际没有成功进入 TX Queue，不能直接认为它已经发送；收到重复 SYN 时也应考虑重发 SYN+ACK。

24. 逐行构造 SYN+ACK

Ethernet 和 IPv4 Header 的写法与 UDP 响应相同，只需把 IP 上层协议及总长度改为 TCP：

01 uint16_t tcp_len = sizeof(struct rte_tcp_hdr);
02 uint16_t ip_len = sizeof(struct rte_ipv4_hdr) + tcp_len;
03 uint16_t frame_len = sizeof(struct rte_ether_hdr) + ip_len;
04
05 ip->total_length = rte_cpu_to_be_16(ip_len);
06 ip->next_proto_id = IPPROTO_TCP;
07 ip->hdr_checksum = 0;
08 ip->hdr_checksum = rte_ipv4_cksum(ip);
09
10 struct rte_tcp_hdr *tcp =
11 (struct rte_tcp_hdr *)(ip + 1);
12 *tcp = (struct rte_tcp_hdr){0};
13
14 tcp->src_port = global_sport;
15 tcp->dst_port = global_dport;
16 tcp->sent_seq = rte_cpu_to_be_32(server_isn);
17 tcp->recv_ack = rte_cpu_to_be_32(peer_seq + 1);
18 tcp->data_off =
19 (sizeof(struct rte_tcp_hdr) / sizeof(uint32_t)) << 4;
20 tcp->tcp_flags = RTE_TCP_SYN_FLAG | RTE_TCP_ACK_FLAG;
21 tcp->rx_win = rte_cpu_to_be_16(TCP_INIT_WINDOW);
22 tcp->cksum = 0;
23 tcp->cksum = rte_ipv4_udptcp_cksum(ip, tcp);

第 1 行：SYN+ACK 不带 payload，本例 TCP 段只有基础 TCP Header。
第 2～3 行：依次得到 IPv4 总长度与完整帧长度，用于 Header 和 mbuf。
第 5 行：IPv4 总长度包含 IPv4 Header 与 TCP Header，不含 Ethernet Header。
第 6 行：把 IPv4 上层协议改为 TCP。
第 7～8 行：写完影响 IPv4 Header 的字段后重新计算 Header checksum。
第 10～11 行：TCP Header 紧跟在基础 IPv4 Header 后面。
第 12 行：清零整个 TCP Header，避免窗口、紧急指针等字段含有随机值。
第 14～15 行：写入对调后的端口。
第 16 行：服务端第一次发送 SYN，SEQ 等于本端 ISN。
第 17 行：确认客户端的 SYN，所以 ACK 等于客户端 SEQ+1。
第 18～19 行：TCP Header 长度以 32 位字为单位，并放在 data_off 的高 4 位。
第 20 行：同时置位 SYN 与 ACK。
第 21 行：窗口是 16 位字段，要转换为网络字节序。
第 22～23 行：清零后计算覆盖 IPv4 伪首部和 TCP 段的 checksum。

完成 Header 后，仍要像 UDP 一样分配/扩展 mbuf、调用 rte_eth_tx_burst() 并处理未发送的 mbuf。

25. 验证三次握手最后一个 ACK

01 if ((flags & RTE_TCP_ACK_FLAG) != 0 &&
02 tcp_status == USTACK_TCP_STATUS_SYN_RCVD &&
03 peer_ack == server_isn + 1) {
04
05 tcp_status = USTACK_TCP_STATUS_ESTABLISHED;
06 printf("enter established\n");
07 }

第 1 行：检查 ACK 标志存在。
第 2 行：只有已经发送 SYN+ACK 的连接才能通过这个分支建立。
第 3 行：客户端必须确认服务端的 SYN；因为 SYN 占一个序列号，所以期望值是 server_isn + 1。
第 5 行：状态迁移到 ESTABLISHED。
第 6 行：打印日志，方便结合抓包确认状态变化时机。

草稿最初只检查“有 ACK 标志且当前是 SYN_RCVD”，没有验证 ACK 数值。补上第 3 行后，三次握手判断才更完整。

26. 计算 TCP payload，而不是只检查 PSH

01 uint16_t ip_hdr_len =
02 (iphdr->version_ihl & 0x0f) * 4;
03 uint16_t tcp_hdr_len =
04 (tcphdr->data_off >> 4) * 4;
05 uint16_t ip_total_len =
06 rte_be_to_cpu_16(iphdr->total_length);
07
08 if (ip_total_len < ip_hdr_len + tcp_hdr_len) {
09 continue;
10 }
11
12 uint16_t payload_len =
13 ip_total_len - ip_hdr_len - tcp_hdr_len;
14 uint8_t *payload =
15 (uint8_t *)tcphdr + tcp_hdr_len;
16
17 if (tcp_status == USTACK_TCP_STATUS_ESTABLISHED &&
18 payload_len > 0) {
19 printf("tcp data: %.*s\n",
20 (int)payload_len,
21 (char *)payload);
22 }

第 1～2 行：从 IHL 低 4 位得到 IPv4 Header 的 32 位字数量，再乘 4 得到字节数。
第 3～4 行：从 data_off 高 4 位得到 TCP Header 的字节数，因此 TCP Options 也会被正确跳过。
第 5～6 行：读取 IPv4 Header 声明的整个 IP 包长度。
第 8～10 行：总长度不能比两个 Header 相加还小，否则减法会发生无符号下溢。
第 12～13 行：用 IP 总长度减去两个 Header，得到 TCP payload 长度。
第 14～15 行：根据真实 TCP Header 长度定位 payload，而不是固定写 tcphdr + 1。
第 17 行：只有已建立连接才把数据交给应用层。
第 18 行：以实际 payload 长度判断是否有数据，不依赖 PSH 标志。
第 19～21 行：使用带长度的格式打印，避免把网络数据误当作以 \0 结尾的字符串。

收到数据后还应该回复 ACK：

ack_to_peer = peer_seq + payload_len;

如果该段带 SYN 或 FIN，还应为每个标志额外加 1。当前草稿尚未实现数据 ACK，因此还只是握手与数据解析原型。

27. RX mbuf 的最终释放位置

接收循环应为每个包建立唯一、清楚的释放路径。使用新 TX mbuf 构造响应时，可以在本轮处理结束后释放 RX mbuf：

for (uint16_t i = 0; i < num_recvd; i++) {
 bool rx_forwarded_to_tx = false;

 /* 解析并处理 mbufs[i] */

 if (!rx_forwarded_to_tx) {
 rte_pktmbuf_free(mbufs[i]);
 }
}

当前 UDP/TCP 示例新建了 tx_mbuf，所以原 mbufs[i] 没有转交给 TX，应由接收循环释放。草稿中缺少这一步，会导致 RX mbuf 持续泄漏，最终耗尽 mempool。

如果以后改为原地改写并发送 RX mbuf，则发送成功后应把 rx_forwarded_to_tx 设为 true，防止重复释放。

十四、怎样验证实现是否正确

建议按层验证，不要一上来同时调 UDP 和 TCP。

阶段一：只验证 TX Queue

网口成功配置一个 TX Queue；
rte_eth_tx_burst() 返回 1；
抓包能看到 DPDK 网卡发出的帧。

阶段二：验证 UDP Echo

请求和响应的 MAC、IP、Port 方向相反；
Echo payload 与请求完全一致；
IPv4 total_length、UDP dgram_len 正确；
Wireshark 未报告 IPv4/UDP checksum 错误；
连续发送大量数据时，mempool 可用数量没有持续下降。

若开启了 TX checksum offload，抓包点可能位于网卡真正计算 checksum 之前，抓包工具会显示“校验和错误”；需要结合 offload 配置和抓包位置判断，不能只看这一条提示。

阶段三：验证 TCP 握手

SYN 到达时，状态为 LISTEN；
SYN+ACK 的 ACK 等于客户端 SEQ+1；
客户端最终 ACK 等于服务端 SEQ+1；
只有 ACK 校验通过后才进入 ESTABLISHED；
发送 payload 后，能正确计算 TCP Header 长度和 payload 长度。

常用观察点：

源/目的 MAC
源/目的 IP
源/目的端口
EtherType / IP Protocol
IP total_length
UDP length 或 TCP data offset
TCP flags / seq / ack
checksum
rte_eth_tx_burst 返回值

十五、把实验抽象成 pktgen 发包工具

完成 UDP/TCP 编码后，可以把“回包程序”进一步抽象为一个简单的发包工具。命令行可以设计为：

./ustack-pktgen \
 --udp \
 --src-ip 192.168.1.10 \
 --dst-ip 192.168.1.20 \
 --src-port 10000 \
 --dst-port 20000 \
 --dst-mac 00:11:22:33:44:55 \
 --count 1000 \
 --payload "hello dpdk"

TCP 模式可改用 --tcp，并增加：

--flags syn|ack|psh|fin|rst
--seq N
--ack N
--window N

程序结构可以拆成：

参数解析
 ├── 公共参数：源/目的 MAC、IP、数量、长度
 ├── UDP 参数：源/目的端口、payload
 └── TCP 参数：flags、seq、ack、window
 ↓
统一 packet description
 ↓
encode_ether + encode_ipv4
 ↓
encode_udp 或 encode_tcp
 ↓
burst send + 统计

这个小工具的价值在于：

为协议栈、网关、防火墙等项目构造可重复的测试流量；
精确控制五元组、TCP Flags、SEQ/ACK 等字段；
练习 DPDK 多包批量构造和发送；
后续可增加速率限制、不同包长、随机地址、时延与丢包统计。

在简历中应写清“实现了哪些能力”和“测得什么结果”，不要泛写成“实现 TCP/IP 协议栈”。例如：

基于 DPDK 实现用户态 UDP Echo 与最小 TCP 服务端握手原型，完成 Ethernet/IPv4/UDP/TCP 报文构造、校验和计算、TCP 状态迁移及 mbuf 批量收发；进一步抽象可配置五元组与报文数量的流量生成工具，用于协议功能测试。

若有实测结果，可以继续补充包长、队列数、CPU 核数、吞吐量和丢包率。

十六、本篇回顾清单

读完代码后，应能不看资料回答这些问题：

为什么配置了 RX Queue 仍不能发送数据？
为什么把收到的 mbuf 原样送进 TX Queue 不构成 Echo？
UDP Echo 需要交换哪三层的哪些字段？
Ethernet FCS 与 IPv4/UDP/TCP checksum 分别由谁处理？
ip->total_length、udp->dgram_len、mbuf->pkt_len 各自包含什么？
为什么 payload 复制长度不能直接使用 UDP dgram_len？
rte_eth_tx_burst() 返回 0 时，mbuf 应由谁释放？
SYN 和 FIN 为什么会各占用一个序列号？
为什么 TCP Header 没有类似 UDP 的长度字段？
为什么仅凭 PSH 标志不能判断 TCP 包一定携带数据？
为什么一个全局 tcp_status 无法支持多个 TCP 连接？
当前原型距离完整 TCP 协议栈还缺哪些关键能力？

十七、总结

本篇真正跨过的一步，是从“解析别人构造好的报文”走向“自己构造一个能被对端接受的报文”。

UDP Echo 说明了发包的基本方法：

分配 mbuf → 填各层 Header → 复制 payload
→ 写网络字节序 → 计算 checksum → 交给 TX Queue

TCP 实验则进一步说明：协议栈不只是报文格式的集合，还必须维护状态和时序。能生成 SYN+ACK 只是起点；要成为完整 TCP 实现，还需要可靠传输、序列号校验、超时重传、窗口管理、连接表和连接关闭等机制。

从工程实践看，本次代码最值得记住的不是某个固定 API，而是四条原则：

每一层的长度边界必须算清楚；
所有多字节协议字段都要明确主机/网络字节序；
checksum 计算前先清零，并明确由软件还是硬件负责；
任何 mbuf 都必须有清晰的所有权和释放路径。

DPDK 用户态协议栈设计与实现

Sat, 15 Aug 2026 00:00:00 +0800

学习目标：理解网卡、网卡驱动、TCP/IP 协议栈、POSIX Socket API 与应用程序之间的关系；搭建 DPDK 环境；使用 DPDK 收取以太网帧；逐步解析 Ethernet、IPv4、UDP、TCP；最终理解用户态协议栈需要补齐哪些能力。

一、先建立完整的网络数据路径

可以把网络程序拆成五个逻辑模块：

1. 网卡 NIC
 ↕
2. 网卡驱动 Driver
 ↕
3. TCP/IP 协议栈
 ↕
4. POSIX Socket API：socket / bind / listen / accept / recv / send
 ↕
5. Application：Redis / Nginx / 自己编写的服务器

接收数据时，数据总体从左向右、从上向下流动；发送数据时方向相反。

不过，必须区分下面两条不同的数据路径。

1. Linux 内核协议栈路径

物理网络
 → 网卡
 → Linux 内核网卡驱动
 → sk_buff
 → 内核 Ethernet/IP/TCP/UDP 协议栈
 → Socket 接收缓冲区
 → recv()/read()
 → 应用程序

应用程序使用的是 Linux 已经实现好的协议栈。Redis、Nginx 默认走的就是这条路径。

2. DPDK 用户态路径

物理网络
 → 网卡
 → VFIO/UIO + DPDK PMD 用户态驱动
 → RX Descriptor Ring
 → rte_mbuf
 → 自己实现或引入的用户态协议栈
 → 自己实现的 Socket/POSIX 兼容层
 → 应用程序

网卡绑定给 DPDK 使用的驱动后，该端口的普通数据收发路径通常绕过 Linux 内核网卡驱动和内核 TCP/IP 协议栈。DPDK 负责高速收发原始数据包，但 DPDK 本身不是 TCP/IP 协议栈。

重要纠错：不能把 DPDK 主路径理解成“网卡 → DPDK → 内核驱动 → 内核 TCP/IP”。正常的 DPDK 用户态收包路径绕过内核协议栈。只有主动使用 KNI、TAP、virtio-user 等机制时，才会把选定的数据包重新送入内核。

二、网卡是什么

1. 网卡的基本职责

网卡（NIC，Network Interface Card）连接计算机和网络介质，主要完成：

接收和发送物理信号；
完成物理层编码、解码、时钟恢复等工作；
识别和生成以太网帧；
校验帧的 FCS；
按配置进行 MAC 地址过滤、VLAN 处理；
通过 DMA 在网卡和主机内存之间搬运数据；
一些网卡还能完成 checksum、TSO、LRO、RSS 等硬件卸载。

“网卡把模拟信号通过 AD/DA 转换为 0 和 1”可以帮助入门理解，但并不完全准确。现代以太网 PHY 会进行复杂的线路编码、调制、均衡和信号恢复，不能简单等同于普通 ADC/DAC。

2. 网卡属于哪一层

网卡不是完全独立于分层模型之外。通常可以这样理解：

PHY 部分主要工作在物理层；
MAC 部分主要工作在数据链路层；
checksum、TSO、RSS 等卸载能力会辅助更高层处理。

因此，说网卡“主要横跨物理层和数据链路层”更准确。

3. DMA：网卡如何把数据交给内存

网卡不会要求 CPU 一个字节一个字节地读取数据。典型过程如下：

驱动在内存中准备一组 RX 描述符和数据缓冲区；
驱动把这些内存地址告诉网卡；
网卡收到数据后，通过 DMA 直接把数据写入内存缓冲区；
网卡更新 RX 描述符，标记该数据包已经完成；
CPU 再处理描述符所指向的数据。

这里的 RX 描述符通常按环形结构组织，所以常称为 RX Ring 或 Descriptor Ring。

三、网卡驱动做什么

网卡驱动是操作系统或 DPDK 与具体网卡硬件之间的适配层。它通常负责：

根据 PCI Vendor ID / Device ID 识别硬件；
初始化网卡寄存器；
配置 MAC、MTU、收发队列和硬件卸载；
分配 RX/TX Descriptor Ring；
建立 DMA 映射；
启停网卡；
处理链路状态和错误；
在中断模式或轮询模式下回收、提交数据包。

Linux 内核中有统一的网络设备框架，e1000、ixgbe、i40e、mlx5、vmxnet3 等具体驱动在这个框架下实现。DPDK 则提供 PMD（Poll Mode Driver），让用户态程序通过轮询直接与网卡队列交互。

1. 中断模式与轮询模式

传统内核路径通常结合中断和 NAPI 轮询：

流量较低时，网卡通过中断通知 CPU；
流量较高时，NAPI 暂时关闭频繁中断，改用批量轮询；
这样可以避免“中断风暴”。

DPDK 的典型方式是 Poll Mode：

rte_eth_rx_burst(port_id, queue_id, mbufs, BURST_SIZE);

线程不断轮询指定的端口和队列，避免中断、调度和上下文切换开销。代价是即使没有数据，轮询线程也可能持续占用一个 CPU 核。

2. 多队列网卡

多队列网卡拥有多个 RX/TX 队列。其价值在于：

不同队列可以由不同 CPU 核或线程独立处理；
减少多个核心竞争同一个队列锁；
利用 RSS 把不同网络流分散到多个 RX 队列；
提升并行处理能力和总体吞吐量。

常见绑定关系是：

RX Queue 0 → lcore 1
RX Queue 1 → lcore 2
RX Queue 2 → lcore 3
RX Queue 3 → lcore 4

RSS 通常根据源/目的 IP、源/目的端口、协议号计算哈希，将同一个流稳定地送到同一队列，避免同一 TCP 流的数据包在多个核心间乱序处理。

重要纠错：多队列能显著提高并行性，但“不是多队列网卡就一定无法绑定 DPDK”并不准确。单队列设备也可能被支持，只是扩展能力差。能否绑定和运行取决于设备、PMD、IOMMU、VFIO/UIO 以及虚拟化环境等条件。

3. 虚拟机中的 vmxnet3

VMware 中可以在 .vmx 文件中指定：

ethernet0.virtualDev = "vmxnet3"
ethernet0.wakeOnPcktRcv = "TRUE"

vmxnet3 是 VMware 的半虚拟化高性能网卡，通常比模拟的 e1000 拥有更好的性能和多队列能力。修改配置前应关闭虚拟机，并确认实际使用的 ethernet0、ethernet1 与目标 MAC 地址相匹配。

四、sk_buff、rte_mbuf 与 Ring

1. Linux 的 sk_buff

Linux 内核用 struct sk_buff 描述网络包。它不是简单地把所有协议头复制一遍，而是保存：

数据缓冲区的位置；
当前数据起点和末尾；
MAC、网络层和传输层头的位置；
数据包长度；
所属设备；
checksum、VLAN、路由等元数据；
链表等组织信息。

协议层之间传递的通常是 sk_buff 指针。各层通过移动或记录头部位置来解析数据，而不是每经过一层就复制整个包。

2. 海量 sk_buff 如何组织

“每包一个 sk_buff，海量包如何组织”不能只用一种数据结构回答。不同阶段使用不同结构：

网卡收发描述符：环形队列 Ring；
NAPI 待处理对象：调度列表；
Socket 接收队列：链表/队列形式的 skb queue；
TCP 乱序数据：红黑树等结构；
TCP 重传数据：按发送顺序管理的队列/树；
内存对象分配：slab/slub 缓存。

所以，常用答案是“以 Ring 和各种队列为主，根据查找、排序、重传等需求再使用树结构”。

3. DPDK 的 rte_mbuf

rte_mbuf 与 sk_buff 的定位相似：都用来描述一个数据包及其元数据。DPDK 通常从预先创建的 mempool 中分配 mbuf，以减少频繁动态分配的开销。

mempool
 ├── rte_mbuf + data buffer
 ├── rte_mbuf + data buffer
 ├── rte_mbuf + data buffer
 └── ...

网卡通过 DMA 把数据写入 mbuf 对应的数据缓冲区。rte_eth_rx_burst() 返回的是已经装有数据的 mbuf 指针数组，因此 CPU 不需要再把整个数据包从内核复制到用户态。

这通常称为零拷贝或少拷贝设计，但严格来说仍然可能发生 DMA、缓存行传输、跨 NUMA 访问以及应用层复制，不能把“零拷贝”理解成整个系统完全没有任何数据移动。

五、协议栈是什么

协议栈是一组按层协作的协议实现。接收一个 UDP/IPv4 以太网帧时，可依次解析：

Ethernet Header
 → IPv4 Header
 → UDP Header
 → Application Payload

接收 TCP 时则是：

Ethernet Header
 → IPv4 Header
 → TCP Header
 → TCP Segment Payload

解析协议头只是用户态协议栈的第一步。一个真正可用的协议栈还需要实现 ARP、路由、校验和、分片重组、TCP 状态机、重传、拥塞控制、Socket 缓冲区等功能。

六、以太网帧解析

不考虑 VLAN 标签时，Ethernet II 头部固定为 14 字节：

0 5 6 11 12 13
+----------------+----------------+--------+
| 目的 MAC 6字节 | 源 MAC 6字节 | 类型 2 |
+----------------+----------------+--------+

常见 EtherType：

0x0800：IPv4；
0x0806：ARP；
0x86DD：IPv6；
0x8100：802.1Q VLAN。

DPDK 中对应：

struct rte_ether_hdr *ethhdr =
 rte_pktmbuf_mtod(mbufs[i], struct rte_ether_hdr *);

rte_pktmbuf_mtod() 的作用是把 mbuf 中的数据起始地址转换成指定类型的指针。它并没有复制以太网头，只是在同一段内存上按 struct rte_ether_hdr 的布局解释字节。

判断是否为 IPv4：

if (ethhdr->ether_type != rte_cpu_to_be_16(RTE_ETHER_TYPE_IPV4)) {
 continue;
}

网络协议字段通常采用大端字节序，所以要进行主机字节序与网络字节序转换。

VLAN 注意事项

代码直接把以太网头后的数据当作 IPv4，只适用于没有 VLAN 标签的帧。若 EtherType 为 0x8100，还要解析 4 字节 VLAN Header，然后才能找到真正的上层 EtherType。

七、IPv4 解析

IPv4 基础头部最少 20 字节，结构包括：

+---------+---------+-------------------+
|Version | IHL | DSCP/ECN | Length |
+---------+---------+-------------------+
| Identification | Flags/Fragment Offset|
+---------------------------------------+
| TTL | Protocol | Header Checksum |
+---------------------------------------+
| Source IPv4 Address |
+---------------------------------------+
| Destination IPv4 Address |
+---------------------------------------+
| Options（可选，IHL > 5 时存在） |
+---------------------------------------+

关键字段：

Version：IPv4 时为 4；
IHL：头部长度，以 4 字节为单位；最小值为 5，即 20 字节；
Total Length：整个 IPv4 数据报长度；
Fragment Offset / Flags：分片相关；
TTL：每经过一个路由器通常减 1；
Protocol：上层协议，UDP=17，TCP=6，ICMP=1；
Header Checksum：只校验 IPv4 头；
Source/Destination Address：源和目的 IPv4 地址。

原代码通过固定的 14 字节 Ethernet Header 偏移找到 IPv4 头：

struct rte_ipv4_hdr *iphdr = rte_pktmbuf_mtod_offset(
 mbufs[i], struct rte_ipv4_hdr *, sizeof(struct rte_ether_hdr));

判断 UDP：

if (iphdr->next_proto_id == IPPROTO_UDP) {

IPv4 解析必须检查的内容

健壮的实现至少应检查：

mbuf 中是否有完整的 Ethernet 和 IPv4 基础头；
IPv4 Version 是否为 4；
IHL 是否至少为 5；
包长度是否覆盖 IHL * 4；
Total Length 是否合理；
IPv4 Header Checksum 是否正确，或确认硬件已校验；
是否为分片；
再根据 Protocol 分发给 ICMP、UDP 或 TCP。

原代码使用 (iphdr + 1) 寻找 UDP 头，相当于默认 IPv4 头固定为 20 字节。若 IPv4 带 Options，IHL 会大于 5，UDP 头的真实起点应为 IP Header 起点 + IHL * 4。

八、UDP 解析

UDP 头固定为 8 字节：

+-------------------+-------------------+
| Source Port | Destination Port |
+-------------------+-------------------+
| UDP Length | UDP Checksum |
+-------------------+-------------------+
| Payload ... |
+---------------------------------------+

关键字段：

Source Port：源端口；
Destination Port：目的端口；
Length：UDP 头加 Payload 的总长度，最小为 8；
Checksum：覆盖伪首部、UDP 头和 UDP 数据。

原代码：

struct rte_udp_hdr *udphdr = (struct rte_udp_hdr *)(iphdr + 1);
printf("udp:%s\n ", (char *)(udphdr + 1));

第一行把 IPv4 基础头后的地址解释为 UDP Header；第二行把 UDP Header 后的数据解释为 C 字符串并打印。

为什么 `%s` 只适合当前演示

网络 Payload 不保证以 \0 结尾，而 %s 会持续读取，直到遇到 \0。因此实际代码必须：

根据 UDP Length 计算 Payload 长度；
确认长度没有超过 mbuf/IPv4 数据长度；
使用带长度的输出方式，例如 %.*s；
对二进制协议应使用十六进制打印，而不是字符串打印。

当前 Packet Sender 发送的是短 ASCII 文本，并且内存后面恰好出现零字节，所以演示中可能正常输出，但这不是安全的通用处理方法。

九、TCP 解析

TCP 头最少为 20 字节，可带 Options，最长可达 60 字节。

+-------------------+-------------------+
| Source Port | Destination Port |
+---------------------------------------+
| Sequence Number |
+---------------------------------------+
| Acknowledgment Number |
+------+----------+---------------------+
|Offset| Flags | Window |
+-----------------+---------------------+
| Checksum | Urgent Pointer |
+---------------------------------------+
| Options（可选） |
+---------------------------------------+
| Payload ... |
+---------------------------------------+

关键字段：

Sequence Number：本段第一个字节的序号；
Acknowledgment Number：期望收到的下一个序号；
Data Offset：TCP Header 长度，以 4 字节为单位；
Flags：SYN、ACK、FIN、RST、PSH、URG 等；
Window：接收窗口，参与流量控制；
Checksum：覆盖 IPv4/IPv6 伪首部、TCP 头和 TCP 数据。

只把 TCP Header 拆出来还不能叫“实现 TCP”。至少还需要：

四元组查找连接：源 IP、源端口、目的 IP、目的端口；
TCP 状态机；
三次握手和四次挥手；
序列号和 ACK；
乱序重组；
超时重传；
RTT/RTO 估计；
滑动窗口和流量控制；
拥塞控制；
TIME_WAIT 等定时器管理。

TCP 状态机简图

服务器：CLOSED → LISTEN → SYN_RECEIVED → ESTABLISHED
客户端：CLOSED → SYN_SENT → ESTABLISHED

主动关闭的一方：ESTABLISHED → FIN_WAIT_1 → FIN_WAIT_2 → TIME_WAIT → CLOSED
被动关闭的一方：ESTABLISHED → CLOSE_WAIT → LAST_ACK → CLOSED

十、POSIX Socket API 与用户态协议栈

POSIX API 是应用程序看到的接口：

socket()：创建 Socket；
bind()：绑定本地 IP 和端口；
listen()：把 TCP Socket 设为监听状态；
accept()：取出一个已经建立的 TCP 连接；
connect()：主动发起 TCP 连接；
recv()/read()：读取接收数据；
send()/write()：发送数据；
close()：关闭 Socket。

1. 内核中的关系

在 Linux 内核协议栈中，文件描述符 fd 会关联到内核 Socket 对象。TCP 连接还对应一个传输控制块，可广义称为 TCB，其中保存：

四元组；
TCP 状态；
序列号；
收发窗口；
重传队列；
接收队列；
定时器等。

recv(fd, ...) 不是简单地“直接读取 TCB 某个位置”，而是通过 fd 找到 Socket，再从该 Socket 的接收缓冲区读取已经按序整理好的字节。如果没有数据，调用可能阻塞，或者在非阻塞模式下返回 EAGAIN。

2. 用户态协议栈怎样提供 POSIX API

如果应用完全绕过内核协议栈，Linux 原生 recv() 不会自动读取 DPDK mbuf。需要增加适配层，常见方法包括：

修改应用，让它调用用户态协议栈自己的 API；
使用库替换或 LD_PRELOAD 截获 Socket 调用；
提供兼容 POSIX 的用户态 Socket 库；
通过事件通知机制实现类似 epoll 的接口。

用户态需要自己维护：

fd/table
 → socket object
 → UDP endpoint 或 TCP TCB
 → receive queue / send queue

对于 UDP，recvfrom() 通常从对应端口的报文队列取出一个 Datagram；对于 TCP，recv() 从已经重排并确认连续的字节流中读取数据。

十一、DPDK 是什么，以及为什么快

DPDK（Data Plane Development Kit）是一组用于高速数据包处理的库、驱动和工具。它的核心思想包括：

用户态 PMD 轮询网卡；
批量收发 Burst；
预分配 mempool/mbuf；
Hugepage；
CPU 亲和性和独占核心；
NUMA 感知；
无锁 Ring；
硬件多队列与 RSS；
Prefetch 和缓存友好布局；
减少中断、系统调用、上下文切换和数据复制。

DPDK 优化的核心指标

DPDK 不只是“处理大包、提高吞吐量”。更准确地说，它常用于提高：

每秒处理的数据包数 PPS，尤其是大量小包；
总吞吐量；
延迟的可预测性和尾延迟；
多核心扩展能力。

是否能提升 Redis/Nginx 性能，取决于瓶颈：

如果瓶颈在业务逻辑、锁、存储或单线程执行，只有 DPDK 不会神奇地提高 QPS；
如果瓶颈在内核网络路径、软中断、系统调用或数据复制，用户态网络方案可能改善 QPS 或延迟；
把现有 Redis/Nginx 接到 DPDK 上需要完整协议栈和兼容层，并非简单绑定网卡即可。

常见使用场景

防火墙、ACL、DPI；
路由器、交换机、网关；
负载均衡器；
5G/电信数据面；
虚拟交换机；
流媒体或报文转发；
流量采集与监控；
高性能存储网络的数据面。

数据备份和 RDMA 可能使用类似的大页、DMA、零拷贝、用户态驱动思想，但 DPDK 与 RDMA 是不同的技术体系，不能简单说“底层一定用 DPDK，应用层用 RDMA”。

可研究的用户态协议栈/数据面项目包括 mTCP、lwIP、F-Stack、VPP、Seastar networking、基于 BSD 协议栈移植的实现等。项目是否仍活跃、DPDK 版本是否兼容，需要按实际版本确认。

十二、VFIO、UIO、PCI、KNI 与 NUMA

1. PCI 地址

网卡通常是 PCIe 设备。可以使用：

lspci
lspci -nn
lspci -k

PCI 地址形如：

0000:1a:00.0

含义是：

domain:bus:device.function

2. VFIO 与 UIO

它们帮助用户态程序访问 PCI 设备资源：

UIO：较简单的通用用户态 I/O 框架；
VFIO：通常配合 IOMMU，隔离性和安全性更好，现代环境一般优先使用；
DPDK PMD：真正理解并操作具体网卡寄存器和队列的用户态驱动。

不能简单理解为 VFIO/UIO“截获 PCI 地址”；更准确地说，它们把设备资源安全地映射或暴露给用户态驱动，并管理中断、DMA/IOMMU 等能力。

3. KNI

KNI 曾用于在 DPDK 应用与 Linux 内核网络栈之间交换数据包。例如，把控制面流量送回内核处理。但它不是 DPDK 收包必须经过的组件，而且在较新的 DPDK 方案中通常会考虑 TAP、virtio-user 等替代路径。

4. NUMA

NUMA 是 Non-Uniform Memory Access，即非一致内存访问。多路 CPU 服务器中，每个 CPU Socket 通常拥有本地内存：

CPU Socket 0 ↔ Local Memory 0
CPU Socket 1 ↔ Local Memory 1

CPU 访问本地内存比跨 Socket 访问远端内存更快。因此应尽量做到：

网卡所在 NUMA Node；
轮询该网卡的 CPU 核；
mbuf mempool 所在内存；

三者位于同一个 NUMA Node。

代码中的 rte_eth_dev_socket_id() 用于查询设备所在 NUMA Socket，rte_socket_id() 返回当前 lcore 所在 Socket。二者不一定总是相同。

十三、Hugepage 大页

普通页通常为 4 KiB。Hugepage 常见规格为：

2 MiB；
1 GiB。

DPDK 使用大页主要是为了：

减少页表项数量；
降低 TLB Miss；
便于大块、稳定、可用于 DMA 的内存管理；
减少运行时内存分配的不确定性。

1. 示例 GRUB 配置

GRUB_CMDLINE_LINUX_DEFAULT="default_hugepagesz=2M hugepagesz=2M hugepages=1024"

这表示默认大页为 2 MiB，共预留 1024 页，即约 2 GiB 内存。虚拟机内存有限时，需要根据虚拟机总内存调整，不能机械照抄。

通常修改后还需要更新 GRUB 并重启，例如 Ubuntu/Debian：

sudo update-grub
sudo reboot

重启后验证：

grep -i huge /proc/meminfo

具体命令因发行版和 DPDK 版本而异。现代 DPDK 可能自动处理 hugetlbfs，也可以手动挂载。1 GiB 大页还依赖 CPU 支持，并通常需要在启动参数中预留。

2. Hugepage 不直接提升网卡物理转换速度

Hugepage 优化的是主机内存管理、TLB 和 DMA 缓冲区访问，并不会让网卡的光电信号转换本身更快。它提升的是数据包在 CPU/内存数据面中的处理效率和稳定性。

十四、VMware 三种网络模式

1. Bridged（桥接）

虚拟机像局域网中的独立主机：

物理局域网
 ├── Windows/macOS 宿主机：172.26.185.5
 └── 虚拟机：172.26.185.250

虚拟机通常与宿主机处于同一二层网络，可从局域网 DHCP 获取地址，或配置同网段静态地址。桥接绑定到某个宿主机物理接口时，该接口断开可能影响虚拟机网络。

“复制物理网络连接状态”之类的选项，通常让虚拟网卡随宿主机物理接口的连接/断开状态变化，适合笔记本在 Wi-Fi、有线网络之间切换的场景。不同 VMware 产品中的名称和细节会略有不同。

2. NAT

VMware 在宿主机上创建虚拟子网，虚拟机通过宿主机做 NAT 访问外网：

虚拟机 → VMware 虚拟网关/NAT → 宿主机 → 外网

外部设备通常不能直接主动访问虚拟机，除非做端口映射或额外配置。

3. Host-only（仅主机）

虚拟机主要与宿主机及同一 Host-only 网络中的虚拟机通信，默认不能直接访问外网。它适合隔离实验环境。

“Host-only 一定可以 ping 通公网”是不对的；默认情况下它不能上网，除非宿主机另行开启路由/NAT。

十五、macOS Packet Sender 测试链路

已知 DPDK 端口信息：

MAC：00:0c:29:aa:5b:f0
PCI：0000:1a:00.0
PMD：net_vmxnet3
Link：up

宿主机：

IP：172.26.185.5
Mask：255.255.0.0
Interface：en0

ustack 测试地址：

172.26.185.250

1. 为什么需要静态 ARP

应用把 UDP 发往 172.26.185.250:8888 时，操作系统需要构造以太网帧。因为目标 IP 在同一子网，macOS 必须知道目标 IP 对应的 MAC 地址。

正常情况是：

macOS 广播 ARP Request：谁是 172.26.185.250？
ustack 单播 ARP Reply：172.26.185.250 是 00:0c:29:aa:5b:f0

当前 ustack 没有实现 ARP Reply，所以手工建立：

sudo arp -s 172.26.185.250 00:0c:29:aa:5b:f0
sudo arp -s 172.26.185.250 00:0c:29:aa:5b:f0 ifscope en0

验证：

arp -n 172.26.185.250

2. Packet Sender 配置

Address：172.26.185.250
Port：8888
Protocol：UDP
ASCII：hello dpdk

完整路径：

Packet Sender
 → macOS UDP/IP 处理
 → 静态 ARP 表查到目标 MAC
 → macOS en0
 → VMware Fusion 桥接
 → vmxnet3 虚拟网卡
 → DPDK port 0 / RX queue 0
 → rte_eth_rx_burst()
 → Ethernet / IPv4 / UDP 解析
 → 打印 hello dpdk

看到：

udp:hello dpdk

说明至少以下环节已经连通：

macOS 到 Fusion 桥接网络；
目标 MAC 投递；
vmxnet3 链路；
DPDK 端口初始化；
RX Queue 0 收包；
当前测试报文的 Ethernet/IPv4/UDP 基础解析。

但它还不能单独证明 checksum、分片、VLAN、IP Options、异常长度处理等已经正确实现。

十六、DPDK 环境搭建思路

老版本 DPDK 常使用 dpdk-setup.sh、RTE_SDK 和 RTE_TARGET。典型含义是：

export RTE_SDK=/home/.../dpdk
export RTE_TARGET=...

RTE_SDK：DPDK 源码/SDK 根目录；
RTE_TARGET：旧版构建系统生成的目标目录名称。

native 一般表示按当前机器架构优化；linuxapp 是旧版目标名称的一部分；具体选项需要以所使用的旧版 DPDK 文档和脚本为准。

现代 DPDK 已主要使用 Meson + Ninja 构建，不再依赖旧式 make config、RTE_TARGET 流程：

meson setup build
ninja -C build

因此必须先确认教程使用的 DPDK 版本。不要把老教程里的菜单选项直接套到新版本。

通用搭建检查表

确认 CPU 架构、Linux 发行版和 DPDK 版本；
确认 vmxnet3/物理网卡被当前 DPDK PMD 支持；
配置 Hugepage；
若使用 VFIO，确认 IOMMU/VFIO 条件；
查看 PCI 地址和当前驱动；
将实验网卡绑定到合适驱动；
保留管理网卡，避免把 SSH 所依赖的唯一网卡绑定走；
用 testpmd 检查端口、队列、Link 和收包计数；
再运行自己的程序。

安全提示：绑定网卡前一定确认 PCI 地址。将正在承载 SSH 或默认路由的网卡绑定给 DPDK，会立即让普通 Linux 网络连接中断。

十七、原始代码（保持不变）

下面代码完全按原内容保留，没有修改：

#include<stdio.h>
#include<rte_eal.h>
#include<rte_ethdev.h>
#include<arpa/inet.h>

int global_portid=0;//网卡绑定id从0开始 发数据和收数据知道id就好
#define NUM_MBUFS 4096
#define BURST_SIZE 128
static const struct rte_eth_conf port_conf_default={
 .rxmode={.max_rx_pkt_len=RTE_ETHER_MAX_LEN}
};
static int ustack_init_port(struct rte_mempool *mbuf_pool){

 uint16_t nb_sys_ports=rte_eth_dev_count_avail();
 if(nb_sys_ports==0){
 rte_exit(EXIT_FAILURE,"No Supported eth found/n");
 } 
 //struct rte_eth_dev_info dev_info;
 //rte_eth_dev_info_get(global_portid，&dev_info);
 //绑定的网卡
 //现在有八个 队列 弄1 2 4 8 
 const int num_rx_queues =1;
 const int num_tx_queues =0;
 rte_eth_dev_configure(global_portid,num_rx_queues,num_tx_queues,&port_conf_default);
 
 if(rte_eth_rx_queue_setup(global_portid,0,128,rte_eth_dev_socket_id(global_portid),NULL,mbuf_pool)<0){
 //在0号网卡的0号队列开辟了RX队列 准备了128个mbuffer
 rte_exit(EXIT_FAILURE," Could not setup RX queue/n"); 
 }

 if (rte_eth_dev_start(global_portid)<0){//启动
 rte_exit(EXIT_FAILURE,"Could not start"); 
 }
 return 0;
}

int main(int argc,char *argv[]){

 if(rte_eal_init(argc,argv)<0){//初始化 检查网卡信息 配置 是否绑定
 rte_exit(EXIT_FAILURE,"Error with EAL init\n");
 }
 struct rte_mempool *mbuf_pool= rte_pktmbuf_pool_create("mbuf pool",NUM_MBUFS,0,0,RTE_MBUF_DEFAULT_BUF_SIZE,rte_socket_id());
 //接收数据放在mbuff
 //mbuffer分配在内存上的 rte_socket_id 就是当前使用哪块内存卡槽ID分配的
 if(mbuf_pool==NULL){
 rte_exit(EXIT_FAILURE,"Could not create mbuf pool\n");
 }

 ustack_init_port(mbuf_pool);

 //接收数据
 while(1){
 struct rte_mbuf *mbufs[BURST_SIZE]={0};
 uint16_t num_recvd= rte_eth_rx_burst(global_portid,0,mbufs,BURST_SIZE);
 if (num_recvd>BURST_SIZE){
 rte_exit(EXIT_FAILURE,"Error receiving from eth\n");
 }

 int i=0;
 for(i=0;i<num_recvd;i++){
 struct rte_ether_hdr *ethhdr=rte_pktmbuf_mtod(mbufs[i],struct rte_ether_hdr *);
 if(ethhdr->ether_type != rte_cpu_to_be_16(RTE_ETHER_TYPE_IPV4)){
 continue;
 }
 struct rte_ipv4_hdr *iphdr =rte_pktmbuf_mtod_offset(mbufs[i],struct rte_ipv4_hdr *,sizeof(struct rte_ether_hdr));
 if (iphdr->next_proto_id==IPPROTO_UDP){//两个以上都转
 struct rte_udp_hdr *udphdr =(struct rte_udp_hdr *)(iphdr+1);
 printf("udp:%s\n ",(char*)(udphdr+1));
 }
 }

 }
 printf("Hello dpdk\n");


}

十八、代码逐行对照理解

1. 头文件

#include<stdio.h>

引入标准输入输出声明，本程序用它调用 printf()。

#include<rte_eal.h>

引入 DPDK EAL 接口。EAL 是 Environment Abstraction Layer，负责 Hugepage、lcore、内存、PCI 设备等基础环境初始化，也声明了 rte_eal_init()、rte_exit() 等接口。

#include<rte_ethdev.h>

引入以太网设备抽象接口，包括端口配置、RX Queue 设置、设备启动和 Burst 收包。

#include<arpa/inet.h>

提供网络字节序、IP 地址转换等常用声明。当前代码中没有直接调用 htons()、ntohs() 等函数，但 IPPROTO_UDP 等定义可能通过相关系统头可见。实际项目通常还会显式包含 DPDK Ethernet/IP/UDP 头文件，具体取决于 DPDK 版本的包含关系。

2. 全局端口与常量

int global_portid=0;

选择 DPDK 逻辑端口 0。这里的 port id 是 DPDK 枚举后的端口编号，不等于 PCI 地址，也不一定等于 Linux 的 eth0。

#define NUM_MBUFS 4096

准备在 mempool 中创建 4096 个 mbuf。它们不仅供 128 个 RX 描述符使用，还要留给收包后尚未释放、缓存以及其他内部需求。

#define BURST_SIZE 128

每次调用 rte_eth_rx_burst()，最多希望取回 128 个包。实际返回值可以是 0 到 128。

3. 默认端口配置

static const struct rte_eth_conf port_conf_default={
 .rxmode={.max_rx_pkt_len=RTE_ETHER_MAX_LEN}
};

创建端口配置结构，把最大接收包长设为标准以太网最大长度对应的 DPDK 常量。

注意：DPDK 的结构体字段会随版本变化。某些新版本中 max_rx_pkt_len 的位置或用法已变化。如果发生编译错误，应首先对照当前版本 API，而不是认为网络原理有问题。

4. 端口初始化函数

static int ustack_init_port(struct rte_mempool *mbuf_pool){

定义只在本源文件使用的函数，参数是已经创建好的 mbuf 内存池。

uint16_t nb_sys_ports=rte_eth_dev_count_avail();

查询当前 EAL 环境中可用的 DPDK Ethernet 设备数量。nb 是 number 的常用缩写。它不是固定表示“绑定网口数量”，更准确地说是当前可用的 ethdev 数量。

if(nb_sys_ports==0){
 rte_exit(EXIT_FAILURE,"No Supported eth found/n");
}

如果没有设备，打印错误并退出。字符串中的 /n 是普通字符，不是换行符；真正的换行符写法是 \n。本笔记遵守要求，不修改原代码，只指出区别。

//struct rte_eth_dev_info dev_info;
//rte_eth_dev_info_get(global_portid，&dev_info);

这两行被注释，不会执行。设计意图是读取端口能力，比如最大队列数、RSS、offload 能力。第二行参数之间使用了中文逗号 ，，若取消注释需要注意它不能作为 C 语言逗号使用。

const int num_rx_queues =1;
const int num_tx_queues =0;

配置 1 个接收队列、0 个发送队列。此程序只收不发，所以 TX Queue 设为 0。若以后要回复 ARP、UDP 或 TCP，就必须配置 TX Queue。

rte_eth_dev_configure(global_portid,num_rx_queues,num_tx_queues,&port_conf_default);

配置端口的 RX/TX 队列数量和总体参数。函数有返回值，当前代码没有检查；健壮程序应检查是否小于 0。

if(rte_eth_rx_queue_setup(global_portid,0,128,
 rte_eth_dev_socket_id(global_portid),NULL,mbuf_pool)<0){

配置 RX Queue：

global_portid：端口 0；
0：RX Queue 0；
128：描述符数量；
rte_eth_dev_socket_id(...)：在网卡所在 NUMA Socket 分配队列资源；
NULL：使用默认 RX Queue 配置；
mbuf_pool：网卡收到的数据放入这个池提供的 mbuf。

注释“准备了 128 个 mbuffer”是便于理解的近似说法。准确说是请求建立 128 个 RX descriptors；描述符与 mbuf 的补充、占用和回收由 PMD 管理，mempool 总大小仍为 4096。

rte_exit(EXIT_FAILURE," Could not setup RX queue/n");

配置失败就退出。同样，/n 不会产生换行。

if (rte_eth_dev_start(global_portid)<0){
 rte_exit(EXIT_FAILURE,"Could not start");
}

启动端口。配置端口和队列只是准备工作，start 后网卡才进入正式收发状态。

return 0;

表示初始化成功。

5. main 与 EAL 初始化

int main(int argc,char *argv[]){

程序入口。DPDK 会先解析命令行中的 EAL 参数，应用自己的参数通常放在 -- 后面并根据 rte_eal_init() 的返回值调整。

if(rte_eal_init(argc,argv)<0){
 rte_exit(EXIT_FAILURE,"Error with EAL init\n");
}

初始化 DPDK 运行环境，涉及：

解析 EAL 参数；
发现 CPU lcore；
初始化 Hugepage 内存；
初始化内存管理；
探测并初始化设备和总线；
建立主从 lcore 等运行环境。

它不等于“自动保证所有网卡已经正确绑定”。绑定通常要在运行程序之前完成，EAL 负责发现当前可使用的设备。

6. 创建 mbuf pool

struct rte_mempool *mbuf_pool=
 rte_pktmbuf_pool_create("mbuf pool",NUM_MBUFS,0,0,
 RTE_MBUF_DEFAULT_BUF_SIZE,rte_socket_id());

参数逐个理解：

"mbuf pool"：内存池名称；
NUM_MBUFS：4096 个 mbuf；
第一个 0：每个 lcore 的 cache 数量为 0；
第二个 0：每个对象额外私有区域大小为 0；
RTE_MBUF_DEFAULT_BUF_SIZE：每个 mbuf 默认数据缓冲区大小；
rte_socket_id()：在当前运行核心所在 NUMA Socket 分配。

这里 rte_socket_id() 指 NUMA 节点编号，不是物理“内存卡槽 ID”。服务器硬件的 DIMM 插槽和 NUMA Node 不是同一个概念。

if(mbuf_pool==NULL){
 rte_exit(EXIT_FAILURE,"Could not create mbuf pool\n");
}

创建失败立即退出。可能原因包括 Hugepage 不足、名称冲突、socket 内存不够或参数不合法。

ustack_init_port(mbuf_pool);

用刚创建的内存池配置并启动端口。

7. 轮询收包

while(1){

进入无限循环。这是 PMD 轮询模型的核心，线程会持续询问 RX Queue 是否有包。

struct rte_mbuf *mbufs[BURST_SIZE]={0};

创建一个长度为 128 的指针数组。数组保存 rte_mbuf *，并不在栈上创建 128 个完整 mbuf。

uint16_t num_recvd=
 rte_eth_rx_burst(global_portid,0,mbufs,BURST_SIZE);

从端口 0、队列 0 最多取 128 个已经收到的包：

返回 0：当前没有包；
返回 1～128：实际取到的包数；
mbuf 指针写入 mbufs[0 ... num_recvd-1]。

rte_eth_rx_burst() 通常通过检查 RX descriptors 批量完成工作，不是每次都触发系统调用。

if (num_recvd>BURST_SIZE){
 rte_exit(EXIT_FAILURE,"Error receiving from eth\n");
}

按 API 契约，返回值不会大于传入的 BURST_SIZE，所以这个判断正常情况下不会成立。它也不能检测一般收包错误，因为该 API 的返回值语义主要是“本次收到多少包”。

8. 遍历每一个包

int i=0;
for(i=0;i<num_recvd;i++){

依次处理本轮收到的所有 mbuf。

struct rte_ether_hdr *ethhdr=
 rte_pktmbuf_mtod(mbufs[i],struct rte_ether_hdr *);

取得包数据起点，把它解释成 Ethernet Header。

if(ethhdr->ether_type != rte_cpu_to_be_16(RTE_ETHER_TYPE_IPV4)){
 continue;
}

如果 EtherType 不是 IPv4，就跳过后续解析。ARP、IPv6、VLAN 等都会走 continue。

这里有一个重要的生命周期问题：跳过不等于释放。当前程序没有调用 rte_pktmbuf_free(mbufs[i])，因此收到的 mbuf 不会归还 mempool。运行一段时间后，RX Queue 可能因为拿不到空闲 mbuf 而停止继续收包。

struct rte_ipv4_hdr *iphdr =rte_pktmbuf_mtod_offset(
 mbufs[i],struct rte_ipv4_hdr *,sizeof(struct rte_ether_hdr));

从数据起点向后移动一个 Ethernet Header 的长度，即 14 字节，再把地址解释成 IPv4 Header。

当前代码在解引用前没有检查包的实际长度；遇到截断帧或异常帧时可能越界读取。

if (iphdr->next_proto_id==IPPROTO_UDP){

检查 IPv4 Protocol 字段是否等于 UDP 的协议号 17。

struct rte_udp_hdr *udphdr =(struct rte_udp_hdr *)(iphdr+1);

iphdr + 1 会跳过一个 struct rte_ipv4_hdr，也就是按 20 字节基础 IPv4 头定位 UDP Header。它没有考虑 IHL 大于 5的 IPv4 Options。

printf("udp:%s\n ",(char*)(udphdr+1));

udphdr + 1 跳过 8 字节 UDP Header，将后续 Payload 当作字符串打印。它没有依据 UDP Length 限制读取长度，也没有保证 Payload 以 \0 结尾，因此只适合受控的入门测试。

9. 循环之后的代码

printf("Hello dpdk\n");

由于前面是无限循环，并且没有 break，正常情况下这一行不可达。

十九、今天内容的核心总结

网卡把网络介质上的信号变成帧，并通过 DMA 把数据放入主机内存；它主要涉及物理层和数据链路层。
驱动负责初始化网卡、配置队列和 DMA，并让软件能够操作具体硬件。
Linux 使用 sk_buff 描述数据包；DPDK 使用 rte_mbuf，两者都不只是数据本身，还包含元数据。
多队列让多个 CPU 核并行处理流量，RSS 负责把流分配到不同队列；多队列很重要，但不是所有 DPDK 绑定的绝对前提。
DPDK 用用户态轮询、Burst、Hugepage、mempool、多队列和 NUMA 优化高速包处理。
网卡绑定给 DPDK 后，常规数据路径绕过内核 TCP/IP；因此要么引入现有用户态协议栈，要么自己实现。
Ethernet 普通头为 14 字节，IPv4 最少 20 字节，UDP 固定 8 字节，TCP 最少 20 字节。
“能找到协议头并打印 Payload”只是解析器原型，不等于完整协议栈。
完整 UDP 还需要 ARP、IP、校验和、端口分发、队列和 API；完整 TCP 还需要状态机、序列号、重传、窗口、定时器等。
POSIX recv() 读取的是 Socket 接收缓冲区；用户态协议栈必须自己建立 fd、Socket、TCB 和收发队列之间的关系。
当前测试通过静态 ARP 绕过了尚未实现的 ARP Reply，成功证明了 macOS、Fusion 桥接、vmxnet3、DPDK RX 和基础 UDP 解析链路已打通。
下一步最重要的不是立即写 TCP，而是先补齐 mbuf 释放、长度校验、ARP Reply、TX 和 UDP Echo。

二十、版本说明与官方参考

你的学习材料明显包含旧版 DPDK 构建流程，因此本笔记保留了 dpdk-setup.sh、RTE_SDK、RTE_TARGET 的历史解释，同时把现代版本单独说明。实际执行命令时，必须先运行 dpdk-testpmd -v、查看源码目录中的 release 信息或构建文件，确认本机 DPDK 版本。

DPDK Linux Getting Started Guide：现代 Linux 环境、编译、驱动和运行入口；
DPDK Poll Mode Driver：PMD 绕过传统内核网络栈、直接轮询 RX/TX Descriptor 的官方说明；
DPDK Linux Drivers：VFIO、UIO、设备绑定和安全性说明；
DPDK VMXNET3 PMD：vmxnet3 收发环、多队列/RSS、功能与限制；
DPDK Hugepage Tool：查看、预留和挂载大页；
DPDK 22.11 KNI 文档：KNI 的用途、弃用状态及 virtio-user 替代说明。

协程运行时：IO Hook、调度器与汇编上下文切换

Tue, 11 Aug 2026 00:00:00 +0800

本篇承接 yield、resume、ucontext 和简单轮询调度，重点理解阻塞式 I/O 的 Hook、协程状态管理、调度器与 epoll 的协作，以及 x86-64 汇编上下文切换。

一、从上下文切换走向完整协程运行时

已经掌握的两个方向：

main → ctx ：resume
ctx → main ：yield

它们底层都依赖一次 context switch：

保存当前执行现场
 ↓
恢复目标执行现场
 ↓
目标协程从上次暂停位置继续

但只有 switch、resume 和 yield 还不够。真正处理网络 I/O 还需要回答：

1. 普通read/recv没有数据时，怎样自动yield？
2. fd就绪以后，怎样找到并resume对应协程？
3. 十万个协程如何保存和组织？
4. READY、WAITING、SLEEPING、EXITED如何管理？
5. 定时器和I/O超时如何处理？
6. 上下文切换怎样用汇编实现？
7. 多核机器上怎样运行多个调度器？

最终需要形成：

POSIX I/O调用
 ↓
Hook层
 ↓
非阻塞I/O + epoll
 ↓
yield / resume
 ↓
协程状态和调度器
 ↓
ucontext或汇编context switch

二、为什么需要 Hook I/O

一个协程中的业务代码希望保持顺序结构：

while(1){
recv();
parser();
send();
}

阅读时仍然是：

接收数据
 ↓
解析数据
 ↓
发送响应

但如果这里直接调用阻塞式 recv()，没有数据时会阻塞整个线程，线程内其他协程也无法运行。

协程库希望在不大改业务流程的情况下，把调用替换为自己的实现：

业务调用recv/read
 ↓
进入协程库Hook函数
 ↓
先尝试非阻塞I/O
 ├── 已就绪：调用真实系统函数并返回
 └── 未就绪：注册epoll事件并yield
 ↓
 fd就绪
 ↓
 resume协程
 ↓
 再调用真实系统函数

这就是：

上层保持同步代码结构，底层通过 epoll 和协程实现异步等待。

三、Hook 的概念流程

笔记中的伪代码：

recv（fd,buffer,length）{
struct pollfd fds[1]={0};
fds[0].fd=fd;
if(0<poll(fd,1,0)){//io可读
recv_f(fd,buffer,length);
}else{
epoll_ctl(epfd,EPOLL_CTL_ADD,fd,&ev);
swapcontext();

}
}

它表达了四步。

3.1 检查 fd 是否就绪

poll(fd,1,0)

timeout 为 0，表示立即检查，不在 poll() 中等待。

返回值 > 0 → 当前fd有事件
返回值 = 0 → 当前没有事件
返回值 < 0 → 调用发生错误

3.2 已就绪时调用真实函数

recv_f(fd,buffer,length);

recv_f 指向真正的系统 recv，而不是 Hook 后的同名函数。

3.3 未就绪时注册 epoll

epoll_ctl(epfd,EPOLL_CTL_ADD,fd,&ev);

同时记录：

哪个fd
等待什么事件
哪个协程正在等待它
是否存在超时时间

3.4 当前协程 yield

swapcontext();

这里代表概念上的 yield。实际实现需要明确传入当前协程上下文和调度器上下文。

当前协程WAITING
 ↓
yield回调度器
 ↓
调度器运行其他READY协程

四、使用 dlsym 拦截 read 和 write

以下是提供的 Hook 代码：

#define _GNU_SOURCE

#include <dlfcn.h>

#include <stdio.h>
#include <ucontext.h>
#include <string.h>
#include <unistd.h>
#include <fcntl.h>

#include <sys/socket.h>
#include <errno.h>
#include <netinet/in.h>


#include <pthread.h>
#include <sys/poll.h>
#include <sys/epoll.h>

4.1 为什么需要 _GNU_SOURCE

#define _GNU_SOURCE

它在包含系统头文件前启用 GNU 扩展声明，使 dlsym()、RTLD_NEXT 等接口在相应环境中可见。

4.2 函数指针类型

原代码：

typedef ssize_t (*read_t)(int fd, void *buf, size_t count);
read_t read_f = NULL;

typedef ssize_t (*write_t)(int fd, const void *buf, size_t count);
write_t write_f = NULL;

read_t 描述真实 read() 的函数类型：

参数1：fd
参数2：接收缓冲区
参数3：最大读取长度
返回值：实际读取长度或错误

write_t 对应真实 write()。

read_f → 保存原始read地址
write_f → 保存原始write地址

五、init_hook() 如何取得真实函数

原代码：

void init_hook(void) {

	if (!read_f) {
		read_f = dlsym(RTLD_NEXT, "read");
	}

	
	if (!write_f) {
		write_f = dlsym(RTLD_NEXT, "write");
	}

}

dlsym() 根据符号名查找函数地址：

dlsym(RTLD_NEXT, "read");

RTLD_NEXT 的含义可以理解为：

从当前 Hook 定义之后继续寻找下一个名为 read 的实现。

因此调用关系是：

业务代码调用read()
 ↓
进入当前文件定义的Hook read()
 ↓
Hook内部调用read_f()
 ↓
进入真正的系统read()

如果 Hook 内部再次直接调用 read()：

Hook read()
 ↓
又进入Hook read()
 ↓
无限递归

所以必须使用 read_f 调用真实函数。

使用 dlsym() 时通常需要链接动态加载库：

gcc ... -ldl

六、read() Hook 的执行过程

原代码：

ssize_t read(int fd, void *buf, size_t count) {

	struct pollfd fds[1] = {0};

	fds[0].fd = fd;
	fds[0].events = POLLIN;

	int res = poll(fds, 1, 0);
	if (res <= 0) { //不可读


		// fd --> epoll_ctl();

		swapcontext(); // fd --> ctx fd与context一对一
		
	}
	// io

	
	ssize_t ret = read_f(fd, buf, count);
	printf("read: %s\n", (char *)buf);
	return ret;

	
	
}

6.1 构造 pollfd

struct pollfd fds[1] = {0};

fds[0].fd = fd;
fds[0].events = POLLIN;

表示只检查一个 fd 的可读事件。

6.2 立即检查

int res = poll(fds, 1, 0);

第三个参数为 0：

不等待
立即返回当前状态

6.3 不可读时暂停协程

if (res <= 0) {
 // fd --> epoll_ctl();
 swapcontext();
}

完整运行时还需要在 yield 前完成：

将fd设置为非阻塞
将fd注册到epoll
记录fd等待POLLIN/EPOLLIN
记录当前等待协程
设置可选超时时间
当前协程状态改为WAITING
yield到scheduler

fd 就绪后：

epoll_wait返回fd
 ↓
找到等待它的协程
 ↓
协程进入READY队列
 ↓
scheduler resume协程
 ↓
从swapcontext()之后继续
 ↓
read_f()真正读取数据

6.4 调用真实 read

ssize_t ret = read_f(fd, buf, count);

这一步才真正从内核读取数据。

poll 告诉程序“当前可能可读”，read_f 才完成实际读取。就绪状态可能在检查和读取之间变化，因此 fd 仍然应该是非阻塞的，并正确处理 EAGAIN。

七、write() Hook

原代码：

ssize_t write(int fd, const void *buf, size_t count) {

	printf("write: %s\n", (const char *)buf);

	return write_f(fd, buf, count);
}

当前实现主要展示：

业务调用write
 ↓
进入Hook write
 ↓
调用write_f进入真实write

完整协程版 write() 也需要处理：

真实write成功一部分
 → 记录已写偏移，继续写剩余数据

真实write返回EAGAIN
 → 注册EPOLLOUT
 → 当前协程yield
 → fd可写后resume

Hook write() 内部使用 printf() 记录日志时要特别小心，因为 printf() 最终也可能调用 write()，从而再次进入 Hook。实际实现通常使用不会再次触发该 Hook 的日志路径，或者直接调用保存下来的真实 write_f。

八、Hook 示例怎样接入普通服务端

原代码：

int main() {

	init_hook();

	int sockfd = socket(AF_INET, SOCK_STREAM, 0);

	struct sockaddr_in serveraddr;
	memset(&serveraddr, 0, sizeof(struct sockaddr_in));

	serveraddr.sin_family = AF_INET;
	serveraddr.sin_addr.s_addr = htonl(INADDR_ANY);
	serveraddr.sin_port = htons(2048);

	if (-1 == bind(sockfd, (struct sockaddr*)&serveraddr, sizeof(struct sockaddr))) {
		perror("bind");
		return -1;
	}

	listen(sockfd, 10);

	struct sockaddr_in clientaddr;
	socklen_t len = sizeof(clientaddr);
	int clientfd = accept(sockfd, (struct sockaddr*)&clientaddr, &len);
	printf("accept\n");

	while (1) {

		char buffer[128] = {0};
		int count = read(clientfd, buffer, 128);
		if (count == 0) {
			break;
		}
		write(clientfd, buffer, count);
		printf("sockfd: %d, clientfd: %d, count: %d, buffer: %s\n", sockfd, clientfd, count, buffer);

	}

	return 0;

}

业务代码仍然调用：

read(clientfd, buffer, 128);
write(clientfd, buffer, count);

但由于程序中定义了同名 read() 和 write()，符号解析会先进入 Hook。

这正是 Hook 的价值：

业务代码结构保持不变
 ↓
read/write调用被协程库接管
 ↓
等待I/O时自动yield
 ↓
就绪后自动resume

当前示例只接收一个 clientfd，重点是展示 Hook 链路。与真正协程服务器结合时，还需要 accept Hook、多连接协程、epoll mainloop 和 scheduler。

九、为什么第三方库也可以受益

例如本地程序使用 hiredis 连接 Redis。hiredis 内部会调用 read/write 或 send/recv 完成网络操作。

不修改 hiredis 源码时：

业务调用hiredis
 ↓
hiredis内部调用read/write
 ↓
进入协程库Hook
 ↓
没有数据时yield
 ↓
Redis响应到达后resume

因此原本按照阻塞式 POSIX API 编写的库，有机会直接运行在协程调度环境中。

前提是 Hook 覆盖了它实际调用的 API，并正确处理：

阻塞标志
超时
EINTR
EAGAIN
部分读写
close和fd复用
线程安全

十、如何定义一个协程

笔记中的初始设计：

struct coroutinue{
int fd;
ucontext_t ctx;//stack ，stack_size,func包含在里面
void *arg

};

一个协程需要保存两类信息。

10.1 执行现场

ctx → 寄存器、栈指针、执行位置等上下文
stack → 协程自己的栈
stack_size → 栈大小
entry → 协程入口函数
arg → 入口参数

10.2 调度状态

id → 协程标识
state → READY、RUNNING、WAITING等
fd → 当前等待的I/O对象
events → 等待EPOLLIN或EPOLLOUT
expire_at → 超时时间或唤醒时间
scheduler → 所属调度器

概念上的完整结构：

struct coroutine
 ├── id
 ├── state
 ├── context
 ├── stack / stack_size
 ├── entry / arg
 ├── waiting_fd / events
 ├── expire_at
 ├── ready_node
 ├── wait_node
 ├── sleep_node
 └── scheduler

本篇沿用原笔记中的 coroutinue 拼写来对应代码，实际项目中可以统一为 coroutine。

十一、协程入口与创建

原始设计：

void func(void){

}


typedef void *(*coroutinue_entry)(void *)
int create_coroutinue(co_id id,coroutinue_entry entry,void *arg){
struct coroutinue *co =malloc(sizeof(struct coroutinue));
co.ss_sp=
makecontext(co->ctx,func,0);
}

创建协程需要完成：

1. 分配struct coroutine
2. 分配或绑定独立栈
3. 保存entry和arg
4. 初始化context
5. 设置入口包装函数
6. 设置协程退出后的返回目标
7. state设为READY
8. 加入ready_queue

为什么通常需要一个入口包装函数：

scheduler resume新协程
 ↓
进入wrapper
 ↓
wrapper调用entry(arg)
 ↓
entry返回
 ↓
wrapper把协程状态设为EXITED
 ↓
yield回scheduler
 ↓
scheduler回收资源

如果直接让入口函数随意 return，而没有统一退出路径，调度器很难正确修改状态和释放栈。

十二、十万个协程如何组织

假设采用“一连接一协程”：

10万个fd
 ↓
10万个coroutine对象

但它们不会全部同时运行。

例如：

10万个协程
 ├── 2万个READY
 ├── 5万个WAITING
 ├── 2万个SLEEPING
 └── 1万个已结束或待回收

调度器必须按状态组织它们，不能每轮扫描全部十万个对象。

十三、READY 为什么使用队列

笔记中的设计：

queue_node (corountine,)ready_queue

READY 协程表示现在就可以运行。

常见操作：

协程变为READY → 从队尾加入
scheduler取任务 → 从队头取出
协程yield但仍可运行 → 再放回队尾

因此队列适合：

O(1)入队
O(1)出队
天然支持轮询公平调度

如果有 2 万个 READY 协程：

ready_head
 → co1 → co2 → co3 → ... → co20000

scheduler 每次取队头协程 resume。

十四、WAITING 与 SLEEPING 为什么需要有序结构

笔记中的设计：

rbtree_node(coroutinue,)wait_rb;
rbtree_node(coroutinue,)sleep_rb;

等待 I/O 的协程可能还设置超时：

协程A等待fd=4，100ms后超时
协程B等待fd=5，500ms后超时
协程C等待fd=6，50ms后超时

睡眠协程也有不同唤醒时间：

协程D睡眠到10:00:00.100
协程E睡眠到10:00:00.800

如果以 expire_at 为 key 放入有序结构，调度器可以快速找到最早到期节点：

最小expire_at
 ↓
与当前时间比较
 ↓
已经到期就移出
 ↓
状态改为READY
 ↓
加入ready_queue

红黑树、最小堆、跳表、时间轮都可以实现定时管理，具体选择取决于插入、删除、精度和规模要求。

I/O fd 到协程的查找，还可以另外使用：

epoll_event.data.ptr
哈希表 fd → coroutine
数组 fd → coroutine

时间树解决“谁先超时”，fd 映射解决“哪个事件唤醒谁”，它们是两个不同查找维度。

十五、一个协程为什么可以同时拥有多个节点

笔记中的思路是把数据结构节点直接放进 coroutine：

ready_node
wait_node
sleep_node

这种方式称为侵入式数据结构：

coroutine对象本身包含链表节点或树节点
 ↓
不需要额外分配包装节点
 ↓
从节点可以找回所属coroutine

但协程状态必须保持一致：

READY → 位于ready_queue
WAITING → 位于I/O等待集合，可能同时位于超时树
SLEEPING → 位于sleep定时结构
RUNNING → 当前正在执行，通常不在ready_queue
EXITED → 位于回收集合或等待立即回收

协程从一个状态切到另一个状态时，需要从旧集合移除，再加入新集合，避免同一个节点被重复挂载。

十六、scheduler 如何定义

笔记中的设计：

scheduler
struct scheduler{
int epfd
struct epoll_event events[];

queue_node (corountine,)ready_head
rbtree_root(coroutinue,)wait_rb;
rbtree_root(coroutinue,)sleep_rb;

};

各字段含义：

epfd → epoll实例
events[] → epoll_wait返回的就绪事件
ready_head → 当前可以运行的协程
wait_rb → 等待I/O并带超时的协程
sleep_rb → 主动睡眠的协程

完整调度器还会需要：

main_context → scheduler自己的上下文
current → 当前正在运行的协程
all_coroutines → 所有协程的所有权集合
exited_queue → 等待回收的协程
stop → 退出标志
thread_id → 所属线程

十七、哪些操作由协程执行，哪些由调度器执行

17.1 协程主动执行

调用read/recv/send/write
发现需要等待后yield
主动sleep
业务处理
入口函数返回并exit

17.2 调度器执行

维护ready_queue
计算最近超时时间
调用epoll_wait
处理fd就绪事件
处理wait/sleep超时
把协程转为READY
选择下一个协程resume
回收EXITED协程

核心边界：

协程表达“我要等待什么”，调度器决定“等待期间运行谁，以及何时唤醒我”。

十八、调度循环的完整流程

一个合理的 scheduler mainloop 可以概括为：

while没有停止：

 1. 处理已经到期的sleep节点
 2. 处理已经超时的I/O等待节点
 3. 处理ready_queue中的协程
 4. 根据最近定时器计算epoll_wait超时
 5. 调用epoll_wait
 6. 根据events找到等待协程
 7. 将就绪协程加入ready_queue
 8. 回收已经退出的协程

如果 ready_queue 非空：

可以先继续运行READY协程
epoll_wait使用timeout=0避免阻塞

如果 ready_queue 为空：

根据最近timer计算等待时间
 ↓
epoll_wait可以阻塞到I/O到达或定时器到期

这样线程不会忙等。

十九、协程状态怎样流转

典型状态：

NEW
 ↓ create
READY
 ↓ scheduler resume
RUNNING
 ├── 等待I/O → WAITING
 ├── sleep → SLEEPING
 ├── 主动yield且仍可运行 → READY
 └── entry返回 → EXITED

WAITING
 ├── fd就绪 → READY
 └── 超时 → READY，并携带timeout结果

SLEEPING
 └── 时间到 → READY

EXITED
 ↓ scheduler回收
DESTROYED

状态与容器必须同步：

state = READY
 ↔ 在ready_queue中

state = WAITING
 ↔ 在I/O等待映射中

state = SLEEPING
 ↔ 在timer结构中

二十、setjmp、ucontext 和汇编怎样选择

三种方案：

setjmp / longjmp
ucontext
architecture-specific assembly

20.1 setjmp / longjmp

优点：

标准C接口
可移植性相对好
适合理解保存点和恢复点

限制：

不直接提供独立协程栈管理
构造完整栈式协程较复杂

20.2 ucontext

优点：

getcontext/makecontext/swapcontext语义清晰
可以直接指定独立栈和入口函数
教学和原型实现简单

限制：

已经不属于现代POSIX标准
不同平台支持情况不一致

20.3 汇编

优点：

直接控制保存和恢复的寄存器
切换路径短
适合性能敏感的运行时

限制：

与CPU架构、ABI和调用约定绑定
x86-64、ARM64等需要不同实现
测试和维护成本高

性能不能只靠固定排名判断，需要在相同编译器、架构和切换模型下基准测试。汇编通常能做得更精简，但正确性和可移植性同样重要。

二十一、x86-64 汇编上下文切换原代码

#elif defined(__x86_64__)

__asm__ (
" .text \n"
" .p2align 4,,15 \n"
".globl _switch \n"
".globl __switch \n"
"_switch: \n"
"__switch: \n"
" movq %rsp, 0(%rsi) # save stack_pointer \n"
" movq %rbp, 8(%rsi) # save frame_pointer \n"
" movq (%rsp), %rax # save insn_pointer \n"
" movq %rax, 16(%rsi) \n"
" movq %rbx, 24(%rsi) # save rbx,r12-r15 \n"
" movq %r12, 32(%rsi) \n"
" movq %r13, 40(%rsi) \n"
" movq %r14, 48(%rsi) \n"
" movq %r15, 56(%rsi) \n"
" movq 56(%rdi), %r15 \n"
" movq 48(%rdi), %r14 \n"
" movq 40(%rdi), %r13 # restore rbx,r12-r15 \n"
" movq 32(%rdi), %r12 \n"
" movq 24(%rdi), %rbx \n"
" movq 8(%rdi), %rbp # restore frame_pointer \n"
" movq 0(%rdi), %rsp # restore stack_pointer \n"
" movq 16(%rdi), %rax # restore insn_pointer \n"
" movq %rax, (%rsp) \n"
" ret \n"
);
#endif

对应的上下文结构：

typedef struct _nty_cpu_ctx {
	void *esp; //
	void *ebp;
	void *eip;
	void *edi;
	void *esi;
	void *ebx;
	void *r1;
	void *r2;
	void *r3;
	void *r4;
	void *r5;
} nty_cpu_ctx;



int _switch(nty_cpu_ctx *new_ctx, nty_cpu_ctx *cur_ctx);

函数语义：

new_ctx → 即将恢复的目标上下文
cur_ctx → 当前需要保存的上下文

在 System V AMD64 ABI 中，前两个整数或指针参数通常放在：

第一个参数new_ctx → RDI
第二个参数cur_ctx → RSI

因此：

RSI作为基地址 → 保存当前上下文
RDI作为基地址 → 加载目标上下文

二十二、汇编第一部分：保存当前上下文

22.1 保存栈指针

movq %rsp, 0(%rsi)

含义：

把当前RSP保存到cur_ctx偏移0的位置

RSP 指向当前线程正在使用的栈顶。恢复 RSP 才能回到该协程自己的栈。

22.2 保存帧指针

movq %rbp, 8(%rsi)

一个指针占 8 字节，所以第二个字段位于偏移 8。

22.3 保存返回地址

movq (%rsp), %rax
movq %rax, 16(%rsi)

调用 _switch 时，返回地址位于当前栈顶。先读到 RAX，再保存到 cur_ctx 偏移 16。

这个地址就是以后恢复协程时需要继续执行的位置。

22.4 保存被调用者保存寄存器

movq %rbx, 24(%rsi)
movq %r12, 32(%rsi)
movq %r13, 40(%rsi)
movq %r14, 48(%rsi)
movq %r15, 56(%rsi)

这些寄存器按照 x86-64 System V ABI 属于 callee-saved registers。函数返回后调用方有权期待它们保持不变，因此 context switch 必须保存和恢复。

偏移每次增加 8：

0 → rsp
8 → rbp
16 → rip/返回地址
24 → rbx
32 → r12
40 → r13
48 → r14
56 → r15

原结构中的 esp、ebp、eip 是 32 位风格名称；在这段 x86-64 汇编中实际保存的是 rsp、rbp 和返回地址。

二十三、汇编第二部分：恢复目标上下文

movq 56(%rdi), %r15
movq 48(%rdi), %r14
movq 40(%rdi), %r13
movq 32(%rdi), %r12
movq 24(%rdi), %rbx
movq 8(%rdi), %rbp
movq 0(%rdi), %rsp
movq 16(%rdi), %rax
movq %rax, (%rsp)
ret

这部分按相反方向加载 new_ctx：

恢复r15、r14、r13、r12、rbx
 ↓
恢复rbp
 ↓
恢复目标协程rsp
 ↓
把目标返回地址放到目标栈顶
 ↓
ret弹出返回地址
 ↓
从目标协程保存位置继续执行

最关键的一步：

movq 0(%rdi), %rsp

RSP 一旦切换，当前使用的栈就从旧协程栈变成了目标协程栈。

最后：

ret

从目标栈弹出保存的指令地址，于是代码看起来像目标协程之前调用的 _switch() 正常返回。

二十四、为什么不是保存所有寄存器

x86-64 有更多通用寄存器，但按照函数调用约定分为：

caller-saved → 调用方负责在需要时保存
callee-saved → 被调用函数必须保证返回后不变

_switch() 以普通函数调用形式进入，编译器会按照 ABI 处理 caller-saved 寄存器中的临时值，因此最小切换实现主要保存 callee-saved 寄存器、栈指针和返回位置。

这依赖：

明确的ABI
正确的函数声明
编译器遵循调用约定
汇编与结构体布局完全一致

System V AMD64 中，前六个整数或指针参数通常依次使用：

RDI、RSI、RDX、RCX、R8、R9

函数并不是不能超过六个参数。超过六个的参数会按照 ABI 放到栈上，只是调用方式不再全部使用参数寄存器。

二十五、从 Hook read 到调度器唤醒的完整链路

协程A调用read(fd)
 ↓
进入Hook read
 ↓
poll或真实read发现暂时不可读
 ↓
fd注册EPOLLIN
 ↓
记录fd → 协程A
 ↓
协程A状态RUNNING → WAITING
 ↓
_switch(scheduler_ctx, coA_ctx)
 ↓
scheduler运行其他READY协程
 ↓
epoll_wait返回fd
 ↓
根据event找到协程A
 ↓
从等待集合删除协程A
 ↓
协程A状态WAITING → READY
 ↓
加入ready_queue
 ↓
scheduler选择协程A
 ↓
_switch(coA_ctx, scheduler_ctx)
 ↓
协程A从Hook read中的yield位置继续
 ↓
调用read_f真正读取
 ↓
返回业务代码

这一整条链路把四个模块连接起来：

Hook层
epoll事件层
scheduler调度层
context switch底层

二十六、多线程与多进程模式

26.1 多线程模式

一种设计是多个线程各自运行调度器：

线程1 → scheduler1 → epoll1 → 一组协程
线程2 → scheduler2 → epoll2 → 一组协程
线程3 → scheduler3 → epoll3 → 一组协程

这通常比多个线程共同操作一个 scheduler 更容易控制，因为每个协程和上下文固定属于一个线程。

如果多个线程共享：

ready_queue
wait tree
sleep tree
coroutine对象

就需要考虑锁、并发状态迁移、跨线程唤醒和缓存竞争。

CPU affinity 可以让调度线程尽量固定在某个 CPU 核，减少迁移和缓存失效，但是否绑定需要通过测试决定。

26.2 多进程模式

进程1 → scheduler1 → 一组连接
进程2 → scheduler2 → 一组连接
进程3 → scheduler3 → 一组连接

每个进程拥有独立地址空间和调度器，协程数据天然隔离，减少共享锁。

需要额外考虑：

监听端口如何共享
连接如何负载均衡
进程间通信
共享状态
进程崩溃恢复

多线程和多进程都能利用多核。区别主要在共享内存、隔离性和通信成本。

二十七、怎样把协程能力用到实际项目

27.1 网络框架

以 ntyco 为基础理解：

coroutine
scheduler
epoll
Hook
timer
assembly switch

重点不是只复现 switch，而是打通：

I/O等待 → yield → epoll唤醒 → ready → resume

27.2 WebServer

一个连接或请求由一个协程处理
 ↓
协程recv HTTP请求
 ↓
解析协议
 ↓
查询Redis/MySQL
 ↓
发送HTTP响应

每个等待点都由 Hook 和 scheduler 自动让出。

27.3 KV 存储

例如 dkvstore：

连接协程
 ↓
接收命令
 ↓
解析SET/GET
 ↓
访问存储结构
 ↓
返回结果

27.4 图床

上传连接
 ↓
接收文件数据
 ↓
写磁盘或对象存储
 ↓
写数据库
 ↓
返回图片URL

这些项目能够体现的不是“使用了协程”一句话，而是：

怎样Hook阻塞API
怎样管理十万连接状态
怎样设计ready/wait/sleep结构
怎样处理超时和部分读写
怎样在多核上部署调度器
怎样测试切换和网络性能

二十八、核心总结

重点一：Hook 让同步代码接入异步调度

业务仍然调用read/write
 ↓
Hook判断I/O状态
 ↓
不可用时注册epoll并yield
 ↓
就绪后resume

重点二：协程对象既保存执行现场，也保存调度状态

context/stack → 回来后从哪里继续
state/fd/time → 什么时候可以回来
data nodes → 当前属于哪个调度集合

重点三：不同状态需要不同数据结构

READY → queue
I/O映射 → epoll data、数组或哈希
超时/睡眠 → 红黑树、最小堆或时间轮
EXITED → 回收队列

重点四：scheduler 是整个运行时的中心

处理epoll事件
处理定时器
维护协程状态
选择READY协程
执行resume
接收yield
回收退出协程

重点五：汇编 switch 只做保存和恢复

RSI → 保存当前上下文
RDI → 恢复目标上下文
RSP → 切换协程栈
ret → 跳回目标协程保存位置

最终可以把协程运行时理解成：

Hook 决定何时等待，epoll 决定何时就绪，scheduler 决定运行谁，context switch 决定怎样切过去。

POSIX API 与 TCP 连接生命周期

Mon, 10 Aug 2026 00:00:00 +0800

本篇承接已有的《网络IO》《IO 多路复用与 Reactor》《Reactor 与 epoll：百万并发网络服务器课后笔记》。
socket、fd、服务端基础代码、select/poll/epoll 和 Reactor 不再重复；

一、为什么网络代码可以跨 Linux、Unix 和 macOS

Linux 受到 Unix 设计影响，不同厂商和社区又形成了不同发行版。它们的内核、工具和扩展功能可能不同，但应用程序仍然可以使用一组相似的接口：

socket();
bind();
listen();
accept();
connect();
send();
recv();
close();

重要原因是这些系统广泛支持 POSIX 和 BSD Socket 风格的接口规范。

标准接口主要约定：

函数叫什么
函数接收什么参数
返回值如何表达成功和失败
错误通过什么方式报告
应用程序可以依赖哪些行为

不同系统的内核实现可以不同，但只要对应用程序提供兼容接口，使用标准接口编写的代码就比较容易迁移：

应用程序
 ↓
POSIX / Socket API
 ↓
不同操作系统的内核实现

代码可以直接迁移还要求它没有依赖某个系统的专有能力。例如 socket、bind、listen 是通用 Socket API；epoll 是 Linux 专用机制，迁移到 macOS 时通常要换成 kqueue。

二、客户端和服务端使用的 API

2.1 TCP 客户端

课堂中的客户端调用顺序：

socket();
bind();//optional
connect();
send();
recv();
close();

对应作用：

socket() → 创建 socket 和 fd
bind() → 可选，指定本地 IP 和本地端口
connect() → 指定对端并发起 TCP 连接
send() → 把应用数据交给内核
recv() → 从内核取出收到的数据
close() → 关闭 fd，并推动 TCP 关闭过程

客户端通常不主动调用 bind()。如果直接 connect()，内核会选择合适的本地 IP 和临时端口。

临时端口范围由系统配置决定，不固定为 1024～65535。Linux 上可以查看：

cat /proc/sys/net/ipv4/ip_local_port_range

客户端需要固定源 IP 或源端口时，才会在 connect() 前显式调用 bind()。

2.2 TCP 服务端

课堂中的服务端调用顺序：

socket();
bind();
listen();
accept();
recv();
send();
close();

与 Reactor 结合后还会使用：

epoll_create();
epoll_ctl();
epoll_wait();
fcntl();

这两组 API 位于不同层次：

socket/bind/listen/accept/connect/send/recv/close
 → 管理 TCP socket 和数据传输

epoll_create/epoll_ctl/epoll_wait
 → 管理大量 fd 的就绪事件

fcntl() 常用于把 fd 设置为非阻塞。

三、一次 TCP 连接的三个阶段

1. 建立连接：三次握手
2. 数据传输：序号、确认、流量控制、拥塞控制和重传
3. 断开连接：FIN/ACK 与 TCP 状态迁移

应用程序看到的是：

connect() / accept()
send() / recv()
close()

内核真正执行的是 TCP 协议状态机。

四、socket() 在应用层与内核之间建立了什么

课堂代码：

fd=socket();

socket 的英文含义是插座。可以用“插头和插座”帮助理解应用层 fd 与内核 socket 对象的关系：

应用层
 fd：应用程序使用的整数句柄
 ↓
内核
 socket/TCP相关对象：保存协议、地址、状态、缓冲区等

socket() 成功后主要完成两类事情。

4.1 分配 fd

fd 是当前进程文件描述符表中的一个位置。内核找到可用位置，将它标记为正在使用，然后返回对应整数。

进程fd表
0 → 标准输入
1 → 标准输出
2 → 标准错误
3 → 新创建的socket

调用 close(fd) 后，该 fd 位置会被释放，之后可能被其他文件或 socket 再次使用。

4.2 创建并关联内核 socket 状态

应用程序用 fd 查找内核中的 socket 对象。TCP 相关对象会逐步保存：

本地IP
本地端口
远端IP
远端端口
协议类型
TCP状态
发送缓冲区
接收缓冲区
序号和确认号
窗口及重传信息

课堂中把这组 TCP 连接状态概括为 TCB（Transmission Control Block，传输控制块）。

五元组是：

源IP
源端口
目的IP
目的端口
传输层协议

例如：

192.168.1.10:52000
 → 192.168.1.20:2000
 → TCP

同一个服务端端口可以同时拥有大量连接，因为每条连接的五元组不同。

五、bind()：把本地地址写入 socket

课堂代码：

bind(fd,);

bind() 的作用是给 socket 指定本地 IP 和本地端口：

通过fd找到内核socket对象
 ↓
设置本地IP
 ↓
设置本地端口

服务端必须有稳定的监听地址，所以通常显式绑定：

0.0.0.0:2000

客户端通常直接调用 connect()；如果之前没有 bind()，内核会自动选择本地地址和临时端口。

六、listen()：让 socket 进入监听状态

课堂代码：

listen(fd,backlog);

listen() 将 socket 变成监听 socket：

普通TCP socket
 ↓ listen()
LISTEN状态

如果服务端只完成 bind() 而没有 listen()，对应端口没有处于 TCP 监听状态，客户端连接通常会被拒绝。

6.1 两类连接队列

监听 socket 的连接可以从两个阶段理解：

收到客户端SYN
 ↓
SYN队列：握手尚未完成
 ↓
收到第三次握手ACK
 ↓
已完成连接队列：等待应用accept()

常见名称：

SYN queue / 半连接队列
accept queue / 已完成连接队列

“半连接”不是只能传一半数据，而是三次握手还没有完成。

6.2 backlog

现代 Linux 中，listen(fd, backlog) 的 backlog 主要限制等待 accept() 的已完成连接队列长度：

listen(fd,backlog);

可以理解成：

应用程序暂时没来得及 accept 时，内核允许多少条已经建立完成的连接排队等待。

SYN 队列还有独立内核配置：

cat /proc/sys/net/ipv4/tcp_max_syn_backlog

实际队列长度还受内核上限、系统配置和 SYN cookies 等机制影响。

七、TCP 三次握手

三次握手由内核 TCP 协议栈完成。应用程序通过 connect() 发起；服务端 listen() 后由内核接收握手；accept() 取出的是已经完成握手的连接。

假设双方初始序号分别是：

客户端初始序号：1234
服务端初始序号：5647

7.1 第一次：客户端发送 SYN

client → server

SYN = 1
SEQ = 1234

含义：

客户端希望建立连接，自己的初始发送序号从 1234 开始。

客户端状态：

CLOSED → SYN_SENT

SYN 会占用一个序号，所以服务端确认时使用 1234 + 1。

7.2 第二次：服务端返回 SYN + ACK

server → client

SYN = 1
ACK = 1
SEQ = 5647
ACK number = 1235

ACK number = 1235 表示客户端序号 1234 的 SYN 已经收到，下一次期望从 1235 开始。

同时，服务端告诉客户端自己的初始发送序号是 5647。

服务端相关连接状态：

LISTEN → SYN_RECEIVED

7.3 第三次：客户端返回 ACK

client → server

ACK = 1
ACK number = 5648

5648 = 5647 + 1，表示服务端的 SYN 已经收到。随后双方进入：

ESTABLISHED

完整过程：

客户端 服务端

SYN, SEQ=1234
 ───────────────────────────────→

 SYN+ACK,
 SEQ=5647, ACK=1235
 ←───────────────────────────────

ACK, ACK=5648
 ───────────────────────────────→

双方进入ESTABLISHED

7.4 为什么要交换序号

双方分别告诉对方自己的初始序号，后续 TCP 才能利用序号和确认号实现：

识别数据顺序
发现数据缺失
排除重复数据
确认已经收到的字节范围
进行超时重传

初始序号不是固定从 0 开始，而是由内核生成。这样可以减少旧连接延迟报文的干扰，也提高序号的不可预测性。

八、connect()、握手和 accept() 的关系

客户端：

connect();

connect() 让内核发起 TCP 三次握手。阻塞 socket 上，connect() 通常要等待连接成功或失败后才返回，因此服务端不可达时可能等待较长时间。

服务端：

listen();
accept();

三次握手不是由 accept() 执行的。握手由服务端内核协议栈在监听状态下完成：

内核完成三次握手
 ↓
连接进入已完成连接队列
 ↓
listenfd出现可读事件
 ↓
应用调用accept()

accept() 主要完成：

从已完成连接队列取出一条连接
 ↓
为它分配新的clientfd
 ↓
让clientfd关联这条已连接socket

因此：

listenfd → 继续监听新连接
clientfd → 与某个客户端收发数据

8.1 Reactor 中的对应关系

listenfd出现EPOLLIN
 ↓
accept_cb()
 ↓
accept()
 ↓
得到clientfd
 ↓
把clientfd注册到epoll

LT 下，如果队列中还有连接，监听 fd 会继续报告可读。

ET 下应循环 accept()，直到当前队列已经取空。课堂代码：

while（1）{
fd =accept();
if(fd==-1){
break

}
}

这段代码表达的核心是：

一次EPOLLIN通知
 ↓
连续accept
 ↓
把当前已经完成的连接全部取出

实际使用非阻塞 fd 时，accept() 返回 -1 且 errno 为 EAGAIN/EWOULDBLOCK，表示本轮队列已经取空。

九、SYN 队列如何匹配第三次握手

收到第三次握手报文后，内核需要找到它属于哪一条正在建立的连接。

IP 头和 TCP 头能够提供：

源IP
目的IP
源端口
目的端口
协议类型TCP

内核结合五元组、序号和连接状态查找对应的半连接状态，验证 ACK 后，将连接推进到已建立状态并放入已完成连接队列。

连接状态的生命周期不是从 accept() 才开始。服务端收到 SYN 后，内核已经需要保存握手状态；accept() 只是把完成后的连接交给应用程序。

十、SYN Flood

SYN Flood 的基本过程：

攻击者发送大量SYN
 ↓
服务端为握手保存状态
 ↓
攻击者不完成第三次握手
 ↓
半连接状态和相关资源被持续占用

常见防护包括：

SYN cookies。
调整 SYN 队列和重试参数。
防火墙、负载均衡器和云安全组。
限速和异常源识别。
DDoS 清洗服务。

listen() 的 backlog 主要用于已完成连接队列，不能单独解决 SYN Flood。

十一、send() 和 recv() 到底做了什么

课堂中的数据路径：

发送方application
 ↓ send/write
发送方kernel TCP协议栈
 ↓
网络
 ↓
接收方kernel TCP协议栈
 ↓ recv/read
接收方application

11.1 send()

课堂例子：

send（fd,buffer,100,0）;
send（fd,buffer,200,0）;
send（fd,buffer,400,0）;

send() 返回正数，表示本次有多少字节被内核 socket 发送路径接受。它不表示对端应用已经读取这些数据。

后续什么时候组成 TCP 段、什么时候交给 IP 层、何时重传，由内核协议栈处理。

TCP 是字节流，不保留应用层每次 send() 的边界。上面三次调用总共交给 TCP 700 字节，接收端不一定按照 100、200、400 三次收到。

11.2 recv()

课堂例子：

recv（fd，buffer，50,0）
recv（fd，buffer，250,0）
recv（fd，buffer，250,0）
recv（fd，buffer，150,0）

接收端可以按照 50 + 250 + 250 + 150 取出相同的 700 字节。

recv() 把已经到达 socket 接收缓冲区的数据复制到应用层 buffer。一次返回多少字节取决于：

当前已经到达多少数据
应用提供的buffer有多大
socket是否阻塞
协议栈和调度时机

因此：

发送端三次send
不等于
接收端必须三次recv

这也是 TCP 半包、粘包问题的来源。应用层协议需要自己定义消息边界，例如固定长度、长度字段或分隔符。

11.3 一次接收 1000 与十次接收 100

课堂对比：

recv（fd,buffer,1000,0）;

与：

recv（fd,buffer,100,0）;
// 循环10次

复制总数据量可以相同，但十次 recv() 会产生更多系统调用、循环判断和状态处理开销，因此性能并非完全没有差异。

实际代码应以协议完整性和程序结构为主，选择合理缓冲区大小，不必把每次读取切得非常小。

十二、MTU、MSS 与 TCP 分段

MTU 是链路能够承载的最大 IP 包大小。常见以太网 MTU 是 1500 字节，但它包含 IP 头，不等于 TCP 应用数据长度。

TCP 常用 MSS 表示一个 TCP 段最多携带的 payload 大小：

MSS ≈ MTU - IP头 - TCP头

常见 IPv4、无额外选项时：

1500 - 20 - 20 = 1460字节

课堂例子：

send（fd,buffer,1700,0）;

应用一次交给内核 1700 字节，不代表网络上一定只有一个包。协议栈会根据 MSS、网卡卸载、路径 MTU 等条件分段。

接收端 recv() 的边界与网络分段也没有一一对应关系。网络上传输多个 TCP 段，接收端可能一次取出合并后的数据，也可能分多次取出。

十三、TCP 如何可靠并尽量快速地传输

这些机制主要运行在两端内核 TCP 协议栈之间，不由应用程序逐包控制。

13.1 序号与确认号

SEQ → 当前报文携带的数据从哪个字节序号开始
ACK → 下一次期望收到哪个字节序号

如果 ACK number = 1235，可以理解为序号 1235 之前的数据已经连续收到，下一次希望从 1235 开始。

13.2 接收窗口与滑动窗口

接收方通过窗口告诉发送方：

当前接收缓冲区还允许接收多少数据。

发送方可以在没有逐段等待 ACK 的情况下发送窗口范围内的多段数据。ACK 推进后，允许发送的范围继续向前滑动。

它解决：

既要连续发送提高吞吐
又不能超过接收方处理能力

13.3 慢启动

连接开始时，发送方不知道网络能承受多少在途数据，因此从较小的拥塞窗口开始。在慢启动阶段，拥塞窗口按每个 RTT 观察通常接近指数增长。

13.4 拥塞避免

拥塞窗口达到阈值后，增长转为更平缓的方式。检测到丢包或拥塞信号后，具体如何降低窗口取决于拥塞控制算法和丢包检测方式，不能把所有情况都理解为固定“减半重新开始”。

13.5 延迟确认

接收方可以短暂等待，把 ACK 与反向数据一起发送，或者用一个 ACK 确认更多数据，以减少纯 ACK 包数量。

延迟时间由协议实现和当前状态决定，不是所有系统都固定延迟 200 ms。

13.6 超时重传与快速重传

发送方在规定时间内没有收到确认，会认为数据可能丢失并触发重传。连续收到重复 ACK 时，也可能在超时前触发快速重传。

这些机制共同实现：

可靠传输
按序交付
避免重复
适应接收端能力
适应网络拥塞程度

十四、close() 与四次挥手

课堂代码：

close(fd);

close() 首先是通用的 fd 关闭接口。对 TCP socket 来说，当最后一个引用被关闭时，内核会根据 socket 状态和配置推进 TCP 关闭过程。

TCP 关闭使用 FIN 标志，不是 final。

14.1 为什么通常是四次

TCP 是全双工连接，两个方向需要分别关闭：

主动关闭方 被动关闭方

FIN
 ───────────────────────────────→

 ACK
 ←───────────────────────────────

 FIN
 ←───────────────────────────────

ACK
 ───────────────────────────────→

过程：

1. 主动方发送FIN：我没有更多数据要发送
2. 被动方返回ACK：我知道你不再发送
3. 被动方处理完自己的发送后，也发送FIN
4. 主动方返回ACK：确认对方也不再发送

第二步和第三步有时会合并在同一个报文中，所以抓包时不一定总能机械地看到四个独立数据包。

14.2 主动关闭方状态

ESTABLISHED
 ↓ close()，发送FIN
FIN_WAIT_1
 ↓ 收到对方对FIN的ACK
FIN_WAIT_2
 ↓ 收到对方FIN，返回ACK
TIME_WAIT
 ↓ 等待2MSL
CLOSED

14.3 被动关闭方状态

ESTABLISHED
 ↓ 收到FIN，返回ACK
CLOSE_WAIT
 ↓ 本地应用调用close()，发送FIN
LAST_ACK
 ↓ 收到对方ACK
CLOSED

14.4 为什么 recv() 返回 0

被动方收到 FIN 后，如果此前还有已到达的数据，应用应先读出这些数据。全部读完以后，再次调用：

recv(fd,buffer,size,0);

会返回：

它表示对方正常关闭了发送方向，后面不会再有数据。非阻塞 socket 暂时没有数据返回的是 -1/EAGAIN，不是 0。

14.5 数据与 FIN

应用先调用：

send（fd,buffer,100,0）

随后调用：

close(fd);

TCP 会保持字节流顺序：内核已经接受的待发送数据排在 FIN 之前。接收端先读到数据，数据全部读完后才观察到 EOF，即 recv() == 0。

14.6 shutdown()

shutdown() 可以只关闭 TCP 的一个方向：

SHUT_RD → 关闭读方向
SHUT_WR → 关闭写方向，向对端发送FIN
SHUT_RDWR → 关闭读写方向

它适合“我已经发送完，但还要继续接收对方响应”的半关闭协议。普通请求响应程序只使用 close() 也很常见，但 shutdown() 并不是没有用途。

十五、TIME_WAIT、CLOSING 与同时关闭

15.1 TIME_WAIT

通常由最终发送 ACK 的主动关闭方进入 TIME_WAIT。作用：

如果最后一个ACK丢失，可以重新确认对方重发的FIN
让旧连接的延迟报文在网络中消失

服务端出现大量 TIME_WAIT，通常说明服务端经常主动关闭连接，不等于双方一定同时调用了 close()。

15.2 同时关闭

如果双方几乎同时调用 close()：

双方都发送FIN
 ↓
双方都可能在FIN_WAIT_1时收到对方FIN
 ↓
进入CLOSING
 ↓
收到自己FIN对应的ACK
 ↓
进入TIME_WAIT

简化状态：

ESTABLISHED
 ↓ 本地发送FIN
FIN_WAIT_1
 ↓ 先收到对端FIN
CLOSING
 ↓ 收到ACK
TIME_WAIT

如果主动方先收到 ACK，再收到 FIN，则通常经过：

FIN_WAIT_1 → FIN_WAIT_2 → TIME_WAIT

TCP 状态机用于处理这些不同的报文到达顺序。

十六、同时打开与 TCP P2P

常规应用使用客户端/服务端角色：

客户端调用connect()
服务端调用listen()/accept()

但 TCP 建立后，双方都是全双工通信端点。客户端和服务端主要描述谁主动连接、谁被动监听，以及应用协议中的角色。

TCP 还定义了“同时打开”：双方都主动发送 SYN，并在 SYN_SENT 状态收到对方 SYN。

双方CLOSED
 ↓ 同时主动打开
双方SYN_SENT
 ↓ 收到对方SYN并返回SYN+ACK
双方SYN_RECEIVED
 ↓ 收到ACK
双方ESTABLISHED

课堂中的 P2P 方向：

fd=socket（）
bind（）//optional
connect（）；

真正跨公网实现 P2P 还需要考虑 NAT、端口映射、防火墙和连接协调。单纯同时调用 connect() 不保证一定能穿透网络设备。

本节需要理解：

TCP 建立后没有“只能客户端发、只能服务端收”的限制，双方都可以 send 和 recv。

十七、把 API 与 TCP 状态对应起来

应用调用或事件	内核中的主要含义
socket()	创建 fd 和 socket 相关内核对象
bind()	设置本地 IP 和端口
listen()	进入 LISTEN，准备接收连接
connect()	主动发起三次握手
收到 SYN	创建或查找握手状态，进入 SYN_RECEIVED
握手完成	连接进入 ESTABLISHED，并等待 accept
accept()	从已完成连接队列取出连接，返回 clientfd
send()	把应用字节交给 socket 发送路径
recv()	把 socket 接收数据复制到应用缓冲区
收到 FIN	对端关闭发送方向，最终让 recv 返回 0
close()	释放 fd 引用，并推动 TCP 关闭过程

完整主线：

socket()
 ↓
bind()
 ↓
listen() / connect()
 ↓
三次握手
 ↓
accept()得到clientfd
 ↓
send()/recv()
 ↓
序号、确认、窗口、拥塞控制、重传
 ↓
close()
 ↓
FIN/ACK与四次挥手
 ↓
TIME_WAIT或CLOSED

十八、本节课需要真正掌握的内容

重点一：API 是入口，协议栈完成真正的 TCP 工作

connect()不是应用自己发送三个包
accept()不负责执行三次握手
send()不等于对端应用已经收到
recv()不对应某一次send()
close()会推动TCP关闭状态机

重点二：监听 fd 和客户端 fd 对应不同状态

listenfd
 → LISTEN状态
 → 管理握手和等待accept的连接

clientfd
 → 对应某条已建立TCP连接
 → 用于send和recv

重点三：TCP 是可靠字节流

没有应用消息边界
使用序号和ACK保证顺序与可靠性
使用接收窗口进行流量控制
使用拥塞窗口适应网络承载能力
使用重传恢复丢失数据

重点四：建立和关闭都是状态机

三次握手：
CLOSED → SYN_SENT/SYN_RECEIVED → ESTABLISHED

主动关闭：
ESTABLISHED → FIN_WAIT_1 → FIN_WAIT_2 → TIME_WAIT

被动关闭：
ESTABLISHED → CLOSE_WAIT → LAST_ACK → CLOSED

课后实践

准备两台虚拟机，观察 TCP P2P：

1. 双方创建TCP socket
2. 根据实验设计绑定本地地址
3. 协调双方连接时机
4. 抓包观察SYN、SYN+ACK、ACK
5. 建立后让双方都执行send和recv
6. 同时或分别close，观察TCP状态

可以配合：

ss -ant
tcpdump -nn -i any tcp

协程设计原理：从异步回调到 ucontext 调度

Mon, 10 Aug 2026 00:00:00 +0800

本篇承接已有的网络 I/O、epoll 与 Reactor 笔记。这份笔记重点理解：为什么需要协程、协程怎样把异步 I/O 写成同步流程、上下文切换的三种实现方式，以及 yield、resume 和调度器之间的关系。

一、这份笔记要解决的问题

以开源协程库 ntyco 为参照，尝试逐步理解并实现一套用户态协程框架。

完整学习路线包括：

1. 为什么需要协程
2. 协程有哪些原语操作
3. 如何定义 struct coroutine
4. 如何定义 struct scheduler
5. 调度器采用什么策略
6. 如何兼容或封装 POSIX API
7. 协程从创建到退出的执行流程
8. 协程如何扩展到多核
9. 如何测试协程性能

当前真正落到代码上的内容主要是：

异步回调为什么难写
 ↓
协程如何保留同步代码结构
 ↓
上下文切换需要保存什么
 ↓
setjmp/longjmp
 ↓
ucontext
 ↓
yield / resume
 ↓
最简单的轮询调度器

后续的 struct coroutine、struct scheduler、I/O 调度、多核模式和性能测试，是建立在这些基础之上的下一阶段。

二、协程要解决什么问题

2.1 同步请求

同步代码通常按顺序执行：

func(){
send（）；
recv();
}

执行过程：

send()发起请求
 ↓
recv()等待结果
 ↓
结果返回以后继续执行

优点是代码符合人的思考顺序：

发请求 → 等结果 → 处理结果

缺点是等待 I/O 时，当前执行单元不能继续做其他工作。

2.2 异步回调

异步写法可以表示为：

callback(){
 recv();
 send(fd,cb);
 }
 func{
 send(fd,callback)
 }

执行过程：

func()发起请求
 ↓
立即返回，不阻塞当前流程
 ↓
fd就绪
 ↓
事件系统调用callback()
 ↓
callback()继续处理结果

异步的关键不是函数名字叫 async，而是：

发起操作和处理结果不在同一次连续调用栈中，中间通过事件和回调重新进入业务逻辑。

2.3 异步不等于并行

异步表示等待期间可以处理其他任务；并行表示多个任务在同一时刻由不同 CPU 核执行。

异步 → 关注等待关系
并行 → 关注是否同时执行

单线程 epoll 也可以实现异步，但它并没有同时使用多个 CPU 核。

2.4 协程的目标

回调的性能模型很好，但业务流程一复杂，就会出现多层嵌套：

请求A完成
 → 回调中发起请求B
 → B的回调中发起请求C
 → C的回调继续业务

协程希望实现：

底层：仍然使用异步事件和非阻塞I/O
上层：代码看起来像同步顺序执行

即：

底层异步，上层同步写法。

三、线程池异步与单线程同步的对比

线程池任务示例：

client_t *rClient = (client_t*)malloc(sizeof(client_t));
					memset(rClient, 0, sizeof(client_t));				
					rClient->fd = clientfd;
					
					job_t *job = malloc(sizeof(job_t));
					job->job_function = client_job;
					job->user_data = rClient;
					workqueue_add_job(&workqueue, job);

这里把 clientfd 封装进任务：

rClient->fd = clientfd
 ↓
job->job_function = client_job
 ↓
job->user_data = rClient
 ↓
workqueue_add_job()
 ↓
工作线程取出任务并执行

两种结构如下。

3.1 同一个线程检测和处理 I/O

while(1){
int nready =epll_wait();
for(int i=0;i<nready;i++){
recv(event[i].data.fd,buffer)
send(event[i]data.fd,buffer)
}
}
}
//单线程

流程：

epoll_wait()
 ↓
遍历就绪fd
 ↓
当前线程执行recv/send
 ↓
处理完成后才能继续下一个事件

3.2 epoll 线程只分发任务

void *task_callback(void *arg){
	recv(event[i].data.fd,buffer)
send(event[i]data.fd,buffer)
}
while(1){
int nready =epll_wait();
for(int i=0;i<nready;i++){
task.fd=event[i].fd
task.callback=task_callback
push_task_to_threadpool(&task);
}//多线程

流程：

epoll_wait()检测就绪
 ↓
把fd包装成task
 ↓
推入线程池
 ↓
工作线程执行recv/send

一次示例测试得到：

线程池方式：每1000连接约1500ms
直接处理：每1000连接约7300ms

这个结果只能说明当前代码、机器和负载下，任务并行处理改善了吞吐。它不能直接推导出“所有异步程序一定比同步程序快六倍”。

性能差异还可能来自：

任务中是否有阻塞操作
CPU核心数量
连接和请求模型
锁与队列开销
日志输出
测试方法
数据大小

协程与线程池也不是同一种实现：

线程池 → 内核线程并行执行任务
协程 → 通常在线程内由用户态调度器协作切换

四、为什么互联网业务需要并发等待

一个网页可能需要同时请求多个动态接口：

用户信息
文章列表
消息数量
推荐内容
广告数据
权限信息

如果完全串行：

请求1完成
 ↓
请求2完成
 ↓
请求3完成

总等待时间会累积。

如果这些请求相互独立，可以在等待某个请求时推进其他请求：

发起请求1 ─┐
发起请求2 ─┼→ 分别等待 → 谁先完成先处理谁
发起请求3 ─┘

同样的模型也会出现在：

DNS查询
HTTP请求
数据库查询
Redis请求
Kafka或MongoDB访问
文件I/O
多个客户端连接

如果请求之间存在依赖：

A的结果决定B的参数
B的结果决定C的参数

业务顺序仍然必须是 A → B → C。协程不能消除真实依赖，但可以在 A 等待期间调度其他不相关协程。

五、从回调流程演化到协程流程

5.1 回调写法

三个请求流程可以写成：

请求流程1
callback(){
 recv();
 send(fd,cb);
 }
 func{
 send_http(fd,callback)
switch(1,2)
 }

请求流程2
callback(){
 recv();
 send(fd,cb);
 }
 func{
 switch(2,3)
 send(fd,callback)
 }

请求流程3
callback(){
 recv();
 send(fd,cb);
 }
 func{
 send(fd,callback)
 switch(3,1)
 }

业务被拆散到多个 callback 中，切换关系也混在业务代码里。

5.2 协程期望的写法

希望得到的目标形式：

请求流程1

 func{
 setjmp();
asyn_send(fd,callback)

asyn_recv(fd,buffer)
 }

其他请求也保持相同的顺序结构：

请求流程2

 func{
asyn_send(fd,callback)

asyn_recv(fd,buffer)
 }

请求流程3

 func{
asyn_send(fd,callback)

asyn_recv(fd,buffer)
 }

表面看起来仍然是：

发送
 ↓
接收
 ↓
处理

但 asyn_recv() 发现 fd 尚未就绪时，不阻塞整个线程，而是让出当前协程：

async_xxx(){
if(1==poll(fd,0)){
switch();
}
}

它表达的思想是：

I/O已经就绪
 → 当前协程继续执行

I/O尚未就绪
 → 保存当前协程上下文
 → yield到调度器
 → 调度其他协程
 → fd就绪后resume回来

所以协程不是把阻塞 I/O 变快，而是在等待发生时切走。

六、协程必须具备哪些原语

最基础的协程原语可以概括为：

create → 创建协程
resume → 从调度器进入协程
yield → 协程主动让出执行权
exit → 协程执行结束
switch → 保存一个上下文并恢复另一个上下文

与 I/O 调度结合后还需要：

wait_io(fd, event) → 当前协程等待某个fd事件
wakeup(coroutine) → fd就绪后把协程变为可运行
schedule() → 选择下一个可运行协程

三者之间的关系：

resume和yield → 面向协程业务语义
switch → 底层上下文切换动作
schedule → 决定下一次resume谁

七、上下文到底是什么

协程执行到一半切走，之后还要从原位置继续，因此必须保存执行现场。

上下文通常包括：

程序计数器/指令位置
栈指针
通用寄存器
部分调用约定要求保存的寄存器
协程自己的栈
协程状态

如果只记住“执行到了哪一行”，但没有保存栈和寄存器，函数局部变量、返回地址和调用关系就无法恢复。

栈式协程通常需要：

每个协程一个独立栈
每个协程一份上下文
一个调度器上下文

I/O 模型中常见的是：

fd就绪事件
 → 找到等待这个fd的协程
 → 将协程加入ready队列

并不是 fd 本身天然等于协程；实现可以选择“一连接一协程”“一请求一协程”，也可以让一个协程等待多个事件。

八、实现上下文切换的三种方式

常见的实现方式：

1. setjmp / longjmp
2. ucontext
3. 汇编保存和恢复寄存器，例如 ntyco

8.1 setjmp / longjmp

setjmp() 保存可以恢复的执行环境，longjmp() 跳回该位置。

它适合帮助理解“保存位置并跳回来”，但它本身不自动为每个协程创建独立栈。要实现完整栈式协程，还要管理协程栈和更完整的上下文。

8.2 ucontext

ucontext 提供：

getcontext() → 获取当前上下文
makecontext() → 为上下文指定入口函数
swapcontext() → 保存当前上下文并切换到目标上下文
setcontext() → 直接恢复某个上下文

它非常适合教学，因为能够明确看到栈、入口函数和上下文切换。

ucontext 已从 POSIX.1-2008 中移除，不适合作为现代跨平台库的统一标准接口，但很多 Unix/Linux 环境仍然提供它。

8.3 汇编切换

汇编实现会按照目标架构和调用约定，直接保存、恢复必要寄存器和栈指针。

优点：

可控制保存哪些寄存器
切换路径短
适合高性能协程库

代价：

与CPU架构相关
与ABI和调用约定相关
移植成本更高
实现错误容易破坏栈

ntyco 采用汇编方式实现底层上下文切换。

九、setjmp / longjmp 原代码

setjmp / longjmp 示例代码：

#include<setjmp.h>
#include<stdio.h>
jmp_buf env;//上下文环境
void func(int arg){
 printf("func: %d\n",arg);
 longjmp(env,++arg);
}
int main(){
 
 int ret=setjmp(env);
 if(ret==0){
 func(ret);
 }else if(ret==1){
 func(ret);
 }else if(ret==2){
 func(ret);
 }else if(ret==3){
 func(ret);
 }


 return 0; 

}

9.1 jmp_buf

jmp_buf env;//上下文环境

env 用来保存 setjmp() 所需的执行环境。

9.2 第一次 setjmp()

int ret=setjmp(env);

直接调用 setjmp() 时返回 0：

ret = 0
 ↓
进入if(ret==0)
 ↓
func(0)

9.3 longjmp()

longjmp(env,++arg);

func(0) 中 arg 先变成 1，再跳回 setjmp() 保存的位置。

这一次 setjmp() 看起来像重新返回，并得到：

ret = 1

于是进入：

}else if(ret==1){
 func(ret);
}

执行过程：

setjmp首次返回0
 ↓
func(0)打印func: 0
 ↓ longjmp(...,1)
setjmp恢复后返回1
 ↓
func(1)打印func: 1
 ↓ longjmp(...,2)
setjmp恢复后返回2
 ↓
func(2)打印func: 2
 ↓ longjmp(...,3)
setjmp恢复后返回3
 ↓
func(3)打印func: 3
 ↓ longjmp(...,4)
setjmp恢复后返回4
 ↓
没有匹配分支，main结束

预期打印：

func: 0
func: 1
func: 2
func: 3

这段代码展示的是控制流跳转，还不是完整的多协程调度器。

十、ucontext 原代码：三个协程和 main 上下文

ucontext 示例代码：

#include<stdio.h>
#include<ucontext.h>

ucontext_t ctx[3];
ucontext_t main_ctx;
int count=0;
//coroutine1
void func1(void){
 while(count++<30){
 printf("1\n");
 //swapcontext(&ctx[0],&ctx[1]);
 swapcontext(&ctx[0],&main_ctx);
 printf("4\n");
 }

}
//coroutine2
void func2(void){
 while(count++<30){
 printf("2\n");
 //swapcontext(&ctx[1],&ctx[2]);
 swapcontext(&ctx[1],&main_ctx);
 printf("5\n");
 }



}
//coroutine3
void func3(void){
 while(count++<30){
 printf("3\n");
	//swapcontext(&ctx[2],&ctx[0]);
	swapcontext(&ctx[2],&main_ctx);
 printf("6\n");
 }



}
//schedule
int main(){

 char stack1[2048]={0};
 char stack2[2048]={0};
 char stack3[2048]={0}; 
 getcontext(&ctx[0]);
 ctx[0].uc_stack.ss_sp=stack1;
 ctx[0].uc_stack.ss_size=sizeof(stack1);
 ctx[0].uc_link=&main_ctx;
 makecontext(&ctx[0],func1,0);

 
 getcontext(&ctx[1]);
 ctx[1].uc_stack.ss_sp=stack2;
 ctx[1].uc_stack.ss_size=sizeof(stack2);
 ctx[1].uc_link=&main_ctx;
 makecontext(&ctx[1],func2,0); 

 getcontext(&ctx[1]);
 ctx[2].uc_stack.ss_sp=stack3;
 ctx[2].uc_stack.ss_size=sizeof(stack3);
 ctx[2].uc_link=&main_ctx;
 makecontext(&ctx[1],func3,0); 

 printf("swapcontext\n");
 swapcontext(&main_ctx,&ctx[0]);
 int i=30;
 while(count<30){
 swapcontext(&main_ctx,&ctx[count%3]);
 }
 printf("\n");






 return 0;
}

这段代码希望建立：

main_ctx → 调度器上下文
ctx[0] → func1协程
ctx[1] → func2协程
ctx[2] → func3协程

阅读第三个协程的初始化时，要按照这个对应关系理解：

ctx[2]使用stack3
ctx[2]的入口函数是func3

十一、如何创建一个 ucontext 协程

以第一个协程为例。

11.1 保存初始上下文

getcontext(&ctx[0]);

ctx[0] 获得一份可继续配置的上下文。

11.2 指定独立栈

ctx[0].uc_stack.ss_sp=stack1;
ctx[0].uc_stack.ss_size=sizeof(stack1);

含义：

stack1 → 栈起始地址
sizeof(stack1) → 栈大小
ctx[0].uc_stack → ctx[0]使用的协程栈

三个协程分别使用：

ctx[0] → stack1
ctx[1] → stack2
ctx[2] → stack3

独立栈让不同协程能够保存自己的函数调用关系和局部变量。

11.3 指定返回去向

ctx[0].uc_link=&main_ctx;

如果 func1 正常执行完并返回，运行时会转到 main_ctx。

uc_link 处理的是入口函数正常返回后的去向；func1 中主动调用 swapcontext() 则是显式 yield。

11.4 指定入口函数

makecontext(&ctx[0],func1,0);

含义：

ctx[0]第一次被resume时
 ↓
从func1开始执行
 ↓
func1没有参数

最后一个 0 表示传给 func1 的参数数量为 0。

十二、swapcontext()：保存当前上下文并恢复另一个

函数形式：

swapcontext(&from,&to);

可以理解成：

把当前执行现场保存到from
 ↓
恢复to中的执行现场
 ↓
开始运行to

12.1 main resume 第一个协程

swapcontext(&main_ctx,&ctx[0]);

含义：

保存main当前执行位置到main_ctx
 ↓
恢复ctx[0]
 ↓
第一次进入func1

func1 打印：

printf("1\n");

12.2 func1 yield 回 main

swapcontext(&ctx[0],&main_ctx);

含义：

保存func1当前执行位置到ctx[0]
 ↓
恢复main_ctx
 ↓
main从刚才swapcontext之后继续

func1 的执行位置停在：

swapcontext(&ctx[0],&main_ctx);

下一次 main 再 resume ctx[0] 时，swapcontext() 返回，继续执行：

printf("4\n");

这就是协程能够“从上次让出的位置继续”的原因。

十三、yield、resume 和 switch

三者的对应关系：

main → ctx[0] → resume协程
ctx[0] → main → yield协程
swapcontext() → 底层switch动作

13.1 resume

调度器选择一个协程
 ↓
从main_ctx切到该协程ctx
 ↓
协程开始或继续运行

13.2 yield

协程遇到I/O等待或主动让出
 ↓
保存自己的ctx
 ↓
切回main_ctx
 ↓
调度器选择其他协程

13.3 switch

switch 不关心为什么切换，只负责：

保存from
恢复to

resume 和 yield 是对 switch 在不同业务方向上的命名。

十四、当前调度器如何工作

原代码：

while(count<30){
 swapcontext(&main_ctx,&ctx[count%3]);
}

count % 3 的结果不断在 0、1、2 之间变化：

count % 3 == 0 → resume ctx[0]
count % 3 == 1 → resume ctx[1]
count % 3 == 2 → resume ctx[2]

因此它相当于一个简单轮询调度器：

main
 ↓
ctx[0]运行一段后yield
 ↓
main
 ↓
ctx[1]运行一段后yield
 ↓
main
 ↓
ctx[2]运行一段后yield
 ↓
main继续轮询

这些上下文的栈关系可以画成：

ctx3独立栈
ctx2独立栈
ctx1独立栈
main栈

这些栈并不是垂直嵌套成一条普通函数调用链，而是各自保存执行现场，由 swapcontext() 在它们之间切换。

十五、为什么当前轮询还不是 I/O 调度器

当前策略只根据：

ctx[count%3]

选择协程，它不知道：

哪个协程正在等待fd
哪个fd已经就绪
哪个协程已经结束
哪个协程可以立即运行

真正的 I/O 协程调度需要至少维护：

ready队列 → 当前可以运行的协程
waiting集合 → 等待I/O、定时器或条件的协程
epoll → 检测fd就绪
协程状态 → NEW、READY、RUNNING、WAITING、DEAD

典型过程：

协程调用异步recv
 ↓
数据尚未就绪
 ↓
把“fd → 当前协程”注册给调度器
 ↓
当前协程状态变成WAITING
 ↓
yield回调度器
 ↓
调度器resume其他READY协程
 ↓
epoll报告fd可读
 ↓
对应协程进入READY队列
 ↓
调度器再次resume它
 ↓
recv继续执行

这个过程才真正实现：

代码看起来在等待 recv，但线程没有被这个协程阻塞。

十六、协程结构体需要保存什么

进一步实现时需要定义 struct coroutine。根据前面的执行过程，它至少需要表达：

协程ID
协程状态
上下文
独立栈和栈大小
入口函数
入口参数
所属调度器
等待的fd和事件
退出结果或错误

概念结构：

struct coroutine
 ├── id
 ├── state
 ├── context
 ├── stack
 ├── function
 ├── argument
 ├── waiting_fd
 └── scheduler

这里先理解字段为什么存在，不需要脱离后续 ntyco 代码自行发明另一套结构。

十七、调度器需要保存什么

调度器负责管理所有协程并决定下一次运行谁。

概念结构：

struct scheduler
 ├── main_context
 ├── current_coroutine
 ├── ready_queue
 ├── waiting_coroutines
 ├── epoll_fd
 ├── timer
 └── all_coroutines

调度器要回答：

当前运行的是谁
哪些协程可以运行
哪些协程在等待I/O
哪些协程等待超时
fd就绪后应该唤醒谁
协程退出后怎样回收

十八、如何封装 POSIX API

一个重要设计目标，是让协程网络库尽量保持熟悉的 POSIX 调用方式。

期望上层仍然写：

connect
accept
recv
send
close

但协程封装后的行为是：

调用recv
 ↓
先尝试非阻塞recv
 ├── 已就绪：直接返回结果
 └── EAGAIN：注册EPOLLIN并yield
 ↓
 fd就绪
 ↓
 resume协程
 ↓
 再次尝试recv

这样业务代码保留同步风格，但底层仍然由 epoll 和协程调度实现异步等待。

“接口一致”不代表直接调用阻塞版本的 POSIX API，而是协程库提供行为兼容的包装层或 hook。

十九、协程怎样用于 WebServer

已有 Reactor WebServer 的逻辑：

epoll_wait
 ↓
recv_cb
 ↓
http_request
 ↓
send_cb
 ↓
http_response

协程模型可以把一个连接或一个请求组织成顺序流程：

协程开始
 ↓
等待并接收HTTP请求
 ↓
解析HTTP
 ↓
查询数据库或缓存
 ↓
构造HTTP响应
 ↓
发送响应
 ↓
等待下一次请求或退出

遇到 fd 尚未就绪时：

当前协程yield
 ↓
线程继续处理其他连接协程
 ↓
fd就绪后resume

Reactor 与协程不是互斥关系：

Reactor/epoll → 检测事件
协程调度器 → 把事件转换成协程唤醒
协程 → 承载顺序业务流程

二十、微信群聊场景应该怎样思考

思考这个场景时，不必急着寻找固定答案，先建立分析框架。

面对“微信群聊如何使用协程”时，可以依次问：

1. 一个协程对应一个连接、一个用户，还是一次消息处理？
2. 连接没有消息时，协程处于什么状态？
3. fd可读后，谁把对应协程唤醒？
4. 一条消息需要广播给多人时，哪些步骤能够并发？
5. 慢客户端发送不出去时，是否会阻塞其他用户？
6. 每个连接的发送队列放在哪里？
7. 用户断开以后，协程、fd和缓冲区如何回收？
8. 心跳和超时由谁管理？
9. 群消息顺序如何保证？
10. 多核模式下，同一个连接能否跨调度器迁移？

可以先画：

用户A连接协程
 ↓ 收到群消息
服务端业务处理
 ↓
找到群成员
 ↓
把消息加入B/C/D的发送队列
 ↓
对应连接可写时唤醒发送流程

重点不是简单回答“一个用户一个协程”，而是明确：

协程在哪里等待
什么事件唤醒
状态保存在哪里
慢连接如何隔离

二十一、协程的多核模式

单个调度器通常运行在一个线程中，同一时刻只能使用一个 CPU 核。

多核模式常见思路：

一个线程一个调度器
 ↓
每个调度器拥有自己的epoll和ready队列
 ↓
多个线程并行运行

这形成 M:N 模型：

M个协程
 ↓ 用户态调度
N个内核线程
 ↓
多个CPU核

需要处理：

连接如何分配到各调度器
协程是否允许跨线程迁移
跨线程唤醒
共享队列和锁
负载均衡
work stealing
线程局部状态

上下文通常只能在它所属的线程和栈环境中安全切换，不能随意把 setjmp/ucontext 保存的上下文拿到另一个线程恢复。

二十二、协程性能如何测试

不能只看一个“每 1000 连接耗时”。协程性能至少分成四层。

22.1 原语性能

创建一个协程的耗时
一次yield/resume的耗时
每秒可以上下文切换多少次
销毁协程的耗时

22.2 内存

每个协程结构体大小
每个协程栈大小
一万或百万协程的总内存
栈是否按需增长

22.3 I/O 服务性能

并发连接数
QPS
吞吐量
P50/P95/P99延迟
超时和错误率
CPU使用率
上下文切换次数

22.4 对比基线

应在相同业务和负载下比较：

单线程Reactor
Reactor + 线程池
Reactor + 协程
一连接一线程

只有测试业务、连接数、响应大小和日志配置相同，结果才有可比性。

二十三、核心总结

重点一：协程不是为了创造真正并行

单线程协程仍然只使用一个CPU核
协程的主要价值是等待I/O时切换任务
多核需要多个调度线程配合

重点二：协程结合了两种优点

上层：同步顺序代码，容易理解
底层：异步事件等待，不阻塞整个线程

重点三：上下文和独立栈是恢复执行的基础

上下文 → 记录执行现场
协程栈 → 保存函数调用和局部变量
switch → 保存一个上下文，恢复另一个

重点四：yield、resume 与调度器

resume → 调度器进入协程
yield → 协程返回调度器
switch → 完成底层上下文切换
scheduler → 决定下一个运行谁

重点五：真正的 I/O 协程需要 epoll

recv遇到EAGAIN
 ↓
协程注册等待EPOLLIN
 ↓
yield
 ↓
epoll报告fd可读
 ↓
协程进入ready队列
 ↓
resume
 ↓
继续recv和后续业务

最终理解：

协程不是替代 epoll，而是建立在事件驱动之上，把回调式异步流程重新组织成可顺序阅读的业务代码。

Reactor 在 WebServer 与 WebSocket 中的应用

Sun, 09 Aug 2026 00:00:00 +0800

本篇是《网络IO》《IO 多路复用与 Reactor》《Reactor 与 epoll：百万并发网络服务器》的后续实践。
socket、fd、select、poll、epoll 接口、连接对象和 Reactor 基础不再重复；本篇只整理这节课新增的 LT/ET、HTTP WebServer、文件发送状态机和 WebSocket。

一、本节课做了什么

前一节已经搭好了 Reactor 网络层，本节在它上面接入两种协议业务：

reactor.c：网络 I/O 层
 ├── recv_cb()
 └── send_cb()

webserver.c：HTTP 协议层
 ├── http_request()
 └── http_response()

websocket.c：WebSocket 协议层
 ├── ws_request()
 └── ws_response()

本节最重要的调用链：

clientfd 出现 EPOLLIN
 ↓
recv_cb() 调用 recv()
 ↓
http_request() / ws_request()
 ↓
set_event(fd, EPOLLOUT, 0)
 ↓
clientfd 出现 EPOLLOUT
 ↓
send_cb()
 ↓
http_response() / ws_response()
 ↓
send()
 ↓
set_event(fd, EPOLLIN, 0)

因此，Reactor 与协议层的分工是：

reactor.c → 关心 fd 是否可读、可写，以及 recv/send
webserver.c → 关心 HTTP 请求和 HTTP 响应
websocket.c → 关心握手、帧解码和帧编码

二、LT 与 ET

2.1 LT：水平触发

只要内核接收缓冲区中还有数据，LT 就会继续报告可读事件。

例如客户端发送 32 字节，服务端一次只接收 10 字节：

第一次 recv：10 字节，剩余 22
第二次 recv：10 字节，剩余 12
第三次 recv：10 字节，剩余 2
第四次 recv：2 字节，接收完成

2.2 ET：边沿触发

ET 主要关注从“没有数据”到“有数据”的状态变化。收到一次通知后，应在当前回调中尽量把数据处理完。

当前代码在 accept_cb() 中这样注册客户端：

event_rigister(clientfd,EPOLLIN|EPOLLET);//|EPOLLET

这表示 clientfd 使用 ET，并且先关注可读事件。

ET 的处理思路：

accept_cb() → 持续 accept，直到当前没有新连接
recv_cb() → 持续 recv，直到当前数据读完
send_cb() → 持续推进发送，直到发完或暂时不可写

循环读取时要配合非阻塞 fd。当前没有更多数据时，recv() 返回 -1，并且 errno 为 EAGAIN 或 EWOULDBLOCK，这表示本轮读取结束，应回到事件循环。

LT 和 ET 都不能决定 HTTP 请求或 WebSocket 帧是否完整。TCP 是字节流，协议层仍然需要根据协议格式判断消息边界。

三、`recv_cb()`：从网络层进入协议层

本节使用你提交的原代码：

int recv_cb(int fd){
 memset(conn_list[fd].rbuffer,0,BUFFER_LENGTH);
	int count = recv(fd, conn_list[fd].rbuffer, BUFFER_LENGTH, 0);
	if (count == 0) { // disconnect
		printf("client disconnect: %d\n", fd);
		close(fd);

 epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);//unfinished

		return -1;

				}else if(count<0){
 printf("count:%d,errno:%d ,%s\n", count,errno,strerror(errno));
		 close(fd);
 epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);//unfinished
 return 0;
 }
 conn_list[fd].rlength=count;
 // printf("RECV: %s\n", conn_list[fd].rbuffer);
#if 0//echo
 conn_list[fd].wlength=conn_list[fd].rlength;
 memcpy(conn_list[fd].wbuffer,conn_list[fd].rbuffer,conn_list[fd].wlength);
 printf("[%d]RECV: %s\n",conn_list[fd].rlength,conn_list[fd].rbuffer);
#elif0
 http_request(&conn_list[fd]);
#else 
 ws_request(&conn_list[fd]);
#endif

 set_event(fd,EPOLLOUT,0);
 return count;
}

3.1 接收数据

int count = recv(fd, conn_list[fd].rbuffer, BUFFER_LENGTH, 0);

数据从内核 socket 接收缓冲区复制到当前连接的 rbuffer，实际接收长度保存到：

conn_list[fd].rlength=count;

3.2 三种业务切换

Echo 分支把收到的数据复制到写缓冲区：

#if 0//echo
 conn_list[fd].wlength=conn_list[fd].rlength;
 memcpy(conn_list[fd].wbuffer,conn_list[fd].rbuffer,conn_list[fd].wlength);
 printf("[%d]RECV: %s\n",conn_list[fd].rlength,conn_list[fd].rbuffer);

HTTP 分支把连接对象交给 `http_request()`：

```c
#elif0
 http_request(&conn_list[fd]);
```

WebSocket 分支把连接对象交给 `ws_request()`：

```c
#else 
 ws_request(&conn_list[fd]);
```

三种业务共用同一个 `recv_cb()`，只替换上层协议处理函数。这正是 Reactor 与业务分层后的好处。

3.3 从读事件切换到写事件

set_event(fd,EPOLLOUT,0);

http_request() 或 ws_request() 处理完输入后，当前 fd 改为关注 EPOLLOUT。等 socket 可写时，Reactor 会调用 send_cb()。

四、HTTP 请求：`http_request()`

浏览器访问服务器时，会发送类似内容：

GET / HTTP/1.1
Host: 172.16.145.129:2000
Connection: keep-alive
Upgrade-Insecure-Requests: 1
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
Accept: text/html,application/xhtml+xml,application/xml
Accept-Encoding: gzip, deflate
Accept-Language: zh-CN,zh;q=0.9,en;q=0.8

请求由请求行、请求头、空行和可选 body 组成：

GET / HTTP/1.1 → 请求行
Host → 请求头
Connection → 请求头
User-Agent → 请求头
空行 → 请求头结束

原代码：

int http_request(struct conn *c){
 //printf("request: %s\n",c->rbuffer);
 memset(c->wbuffer,0,BUFFER_LENGTH);
 c->wlength=0;
 c->status=0;
}

当前 http_request() 主要完成一次新响应的状态初始化：

c->rbuffer → 当前 HTTP 请求
c->wbuffer → 清空，准备写响应
c->wlength → 置 0
c->status → 置 0，从响应状态机起点开始

它位于：

recv_cb() 之后
send_cb() 之前

五、HTTP 响应：直接返回 HTML

原代码：

int http_response(struct conn *c){
#if 1
 c->wlength=sprintf(c->wbuffer,"HTTP/1.1 200 OK\r\n"
 "Content-Type: text/html\r\n"
 "Accept-Ranges: bytes\r\n"
 "Content-Length: 82\r\n"
 "Date: Tue,30 Apr 2024 13:16:46 GMT\r\n\r\n"
 "<html><head><title>0voice.king</title></head><body><h1>King</h1></body></html>\r\n\r\n");
 return 0;

其中：

HTTP/1.1 200 OK
Content-Type: text/html
Accept-Ranges: bytes
Content-Length: 82
Date: Tue,30 Apr 2024 13:16:46 GMT

是 HTTP 状态行和响应头。它们告诉浏览器响应是否成功、body 是什么类型、长度是多少。

下面是 HTTP body：

<html><head><title>0voice.king</title></head><body><h1>King</h1></body></html>

浏览器看到 Content-Type: text/html 后，会把 body 当作 HTML 渲染，页面中显示 King。

这一分支中，HTTP 头和 body 一起写入：

c->wbuffer

总长度由 sprintf() 的返回值保存到：

c->wlength

调用链：

recv_cb()
 ↓
http_request()
 ↓
设置 EPOLLOUT
 ↓
send_cb()
 ↓
http_response()
 ↓
HTTP 头和 HTML 写入 wbuffer
 ↓
send()

六、返回 `index.html`

原代码：

#elif 0
 int filefd =open("index.html",O_RDONLY);
 struct stat stat_buf;
 fstat(filefd,&stat_buf);
 c->wlength=sprintf(c->wbuffer,"HTTP/1.1 200 OK\r\n"
 "Content-Type: text/html\r\n"
 "Accept-Ranges: bytes\r\n"
 "Content-Length: %ld\r\n"
 "Date: Tue,30 Apr 2024 13:16:46 GMT\r\n\r\n",
 stat_buf.st_size);

 int count=read(filefd,c->wbuffer+c->wlength,BUFFER_LENGTH-c->wlength);
 c->wlength +=count;

 close(filefd);

执行过程：

open("index.html")
 ↓
fstat() 得到文件大小
 ↓
HTTP 响应头写入 wbuffer
 ↓
read() 把 index.html 追加在 HTTP 头后面
 ↓
wlength = HTTP 头长度 + 本次文件读取长度
 ↓
send_cb() 发送整个 wbuffer

stat_buf.st_size 被写入：

Content-Length: 文件大小

这个分支的特点是：HTTP 头和文件内容都先进入应用层 wbuffer，然后统一调用 send()。

七、状态机与 `sendfile()`

当一个响应需要多个发送阶段时，课程使用 status 保存当前进度：

status = 0 → 构造并发送 HTTP 头
status = 1 → 持续发送文件
status = 2 → 文件发送结束，清理状态

原代码：

#elif 0
 int filefd =open("index.html",O_RDONLY);
 struct stat stat_buf;
 fstat(filefd,&stat_buf);
 if(c->status==0){
 c->wlength=sprintf(c->wbuffer,"HTTP/1.1 200 OK\r\n"
 "Content-Type: text/html\r\n"
 "Accept-Ranges: bytes\r\n"
 "Content-Length: %ld\r\n"
 "Date: Tue,30 Apr 2024 13:16:46 GMT\r\n\r\n",
 stat_buf.st_size);
 c->status=1;
 }else if (c->status==1){
 int ret=sendfile(c->fd,filefd,NULL,stat_buf.st_size);
 if(ret==-1){
 printf("error:%d\n",errno);
 }
 //c->wlength=0;
 memset(c->wbuffer,0,BUFFER_LENGTH);
 c->status=2;
 }else if(c->status==2){

 c->wlength=0;
 memset(c->wbuffer,0,BUFFER_LENGTH);
 c->status=0;
 }
 close(filefd);

状态流转：

第一次进入 http_response()
 ↓ status == 0
构造 HTTP 响应头
 ↓ status = 1
send_cb() 发送 wbuffer，并继续关注 EPOLLOUT
 ↓
第二次进入 http_response()
 ↓ status == 1
sendfile() 发送 index.html
 ↓ status = 2
继续关注 EPOLLOUT
 ↓
第三次进入 http_response()
 ↓ status == 2
清理 wbuffer 和 wlength
 ↓ status = 0
重新关注 EPOLLIN

sendfile() 直接建立文件 fd 到 socket fd 的发送路径：

int ret=sendfile(c->fd,filefd,NULL,stat_buf.st_size);

协议层仍然负责构造 HTTP 头，sendfile() 负责发送文件内容。状态机把两个阶段连接起来。

八、返回图片

图片与 HTML 在网络层都是字节数据，主要区别是 HTTP 的 Content-Type。

原代码：

#else
int filefd =open("vip.png",O_RDONLY);
 struct stat stat_buf;
 fstat(filefd,&stat_buf);
 if(c->status==0){
 c->wlength=sprintf(c->wbuffer,"HTTP/1.1 200 OK\r\n"
 "Content-Type: image/png\r\n"
 "Accept-Ranges: bytes\r\n"
 "Content-Length: %ld\r\n"
 "Date: Tue,30 Apr 2024 13:16:46 GMT\r\n\r\n",
 stat_buf.st_size);
 c->status=1;
 }else if (c->status==1){
 int ret=sendfile(c->fd,filefd,NULL,stat_buf.st_size);
 if(ret==-1){
 printf("error:%d\n",errno);
 }
 //c->wlength=0;
 memset(c->wbuffer,0,BUFFER_LENGTH);
 c->status=2;
 }else if(c->status==2){

 c->wlength=0;
 memset(c->wbuffer,0,BUFFER_LENGTH);
 c->status=0;
 }
 close(filefd);

与 HTML 文件的区别：

响应内容	打开的文件	Content-Type
网页	`index.html`	`text/html`
PNG 图片	`vip.png`	`image/png`

Reactor 的 recv_cb()、send_cb() 不需要知道 body 是网页还是图片。WebServer 协议层设置正确的响应头即可。

九、`send_cb()` 如何驱动多阶段发送

原代码：

int send_cb(int fd){
#if 0

 http_response(&conn_list[fd]);

#else
 ws_response(&conn_list[fd]);

#endif
 int count=0;
 if(conn_list[fd].status==1){
 //printf("SEND:%s\n",conn_list[fd].wbuffer);
 count = send(fd, conn_list[fd].wbuffer,conn_list[fd].wlength, 0);
 set_event(fd,EPOLLOUT,0);
}else if(conn_list[fd].status==2){
 set_event(fd,EPOLLOUT,0);
}else if(conn_list[fd].status==0){
 if(conn_list[fd].wlength !=0){
 count = send(fd, conn_list[fd].wbuffer,conn_list[fd].wlength, 0); 
 }
 set_event(fd,EPOLLIN,0);
}
 //set_event(fd,EPOLLOUT,0);
 return count;
}

9.1 选择协议响应

学习 HTTP 时，让写回调进入：

#if 0

 http_response(&conn_list[fd]);

学习 WebSocket 时，让写回调进入：

#else
 ws_response(&conn_list[fd]);

9.2 状态与事件切换

status == 1
 → send() 发送当前 wbuffer
 → 继续设置 EPOLLOUT
 → 等待下一阶段

status == 2
 → 继续设置 EPOLLOUT
 → 进入状态机清理阶段

status == 0
 → 如果 wlength 不为 0，就发送当前数据
 → 设置 EPOLLIN
 → 等待下一次请求

这就是“需要发送多次时怎么办”的答案：

保存当前发送状态，再通过后续的 EPOLLOUT 事件继续推进，而不是把整个过程强行塞进一次回调。

十、WebSocket 握手

WebSocket 用于浏览器与服务器之间的长连接和双向通信。

建立 WebSocket 连接时，浏览器先发送 HTTP Upgrade 请求，其中包括：

Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: T29c4Rys861qGqbGGNdkwA==
Sec-WebSocket-Version: 13

你提交的 WebSocket 代码：

#include"server.h"
#include<stdio.h>
#define GUID "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
/*
Key："T29c4Rys861qGqbGGNdkwA=="
T29c4Rys861qGqbGGNdkwA==258EAFA5-E914-47DA-95CA-C5AB0DC85B11
SHA-1

20 bytes
base64

handshake

transmission
decode
encode

*/

服务端计算 Sec-WebSocket-Accept 的过程：

客户端 Sec-WebSocket-Key
 +
固定 GUID
 ↓
SHA-1
 ↓
160 bit = 20 bytes
 ↓
Base64
 ↓
Sec-WebSocket-Accept

固定 GUID：

#define GUID "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"

客户端 Key 放在前面，GUID 放在后面。

服务端响应格式：

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: 计算结果

返回 101 后，同一个 TCP 连接不再传输普通 HTTP 消息，而是进入 WebSocket 帧传输阶段。

十一、WebSocket 在 Reactor 中的位置

原代码：

int ws_request(struct conn *c){
 printf("request: %s",c->rbuffer);
}

int ws_response(struct conn *c){
 
}

当前两个函数是课程为后续实现预留的协议接口。

ws_request() 后续负责：

握手阶段 → 解析 HTTP Upgrade 请求和 Sec-WebSocket-Key
传输阶段 → 解析 WebSocket frame，完成 decode

ws_response() 后续负责：

握手阶段 → 构造 101 和 Sec-WebSocket-Accept
传输阶段 → 把文本或二进制业务数据 encode 成 WebSocket frame

在 Reactor 中的调用位置：

EPOLLIN
 ↓
recv_cb()
 ↓
ws_request()
 ↓
设置 EPOLLOUT
 ↓
send_cb()
 ↓
ws_response()
 ↓
send()

WebSocket 是应用层协议，底层仍然是普通 TCP clientfd。Reactor 不需要为 WebSocket 创建一种新 fd。

十二、使用 wrk 测试 WebServer

测试命令：

wrk -t10 -c50 -d10s http://172.16.145.129:2000/

课程中的测试现象：

打印每次 request 和 Host 数据时：QPS 约 1.5 万
关闭逐请求打印后：QPS 约 4.5 万

逐请求打印会产生格式化、终端输出和系统调用开销，因此会明显降低服务器吞吐量。

wrk 结果中主要关注：

Requests/sec → 每秒请求数，即 QPS
Latency → 请求延迟
timeout → 超时数量
read/write → 读写错误
Transfer/sec → 每秒传输数据量

局域网延迟较小；公网还会受到网络时延、丢包、带宽和中间设备影响。

十三、Connection reset by peer

Connection reset by peer 表示连接被对端通过 TCP RST 重置。

常见情况：

客户端提前关闭连接
压测工具结束请求
服务器准备发送时客户端已经退出
网络设备重置连接

服务器应识别错误并清理当前连接，不要让单个客户端断开导致整个进程退出。

十四、本节课的三个重点

重点一：事件与协议函数的对应关系

clientfd + EPOLLIN
 → recv_cb()
 → http_request() / ws_request()

clientfd + EPOLLOUT
 → send_cb()
 → http_response() / ws_response()

重点二：网络层与协议层分离

reactor.c
 → 管理 fd、事件、recv、send

webserver.c
 → 处理 HTTP request 和 response

websocket.c
 → 处理 handshake、decode 和 encode

重点三：多次发送使用状态机

一次发送即可完成
 → wbuffer + wlength

需要多个发送阶段
 → status 保存进度
 → 多次 EPOLLOUT 推进

发送静态文件
 → HTTP 头放入 wbuffer
 → 文件内容交给 sendfile()

最终理解：

Reactor 提供统一的事件驱动网络层；HTTP 和 WebSocket 负责协议，业务数据何时读取、何时发送，由 fd 的事件和回调共同驱动。

Reactor 与 epoll：百万并发网络服务器

Sat, 08 Aug 2026 00:00:00 +0800

1. 本节课要解决什么问题

本节课不是直接实现完整 WebServer，而是先搭建一个能够承载大量网络连接的底层 I/O 框架。在这个框架之上，后续才能继续实现 HTTP 解析、路由、业务处理等功能。

核心目标有两个：

使用 Linux epoll 管理大量 socket。
使用 Reactor 思想，把不同 I/O 事件分发给不同回调函数。

当前代码实现的是一个简单的多端口 Echo Server：客户端发来什么，服务端就回写什么。

2. Reactor 的核心思想

Reactor 可以概括为：

I/O 对象（fd） → 发生事件（event） → 执行回调（callback）

本例中的映射关系如下：

I/O 对象	事件	含义	回调函数
`listenfd`	`EPOLLIN`	有新连接到达	`accept_cb()`
`clientfd`	`EPOLLIN`	客户端数据可读	`recv_cb()`
`clientfd`	`EPOLLOUT`	socket 当前可写	`send_cb()`

因此，主循环不需要判断“这个 fd 到底要做什么业务”，而只需要：

调用 epoll_wait() 等待事件。
从事件中取得 fd。
根据事件类型，调用该 fd 已经注册好的回调。

这就是“事件驱动”：没有事件时线程阻塞等待，有事件时才处理对应连接。

2.1 Reactor 的两个重点

建立 event 与 callback 的对应关系。
为每一个 I/O 保存独立的连接状态。

第二点非常重要。多个连接的数据不能共用一组读写缓冲区，否则连接之间会互相覆盖。因此每个 fd 都需要自己的：

读缓冲区 rbuffer
当前读取长度 rlength
写缓冲区 wbuffer
待发送长度 wlength
读事件回调
写事件回调

3. `epoll` 在 Reactor 中的职责

epoll 是 Linux 提供的 I/O 多路复用机制。一个线程可以通过一个 epoll 实例监听大量 fd，而不必给每条 TCP 连接创建一个线程。

三个最重要的接口是：

int epoll_create1(int flags);
int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);
int epoll_wait(int epfd, struct epoll_event *events,
 int maxevents, int timeout);

其作用分别为：

epoll_create1()：创建一个 epoll 实例。
epoll_ctl()：添加、修改或删除所关注的 fd 和事件。
epoll_wait()：等待已经注册的 fd 产生事件。

当前代码使用的是默认的 LT（Level Triggered，水平触发）模式，因为没有设置 EPOLLET。

LT 模式下，只要 fd 仍处于可读或可写状态，epoll_wait() 就会继续报告它。若以后改成 ET（边沿触发），则 socket 必须设置成非阻塞，并且 accept()、recv() 等操作通常要循环执行，直到返回 EAGAIN。

4. 代码中的连接对象

struct conn {
 int fd;

 char rbuffer[BUFFER_LENGTH];
 int rlength;

 char wbuffer[BUFFER_LENGTH];
 int wlength;

 RCALLBACK send_callback;
 union {
 RCALLBACK recv_callback;
 RCALLBACK accept_callback;
 } r_action;
};

4.1 为什么需要 `struct conn`

TCP 是字节流协议，一次 recv() 不保证收到一个完整业务消息：

一个完整消息可能被拆成多次接收。
多个消息也可能在一次 recv() 中一起到达。
一次 send() 也不保证发送全部待发送数据。

所以 Reactor 不仅要保存回调，还必须保存每个连接的处理进度。严格来说，后续还应增加：

已读取但尚未解析的数据偏移量；
待发送数据的起始偏移量；
协议解析状态；
连接状态和超时信息；
动态扩容或链式缓冲区。

4.2 为什么 `accept_callback` 与 `recv_callback` 使用 `union`

监听 fd 的读事件表示“有连接可接受”，其回调是 accept_cb()；客户端 fd 的读事件表示“有数据可接收”，其回调是 recv_cb()。

同一个 fd 在这里不会同时既是监听 fd 又是客户端 fd，因此两个函数指针可以共用同一块存储空间。union 表达了二者“二选一”的关系。

不过，代码在赋值时使用了：

conn_list[sockfd].r_action.recv_callback = accept_cb;

语义上更清晰的写法是：

conn_list[sockfd].r_action.accept_callback = accept_cb;

调用时也应根据 fd 的角色使用对应成员，或者直接将二者合并成一个名称更通用的 read_callback。

4.3 为什么可以用 fd 作为数组下标

当前代码使用：

struct conn conn_list[CONNECTION_SIZE];

并直接通过 conn_list[fd] 找到连接。这种方法查找复杂度为 O(1)，非常直接。

但它有两个条件：

必须保证 0 <= fd < CONNECTION_SIZE，否则会越界。
数组内存非常大。

每个连接对象包含两个 1024 字节缓冲区，再加上长度、fd 和函数指针。100 多万个元素大约需要 2 GiB 以上的地址空间和可观的实际内存。因此“支持 100 万个 fd”不等于“采用这种结构后机器就一定能稳定承载 100 万连接”。生产实现通常会根据实际连接动态分配，或者按块分配连接对象与缓冲区。

5. 程序完整执行流程

5.1 初始化 epoll

代码中：

epfd = epoll_create(1);

参数在现代 Linux 中只要大于 0 即可，并不表示只能监听一个 fd。更推荐：

epfd = epoll_create1(EPOLL_CLOEXEC);

创建失败时必须检查返回值。

5.2 创建 20 个监听 socket

for (i = 0; i < MAX_PORTS; i++) {
 int sockfd = init_server(port + i);
 ...
}

程序监听 2000~2019 共 20 个端口。每个监听 fd 都注册 EPOLLIN，并对应 accept_cb()。

监听 fd 上的 EPOLLIN 不是普通业务数据可读，而是表示全连接队列中存在已经完成握手、可以由 accept() 取出的连接。

5.3 接受新连接

accept_cb() 的逻辑是：

调用 accept()，获得 clientfd。
检查 clientfd < 0。
初始化 conn_list[clientfd]。
给客户端 fd 注册 EPOLLIN。

这时事件映射从：

listenfd + EPOLLIN → accept_cb

变成新连接上的：

clientfd + EPOLLIN → recv_cb

5.4 接收数据

当客户端 fd 可读时执行 recv_cb()：

count = recv(fd, conn_list[fd].rbuffer, BUFFER_LENGTH, 0);

当前 Echo 逻辑把收到的数据复制到写缓冲区：

conn_list[fd].wlength = conn_list[fd].rlength;
memcpy(conn_list[fd].wbuffer,
 conn_list[fd].rbuffer,
 conn_list[fd].wlength);

随后把关注事件修改为 EPOLLOUT：

clientfd + EPOLLOUT → send_cb

5.5 发送数据

当 fd 可写时执行 send_cb()。数据发送结束后，再把关注事件切换回 EPOLLIN，等待客户端下一次发送。

完整状态流转如下：

监听 EPOLLIN
 ↓
accept_cb：建立 clientfd
 ↓
客户端 EPOLLIN
 ↓
recv_cb：接收并准备响应
 ↓
客户端 EPOLLOUT
 ↓
send_cb：发送响应
 ↓
重新监听客户端 EPOLLIN

6. `set_event()` 与事件注册

int set_event(int fd, int event, int flag)

当前约定：

flag == 1：使用 EPOLL_CTL_ADD。
flag == 0：使用 EPOLL_CTL_MOD。

功能上可行，但 flag 的含义不直观。更清晰的设计是直接传入 EPOLL_CTL_ADD、EPOLL_CTL_MOD，或者分别封装成 add_event() 和 mod_event()。

同时必须检查 epoll_ctl() 的返回值。例如：

if (epoll_ctl(epfd, op, fd, &ev) == -1) {
 perror("epoll_ctl");
 return -1;
}

set_event() 和 event_rigister() 声明为返回 int，但成功路径没有 return，这属于未定义行为。应补充 return 0。另外，rigister 应改为 register。

7. 主事件循环

while (1) {
 int nready = epoll_wait(epfd, events, 1024, -1);

 for (i = 0; i < nready; i++) {
 int connfd = events[i].data.fd;

 if (events[i].events & EPOLLIN)
 conn_list[connfd].r_action.recv_callback(connfd);

 if (events[i].events & EPOLLOUT)
 conn_list[connfd].send_callback(connfd);
 }
}

timeout == -1 表示没有事件时一直阻塞，避免空转消耗 CPU。

两个独立的 `if` 还是 `if ... else if`？

两个独立 if 理论上允许同一次返回同时处理读、写事件；else if 每轮只处理其中一种。

但不能简单认为两个 if 一定更好。若读回调发现连接已经断开并关闭了 fd，随后继续执行写回调就可能访问已经失效或被复用的 fd。稳妥做法是：

先处理 EPOLLERR、EPOLLHUP、EPOLLRDHUP。
回调返回关闭状态后，不再处理该 fd 的其他事件。
再依据连接状态处理读写事件。

8. 课堂代码补充

这份代码主要是为了演示 Reactor 的整体流程，所以有些细节课堂上只是带了一下。自己再写一遍时，可以顺手补上下面这些地方。

关于 send()

课上代码里有一句：

int count = send(fd, conn_list[fd].wbuffer, count, 0);

这里最后的 count 还没有赋值，应该写成 conn_list[fd].wlength。

另外，一次 send() 不一定能把 wlength 个字节全部发完。可以在连接对象里再记一个 woffset，每次发送后往后移动。数据还没发完就继续等 EPOLLOUT，全部发完后再切回 EPOLLIN。

关于 recv()

记住三个返回值：

大于 0：本次收到的字节数；
等于 0：对端关闭连接；
小于 0：要结合 errno 判断，非阻塞情况下可能只是暂时没有数据。

不能让 -1 继续参与后面的 memcpy()，否则长度转换后可能越界。EINTR 可以重试，EAGAIN/EWOULDBLOCK 表示这次先读到这里，其他情况再按真正的错误处理。

还有一点：recv() 收到的是一段字节，不会自动在末尾补 \0。要用 %s 打印时需要自己留位置并补结束符；如果处理二进制数据，就一直按长度来处理。

关于非阻塞

Reactor 一般要和非阻塞 socket 配合。监听 fd 和客户端 fd 都可以设置成 O_NONBLOCK，避免某一次 accept()、recv() 或 send() 卡住整个事件循环。

fcntl(fd, F_SETFL, fcntl(fd, F_GETFL, 0) | O_NONBLOCK);

如果以后从 LT 改成 ET，accept() 和 recv() 通常都要放在循环里，一直处理到返回 EAGAIN/EWOULDBLOCK。当前是 LT，一次只 accept() 一个连接也能继续触发，不过连接集中到来时，循环取完会更快一些。

关于 fd 和连接状态

当前写法直接用 fd 作为 conn_list 的下标，使用前要判断：

if (fd < 0 || fd >= CONNECTION_SIZE)
 return -1;

连接关闭时也不只是 close(fd)，对应的读写长度、偏移量和回调最好一起清空。因为 fd 的数字会被复用，下一个新连接有可能再次拿到同一个编号。

fd 也不能当作累计连接数。想每建立 1000 个连接打印一次，应该另外维护一个 accepted_count，不能用 clientfd % 1000 来判断。

其他随手记下的点

socket()、bind()、listen()、epoll_ctl()、epoll_wait() 等系统调用都要看返回值；
监听 socket 通常会设置 SO_REUSEADDR；
listen(sockfd, 10) 中的 10 是 backlog，不是服务器最多只能保持 10 条连接；
主循环除了 EPOLLIN、EPOLLOUT，还要留意 EPOLLERR、EPOLLHUP 和 EPOLLRDHUP；
对端关闭后继续发送可能触发 SIGPIPE，可以忽略该信号，或在 send() 时使用 MSG_NOSIGNAL；
TIME_SUB_MS(current, begin) 当前记录的是两次打印之间的间隔，不是从程序启动开始的总耗时。

9. 大包、拆包与粘包

代码中的读缓冲区只有 1024 字节。若客户端发送 2048 字节，一次 recv() 可能只收到其中一部分；即使缓冲区足够大，TCP 也不保证一次接收对应一次发送。

因此不能把：

一次 send = 一个业务消息 = 一次 recv

当成可靠规律。

业务协议需要定义消息边界，常见方法有：

固定长度消息。
特殊分隔符，例如文本协议中的换行。
消息头携带正文长度，例如“4 字节长度 + 消息体”。
HTTP 中使用请求行、首部、Content-Length 或分块传输规则。

Reactor 收到数据后应先追加到该连接自己的缓冲区，再交给协议解析器：

recv → 追加到连接缓冲区 → 判断是否形成完整消息
 → 未完整：保留并等待下次 EPOLLIN
 → 已完整：取出消息并处理，剩余数据继续保留

如果固定数组空间不足，可以使用动态缓冲区、环形缓冲区或链式缓冲区。

10. 为什么会出现 `Too many open files`

报错对应 errno == EMFILE（常见值为 24），表示当前进程已经达到可打开 fd 的上限。

一条 TCP 连接在客户端和服务端各自都占用一个 fd。百万连接测试至少要同时考虑：

10.1 进程级限制

查看当前 shell 的限制：

ulimit -n
ulimit -a

临时提高当前 shell 的 soft limit：

ulimit -n 1048576

程序必须从修改后的 shell 中启动，才能继承该限制。还要确保 hard limit 足够高。

10.2 系统级限制

cat /proc/sys/fs/file-max
cat /proc/sys/fs/file-nr

fs.file-max 是系统范围的文件句柄限制，ulimit -n 是单进程/会话限制，两者不是同一个概念。持久化设置还取决于系统的 PAM、systemd unit 和发行版配置，不能只改一个参数就假定生效。

10.3 程序自身限制

CONNECTION_SIZE 是否覆盖可能出现的 fd 值；
进程虚拟内存和实际物理内存是否足够；
每连接缓冲区是否过大；
是否存在 fd 泄漏；
epoll 实例和监听 socket 自己也会占 fd。

11. 为什么单个目标端口大约只能建立数万连接

一条 TCP 连接由五元组唯一标识：

源 IP、源端口、目的 IP、目的端口、传输层协议

在单台压测客户端连接单台服务器的单个端口时：

源 IP 固定；
目的 IP 固定；
目的端口固定；
协议固定为 TCP；
主要只能变化源端口。

当可用临时源端口耗尽时，客户端可能报：

Cannot assign requested address

11.1 一个需要校正的细节

客户端临时端口范围并非固定为 1024~65535。Linux 实际自动分配范围应通过下面的命令查看：

sysctl net.ipv4.ip_local_port_range

不同系统、不同配置的范围可能不同，部分端口还可能被占用、保留，或暂时处于 TIME_WAIT 等状态。因此可建立数量通常小于理论上的 65535。

11.2 为什么增加到 20 个服务端端口有效

将目标端口从一个增加到 2000~2019，改变了五元组中的“目的端口”。只要客户端把连接分散到这些端口，同一个源端口就可以与不同目的端口组成不同连接，理论连接空间随之扩大。

其他扩展方式还包括：

使用多个客户端源 IP；
使用多台压测机；
使用多个服务端 IP；
使用多个网络命名空间，但必须正确配置各自地址和路由。

不能仅用单台客户端的结果直接代表服务端的最大承载能力，因为压测端本身可能先耗尽端口、fd、CPU、内存或 conntrack 容量。

12. `nf_conntrack` 应该怎样理解

nf_conntrack 是 Linux Netfilter 的连接跟踪机制，防火墙、NAT 等功能会用到它。它不是 epoll 工作所必需的组成部分。

如果测试路径启用了连接跟踪，并且连接数达到表容量，才需要观察：

sysctl net.netfilter.nf_conntrack_max
cat /proc/sys/net/netfilter/nf_conntrack_count

旧资料中的 ip_conntrack 是较早的名称；现代内核通常使用 nf_conntrack。只有确实需要且模块尚未加载时，才考虑：

sudo modprobe nf_conntrack

不应看到连接问题就盲目加载模块或增大参数。应先确认机器是否启用了防火墙/NAT、模块是否存在、表是否真的已满。在服务端还是客户端调整，取决于哪台机器实际承担连接跟踪；中间的 NAT/防火墙设备也可能成为瓶颈。

13. 百万连接断开时为什么 CPU 会突然升高

如果一次性终止百万连接的一端，另一端会在短时间内集中处理大量 TCP 状态变化与关闭事件，例如 FIN/RST、epoll 唤醒、连接对象清理、定时器更新等。

这会形成“惊群式的业务处理洪峰”或资源回收洪峰，表现为 CPU 短时暴增。它不一定表示程序死循环，而可能是系统在集中处理积压事件。

优化方向包括：

分批建立和分批关闭连接；
减少关闭路径上的日志和同步操作；
将耗时清理异步化；
使用高效定时器结构，如时间轮；
避免每连接大量内存分配和释放；
做好背压和过载保护；
使用多 Reactor、多线程或多进程分摊事件处理；
用火焰图、perf、系统指标确认 CPU 真正消耗在哪里。

优化目标不是保证 CPU 永不升高，而是让峰值可控、持续时间缩短，并保证服务仍能继续响应。

14. “百万并发”不等于“百万 QPS”

性能测试至少要区分四个维度：

指标	含义
并发连接数	同一时刻保持的连接数量
QPS/吞吐量	单位时间完成的请求或消息数量
延迟	一次请求从发出到收到响应所需时间，通常关注 P50/P95/P99
测试用例	报文大小、收发频率、连接是否长连、业务是否计算或访问存储

保持 100 万条空闲 TCP 连接，和让 100 万条连接持续高速收发数据，是完全不同的负载。前者更考验 fd、内存和内核连接管理；后者还会迅速消耗 CPU、网络带宽、内存带宽以及业务依赖资源。

因此，一份可信的测试报告至少应说明：

客户端和服务端硬件配置；
内核和发行版版本；
所有相关内核参数与 fd 限制；
连接建立速率；
活跃连接与空闲连接比例；
请求/响应大小和频率；
QPS、吞吐量、错误率和延迟分位数；
CPU、内存、网络、fd、conntrack 使用率；
测试持续时间和连接关闭方式。

15. 本节课一句话总结

Reactor 的本质不是“用了 epoll 就很快”，而是把每个 fd 的状态独立保存起来，由事件循环将 I/O + event 精确分发给相应 callback；百万连接则是在这个正确模型之上，再共同解决 fd、内存、端口空间、内核网络栈和压测方法等系统性限制。

IO 多路复用与 Reactor

Fri, 07 Aug 2026 00:00:00 +0800

1. 为什么需要 IO 多路复用

网络服务器主要管理两类 socket：

监听 socket（listenfd / 代码中的 sockfd） 它出现可读事件，通常表示已经完成 TCP 握手的连接正在等待 accept()。
已连接 socket（clientfd / connfd） 它出现可读事件，可能表示收到了数据，也可能表示对端关闭连接；随后由 recv() 判断具体情况。它也可能出现可写、错误、挂断等事件。

最直接的服务器模型是“一连接一线程”：主线程执行 accept()，每建立一个连接便创建一个线程，由该线程阻塞在 recv() 上。

int clientfd = accept(sockfd, ...);
pthread_create(&thid, NULL, client_thread, &clientfd);

这种模型的优点是代码直观，一个线程可以按顺序处理一个连接的收、发逻辑。缺点是连接数增加时，需要大量线程；线程会占用栈空间和内核资源，还会产生调度及上下文切换成本。许多长连接大部分时间并没有数据，线程却仍然存在，因此不适合大量空闲连接并发存在的场景。

IO 多路复用的核心思想：让一个线程同时等待多个 fd。线程不再阻塞于某一个 recv()，而是阻塞在 select()、poll() 或 epoll_wait() 上；哪些 fd 已经就绪，线程就处理哪些 fd。

“多路”指多个 IO/fd，“复用”指复用同一个线程进行等待和处理。它复用的是等待能力，并不会自动并行执行业务代码。

2. “IO 就绪”与“完成 IO”

select、poll、epoll 提供的是就绪通知机制：

监听 fd 可读：通常可以调用 accept()。
客户端 fd 可读：可以调用 recv()；也可能是对端关闭或发生错误。
客户端 fd 可写：内核发送缓冲区当前有空间，并不等于全部数据已经发送完成。

它们只告诉应用程序“现在适合尝试某项 IO 操作”，不会替应用程序完成请求解析、业务计算和响应组装。

一个长连接的生命周期会经历许多次事件，而不是“连接一次只触发一个事件”：

建立连接 → 收到请求 → 发送响应 → 再次收到请求 → …… → 断开连接

因此，用户在线数或 TCP 连接数并不等于同一时刻的活跃请求数。例如服务器可能维护 100 万个连接，但某一时刻只有 1 万个连接真正产生事件。高并发服务器真正希望快速取得并处理的是这 1 万个就绪 fd。

3. select

3.1 接口

int select(int nfds,
 fd_set *readfds,
 fd_set *writefds,
 fd_set *exceptfds,
 struct timeval *timeout);

五类参数的含义：

nfds：三个集合中最大 fd 值加 1，而不是 fd 的数量。
readfds：关注可读事件的 fd 集合。
writefds：关注可写事件的 fd 集合。
exceptfds：关注异常条件的 fd 集合；它并不是所有网络错误的统一集合。
timeout：最长等待时间。
- NULL：一直阻塞，直到出现事件或被信号中断。
- {0, 0}：立即返回，成为轮询。
- 指定时间：超时后返回 0，可让事件循环顺便检查定时任务，但精确定时器通常还需要专门的数据结构。

返回值：

> 0：返回集合中就绪项的数量。
= 0：超时。
= -1：调用失败，例如被信号中断时 errno == EINTR。

3.2 如何理解 fd_set

fd_set 可以理解成一个位图集合：fd 是非负整数，位图中编号为 fd 的那一位表示该 fd 是否属于集合。

fd 编号： 0 1 2 3 4 5 6 7 8
位图值： 0 0 0 1 1 1 1 0 0
 ↑
 关注 3、4、5、6

常用宏：

FD_ZERO(&set); // 清空集合
FD_SET(fd, &set); // 加入 fd
FD_CLR(fd, &set); // 移除 fd
FD_ISSET(fd, &set); // 判断 fd 是否位于集合中

在典型 Linux/glibc 环境中，FD_SETSIZE 为 1024，fd_set 可表示编号 0～1023 的 fd，通常占 1024 bit，即 128 byte。但应以当前平台的 FD_SETSIZE 和 sizeof(fd_set) 为准。

需要注意：在 Linux 上，仅仅尝试修改 FD_SETSIZE 并不能可靠地突破 select() 的 1024 fd 限制；处理大量 fd 应改用 poll 或 epoll。此外，“最多 1024 个 fd”并不完全等于“最多 1024 个客户端”，因为进程还会占用标准输入输出、监听 socket、文件等其他 fd，而且 fd 编号必须小于 FD_SETSIZE。

3.3 为什么代码需要 rfds 和 rset 两份集合

附件代码中：

fd_set rfds, rset;
FD_ZERO(&rfds);
FD_SET(sockfd, &rfds);

while (1) {
 rset = rfds;
 int nready = select(maxfd + 1, &rset, NULL, NULL, NULL);
 ...
}

原因是 select() 的 fd 集合是传入兼传出参数：

调用前，集合表示“应用程序关注哪些 fd”。
返回后，集合被改写，只保留本次已经就绪的 fd。

因此：

rfds 保存长期关注的完整集合（整集）。
rset 是每次调用时复制出的工作集合，返回后用于判断本轮哪些 fd 就绪。

代码先判断监听 fd：

if (FD_ISSET(sockfd, &rset)) {
 int clientfd = accept(sockfd, ...);
 FD_SET(clientfd, &rfds);
}

然后从较小 fd 一直扫描到 maxfd，找出就绪客户端并执行 recv()：

for (int i = sockfd + 1; i <= maxfd; i++) {
 if (FD_ISSET(i, &rset)) {
 recv(i, ...);
 }
}

3.4 优缺点

优点：

一个线程可以等待多个 fd。
跨 Unix 类系统的可移植性较好。
fd 数量较少时足够简单实用。

缺点：

每次调用都要把集合从用户态复制到内核态，返回时还要复制回来。
内核需要检查关注集合；应用层也要扫描到 maxfd 才知道谁就绪。
集合会被改写，调用前必须重新准备。
Linux 上受 FD_SETSIZE 限制。
参数和集合管理较烦琐。

4. poll

4.1 数据结构与接口

poll 使用结构体数组描述关注对象：

struct pollfd {
 int fd; // 被监控的 fd
 short events; // 输入：关注的事件
 short revents; // 输出：实际发生的事件
};

int poll(struct pollfd *fds, nfds_t nfds, int timeout);

常见事件包括：

POLLIN：可读。
POLLOUT：可写。
POLLERR：发生错误。
POLLHUP：挂断。
POLLNVAL：fd 无效。

timeout 的单位是毫秒：

-1：一直阻塞。
0：立即返回。
> 0：最多等待指定毫秒数。

与 select 相比，pollfd 把“关注的事件”和“实际发生的事件”分开，因此不必在每轮调用前重建整个关注集合。它也没有 FD_SETSIZE 这种固定位图上限；实际容量仍受进程 fd 限额和内存限制。

4.2 poll 是否从根本上解决了性能问题

没有。每次调用 poll() 时，仍需把 pollfd 数组交给内核；内核和应用层仍需要在数组中检查事件。因此大量 fd 中只有少量就绪时，工作量仍与整个关注集合的规模相关。

poll 的主要价值是接口更统一、没有 select 的固定 fd 编号限制，而不是在大量连接场景中获得 epoll 那种只返回就绪项的机制。

适合场景通常包括：

需要比 select 更方便的事件表达方式。
fd 数量不特别大。
需要较好的 Unix 平台可移植性，而不能使用 Linux 专有的 epoll。

4.3 附件 poll 代码中的两个重要问题

原代码连续调用了两次 poll()：

poll(fds, maxfd + 1, -1);
int nready = poll(fds, maxfd + 1, -1);

第一次调用已经取得事件，第二次又重新阻塞；应删除第一次，只保留：

int nready = poll(fds, maxfd + 1, -1);

此外，代码用 fd 值作为数组下标，但数组被 {0} 初始化。未使用位置的 fd 因而是 0，会意外重复监控标准输入。poll 约定 fd < 0 的项会被忽略，因此所有空槽应初始化为 -1。更常见的写法是紧凑地保存有效 pollfd 项，而不是把 fd 直接当数组下标。

5. epoll

epoll 是 Linux 专用的 IO 事件通知机制。它将“维护关注集合”和“等待就绪事件”拆开，尤其适合大量连接、少量活跃的服务器场景。

5.1 三个核心接口

1. 创建 epoll 实例

int epfd = epoll_create(1);

返回的 epfd 本身也是一个 fd，代表一个内核中的 epoll 实例。较新的代码通常使用：

int epfd = epoll_create1(EPOLL_CLOEXEC);

epoll_create(size) 的 size 在现代 Linux 中已被忽略，但必须大于 0；保留它是为了兼容旧接口。它不是“单次最多返回多少个就绪事件”。单次最多返回多少项由 epoll_wait() 的 maxevents 决定。

2. 增删改关注对象

int epoll_ctl(int epfd, int op, int fd,
 struct epoll_event *event);

三种操作：

EPOLL_CTL_ADD：加入一个 fd。
EPOLL_CTL_DEL：删除一个 fd。
EPOLL_CTL_MOD：修改该 fd 关注的事件或关联数据。

事件结构体：

struct epoll_event {
 uint32_t events; // EPOLLIN、EPOLLOUT 等
 epoll_data_t data; // 可保存 fd、指针等用户数据
};

附件先注册监听 fd：

ev.events = EPOLLIN;
ev.data.fd = sockfd;
epoll_ctl(epfd, EPOLL_CTL_ADD, sockfd, &ev);

accept() 得到新客户端后，再单独将 clientfd 加入关注集合。

3. 等待就绪事件

int nready = epoll_wait(epfd, events, maxevents, timeout);

events：用户提供的结果数组，用来接收本次就绪项。
maxevents：结果数组最多能装多少项，必须大于 0；它不是 epoll 能管理的 fd 总数。
timeout：-1 一直等待，0 立即返回，正数表示最多等待的毫秒数。
返回值：本轮写入 events 数组的就绪项数，超时返回 0，失败返回 -1。

应用只需遍历 events[0..nready-1]：

for (int i = 0; i < nready; i++) {
 int fd = events[i].data.fd;
 ...
}

5.2 “整集”和“就绪集”

从概念上看，epoll 实例在内核中维护两个重要集合：

关注集合（interest list）：应用通过 epoll_ctl() 增、删、改的所有 fd。
就绪集合（ready list）：其中当前有事件需要应用处理的 fd。

传统实现说明中常把关注集合描述为红黑树、就绪集合描述为链表。但这些属于 Linux 内核实现细节，理解接口时更重要的是“长期关注集合”和“当前就绪集合”的分离，不应让业务代码依赖具体内部数据结构。

5.3 为什么 epoll 更适合大并发

以 100 万个连接、当前 1 万个连接活跃为例：

select/poll：每轮等待都需要提交并检查规模接近 100 万的关注集合，应用还要从大集合里寻找就绪项。
epoll：连接建立或状态变化时，通过 epoll_ctl() 增量维护关注集合；epoll_wait() 主要把当前就绪项返回给应用，应用遍历约 1 万个结果。

因此，epoll 的优势不应简单概括成“完全没有遍历或拷贝”，而应表述为：

不必在每次等待时重新提交整个关注集合。
应用遍历的是本轮返回的就绪项，而不是从 0 扫描至最大 fd。
连接管理是增量进行的，适合大量长连接中只有少量活跃的情形。

不过，epoll 不会消除业务处理、数据复制、系统调用等全部成本；当绝大部分连接始终活跃时，它相对 poll 的优势也会缩小。

5.4 LT 与 ET

epoll 有两种常见触发方式：

LT（Level Triggered，水平触发）：默认方式。只要 fd 仍处于就绪状态，后续 epoll_wait() 还会继续报告，较容易编写。
ET（Edge Triggered，边沿触发）：只有状态发生变化时重点通知。通常必须配合非阻塞 fd，并持续 accept() / recv() / send()，直到返回 -1 且 errno 为 EAGAIN 或 EWOULDBLOCK，否则可能遗漏尚未处理完的数据。

附件只设置了 EPOLLIN，没有设置 EPOLLET，因此使用的是 LT。

6. 从 IO 多路复用到 Reactor

select、poll、epoll 解决的是：

哪些 fd 上发生了应用关心的 IO 事件？

但实际服务器还需要解决：

某类事件发生以后，应当执行哪段业务逻辑？

Reactor 是一种事件驱动的程序组织模式。应用先把“事件”和“处理函数”注册起来；事件循环等待事件，事件发生后再把它分派给对应处理函数。

注册 fd + 关注事件 + 回调函数
 ↓
 select / poll / epoll 等待
 ↓
 得到就绪事件
 ↓
 Reactor 分派事件
 ↓
 accept_cb / recv_cb / send_cb

例如：

listenfd + READ -> accept_cb()
clientfd + READ -> recv_cb()
clientfd + WRITE -> send_cb()

因此，可以把两者的关系概括为：

select/poll/epoll 是底层的事件检测或事件分离机制。
Reactor 是上层的事件注册、循环等待和回调分派模式。
Reactor 关注的中心从“对某个 fd 写一段固定流程”转为“某个 fd 的某种事件应该调用哪个 handler”。

它和路由有相似之处：路由根据请求路径找到处理器，Reactor 根据 fd 上发生的事件找到处理器。但 Reactor 还负责事件监听、生命周期管理和持续循环，因此不能简单等同于路由。

典型 Reactor 由以下部分组成：

事件源：监听 socket、客户端 socket、定时器等。
事件多路分离器：select、poll 或 epoll。
Reactor / Dispatcher：事件循环与分派器。
Handler / Callback：处理连接、读取、写入、关闭等事件的函数。

Reactor 只是组织 IO 事件处理的模式，并不意味着业务一定只使用一个线程。常见结构包括：

单 Reactor、单线程。
单 Reactor + 工作线程池。
主 Reactor 负责接收连接，多个从 Reactor 负责已连接 socket，再配合工作线程池。

耗时业务不能长期阻塞事件循环，否则一个回调会拖延其他连接；CPU 密集型或阻塞型任务通常交给工作线程池。

7. 三种工具对比

特性	select	poll	epoll
平台	多种 Unix 类系统	多种 Unix 类系统	Linux
关注集合表示	`fd_set` 位图	`pollfd` 数组	内核维护的 epoll 关注集合
每轮是否重新提交整个关注集合	是	是	否，使用 `epoll_ctl` 增量维护
应用如何找就绪项	扫描到 `maxfd`	扫描数组	遍历 `epoll_wait` 返回的就绪数组
固定 1024 fd 编号限制	Linux 上通常有	无此固定限制	无此固定限制
主要适用情况	fd 较少、重视可移植性	fd 中等、重视可移植性和统一事件接口	Linux 大量连接、少量活跃

不能笼统地说谁在所有场景下一定最快。fd 很少时差别可能很小；平台兼容性、接口复杂度、连接活跃比例和业务负载都应纳入选择。

8. 附件代码的演进关系

代码使用条件编译展示了四个阶段：

单连接阻塞处理
 ↓
循环 accept，但一个连接的 recv 会阻塞后续连接
 ↓
一连接一线程，逻辑简单但线程成本随连接数增长
 ↓
select / poll / epoll，一个线程等待多个 fd
 ↓
进一步封装事件、状态与回调，即 Reactor

当前真正编译的是最后的 #else，即 epoll 版本；前面的分支因为使用 #if 0 / #elif 0 而不会参与编译。

9. 先记住三套代码共同的骨架

学习这三个接口时，不要一开始背所有参数。先固定服务器永远重复的四步：

1. 注册：告诉系统要关注哪些 fd、哪些事件
2. 等待：阻塞到至少一个事件发生
3. 分发：判断是监听 fd，还是客户端 fd
4. 更新：新连接加入，断开的连接删除，需要时修改关注事件

把三种接口代入同一骨架：

阶段	select	poll	epoll
保存关注对象	`fd_set rfds`	`struct pollfd fds[]`	内核中的 epoll 关注集合
注册新客户端	`FD_SET(clientfd, &rfds)`	添加一个 `pollfd`	`epoll_ctl(...ADD...)`
等待事件	`select(...)`	`poll(...)`	`epoll_wait(...)`
找出就绪对象	扫描并调用 `FD_ISSET`	扫描并检查 `revents`	直接遍历返回的 `events`
删除客户端	`FD_CLR(fd, &rfds)`	删除数组项或设为 `-1`	`epoll_ctl(...DEL...)`

下面三段代码都实现同一个核心功能：

监听 fd 可读 → accept 新连接 → 注册 clientfd
clientfd 可读 → recv 数据 → send 回显
连接关闭/出错 → 删除 clientfd → close

为了突出多路复用主干，示例省略了非阻塞设置、完整发送缓冲区、信号处理等生产级细节。

10. select 核心代码逐段对照

10.1 初始化：建立长期关注集合

fd_set rfds, rset; // 完整关注集合、本轮就绪集合
FD_ZERO(&rfds); // 初始为空
FD_SET(sockfd, &rfds); // 首先关注监听 fd

int maxfd = sockfd; // select 要知道最大的 fd

此时可以想象：

rfds = { sockfd }

10.2 每轮复制并等待

while (1) {
 rset = rfds;
 int nready = select(maxfd + 1, &rset, NULL, NULL, NULL);

这里两个集合的职责一定要分清：

调用前：rfds = 长期关注的完整集合
 rset = 复制品，也包含完整集合

返回后：rfds = 保持不变，供下一轮继续使用
 rset = 被 select 改写，只保留本轮就绪 fd

maxfd + 1 中的 +1 是因为 nfds 表示检查区间的右边界：内核检查 fd 0 到 maxfd，即 [0, maxfd + 1)。

10.3 监听 fd 就绪：接收并注册新连接

 if (FD_ISSET(sockfd, &rset)) {
 // sockfd 可读不是有业务数据，而是有连接可以取出
 int clientfd = accept(sockfd,
 (struct sockaddr *)&clientaddr,
 &len);

 // accept 不会删除 sockfd；它返回一个新的 clientfd
 FD_SET(clientfd, &rfds);

 if (clientfd > maxfd)
 maxfd = clientfd;
 }

要点：

检查的是返回集合 rset，因为要问“本轮谁就绪”。
新连接加入的是长期集合 rfds，因为要从下一轮开始持续关注它。
accept() 从已完成连接队列取出一个连接，但 sockfd 仍然继续监听。
新 clientfd 本轮不在 rset 中，从下一轮开始接受监控。

10.4 扫描客户端：处理并删除

 for (int fd = sockfd + 1; fd <= maxfd; ++fd) {
 if (!FD_ISSET(fd, &rset))
 continue; // 这个 fd 本轮不可读

 char buffer[1024] = {0};
 int count = recv(fd, buffer, sizeof(buffer), 0);

 if (count > 0) {
 send(fd, buffer, count, 0); // Echo：原样回发
 } else {
 // count == 0 表示对端关闭；教学代码也在出错时删除
 FD_CLR(fd, &rfds);
 close(fd);
 }
 }
}

这里的“可读”应理解为：现在调用读取类操作能够立即得到结果，而不会因为没有事件一直阻塞：

监听 fd 可读 → 调用 accept()，取出一个连接
客户端 fd 可读 → 调用 recv()，读取数据或得知对端关闭

maxfd = sockfd 也不是说监听 fd 永远最大，而是初始化时集合中只有 sockfd。加入新客户端以后，再通过比较更新 maxfd。

select 版最值得背下来的代码主干是：

rset = rfds;
nready = select(maxfd + 1, &rset, NULL, NULL, NULL);

if (FD_ISSET(sockfd, &rset)) {
 clientfd = accept(...);
 FD_SET(clientfd, &rfds);
}

for (fd = sockfd + 1; fd <= maxfd; fd++) {
 if (FD_ISSET(fd, &rset))
 recv(fd, ...);
}

记忆关键词：复制集合、maxfd + 1、扫描、FD_ISSET。

11. poll：对照附件代码理解

你的写法直接把 fd 当作 fds 数组下标：fd 3 放在 fds[3]，fd 4 放在 fds[4]。下面保留这种写法，方便和原代码逐行对应。

11.1 初始化数组

#define MAX_FDS 1024

struct pollfd fds[MAX_FDS];

// poll 会忽略 fd < 0 的项
for (int i = 0; i < MAX_FDS; ++i) {
 fds[i].fd = -1;
 fds[i].events = 0;
 fds[i].revents = 0;
}

fds[sockfd].fd = sockfd;
fds[sockfd].events = POLLIN;

int maxfd = sockfd;

此时：

假设 sockfd = 3：

fds[3].fd = 3
fds[3].events = POLLIN

events = POLLIN 表示“我希望观察可读”，revents 表示 poll() 返回时“本轮实际发生了什么”。

11.2 等待事件

while (1) {
 int nready = poll(fds, maxfd + 1, -1);

调用前后：

events = 输入：希望关注什么
revents = 输出：实际上发生了什么

与 select 不同，events 不会被替换成就绪集合，因此下一轮通常不必重建所有关注事件；但应把 revents 当作当轮结果使用。

附件原本连续调用了两次 poll()，应删掉第一次，否则第一次取得事件后，第二次又会重新阻塞。

11.3 监听 fd 就绪：注册新客户端

 if (fds[sockfd].revents & POLLIN) {
 // 监听 fd 可读：取出一个新连接
 int clientfd = accept(sockfd,
 (struct sockaddr *)&clientaddr,
 &len);

 // clientfd 直接作为数组下标
 fds[clientfd].fd = clientfd;
 fds[clientfd].events = POLLIN;

 if (clientfd > maxfd)
 maxfd = clientfd;
 }

例如 sockfd = 3、accept() 返回 clientfd = 4：

fds[3] 管理监听 fd 3：可读时调用 accept()
fds[4] 管理客户端 fd 4：可读时调用 recv()

11.4 扫描客户端的 revents

 for (int fd = sockfd + 1; fd <= maxfd; ++fd) {
 if (!(fds[fd].revents & POLLIN))
 continue; // fd 本轮没有发生可读事件

 char buffer[1024] = {0};
 int count = recv(fd, buffer, sizeof(buffer), 0);

 if (count > 0) {
 send(fd, buffer, count, 0);
 } else {
 close(fd);
 fds[fd].fd = -1; // 让 poll 忽略这个位置
 fds[fd].events = 0;
 }
 }
}

poll 版最值得背下来的代码主干是：

fds[clientfd].fd = clientfd;
fds[clientfd].events = POLLIN;

nready = poll(fds, maxfd + 1, -1);

for (fd = sockfd + 1; fd <= maxfd; ++fd) {
 if (fds[fd].revents & POLLIN)
 recv(fd, ...);
}

记忆关键词：events 是我想观察什么，revents 是本轮实际发生了什么。

12. epoll 核心代码逐段对照

epoll 的明显区别是：应用不再把完整关注数组传给每一次等待，而是提前通过 epoll_ctl() 增量维护关注集合。

12.1 创建实例并注册监听 fd

int epfd = epoll_create(1);

struct epoll_event ev;
ev.events = EPOLLIN;
ev.data.fd = sockfd;

epoll_ctl(epfd, EPOLL_CTL_ADD, sockfd, &ev);

此处可以理解为：

epoll_create：创建一个事件管理器
epoll_ctl ADD：向管理器登记“关注 sockfd 的可读事件”

其中 ev.data.fd = sockfd 可以看成给这次登记贴上“sockfd 身份标签”。内核会保存这个标签，等该 fd 就绪时再原样放进返回结果中。

12.2 等待并直接遍历就绪数组

while (1) {
 struct epoll_event events[1024] = {0};
 int nready = epoll_wait(epfd, events, 1024, -1);

 for (int i = 0; i < nready; ++i) {
 int fd = events[i].data.fd;

这里两个变量要严格分开：

ev ：调用 epoll_ctl() 时送进去的登记卡
events[] ：调用 epoll_wait() 时拿回来的结果数组

例如注册时写入：

ev.data.fd = 3;
epoll_ctl(epfd, EPOLL_CTL_ADD, 3, &ev);

当 fd 3 可读时，epoll_wait() 可能返回：

nready = 1
events[0].data.fd = 3
events[0].events = EPOLLIN

所以 events[i].data.fd 不是凭空出现的，它就是注册时 ev.data.fd 中保存的身份标签。

12.3 监听 fd 就绪：ADD 新客户端

 if (fd == sockfd) {
 // 监听 fd 可读：从连接队列中取出一个连接
 int clientfd = accept(sockfd,
 (struct sockaddr *)&clientaddr,
 &len);

 // 给新客户端准备新的登记信息
 ev.events = EPOLLIN;
 ev.data.fd = clientfd;

 epoll_ctl(epfd, EPOLL_CTL_ADD, clientfd, &ev);
 continue;
 }

accept() 不会删除监听 fd。假设 sockfd = 3、它返回 clientfd = 5，注册完成后可以这样理解：

fd 3 → 可读时返回标签 3 → 调用 accept()
fd 5 → 可读时返回标签 5 → 调用 recv()

12.4 客户端就绪：读取或 DEL

 if (events[i].events & EPOLLIN) {
 char buffer[1024] = {0};
 int count = recv(fd, buffer, sizeof(buffer), 0);

 if (count > 0) {
 send(fd, buffer, count, 0);
 } else {
 // 客户端断开：先从 epoll 删除，再关闭 fd
 epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);
 close(fd);
 }
 }
 }
}

epoll 版最值得背下来的代码主干是：

epfd = epoll_create(1);

ev.events = EPOLLIN;
ev.data.fd = sockfd;
epoll_ctl(epfd, EPOLL_CTL_ADD, sockfd, &ev);

nready = epoll_wait(epfd, events, 1024, -1);

for (i = 0; i < nready; i++) {
 fd = events[i].data.fd;
 if (fd == sockfd) {
 clientfd = accept(...);
 ev.events = EPOLLIN;
 ev.data.fd = clientfd;
 epoll_ctl(epfd, EPOLL_CTL_ADD, clientfd, &ev);
 } else if (events[i].events & EPOLLIN) {
 recv(fd, ...);
 }
}

记忆关键词：create 创建、ctl 管理、wait 等待、只遍历就绪项。

13. 把三段代码放在一起看

13.1 注册客户端

// select：修改用户态位图
FD_SET(clientfd, &rfds);

// poll：修改用户态结构体数组
fds[clientfd].fd = clientfd;
fds[clientfd].events = POLLIN;

// epoll：通过系统调用修改内核关注集合
ev.events = EPOLLIN;
ev.data.fd = clientfd;
epoll_ctl(epfd, EPOLL_CTL_ADD, clientfd, &ev);

13.2 等待事件

// select：集合会被改写，所以先复制
rset = rfds;
nready = select(maxfd + 1, &rset, NULL, NULL, NULL);

// poll：传入完整 pollfd 数组
nready = poll(fds, maxfd + 1, -1);

// epoll：关注集合已在内核，只传结果数组
nready = epoll_wait(epfd, events, 1024, -1);

13.3 寻找就绪客户端

// select：监听 fd 已单独处理，这里遍历客户端 fd
for (fd = sockfd + 1; fd <= maxfd; ++fd)
 if (FD_ISSET(fd, &rset)) { ... }

// poll：遍历完整 pollfd 数组
for (fd = sockfd + 1; fd <= maxfd; ++fd)
 if (fds[fd].revents & POLLIN) { ... }

// epoll：遍历本轮就绪数组
for (i = 0; i < nready; ++i)
 if (events[i].events & EPOLLIN) { ... }

13.4 删除客户端

// select
FD_CLR(fd, &rfds);
close(fd);

// poll
close(fd);
fds[fd].fd = -1;
fds[fd].events = 0;

// epoll
epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);
close(fd);

最核心的差别就体现在“完整集合放在哪里、每轮遍历谁”：

select：应用保存位图 → 每轮复制 → 扫描 0..maxfd
poll： 应用保存数组 → 每轮提交 → 扫描完整数组
epoll： 内核保存关注集合 → 每轮只取出并遍历就绪数组

总结

一连接一线程用线程等待每个连接；IO 多路复用让一个线程等待多个 fd；select 和 poll 每轮仍需处理整个关注集合，而 epoll 将关注集合长期维护在内核中并返回当前就绪项；Reactor再进一步把这些就绪事件分派给预先注册的回调函数，使服务器从“管理 fd”上升为“管理事件及其处理逻辑”。

网络 I/O 与 I/O 多路复用

Thu, 06 Aug 2026 00:00:00 +0800

一、网络 I/O 的使用场景

网络是后端服务开发中的重要环节。生活中大量功能都依赖客户端与服务端之间的网络通信。

1. 微信发送文字、语音和视频

当用户在微信发送消息时，大致过程是：

发送方微信
 ↓
通过网络将数据发送给微信服务器
 ↓
服务器找到接收方
 ↓
将数据转发给接收方微信

文字、语音、图片、视频在网络上传输时，最终都会被转换成字节数据。

网络 I/O 主要关心：

数据从哪里读取
数据向哪里发送
读取了多少字节
发送了多少字节

网络 I/O 本身并不关心这些字节具体表示文字、图片还是视频。

2. 刷抖音

刷视频时：

抖音 App 请求视频
 ↓
服务器返回视频信息和资源地址
 ↓
App 通过网络下载视频数据
 ↓
客户端解码并播放

通常视频会被切分成多个数据块，App 可以一边下载、一边播放。

3. 使用 `git clone`

执行：

git clone 仓库地址

大致过程是：

本地 Git 客户端连接 GitHub
 ↓
向 GitHub 请求仓库数据
 ↓
GitHub 通过网络发送 Git 对象
 ↓
本地接收、校验和解压
 ↓
形成本地仓库

代码能够到达本地，本质上也是客户端和 GitHub 服务端之间进行了网络 I/O。

这些场景都可以概括成：

客户端发起请求 → 服务端处理请求 → 服务端返回响应

二、什么是网络 I/O

网络 I/O 是建立在客户端和服务端之间的数据传输过程，类似二者之间连接的网络管道。例如十个客户端分别连接服务器，服务端通常会获得十个连接 fd：

客户端 A ←→ fd 4
客户端 B ←→ fd 5
客户端 C ←→ fd 6
...
客户端 J ←→ fd 13

随着客户端数量增加，fd 数量也会增加，于是就产生了一个重要问题：

服务端如何同时管理大量 fd？

这正是后面需要学习 select、poll 和 epoll 的原因。

三、socket 与 fd

在 Linux 中，Linux 通过 socket API 通信。创建 socket：

int sockfd = socket(AF_INET, SOCK_STREAM, 0);

参数的含义：

AF_INET：IPv4
SOCK_STREAM：面向字节流，对应 TCP
0：使用该组合默认的 TCP 协议

fd 本质是进程中的非负整数（此处了解，记忆也没啥用）：

0：标准输入
1：标准输出
2：标准错误
3：监听 socket
4：客户端连接 A
5：客户端连接 B

在当前服务端进程中，一个已连接 socket 的 fd 通常对应一条 TCP 连接。（存在 ACCEPT 的情况）

四、TCP 服务端的简便理解

可以把 TCP 服务端理解成酒店：

socket()：聘请迎宾员
bind()：安排迎宾员在哪个门口工作
listen()：正式开始迎宾
accept()：接待一位到达的客人
recv()：听客人提出需求
send()：将处理结果交给客人
close()：结束服务

说说两类重要 fd：

1. 监听 fd

定义完 sockfd 经过 bind、listen 后，sockfd 就成为监听 fd。主要职责是监听新连接，不负责收发数据。

2. 连接 fd

参考代码中的 int clientfd = accept(sockfd, ...);。accept() 成功后会返回一个新的 fd：

sockfd：负责监听新客户端
clientfd：负责和某个客户端通信

关系如下：

 ┌→ clientfd 4 ←→ 客户端 A
listenfd → accept() ─┼→ clientfd 5 ←→ 客户端 B
 └→ clientfd 6 ←→ 客户端 C

监听 fd 通常只有一个，但每建立一个客户端连接，服务端就会获得一个新的连接 fd。

五、服务端代码执行流程

1. 创建 socket

int sockfd = socket(AF_INET, SOCK_STREAM, 0);

作用：

在内核中创建 socket 对象。
返回一个 fd。
当前还没有绑定 IP 和端口。
当前也没有开始监听。

更准确的变量名可以理解为：

int listenfd;

因为它后面会被设置为监听 socket。

2. 准备服务器地址

struct sockaddr_in servaddr;

servaddr.sin_family = AF_INET;
servaddr.sin_addr.s_addr = htonl(INADDR_ANY);
servaddr.sin_port = htons(2000);

`sin_family`

servaddr.sin_family = AF_INET;

表示使用 IPv4。

`INADDR_ANY`

servaddr.sin_addr.s_addr = htonl(INADDR_ANY);

INADDR_ANY 表示监听本机所有 IPv4 网络接口，对应：

0.0.0.0

假设服务器有多个 IP：

127.0.0.1
192.168.1.10
10.0.0.10

绑定 0.0.0.0，表示这些本机地址上的 2000 端口都可以接收连接。

`htons()`

servaddr.sin_port = htons(2000);

htons 表示：

host to network short

它把主机字节序的 16 位端口号转换成网络字节序。

同理：

htonl

表示把 32 位数据从主机字节序转换成网络字节序。

端口范围是：

0～65535

通常：

0：让操作系统自动分配端口。
1～1023：传统意义上的特权端口。
1024～65535：普通程序通常可以使用。

但 1024 以上的端口也可能已经被其他程序占用。

3. 绑定 IP 和端口

bind(sockfd,
 (struct sockaddr *)&servaddr,
 sizeof(struct sockaddr));

bind() 将 socket 与本地 IP、端口建立联系：

sockfd ←→ 0.0.0.0:2000

可以理解为：

给迎宾人员安排具体的工作地点。

如果端口已经被其他服务绑定，可能出现：

Address already in use

你的代码通过下面的方式查看错误：

printf("bind error:%s\n", strerror(errno));

不过如果 bind() 失败，程序理论上不应该继续执行 listen()。

4. 进入监听状态

listen(sockfd, 10);

执行成功后，socket 从普通 socket 变成监听 socket。

此时可以使用：

ss -lntp | grep ':2000'

查看监听状态。

可能看到：

LISTEN 0 10 0.0.0.0:2000

5. 接收客户端连接

int clientfd = accept(
 sockfd,
 (struct sockaddr *)&clientaddr,
 &len
);

如果当前没有已经建立完成的客户端连接，阻塞模式下的 accept() 会暂停程序：

程序阻塞在 accept()
 ↓
等待客户端连接
 ↓
客户端完成 TCP 三次握手
 ↓
accept() 返回 clientfd

accept() 不会把原来的 sockfd 变成客户端连接。

它会返回一个全新的 clientfd。

六、代码中的三个服务端版本（代码文末附）

第一阶段：只处理一个客户端的一次数据

#if 0
 int clientfd = accept(...);

 char buffer[1024] = {0};
 int count = recv(clientfd, buffer, 1024, 0);

 printf("RECV:%s\n", buffer);

 count = send(clientfd, buffer, count, 0);
#endif

执行过程：

accept 一个客户端
 ↓
recv 一次
 ↓
send 一次
 ↓
后面不再 accept

这个版本只能：

接收一个客户端。
读取一次数据。
返回一次数据。

如果客户端想再次发送，服务端没有循环继续读取。

第二阶段：循环接收客户端，但串行处理

#elif 0
while (1) {
 int clientfd = accept(...);

 char buffer[1024] = {0};
 int count = recv(clientfd, buffer, 1024, 0);

 printf("RECV:%s\n", buffer);

 count = send(clientfd, buffer, count, 0);
}
#endif

这里增加了：

while (1)

因此服务端可以不断接收新客户端。

但是它仍然是串行处理：

accept 客户端 A
 ↓
recv 等待 A 发送数据
 ↓
send 返回给 A
 ↓
重新 accept 客户端 B

关键问题在这里：

recv(clientfd, buffer, 1024, 0);

默认情况下，recv() 是阻塞的。

假设客户端 A 已经连接，但一直没有发送数据：

服务端阻塞在 A 的 recv()

此时即使客户端 B 已经发起连接，应用程序也暂时无法回到 accept() 处理 B。

第三阶段：一个客户端对应一个线程

当前实际编译的是 #else：

#else
while (1) {
 int clientfd = accept(...);

 pthread_t thid;
 pthread_create(
 &thid,
 NULL,
 client_thread,
 &clientfd
 );
}
#endif

每接收一个客户端，创建一个线程。

线程函数：

void *client_thread(void *arg)
{
 int clientfd = *(int *)arg;

 while (1) {
 char buffer[1024] = {0};

 int count = recv(
 clientfd,
 buffer,
 1024,
 0
 );

 printf("RECV:%s\n", buffer);

 count = send(
 clientfd,
 buffer,
 count,
 0
 );
 }
}

运行关系变成：

主线程
 │
 ├─ accept 客户端 A
 │ └─ 创建线程 1 → recv(A)
 │
 ├─ accept 客户端 B
 │ └─ 创建线程 2 → recv(B)
 │
 └─ accept 客户端 C
 └─ 创建线程 3 → recv(C)

主线程只负责：

不断执行 accept()

工作线程负责：

recv() → 处理数据 → send()

这样即使线程 1 阻塞在客户端 A 的 recv()，主线程仍然可以继续 accept() 客户端 B。

准确来说，这是：

一个连接对应一个线程。

不是严格的”一次请求对应一个线程”，因为一个连接线程内部可以通过 while 处理多次请求。

七、对于阶段三一个连接一个线程的问题

这种模型简单直观，但连接数量增大后会产生问题。

1. 线程需要内存

每创建一个线程，都需要线程栈及相关管理资源。连接越多，线程越多，百万并发的时候…

2. 上下文切换成本

CPU 核心数量有限。

假设服务器只有 8 个 CPU 核心，却创建了 5000 个线程，操作系统必须不停地：

保存线程 A 的状态
切换到线程 B
保存线程 B 的状态
切换到线程 C

线程太多时，大量 CPU 时间可能消耗在线程调度上。

3. 大部分线程可能只是在等待

很多网络连接并不是一直都有数据。

例如即时通信中的长连接：

客户端保持在线
但大部分时间没有发送消息

对应线程会长期阻塞在：

recv(clientfd, ...);

如果一个空闲连接占用一个线程，就会浪费大量线程资源。

代码

#include <stdio.h> // printf
#include <string.h> // memset
#include <sys/socket.h>
#include <arpa/inet.h> // htonl, htons
#include <errno.h> // errno
#include <netinet/in.h> // struct sockaddr_in
#include <unistd.h> // close
#include <pthread.h>

void *client_thread(void *arg) {
 int clientfd = *(int *)arg;
 while (1) {
 char buffer[1024] = {0};
 int count = recv(clientfd, buffer, 1024, 0); // 全部阻塞在 recv 上
 printf("RECV:%s\n", buffer);
 count = send(clientfd, buffer, count, 0);
 printf("SEND:%s\n", count);
 }
}

int main() {
 int sockfd = socket(AF_INET, SOCK_STREAM, 0); // create socket 聘请迎宾者
 // 绑定本地端口
 struct sockaddr_in servaddr;
 servaddr.sin_family = AF_INET;
 servaddr.sin_addr.s_addr = htonl(INADDR_ANY); // 0.0.0.0
 servaddr.sin_port = htons(2000); // 0-1023 系统默认，1024 之后都可以用，不能与其他的冲突
 // 在哪个门迎宾，安排的位置
 if (-1 == bind(sockfd, (struct sockaddr *)&servaddr, sizeof(struct sockaddr))) {
 printf("bind error:%s\n", strerror(errno));
 }
 // 登记绑定
 listen(sockfd, 10); // 正式上榜
 printf("listen finished\n");
 struct sockaddr_in clientaddr;
 socklen_t len = sizeof(clientaddr);
#if 0
 printf("accept\n");
 int clientfd = accept(sockfd, (struct sockaddr *)&clientaddr, &len); // 建立链接
 printf("accept finished\n");
 char buffer[1024] = {0};
 int count = recv(clientfd, buffer, 1024, 0);
 printf("RECV:%s\n", buffer);
 count = send(clientfd, buffer, count, 0);
 printf("SEND:%s\n", count);
#elif 0
 while (1) {
 printf("accept\n");
 int clientfd = accept(sockfd, (struct sockaddr *)&clientaddr, &len); // 建立链接
 printf("accept finished\n");
 char buffer[1024] = {0};
 int count = recv(clientfd, buffer, 1024, 0); // 全部阻塞在 recv 上
 printf("RECV:%s\n", buffer);
 count = send(clientfd, buffer, count, 0);
 printf("SEND:%s\n", count);
 } // 多个 io 如何接收数据
#else
 while (1) {
 printf("accept\n");
 int clientfd = accept(sockfd, (struct sockaddr *)&clientaddr, &len); // 建立链接
 printf("accept finished\n");
 pthread_t thid;
 pthread_create(&thid, NULL, client_thread, &clientfd);
 }
#endif
 getchar();
 printf("exit\n");
 return 0;
}

暑假七月总结：从期末月到新起点

Sat, 01 Aug 2026 22:26:00 +0800

期末月回顾

时隔两个月，博客写了不少，经历也不少，这段时间打算重启这个记录吧。

简明扼要地说说消失的这两个月我干了什么。在学校的时间大概就是期末月，平时完全不怎么学，度过了最 free 一学期的我，只能靠这最后一个月找补了。其缺点也是非常明显的，不知为何感觉复习得草草，期末的题都能应付了事，只不过很奇怪，为什么分数还是很低呢？没有认真学，这样的结果我也释怀了。下学期尽量认真学吧，每一门、每一科——除非真的是很无语、没有一点知识性的科目。

下学期目标

希望下学期的主线编排还是在自己能力的提升和找实习上吧。希望绩点能到 3.8，这是我对下学期的 goal，应该朝着这个方向努力。也希望能如愿以偿找到一份好的实习，在寒假努努力、取取经，多涨涨经验。

希望下学期也可以探索多样的分支，对 Quant 和 Infra 的理解也希望能并行。

学习与收获

其实消失的这几个月我陷入了漩涡。具体到学习上，我觉得还好，因为有一个实习作为导向，无非就是强化力扣、强化八股、强化对项目的理解，这些都是可以日拱一卒的。

此外，机缘巧合了解到 PKU 的 Infra 夏令营，这无疑是一个契机，让我了解到 Infra 相关的内容，并在一定程度上提供了学习指导。

顺带一提感悟：难以想象 PKU 的学生接受的兴趣社团内容原来是这样。如此的课程设计，我只能在国外大学的网课上看到，譬如 CS61A。他们的天赋、他们的大学、他们的环境、他们的资源，正在加速分离与其他人的命运，令人艳羡吧。至少就我所知，中九是无法望其项背的。

总归，网课讲得很玄幻，知识跳跃度很大，很难吸收理解。好在这个时代有了 AI，Assignment 的设置一步一步，慢慢地也不至于被拉下太远。

状态与计划

状态不太好，是因为感觉每天十分单调，作息也不是很健康。对着电脑学习一会儿，总想着干点其他的事，继而脑雾产生。专注力真的是很重要的思维资产，大部分的专注力都喂狗了，哈哈哈哈。

总体就是这样。希望还剩下一个月的暑假能够认真利用：跟上 Infra，认真做 Assignment，有自己的理解和复盘；对后端项目有所提升。就是这样，自己的身体也希望更加健康，对于一些旁枝的探索也要慢慢拓展。

就是这样，共勉，加油！

Go 项目反推：Feed 流系统实战——Feed 流设计

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——数据库与 GORM，这一篇继续拆解 feedsystem_video_go 的核心 Feed 流：从推拉模型到游标分页，再到热榜、关注流、话题流与缓存策略。

什么是 Feed 流

打开抖音/微博，往下刷，不断出来新内容，这就是 Feed 流。

这个项目的 4 种 Feed 流

类型	说明	排序方式
最新视频	全站最新发布的视频	按时间倒序
热榜	最热门的视频	按热度排序
关注流	只看关注的人发的视频	按时间倒序
话题流	某个话题下的视频	按时间倒序

推模型 vs 拉模型

拉模型（这个项目用的）

发视频：只写Video表（不做额外操作）
刷视频：实时查询Video表（拉取数据）

数据流动：用户刷的时候才从 DB 拉。

推模型

发视频：写Video表 + 把视频ID推送到所有粉丝的Feed列表里
刷视频：直接从自己的Feed列表读（不用查DB）

数据流动：发的时候就推给粉丝了，粉丝刷的时候直接读。

推拉结合

普通用户发视频 → 推送给粉丝（粉丝少，推送成本低）
大V发视频 → 不推送，粉丝读的时候实时拉取

对比

	拉模型	推模型	推拉结合
发视频成本	低	高（大V要推给几百万粉丝）	中
刷视频成本	高（每次都要查DB）	低（直接读列表）	中
实时性	实时	略有延迟	中
复杂度	简单	复杂	最复杂
场景	用户量小	用户量大	抖音/微博

这个项目用拉模型，因为是学习项目，用户量小，拉模型简单够用。

游标分页 vs 页码分页

页码分页

第1页：GET /feed?page=1&size=10
第2页：GET /feed?page=2&size=10

对应 SQL：

SELECT * FROM videos ORDER BY create_time DESC LIMIT 5 OFFSET 0 -- 第1页
SELECT * FROM videos ORDER BY create_time DESC LIMIT 5 OFFSET 5 -- 第2页

问题：数据变化时可能重复或漏数据

数据库：[100, 90, 80, 70, 60, 50, 40, 30]

第1页（page=1, size=3）：跳过0条，取3条 → [100, 90, 80]

插入新视频110，数据库变成：[110, 100, 90, 80, 70, 60, 50, 40, 30]

第2页（page=2, size=3）：跳过3条，取3条 → [80, 70, 60]

视频80重复出现了！

为什么？因为 OFFSET 是基于"位置"的，不是基于"数据"的。新视频插入后，原来第 4 个位置的视频 80 变成了第 5 个，但 OFFSET 还是 3，所以又取到了。

游标分页（这个项目用的）

第1页：GET /feed?limit=10
 返回：video_list + next_time=1000

第2页：GET /feed?limit=10&latest_time=1000
 返回：video_list + next_time=900

对应 SQL：

SELECT * FROM videos ORDER BY create_time DESC LIMIT 10
SELECT * FROM videos WHERE create_time < 1000 ORDER BY create_time DESC LIMIT 10

为什么游标分页不会重复？

第1页：WHERE create_time < now() LIMIT 3
 返回 [100, 90, 80]
 next_time = 80的时间

插入110

第2页：WHERE create_time < 80的时间 LIMIT 3
 返回 [70, 60, 50]

没有重复！

游标是基于数据的值（时间），不是位置。新视频插入不影响查询条件。

对比

	页码分页	游标分页
请求方式	page=2	latest_time=1000
数据变化时	可能重复或漏数据	不会重复
SQL	OFFSET 跳过	WHERE 条件过滤
场景	后台管理系统	Feed 流、时间线

游标分页的实现

服务器代码

func (repo *FeedRepository) ListLatest(ctx context.Context, limit int, latestBefore time.Time) ([]*video.Video, error) {
 query := repo.db.WithContext(ctx).Model(&video.Video{}).Order("create_time DESC")

 // 关键：如果有游标，加上WHERE条件
 if !latestBefore.IsZero() {
 query = query.Where("create_time < ?", latestBefore)
 }

 query.Limit(limit).Find(&videos)
 return videos, nil
}

游标怎么生成的

// 取本页最后一条视频的时间作为游标
var nextTime int64
if len(baseVideos) > 0 {
 nextTime = baseVideos[len(baseVideos)-1].CreateTime.UnixMilli()
}

本页最后一条视频的时间 = 下一页的起点。

响应结构

type ListLatestResponse struct {
 VideoList []FeedVideoItem `json:"video_list"`
 NextTime int64 `json:"next_time"` // 游标
 HasMore bool `json:"has_more"` // 还有没有更多
}

完整流程

客户端：GET /feed?limit=10
 ↓
服务器：SELECT * FROM videos ORDER BY create_time DESC LIMIT 10
 ↓
返回：video_list + next_time = 本页最后一条的时间
 ↓
客户端：GET /feed?limit=10&latest_time=next_time
 ↓
服务器：SELECT * FROM videos WHERE create_time < next_time ORDER BY create_time DESC LIMIT 10
 ↓
返回：video_list + next_time = 新的游标
 ↓
...循环，直到 has_more = false

热榜实现

热榜排序算法

query := repo.db.WithContext(ctx).Model(&video.Video{}).
 Order("popularity DESC, create_time DESC, id DESC")

排序规则：热度高的优先，热度相同按时间倒序，时间也相同按 ID 倒序。

热度分数怎么算的

func UpdatePopularityCache(ctx context.Context, cache *rediscache.Client, id uint, change int64) {
 now := time.Now().UTC().Truncate(time.Minute)
 windowKey := cache.Key("hot:video:1m:%s", now.Format("200601021504"))
 member := strconv.FormatUint(uint64(id), 10)

 cache.ZincrBy(opCtx, windowKey, member, float64(change)) // 热度+change
 cache.Expire(opCtx, windowKey, 2*time.Hour)
}

每次点赞/评论/关注，热度+1。

热榜查询流程（冷热分离）

func (f *FeedService) ListByPopularity(ctx context.Context, limit int, reqAsOf int64, offset int, ...) {
 // 1. 确定时间窗口（最近60分钟）
 asOf := time.Now().UTC().Truncate(time.Minute)

 // 2. 生成60个ZSET的key
 keys := make([]string, 0, 60)
 for i := 0; i < 60; i++ {
 keys = append(keys, f.rediscache.Key("hot:video:1m:%s", asOf.Add(-time.Duration(i)*time.Minute).Format("200601021504")))
 }

 // 3. 合并成一个ZSET（快照）
 dest := f.rediscache.Key("hot:video:merge:1m:%s", asOf.Format("200601021504"))
 f.rediscache.ZUnionStore(opCtx, dest, keys, "SUM")

 // 4. 从合并后的ZSET取top N
 members, _ := f.rediscache.ZRevRange(opCtx, dest, start, stop)

 // 5. 根据ID去查视频详情
 videos, _ := f.repo.GetByIDs(ctx, ids)

 return videos
}

快照 key 是什么

快照 key 就是"合并结果的缓存"。

没有快照key：
 用户A请求 → 合并60个ZSET → 返回
 用户B请求 → 合并60个ZSET → 返回
 100个用户请求 → 合并100次 → 浪费！

有快照key：
 用户A请求 → 合并60个ZSET → 存到快照key → 返回
 用户B请求 → 发现快照key已存在 → 直接用 → 返回
 100个用户请求 → 只合并1次 → 省资源！

代码：

dest := f.rediscache.Key("hot:video:merge:1m:%s", asOf.Format("200601021504"))
exists, _ := f.rediscache.Exists(opCtx, dest)
if !exists {
 f.rediscache.ZUnionStore(opCtx, dest, keys, "SUM")
 f.rediscache.Expire(opCtx, dest, 2*time.Minute)
}
members, _ := f.rediscache.ZRevRange(opCtx, dest, start, stop)

快照 key 2 分钟后过期，下次请求重新合并，拿到最新数据。

关注流实现

核心代码

func (repo *FeedRepository) ListByFollowing(ctx context.Context, limit int, viewerAccountID uint, latestBefore time.Time) ([]*video.Video, error) {
 var videos []*video.Video
 query := repo.db.WithContext(ctx).Model(&video.Video{}).Order("create_time DESC")

 if viewerAccountID > 0 {
 // 子查询：找到我关注的所有人
 followingSubQuery := repo.db.WithContext(ctx).
 Model(&social.Social{}).
 Select("vlogger_id").
 Where("follower_id = ?", viewerAccountID)

 // 只查这些人发的视频
 query = query.Where("author_id IN (?)", followingSubQuery)
 }

 if !latestBefore.IsZero() {
 query = query.Where("create_time < ?", latestBefore)
 }

 query.Limit(limit).Find(&videos)
 return videos, nil
}

等价 SQL

SELECT * FROM videos
WHERE author_id IN (
 SELECT vlogger_id FROM socials WHERE follower_id = 123 -- 我关注的人
)
AND create_time < 1000 -- 游标
ORDER BY create_time DESC
LIMIT 10

子查询是什么

子查询就是"查询里的查询"，拆成两步理解：

第1步（子查询）：
 SELECT vlogger_id FROM socials WHERE follower_id = 123
 → 结果：[456, 789]（用户A关注的人）

第2步（主查询）：
 SELECT * FROM videos WHERE author_id IN (456, 789)
 → 结果：视频100（B发的）、视频200（C发的）

子查询是一次 SQL 搞定，数据库内部优化，比两条 SQL 更快。

流程

用户A关注了B和C
 ↓
子查询：从social表找到 [456, 789]
 ↓
主查询：从video表找 author_id 是 456 或 789 的视频
 ↓
返回：视频100（B发的）、视频200（C发的）
 ↓
用户D的视频300不会出现（A没关注D）

话题流实现

核心代码

func (repo *FeedRepository) ListByTag(ctx context.Context, tagName string, limit int) ([]*video.Video, error) {
 var videos []*video.Video
 err := repo.db.WithContext(ctx).Model(&video.Video{}).Table("videos").
 Joins("JOIN video_tags ON video_tags.video_id = videos.id").
 Joins("JOIN tags ON tags.id = video_tags.tag_id").
 Where("tags.name = ?", tagName).
 Order("videos.create_time desc").
 Limit(limit).
 Find(&videos).Error
 return videos, err
}

等价 SQL

SELECT videos.* FROM videos
JOIN video_tags ON video_tags.video_id = videos.id
JOIN tags ON tags.id = video_tags.tag_id
WHERE tags.name = 'Go语言'
ORDER BY videos.create_time DESC
LIMIT 10

三张表的关系

tags表：
┌────┬──────────┐
│ id │ name │
├────┼──────────┤
│ 1 │ Go语言 │
│ 2 │ Python │
└────┴──────────┘

video_tags表（多对多关联）：
┌──────────┬─────────┐
│ video_id │ tag_id │
├──────────┼─────────┤
│ 100 │ 1 │ ← 视频100有"Go语言"标签
│ 100 │ 2 │ ← 视频100也有"Python"标签
│ 200 │ 1 │ ← 视频200有"Go语言"标签
└──────────┴─────────┘

videos表：
┌────┬──────────┐
│ id │ title │
├────┼──────────┤
│ 100 │ Go入门 │
│ 200 │ 并发编程 │
└────┴──────────┘

查询流程

1. 从tags表找到"Go语言"的id = 1
2. 从video_tags表找到tag_id = 1的video_id = [100, 200]
3. 从videos表找到id = [100, 200]的视频

JOIN一次搞定。

三级缓存架构

这个项目在 Feed 查询里用了三级缓存：

请求 → L1本地缓存 → L2 Redis → L3 MySQL
 ↓ 快 ↓ 较快 ↓ 慢
 纳秒级 毫秒级 毫秒级

代码

type FeedService struct {
 localcache *cache.Cache // L1：本地缓存（进程内存，3秒过期）
 rediscache *rediscache.Client // L2：Redis缓存
 repo *FeedRepository // L3：MySQL
}

// L1：本地缓存
localcache: cache.New(3*time.Second, 5*time.Second)

// L2：Redis缓存（50ms超时）
cacheCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)

// L3：MySQL
videos, err := f.repo.GetByIDs(ctx, ids)

查询流程

请求来了
 ↓
查L1本地缓存（进程内存）
 ├── 命中 → 直接返回（最快）
 └── 没命中
 ↓
 查L2 Redis（50ms超时）
 ├── 命中 → 写回L1 → 返回
 └── 没命中
 ↓
 查L3 MySQL
 → 写回L2 Redis → 写回L1 → 返回

singleflight 防并发

什么是 singleflight

Go 内置的工具，保证同一个请求只执行一次，其他并发请求等着用结果。

场景

100个用户同时请求热榜
 ↓
没有singleflight：
 用户1：查DB → 返回
 用户2：查DB → 返回
 ...
 用户100：查DB → 返回
 DB被查了100次！

有singleflight：
 用户1：查DB → 返回
 用户2-100：等着 → 用户1查完后直接用结果
 DB只被查了1次！

代码

type FeedService struct {
 requestGroup singleflight.Group
}

v, err, _ := f.requestGroup.Do(sfKey, func() (interface{}, error) {
 return f.repo.GetByIDs(ctx, []uint{videoID})
})

第 1 个请求：执行 func，查 DB
其他请求：同一个 sfKey，等着，拿到同样的结果

sfKey 是什么

请求的唯一标识：

sfKey := f.rediscache.Key("sf:entity:%d", videoID)
// 结果："sf:entity:123"

同一个视频 ID 的请求，sfKey 相同，会共享结果。

和分布式锁的对比

	分布式锁	singleflight
作用范围	多台机器	单机内
实现	Redis	Go 内存
复杂度	高	低
场景	分布式系统	单机内防并发

面试要点总结

Q: 推模型和拉模型的区别？

A: 推是发视频时推送给粉丝，拉是刷视频时实时查 DB。推的读快写慢，拉的读慢写快。抖音用推拉结合。

Q: 游标分页和页码分页的区别？

A: 游标用 WHERE 条件过滤，不会重复；页码用 OFFSET 跳过，数据变化时可能重复。Feed 流用游标分页。

Q: 热榜怎么实现的？

A: ZSET 按分钟分窗口，点赞时热度+1，查询时合并 60 个窗口算总分，快照 key 缓存合并结果。

Q: 关注流怎么实现的？

A: 子查询找关注列表，再查这些人发的视频。一次 SQL 搞定。

Q: 话题流怎么实现的？

A: 三表 JOIN（videos + video_tags + tags），查某个标签下的视频。

Q: 什么是 singleflight？

A: Go 内置工具，保证同一个请求只执行一次，其他并发请求等着用结果。和分布式锁类似，但作用于单机内。

Q: 三级缓存是什么？

A: L1 本地缓存（进程内存）→ L2 Redis → L3 MySQL。先查快的，没命中再查慢的。

Go 项目反推：Feed 流系统实战——SSE 实时推送与分片上传

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——Feed 流设计，这一篇继续拆解 feedsystem_video_go 的两个关键能力：用 SSE 实时推送通知，以及用分片上传和断点续传处理大文件。

阶段6：SSE实时推送

SSE 是什么

SSE = Server-Sent Events，服务器主动给客户端推送消息。

就像外卖 APP 的订单状态：

你下单 → 服务器推送"商家已接单"
 → 服务器推送"骑手已取餐"
 → 服务器推送"骑手已送达"

客户端不用一直问"好了没？好了没？"，服务器有消息就主动推。

SSE vs WebSocket

	SSE	WebSocket
方向	服务器 → 客户端（单向）	双向
协议	HTTP	独立协议
复杂度	简单	复杂
场景	通知、状态更新、新闻推送	聊天、游戏、实时协作

这个项目用 SSE 推送通知（点赞、评论、关注），因为只需要服务器→客户端，不需要客户端→服务器。

为什么用 SSE 不用轮询

方案	做法	问题
轮询	客户端每隔几秒问一次"有新消息吗？"	浪费资源、实时性差、大部分请求返回空
SSE	服务器有消息就推，没有就等着	省资源、实时性高

项目里 SSE 用在哪

用户A给用户B的视频点赞
 ↓
LikeWorker处理点赞事件
 ↓
NotificationWorker收到MQ消息
 ↓
创建Notification记录，写入DB
 ↓
SSEHub.Push(userID, notification)
 ↓
用户B的浏览器收到推送，实时显示"xxx点赞了你的视频"

SSEHub 数据结构

type SSEHub struct {
 mu sync.RWMutex
 clients map[uint][]chan *Notification // userID -> 多个通知channel
 db *gorm.DB
}

数据结构：

map[uint][]chan *Notification

用户1 → [channel1, channel2] （可能多个设备）
用户2 → [channel3]
用户3 → [channel4, channel5, channel6] （三个设备）

代码实现

Notification 表结构

type Notification struct {
 ID uint
 RecipientID uint // 接收者ID
 SenderID uint // 发送者ID
 Type string // 通知类型：like、comment、follow
 TargetID uint // 目标ID（视频ID、用户ID）
 Content string // 通知内容
 IsRead bool // 是否已读
 CreatedAt time.Time
}

SSEHub 核心方法

// 订阅：用户连接时调用
func (h *SSEHub) Subscribe(userID uint) chan *Notification {
 ch := make(chan *Notification, 20) // 缓冲区20
 h.mu.Lock() // 写锁
 h.clients[userID] = append(h.clients[userID], ch)
 h.mu.Unlock()
 return ch
}

// 取消订阅：用户断开时调用
func (h *SSEHub) Unsubscribe(userID uint, ch chan *Notification) {
 h.mu.Lock() // 写锁
 defer h.mu.Unlock()
 chs := h.clients[userID]
 for i, c := range chs {
 if c == ch {
 chs = append(chs[:i], chs[i+1:]...)
 if len(chs) == 0 {
 delete(h.clients, userID)
 } else {
 h.clients[userID] = chs
 }
 close(c)
 return
 }
 }
}

// 推送：有新通知时调用
func (h *SSEHub) Push(userID uint, n *Notification) {
 h.mu.RLock() // 读锁
 defer h.mu.RUnlock()
 chs, ok := h.clients[userID]
 if !ok {
 return
 }
 for _, ch := range chs {
 select {
 case ch <- n: // 往channel里塞消息
 default: // 塞不进去就跳过（防阻塞）
 }
 }
}

SSEHandler - 处理 SSE 连接

func (h *SSEHub) SSEHandler(c *gin.Context) {
 userID, ok := sseAccountID(c)
 if !ok {
 c.JSON(http.StatusUnauthorized, gin.H{"error": "invalid account"})
 return
 }

 // 设置SSE响应头
 c.Writer.Header().Set("Content-Type", "text/event-stream")
 c.Writer.Header().Set("Cache-Control", "no-cache")
 c.Writer.Header().Set("Connection", "keep-alive")
 c.Writer.WriteHeader(http.StatusOK)

 // 订阅通知
 ch := h.Subscribe(userID)
 defer h.Unsubscribe(userID, ch)

 ctx := c.Request.Context()
 flusher, _ := c.Writer.(http.Flusher)

 for {
 select {
 case <-ctx.Done(): // 客户端断开
 return
 case n, ok := <-ch: // 收到通知
 if !ok {
 return
 }
 b, _ := json.Marshal(n)
 fmt.Fprintf(c.Writer, "data: %s\n\n", b) // SSE格式
 if flusher != nil {
 flusher.Flush() // 立刻发送给客户端
 }
 case <-time.After(30 * time.Second): // 心跳
 fmt.Fprintf(c.Writer, ": keepalive\n\n")
 if flusher != nil {
 flusher.Flush()
 }
 }
 }
}

Push 为什么用 RLock 不用 Lock

什么是读写锁（RWMutex）

普通锁（Mutex）：同一时刻只能一个人进去，不管是读还是写。

读写锁（RWMutex）：

多个人可以同时读（RLock）
写的时候只能一个人进去，其他人不能读也不能写（Lock）

对比

操作	做什么	用什么锁
Push	读 map，往 channel 塞消息	RLock（读锁）
Subscribe	往 map 里加一个 channel	Lock（写锁）
Unsubscribe	从 map 里删一个 channel	Lock（写锁）

为什么 Push 能用 RLock

Push 只做两件事：

从 map 里找到用户的 channel（读）
往 channel 里塞消息（不改 map）

map 结构没变，所以多个 Push 可以同时进行。

一句话：读用 RLock（可以并发），写用 Lock（必须独占）。

场景对比

场景：100个用户同时收到通知

用普通锁（Mutex）：
 Push1加锁 → 推送 → 解锁
 Push2加锁 → 推送 → 解锁
 ... 一个一个来，慢

用读写锁（RWMutex）：
 Push1加RLock → 推送
 Push2加RLock → 推送
 Push3加RLock → 推送
 ... 100个同时推，快

心跳机制

什么是心跳

SSE 连接可能因为网络问题断开，客户端不知道。

解决方案：每 30 秒发一次空消息（keepalive），告诉客户端"我还活着"。

case <-time.After(30 * time.Second):
 fmt.Fprintf(c.Writer, ": keepalive\n\n")
 flusher.Flush()

为什么需要心跳

没有心跳：
 客户端连接服务器 → 网络抖动 → 连接断了
 客户端不知道断了 → 一直等 → 漏掉通知

有心跳：
 客户端连接服务器 → 每30秒收到keepalive
 30秒没收到 → 知道断了 → 重新连接

select 里的 default 防阻塞

for _, ch := range chs {
 select {
 case ch <- n: // 往channel里塞消息
 default: // 塞不进去就跳过
 }
}

channel 缓冲区满了（20条），塞不进去怎么办？

没有 default：阻塞等着，Push 卡住，其他用户的推送也卡住
有 default：直接跳过，不等，保证其他用户能正常收到推送

这是防阻塞设计：一个用户的消息堆积不影响其他用户。

NotificationWorker 处理流程

func (w *NotificationWorker) process(ctx context.Context, d amqp.Delivery) error {
 routingKey := d.RoutingKey

 var notif *Notification

 switch {
 case routingKey == "like.like":
 // 解析点赞事件
 // 查询视频作者ID
 // 如果是自己给自己点赞，不通知
 notif = &Notification{RecipientID: authorID, SenderID: evt.UserID, Type: "like", Content: "点赞了你的视频"}

 case routingKey == "comment.publish":
 // 解析评论事件
 // 查询视频作者ID
 // 如果是自己评论自己，不通知
 notif = &Notification{RecipientID: authorID, SenderID: evt.AuthorID, Type: "comment", Content: "评论了你的视频"}

 case routingKey == "social.follow":
 // 解析关注事件
 notif = &Notification{RecipientID: evt.VloggerID, SenderID: evt.FollowerID, Type: "follow", Content: "关注了你"}
 }

 if notif == nil {
 return nil
 }

 // 写入DB
 w.db.Create(notif)

 // 实时推送给用户
 w.hub.Push(notif.RecipientID, notif)

 return nil
}

接口设计

接口	方法	作用
`/stream`	GET	SSE 连接，实时接收通知
`/list`	POST	查询通知列表（最近 50 条）
`/markRead`	POST	标记已读
`/unreadCount`	POST	查询未读数量

阶段7：分片上传

为什么需要分片上传

视频文件可能很大（几十 MB 到 200MB），一次上传的问题：

一次上传100MB：
 网络抖动 → 上传到99%断了 → 重头再来
 用户体验极差

分片上传：

100MB文件，分成5MB一片，共20片
 第1片上传成功 ✓
 第2片上传成功 ✓
 ...
 第17片网络断了 ✗
 重新连接 → 只需要重新上传第17片，1-16不用重传

分片上传流程

整体流程

1. 客户端：计算文件MD5 → 调用Init接口 → 获得upload_id + 已上传分片列表
2. 客户端：逐片上传（跳过已上传的） → 每片带MD5校验
3. 客户端：全部上传完 → 调用Complete接口 → 服务器合并分片 → 返回视频URL

流程图

客户端 服务器
 | |
 |--- Init(文件名, 大小, MD5) ----------->|
 |<-- upload_id + 已上传列表 -------------|
 | |
 |--- UploadChunk(分片0, MD5) ----------->| 保存到临时目录
 |<-- chunk_index: 0 ----------------------|
 | |
 |--- UploadChunk(分片1, MD5) ----------->| 保存到临时目录
 |<-- chunk_index: 1 ----------------------|
 | |
 | ...（中间可能断线重连） |
 | |
 |--- Complete(upload_id) --------------->| 合并所有分片
 |<-- url: 视频地址 -----------------------|

核心数据结构

ChunkUploadSession（上传会话）

const ChunkSize = 5 << 20 // 5 MB

type ChunkUploadSession struct {
 UploadID string // 上传会话ID（随机生成）
 AccountID uint // 上传者ID
 Filename string // 原始文件名
 FileSize int64 // 文件总大小
 ChunkSize int64 // 每片大小（默认5MB）
 TotalChunks int // 总片数
 FileHash string // 整个文件的MD5
 UploadedBits []bool // 每片是否已上传（位图）
}

UploadedBits 是什么

UploadedBits: []bool{true, true, true, false, false}

这个数组表示：

分片 0：已上传 ✓
分片 1：已上传 ✓
分片 2：已上传 ✓
分片 3：未上传
分片 4：未上传

用 bool 数组而不是存已上传的分片列表，好处是：

判断某片是否已上传：O(1)，直接 index
判断是否全部上传完：遍历一次，O(n)

两个辅助方法

// 返回已上传的分片索引列表
func (s *ChunkUploadSession) UploadedChunks() []int {
 var indices []int
 for i, uploaded := range s.UploadedBits {
 if uploaded {
 indices = append(indices, i)
 }
 }
 return indices
}

// 判断是否全部上传完
func (s *ChunkUploadSession) IsComplete() bool {
 for _, b := range s.UploadedBits {
 if !b {
 return false
 }
 }
 return true
}

会话存在哪：Redis

上传会话存在 Redis，不是 MySQL，原因是：

存储	读写速度	持久化	适合存什么
Redis	微秒级	可配置过期	临时状态（上传进度）
MySQL	毫秒级	永久	持久数据（用户信息、视频记录）

上传会话是临时的（24 小时过期），用 Redis 更合适。

Redis Key 设计

// 上传会话
func (h *ChunkUploadHandler) sessionKey(uploadID string) string {
 return h.cache.Key("chunk_upload:%s", uploadID)
}

// 文件哈希 → upload_id 的映射（用于断点续传）
func (h *ChunkUploadHandler) hashKey(accountID uint, fileHash string) string {
 return h.cache.Key("chunk_upload_hash:%d:%s", accountID, fileHash)
}

两个 Key 的作用：

chunk_upload:<upload_id>：存完整的上传会话
chunk_upload_hash:<account_id>:<file_hash>：文件哈希到 upload_id 的映射，用于断点续传

四个接口详解

接口 1：InitChunkUpload（初始化上传）

func (h *ChunkUploadHandler) InitChunkUpload(c *gin.Context)

做了什么：

校验请求参数（文件名、大小、哈希、总片数）
检查文件大小是否超过 200MB 限制
断点续传检查：用文件哈希查 Redis，如果找到之前的会话，直接返回
创建新会话，存入 Redis
返回 upload_id + 已上传列表（新上传为空）

断点续传的实现：

// 检查是否有同文件的旧会话
hashKey := h.hashKey(accountID, req.FileHash)
existingID, err := h.cache.GetBytes(c.Request.Context(), hashKey)
if err == nil && len(existingID) > 0 {
 session, sessErr := h.getSession(c, string(existingID))
 if sessErr == nil {
 // 找到了！返回旧的upload_id和已上传列表
 c.JSON(http.StatusOK, gin.H{
 "upload_id": session.UploadID,
 "uploaded_chunks": session.UploadedChunks(),
 })
 return
 }
}

为什么用文件哈希做断点续传？

用户上传 video.mp4（100MB，MD5: abc123）
 → Init，upload_id: xxx，开始上传
 → 上传了15片，浏览器关闭

用户重新选择同一个 video.mp4
 → Init，参数里带同样的 file_hash: abc123
 → 服务器查Redis：chunk_upload_hash:<uid>:abc123 → xxx
 → 找到旧会话！返回已上传的15片
 → 客户端跳过这15片，只上传剩下的5片

接口 2：UploadChunk（上传单片）

func (h *ChunkUploadHandler) UploadChunk(c *gin.Context)

做了什么：

从表单获取 upload_id、chunk_index、chunk_hash
查 Redis 获取会话
校验：会话存在、是本人上传、分片索引合法
幂等检查：如果这片已经上传过，直接返回成功（不重复处理）
读取上传的文件内容，计算 MD5
哈希校验：对比客户端传的 chunk_hash 和实际计算的 MD5
保存分片到临时目录：.run/uploads/tmp/<upload_id>/<chunk_index>
更新 Redis 中的会话状态

幂等设计：

if session.UploadedBits[req.ChunkIndex] {
 c.JSON(http.StatusOK, gin.H{"chunk_index": req.ChunkIndex})
 return
}

如果分片已上传过，直接返回成功，不重复处理。这保证了重试的安全性。

哈希校验：

hash := md5.New()
io.Copy(hash, chunkFile)
actualHash := fmt.Sprintf("%x", hash.Sum(nil))

if actualHash != req.ChunkHash {
 c.JSON(http.StatusBadRequest, gin.H{"error": "chunk hash mismatch"})
 return
}

每个分片都有 MD5 校验，防止传输过程中数据损坏。

分片存储位置：

.run/uploads/tmp/
 └── <upload_id>/
 ├── 0 ← 第0片
 ├── 1 ← 第1片
 ├── 2 ← 第2片
 └── ...

接口 3：ChunkStatus（查询上传状态）

func (h *ChunkUploadHandler) ChunkStatus(c *gin.Context)

返回：upload_id + 已上传分片列表 + 总片数。

用于客户端轮询或断线后查询进度。

接口 4：CompleteChunkUpload（完成上传）

func (h *ChunkUploadHandler) CompleteChunkUpload(c *gin.Context)

做了什么：

校验会话、校验是否本人
检查是否所有分片都已上传（IsComplete()）
如果有未上传的分片，返回错误和缺失信息
合并分片：按顺序读取所有分片，写入最终文件
清理临时文件和 Redis 会话
返回视频 URL

合并过程：

tmpDir := filepath.Join(".run", "uploads", "tmp", req.UploadID)
for i := 0; i < session.TotalChunks; i++ {
 chunkPath := filepath.Join(tmpDir, fmt.Sprintf("%d", i))
 cf, _ := os.Open(chunkPath)
 io.Copy(finalFile, cf) // 按顺序拼接
 cf.Close()
}

最终文件位置：

.run/uploads/
 └── videos/
 └── <account_id>/
 └── <date>/
 └── <random>.mp4

清理：

// 删除临时分片
os.RemoveAll(tmpDir)

// 删除Redis会话
h.cache.Del(ctx, sessionKey)
h.cache.Del(ctx, hashKey)

安全设计

文件大小限制

const maxSize = 200 << 20 // 200MB
if req.FileSize > maxSize {
 c.JSON(http.StatusBadRequest, gin.H{"error": "file size exceeds 200MB limit"})
 return
}

权限校验

每个接口都检查：会话存在 + 是本人操作。

accountID, _ := jwt.GetAccountID(c)
if session.AccountID != accountID {
 c.JSON(http.StatusForbidden, gin.H{"error": "forbidden"})
 return
}

分片哈希校验

每个分片上传时都验证 MD5，防止数据损坏。

接口总结

接口	方法	作用
`/chunk/init`	POST	初始化上传，返回 upload_id
`/chunk/upload`	POST	上传单个分片
`/chunk/status`	POST	查询上传状态
`/chunk/complete`	POST	完成上传，合并分片

面试要点总结

Q: SSE 是什么？

A: Server-Sent Events，服务器主动推送消息给客户端，单向，基于 HTTP。场景：通知、状态更新、新闻推送。

Q: SSE 和 WebSocket 怎么选？

A: 只要服务器推用 SSE（简单），需要双向通信用 WebSocket（复杂）。这个项目用 SSE 推送通知，因为只需要服务器→客户端。

Q: 为什么用 SSE 不用轮询？

A: 轮询客户端每隔几秒问一次，浪费资源、实时性差。SSE 服务器有消息就推，省资源、实时性高。

Q: 心跳机制是什么？

A: 每 30 秒发一次空消息（keepalive），告诉客户端"我还活着"。客户端 30 秒没收到，知道连接断了，重新连接。

Q: Push 为什么用 RLock？

A: Push 只读 map 不改 map，用读锁可以多个 Push 并发。Subscribe/Unsubscribe 要改 map，用写锁必须独占。

Q: select 里的 default 是干什么的？

A: 防阻塞。channel 满了塞不进去就跳过，保证一个用户的消息堆积不影响其他用户。

Q: 为什么要分片上传？

A: 大文件一次上传，网络断了要重头来。分片后断点续传，只需重传失败的分片。

Q: 断点续传怎么实现？

A: 用文件 MD5 做唯一标识，Init 时查 Redis 是否有同文件的旧会话。有就返回已上传列表，客户端跳过这些分片。

Q: 上传会话存在哪？为什么？

A: 存 Redis，因为是临时状态（24 小时过期），读写快。MySQL 存持久数据。

Q: 怎么保证分片数据没损坏？

A: 每片上传时计算 MD5，和客户端传的 chunk_hash 对比，不匹配就拒绝。

Q: 分片重复上传怎么办？

A: 幂等设计——检查 UploadedBits，已上传的分片直接返回成功，不重复处理。

Q: 会话里 UploadedBits 是什么？

A: bool 数组，每个元素对应一个分片是否已上传。长度等于总片数，直接用下标访问，O(1) 判断某片是否已上传。

Go 项目反推：Feed 流系统实战——工程化

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——SSE 实时推送与分片上传，这一篇回到工程全景，梳理 feedsystem_video_go 的容器编排、配置管理、性能分析、持续集成与本地启动流程。

Docker Compose（容器编排）

什么是 Docker Compose

把所有服务打包成容器，一键启动。

没有 Docker Compose：

手动启动MySQL → 手动启动Redis → 手动启动RabbitMQ → 手动启动Backend → 手动启动Worker → 手动启动Frontend
每次都要敲6条命令，还要记住启动顺序

有 Docker Compose：

docker compose up -d
一键启动所有服务

这个项目的 Docker Compose

services:
 mysql: # 数据库
 redis: # 缓存
 rabbitmq: # 消息队列
 backend: # API进程
 worker: # Worker进程
 frontend: # 前端

相关文件：~/dev/projects/feedsystem_video_go/docker-compose.yml

depends_on + healthcheck（保证启动顺序）

depends_on 是什么

告诉 Docker：某个服务依赖其他服务，要等依赖的服务启动后才能启动自己。

backend:
 depends_on:
 mysql:
 condition: service_healthy  # MySQL健康了才启动backend
 redis:
 condition: service_healthy  # Redis健康了才启动backend
 rabbitmq:
 condition: service_healthy  # RabbitMQ健康了才启动backend

healthcheck 是什么

判断服务是否"健康"（真正能接受连接）。

mysql:
 healthcheck:
 test: ["CMD-SHELL", "mysqladmin ping -h 127.0.0.1 -uroot -p123456"]
 interval: 5s  # 每5秒检查一次
 timeout: 5s  # 超时5秒
 retries: 20 # 重试20次

MySQL 启动后，每 5 秒 ping 一次，连续 ping 成功才算"健康"。

为什么要 healthcheck

没有healthcheck：
 MySQL容器启动了 → backend立刻启动
 但MySQL还没初始化完 → backend连接失败 → 崩溃

有healthcheck：
 MySQL容器启动了 → 等MySQL真正能接受连接 → backend再启动

所有服务的 healthcheck

服务	healthcheck 测试	作用
mysql	`mysqladmin ping`	确认 MySQL 能接受连接
redis	`redis-cli ping`	确认 Redis 能接受连接
rabbitmq	`rabbitmq-diagnostics ping`	确认 RabbitMQ 能接受连接
backend	`wget http://127.0.0.1:8080/healthz`	确认 API 进程正常
worker	`pgrep worker`	确认 Worker 进程存在
frontend	`wget http://127.0.0.1:80/`	确认前端能访问

配置管理（优先级）

配置文件位置

~/dev/projects/feedsystem_video_go/backend/configs/
├── config.yaml # 本地开发用（MySQL端口3306）
├── config.compose-local.yaml # Docker Compose本地用（MySQL端口3307）
└── config.docker.yaml # Docker部署用（容器内部通信）

三个配置文件的区别

文件	MySQL 端口	用途
config.yaml	3306	本地开发，MySQL 装在本机
config.compose-local.yaml	3307	Docker Compose，MySQL 容器映射到 3307
config.docker.yaml	3306	Docker 部署，容器内部通信

配置加载优先级

环境变量 > .env文件 > YAML文件

来源	举例	优先级
环境变量	`export MYSQL_DATABASE=feedsystem`	最高
.env 文件	`MYSQL_DATABASE=feedsystem`	中
YAML 文件	`database.dbname: feedsystem`	最低

为什么要这样设计

开发环境：
 用YAML文件，配置写死在代码里，方便开发

Docker部署：
 用环境变量覆盖，不用改配置文件

 docker run -e MYSQL_DATABASE=feedsystem -e JWT_SECRET=*** ...

环境变量覆盖的好处

场景	做法
本地开发	用 YAML 文件的默认配置
Docker 部署	用环境变量覆盖数据库地址、密码等
生产环境	用环境变量覆盖，敏感信息不写进代码

启动时指定配置文件

# 本地开发
cd backend && CONFIG_PATH=configs/config.yaml go run ./cmd

# Docker Compose本地
cd backend && CONFIG_PATH=configs/config.compose-local.yaml go run ./cmd

API 进程和 Worker 进程为什么要分开

两个进程

cmd/
├── main.go # API进程（处理HTTP请求）
└── worker/
 └── main.go # Worker进程（消费MQ消息）

各自做什么

	API 进程	Worker 进程
职责	处理 HTTP 请求	消费 MQ 消息
入口	`go run ./cmd`	`go run ./cmd/worker`
启动方式	接收 HTTP 请求	订阅 MQ 队列

为什么要分开

1. 职责不同

API进程：用户发请求 → 处理 → 返回响应（要求快）
Worker进程：从MQ取消息 → 更新DB、推送通知（可以慢）

2. 独立扩展

场景：API扛不住了

没分开：只能整体加机器
分开后：只加API机器，Worker不动

场景：Worker扛不住了

分开后：只加Worker机器，API不动

3. 故障隔离

Worker崩了：不影响API，用户还能正常访问
API崩了：不影响Worker，后台任务还在处理

4. 资源分配不同

API进程：需要低延迟，分配更多CPU
Worker进程：可以容忍高延迟，分配更多内存

Docker Compose 里的配置

backend:
 build:
 dockerfile: backend/Dockerfile
 target: api  # 构建API镜像

worker:
 build:
 dockerfile: backend/Dockerfile
 target: worker  # 构建Worker镜像

同一个 Dockerfile，用不同的 target 构建两个镜像。

pprof（性能分析）

pprof 是什么

Go 内置的性能分析工具，帮你找出程序哪里慢、哪里吃内存。

能分析什么

类型	作用
CPU	哪个函数最耗 CPU
内存	哪个函数最耗内存
goroutine	有没有 goroutine 泄漏
阻塞	哪里卡住了

配置

observability:
 pprof:
 enabled: true
 api_addr: localhost:6060  # API进程的pprof端口
 worker_addr: localhost:6061  # Worker进程的pprof端口

启动后，访问 http://localhost:6060/debug/pprof/ 就能看到性能数据。

常用命令

# CPU分析（30秒）
go tool pprof http://localhost:6060/debug/pprof/profile?seconds=30

# 内存分析
go tool pprof http://localhost:6060/debug/pprof/heap

# goroutine分析
go tool pprof http://localhost:6060/debug/pprof/goroutine

场景举例

用户反馈：API响应慢

1. 用pprof抓CPU分析
2. 发现某个函数占了80%的CPU时间
3. 优化这个函数
4. 响应变快了

CI 流程（持续集成）

CI 是什么

代码推送到 GitHub 后，自动运行检查，确保代码质量。

这个项目的 CI

# .github/workflows/ci.yml
jobs:
 test:
 steps:
 - go vet ./...  # 静态检查
 - go test -race ./...  # 运行测试，检测数据竞争

go vet 是什么

静态分析，找出语法错误和可疑代码，不需要运行程序。

举例：
- 变量声明了但没用
- 格式化字符串参数不对
- 死代码（永远不会执行的代码）

go test -race 是什么

运行测试，同时检测数据竞争。

什么是数据竞争

多个 goroutine 同时读写同一个变量，没有加锁。

// 数据竞争的例子
var count int

go func() { count++ }() // goroutine1写
go func() { count++ }() // goroutine2写

// 两个goroutine同时写count，结果不确定

-race 怎么检测

go test -race ./...

如果发现数据竞争：
 WARNING: DATA RACE
 Write by goroutine 1
 Read by goroutine 2
 ...
 FAIL

CI 流程

开发者推送代码到GitHub
 ↓
GitHub Actions自动触发
 ↓
go vet ./... → 静态检查
 ↓
go test -race ./... → 运行测试 + 检测数据竞争
 ↓
全部通过 → 绿色 ✅
有失败 → 红色 ❌，不允许合并

好处

	没有 CI	有 CI
代码质量	靠人工 review	自动检查
数据竞争	上线后才发现	提交时就发现
合并代码	随便合并	检查通过才能合并

启动脚本（start.sh）

一键启动所有服务

./start.sh

相关文件：~/dev/projects/feedsystem_video_go/start.sh

脚本是什么语言写的

Bash（Shell 脚本），文件扩展名 .sh = Shell 脚本。

#!/usr/bin/env bash # 声明用bash解释器
set -euo pipefail # 遇到错误立刻停止

Bash 是 Linux/macOS 终端的脚本语言，用来自动化命令行操作。

脚本做的事

1. 启动Redis（如果没有运行）
2. 启动RabbitMQ（通过Docker Compose）
3. 启动Backend（go run ./cmd）
4. 启动Worker（go run ./cmd/worker）
5. 启动Frontend（npm run dev）
6. Ctrl+C停止所有服务

核心逻辑

# 启动Redis
start_redis() {
 redis-server --bind 127.0.0.1 --port 6379
}

# 启动RabbitMQ（通过Docker Compose）
start_rabbitmq_compose() {
 docker compose up -d rabbitmq
}

# 启动Backend
start_backend_bg() {
 cd backend && go run ./cmd &
}

# 启动Worker
start_worker_bg() {
 cd backend && go run ./cmd/worker &
}

# 启动Frontend
start_frontend_bg() {
 cd frontend && npm run dev &
}

# Ctrl+C停止所有服务
trap cleanup INT TERM EXIT
cleanup() {
 kill $BACKEND_PID
 kill $WORKER_PID
 kill $FRONTEND_PID
 docker compose stop
}

环境变量控制

START_REDIS=1 # 是否启动Redis
START_RABBITMQ=1 # 是否启动RabbitMQ
START_BACKEND=1 # 是否启动Backend
START_WORKER=1 # 是否启动Worker
START_FRONTEND=1 # 是否启动Frontend

可以按需启动：

# 只启动Backend和Worker
START_FRONTEND=0 ./start.sh

面试要点总结

Q: Docker Compose 怎么保证启动顺序？

A: depends_on + healthcheck，服务健康了才启动下一个。

Q: 配置优先级？

A: 环境变量 > .env 文件 > YAML 文件。

Q: API 和 Worker 为什么要分开？

A: 职责不同、独立扩展、故障隔离、资源分配不同。

Q: pprof 能分析什么？

A: CPU、内存、goroutine、阻塞。

Q: CI 做了什么？

A: go vet 静态检查 + go test -race 检测数据竞争。

Q: 什么是数据竞争？

A: 多个 goroutine 同时读写同一个变量，没有加锁。用 go test -race 检测。

Q: 为什么要用 healthcheck？

A: 确保服务真正能接受连接，而不是只启动了容器。

Go 项目反推：Feed 流系统实战——消息队列与异步架构

Wed, 29 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——Redis 缓存设计，这一篇继续反推 feedsystem_video_go 的消息队列与异步架构，梳理 RabbitMQ 的消息路由、消费重试、降级策略、Outbox 模式和死信队列。

什么是消息队列（MQ）

想象一个餐厅：

没有 MQ：顾客点餐 → 厨师做完一个才能做下一个 → 顾客等着
有 MQ：顾客点餐 → 写在小票上放窗口 → 厨师按顺序做 → 做好了喊号

消息队列就是那个"窗口"，消息就是"小票"。

为什么需要消息队列

用户点赞后要做的事：

用户点赞 → 更新Like表 → 更新Video点赞数 → 更新热度 → 推送通知 → 返回成功

没有 MQ 的问题：

用户等太久（每个操作都要时间）
任何一个失败，整个流程卡住
高并发时 DB 扛不住

有了 MQ：

用户点赞 → 更新Like表 → 发一条"点赞消息"到MQ → 立刻返回成功
 ↓
 Worker从MQ取消息 → 更新点赞数 → 更新热度 → 推送通知

好处：

用户不用等所有操作完成，体验快
点赞服务和热度计算服务解耦，改一个不影响另一个
高并发时消息排队，DB 不会被打垮

MQ 的三个核心概念

概念	比喻	作用
Exchange	邮局	接收消息，根据规则分发
Queue	邮箱	存储消息，等 Worker 来取
Routing Key	地址	消息的"目的地"，Exchange 根据它决定放哪个 Queue

流程：

生产者（点赞服务） → 发消息到Exchange → Exchange根据Routing Key → 放到Queue → Worker从Queue取消息消费

三种 Exchange 类型

类型	规则	举例
Direct	Routing Key 完全匹配	发到"like.like"，只有绑定了"like.like"的 Queue 才能收到
Topic	支持通配符（* 和 #）	发到"like.*"，能匹配"like.like"、“like.unlike”
Fanout	广播，忽略 Routing Key	发到所有绑定的 Queue，每个 Queue 都能收到

这个项目用的是 Topic Exchange。

项目里的 6 种 MQ

Exchange	Routing Key	用途
like.events	like.like / like.unlike	点赞/取消点赞
comment.events	comment.publish / comment.delete	评论/删除评论
social.events	social.follow / social.unfollow	关注/取关
video.popularity.events	video.popularity.update	热度更新
video.timeline.events	video.timeline.publish	视频发布
dlx.events	#	死信队列（重试/告警）

代码实现

MQ 相关文件

backend/internal/middleware/rabbitmq/
├── rabbitMQ.go # MQ基础封装（连接、Channel、DeclareTopic、PublishJSON）
├── dlx.go # 死信队列声明和重试计数
├── likeMQ.go # 点赞MQ
├── commentMQ.go # 评论MQ
├── socialMQ.go # 关注MQ
├── popularityMQ.go # 热度MQ
└── timelineMQ.go # Feed流MQ（Outbox模式）

Worker 相关文件

backend/internal/worker/
├── likeworker.go # 点赞Worker
├── commentworker.go # 评论Worker
├── socialworker.go # 关注Worker
├── popularityworker.go # 热度Worker
├── outboxworker.go # Outbox定时任务
├── notificationworker.go # 通知Worker
└── ssehub.go # SSE推送Hub

消息生产（发消息）

rabbitMQ.go - PublishJSON

func PublishJSON(ctx context.Context, ch *amqp.Channel, exchange string, routingKey string, payload any) error {
 b, _ := json.Marshal(payload) // 第1步：把数据变成JSON
 return ch.PublishWithContext(ctx, exchange, routingKey, false, false, amqp.Publishing{
 ContentType: "application/json", // 第2步：告诉MQ这是JSON格式
 DeliveryMode: amqp.Persistent, // 第3步：消息持久化
 Body: b, // 第4步：消息内容
 })
}

逐行解释：

json.Marshal(payload)：把 Go 结构体变成 JSON 字节
ch.PublishWithContext(...)：调用 MQ 客户端，发一条消息
exchange：发到哪个 Exchange（邮局）
routingKey：消息地址（like.like）
amqp.Persistent：消息存到磁盘，MQ 重启不丢
Body: b：消息内容

消息长什么样

{
 "video_id": 123,
 "account_id": 456,
 "event_type": "like.like",
 "timestamp": "2026-07-28T14:30:00Z"
}

就是一个 JSON，告诉 Worker"用户 456 给视频 123 点了赞"。

消息消费（Worker 处理）

likeworker.go - Run

func (w *LikeWorker) Run(ctx context.Context) error {
 deliveries, err := w.ch.Consume(w.queue, "", false, false, false, false, nil)

 for {
 select {
 case <-ctx.Done():
 return ctx.Err()
 case d, ok := <-deliveries:
 if !ok {
 return errors.New("deliveries channel closed")
 }
 w.handleDelivery(ctx, d)
 }
 }
}

逐行解释：

w.ch.Consume(w.queue, ...)：从 Queue 订阅消息，返回一个 channel
for { select { ... } }：循环读消息，有消息来就处理
w.handleDelivery(ctx, d)：调用处理函数，执行业务逻辑

handleDelivery - 重试逻辑

func (w *LikeWorker) handleDelivery(ctx context.Context, d amqp.Delivery) {
 const maxRetries = 3
 for i := 0; i <= maxRetries; i++ {
 if err := w.process(ctx, d.Body); err != nil {
 if i >= maxRetries {
 // 超过3次，放弃，Ack删除消息
 log.Printf("like worker: 重试 %d 次后仍失败, 丢弃", maxRetries)
 _ = d.Ack(false)
 return
 }
 // 等一下再重试（指数退避）
 wait := time.Duration(1<<uint(i)) * time.Second // 1s, 2s, 4s
 log.Printf("like worker: 处理失败, %v 后重试 (%d/%d)", wait, i+1, maxRetries)
 time.Sleep(wait)
 continue
 }
 // 成功，Ack删除消息
 _ = d.Ack(false)
 return
 }
}

重试流程：

第1次处理 → 失败 → 等1秒
第2次处理 → 失败 → 等2秒
第3次处理 → 失败 → 等4秒
第4次处理 → 失败 → 放弃，Ack删除消息

指数退避（1s → 2s → 4s）

1<<uint(i) 是位运算：

i=0: 1«0 = 1秒
i=1: 1«1 = 2秒
i=2: 1«2 = 4秒

为什么要等这么久？避免疯狂重试打垮服务器。

为什么失败了还 Ack？

不 Ack 的话，消息会一直留在 Queue 里，Worker 会一直重试，卡住后面的消息。Ack 后消息从 Queue 删除，避免阻塞。

MQ 发布失败的降级策略

场景：用户点赞成功，DB 写入了，但发 MQ 消息失败了。

如果直接忽略：热度不会更新，点赞数据和热度不一致。

fallback 直写

func (s *LikeService) publishLikeEvent(ctx context.Context, videoID, accountID uint, routingKey string) {
 event := LikeEvent{VideoID: videoID, AccountID: accountID}

 err := rabbitmq.PublishJSON(ctx, s.ch, "like.events", routingKey, event)
 if err != nil {
 // MQ发送失败，降级：直接更新热度
 go s.popularityWorker.HandleLikeEvent(event)
 }
}

意思：

MQ 能用 → 走 MQ 异步处理
MQ 挂了 → 直接调 Worker 的处理函数，同步处理

为什么不用重试？如果 MQ 挂了，重试大概率还是失败，用户要等很久。直接降级：虽然绕过了 MQ，但保证功能正常，用户体验不受影响。

Outbox 模式

什么是 Outbox 模式

发视频时用的模式。

场景：用户发视频 → 更新 DB → 发 MQ 消息

问题：如果 DB 更新成功，MQ 发送失败，视频发布了但 Feed 流里没有。

为什么不能放在一个事务里？DB 和 MQ 是两个系统，没法用一个事务包起来。

Outbox 的解法

把 MQ 消息先存到数据库里，用数据库事务保证一致性：

数据库事务（保证原子性）：
 INSERT INTO videos (title, play_url, ...) VALUES (...)
 INSERT INTO outbox_msgs (video_id, status) VALUES (xxx, 'pending')
 COMMIT

两步在同一个 DB 事务里，要么都成功，要么都失败。

然后用定时任务把消息发出去：

OutboxPoller（每秒运行一次）：

 查询：SELECT * FROM outbox_msgs WHERE status = 'pending'

 对于每条消息：
 发MQ消息
 更新：UPDATE outbox_msgs SET status = 'sent' WHERE id = xxx

OutboxMsg 表结构

type OutboxMsg struct {
 ID uint
 VideoID uint
 EventType string
 CreateTime time.Time
 Status string // "pending" 或 "sent"
}

完整流程

00:00 用户发视频
 → 写Video表 + 写OutboxMsg表（同一个事务，保证原子）

00:01 OutboxPoller扫到这条消息
 → 发MQ消息成功
 → 标记为sent

00:02 Worker收到MQ消息
 → 更新Feed流

为什么这样能保证消息不丢？

消息先存在 DB 里，和业务数据在同一个事务
定时任务保证最终会发出去
即使 MQ 暂时挂了，消息还在 DB 里，等 MQ 恢复了再发

回滚只发生在 DB 层面

数据库事务：
 INSERT INTO videos ... → 成功
 INSERT INTO outbox_msgs ... → 失败
 ROLLBACK → 两个都撤销

MQ 发送失败不回滚：

数据库事务：COMMIT（消息已经存到outbox_msgs表了）

OutboxPoller：
 发MQ消息 → 失败（MQ挂了）

 → 不回滚！消息还在outbox_msgs表里
 → 等MQ恢复了，下次扫描再发

为什么发视频用 Outbox，点赞不用？

场景	方案	原因
点赞	直接发 MQ + fallback	点赞失败可以重试，用户能接受
发视频	Outbox 模式	视频必须进 Feed 流，不能丢

视频发布是关键业务，不能丢消息，所以用 Outbox 保证"至少发一次"。

死信队列（DLX）

什么是死信队列

消息"死了"（消费失败），放到一个专门的队列里等处理。

就像快递派送失败：

正常流程：快递 → 送到你家 → 签收

派送失败：快递 → 送到你家 → 没人签收 → 退回快递站（死信队列）
 → 重新派送（重试）
 → 联系收件人（告警）

消息为什么会"死"

原因	举例
业务逻辑报错	热度计算除零了
消费超时	Worker 处理太久，MQ 等不及了
拒绝消息	代码里主动 reject

正常消费流程

Worker从Queue取消息
 ↓
处理成功 → msg.Ack() → MQ删除消息

消费失败了

Worker从Queue取消息
 ↓
处理失败 → msg.Nack() 或 超时
 ↓
MQ把消息放到死信队列（DLX）
 ↓
死信Worker处理：
 - 记录日志
 - 重试（最多N次）
 - 超过重试次数 → 告警/人工处理

dlx.go - DeclareDLX

const DLXExchange = "dlx.events"
const MaxRetryCount = 3

func DeclareDLX(ch *amqp.Channel, queueName string) error {
 // 1. 声明死信Exchange
 ch.ExchangeDeclare(DLXExchange, "topic", true, false, false, false, nil)

 // 2. 声明死信Queue（名字是 原Queue名 + ".dlx"）
 dlxQueue := queueName + ".dlx"
 ch.QueueDeclare(dlxQueue, true, false, false, false, nil)

 // 3. 绑定：# 匹配所有Routing Key
 ch.QueueBind(dlxQueue, "#", DLXExchange, false, nil)
}

like.events 的死信队列叫 like.events.dlx
comment.events 的死信队列叫 comment.events.dlx

GetRetryCount - 获取重试次数

func GetRetryCount(d amqp.Delivery) int {
 deaths, ok := d.Headers["x-death"].([]interface{})
 if !ok || len(deaths) == 0 {
 return 0
 }
 death, ok := deaths[0].(amqp.Table)
 if !ok {
 return 0
 }
 count, ok := death["count"].(int64)
 if !ok {
 return 0
 }
 return int(count)
}

MQ 会自动在消息头里记录"这条消息死了几次"，从 x-death 里取出来。

正常 Queue 声明时绑定 DLX

func DeclareTopic(ch *amqp.Channel, exchange string, queue string, bindingKey string) error {
 // 声明Exchange
 ch.ExchangeDeclare(exchange, "topic", true, false, false, false, nil)

 // 声明Queue，绑定死信Exchange
 q, err := ch.QueueDeclare(queue, true, false, false, false,
 amqp.Table{"x-dead-letter-exchange": DLXExchange})

 // 绑定：Queue订阅Exchange的消息
 ch.QueueBind(q.Name, bindingKey, exchange, false, nil)
}

x-dead-letter-exchange：告诉 MQ，这个 Queue 的消息如果"死了"，发到 DLXExchange。

完整流程举例

正常流程：
 点赞 → like.events Queue → LikeWorker消费 → 成功 → Ack

失败流程：
 点赞 → like.events Queue → LikeWorker消费 → 失败 → Nack
 ↓
 like.events.dlx Queue（死信队列）
 ↓
 死信Worker处理（重试/告警）

API 进程和 Worker 进程为什么要分开

cmd/
├── main.go # API进程（处理HTTP请求）
└── worker/
 └── main.go # Worker进程（消费MQ消息）

分开的原因：

职责不同：API 处理请求，Worker 处理后台任务
独立扩展：API 扛不住加 API 机器，Worker 扛不住加 Worker 机器
故障隔离：Worker 崩了不影响 API，API 崩了不影响 Worker
资源分配：API 需要低延迟，Worker 可以容忍高延迟

ch.Qos(50, 0, false) - 预取数量控制

ch.Qos(50, 0, false)

50：每次最多取 50 条消息
0：不限制消息大小
false：只对当前 Channel 生效

为什么要控制预取数量？

太多：Worker 内存爆了
太少：Worker 闲着没事干
50：平衡点，Worker 处理完一批再取下一批

面试要点总结

Q: 为什么用 MQ？

A: 削峰（高并发时消息排队）、解耦（点赞服务和热度计算独立）、异步（用户不用等所有操作完成）。

Q: MQ 发布失败了怎么办？

A: 降级策略，直接调 Worker 的处理函数同步处理。点赞用 fallback 直写，发视频用 Outbox 模式保证消息不丢。

Q: Outbox 模式是什么？

A: 把 MQ 消息先存到数据库里，用 DB 事务保证一致性。定时任务扫描 outbox_msgs 表，发 MQ 消息，标记已发送。

Q: 死信队列怎么用的？

A: 消息消费失败时，MQ 自动把消息放到死信队列。Worker 里有重试逻辑，最多重试 3 次，指数退避（1s→2s→4s），超过 3 次放弃。

Q: API 进程和 Worker 进程为什么要分开？

A: 职责不同、独立扩展、故障隔离、资源分配不同。

Q: 什么是指数退避？

A: 重试间隔按 2 的幂次增长（1s→2s→4s），避免疯狂重试打垮服务器。

Q: 三种 Exchange 的区别？

A: Direct 精确匹配，Topic 支持通配符，Fanout 广播到所有 Queue。

Q: 为什么点赞用 fallback，发视频用 Outbox？

A: 点赞失败用户能接受重试，视频发布是关键业务不能丢消息。Outbox 保证"至少发一次"。

Go 项目反推：Feed 流系统实战——Redis 缓存设计

Tue, 28 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——数据库与 GORM，这一篇继续反推 feedsystem_video_go 的 Redis 设计，梳理缓存读写、一致性与高并发防护，以及 Lua 限流和 ZSET 热榜的实现。

项目里 Redis 的 7 种用途

#	用途	数据结构	Key模式
1	JWT Token 缓存	String	`account:<id>`
2	Refresh Token 缓存	String	`account:<id>:refresh` / `refresh:<token>`
3	视频详情缓存	String(JSON)	`video:detail:id=<id>`
4	视频实体缓存	String(JSON)	`video:entity:<id>`
5	热榜	ZSET	`hot:video:1m:<时间窗口>`
6	分片上传会话	String(JSON)	`chunk_upload:<upload_id>`
7	接口限流	String(计数器)	`ratelimit:<prefix>:<subject>`

1. 缓存读取流程（video_service.go 的 GetDetail）

func (vs *VideoService) GetDetail(ctx context.Context, id uint) (*Video, error) {
 cacheKey := vs.cache.Key("video:detail:id=%d", id)

 // 第一步：查缓存（50ms 超时）
 getCached := func() (*Video, bool) {
 opCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
 defer cancel()

 b, err := vs.cache.GetBytes(opCtx, cacheKey)
 if err != nil {
 return nil, false // 缓存没命中
 }
 var cached Video
 if err := json.Unmarshal(b, &cached); err != nil {
 return nil, false // 数据损坏
 }
 return &cached, true // 缓存命中
 }

 // 尝试读缓存
 if v, ok := getCached(); ok {
 return v, nil // 命中，直接返回
 }

 // 缓存没命中，查数据库...
}

为什么缓存读取要设 50ms 超时？

50ms 超时不是判断"没命中"，而是防止 Redis 卡住的降级策略：

缓存没命中：Redis 快速返回"key 不存在"，几毫秒就完成
Redis 卡住：网络抖动、Redis 内部阻塞、连接池耗尽，可能卡几秒

没有超时：Redis 卡住 → 请求一直等着 → 用户体验很差有 50ms 超时：Redis 超过 50ms 没响应 → 放弃缓存 → 直接查数据库

为什么不设更短的超时，比如 5ms？

Redis 正常操作本身需要几毫秒，设 5ms 正常情况都可能超时，缓存形同虚设。50ms 是平衡点：覆盖正常操作 + 轻微网络波动，同时不会让用户等太久。

2. 缓存写入

setCached := func(video *Video) {
 b, err := json.Marshal(video)
 if err != nil {
 return
 }
 opCtx, cancel := context.WithTimeout(ctx, 50*time.Millisecond)
 defer cancel()
 _ = vs.cache.SetBytes(opCtx, cacheKey, b, vs.cacheTTL)
}

为什么缓存要设过期时间（TTL）？

TTL = Time To Live，缓存的"保质期"。

主要原因：数据一致性

09:00 缓存存了视频标题"今天天气真好"
09:05 作者把标题改成"今天下雨了"
 → 数据库更新了，但缓存还是旧的
09:06 用户查这个视频 → 从缓存读到"今天天气真好"
 → 看到的是过期数据

没有 TTL：缓存永远是旧数据，用户看到的和数据库不一致有了 TTL（比如 10 分钟）：最多 10 分钟后缓存自动过期，下次请求加载最新数据

这是用时间换一致性：允许短暂不一致，但最终会一致。

次要原因：缓存空间有限

缓存满了需要淘汰旧数据，TTL 帮助自动清理。

3. 缓存删除（主动失效）

为什么不等 TTL 过期，要主动删缓存？

看 video_service.go 删视频时：

func (vs *VideoService) DeleteVideo(ctx context.Context, id uint) error {
 // 先删数据库
 if err := vs.repo.DeleteVideo(ctx, id); err != nil {
 return err
 }
 // 再删缓存
 if vs.cache != nil {
 cacheKey := vs.cache.Key("video:detail:id=%d", id)
 _ = vs.cache.Del(context.Background(), cacheKey)
 }
 return nil
}

DB 更新后立刻删缓存，下次请求来了缓存没命中，从数据库加载最新数据。

4. 缓存和 DB 的一致性策略

两种方案对比

方案	做法	风险
先删缓存，再更新 DB	删缓存 → 写 DB	删完缓存、还没写 DB 时，另一个请求读 DB 旧数据写入缓存
先更新 DB，再删缓存	写 DB → 删缓存	写完 DB、还没删缓存时，另一个请求读到旧缓存

为什么"先更新 DB 再删缓存"更安全？

方案 1：先删缓存，再更新 DB

00:00 请求A：删缓存
00:01 请求B：查视频 → 缓存没命中 → 从DB读到旧数据 → 写入缓存
00:02 请求A：更新DB为新数据

结果：DB是新数据，缓存里是旧数据（脏数据）

发生概率不低，因为"删缓存"到"更新 DB"之间可能有几百毫秒（DB 写入比 Redis 慢）。

方案 2：先更新 DB，再删缓存

00:00 请求A：更新DB为新数据
00:01 请求B：查视频 → 从缓存读到旧数据（概率小）
00:02 请求A：删缓存

结果：即使请求B读到旧缓存，00:02缓存就被删了

出问题窗口极小：必须在"更新 DB"和"删缓存"之间，恰好有另一个请求来读。

共同风险点：删缓存失败了怎么办？

00:00 更新DB成功 → DB是新数据
00:01 删缓存失败（网络抖动、Redis挂了）
 → 缓存还是旧数据

解决方案：靠 TTL 兜底

代码里删缓存都用了 _ = 忽略错误：

_ = vs.cache.Del(context.Background(), cacheKey)

即使删缓存失败，最多等 TTL 过期（比如 10 分钟），缓存自动失效，下次请求从 DB 加载新数据。

这是最终一致性：允许短暂不一致，但最终会一致。

5. 缓存穿透/击穿/雪崩

三个概念的区别

问题	现象	危害
缓存穿透	查询不存在的数据，缓存永远没命中	每次请求都打到 DB
缓存击穿	热点 key 过期，大量请求同时打到 DB	DB 瞬间压力暴增
缓存雪崩	大量 key 同时过期	DB 瞬间压力暴增

缓存击穿的解法（这个项目用的）

场景：一个热门视频的缓存过期了，100 个用户同时请求

// 缓存没命中，尝试获取分布式锁
lockKey := "lock:" + cacheKey
token, locked, lockErr := vs.cache.Lock(lockCtx, lockKey, 2*time.Second)

if lockErr == nil && locked {
 // 拿到锁：去查DB，回填缓存
 defer func() { _ = vs.cache.Unlock(context.Background(), lockKey, token) }()

 video, err := vs.repo.GetByID(ctx, id)
 if err != nil {
 return nil, err
 }
 setCached(video)
 return video, nil
}

// 没拿到锁：等待别人回填缓存（最多100ms）
for i := 0; i < 5; i++ {
 time.Sleep(20 * time.Millisecond)
 if v, ok := getCached(); ok {
 return v, nil // 别人已经回填了，直接用
 }
}

// 降级：直接查DB
video, err := vs.repo.GetByID(ctx, id)

核心逻辑：让一个请求干活，其他请求等着用结果

❌ 没有锁的击穿场景：
100个请求同时来 → 缓存没命中 → 100个都去查DB → DB压力x100

✅ 有锁的保护：
100个请求同时来 → 缓存没命中
 ↓
请求1：拿到锁 → 查DB → 写缓存 → 返回
请求2-100：没拿到锁 → 等20ms → 查缓存 → 命中 → 返回

时序示例（DB 查询 15ms）：

00:00 请求1拿到锁，开始查DB（耗时15ms）
 请求2-100没拿到锁，开始sleep 20ms
00:15 请求1查完DB，写入缓存
00:20 请求2-100醒来，查缓存 → 命中！

降级策略（DB 查询很慢时）：

请求 2-100 最多等 100ms（5次x20ms），如果请求 1 还没完成，降级去查 DB。

但这种情况很少见，DB 查询通常几毫秒到几十毫秒。

缓存穿透的解法（这个项目没做）

缓存穿透：查询不存在的数据，比如 GET /video/999999999，数据库里没有，每次请求都打到 DB。

方案	做法
缓存空值	查 DB 没结果，也写入缓存（value=""），设短 TTL
布隆过滤器	在缓存前加一层，快速判断 key 是否存在

项目为什么没做：视频 ID 通过 Feed 流返回，不存在"查不存在 ID"的正常场景。接口有限流保护，攻击成本高。

缓存雪崩的解法（这个项目没做）

缓存雪崩：大量 key 同时过期，DB 瞬间压力暴增。

方案	做法
随机 TTL	给缓存 TTL 加随机值，避免同时过期
多级缓存	L1 本地缓存 + L2 Redis 缓存
永不过期 + 异步更新	缓存不设 TTL，由后台任务定期更新

项目用的是固定 TTL，没做随机化，业务量可控。

6. 限流中间件（ratelimit.go）

限流是什么？

防止用户发太多请求打垮服务器。像银行取号机：每分钟最多服务 100 个人，第 101 个人来了告诉他"请稍后再来"。

限流中间件是什么？

Gin 中间件，所有请求都要经过它：

用户请求 → 限流中间件检查 → 通过 → handler处理 → 返回
 ↓
 超限 → 直接返回429 "too many requests"

限流实现原理

func Limit(cache *rediscache.Client, keyPrefix string, maxRequests int64, window time.Duration, keyFunc KeyFunc) gin.HandlerFunc {
 return func(c *gin.Context) {
 subject, ok := keyFunc(c)
 key := buildKey(keyPrefix, subject)

 count, err := cache.IncrementWithExpire(c.Request.Context(), key, window)
 if err != nil {
 c.Next()
 return
 }
 if count > maxRequests {
 c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{"error": "too many requests"})
 return
 }
 c.Next()
 }
}

IncrementWithExpire 的 Lua 脚本

local count = redis.call("INCR", KEYS[1])
if count == 1 then
 redis.call("PEXPIRE", KEYS[1], ARGV[1])
end
return count

限流流程（1 分钟内最多 100 次）：

00:00.000 请求1来 → INCR → count=1
 因为count==1，是第一个请求
 → PEXPIRE设60000毫秒（60秒）过期

00:00.001 请求2来 → INCR → count=2
 count!=1，不设过期（沿用之前的）

...

00:00.500 请求100来 → INCR → count=100
 → 通过（100 <= 100）

00:00.600 请求101来 → INCR → count=101
 → 拒绝！（101 > 100）
 → 返回429 "too many requests"

01:00.000 key自动过期，Redis删除这个key
 计数器归零

01:00.001 请求来 → INCR → count=1（重新开始计数）
 → PEXPIRE重新设60秒
 → 通过

为什么用 Lua 脚本？

原子执行 = 两条命令之间不会有其他命令插队

没有 Lua 脚本（可能被插队）：

00:00 你的程序：INCR key → count=1
00:01 另一个程序：INCR key → count=2
00:02 你的程序：EXPIRE key 60秒
00:03 另一个程序：EXPIRE key 60秒

你的 INCR 和 EXPIRE 之间，被别人插队了。

有 Lua 脚本（不会插队）：

00:00 你的程序：开始执行Lua脚本
 INCR key → count=1
 EXPIRE key 60秒
00:01 Lua脚本执行完，其他程序才能执行

注意：原子执行 ≠ 回滚，原子执行 = 不插队

如果 INCR 成功了，EXPIRE 失败了，INCR 的结果不会撤销。

为什么需要原子执行？

如果分开写：

count = redis.INCR(key) // count=1
// 这里程序崩了，EXPIRE没执行
redis.EXPIRE(key, 60秒) // 没执行到

结果：key 永远不过期，计数永远不会归零，限流永久生效。

Lua 脚本保证 INCR 和 EXPIRE 一起执行，不会出现"只执行了一半"的情况。

EXPIRE 和 PEXPIRE

EXPIRE：单位是秒
PEXPIRE：单位是毫秒

限流的 key 设计

func buildKey(keyPrefix, subject string) string {
 return fmt.Sprintf("feedsystem:ratelimit:%s:%s", keyPrefix, strings.TrimSpace(subject))
}

两种维度：

KeyByIP：按 IP 限流，防止单 IP 攻击
KeyByAccount：按用户 ID 限流，防止单用户刷接口

7. ZSET 热榜（popularity_cache.go）

ZSET 是什么？

Redis 的有序集合，每个元素有一个分数，自动按分数排序。

ZSET "热榜"
┌─────────┬─────────┐
│ 元素 │ 分数 │
├─────────┼─────────┤
│ video_5 │ 1000 │ ← 最热
│ video_2 │ 800 │
│ video_8 │ 500 │
│ video_1 │ 100 │ ← 最冷
└─────────┴─────────┘

热榜更新代码

func UpdatePopularityCache(ctx context.Context, cache *rediscache.Client, id uint, change int64) {
 // 删掉旧缓存
 _ = cache.Del(context.Background(), cache.Key("video:detail:id=%d", id))
 _ = cache.Del(context.Background(), cache.Key("video:entity:%d", id))

 // 写入热榜
 now := time.Now().UTC().Truncate(time.Minute) // 当前时间，精确到分钟
 windowKey := cache.Key("hot:video:1m:%s", now.Format("200601021504")) // 热榜key
 member := strconv.FormatUint(uint64(id), 10) // 视频ID

 _ = cache.ZincrBy(opCtx, windowKey, member, float64(change)) // 热度+change
 _ = cache.Expire(opCtx, windowKey, 2*time.Hour) // 2小时后过期
}

滑动窗口设计

热榜 key 是 hot:video:1m:202607281430，意思是"2026 年 7 月 28 日 14:30 这一分钟的热榜"。

00:00 video_5被点赞 → hot:video:1m:202607281430 → video_5分数+1
00:30 video_5又被点赞 → hot:video:1m:202607281430 → video_5分数+1
01:00 新的一分钟 → hot:video:1m:202607281431

每分钟一个 ZSET，2 小时后自动过期。

为什么要按分钟分窗口？

如果用一个大的 ZSET（不分窗口）：

所有点赞都写到同一个key "hot:video"

1月1日：video_5被点赞1000次，分数=1000，排第一
1月2日：video_8被点赞500次，分数=500
1月3日：video_5被点赞0次，但分数还是1000，还是排第一

问题：旧视频的热度永远不衰减，新视频永远追不上。

按分钟分窗口：

每分钟一个ZSET：

hot:video:1m:202607281430 → 14:30这一分钟的热度
hot:video:1m:202607281431 → 14:31这一分钟的热度
hot:video:1m:202607281432 → 14:32这一分钟的热度

查热榜时，把最近几个窗口合并：

14:35查热榜：
→ 合并 14:30、14:31、14:32、14:33、14:34、14:35 这6个窗口
→ 算总分，排序

好处：

14:30 的热度，到 14:35 时已经衰减了（只有 1/6 权重）
14:35 新产生的热度立刻反映
热榜是"最近几分钟"的热度，不是"历史累计"

ZSET 常用操作

// 分数增加
cache.ZincrBy(ctx, key, member, score)

// 按分数倒序取 top N
cache.ZRevRange(ctx, key, 0, 99) // 取前100名

// 合并多个ZSET
cache.ZUnionStore(ctx, dst, keys, "SUM")

// 设置过期时间
cache.Expire(ctx, key, 2*time.Hour)

面试要点总结

Q: 缓存和 DB 的一致性怎么保证？

A: 先更新 DB，再删缓存。删缓存失败靠 TTL 兜底，最终一致性。

Q: 缓存穿透/击穿/雪崩的区别和解法？

A: 穿透是查不存在的数据（缓存空值/布隆过滤器），击穿是热点 key 过期（分布式锁 + 等待重试），雪崩是大量 key 同时过期（随机 TTL）。

Q: 限流怎么实现的？

A: Redis 计数器，Lua 脚本原子执行 INCR + PEXPIRE，超限返回 429。

Q: 为什么用 Lua 脚本？

A: 保证 INCR 和 EXPIRE 原子执行，不会被其他命令插队，避免"只执行了一半"的问题。

Q: 热榜怎么实现的？

A: ZSET 按分钟分窗口，点赞时 ZincrBy 加分数，查热榜时合并最近几个窗口算总分。分窗口实现热度自动衰减。

Go 项目反推：Feed 流系统实战——数据库与 GORM

Mon, 27 Jul 2026 00:00:00 +0800

承接 Go 项目反推：Feed 流系统实战——认证体系，这一篇继续反推 feedsystem_video_go 的数据库代码，理解表结构、索引设计和 GORM 的常见用法。

理解所有表结构、索引设计、GORM 用法。

1. entity.go 的两种结构体

entity.go 里有两种东西：

1. 存数据库的（有 gorm 标签） → Social struct、Like struct...
2. 不存数据库的（没有 gorm 标签）→ FeedVideoItem、Request、Response...

gorm:"xxx" 标签 = 给 GORM 看的指令（怎么存数据库）
json:"xxx" 标签 = 给 JSON 看的指令（怎么显示给客户端）
两者互不影响，各管各的

2. gorm 标签汇总

标签	含义	示例
`gorm:"primaryKey"`	主键（唯一标识，类似身份证号）	`ID uint gorm:"primaryKey"`
`gorm:"unique"`	唯一（不能重复）	`Username string gorm:"unique"`
`gorm:"index"`	普通索引（加快查询，可以重复）	`VideoID uint gorm:"index"`
`gorm:"uniqueIndex:idx_name"`	唯一索引（不能重复）	`VideoID uint gorm:"uniqueIndex:idx_like_video_account"`
`gorm:"uniqueIndex:idx_name;not null"`	联合唯一索引（多个字段组合唯一）	见 Like 表
`gorm:"index:idx_name,priority:1,sort:desc"`	索引排序优先级	见 Video 表
`gorm:"not null"`	不能为空	`Title string gorm:"not null"`
`gorm:"default:false"`	默认值	`IsRead bool gorm:"default:false"`
`gorm:"autoCreateTime"`	自动填创建时间	`CreateTime time.Time gorm:"autoCreateTime"`
`gorm:"type:varchar(255)"`	字符串长度限制	`Title string gorm:"type:varchar(255)"`
`gorm:"type:text"`	长文本（无固定限制）	`Content string gorm:"type:text"`
`gorm:"column:likes_count"`	指定数据库列名	Go 驼峰 → DB 下划线
`gorm:"-"`	不存数据库	临时字段

3. json 标签

标签	含义
`json:"id"`	JSON 里显示为 “id”
`json:"-"`	JSON 里不显示（密码、Token 等敏感信息）
`json:"description,omitempty"`	空值时不显示这个字段

4. 表结构一览

Account 表（用户表）

ID → 主键
Username → 唯一（不能重复注册）
Password → 不显示在 JSON 里
Token → 不显示在 JSON 里
RefreshToken → 不显示在 JSON 里
AvatarURL → 头像地址
Bio → 个人简介

Video 表（视频表）

ID → 主键
AuthorID → 外键（关联 Account 表，存的是用户ID）
Username → 作者名（冗余存储，方便查询）
Title → 标题
Description → 描述
PlayURL → 播放地址
CoverURL → 封面地址
CreateTime → 自动填创建时间
LikesCount → 点赞数（统计字段）
Popularity → 热度值（统计字段）

Video 表的三个索引：

索引名	排序规则	用途
idx_videos_create_time	CreateTime DESC	最新视频
idx_videos_likes_count_id	LikesCount DESC	最热视频（按点赞）
idx_videos_popularity_time_id	Popularity DESC, CreateTime DESC	综合热度

priority = 优先级，数字越小越优先。

Like 表（点赞表）

ID → 主键
VideoID → 外键 + 联合唯一索引
AccountID → 外键 + 联合唯一索引

联合唯一索引：VideoID + AccountID 的组合不能重复

张三给视频 A 点赞 ✓
张三再给视频 A 点赞 ✗（违反唯一索引）
李四给视频 A 点赞 ✓（不同人）
张三给视频 B 点赞 ✓（不同视频）

为什么需要 Like 表 + Video 表的 LikesCount？

Like 表 → 记录"关系"（谁点了谁）
LikesCount → 记录"总数"（点赞数）
两者配合：Like 管关系，LikesCount 管统计

Comment 表（评论表）

ID → 主键
Username → 普通索引
VideoID → 外键 + 普通索引
AuthorID → 外键 + 普通索引
Content → 长文本（type:text）
CreatedAt → 自动填创建时间

index vs uniqueIndex：

index = 普通索引（可以重复，一个视频可以有很多评论）
uniqueIndex = 唯一索引（不能重复）

ID → 主键
FollowerID → 外键 + 联合唯一索引（谁在关注）
VloggerID → 外键 + 联合唯一索引（关注谁）

联合唯一索引：一个人不能关注同一个人两次。

Tag 表 + VideoTag 表（标签表）

Tag 表：
 ID → 主键
 Name → 唯一索引（标签名不能重复）

VideoTag 表（中间表）：
 ID → 主键
 VideoID → 外键 + 普通索引
 TagID → 外键 + 普通索引

多对多关系：一个视频可以有多个标签，一个标签可以属于多个视频，需要中间表 VideoTag 来记录关系。

Message 表（私信表）

ID → 主键
FromID → 外键 + 普通索引（谁发的）
ToID → 外键 + 普通索引（发给谁）
Content → 长文本
IsRead → 是否已读（默认 false）
CreatedAt → 自动填创建时间

ChunkUploadSession（分片上传）

不是 MySQL 表，存 Redis 的。

UploadID → 上传会话ID
AccountID → 谁在上传
UploadedBits → []bool 位图，记录每片上传状态

FeedVideoItem（Feed 流响应格式）

不是数据库表，是 API 响应格式。

Author → FeedAuthor（包含 ID + Username，不是外键）
IsLiked → 动态计算（查 Like 表），不存在数据库里

5. db.go（数据库初始化）

三个函数：

NewDB() → 连接数据库（DSN 格式：用户名:密码@tcp(地址:端口)/数据库名）
AutoMigrate() → 根据 struct 自动建表/更新表
CloseDB() → 关闭数据库连接

AutoMigrate 的好处：

手动建表：写 SQL，容易忘、容易错
AutoMigrate：改 struct，重启程序，自动更新表

6. repo.go（数据库操作）

每个模块都有自己的 repo.go，包含增删改查操作。

基础套路

// 创建
ar.db.WithContext(ctx).Create(&data)

// 查询（根据ID）
ar.db.WithContext(ctx).First(&result, id)

// 查询（根据条件）
ar.db.WithContext(ctx).Where("username = ?", name).First(&result)

// 更新（单字段）
ar.db.WithContext(ctx).Model(&Account{}).Where("id = ?", id).Update("username", newName)

// 更新（多字段）
ar.db.WithContext(ctx).Model(&Account{}).Where("id = ?", id).Updates(map[string]interface{}{"token": "", "refresh_token": ""})

// 删除
ar.db.WithContext(ctx).Delete(&Like{}).Where("video_id = ? AND account_id = ?", vID, aID)

db.WithContext(ctx) 的作用

把 context 传进去，支持超时取消。

事务（db.Transaction）

ar.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
 // 操作1
 tx.Model(&Account{}).Where("id = ?", id).Update("username", newName)
 // 操作2
 tx.Model(&Account{}).Where("id = ?", id).Update("token", token)
 return nil
})

事务 = 要么全做，要么全不做。

类比：银行转账，A 扣钱与 B 加钱必须同时成功或同时失败。

原子操作（gorm.Expr）

// 错误做法：先读再写，并发会出错
likes_count = 100
用户A读到100，用户B读到100
用户A写入101，用户B写入101
结果：只加了1 ❌

// 正确做法：让数据库直接加
gorm.Expr("likes_count + ?", 1)
数据库排队执行：100+1=101, 101+1=102
结果：正确加了2 ✓

GREATEST(likes_count + ?, 0)：防止点赞数变成负数。

LikeIgnoreDuplicate（忽略重复点赞）

err = r.db.WithContext(ctx).Create(like).Error
if err == nil {
 return true, nil // 创建成功
}
// 如果是"重复主键"错误（1062），忽略
var mysqlErr *mysql.MySQLError
if errors.As(err, &mysqlErr) && mysqlErr.Number == 1062 {
 return false, nil // 已经点过赞了，不报错
}

为什么需要这个？

联合唯一索引：保证数据正确（一人只能点一次）
LikeIgnoreDuplicate：保证用户体验（重复点赞不报错）
两个配合：数据对 + 体验好

gorm.ErrRecordNotFound（判断记录不存在）

if err == gorm.ErrRecordNotFound {
 return false, nil // 记录不存在
}

关联查询（Joins）

// 查"张三点赞过的所有视频"
r.db.WithContext(ctx).
 Model(&Video{}).
 Joins("JOIN likes ON likes.video_id = videos.id").
 Where("likes.account_id = ?", accountID).
 Find(&videos)

分步查询（GetAllFollowers）

-- 第1步：从 Social 表查出 follower_id 列表
SELECT follower_id FROM socials WHERE vlogger_id = 1;
-- 得到 [2, 5, 8]

-- 第2步：用 ID 列表去 Account 表查用户信息
SELECT * FROM accounts WHERE id IN (2, 5, 8);

为什么分两步？

Social 表只存 ID（避免数据冗余），Account 表存用户信息。用户改名只改 Account 表，Social 表不用动。

7. 数据库规范化

同一份数据只存一个地方，其他地方只存 ID（外键）。

反范例：Social 表存用户名
 用户改名 → 要更新 Account 表 + Social 表 + 其他表...
 牵一发动全身

正范例：Social 表只存 ID
 用户改名 → 只改 Account 表
 需要名字时，拿着 ID 去 Account 表查

8. 面试要点

1. Video 表为什么有三个索引？

因为有三种查询需求：

idx_videos_create_time → 按时间排序（查最新视频）
idx_videos_likes_count_id → 按点赞数排序（查最热视频）
idx_videos_popularity_time_id → 按热度 + 时间排序（综合排名）

每种查询方式都需要自己的“目录”（索引），没有索引就要全表扫描，很慢。

2. 点赞表为什么使用联合唯一索引？

点赞表用 uniqueIndex:idx_like_video_account，保证 VideoID + AccountID 的组合唯一。一个人只能给一个视频点一次赞，如果重复点赞会违反唯一索引报错。配合 LikeIgnoreDuplicate 函数，重复点赞时静默忽略，不向用户报错。

3. gorm.Expr 是怎么解决并发问题的？

错误做法：先读 likes_count=100，再写 100+1=101。两个用户同时读到 100，都写入 101，结果只加了 1。

正确做法：用 gorm.Expr("likes_count + ?", 1)，让数据库直接执行 likes_count = likes_count + 1，数据库保证原子更新，结果正确。GREATEST(likes_count + ?, 0) 可以防止点赞数变成负数。

4. 改名 + 更新 Token 为什么要用事务？

因为改名后 Token 里的 Username 就过期了，必须同时更新。事务保证“要么全做，要么全不做”：改名成功但更新 Token 失败时回滚，改名也不生效。

如果存用户名，用户改名时要更新 Account 表、Social 表和其他表，牵一发动全身。只存 ID 时，用户改名只改 Account 表，Social 表不用动；需要名字时拿着 ID 去 Account 表查询。

6. Tag 和 Video 为什么需要中间表？

一个视频可以有多个标签，一个标签也可以属于多个视频，这是多对多关系。一个外键字段只能存一个值，因此需要中间表 VideoTag 存储 VideoID + TagID，记录“哪个视频有哪些标签”。

梯度下降实践：从手写实现到 Scikit-Learn

Mon, 27 Jul 2026 00:00:00 +0800

1. 学习目标

这组实验主要解决以下问题：

从零实现线性回归的代价函数和梯度；
使用批量梯度下降训练模型；
判断梯度下降是否正在收敛；
选择合适的学习率；
使用 Z-score 标准化加快收敛；
通过特征工程实现多项式回归；
使用 Scikit-Learn 完成标准化、训练与预测。

2. 梯度下降的核心流程

线性回归模型：

$$f_{\mathbf{w},b}(\mathbf{x}) = \mathbf{w}\cdot\mathbf{x}+b$$

整个训练过程可以概括为：

输入训练数据 X、y
 ↓
使用当前 w、b 计算预测
 ↓
预测值减去真实值得到误差
 ↓
根据全部误差计算梯度
 ↓
沿梯度反方向更新 w、b
 ↓
重复，直到代价不再明显下降

参数更新规则：

$$w_j \leftarrow w_j-\alpha\frac{\partial J}{\partial w_j}$$$$b \leftarrow b-\alpha\frac{\partial J}{\partial b}$$

其中：

$\alpha$：学习率，决定每一步走多远；
梯度：代价函数上升最快的方向；
减去梯度：向代价下降的方向移动。

3. 实践一：从零实现一元线性回归

实验使用城市人口预测餐厅利润：

x_train：城市人口，单位为 10,000 人；
y_train：餐厅月利润，单位为 10,000 美元；
数据集共有 97 个样本。

一元线性回归模型：

$$f_{w,b}(x^{(i)})=wx^{(i)}+b$$

3.1 实现代价函数

平方误差代价函数：

$$J(w,b) = \frac{1}{2m} \sum_{i=0}^{m-1} \left( f_{w,b}(x^{(i)})-y^{(i)} \right)^2$$

代码：

def compute_cost(x, y, w, b):
 m = x.shape[0]
 total_cost = 0.0

 for i in range(m):
 prediction = w * x[i] + b
 error = prediction - y[i]
 total_cost += error ** 2

 return total_cost / (2 * m)

这里除以 $2m$：

除以 $m$：计算所有样本的平均损失；
除以 2：求导后平方项产生的 2 可以抵消，使梯度公式更简洁。

3.2 实现梯度

梯度公式：

$$\frac{\partial J}{\partial w} = \frac{1}{m} \sum_{i=0}^{m-1} \left( f_{w,b}(x^{(i)})-y^{(i)} \right)x^{(i)}$$$$\frac{\partial J}{\partial b} = \frac{1}{m} \sum_{i=0}^{m-1} \left( f_{w,b}(x^{(i)})-y^{(i)} \right)$$

代码：

def compute_gradient(x, y, w, b):
 m = x.shape[0]
 dj_dw = 0.0
 dj_db = 0.0

 for i in range(m):
 prediction = w * x[i] + b
 error = prediction - y[i]

 dj_dw += error * x[i]
 dj_db += error

 dj_dw /= m
 dj_db /= m

 return dj_dw, dj_db

dj_dw 多乘了一个 x[i]，因为 $w$ 是和输入 $x$ 相乘的参数；而 $b$ 只是直接相加，因此 dj_db 不需要乘 x[i]。

3.3 批量梯度下降

import copy
import math

def gradient_descent(
 x, y,
 w_in, b_in,
 cost_function,
 gradient_function,
 alpha,
 num_iters
):
 w = copy.deepcopy(w_in)
 b = b_in
 J_history = []

 for i in range(num_iters):
 dj_dw, dj_db = gradient_function(x, y, w, b)

 # 必须使用同一次迭代计算出的梯度同步更新
 w = w - alpha * dj_dw
 b = b - alpha * dj_db

 if i < 100_000:
 J_history.append(cost_function(x, y, w, b))

 if i % math.ceil(num_iters / 10) == 0:
 print(
 f"Iteration {i:4d}: "
 f"Cost {J_history[-1]:8.2f}"
 )

 return w, b, J_history

实验参数：

initial_w = 0.0
initial_b = 0.0
iterations = 1500
alpha = 0.01

w, b, J_history = gradient_descent(
 x_train,
 y_train,
 initial_w,
 initial_b,
 compute_cost,
 compute_gradient,
 alpha,
 iterations
)

实验结果大约为：

w = 1.1664
b = -3.6303

预测利润：

profit_35k = (3.5 * w + b) * 10_000
profit_70k = (7.0 * w + b) * 10_000

print(profit_35k) # 约 4519.77 美元
print(profit_70k) # 约 45342.45 美元

这里的"批量"表示：

每轮使用全部 $m$ 个训练样本计算平均梯度，然后更新一次参数。

4. 多变量梯度下降

假设训练数据形状为：

X：(m, n)
y：(m,)
w：(n,)
b：标量

其中：

$m$：训练样本数量；
$n$：每个样本的特征数量。

预测：

y_hat = X @ w + b

误差：

errors = y_hat - y

向量化代价：

def compute_cost(X, y, w, b):
 errors = X @ w + b - y
 return np.sum(errors ** 2) / (2 * X.shape[0])

向量化梯度：

def compute_gradient(X, y, w, b):
 m = X.shape[0]
 errors = X @ w + b - y

 dj_dw = X.T @ errors / m
 dj_db = np.sum(errors) / m

 return dj_dw, dj_db

形状变化：

X.T ：(n, m)
errors ：(m,)
X.T @ errors ：(n,)
dj_dw ：(n,)
dj_db ：标量

最终得到的 dj_dw 恰好包含 $n$ 个梯度，对应 $w$ 中的 $n$ 个参数。

5. 学习率实验

在未缩放的房价数据中，不同学习率会产生不同表现。

$\alpha=9.9\times10^{-7}$

学习率过大：

参数更新越过最低点；
代价不断增加；
模型发散。

$\alpha=9\times10^{-7}$

学习率稍小：

代价持续下降；
参数仍会在最低点两侧震荡；
最终能够收敛。

$\alpha=1\times10^{-7}$

学习率更小：

参数较平稳地靠近最低点；
基本没有明显震荡；
但收敛速度更慢。

因此：

学习率太大 → 震荡或发散
学习率太小 → 稳定但很慢
学习率合适 → 快速且稳定下降

6. 为什么需要特征缩放？

房价数据包含以下特征：

面积：几百到几千
卧室：0 到 5
楼层：1 到 3
房龄：数十年

假设：

$$f(\mathbf{x})=w_1x_1+w_2x_2+b$$

如果 $x_1$ 是房屋面积，最大接近 2000；$x_2$ 是卧室数量，最大只有 5。

对于面积 2000、5 间卧室的房屋，一组合适的参数可能是：

$$w_1=0.1,\quad w_2=50,\quad b=50$$

预测为：

$$0.1\times2000+50\times5+50=500$$

单位是千美元，即 50 万美元。

可以看到：

数值范围大的特征，参数通常较小；
数值范围小的特征，参数通常较大。

这会让代价函数的等高线变得非常狭长：

未缩放：
梯度下降在狭长峡谷两侧反复震荡

缩放后：
等高线更接近圆形
梯度下降更直接地靠近最低点

特征缩放通常不会改变模型能够达到的最优结果，主要作用是让训练更快、更稳定。

7. 三种特征缩放方法

7.1 除以最大值

$$x_j' = \frac{x_j}{\max(x_j)}$$

例如：

面积范围：300～2000
缩放后：0.15～1

卧室范围：0～5
缩放后：0～1

7.2 均值归一化

$$x_j' = \frac{x_j-\mu_j} {\max(x_j)-\min(x_j)}$$

减去均值后，数据会以 0 为中心。

7.3 Z-score 标准化

$$x_j' = \frac{x_j-\mu_j}{\sigma_j}$$

其中：

$$\mu_j = \frac{1}{m} \sum_{i=0}^{m-1}x_j^{(i)}$$$$\sigma_j = \sqrt{ \frac{1}{m} \sum_{i=0}^{m-1} \left(x_j^{(i)}-\mu_j\right)^2 }$$

处理后，每个特征通常具有：

均值接近 0；
标准差接近 1；
各特征具有相似的数值范围。

NumPy 实现：

def zscore_normalize_features(X):
 mu = np.mean(X, axis=0)
 sigma = np.std(X, axis=0)
 X_norm = (X - mu) / sigma

 return X_norm, mu, sigma

使用：

X_norm, X_mu, X_sigma = zscore_normalize_features(X_train)

实验中，未缩放数据只能使用约 1e-7 的学习率；经过 Z-score 标准化后，可以从 0.1 左右开始尝试，收敛速度明显加快。

8. 预测新数据时的关键规则

标准化训练数据后，必须保存训练集的均值和标准差。

预测面积 1200 平方英尺、3 间卧室、1 层、房龄 40 年的房屋：

x_house = np.array([1200, 3, 1, 40])

x_house_norm = (
 x_house - X_mu
) / X_sigma

price = x_house_norm @ w_norm + b_norm

不能对新样本重新计算均值和标准差。

错误：

# 不要这样做
new_mu = np.mean(x_house)
new_sigma = np.std(x_house)

正确原则：

训练集：计算并保存 mu、sigma
验证集：使用训练集的 mu、sigma
测试集：使用训练集的 mu、sigma
新数据：使用训练集的 mu、sigma

否则训练和预测使用的不是同一个坐标系。

9. 如何判断梯度下降是否收敛？

记录每次更新后的代价：

J_history.append(
 compute_cost(X, y, w, b)
)

绘制学习曲线：

plt.plot(J_history)
plt.xlabel("Iteration")
plt.ylabel("Cost J")
plt.show()

正常曲线：

J
│\
│ \
│ \____
│ ───
└──────────── 迭代次数

如果代价持续下降并逐渐变平，说明梯度下降正在收敛。

也可以使用自动收敛条件：

$$\left| J^{(t)}-J^{(t-1)} \right|<\epsilon$$

例如：

if abs(J_history[-1] - J_history[-2]) < 1e-3:
 break

但实际学习中，直接观察学习曲线通常更直观。

10. 梯度下降调试方法

10.1 代价不断增加

可能原因：

学习率太大；
参数更新误写成了加号；
梯度公式实现错误。

错误：

w = w + alpha * dj_dw

正确：

w = w - alpha * dj_dw
b = b - alpha * dj_db

10.2 使用很小的学习率进行测试

把 alpha 设置得非常小。

如果代码正确，代价函数理论上应该缓慢下降。如果很小的学习率下代价仍然增加，通常说明代码存在错误。

需要注意：

很小的学习率适合调试，但不一定适合正式训练，因为它可能导致收敛非常慢。

10.3 尝试一系列学习率

可以按大约 3 倍的间隔尝试：

选择能够让代价快速、持续下降的较大学习率。

11. 特征工程

特征工程是利用业务知识，从已有特征构造更有意义的新特征。

例如：

$x_1$：土地宽度；
$x_2$：土地深度。

可以构造土地面积：

$$x_3=x_1x_2$$

代码：

area = width * depth

模型变为：

$$f(\mathbf{x}) = w_1x_1+w_2x_2+w_3x_3+b$$

相比只使用宽度和深度，面积可能与房价具有更直接的关系。

12. 多项式回归

假设真实数据为：

$$y=1+x^2$$

如果只使用原始特征 $x$，线性回归只能拟合直线：

$$f(x)=wx+b$$

可以构造平方特征：

x = np.arange(0, 20, 1)
y = 1 + x ** 2

X = (x ** 2).reshape(-1, 1)

模型变为：

$$f(x)=w_1x^2+b$$

虽然它对原始变量 $x$ 是非线性的，但对参数 $w_1,b$ 仍然是线性的，所以仍可以使用线性回归的训练方法。

不知道应该使用几次项时，可以构造多个候选特征：

X = np.c_[
 x,
 x ** 2,
 x ** 3
]

对应模型：

$$f(x) = w_1x+w_2x^2+w_3x^3+b$$

多项式特征必须注意尺度

如果：

x：1～1000

那么：

x²：1～1,000,000
x³：1～1,000,000,000

尺度差异会非常大，因此应进行标准化：

X = np.c_[x, x ** 2, x ** 3]
X_norm, mu, sigma = zscore_normalize_features(X)

特征缩放后，可以使用更大的学习率，训练速度会明显提高。

13. 使用 Scikit-Learn

Scikit-Learn 可以直接完成标准化和梯度下降回归。

import numpy as np

from sklearn.linear_model import SGDRegressor
from sklearn.preprocessing import StandardScaler

13.1 标准化训练数据

scaler = StandardScaler()
X_norm = scaler.fit_transform(X_train)

fit_transform() 包含两步：

fit → 从训练集计算均值和标准差
transform → 使用这些统计量转换数据

13.2 创建并训练模型

sgdr = SGDRegressor(
 max_iter=1000,
 random_state=0
)

sgdr.fit(X_norm, y_train)

查看训练信息：

print(sgdr.n_iter_) # 实际迭代轮数
print(sgdr.t_) # 权重更新次数

查看参数：

w_norm = sgdr.coef_
b_norm = sgdr.intercept_

print(w_norm)
print(b_norm)

这些参数对应的是标准化后的输入数据，不能直接按原始面积、卧室数量的单位解释。

13.3 进行预测

y_pred_sgd = sgdr.predict(X_norm)

也可以手动计算：

y_pred_manual = X_norm @ w_norm + b_norm

检查两种结果：

np.allclose(
 y_pred_sgd,
 y_pred_manual
)

不要使用：

(y_pred_sgd == y_pred_manual).all()

浮点数运算可能存在很小的舍入误差，应使用 np.allclose()。

13.4 预测新房屋

x_house = np.array([
 [1200, 3, 1, 40]
])

x_house_norm = scaler.transform(x_house)
price = sgdr.predict(x_house_norm)

print(price)

对新数据只能调用：

scaler.transform()

不能再次调用：

scaler.fit_transform()

因为重新 fit 会改变标准化使用的均值和标准差。

13.5 SGD 与批量梯度下降的区别

手写实验使用的是批量梯度下降：

使用全部训练样本
→ 计算一次平均梯度
→ 更新一次参数

SGDRegressor 使用随机梯度下降：

依次使用单个样本或小批次
→ 更频繁地更新参数

两者都在尝试降低代价函数，但参数更新方式不同。

14. Notebook 中的 NameError

实验中出现：

NameError: name 'plt' is not defined
NameError: name 'load_house_data' is not defined
NameError: name 'run_gradient_descent' is not defined

这通常不是模型或公式的问题，而是依赖单元格没有运行。

Notebook 中的变量只存在于当前内核的内存里。重启内核、断线或者跳过前面的单元格，都会导致变量不存在。

正确运行顺序：

1. 运行 import 单元格
2. 运行辅助函数单元格
3. 加载训练数据
4. 标准化数据
5. 训练模型
6. 计算预测
7. 绘制图像

如果 Notebook 状态混乱，可以使用：

Restart Kernel and Run All

15. 高频易错点

w 和 b 必须同步更新 同一轮参数更新必须使用更新前计算出的同一组梯度。
更新公式使用减号 梯度指向代价上升方向，因此需要减去梯度。
特征尺度差异会拖慢收敛 面积、卧室数量、楼层、房龄应进行缩放。
预测新数据必须复用训练集统计量 不能为新样本重新计算均值和标准差。
多项式特征更需要缩放 $x,x^2,x^3$ 的数值范围可能相差多个数量级。
浮点数不要直接使用 == 比较 使用 np.isclose() 或 np.allclose()。
权重较大不一定代表特征更重要 权重大小受到特征尺度影响，也不代表因果关系。
SGDRegressor 不是批量梯度下降 它使用随机梯度下降，只是优化目标与线性回归相似。

16. 一页实践模板

import numpy as np
from sklearn.preprocessing import StandardScaler
from sklearn.linear_model import SGDRegressor

# 1. 准备数据
X_train, y_train = load_house_data()

# 2. 标准化
scaler = StandardScaler()
X_norm = scaler.fit_transform(X_train)

# 3. 训练
model = SGDRegressor(
 max_iter=1000,
 random_state=0
)
model.fit(X_norm, y_train)

# 4. 训练集预测
y_pred = model.predict(X_norm)

# 5. 新数据预测
x_new = np.array([
 [1200, 3, 1, 40]
])
x_new_norm = scaler.transform(x_new)
prediction = model.predict(x_new_norm)

# 6. 检查手动计算
manual_prediction = (
 X_norm @ model.coef_
 + model.intercept_
)

print(np.allclose(
 y_pred,
 manual_prediction
))

整组实验最重要的主线是：

准备训练数据
→ 检查特征尺度
→ 使用训练集统计量标准化
→ 选择学习率
→ 运行梯度下降
→ 观察代价是否持续下降
→ 保存参数和标准化器
→ 用相同的转换处理新数据
→ 进行预测

一句话总结：

梯度下降负责寻找参数，特征缩放负责让寻找过程更快、更稳定，学习曲线负责判断训练是否正常，特征工程负责让线性模型表达更复杂的关系。

大一回顾：求不得，生不息

Sun, 26 Jul 2026 00:00:00 +0800

平庸的生活方式是麻醉药。他只会束缚你，让你没有作为，甚至没有出息的度过大学的四年。 ——《交大生存手册》

进入山威，是运气作祟。或者老天爷看我高中经历实在不忍心，给这孩子悲惨的高中生活以问号结尾，勉强给他画个句号吧。也许存着点玩笑意味，让我经历三四次大起大落，在这简略的提起吧。

我始终不觉得我比别人付出的努力少。高中三年，无论是笔记、网课、作业、学校的高压练习、人际关系的拷打、身体的不适，一切的一切，都是我确切比周遭同学多经历的。可能是因为迟迟没有成长吧，所以相对应还是很幼稚的，可以说我没有开智哈哈哈。到最后三次模考，约莫也是 800～900 名的水平，可以说是波动很小的。到了高考，却很不一样。对卷子的影响出了考场就已模糊，但是成绩倒是惨惨淡淡的——559 分，3435 名。我不会忘记这哑然失笑的成绩与名次。接受吧，又能如何呢。

着手报志愿，四个冲的，几个稳定。原本打算去央民 CS 保底来着，或许很大的概率能去 UIBE 学什么精算，或者海关。直到投档线出来的夜晚，发现自己落榜外经贸，便以为去央民吧。谁料细细对照，山威爆冷了。这无疑是令我开心的，被好一点的 985 捞了。但是，好似我从来没有了解过山威的专业。没事没事，志愿填报老师和我说过，电子信息不用说，海洋科学是做研究的，经济学嘛大差不差吧。当时填报志愿三者皆可，于是电子信息—海洋科学—经济学，如此排位。

时间回到那个夜晚。和父母分享喜悦之后，去看看专业吧。这一看便让我的心跌入谷底——本来算是意外之喜，电子信息肯定够不上了，所以大概率 99% 是海洋科学。看我搜索一波吧：映入眼帘的是天坑专业、生化环材的集大成者、毕业底薪、累……一系列词条。至此一夜未眠，遂开始搜罗转专业的事项，这一来就是三四天。

待到可以查询录取结果的那天，进入官网，点击查询，映入眼帘的竟然是——电子信息。是的，垂怜之下，我大概是以前五狗运的捡漏进入电子信息大类。人生大起大落，在短短三四天水落石出。

进入山大之后，开启迷茫的大一生活。大一上是充满新奇的，从一个人跨越全中国来到威海，置办生活必需品，与来自其他地方的舍友相处，陌生的城市，陌生却莫名向往的海。

军训可以暂且略过了，强度不大，也没有起到任何出乎意料的作用。

真正的大一生活从军训结束开始。面对五花八门的基础课程、独特的课程时间和空闲时间的绝对自主化，我感觉到还不错。除了这些课程有点小难，好像我并不是能完全 handle，即使坐在第一排也如此。

可能是认真听着听着，耍会手机，到课程过半甚至学不进去直接玩手机了。这也太惨了，课后还需要听网课来补知识，这一点也不好。课余时间分给了手机、一点点游戏，还有图书馆。谁还没有怀揣个保研梦呢？老实说，也是为了保研努力过一次吧，认真做题、复习、鏖战图书馆。但是最后大一上的收效却是很差的。

何尝不是好事呢？放弃了这条大多数人想争一争但是其实很坑的路。不过绩点倒是足够分流到计算机了，这是好事啊。现在看来计算机是我最适合的专业了，按照兴趣的话确实是这样。让我去学机器人、研究高深的自控？天呐，没那么有毅力。或者选择电子科学，对着最厌恶的电路？

作为一个对大学好奇的人，我也在充分地尝试各种活动——演讲比赛、短剧大赛、配音大赛。吗的，尝试了一圈发现全他妈都是野鸡比赛。这里不是内陆的顶尖高校，有着充分的人文气息，这里的比赛没有太多意义，负责这些的领导也是野鸡，纯粹是浪费时间之作。

大一上，跟着毛夏叶学姐打打相对应的比赛吧。依托一个老师、传承的项目比比皆是，但是毛夏叶学姐的好心也是能感受到的。其实没有什么成长，我干的活无非是修改一些文件、修改一些 PPT，但是这和我的专业有毛线关系？如果是为了综测，好的，这坨屎我吃。但是当我大一上考完期末之后便完全摒弃了这个想法，选择退出。

大一上还有什么重要节点呢？FPG 的考核吧。肖家骏学长负责我的考核，下面 po 出来当时的考核内容，仅供回忆：

Linux 和 Shell 入门

难度： ★★★☆☆☆☆

受试人： 石静远 负责人： 肖家骏

最好的计算机路线图，CSDIY

上海交通大学生存手册

Linux 开发环境的搭建

了解命令行（CLI）的含义，以及其和图形化界面（GUI）有什么区别

了解 Shell 基本指令和 Shell 的历史

了解 Linux 发展的历史，以及各个发行版之间的区别

为自己的电脑安装任意一个 Linux 发行版（零基础建议 Ubuntu 24.04 LTS），使用 WSL2/双系统而非虚拟机

自行选择使用 WSL2 还是双系统方式安装

学习 Git 的基本操作和 GitHub 的基本使用：用于学习 Git 的趣味交互网站

配置基本的开发工具链（编辑器/IDE）

了解如何在命令行环境编译并运行 C 语言代码

在完成任务时

确保在纯英文环境中进行操作，增进对英文文档的理解

每次操作前思考其目的，尝试理解每个步骤背后的原理

熟悉你接触的每一个工具或项目的官方文档，遇到问题请尝试查阅官方文档

成功在命令行编译并运行 C 语言后，前往实验室进行最终考核

前置知识

知识技能描述

Linux 免费开源的操作系统，就像 Windows 和 macOS，但你可以完全控制并自由定制它

Shell 命令行界面，让用户以文本指令与操作系统交互

C/C++ 编译器将高级语言代码转换为机器码或字节码的程序

Vim 强大的文本编辑器，通过键盘命令快速编辑文件，初学曲线陡峭，熟练后效率极高

检查形式： 现场检查，使用现场提供的电脑，操作终端完成要求的命令。

截止日期： 请在 12 月 6 日前联系团队以完成检查。

现在看来，大致的内容都很基本，但在当时看来却是全新的。这些新奇的家伙让我感受很好，有了慢慢进步的感觉。我每天去准备些相关的考核内容，其实主要还是问问豆包，继而看看上面推荐的网页。对于 CS DIY 我觉得里面的课程要求较高、过于生涩；对于交大笔记倒是令我大跌眼镜，当时看来大逆不道的话，现在看来却是如此。总而言之给我的震撼很大，也算是开启了新的大门。准备的大差不差，考核通过，之后便无消息，除了被拉进群以外。

这大致是我大一上——探索居多，什么都参加了一点，广度优先。但说起深度，好像并不是很有成效。这也是最迷茫的一学期。

待到大一下学期开始，相对明确的我开始逐渐探索新的知识内容，对于课内知识一笑了之，自然是能不去则不去。这也造就了虚浮的基础。我不是那种随便突击几天便可以有很大成效、能够拿下 4.0 绩点的人，相反，我的绩点来之不易，即使慢慢学，也未必有高分。

在下学期，真正的转折节点是二月的 FPG 团建。那天的经历并不重要，但是自从那天，我成为了实验室的常客。人总在交汇中成长，和肖家骏学长、宋博文学长以及各个学长交流，总是拓宽了很多眼界。看似没有一个实际的成果，但是基础薄弱，无可奈何，总归是在见识和其他潜藏的方面慢慢进步了。

也是在这一学期，我看了 Missing Semester、CS61A，倒腾了 Linux Ubuntu 的输入法，有了自己的博客，慢慢是 GitHub 的常客，开始有意识去看重实习，加入了一位老师的科研。我认为这对我的综合成长是巨大的——醒悟的有点晚，再加上学校从期中考试延伸到期末考试，时间跨度长，感觉没法专心学习自己的内容。对于其他旁枝的知识了解的更是越来越多，我可以大言不惭地称之为“进化前期”吧。所谓进化，指的是在一段时间中，一个人的见解或者工程能力得到了巨大的提升。

只能寄托进化于暑假吧。这个暑假，我打算：

认真刷 LeetCode
反复夯实一个 Go 写的 Feed 流系统
至于八股，开学再背也不迟

希望寒假能找到具体的实习，这是我短期的小目标。

对了，下学期我要认真听课，争取高点的绩点。

此外对于扩展，我还是希望能再做下 Missing Semester 2026 的作业内容，感觉对于一些知识的运用还是没有那么常规化，譬如 Git 之类。此外看看 Coursera 上的 ML 入门，认真参与一个未名超算队 × LCPU AI Infra Seminars 的暑期夏令营。

再细读两本书：《亿级流量系统架构设计与实战》——这是本好书，深入浅出；《打开量化投资的黑箱》。越来越能感受到，当 AI 时代来临，我们本以为知识可以通过反复向 AI 求索得到而忽略书本的重要性，但实际上书本的体系化是无与伦比的高知识浓度体系压缩。

再有就是希望认真锻炼、保持健康，这才是一切的本钱。

在此感叹下，高考的分界重要，着实是无与伦比。北大相对应俱乐部成员才大一，但是这一年的知识增速与累积，已经大于了很多中 9 大三学生的知识量。他们的机会多，成长也快。人终将走向异化，每个人的路都由着自己决定。希望尽量向上，能够不负时间、不负自己。这也许是一个简短的期许吧。

好似也没什么了。大一一年带给我的成长，远远比过去十八年任何一年带来的多。我是幸运的，歪打正着进入想学的专业，有着很多前辈毫无保留的教导，有着父母的不懈支持。我还有什么倦怠而不去做的呢？

从求而不得，到生生不息。 这是我对大一的注脚。

多元线性回归与 NumPy 向量化

Sun, 26 Jul 2026 00:00:00 +0800

1. 多元线性回归

1.1 从单特征到多特征

单变量线性回归只使用一个特征：

$$ f_{w,b}(x)=wx+b $$

多元线性回归同时使用多个特征。例如预测房价时，可以使用：

$x_0$：房屋面积
$x_1$：卧室数量
$x_2$：楼层数
$x_3$：房屋年龄

若共有 $n$ 个特征，则一个样本写成：

$$ \mathbf{x}^{(i)} = \left[x_0^{(i)},x_1^{(i)},\ldots,x_{n-1}^{(i)}\right] $$

其中：

$i$ 表示第几个训练样本；
$j$ 表示第几个特征；
$x_j^{(i)}$ 表示第 $i$ 个样本的第 $j$ 个特征。

数学教材常从 1 开始编号；Python 和本实验从 0 开始编号。

1.2 模型

多元线性回归模型为：

$$ f_{\mathbf{w},b}(\mathbf{x}) =w_0x_0+w_1x_1+\cdots+w_{n-1}x_{n-1}+b $$

使用向量点积可以简写为：

$$ \boxed{f_{\mathbf{w},b}(\mathbf{x})=\mathbf{w}\cdot\mathbf{x}+b} $$

其中：

$\mathbf{w}=[w_0,w_1,\ldots,w_{n-1}]$ 是长度为 $n$ 的参数向量；
$b$ 是标量偏置；
$\mathbf{w}\cdot\mathbf{x}=\sum_{j=0}^{n-1}w_jx_j$。

例如：

$$ f(\mathbf{x})=0.1x_0+4x_1+10x_2-2x_3+80 $$

如果房价单位为千美元，可解释为：面积每增加 1 平方英尺，预测价格增加 0.1 千美元；房龄每增加 1 年，预测价格减少 2 千美元。参数表达的是“其他特征保持不变时”的线性影响。

“多元线性回归”指多个输入特征。它不同于统计学中具有多个输出变量的“多变量回归”。

2. 训练数据的矩阵表示

若有 $m$ 个训练样本，每个样本有 $n$ 个特征，则输入数据组成矩阵：

$$ \mathbf{X}\in\mathbb{R}^{m\times n} $$

每一行是一个训练样本；
每一列是一种特征；
X[i, j] 是第 i 个样本的第 j 个特征；
X[i] 或 X[i, :] 是第 i 个样本的特征向量。

实验数据：

import numpy as np

X_train = np.array([
 [2104, 5, 1, 45],
 [1416, 3, 2, 40],
 [ 852, 2, 1, 35]
])
y_train = np.array([460, 232, 178])

其形状为：

X_train.shape # (3, 4)：3 个样本、4 个特征
y_train.shape # (3,)：3 个目标值

参数示例：

w_init = np.array([
 0.39133535,
 18.75376741,
 -53.36032453,
 -26.42131618
])
b_init = 785.1811367994083

w_init.shape # (4,)

3. 用 NumPy 实现预测

3.1 循环版本

def predict_single_loop(x, w, b):
 p = 0.0
 for j in range(x.shape[0]):
 p += x[j] * w[j]
 return p + b

3.2 向量化版本

def predict(x, w, b):
 return np.dot(x, w) + b

使用方式：

x_vec = X_train[0]
prediction = predict(x_vec, w_init, b_init)

x_vec 和 w_init 的形状都是 (4,)，np.dot(x_vec, w_init) 返回一个标量。

向量化版本的优势：

代码更短、更容易阅读；
底层使用经过优化的数值计算程序；
可利用 CPU 的并行指令及专门的线性代数库；
对大规模数据通常远快于 Python 层的显式循环。

向量化并不意味着“所有运算一定在一个时钟周期完成”，而是将循环交给优化后的底层实现，从而减少 Python 解释器开销并更充分地利用硬件。

4. 代价函数

单个样本的误差为：

$$ e^{(i)} =f_{\mathbf{w},b}(\mathbf{x}^{(i)})-y^{(i)} $$

平方误差代价函数：

$$ \boxed{ J(\mathbf{w},b) =\frac{1}{2m} \sum_{i=0}^{m-1} \left( f_{\mathbf{w},b}(\mathbf{x}^{(i)})-y^{(i)} \right)^2 } $$

Python 实现：

def compute_cost(X, y, w, b):
 m = X.shape[0]
 cost = 0.0

 for i in range(m):
 prediction = np.dot(X[i], w) + b
 cost += (prediction - y[i]) ** 2

 return cost / (2 * m)

进一步向量化：

def compute_cost_vectorized(X, y, w, b):
 errors = X @ w + b - y
 return np.sum(errors ** 2) / (2 * X.shape[0])

其中 @ 在这里执行矩阵与向量的乘法：

X : (m, n)
w : (n,)
X @ w : (m,)
y : (m,)

5. 多元线性回归的梯度

对每个参数 $w_j$：

$$ \boxed{ \frac{\partial J}{\partial w_j} =\frac{1}{m} \sum_{i=0}^{m-1} \left( f_{\mathbf{w},b}(\mathbf{x}^{(i)})-y^{(i)} \right)x_j^{(i)} } $$

对偏置 $b$：

$$ \boxed{ \frac{\partial J}{\partial b} =\frac{1}{m} \sum_{i=0}^{m-1} \left( f_{\mathbf{w},b}(\mathbf{x}^{(i)})-y^{(i)} \right) } $$

循环实现：

def compute_gradient(X, y, w, b):
 m, n = X.shape
 dj_dw = np.zeros(n)
 dj_db = 0.0

 for i in range(m):
 error = np.dot(X[i], w) + b - y[i]
 for j in range(n):
 dj_dw[j] += error * X[i, j]
 dj_db += error

 return dj_db / m, dj_dw / m

完全向量化实现：

def compute_gradient_vectorized(X, y, w, b):
 m = X.shape[0]
 errors = X @ w + b - y
 dj_dw = X.T @ errors / m
 dj_db = np.sum(errors) / m
 return dj_db, dj_dw

形状检查：

errors : (m,)
X.T : (n, m)
X.T @ errors : (n,)
dj_dw : (n,)
dj_db : scalar

6. 批量梯度下降

更新规则：

$$ w_j \leftarrow w_j-\alpha\frac{\partial J}{\partial w_j} $$$$ b \leftarrow b-\alpha\frac{\partial J}{\partial b} $$

向量形式：

$$ \boxed{ \mathbf{w} \leftarrow \mathbf{w}-\alpha\nabla_{\mathbf{w}}J } $$

实现：

import copy
import math

def gradient_descent(
 X, y, w_in, b_in,
 cost_function, gradient_function,
 alpha, num_iters
):
 w = copy.deepcopy(w_in)
 b = b_in
 J_history = []

 for i in range(num_iters):
 dj_db, dj_dw = gradient_function(X, y, w, b)

 # 使用同一次迭代计算出的梯度，同时更新所有参数
 w = w - alpha * dj_dw
 b = b - alpha * dj_db

 if i < 100_000:
 J_history.append(cost_function(X, y, w, b))

 if i % math.ceil(num_iters / 10) == 0:
 print(f"Iteration {i:4d}: Cost {J_history[-1]:8.2f}")

 return w, b, J_history

实验设置：

initial_w = np.zeros_like(w_init)
initial_b = 0.0
iterations = 1000
alpha = 5.0e-7

w_final, b_final, J_hist = gradient_descent(
 X_train,
 y_train,
 initial_w,
 initial_b,
 compute_cost,
 compute_gradient,
 alpha,
 iterations
)

该实验的学习率很小，而且不同特征的数值范围差异大，因此 1000 次迭代后的预测仍不够准确。后续通常会通过特征缩放改善收敛速度。

7. NumPy 向量基础

7.1 一维数组

本课程用一维 NumPy 数组表示向量：

a = np.array([1, 2, 3, 4])
a.shape # (4,)

常用创建方式：

np.zeros(4) # 4 个 0
np.random.random_sample(4) # 4 个 [0, 1) 随机数
np.arange(4.0) # [0., 1., 2., 3.]
np.random.rand(4) # 4 个 [0, 1) 随机数

(4,) 表示含 4 个元素的一维数组，不是二维行矩阵 (1, 4)，也不是二维列矩阵 (4, 1)。

7.2 索引

a = np.arange(10)

a[2] # 第 3 个元素
a[-1] # 最后一个元素

访问一维数组的单个元素通常得到 NumPy 标量。

7.3 切片

格式：

a[start:stop:step]

stop 不包含在结果中。

a[2:7:1] # 索引 2、3、4、5、6
a[2:7:2] # 索引 2、4、6
a[3:] # 从索引 3 到末尾
a[:3] # 索引 0、1、2
a[:] # 全部元素，得到一个视图

7.4 常用向量运算

a = np.array([1, 2, 3, 4])

-a # 逐元素取负
np.sum(a) # 元素求和，返回标量
np.mean(a) # 均值，返回标量
a ** 2 # 逐元素平方
5 * a # 每个元素乘以 5

7.5 逐元素运算与点积

a = np.array([ 1, 2, 3, 4])
b = np.array([-1, 4, 3, 2])

a * b # 逐元素乘法，结果仍是向量
np.dot(a, b) # 点积：逐元素相乘后求和，结果是标量
a @ b # 对两个一维向量，同样是点积

手动实现点积：

def my_dot(a, b):
 result = 0.0
 for i in range(a.shape[0]):
 result += a[i] * b[i]
 return result

两个向量做逐元素运算或点积时，形状必须兼容。

7.6 向量性能示例

import time

size = 10_000_000
a = np.random.rand(size)
b = np.random.rand(size)

start = time.time()
vectorized_result = np.dot(a, b)
vectorized_time = time.time() - start

start = time.time()
loop_result = my_dot(a, b)
loop_time = time.time() - start

两种方法应给出近似相同的结果。浮点数运算顺序不同，可能造成极小的舍入误差，因此比较时宜使用：

np.isclose(vectorized_result, loop_result)

8. NumPy 矩阵基础

8.1 创建矩阵

二维数组使用形状元组：

np.zeros((1, 5)) # shape: (1, 5)
np.zeros((2, 1)) # shape: (2, 1)
np.random.random_sample((3, 4))

手动创建：

a = np.array([
 [5],
 [4],
 [3]
])

a.shape # (3, 1)

8.2 reshape

a = np.arange(6).reshape(3, 2)

结果：

[[0, 1],
 [2, 3],
 [4, 5]]

也可以写：

a = np.arange(6).reshape(-1, 2)

-1 表示让 NumPy 根据元素总数和另一个维度自动推断该维度。

8.3 矩阵索引

a[2, 0] # 第 3 行第 1 列的标量
a[2] # 第 3 行，返回 shape 为 (n,) 的一维数组
a[2, :] # 同上
a[:, 0] # 第 1 列，返回一维数组

8.4 矩阵切片

a = np.arange(20).reshape(-1, 10)

a[0, 2:7] # 第 1 行中索引 2 到 6
a[:, 2:7] # 所有行、索引 2 到 6 的列
a[:, :] # 全部行和列
a[1, :] # 第 2 行，结果是一维数组

9. 广播（Broadcasting）

广播允许 NumPy 在形状兼容时，将较小的数组“扩展”到较大的数组上执行逐元素运算。

最简单的例子是标量与向量：

a = np.array([1, 2, 3, 4])
a + 10
# [11, 12, 13, 14]

在线性模型中：

X @ w + b

X @ w 的形状是 (m,)，标量 b 会广播到每个预测值上。

判断广播是否兼容时，从形状的最后一个维度向前比较；对应维度相等，或其中一个为 1，通常即可广播。

广播很方便，但也可能隐藏形状错误。机器学习代码中应经常打印或断言 .shape。

10. 正态方程与梯度下降

线性回归还可以通过线性代数方法直接求解参数，常称为正态方程法。

特点：

无需像梯度下降那样反复迭代；
主要用于线性回归，不能自然推广到逻辑回归、神经网络等模型；
当特征数很大时，直接求解可能较慢；
实际项目中通常交给成熟的数值计算或机器学习库处理，不应手动计算矩阵逆。

本课程重点学习梯度下降，因为它能推广到更多机器学习模型。

11. 高频易错点

数学下标与 Python 下标不同

数学讲解可能从 1 开始；NumPy 从 0 开始。
(n,) 不等于 (n, 1)

前者是一维数组，后者是二维列矩阵。
a * b 不等于 np.dot(a, b)

前者逐元素相乘，后者对一维向量返回点积。
切片右端不包含

a[2:7] 包含索引 2 到 6。
更新梯度下降参数时要同步

同一轮中的 w 和 b 都应使用更新前的同一组梯度。
特征尺度会影响梯度下降速度

面积可能是上千，楼层数可能只有 1～3；尺度差异大会使代价函数狭长，导致收敛缓慢。
学习率过大或过小都不好

过大可能使代价震荡或发散；过小则收敛很慢。
浮点数结果不要直接用 == 比较

使用 np.isclose 或 np.allclose。
课程原文中的翻译错误

向量 [1,2,3,4] 的 shape (4,) 是一维，不是“二维向量”；向量的元素个数常称为长度或维数，而 NumPy 数组的 ndim 表示轴的数量。

12. 一页速记

# 预测
y_hat = X @ w + b

# 误差
errors = y_hat - y

# 代价
J = np.sum(errors ** 2) / (2 * m)

# 梯度
dj_dw = X.T @ errors / m
dj_db = np.sum(errors) / m

# 更新
w = w - alpha * dj_dw
b = b - alpha * dj_db

对应的核心公式：

$$ \boxed{ \hat{\mathbf{y}}=\mathbf{X}\mathbf{w}+b } $$$$ \boxed{ J(\mathbf{w},b)=\frac{1}{2m}\|\hat{\mathbf{y}}-\mathbf{y}\|_2^2 } $$$$ \boxed{ \nabla_{\mathbf{w}}J =\frac{1}{m}\mathbf{X}^{T}(\hat{\mathbf{y}}-\mathbf{y}) } $$$$ \boxed{ \frac{\partial J}{\partial b} =\frac{1}{m}\sum_{i=0}^{m-1}(\hat y^{(i)}-y^{(i)}) } $$

掌握这一条主线即可：

样本矩阵 X
→ 点积得到预测
→ 预测减目标得到误差
→ 由误差计算代价和梯度
→ 用梯度下降更新 w、b

AI Infra 讲座：从并行计算到 CUDA、Triton 与 TileLang

Sat, 25 Jul 2026 00:00:00 +0800

面向刚进入 Infra / AI Infra 领域的初学者课程时间：2026-07-25 整理依据：96 页课件 + 约 3 小时逐字稿说明：本文不是逐页复述，而是按知识依赖关系重构。逐字稿中的语音识别错误（如把 warp 写成 work、grid 写成 grade、Triton 写成 ten、TileLang 写成 tell long）均已按上下文纠正。

0. 先给出整场讲座的主线

这场讲座其实在回答一个连续的问题：

为什么 AI 需要并行计算？ 大模型中的矩阵乘法、逐元素运算、通信和流水线，都含有大量可以同时完成的工作。
为什么 GPU 适合做这些计算？ GPU 用大量计算单元和高带宽内存换取高吞吐量，并通过并发执行许多 warp 来隐藏单个任务的延迟。
程序员怎样把计算映射到 GPU？ CUDA 用 grid → block/CTA → warp → thread 描述并行任务，并要求程序员显式处理索引、内存、同步和边界。
为什么还需要 Triton / TileLang？ 手写每个线程过于繁琐。Tile-level DSL 让程序员先描述"一块数据如何搬运和计算"，再由编译器完成更细的线程映射。
这与 AI Infra 有什么关系？ 算子、编译器、分布式训练、集群通信、推理服务和强化学习系统，本质上都在解决： 怎样切分计算、放置数据、协调执行，并让昂贵硬件尽可能持续地做有效工作。

可以把全文压缩成一句话：

AI Infra 的核心不是"GPU 比 CPU 快"，而是识别并行性，并在计算、内存和通信之间设计高效的数据流。

1. 活动定位与课程地图

本次暑期活动的目标是"学习和实践 AI Infra"，除课程外还计划提供算力、练习、评测排行、交流讨论和业界连接。整体内容分为四个主题：

主题	主要内容
Kernel 与 ML Compiler	CUDA、GPU 编程、DSL、数据布局、流水线、编译器栈、性能上限分析
Interconnect 与 Communication	Scale-up / Scale-out、网络互联、P2P、集合通信、MoE/EP、通信计算重叠、存储协同
LLM Serving 与 Inference	KV Cache、vLLM/SGLang、算子与框架、并行策略、Prefill-Decode 分离、投机解码
Distributed RL Systems	RL 算法、Rollout、训推一致性、分布式 RL、Agentic RL

Session 1 是后续所有主题的"地基层"：先建立并行计算、GPU 执行模型和 Kernel 编程的共同语言。

第一部分：从计算到并行计算

2. 什么是计算

课程给出的朴素定义是：

计算是把输入值按照某种规则变换为输出值的过程。

这个定义可以拆成两件事：

数据及其搬运：输入在哪里？输出写到哪里？中间数据怎样流动？
计算规则及其执行单元：加法、乘法、比较、矩阵乘法由什么硬件完成？

这是一个很重要的 Infra 视角。应用开发常把"算法"当作核心，但性能工程会同时追问：

算了多少次？
每次计算需要读写多少字节？
数据位于寄存器、缓存、显存，还是另一张卡？
计算单元是在工作，还是在等数据？

很多程序"算得慢"并不是算术运算慢，而是数据没有及时到达计算单元。

3. 指令、时钟周期、流水线与 IPC

一个经典处理器执行指令大致经过：

取指 → 译码 → 执行 → 访存 → 写回

如果把每条指令完整做完才开始下一条，硬件的大量部件会闲置。流水线让不同指令同时处于不同阶段。例如：

指令 1 正在写回；
指令 2 正在访存；
指令 3 正在执行；
指令 4 正在译码；
指令 5 正在取指。

IPC（Instructions Per Cycle） 表示平均每周期完成多少条指令。需要注意：

IPC 不是频率；频率表示一秒有多少周期。
IPC 也不是程序性能的全部；不同指令的工作量、延迟和吞吐不同。
超标量处理器能在同一周期发射或完成多条互不依赖的指令，因此 IPC 可能大于 1。

这已经是一种并行：它发生在单个处理器内部，称为指令级并行（ILP）。

4. 延迟与吞吐量

这是全场最重要的一组区分。

延迟（Latency）

完成一个任务要等多久。

例：一个请求从进入推理服务到收到第一个 token 的时间。

吞吐量（Throughput）

单位时间完成多少任务或多少计算。

例：一个推理集群每秒处理多少 token。

GPU 的优势主要是吞吐量，而不是每个单独运算的最低延迟。它的策略是：

当一个任务在等待数据时，迅速执行另一个已就绪的任务，用大量并发工作隐藏等待。

因此，“GPU 快"必须补全为：

对具有足够并行度、规则控制流和合适访存模式的工作负载，GPU 往往能提供很高的总吞吐量。

5. 什么样的计算能够并行

5.1 数据依赖

c = a * b
d = 3 * c

d 必须等待 c，二者存在真数据依赖，不能直接同时执行。

c = a * b
d = 3 * b
e = a + b

三条计算只读相同输入、写不同输出，可以并行。

更系统地说，判断能否并行要看读写集合是否冲突。常见依赖包括：

RAW（Read After Write）：后者要读前者写出的值，是真依赖。
WAR（Write After Read）：后者写入的位置仍需被前者读取。
WAW（Write After Write）：两个任务写同一位置，最终结果依赖顺序。

5.2 竞争、互斥和锁

多个执行单元同时读写同一资源，可能产生 race condition。锁、原子操作、屏障可以恢复正确性，但会带来等待和串行化。

所以，并行化不只是"把任务分成 N 份”，还要保证：

每份任务的读写范围清楚；
共享状态受到正确保护；
同步频率不过高；
结果与执行顺序无关，或执行顺序被明确控制。

5.3 通信与同步

任务即使能拆开，也常常需要交换中间结果。例如：

多卡训练中聚合梯度；
求所有设备上的最大值或总和；
流水线后一阶段等待前一阶段输出；
MoE 中把 token 路由到不同专家。

并行收益最终要减去：

通信时间；
同步等待；
数据重新布局；
任务调度；
负载不均衡。

这解释了为什么"设备数翻倍"通常不等于"性能翻倍"。

6. 两类基本拆分方法

6.1 Domain Decomposition：按数据域拆分

把一个大数据集切成若干块，让不同计算单元处理不同区域。

常见切法：

连续分块（block）；
循环分配（cyclic）；
block-cyclic；
二维或三维网格切分。

选择切法时要考虑：

各块计算量是否均衡；
相邻数据是否频繁交互；
数据是否连续，能否高效访问；
每块能否放入更快的存储层。

矩阵乘法是典型例子。输出矩阵 C = A × B 的不同块可以独立计算，因此可以先按 M、N 维切分输出，再沿归约维 K 分块累加。

6.2 Functional Decomposition：按功能或阶段拆分

把不同类型的计算放到不同执行单元，或让不同设备负责流水线的不同阶段。

例：

CPU 负责调度和控制，GPU 负责密集计算；
流水线并行中，不同 GPU 负责模型的不同层；
推理系统中，Prefill 和 Decode 由不同资源池承担。

6.3 大模型训练中的典型映射

并行方式	拆什么	主要代价
数据并行 DP	不同设备处理不同 batch，模型副本相同	梯度 All-Reduce
张量并行 TP	把单层矩阵按行或列拆到多卡	层内频繁通信
流水线并行 PP	不同设备负责不同层	流水线气泡、激活传输
专家并行 EP	不同设备放不同 MoE 专家	All-to-All、负载不均
序列/上下文并行	按序列维切分	注意力相关通信

现实系统经常组合多种并行方式，形成多维并行拓扑。

7. Flynn 分类：从指令流与数据流看硬件

类型	含义	直觉
SISD	单指令流、单数据流	经典串行处理
SIMD	单指令流、多数据流	同一指令同时作用于多个数据元素
MISD	多指令流、单数据流	很少有严格对应的通用硬件
MIMD	多指令流、多数据流	多核 CPU、集群等通用并行系统

这个分类是抽象模型，不应把复杂现代处理器硬塞进唯一格子。GPU 在不同层级上会同时呈现不同特征：

不同 block 可以执行不同任务，整体具有 MIMD 味道；
单个 warp 通常以相同指令推进，具有 SIMD/SIMT 味道。

8. 并行编程模型：程序员怎样描述计算

课程提到的主要模型包括：

共享内存：执行单元通过同一地址空间读写数据。
线程模型：创建、同步和管理多个线程。
分布式内存 / 消息传递：不同进程拥有独立内存，通过 send/receive、broadcast、reduce 等显式通信；MPI 是代表。
PGAS：逻辑上提供全局地址空间，但数据具有物理归属。
SPMD：多个执行单元运行同一程序，但依据自身编号处理不同数据。
MPMD：不同执行单元可以运行不同程序。
混合模型：例如节点间 MPI、节点内线程、GPU 上 CUDA。

不要把 SPMD 和"数据并行训练"混为一谈：

SPMD 描述"程序是否相同"；
数据并行描述"模型和数据如何切分"。

第二部分：CUDA 编程模型

9. 为什么 GPU 适合 AI/HPC

课程用"三胜"概括 GPU：

9.1 更多晶体管用于吞吐型计算

CPU 要做好分支预测、乱序执行、低延迟缓存和复杂控制；GPU 把更多面积用于大量相对简单的计算单元。

这不是"GPU 每个核心都比 CPU 核心强"，而是：

CPU 强于低延迟、复杂控制和串行任务；
GPU 强于规则、密集、批量、可并行的任务。

9.2 用并发隐藏延迟

GPU 的单次操作或显存访问可能并不低延迟，但 SM 保存大量 warp 的执行状态。一个 warp 等待内存时，调度器可以选择另一个就绪 warp。

9.3 高显存带宽

训练和推理频繁搬运权重、激活和 KV Cache，高带宽显存非常关键。但标称带宽只有在访问足够连续、事务利用率高时才可能接近。

课堂中的具体延迟、吞吐和"HBM 比 DDR 快多少倍"是用于建立直觉的示例，不是跨所有 CPU/GPU/内存配置都成立的常数。

10. CUDA 的软件层级与硬件层级

10.1 软件视角

Kernel launch
└── Grid
 ├── Block / CTA
 │ ├── Warp（NVIDIA 当前通常为 32 threads）
 │ │ ├── Thread
 │ │ └── ...
 │ └── ...
 └── ...

thread：CUDA 编程中最细的逻辑执行实例。
warp：硬件调度与执行的一组线程。
block / CTA：线程合作、共享 shared memory 和执行块级同步的范围。
grid：一次 kernel launch 创建的所有 block。

10.2 硬件视角

GPU
└── GPC 等更高层组织
 └── 多个 SM
 ├── warp schedulers
 ├── register file
 ├── shared memory / L1
 ├── CUDA cores / ALUs
 ├── Tensor Cores
 └── SFU 等专用单元

一个 block 会被调度到某个 SM，并通常在该 SM 上运行至结束。block 数可以远多于 SM 数，剩余 block 等待调度。

10.3 自动可扩展性的来源

一般 CUDA kernel 应让不同 block 相互独立，因为：

block 的执行顺序没有保证；
设备可能有几十、几百或更多 SM；
同一程序无需根据 SM 数重写。

这是一种软件与硬件规模解耦。例外包括 cooperative launch、thread block cluster 等有额外约束的机制，但初学阶段先遵守"block 独立"最安全。

11. CUDA 程序的基本生命周期

典型流程：

CPU（host）准备输入；
分配 GPU（device）内存；
把数据从 host memory 复制到 device memory；
使用 <<<gridDim, blockDim, ...>>> 启动 kernel；
GPU 并行执行；
必要时同步；
将结果复制回 CPU；
释放资源并检查错误。

CUDA C++ 中常见执行空间修饰符：

__host__：在 CPU 上执行；
__device__：在 GPU 上执行，由 device 代码调用；
__global__：声明 kernel，通常由 host 发起并在 device 上执行，返回类型为 void。

编译链可粗略理解为：

CUDA C++ (.cu)
 ├── host code → host compiler → CPU code
 └── device code → nvcc toolchain → PTX / device binary

PTX 是虚拟指令集/中间表示，便于在不同代际 GPU 上进一步生成机器代码。
CUBIN 包含面向具体 GPU 架构的机器代码。

12. 从线程编号映射到数据

12.1 一维向量

int i = blockIdx.x * blockDim.x + threadIdx.x;
if (i < N) {
 c[i] = a[i] + b[i];
}

其中：

threadIdx.x：线程在 block 内的局部编号；
blockIdx.x：block 在 grid 内的编号；
blockDim.x：每个 block 的线程数；
边界判断处理 N 不是 block 大小整数倍的情况。

12.2 二维矩阵

int row = blockIdx.y * blockDim.y + threadIdx.y;
int col = blockIdx.x * blockDim.x + threadIdx.x;
if (row < M && col < N) {
 c[row * N + col] = a[row * N + col] + b[row * N + col];
}

二维数组在内存中仍然是一段线性地址。以行主序为例：

address(i, j) = base + i * stride_row + j * stride_col

对连续张量，通常 stride_col = 1，stride_row = 列数。理解 stride 是之后看 Triton 矩阵乘法指针计算的关键。

13. Warp、SIMT 与分支发散

13.1 SIMT

SIMT 是 Single Instruction, Multiple Threads。程序员看到独立线程，但硬件通常以 warp 为单位发射指令。

SIMT 与 SIMD 的直觉差异：

SIMD 直接表达"一条向量指令作用于多个数据 lane"；
SIMT 表达"许多逻辑线程运行同一 kernel"。

在 NVIDIA GPU 上，每个线程具有独立执行状态，但同一 warp 中的活跃线程仍以共同指令高效推进。

13.2 Warp divergence

若同一 warp 内部分线程走 if，另一部分走 else，硬件可能依次执行不同路径，并 mask 掉当前路径不参与的线程。

if (threadIdx.x % 2 == 0) {
 expensive_a();
} else {
 expensive_b();
}

这会让每个 warp 都经历两条路径。优化方向是让相同分支的数据按 warp 边界聚集，使一个 warp 尽量只执行一条路径。

但不要把"任何 if 都很慢"当成规则：

所有线程条件一致时没有发散；
很短的分支可能被编译为 predication；
边界判断通常只影响少量 warp；
真正是否成为瓶颈应由 profiler 判断。

13.3 Warp-level primitives

warp 内线程可以通过 shuffle 等原语交换寄存器数据。例如 reduction 可在 log2(32) 轮中逐步求和，而不必经过 shared memory。

14. Block 内协作与同步

同一 block 内的线程可以：

访问 shared memory；
使用原子操作；
使用内存屏障；
使用 __syncthreads() 进行块级同步。

关键规则：

__syncthreads() 必须由 block 中所有相关线程以一致的控制流到达，否则可能死锁或产生未定义行为。

不能仅仅因为"每个线程最终都会调用一次"就认为安全；它们必须在相同的同步阶段到达。

Compute Capability 9.0 起，CUDA 还提供可选的 thread block cluster，使一组 block 在受约束的硬件范围内协作，并可使用 distributed shared memory。它是进阶机制，不改变初学者优先保证普通 block 独立的原则。

15. GPU 内存层次

层次	可见范围	容量/速度直觉	主要用途
Register	单个 thread	最小、最快	当前值、累加器
Shared memory	单个 block/CTA	小、低延迟、显式管理	数据复用、线程协作
L1 cache	通常 SM 层级	硬件管理	缓存局部访问
L2 cache	全 GPU	更大、更慢	跨 SM 数据缓存
Global memory / HBM	全 GPU	最大、高延迟、高总带宽	权重、激活、输入输出
Local memory	逻辑上 thread 私有，物理上通常在 device memory	可能很慢	寄存器不足时的 spill 等
Constant memory	全局只读且有缓存	适合 warp 内相同地址读取	常量参数

重要纠偏：

“local"描述可见性，不保证物理位置靠近线程，也不保证快。
shared memory 与 L1 常共享片上资源或可配置容量，但具体组织取决于架构。
寄存器不是无限的；每线程用得太多，会减少同一 SM 可驻留的 warp/block。

16. 合并访存（Coalescing）

一个 warp 的线程访问 global memory 时，硬件会把地址请求合并为尽量少的内存事务。

理想模式：

lane 0 → A[k]
lane 1 → A[k+1]
lane 2 → A[k+2]
...

不理想模式：

大步长跨越；
随机地址；
每个事务只使用很少字节；
未对齐访问导致额外事务。

这就是为什么行主序矩阵中，常把 threadIdx.x 映射到连续列：同一 warp 内连续线程访问连续地址。

17. Tiling 与矩阵乘法

朴素矩阵乘法：

C[m, n] = Σ_k A[m, k] * B[k, n]

一个高性能分块思路：

每个 block 负责 C 的一个 BLOCK_M × BLOCK_N 输出块；
沿 K 维以 BLOCK_K 为步长循环；
每轮把 A、B 的对应 tile 从 global memory 搬到 shared memory；
block 内线程复用这些数据并进行乘加；
结果在寄存器中累加；
最后写回 global memory。

核心收益不是减少数学运算，而是增加数据复用：

A 的一个元素可参与同一输出块的多列计算；
B 的一个元素可参与同一输出块的多行计算；
从 HBM 读取一次后，在 shared memory / register 中多次使用。

这正是后续 Triton 与 TileLang 都以 tile 为核心抽象的原因。

18. Warp 调度、延迟隐藏与 Occupancy

18.1 延迟隐藏

当 warp A 等待 global memory 时，调度器可以发射 warp B。要做到这一点，SM 中必须有足够多的可运行 warp。

18.2 Occupancy

常用定义：

Occupancy = SM 上实际驻留的 active warps / 该 SM 支持的最大 active warps

限制驻留数量的资源包括：

每 block 的线程数；
每线程的寄存器数；
每 block 的 shared memory；
架构对 block、warp 的数量上限。

18.3 高 Occupancy 不等于最高性能

更高 occupancy 通常有利于隐藏延迟，但可能与其他优化冲突：

更多寄存器可减少 spill 和重复访存；
更大的 shared-memory tile 可提高数据复用；
但它们会降低可同时驻留的 block/warp 数。

所以目标不是机械追求 100%，而是找到足以隐藏主要延迟、同时保留高数据复用和低指令开销的配置。

19. CUDA 优化检查表

课程总结的四个方向可以扩展成：

暴露足够并行度：grid 足够大，能覆盖全部 SM。
提高数据复用：用 register/shared memory 减少重复 HBM 访问。
改善访存模式：合并访问、对齐、减少无效事务。
减少控制流浪费：降低 warp divergence。
控制资源使用：在寄存器、shared memory、occupancy 之间权衡。
使用专用单元：适合时使用 Tensor Core、SFU 等。
让搬运与计算重叠：异步拷贝、pipeline、多 stream。
基于测量优化：先验证正确性，再 benchmark，再 profiler。

API 选讲的准确理解

CUDA events：适合测量 GPU 时间；不要只用 CPU 墙钟且忘记异步执行。
Streams：同一 stream 内有序；不同 stream 的工作"有机会"并发，但是否真正重叠取决于依赖、资源、硬件能力和默认 stream 语义。
Unified Memory：简化地址与迁移管理，但数据迁移仍有成本；性能敏感场景需要关注预取、驻留和缺页。
P2P：在支持的拓扑与配置下允许 GPU 间直接访问或复制；不是所有 GPU 对都支持，性能也取决于 PCIe/NVLink 等互联。

第三部分：从 Thread-level 到 Tile-level

20. 为什么需要 Tile-level Programming

CUDA 的控制力强，但程序员要显式完成：

每个 thread 负责什么；
thread/block 的索引如何映射到数据；
global/shared/register 之间怎样搬运；
如何同步；
如何处理边界；
如何避免 bank conflict、发散和低效访存。

但很多 AI Kernel 的自然表述是：

取一块张量 → 做一次块级计算 → 把结果写回。

因此 Tile-level DSL 把 block 内的大量线程协作抽象成 tile 操作：

确定当前 tile；
加载 tile；
计算；
写回；
用 mask 处理边界。

程序员仍决定关键分块，编译器负责把 tile 内计算映射到 thread/warp。

21. Triton 编程模型

21.1 基本视角

CUDA 从 thread 出发；
Triton 从 program instance 出发；
一个 Triton program 通常负责一个输出 tile；
tl.program_id(axis=...) 类似取得当前 program 在 launch grid 中的位置；
thread ID 通常不显式出现。

“一个 Triton program 约等于一个 CUDA block/CTA"是有用的初学者类比，但不是所有情况下都应理解成严格的一对一源码映射。

21.2 向量加法

核心结构：

pid = tl.program_id(axis=0)
offsets = pid * BLOCK_SIZE + tl.arange(0, BLOCK_SIZE)
mask = offsets < n_elements

x = tl.load(x_ptr + offsets, mask=mask, other=0.0)
y = tl.load(y_ptr + offsets, mask=mask, other=0.0)
z = x + y
tl.store(z_ptr + offsets, z, mask=mask)

理解重点：

offsets 是一组下标，不是单个线程的一个下标；
mask 防止最后一个 tile 越界；
other=0.0 为越界 load 提供填充值；
写法表达的是"整个 tile 的向量操作”。

21.3 矩阵乘法

每个 program 负责 C 的一个输出块：

acc = zeros(BLOCK_M, BLOCK_N)
for k0 in range(0, K, BLOCK_K):
 a_tile = load A[m:m+BLOCK_M, k0:k0+BLOCK_K]
 b_tile = load B[k0:k0+BLOCK_K, n:n+BLOCK_N]
 acc += dot(a_tile, b_tile)
store C tile

这里有三个分块尺度：

BLOCK_M：输出 tile 的行数；
BLOCK_N：输出 tile 的列数；
BLOCK_K：归约维每轮处理的长度。

指针计算依赖 stride：

A[i,j] 地址 = A_base + i * stride_am + j * stride_ak
B[i,j] 地址 = B_base + i * stride_bk + j * stride_bn

性能还受 program 执行顺序影响，因为相邻 program 是否复用同一批 A/B 数据会改变 L2 命中率。

21.4 Triton 的真实优缺点

优点：

Python 风格、代码短；
保留 tile shape、program 排列等重要决策；
适合 elementwise、reduction、matmul、attention 和融合算子；
支持 autotune；
可显著降低手写 CUDA 的工程成本。

代价：

一些线程级布局、shared memory 组织和流水线由编译器决定；
当性能瓶颈恰好位于这些细节时，调优空间较受限；
复杂硬件特化和某些 pipeline 表达可能更困难。

课堂把编译器称为"黑盒”、说 PTX/SASS 不透明，是强调控制粒度的说法，不应理解为"完全无法查看生成代码"。实践中可以 dump IR/PTX、结合 profiler 分析；只是源码与最终机器行为之间的映射比手写 CUDA 更间接。

22. TileLang 编程模型

TileLang 的目标位置可以理解为：

保留 tile-level 的简洁，同时把影响性能的数据流和内存层次更明确地写出来。

课程中的关键层次：

函数参数 T.Tensor：global memory 中的输入输出；
T.alloc_shared：CTA 内共享的 tile；
T.alloc_fragment：寄存器中的局部累加结果；
T.copy：不同内存层次之间搬运；
T.gemm：tile 级矩阵乘加；
T.Pipelined：沿分块循环表达搬运与计算重叠；
T.Kernel(...)：定义 launch grid / CTA 级程序实例。

一个矩阵乘法的数据流可以写成：

Global A/B
 │ T.copy
 ▼
Shared-memory tiles
 │ T.gemm
 ▼
Register fragment / accumulator
 │ T.copy
 ▼
Global C

其价值在于，读代码时能直接看到：

数据在哪一层；
什么数据会被复用；
沿哪个维度循环；
搬运和计算是否流水化。

23. CUDA、Triton、TileLang 怎样选择

维度	CUDA C++	Triton	TileLang
主要抽象	thread / warp / block	program / tensor tile	tile + 显式内存层次和数据流
控制粒度	最细	较高层	介于二者之间
开发效率	较低	高	中等
硬件细节负担	高	较低	中等
典型场景	极端调优、特殊机制、库级实现	快速开发与融合常见算子	需要显式数据流、pipeline 和可读结构的高性能 kernel

选择不是"谁永远更快"，而要问：

算子是否规则？
瓶颈是计算、访存、同步还是 launch overhead？
是否需要特殊硬件指令或复杂流水线？
是否需要跨硬件后端？
团队能承担多少开发和维护成本？

24. `torch.compile` 与手写 Kernel 的关系

课堂问答认为二者大体正交，这个方向是对的，但机制需要更精确地区分：

TorchDynamo 负责从 Python 程序捕获可编译的计算图；
TorchInductor 等后端进行融合、布局、调度和代码生成，GPU 上常生成 Triton kernel；
CUDA Graphs 可用于减少 CPU launch overhead，但它不是 torch.compile 捕获 Python 计算图的同义词；
手写 Triton/TileLang/CUDA 仍有价值，因为通用编译器不一定能生成最适合特殊算子、数据布局或硬件特性的实现。

因此可以同时使用：

模型/图级优化：torch.compile
 +
关键热点算子：手写或定制 Kernel

第四部分：把这些知识连回 AI Infra

25. AI Infra 的共同问题

层级	典型对象	核心问题
单条指令/单个 warp	SIMD/SIMT、分支	lane 是否都做有效工作
单个 block/CTA	tiling、shared memory	数据能否在片上复用
单个 GPU	SM 调度、HBM、stream	是否计算饱和、带宽饱和、延迟被隐藏
多 GPU	TP/PP/DP/EP、collectives	计算与通信如何重叠
单机推理服务	batching、KV Cache、调度	吞吐、首 token 延迟、显存容量如何权衡
集群	网络拓扑、容错、资源调度	如何扩展并保持利用率

同一个思想不断重复：

找到可并行部分；
选择分块；
把块映射到硬件；
把数据放到合适存储层；
安排通信和同步；
用并发隐藏不可避免的延迟；
测量瓶颈并迭代。

26. 为什么矩阵乘法贯穿整个课程

Transformer 的大量计算最终落在 GEMM 或 GEMM-like Kernel 上，包括：

Q/K/V 线性投影；
attention 中的 QKᵀ 和 PV；
MLP 的上投影、门控、下投影；
训练中的梯度计算；
张量并行下的分片矩阵乘。

矩阵乘法同时包含：

大量独立输出元素；
沿 K 维的归约；
明确的数据复用；
对布局、带宽、缓存和专用矩阵单元的强依赖。

因此它是学习并行化、tiling、memory hierarchy 和 pipeline 的最佳样例。

第五部分：课程之外必须补上的性能模型

27. Amdahl 定律：串行部分决定强扩展上限

若程序中可并行比例为 p，使用 N 个处理单元，理想加速比为：

Speedup(N) = 1 / ((1 - p) + p / N)

例如 95% 可并行，即使设备无限多，最大加速也只有 1 / 0.05 = 20 倍。

现实还要加上通信、同步和调度开销，所以实际更低。它解释了为什么优化最后一点串行瓶颈可能比继续加卡更重要。

28. Strong Scaling 与 Weak Scaling

Strong scaling：总问题规模不变，增加设备，看运行时间能否下降。
Weak scaling：每台设备的工作量不变，设备与总问题规模一起增长，看总时间能否保持。

训练一个固定模型更接近 strong scaling；随着 GPU 数增加同时增大 batch 或模型规模，则包含 weak scaling 的味道。

29. Arithmetic Intensity 与 Roofline

算术强度：

Arithmetic Intensity = 运算次数 FLOPs / 从慢速内存搬运的字节数 Bytes

粗略性能上限：

Performance ≤ min(Peak Compute, Memory Bandwidth × Arithmetic Intensity)

算术强度低：通常 memory-bound；
算术强度高：可能 compute-bound。

向量加法每个元素只做一次加法，却要读两个输入、写一个输出，通常是 memory-bound。分块矩阵乘法可让载入的数据被多次复用，算术强度高得多，更容易接近计算峰值。

这比"看到 GPU 峰值 FLOPS 就估算程序速度"可靠得多。

30. Little 定律式的延迟隐藏直觉

要维持高吞吐，系统中需要足够多的在途工作：

并发在途量 ≈ 吞吐量 × 单次延迟

显存延迟很高时，需要许多 warp 在途；推理服务中单请求生成有等待时，需要 continuous batching 等调度策略维持设备利用率。底层 GPU 调度和上层服务调度，在这里有相似的结构。

31. 数值精度不是附属问题

GPU 的不同单元和编译选项可能在速度与精度之间取舍：

FP32、TF32、FP16、BF16、FP8 等格式吞吐不同；
累加精度可能高于输入精度；
--use_fast_math 等选项可能使用更快但精度/语义不同的近似；
并行 reduction 改变求和顺序，浮点结果可能与串行结果略有不同。

性能优化必须同时定义正确性容忍度：绝对误差、相对误差、ULP、任务指标或训练稳定性。

第六部分：容易误解的课堂表述

32. 纠偏清单

“GPU 比 CPU 快” 只对适合高吞吐并行、具有足够工作量和良好数据访问的任务成立。
“有 N 个核心就快 N 倍” 这是无依赖、无通信、无调度开销、负载完全均衡时的理想上限。
“一个 warp 的 32 个线程必须一直执行相同指令” 它们可以发生分支，但不同路径通常会被分阶段执行，造成发散开销。
“block 之间绝对不能通信” 普通 kernel 的可扩展模型要求 block 独立；现代 CUDA 有 cooperative groups、cluster 等受约束机制，但不能默认依赖任意 block 的调度顺序。
“Shared memory 一定比 global memory 快” 通常低延迟且可控，但 bank conflict、额外同步、低复用或过高资源占用都可能抵消收益。
“Occupancy 越高越好” 需要"足够高"来隐藏延迟，不必盲目追求 100%。
“多个 stream 就一定并发” stream 只提供并发机会；真实重叠取决于依赖和硬件资源。
“Unified Memory 不需要考虑拷贝” API 简化了，但迁移、缺页和驻留成本仍然存在。
“Triton 看不到生成代码” 可检查编译中间表示和生成代码；真正的限制是控制较间接、调优与定位成本可能较高。
“torch.compile 就是 CUDA Graph” 计算图捕获、编译优化、代码生成和 CUDA Graphs 是不同环节，可能组合使用。
“TileLang 一定跨平台且性能都好” 可移植抽象能减少迁移成本，但新后端仍需要编译器支持、调度适配和性能验证。

第七部分：术语速查

术语	一句话解释
HPC	High Performance Computing，高性能计算
AI Infra	支撑 AI 训练、推理和部署的软硬件系统
Kernel	在加速器上执行的一段计算函数
Host / Device	通常分别指 CPU 侧 / GPU 侧
Grid	一次 CUDA kernel launch 的全部 block
Block / CTA	可在同一 SM 上合作、共享 shared memory 的线程组
Warp	NVIDIA GPU 的线程调度/执行分组，通常含 32 个线程
SM	Streaming Multiprocessor，执行 block/warp 的硬件单元
SIMT	Single Instruction, Multiple Threads
SIMD	Single Instruction, Multiple Data
SPMD	Single Program, Multiple Data
Tile	数据张量的一个分块
Tiling	把大计算分成适合并行和存储层次的小块
Coalescing	合并同一 warp 的连续内存请求
Divergence	同一 warp 的线程走不同控制路径
Occupancy	SM 实际驻留 warp 与架构上限之比
Register pressure	每线程寄存器需求对驻留并发度造成的压力
Spill	寄存器不足，变量被放到更慢的 local/device memory
Reduction	把多个值按加、最大值等操作聚合
Collective	多进程/多设备共同参与的通信操作
DSL	Domain-Specific Language，面向特定领域的语言
PTX / SASS	NVIDIA 的虚拟指令集 / 更接近实际 GPU 机器指令的表示
HBM	High Bandwidth Memory，高带宽显存
Arithmetic Intensity	每搬运一字节数据能完成多少运算

第八部分：推荐的权威延伸资料

NVIDIA CUDA Programming Guide：Programming Model 优先读 thread block、grid、SM、block 独立性和内存层次。
NVIDIA CUDA Programming Guide：Introduction to CUDA C++ 对照课堂中的 kernel、内置索引和 thread block cluster。
Triton 官方教程总览推荐依次做 vector add、fused softmax、matrix multiplication。
Triton Vector Addition 用于掌握 program_id → offsets → mask → load → compute → store。
Triton Matrix Multiplication 重点看三维分块、pointer arithmetic、L2-friendly program ordering 和 autotune。
TileLang TileLibrary Reference 查阅 T.alloc_shared、T.Pipelined 等原语。
PyTorch torch.compile 文档用于区分图编译、Inductor/Triton 代码生成和 CUDA Graphs。

结语：应该带走的不是术语，而是一个分析模板

以后看到任何 AI Infra 性能问题，可以按这个顺序问：

计算是什么？ 输入、输出、规则分别是什么？
并行机会在哪里？ 哪些任务没有依赖？
怎样分块？ 按数据、功能、模型层、序列还是专家？
映射到哪里？ thread、warp、CTA、SM、GPU、节点分别承担什么？
数据在哪里？ register、shared、HBM 还是远端 GPU？
瓶颈是什么？ 计算、带宽、延迟、同步、通信还是 launch overhead？
能否重叠？ 搬运与计算、通信与计算、不同请求是否可流水化？
怎样证明？ 正确性测试、benchmark 和 profiler 是否支持你的判断？

当你能够沿这八个问题分析一个 Kernel 或一个分布式系统时，就已经不再只是"知道几个 GPU 术语"，而是在用 Infra 的方式思考。

知识技能	描述
Linux	免费开源的操作系统，就像 Windows 和 macOS，但你可以完全控制并自由定制它
Shell	命令行界面，让用户以文本指令与操作系统交互
C/C++ 编译器	将高级语言代码转换为机器码或字节码的程序
Vim	强大的文本编辑器，通过键盘命令快速编辑文件，初学曲线陡峭，熟练后效率极高

JasperSao的博客

KV 进化（二）：Snapshot 全量快照 + AOF 增量日志

1. 确立实现模式

2. 建立独立的持久化模块

3. 打开和关闭 AOF

4. 把命令追加到 AOF

5. 从缓冲区同步到文件

6. 判断哪些命令需要写入 AOF

7. 只有命令执行成功才记录

8. AOF 重放

9. AOF 重放函数的实际过程

10. AOF 基础闭环

11. 开始实现全量快照

12. 定义统一的访问函数

13. foreach 的职责

14. context 的意义

15. 把一组 key-value 写进快照

16. 为什么快照中只保存 SET 类型的命令

17. 保存所有引擎的数据

18. 使用临时文件保存快照

19. 把快照同步到磁盘

20. 增加 SAVE 命令

21. 快照与 AOF 的重复问题

22. 获取 AOF 当前偏移量

23. 把 AOF 偏移量写进快照

24. 加载全量快照

25. 读取快照中的偏移量

26. 逐行恢复快照数据

27. 让 AOF 从指定位置开始重放

28. 最终启动恢复顺序

29. 快照与 AOF 最终如何配合

30. 最终验证

31. 当前完成的整体闭环

KV 进化（一）：给 91kvstore 接上一条跳表

先对跳表有个大致印象

写跳表之前，我先整理了项目

第一步：把整数跳表改造成字符串 KV

第二步：补齐统一接口

第三步：统一返回值

第四步：别让测试变成纯苦力

第五步：从“能运行”走向“融入项目”

第六步：创建全局跳表实例

第七步：命令协议融合

最后：用 testcase 做端到端测试

小结

KV 存储项目：Hash 接入、多语言客户端与 SkipList 扩展

与前三篇的关系

1. 本阶段增加了什么

2. Hash 在项目中的位置

3. 第一个接入点：kvstore.h

3.1 增加编译开关

3.2 Hash 实例在项目中的最小理解

3.3 对外仍然使用已有的 5+2 形状

4. 第二个接入点：Makefile

5. 第三个接入点：实例生命周期

5.1 定义全局实例

5.2 网络服务启动前创建

5.3 网络服务停止后销毁

6. 第四个接入点：协议命令

一条 HSET 的新增路径

7. 当前 Hash 代码必须修正的工程问题

7.1 创建后必须把桶数组清零

7.2 下标计算应使用实例容量

7.3 创建节点失败要逆序回滚

7.4 三条释放路径必须一致

7.5 MOD 要先申请，再替换

7.6 其他接口一致性问题

8. 多语言支持：本阶段新增的认识

用同一场景验证五种语言

9. 课后扩展：把 SkipList 融入 KVEngine

9.1 范围查询需要扩展 5+2

10. 面试题

10.1 KV 存储为什么常采用单线程执行命令？

10.2 范围查询应选择什么 KVEngine？

10.3 频繁 malloc/free 时怎样管理 KV 内存？

11. 本阶段的实施顺序

总结

KV 存储项目：客户端测试、压力测试与多引擎扩展

1. 这一阶段解决什么问题

2. 用 Makefile 固定构建过程

3. 第一个接入点：`kvstore.h`

一条 `HSET` 的新增路径

6.1 `total` 的核心约定

9. 为什么给红黑树命令增加 `R` 前缀

6. `kvstore.h`：数组引擎的数据结构与接口

8. 创建数组实例：`kvs_array_create()`

9. `SET`：保存一组 key-value

10. `GET`：按照 key 查找 value

11. `DEL`：删除 key-value

12. `MOD`：修改已有 key 的 value

13. `EXIST`：复用 GET 判断 key 是否存在

15. `kvs_split_token()`：把命令切成参数

16. `kvs_filter_protocol()`：识别命令并生成响应

17. `kvs_protocol()`：本篇代码的总入口

19. 一条 `SET` 命令的完整路径

20. 一条 `GET` 命令的完整路径