架构与探针开发 ​

本页面面向开发者，提供了 ecapture 核心 TLS 捕获模块（tls、gotls 和 gnutls）的高层架构概览，包括其生命周期管理、事件/输出流水线以及扩展模式。

有关深层技术细节、实现和 ABI 规范，请参阅专用的子页面：

• TLS 捕获架构
• 探针框架与生命周期
• 事件与输出流水线
• 扩展 TLS 探针

5.1. TLS 捕获架构 ​

ecapture 代理通过将 eBPF 程序（uprobes、uretprobes 和 TC hooks）挂载到目标二进制文件或共享库，实现对 OpenSSL/BoringSSL (tls)、Go 原生 TLS (gotls) 和 GnuTLS (gnutls) 的流量捕获。该架构负责解析符号和库路径，提取有效负载或密钥材料，并通过 perf buffer 或 ring buffer 将内核态字节结构转换为用户态事件。

共享的运行时流程连接了命令执行、工厂创建、管理器设置和事件解码，如下图所示：

有关 eBPF 挂载、符号解析和 C/Go 事件 ABI 的全面细节，请参阅 TLS 捕获架构。

Sources: main.go, internal/probe/openssl/openssl_probe.go:61-163, internal/probe/gotls/gotls_probe.go:70-156, internal/probe/gnutls/gnutls_probe.go:48-116

5.2. 探针框架与生命周期 ​

具体的探针（openssl.Probe、gotls.Probe 和 gnutls.Probe）嵌入了 base.BaseProbe internal/probe/openssl/openssl_probe.go:46-47，以继承共享的日志记录、分发器管理、读取器跟踪和停机编排。工厂注册在包初始化期间通过 Go 的 init() 函数进行，将 CLI 命令直接链接到探针构造函数。

生命周期遵循严格的顺序：配置验证、初始化、通过 assets.Asset() 进行字节码选择和资源加载 internal/probe/openssl/openssl_probe.go:126-129、eBPF 管理器初始化与挂载、事件映射获取以及读取器执行。在卸载期间，资源将按相反顺序安全释放。

有关工厂注册、BaseProbe 生命周期钩子、读取器跟踪和并发管理的细节，请参阅 探针框架与生命周期。

Sources: internal/probe/openssl/openssl_probe.go:46-209, internal/probe/gotls/gotls_probe.go:53-211, internal/probe/gnutls/gnutls_probe.go:39-167

5.3. 事件与输出流水线 ​

捕获的二进制事件从 eBPF perf/ring-buffer 读取器流经 EventDecoder.Decode() 进入 events.Dispatcher。分发器向与所选输出模式（text、keylog 或 pcapng）对应的已注册处理器执行同步扇出。

解耦的输出架构将记录路由到 ByteSink 目标（stdout、文件、TCP 流或二进制 WebSockets），同时通过 eCaptureQ 独立发布类型化元数据：

有关事件解码、分发器机制、ByteSink 传输和 eCaptureQ 发布细节，请参阅 事件与输出流水线。

Sources: docs/agent/output-pipeline.md, internal/output/writers/factory.go:77-176

5.4. 扩展 TLS 探针 ​

扩展现有的核心 TLS 模块或引入新功能，需要保持 C eBPF 源码定义、ebpfmanager 映射、全局常量和 Go 解码逻辑之间的原子级对齐。开发者必须保留 CO-RE (_core.o) 和 non-CO-RE (_noncore.o) 资源路径，以及特定架构的构建标签 (linux,netgo,ebpfassets,dynamic)。

在修改或添加探针功能时，确保验证规则保持幂等性，并且特定模式的处理器遵循捕获的有效负载与运行日志之间的分离原则。

有关扩展 tls、gotls 或 gnutls 的分步指南，请参阅 扩展 TLS 探针。

Sources: AGENTS.md, docs/agent/probe-development.md, internal/probe/openssl/openssl_probe.go:44-163