模块系统与生命周期 ​

本文档解释了 eCapture 的模块系统架构，包括 IModule 接口规范、模块注册模式，以及从初始化到关闭的完整生命周期。所有捕获模块（TLS、Bash、MySQL 等）都实现了 IModule 接口并遵循标准生命周期：Init → Start → Run → Close。

关于模块如何配置自身的详细信息，请参阅第 2.4 节（配置系统）。关于模块内 eBPF 程序加载的信息，请参阅第 2.1 节（eBPF 引擎）。关于捕获后的事件处理，请参阅第 2.2 节（事件处理流程）。

IModule 接口规范 ​

IModule 接口定义了所有模块必须实现的标准规范。该接口支持整个系统中的多态模块处理，允许 CLI 和 HTTP API 以统一方式实例化和管理不同的捕获类型（TLS、Bash、MySQL 等）。

核心接口定义

IModule 接口在 user/module/imodule.go:47-75 中定义，并规定了所有模块必须实现的契约：

来源： user/module/imodule.go:47-75

图示：IModule 接口和类层次结构

父子模式允许基础 Module 结构提供通用功能（通过 autoDetectBTF() 进行 BTF 检测，通过 perfEventReader() 和 ringbufEventReader() 读取事件，通过 run() 进行上下文管理），同时通过存储在 Module 中的 child 字段将模块特定操作（通过 Start() 设置 eBPF 程序，通过 DecodeFun() 解码事件）委托给具体实现。

来源： user/module/imodule.go:83-108，user/module/probe_openssl.go:83-106

模块注册与工厂模式 ​

eCapture 使用工厂模式进行模块实例化，根据 CLI 命令动态加载模块。每个模块在包初始化期间注册一个工厂函数。

注册机制

图示：模块注册和工厂模式流程

每个模块在 Go 包初始化期间注册一个工厂函数。当 CLI 调用命令（例如 ecapture tls）时，runModule() 函数在 moduleRegistry 中查找工厂并创建实例。

来源： user/module/probe_openssl.go:785-794，cli/cmd/root.go:344-347

模块名称常量和 CLI 映射

每个模块由模块源文件中定义的唯一字符串常量标识。这些常量用作 moduleRegistry 映射的键。

CLI 命令到 runModule() 调用：

• ecapture tls → openSSLCommandFunc() cli/cmd/tls.go:62 → runModule(module.ModuleNameOpenssl, oc) cli/cmd/tls.go:66
• ecapture gotls → goTLSCommandFunc() cli/cmd/gotls.go:52 → runModule(module.ModuleNameGotls, goc) cli/cmd/gotls.go:57
• ecapture bash → bashCommandFunc() cli/cmd/bash.go:53 → runModule(module.ModuleNameBash, bc) cli/cmd/bash.go:54
• ecapture mysqld → mysqldCommandFunc() cli/cmd/mysqld.go:47 → runModule(module.ModuleNameMysqld, myc) cli/cmd/mysqld.go:48

来源： cli/cmd/tls.go:62-67，cli/cmd/gotls.go:52-58，cli/cmd/bash.go:53-55，cli/cmd/mysqld.go:47-49

模块生命周期阶段 ​

模块生命周期由五个不同的阶段组成，每个阶段都有特定的职责。模块按顺序经过这些阶段，在每个转换点都有错误处理。

图示：带代码引用的模块生命周期状态机

来源： cli/cmd/root.go:336-397，user/module/imodule.go:110-171，user/module/imodule.go:236-262，user/module/probe_openssl.go:109-176，user/module/probe_openssl.go:280-350，user/module/probe_openssl.go:352-358

初始化阶段（Init） ​

Init() 方法由 cli/cmd/root.go:352 中的 runModule() 调用，执行依赖注入和环境设置。

Module.Init() 基础职责（user/module/imodule.go:111-171）：

BTF 自动检测逻辑（user/module/imodule.go:173-190）：

func (m *Module) autoDetectBTF() {
    isContainer, err := ebpfenv.IsContainer()
    if isContainer {
        m.logger.Warn().Msg("检测到容器，BTF 自动检测可能失败")
    }
    enable, e := ebpfenv.IsEnableBTF()
    if enable {
        m.isCoreUsed = true  // 使用 CO-RE 字节码（_core.o）
    }
}

