graph TD
    A[主线程: 配置/监控] --> B[IO_uring 实例池 N个]
    B --> C[Worker 线程组 M个]
    C --> D[共享 SQ/CQ 环形缓冲区]
    D --> E[内核异步执行引擎]
    E --> F[完成队列回调分发]
    F --> G[业务逻辑层: 会话/协议/调度]

typedef enum {
    CONN_ACCEPTING,   // 投放 accept 请求
    CONN_HANDSHAKE,   // TLS/协议握手
    CONN_STREAMING,   // 正常转发：splice/send_zc
    CONN_DRAINING,    // 半关闭/缓冲区排空
    CONN_CLOSING      // 资源回收
} conn_state_e;

[客户端] --recvmsg(ZC)--> [内核 Socket Buffer] --splice--> [Pipe Buffer] --splice/send_zc--> [下游/客户端]

// 提交 splice 请求：上游 socket -> pipe
struct io_uring_sqe *sqe = io_uring_get_sqe(ring);
io_uring_prep_splice(sqe, upstream_fd, 0, pipe_fd[1], 0,
                     MAX_SPLICE_LEN, SPLICE_F_MOVE | SPLICE_F_NONBLOCK);
sqe->user_data = encode_req(CONN_UPSTREAM_TO_PIPE, conn_id);

// 提交 splice 请求：pipe -> 下游 socket
sqe = io_uring_get_sqe(ring);
io_uring_prep_splice(sqe, pipe_fd[0], 0, downstream_fd, 0,
                     MAX_SPLICE_LEN, SPLICE_F_MOVE | SPLICE_F_NONBLOCK);
sqe->user_data = encode_req(CONN_PIPE_TO_DOWNSTREAM, conn_id);

io_uring_submit(ring);  // 批量提交

# /etc/sysctl.d/99-media-server.conf
net.core.netdev_max_backlog = 250000
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.tcp_fastopen = 3
net.ipv4.tcp_slow_start_after_idle = 0
net.ipv4.tcp_notsent_lowat = 131072   # 限制未发送队列，降低延迟
vm.max_map_count = 1048576            # 支持大量 mmap/pipe 缓冲区
fs.pipe-max-size = 4194304            # 单 pipe 最大 4MB
fs.file-max = 10000000

# 吞吐率
rate(media_server_bytes_sent_total[1m])
rate(media_server_bytes_recv_total[1m])

# 零拷贝效率
media_server_zero_copy_bytes_total / media_server_total_bytes_total

# 延迟分位
histogram_quantile(0.99, rate(media_server_io_latency_seconds_bucket[5m]))

# 连接健康度
media_server_active_connections
media_server_connection_errors_total{type="timeout|reset|oom"}

# io_uring 内部状态
media_server_sq_full_total
media_server_cq_overflow_total
media_server_syscall_submit_total

// 线程本地缓存 (TLS)
__thread struct buf_cache {
    void *slots[64];
    int count;
} tls_cache[POOL_LEVELS];

void *buf_acquire(size_t sz) {
    int lvl = level_of(sz);
    if (tls_cache[lvl].count > 0)
        return tls_cache[lvl].slots[--tls_cache[lvl].count];
    // 慢路径：从全局 Slab 批量搬运 32 个
    return slab_bulk_pop(lvl, tls_cache[lvl].slots, &tls_cache[lvl].count);
}

void buf_release(void *ptr, size_t sz) {
    int lvl = level_of(sz);
    if (tls_cache[lvl].count < 64) {
        tls_cache[lvl].slots[tls_cache[lvl].count++] = ptr;
        return;
    }
    slab_bulk_push(lvl, tls_cache[lvl].slots, 32); // 批量归还减少自旋锁争用
}

sequenceDiagram
    participant App as 用户态媒体服务器
    participant Kernel as 内核协议栈
    participant NIC as 智能网卡
    App->>Kernel: 1. 完成 TCP 三次握手 (io_uring ACCEPT)
    App->>Kernel: 2. 发起 TLS 握手 (用户态 OpenSSL/BoringSSL)
    Kernel-->>App: 3. 返回 Session Keys (SSL_get_session)
    App->>Kernel: 4. setsockopt(TCP_ULP, "tls") + TLS_TX/RX 密钥下发
    Kernel->>NIC: 5. 编程加密引擎 (Offload 模式)
    Note right of App: 后续收发仅需 io_uring PREP_READ/WRITE/Splice<br/>数据不再进入用户态地址空间

