qtap:基于 eBPF 的 Linux 内核流量捕获代理项目

---

一款通过 Linux 内核捕获流量的 eBPF 代理。它通过挂载到 TLS/SSL 函数，在数据加密前后进行拦截，然后将完整可见的原始数据及所有可用上下文（进程/容器/主机/用户/协议等信息）传递给灵活的插件系统。Qtap 让您无需修改应用、部署代理或管理证书，即可全面掌握出口流量动态。

Qtap 以带外方式运行，仅产生极小开销，不会增加延迟或影响应用性能，同时能完整呈现发送和接收的原始未加密数据。

Qtap 能够增强您现有的可观测性管道，也可作为自定义解决方案（如 Qpoint）的基础组件，应用场景包括：

• 安全审计 - 安全人员可验证敏感数据是否在网络通信中被意外泄露。
• 网络问题调试 - 当 API 返回错误或连接失败时，查看实际发送的数据有助于识别配置错误的参数、格式错误的请求或意外响应。
• API 开发 - 开发人员无需修改代码，即可验证应用程序是否发送格式正确的请求并正确处理响应。
• 第三方集成排查 - 与外部服务集成时，Qtap 帮助确认实际交换的数据与文档声明是否一致。
• 学习与探索 - 通过观察应用程序与服务之间的真实流量，了解协议的实际工作方式。
• 遗留系统调查 - 处理文档不全或遗留系统时，Qtap 无需源代码访问即可提供其通信方式的洞察。
• 验证测试 - 确认应用程序变更不会意外改变网络通信模式。

更多信息，请参见我们网站的「工作原理」部分。

快速开始

想要试用 Qtap 吗？在演示模式下启动一个临时实例即可！您可以在终端中实时查看流量。

# Run Qtap in demo mode
$ curl -s https://get.qpoint.io/demo | sudo sh

或者立即安装并开始运行！

# Install the Qtap agent
$ curl -s https://get.qpoint.io/install | sudo sh

# Run with defaults!
$ sudo qtap

开发工具（DevTools）

Qtap 内置了开发工具界面（位于 pkg/devtools/app），它提供了类似 Chrome DevTools 的网络标签页，用于监控单个 Linux 节点上的进程和流量。该界面支持实时监控 HTTP 事务、网络连接和进程，并具备过滤、搜索和详细检查功能。更多详情请参见 开发工具 README 和 开发工具文档。

社区

可在 Github Discussions 与 Qpoint 开发人员和贡献者交流。

要求

• Linux 系统，内核版本 5.10 及以上，并已启用 BPF 类型格式（BTF）。您可以通过检查系统上是否存在 /sys/kernel/btf/vmlinux 文件来验证内核是否已启用 BTF。
• 主机已启用 eBPF。
• 在主机上或运行代理的 Docker 容器内拥有提升的权限：
  • 在主机上使用 sudo 运行
  • 在 Docker 中，最佳做法是使用 CAP_BPF 权限、主机 PID 以及特权模式运行。例如：

  docker run \
      --user 0:0 \
      --privileged \
      --cap-add CAP_BPF \
      --cap-add CAP_SYS_ADMIN \
      --pid=host \
      --network=host \
      -v /sys:/sys \
      --ulimit=memlock=-1 \
      us-docker.pkg.dev/qpoint-edge/public/qpoint:v0 \
      tap \
      --log-level=info
  

开发

先决条件

操作系统

• Linux（内核 5.10+）
  • Qpoint 的 macOS 开发人员喜欢使用 Lima 作为快速、简便的 Linux 虚拟机进行开发。

工具：

• go1.24+
• make
• clang14（需版本 14）
• clang-tidy（可选/推荐）

快速开始

$ git clone https://github.com/qpoint-io/qtap.git
$ make build

常用 Makefile 目标

以下是 Qpoint 开发人员最常使用的目标：

• build - 生成 eBPF 二进制文件并构建 Go 应用程序
• generate - 生成 eBPF 二进制文件
• run - 运行 Qtap 的调试实例
• ci - 运行所有 ci 检查（推送代码前使用为宜）

遥测

追踪

可通过按照 OpenTelemetry 文档 [1] [2] 设置 OTEL_TRACES_EXPORTER 和 OTEL_EXPORTER_OTLP_PROTOCOL 环境变量来启用追踪。

指标

我们在 localhost:10001 上提供两个指标端点：

• /metrics 包含可用于创建仪表板以监控系统活动的指标
• /system/metrics 包含与 qtap 代理健康状况相关的指标

我们提供了一个示例 Grafana 仪表板：examples/dashboards/qtap-http-overview.json。

项目状态

本项目目前处于早期开发阶段。我们很高兴能与社区分享我们的工作，并欢迎您的反馈！尽管我们正在积极改进，但请注意：

• 随着我们完善方法，部分 API 可能会发生变化
• 某些地方的文档可能尚不完整
• 可能还存在一些未解决的问题

我们欢迎通过 GitHub issues 提交贡献，并感谢您理解我们是一个需要平衡多个优先事项的小团队。我们珍视有助于改进本项目的建设性反馈。

感谢您关注我们的工作！

贡献

通过向本项目提交贡献，您同意 贡献者许可协议。本协议允许我们将您的贡献包含在开源版本和商业版本中。

许可

本项目采用双重许可：AGPLv3.0（用于开源用途）和商业许可（用于商业用途）。