模块特定的 Init 扩展

具体模块调用 m.Module.Init()，然后添加自己的设置。来自 MOpenSSLProbe.Init() 的示例 user/module/probe_openssl.go:109-176：

来源： user/module/imodule.go:110-171，user/module/probe_openssl.go:109-176，cli/cmd/root.go:352

Start 阶段 ​

Start() 方法由 user/module/imodule.go:239 中的 Module.Run() 调用，将 eBPF 程序加载到内核中。

MOpenSSLProbe.Start() 流程（user/module/probe_openssl.go:280-350）

图示：MOpenSSLProbe 的 Start 阶段序列

按捕获模式的管理器设置：

eBPF 程序的常量编辑（user/module/probe_openssl.go:361-395）

constantEditor() 方法将运行时值注入 eBPF 全局变量：

来源： user/module/probe_openssl.go:280-350，user/module/probe_openssl.go:361-395，user/module/imodule.go:239

Run 阶段 ​

Run() 方法由 cli/cmd/root.go:358 中的 runModule() 调用，启动用于事件处理的并发协程。

Run 阶段架构

图示：带代码引用的 Run 阶段协程架构

事件读取器实现细节

user/module/imodule.go:285-306 中的 readEvents() 方法遍历 child.Events() 返回的所有 eBPF 映射，并根据映射类型创建适当的读取器：

Perf Event Array 读取器（user/module/imodule.go:308-351）

Ring Buffer 读取器（user/module/imodule.go:353-391）

类似的流程，但在 imodule.go:354 处使用 ringbuf.NewReader(em) 而不是 perf 读取器。在较新的内核（5.8+）上，Ring Buffer 因其更好的性能而优先使用。

来源： user/module/imodule.go:236-262，user/module/imodule.go:285-391，cli/cmd/root.go:358

Stop 和清理阶段 ​

Close() 方法由 cli/cmd/root.go:387 中的 runModule() 在关闭期间调用，按初始化的相反顺序执行资源清理。

清理序列

图示：模块清理序列

MOpenSSLProbe.Close() 实现（user/module/probe_openssl.go:352-358）

func (m *MOpenSSLProbe) Close() error {
    m.logger.Info().Msg("module close.")
    if err := m.bpfManager.Stop(manager.CleanAll); err != nil {
        return fmt.Errorf("couldn't stop manager %w .", err)
    }
    return m.Module.Close()  // 委托给父类
}

Module.Close() 实现（user/module/imodule.go:450-460）

额外的模块特定清理

某些模块在调用 Module.Close() 之前执行额外的清理：

• MOpenSSLProbe：如果在 keylog 模式下，关闭 keylogger 文件句柄
• MTCProbe（MOpenSSLProbe 的父类）：关闭 pcapng 写入器，刷新 DSB（解密密钥块）
• 连接跟踪映射（pidConns、sock2pidFd）被垃圾回收

来源： user/module/imodule.go:450-460，user/module/probe_openssl.go:352-358，cli/cmd/root.go:387

基础 Module 实现 ​

user/module/imodule.go:83-108 处的 Module 结构实现了所有捕获模块使用的通用操作：

Module 基类中的共享功能

父子委托模式

Module 基类使用组合和委托来共享通用代码，同时允许模块特定的自定义。child IModule 字段存储对具体模块（例如 MOpenSSLProbe）的引用。

委托的工作原理

图示：Decode 和 Dispatcher 的委托流程

SetChild 注册模式

每个具体模块在初始化期间调用 SetChild(m) 来注册自身：

来自 MOpenSSLProbe.Init() 的示例（user/module/probe_openssl.go:109-176）

func (m *MOpenSSLProbe) Init(ctx context.Context, logger *zerolog.Logger, 
                             conf config.IConfig, ecw io.Writer) error {
    // 1. 首先调用父类 Init
    err = m.Module.Init(ctx, logger, conf, ecw)
    if err != nil {
        return err
    }
    
    // 2. 注册自身为子模块以进行委托
    m.Module.SetChild(m)  // 第 116 行
    
    // 3. 模块特定的初始化
    m.eventMaps = make([]*ebpf.Map, 0, 2)
    m.eventFuncMaps = make(map[*ebpf.Map]event.IEventStruct)
    m.pidConns = make(map[uint32]map[uint32]ConnInfo)
    // ... 更多设置
}