// Worker 线程主循环
while (running) {
    // 1. 批量获取 CQE (非阻塞)
    unsigned head = *ring->cq.khead;
    unsigned tail = *ring->cq.ktail;
    int batch = min(tail - head, MAX_BATCH);
    
    // 2. 分类分发 (O(1) 哈希分桶)
    for (int i = 0; i < batch; i++) {
        struct io_uring_cqe *cqe = &ring->cq.cqes[(head + i) & ring->cq.ring_mask];
        uint64_t udata = cqe->user_data;
        enum req_type type = decode_type(udata);
        uint32_t conn_id = decode_conn(udata);
        
        // 关键：按类型分发至不同处理队列，避免大包挤占小包
        switch (type) {
            case REQ_ACCEPT:      enqueue_fast_path(conn_id, cqe); break;   // 高优
            case REQ_RECV_SIGNAL: enqueue_fast_path(conn_id, cqe); break;   // 高优
            case REQ_SPLICE_DATA: enqueue_data_path(conn_id, cqe); break;   // 批量
            case REQ_SEND_ZC:     enqueue_zc_complete(conn_id, cqe); break; // 回收 skb
            case REQ_TIMER:       enqueue_timer_wheel(cqe); break;          // 低优
        }
    }
    io_uring_cq_advance(ring, batch);

    // 3. 执行时间片调度 (类 CFS)
    run_fast_path(MAX_FAST_US);   // 严格限制 50us
    run_data_path(MAX_DATA_US);   // 200us
    run_background();             // 定时器/GC
}

graph LR
    A[Old Master] -- 1. 监听 FD + 连接 FD + io_uring 注册上下文 --> B[Unix Domain Socket SCM_RIGHTS]
    B --> C[New Master]
    C --> D[New Worker 进程组]
    D --> E[接管 io_uring 实例<br/>恢复 SQ/CQ 状态]

// 用户态 TCP 栈发包路径
// 1. 构造 TCP 段 -> 填充 AF_XDP TX Ring (UMEM)
// 2. 通知网卡驱动发送 (poll TX queue)
// 3. 完成回收 -> 归还 UMEM Frame

// io_uring 仅用于：本地管道/文件读写、定时器、信号量、跨 NUMA 内存搬运
// 避免 AF_XDP 与 Kernel Stack 争抢同一网卡 RX 队列：配置 RSS 规则
//   - 直播端口范围 -> Queue Group A (AF_XDP 绑定)
//   - 点播/管理端口 -> Queue Group B (Kernel Stack + io_uring)

# 1. 采集调用栈 (高频 99Hz, 持续 30s)
perf record -F 99 -g --call-graph dwarf -p $(pidof media_server) -o perf.data -- sleep 30

# 2. 生成火焰图
perf script -i perf.data | ./stackcollapse-perf.pl | ./flamegraph.pl --title "Media Server CPU" > flame.svg

# 3. 重点排查热点
#   - __io_uring_submit_sqes / io_uring_enter  -> SQ 太小或 SQPOLL 未生效
#   - copy_user_enhanced_fast_string           -> 仍有用户态拷贝，检查 splice/send_zc 覆盖率
#   - tls_encrypt_record / tls_decrypt_record  -> KTLS 未生效或未卸载
#   - slab_alloc / kmem_cache_alloc            -> 内存池命中率低，扩容 L1 Slab
#   - schedule / __schedule                    -> Worker 线程过多或锁竞争，检查绑核与无锁队列

# INC-20240520-001: 核心转发集群 P99 延迟突增 10x

## 1. 影响范围
- 时间: 2024-05-20 14:03 ~ 14:27 (24min)
- 集群: media-edge-sh-01 (32 节点)
- 影响: 直播拉流卡顿率 12%，约 45 万用户受影响
- SLA 违背: 可用性 99.95% -> 99.72%

## 2. 时间线 (关键节点)
- 14:03: 监控告警 `media_server_p99_latency > 50ms`
- 14:05: On-call 登录跳板机，`top` 发现 `ksoftirqd/11` 占用 100%
- 14:08: `perf top` 定位 `mlx5e_poll_tx_cq` 热点
- 14:12: 确认为新版驱动 5.19.0-1025 引入 TX 完成轮询回归
- 14:15: 执行滚动重启降级驱动至 5.19.0-1020
- 14:27: 指标恢复，解除告警

## 3. 根因分析 (5 Whys)
1. **现象**: TX 完成队列处理延迟飙升
2. **原因**: 网卡驱动 `mlx5e_completion_event` 处理逻辑变更，引入自旋锁竞争
3. **原因**: 驱动升级未在 Staging 环境跑长稳压测 (仅跑功能测试)
4. **原因**: 变更管理流程缺失“性能基线对比”强制门禁
5. **根因**: **发布流程缺乏性能回归测试 Gate**

## 4. 修正措施 (Action Items)
- [ ] P0: 纳入 `mlx5` 驱动版本至 CMDB 受控清单，禁止自动更新 (Owner: SRE, Due: 05/25)
- [ ] P0: CI/CD 增加 `perf bench` 性能基线对比 Job，波动 > 5% 阻断合并 (Owner: Platform, Due: 06/15)
- [ ] P1: 开发 `bpftrace` 单行脚本一键采集 `ksoftirqd` 热点，缩短 MTTR (Owner: Kernel Team, Due: 05/30)
- [ ] P1: 完善 `io_uring` SQ/CQ 延迟 SLO 仪表盘，增加驱动级指标 (Owner: Observability, Due: 06/10)

## 5. 经验沉淀
- 更新《网卡驱动升级运维手册》v2.1
- 新增混沌工程场景：`tc qdisc` 模拟网卡 TX 拥塞