1. 从一次连接堆积说起epoll 到底解决什么问题如果你在 Linux 上写过高并发服务大概率遇到过这样的场景用 select 或 poll 写的服务器连接数一过千就开始发飘CPU 占用不低但吞吐上不去日志里还时不时冒出超时。这不是代码写得差而是 select/poll 的模型本身有天花板——每次调用都要把整个 fd 集合从用户态拷到内核态内核再线性扫描一遍哪个 fd 就绪了返回哪个。连接越多扫描越慢而且大部分连接在某一时刻其实是空闲的扫描它们纯属浪费。epoll 就是 Linux 内核为「大批量句柄」这个场景做的改进。它把「注册关注哪些 fd」和「等待哪些 fd 就绪」拆成了两步内核里用红黑树维护被监听的 fd用就绪链表维护已经触发事件的 fd。调用 epoll_wait 时内核不需要遍历全部 fd只把就绪链表里的东西返回给你。所以它的 IO 效率不会随 fd 数目增加而线性下降这一点在 WAN 环境、大量空闲连接的场景下尤其明显。这篇文章面向的是已经能写基本 socket 程序、想搞懂 epoll 事件循环怎么落地并且希望把本地服务接到统一 API 通道上的开发者。我会先给一个能直接编译运行的 epoll 示例再讲清楚 LT 和 ET 的差别最后把 TaoToken 的 config.toml 配置骨架和 curl 验证动作补上让你从系统调用一路走到实际接入。TaoToken 在这里扮演的角色是统一 Key 和 API 通道省去你在多个模型服务之间来回切换 base_url 和鉴权的麻烦。2. 三个系统调用撑起 epollcreate、ctl、waitepoll 的接口非常克制核心就三个系统调用理解了它们的分工整个模型就清楚了。epoll_create新代码里更推荐epoll_create1创建一个 epoll 实例返回一个 fd。这个 fd 不是普通文件而是内核里那个红黑树和就绪链表的句柄。epoll_ctl用来往这个实例里增删改要监听的 fd操作类型有EPOLL_CTL_ADD、EPOLL_CTL_MOD、EPOLL_CTL_DEL。epoll_wait则是阻塞等待直到就绪链表里有事件或者超时。这里有个容易忽略的点epoll 监听的 fd 上限不是FD_SETSIZE那种编译期常量而是系统能打开的最大文件数。你可以用cat /proc/sys/fs/file-max看这个值1GB 内存的机器上通常在十万量级。这意味着单进程撑住上万连接在 epoll 下是常规操作而不是什么黑科技。关于 LT 和 ET这是绕不开的。LT 是默认模式只要 fd 还有数据没读完每次epoll_wait都会继续通知你编程容错高select/poll 就是这种思路。ET 是边沿触发只在状态「从未就绪变为就绪」的那一刻通知一次之后你不读完它就不再提醒。ET 必须配非阻塞 socket否则一次 read 卡住整个循环就废了。实测下来LT 写起来省心ET 在特定高吞吐场景下能少几次系统调用但调试成本高新手建议先用 LT 把逻辑跑通。注意ET 模式下如果一次没把数据读干净剩下的数据可能永远等不到下一次通知直到有新数据到达才可能再次触发。所以 ET 的读循环必须一直读到返回EAGAIN为止。3. 可复制的 epoll 事件循环示例下面这段代码是一个最小可用的 epoll 回显服务器监听 8080 端口接受连接后把收到的数据原样发回。它用 LT 模式结构清晰你可以直接保存成epoll_echo.c编译运行。#include stdio.h #include stdlib.h #include string.h #include unistd.h #include errno.h #include fcntl.h #include arpa/inet.h #include sys/epoll.h #include sys/socket.h #define MAX_EVENTS 64 #define PORT 8080 #define BUF_SIZE 1024 static int set_nonblocking(int fd) { int flags fcntl(fd, F_GETFL, 0); if (flags -1) return -1; return fcntl(fd, F_SETFL, flags | O_NONBLOCK); } int main(void) { int listen_fd socket(AF_INET, SOCK_STREAM, 0); if (listen_fd 0) { perror(socket); exit(1); } int opt 1; setsockopt(listen_fd, SOL_SOCKET, SO_REUSEADDR, opt, sizeof(opt)); struct sockaddr_in addr; memset(addr, 0, sizeof(addr)); addr.sin_family AF_INET; addr.sin_addr.s_addr htonl(INADDR_ANY); addr.sin_port htons(PORT); if (bind(listen_fd, (struct sockaddr *)addr, sizeof(addr)) 0) { perror(bind); exit(1); } if (listen(listen_fd, 128) 0) { perror(listen); exit(1); } set_nonblocking(listen_fd); int epfd epoll_create1(0); if (epfd 0) { perror(epoll_create1); exit(1); } struct epoll_event ev, events[MAX_EVENTS]; ev.events EPOLLIN; ev.data.fd listen_fd; if (epoll_ctl(epfd, EPOLL_CTL_ADD, listen_fd, ev) 0) { perror(epoll_ctl add listen); exit(1); } printf(epoll echo server listening on %d\n, PORT); while (1) { int n epoll_wait(epfd, events, MAX_EVENTS, -1); if (n 0) { if (errno EINTR) continue; perror(epoll_wait); break; } for (int i 0; i n; i) { int fd events[i].data.fd; if (fd listen_fd) { struct sockaddr_in cli; socklen_t len sizeof(cli); int conn accept(listen_fd, (struct sockaddr *)cli, len); if (conn 0) { perror(accept); continue; } set_nonblocking(conn); ev.events EPOLLIN; ev.data.fd conn; epoll_ctl(epfd, EPOLL_CTL_ADD, conn, ev); printf(new connection fd%d\n, conn); } else { char buf[BUF_SIZE]; ssize_t r read(fd, buf, sizeof(buf)); if (r 0) { write(fd, buf, r); } else if (r 0) { printf(connection closed fd%d\n, fd); epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL); close(fd); } else { if (errno ! EAGAIN errno ! EWOULDBLOCK) { perror(read); epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL); close(fd); } } } } } close(epfd); close(listen_fd); return 0; }编译命令gcc -O2 -o epoll_echo epoll_echo.c运行后另开一个终端测试printf hello epoll\n | nc 127.0.0.1 8080你会看到服务端打印new connection fd...客户端收到原样返回的hello epoll。这个循环里epoll_wait是唯一阻塞点所有 fd 都设成非阻塞读不到数据就返回EAGAIN不会卡住其他连接。这就是 epoll 事件循环的骨架生产环境无非是在这个骨架上加缓冲区管理、超时控制和业务分发。4. TaoToken 前置统一 Key 与 API 通道的配置骨架本地服务跑通之后下一步往往是让它去调用模型 API。如果你同时用多个模型服务每个都有自己的 base_url 和鉴权方式代码里到处散落 Key 很难维护。TaoToken 提供统一 Key 和 API 通道把这件事收敛到一处配置。先到控制台创建 API Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到 Key 之后在项目根目录建一个config.toml骨架如下# TaoToken 统一接入配置骨架 [api] base_url https://taotoken.net/api api_key sk-你的Key timeout_seconds 30 [model] default claude-sonnet fallback gpt-4o-mini [retry] max_attempts 3 backoff_ms 500这里base_url固定用https://taotoken.net/api不要加 UTM 参数那是给网页链接用的。api_key从控制台复制别硬编码进 git建议用环境变量覆盖export TAOTOKEN_API_KEYsk-你的Key然后在代码里读取环境变量优先、配置文件兜底。这样本地调试和线上部署可以共用一份 config.toml只换环境变量。如果你主要做长期编码或 Agent 类任务可以了解 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合持续性的开发场景。想先在网页上验证模型对话效果用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接试。5. 验证请求用 curl 确认 API 连通性配置写好后别急着改业务代码先用 curl 打一发确认 Key 和通道是通的。这是最省时间的排障动作。curl -sS -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [ {role: user, content: 用一句话说明 epoll 的 LT 和 ET 区别} ], max_tokens: 128 }如果返回里能看到choices数组和模型生成的文本说明通道正常。如果返回 401检查 Key 是否复制完整、有没有多余空格返回 404检查路径是不是/api/v1/chat/completionsbase_url 有没有多写斜杠返回超时先curl -v看 TLS 握手到哪一步再确认网络出口是否正常。把这段 curl 验证通过之后再回到你的 epoll 服务里把「收到请求 → 调用模型 → 返回结果」这条链路接上。因为 epoll 循环本身是非阻塞的调用模型 API 这种耗时操作不要直接放在事件循环里同步做否则会阻塞其他连接。常见做法是把请求丢给线程池或异步任务队列处理完再通过 eventfd 或管道唤醒 epoll 循环写回结果。这一步是 epoll 从「能跑」到「能扛」的关键也是很多人第一次写高并发服务时踩的坑。6. 本篇常见错排查epoll_wait 返回 -1 且 errno 是 EINTR这是被信号中断不是错误直接 continue 重新调用即可。很多示例代码没处理这个导致服务偶尔莫名退出。ET 模式下连接只收到一次数据典型原因是没把 socket 设成非阻塞或者读循环没读到EAGAIN就退出。ET 要求你一次把数据读干净否则剩余数据不会再有通知。accept 返回 EMFILE打开的 fd 达到进程上限。检查有没有及时 close 断开的连接以及ulimit -n的值。epoll 本身不限制 fd 数量但进程的 fd 上限会限制你。curl 返回 401 但 Key 看着没问题先echo $TAOTOKEN_API_KEY确认环境变量在当前 shell 里真的存在再检查有没有把 Key 写进 config.toml 又被环境变量空值覆盖。顺序搞反是常见失误。epoll_ctl 返回 EEXIST同一个 fd 重复 ADD。要么先 DEL 再 ADD要么用 MOD。生产代码里建议维护一张 fd 状态表避免重复操作。接入相关的细节可以对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数说明和示例。如果你用的是 Claude Code 这类工具Anthropic 兼容接入的说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode_anthropicutm_campaignrewrite 。把上面这段 epoll 回显服务编译跑起来再用 curl 确认 TaoToken 通道连通你就完成了从 Linux 系统调用到实际 API 接入的完整闭环。接下来要做的是把业务逻辑填进那个事件循环并且记住任何阻塞操作都不要直接塞进 epoll_wait 所在的线程。 epoll 简介：从 Linux 系统调用到 TaoToken 配置实战
1. 从一次连接堆积说起epoll 到底解决什么问题如果你在 Linux 上写过高并发服务大概率遇到过这样的场景用 select 或 poll 写的服务器连接数一过千就开始发飘CPU 占用不低但吞吐上不去日志里还时不时冒出超时。这不是代码写得差而是 select/poll 的模型本身有天花板——每次调用都要把整个 fd 集合从用户态拷到内核态内核再线性扫描一遍哪个 fd 就绪了返回哪个。连接越多扫描越慢而且大部分连接在某一时刻其实是空闲的扫描它们纯属浪费。epoll 就是 Linux 内核为「大批量句柄」这个场景做的改进。它把「注册关注哪些 fd」和「等待哪些 fd 就绪」拆成了两步内核里用红黑树维护被监听的 fd用就绪链表维护已经触发事件的 fd。调用 epoll_wait 时内核不需要遍历全部 fd只把就绪链表里的东西返回给你。所以它的 IO 效率不会随 fd 数目增加而线性下降这一点在 WAN 环境、大量空闲连接的场景下尤其明显。这篇文章面向的是已经能写基本 socket 程序、想搞懂 epoll 事件循环怎么落地并且希望把本地服务接到统一 API 通道上的开发者。我会先给一个能直接编译运行的 epoll 示例再讲清楚 LT 和 ET 的差别最后把 TaoToken 的 config.toml 配置骨架和 curl 验证动作补上让你从系统调用一路走到实际接入。TaoToken 在这里扮演的角色是统一 Key 和 API 通道省去你在多个模型服务之间来回切换 base_url 和鉴权的麻烦。2. 三个系统调用撑起 epollcreate、ctl、waitepoll 的接口非常克制核心就三个系统调用理解了它们的分工整个模型就清楚了。epoll_create新代码里更推荐epoll_create1创建一个 epoll 实例返回一个 fd。这个 fd 不是普通文件而是内核里那个红黑树和就绪链表的句柄。epoll_ctl用来往这个实例里增删改要监听的 fd操作类型有EPOLL_CTL_ADD、EPOLL_CTL_MOD、EPOLL_CTL_DEL。epoll_wait则是阻塞等待直到就绪链表里有事件或者超时。这里有个容易忽略的点epoll 监听的 fd 上限不是FD_SETSIZE那种编译期常量而是系统能打开的最大文件数。你可以用cat /proc/sys/fs/file-max看这个值1GB 内存的机器上通常在十万量级。这意味着单进程撑住上万连接在 epoll 下是常规操作而不是什么黑科技。关于 LT 和 ET这是绕不开的。LT 是默认模式只要 fd 还有数据没读完每次epoll_wait都会继续通知你编程容错高select/poll 就是这种思路。ET 是边沿触发只在状态「从未就绪变为就绪」的那一刻通知一次之后你不读完它就不再提醒。ET 必须配非阻塞 socket否则一次 read 卡住整个循环就废了。实测下来LT 写起来省心ET 在特定高吞吐场景下能少几次系统调用但调试成本高新手建议先用 LT 把逻辑跑通。注意ET 模式下如果一次没把数据读干净剩下的数据可能永远等不到下一次通知直到有新数据到达才可能再次触发。所以 ET 的读循环必须一直读到返回EAGAIN为止。3. 可复制的 epoll 事件循环示例下面这段代码是一个最小可用的 epoll 回显服务器监听 8080 端口接受连接后把收到的数据原样发回。它用 LT 模式结构清晰你可以直接保存成epoll_echo.c编译运行。#include stdio.h #include stdlib.h #include string.h #include unistd.h #include errno.h #include fcntl.h #include arpa/inet.h #include sys/epoll.h #include sys/socket.h #define MAX_EVENTS 64 #define PORT 8080 #define BUF_SIZE 1024 static int set_nonblocking(int fd) { int flags fcntl(fd, F_GETFL, 0); if (flags -1) return -1; return fcntl(fd, F_SETFL, flags | O_NONBLOCK); } int main(void) { int listen_fd socket(AF_INET, SOCK_STREAM, 0); if (listen_fd 0) { perror(socket); exit(1); } int opt 1; setsockopt(listen_fd, SOL_SOCKET, SO_REUSEADDR, opt, sizeof(opt)); struct sockaddr_in addr; memset(addr, 0, sizeof(addr)); addr.sin_family AF_INET; addr.sin_addr.s_addr htonl(INADDR_ANY); addr.sin_port htons(PORT); if (bind(listen_fd, (struct sockaddr *)addr, sizeof(addr)) 0) { perror(bind); exit(1); } if (listen(listen_fd, 128) 0) { perror(listen); exit(1); } set_nonblocking(listen_fd); int epfd epoll_create1(0); if (epfd 0) { perror(epoll_create1); exit(1); } struct epoll_event ev, events[MAX_EVENTS]; ev.events EPOLLIN; ev.data.fd listen_fd; if (epoll_ctl(epfd, EPOLL_CTL_ADD, listen_fd, ev) 0) { perror(epoll_ctl add listen); exit(1); } printf(epoll echo server listening on %d\n, PORT); while (1) { int n epoll_wait(epfd, events, MAX_EVENTS, -1); if (n 0) { if (errno EINTR) continue; perror(epoll_wait); break; } for (int i 0; i n; i) { int fd events[i].data.fd; if (fd listen_fd) { struct sockaddr_in cli; socklen_t len sizeof(cli); int conn accept(listen_fd, (struct sockaddr *)cli, len); if (conn 0) { perror(accept); continue; } set_nonblocking(conn); ev.events EPOLLIN; ev.data.fd conn; epoll_ctl(epfd, EPOLL_CTL_ADD, conn, ev); printf(new connection fd%d\n, conn); } else { char buf[BUF_SIZE]; ssize_t r read(fd, buf, sizeof(buf)); if (r 0) { write(fd, buf, r); } else if (r 0) { printf(connection closed fd%d\n, fd); epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL); close(fd); } else { if (errno ! EAGAIN errno ! EWOULDBLOCK) { perror(read); epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL); close(fd); } } } } } close(epfd); close(listen_fd); return 0; }编译命令gcc -O2 -o epoll_echo epoll_echo.c运行后另开一个终端测试printf hello epoll\n | nc 127.0.0.1 8080你会看到服务端打印new connection fd...客户端收到原样返回的hello epoll。这个循环里epoll_wait是唯一阻塞点所有 fd 都设成非阻塞读不到数据就返回EAGAIN不会卡住其他连接。这就是 epoll 事件循环的骨架生产环境无非是在这个骨架上加缓冲区管理、超时控制和业务分发。4. TaoToken 前置统一 Key 与 API 通道的配置骨架本地服务跑通之后下一步往往是让它去调用模型 API。如果你同时用多个模型服务每个都有自己的 base_url 和鉴权方式代码里到处散落 Key 很难维护。TaoToken 提供统一 Key 和 API 通道把这件事收敛到一处配置。先到控制台创建 API Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。拿到 Key 之后在项目根目录建一个config.toml骨架如下# TaoToken 统一接入配置骨架 [api] base_url https://taotoken.net/api api_key sk-你的Key timeout_seconds 30 [model] default claude-sonnet fallback gpt-4o-mini [retry] max_attempts 3 backoff_ms 500这里base_url固定用https://taotoken.net/api不要加 UTM 参数那是给网页链接用的。api_key从控制台复制别硬编码进 git建议用环境变量覆盖export TAOTOKEN_API_KEYsk-你的Key然后在代码里读取环境变量优先、配置文件兜底。这样本地调试和线上部署可以共用一份 config.toml只换环境变量。如果你主要做长期编码或 Agent 类任务可以了解 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 它更适合持续性的开发场景。想先在网页上验证模型对话效果用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接试。5. 验证请求用 curl 确认 API 连通性配置写好后别急着改业务代码先用 curl 打一发确认 Key 和通道是通的。这是最省时间的排障动作。curl -sS -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [ {role: user, content: 用一句话说明 epoll 的 LT 和 ET 区别} ], max_tokens: 128 }如果返回里能看到choices数组和模型生成的文本说明通道正常。如果返回 401检查 Key 是否复制完整、有没有多余空格返回 404检查路径是不是/api/v1/chat/completionsbase_url 有没有多写斜杠返回超时先curl -v看 TLS 握手到哪一步再确认网络出口是否正常。把这段 curl 验证通过之后再回到你的 epoll 服务里把「收到请求 → 调用模型 → 返回结果」这条链路接上。因为 epoll 循环本身是非阻塞的调用模型 API 这种耗时操作不要直接放在事件循环里同步做否则会阻塞其他连接。常见做法是把请求丢给线程池或异步任务队列处理完再通过 eventfd 或管道唤醒 epoll 循环写回结果。这一步是 epoll 从「能跑」到「能扛」的关键也是很多人第一次写高并发服务时踩的坑。6. 本篇常见错排查epoll_wait 返回 -1 且 errno 是 EINTR这是被信号中断不是错误直接 continue 重新调用即可。很多示例代码没处理这个导致服务偶尔莫名退出。ET 模式下连接只收到一次数据典型原因是没把 socket 设成非阻塞或者读循环没读到EAGAIN就退出。ET 要求你一次把数据读干净否则剩余数据不会再有通知。accept 返回 EMFILE打开的 fd 达到进程上限。检查有没有及时 close 断开的连接以及ulimit -n的值。epoll 本身不限制 fd 数量但进程的 fd 上限会限制你。curl 返回 401 但 Key 看着没问题先echo $TAOTOKEN_API_KEY确认环境变量在当前 shell 里真的存在再检查有没有把 Key 写进 config.toml 又被环境变量空值覆盖。顺序搞反是常见失误。epoll_ctl 返回 EEXIST同一个 fd 重复 ADD。要么先 DEL 再 ADD要么用 MOD。生产代码里建议维护一张 fd 状态表避免重复操作。接入相关的细节可以对照接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有完整的参数说明和示例。如果你用的是 Claude Code 这类工具Anthropic 兼容接入的说明在 https://taotoken.net/claudecode-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaudecode_anthropicutm_campaignrewrite 。把上面这段 epoll 回显服务编译跑起来再用 curl 确认 TaoToken 通道连通你就完成了从 Linux 系统调用到实际 API 接入的完整闭环。接下来要做的是把业务逻辑填进那个事件循环并且记住任何阻塞操作都不要直接塞进 epoll_wait 所在的线程。