此模式允许父类 Module 回调子类的方法，如 Start()、Events()、DecodeFun() 和 Dispatcher()。

来源： user/module/imodule.go:393-406，user/module/imodule.go:408-448，user/module/probe_openssl.go:109-176

模块配置集成 ​

模块通过 IConfig 接口接收配置，允许运行时行为自定义。每个模块类型都有相应的配置结构。

配置到模块的映射：

全局配置应用：

cli/cmd/root.go:156-175 将全局设置应用于模块配置：

func setModConfig(globalConf config.BaseConfig, modConf config.IConfig) {
    modConf.SetPid(globalConf.Pid)
    modConf.SetUid(globalConf.Uid)
    modConf.SetDebug(globalConf.Debug)
    modConf.SetHex(globalConf.IsHex)
    modConf.SetBTF(globalConf.BtfMode)
    modConf.SetPerCpuMapSize(globalConf.PerCpuMapSize)
    modConf.SetTruncateSize(globalConf.TruncateSize)
    ...
}

运行时配置更新：

HTTP 服务器通过 POST /config 支持运行时配置重新加载 cli/cmd/root.go:375-396：

1. 在 reRloadConfig 通道上接收新配置
2. 调用 mod.Close() 停止当前模块
3. goto reload 跳回初始化
4. 应用新配置并重新启动模块

来源： cli/cmd/root.go:156-175，cli/cmd/root.go:336-397，user/config/iconfig.go:24-70

事件分发和处理 ​

Dispatcher() 方法根据事件类型将解码的事件路由到适当的处理程序。这实现了三路路由策略。

图示：事件分发路由逻辑

事件类型类别：

user/module/imodule.go:408-448 按类型路由事件：

• TypeOutput：准备显示的最终格式化事件 → eventCollector.Write()
• TypeEventProcessor：需要聚合/解析的事件 → processor.Write()
• TypeModuleData：模块特定数据（连接、主密钥） → child.Dispatcher()

模块特定的 Dispatcher 实现

每个具体模块实现 Dispatcher() 来处理其特定的事件类型。基础 Module.Dispatcher() 为 TypeModuleData 事件调用 child.Dispatcher()。

MOpenSSLProbe.Dispatcher() 实现（user/module/probe_openssl.go:741-762）

func (m *MOpenSSLProbe) Dispatcher(eventStruct event.IEventStruct) {
    switch ev := eventStruct.(type) {
    case *event.ConnDataEvent:
        if ev.IsDestroy == 0 {
            m.AddConn(ev.Pid, ev.Fd, ev.Tuple, ev.Sock)
        } else {
            m.DelConn(ev.Sock)
        }
    case *event.MasterSecretEvent:
        m.saveMasterSecret(ev)
    case *event.MasterSecretBSSLEvent:
        m.saveMasterSecretBSSL(ev)
    case *event.TcSkbEvent:
        err := m.dumpTcSkb(ev)
        if err != nil {
            m.logger.Error().Err(err).Msg("save packet error.")
        }
    case *event.SSLDataEvent:
        m.dumpSslData(ev)
    }
}

MOpenSSLProbe 的事件类型处理程序映射：

连接跟踪方法：

• AddConn(pid, fd, tuple, sock) probe_openssl.go:406-424：存储 (pid, fd) → (tuple, sock) 的映射
• GetConn(pid, fd) probe_openssl.go:472-488：检索套接字 FD 的连接信息
• DelConn(sock) probe_openssl.go:463-470：安排延迟删除（3 秒延迟）
• DestroyConn(sock) probe_openssl.go:426-460：立即从映射中删除连接

来源： user/module/imodule.go:408-448，user/module/probe_openssl.go:741-762，user/module/probe_openssl.go:406-488

完整系统集成流程 ​

此序列图展示了从 CLI 命令执行到模块初始化、eBPF 程序附加、事件捕获和清理的完整生命周期。

图示：从 CLI 到内核的完整模块集成序列

关键集成点：

来源： cli/cmd/root.go:249-403，cli/cmd/tls.go:62-67，user/module/imodule.go:236-262，user/module/probe_openssl.go:280-350

模块列表和功能 ​

下表总结了所有可用模块及其关键特性：

来源： user/module/ 目录中的模块文件