DeepFlow Agent 故障排查指南：注册失败、协议解析、资源识别与配置方式

目录

• [1. 前言](#1. 前言)
• [2. 部署问题排查](#2. 部署问题排查)
• [3. 通用排查案例](#3. 通用排查案例)
• [4. 其余常见问题](#4. 其余常见问题)

---

1. 前言

1.1 适用范围

本文档适用于 DeepFlow Agent v6.5 及以上版本。

1.2 运行权限及内核要求

确保环境满足运行权限及内核要求。

1.3 排查前检查

检查项	要求
版本	Agent/Server 为 LTS 版本，且 Agent ≤ Server 版本
部署方式	主机进程部署 或 K8s Pod 部署
工具	已安装与 Server 同版本的 deepflow-ctl
等待时间	Agent 部署后等待 5 分钟以上再排查（初始化需要时间）
网段	Agent IP 在 Server 的 local_ip_ranges 网段内

---

2. 部署问题排查

2.1 主机进程部署

主机进程部署通过 deepflow-agent 二进制直接运行在主机上，默认使用 38086 端口。

Agent 注册失败排查

按以下顺序检查：

1. [检查 Domain 与 Agent Group Config 配置](#检查 Domain 与 Agent Group Config 配置)
2. [检查 Server 网段配置](#检查 Server 网段配置)
3. 检查主机名是否重名
4. [检查是否通过 LB 连接 Server](#检查是否通过 LB 连接 Server)

---

2.1.1 检查 Domain 与 Agent Group Config 配置

主机进程部署需要完成两个步骤：

1. 创建 Host Domain（类型为 agent_sync）
2. 创建 Agent Group Config（采集器组配置）

这两个步骤缺一不可。agent_sync 类型 Domain 只能创建一个，多了会导致注册异常。

排查步骤：

1. 检查 Host Domain 是否已创建：

# 确认列表中存在类型为 agent_sync 的 Domain
deepflow-ctl domain list

2. 检查 Agent Group Config 是否已创建：

deepflow-ctl agent-group-config list

解决方案：

如果缺少 Host Domain：

unset DOMAIN_NAME
DOMAIN_NAME="legacy-host" # 修改为实际的 domain 名称

cat << EOF | deepflow-ctl domain create -f -
name: $DOMAIN_NAME
type: agent_sync
EOF

Domain 用于让 deepflow-agent 以自同步方式将服务器网络信息发送至 deepflow-server，类似于监控 K8s 集群时创建 K8s Domain。

如果缺少 Agent Group Config，通过 deepflow-ctl 创建：

inputs:
  resources:
    workload_resource_sync_enabled: true

采集器组配置用于在无法通过云平台 API 同步资源的场景下，同步物理服务器或虚拟机的资源信息。

注意事项：

• Domain 只需创建一个，创建多个会导致 Agent 注册异常
• 两步操作缺一不可

---

2.1.2 检查 Server 网段配置

DeepFlow Server 通过 local_ip_ranges 配置识别局域网网段。如果 Agent 的 IP 不在该配置范围内，会导致：

1. Agent 无法正常注册
2. 某些 IP 在 metrics 中被聚合为 0.0.0.0（广域网 IP）

排查步骤：

1. 获取 Agent 的 IP 地址
2. 检查 Server 配置中的 local_ip_ranges：

# kubectl edit cm -n deepflow deepflow
# 默认配置：
local_ip_ranges:
  - 10.0.0.0/8
  - 172.16.0.0/12
  - 192.168.0.0/16
  - 169.254.0.0/15
  - 224.0.0.0-240.255.255.255

确认 Agent IP 是否在配置的网段范围内。

解决方案：

更新 Server 配置，将 Agent 所在网段添加到 local_ip_ranges：

更新 Server 配置文档

关于 0.0.0.0 广域网 IP

在 DeepFlow 中，0.0.0.0 代表广域网 IP。当 IP 不在 local_ip_ranges 中时：

数据类型	IP 展示	说明
Metrics	0.0.0.0	聚合为广域网 IP
Request Log	真实 IP	保留原始 IP

判断方法：在 Request Log 面板中通过 is_internet tag 判断，值为 true 时是广域网。

如果需要在 Metrics 中也展示真实 IP，将对应网段添加到 Server 的 local_ip_ranges 配置中。

网卡内/外网类型判断规则

网卡配置	子网类型判断
单个网卡仅有单个 IP，且未包含在 local_ip_ranges 中	自动识别为外网
单个网卡有多个 IP，任意 1 个 IP（含 IPv4、IPv6）未包含在 local_ip_ranges 中	自动识别为外网

如果发现网卡的子网类型识别错误，检查该网卡的所有 IP 是否都在 local_ip_ranges 配置范围内。

---

2.1.3 检查主机名是否重名

多台主机使用相同的主机名会导致注册失败。

排查步骤：

确认环境中是否存在重名主机。

解决方案：

方式一（推荐）：修改 DeepFlow Agent 配置

编辑 Agent 注册配置（默认路径 /etc/deepflow-agent/deepflow-agent.yaml）：

# Agent 注册时使用自定义名称上报
# https://github.com/deepflowio/deepflow/blob/main/agent/config/deepflow-agent.yaml#L35
override-os-hostname: "unique-hostname-001"

重启 Agent 后生效。

方式二：修改系统主机名

hostnamectl set-hostname unique-hostname-001

不推荐直接修改主机名，可能影响其他依赖主机名的应用。通过配置覆盖更灵活。

---

2.1.4 检查是否通过 LB 连接 Server

如果 Agent 通过负载均衡器（LB）连接 Server，可能导致注册失败。详见：

[3.1 通过 LB 连接 Server 导致的注册失败](#3.1 通过 LB 连接 Server 导致的注册失败)

---

2.2 K8s Pod 部署

K8s 部署通过 Helm Chart 安装 deepflow-agent 到集群中，默认以 DaemonSet 形式运行在每个节点上。

Agent 注册失败排查

2.2.1 检查 Pod 运行时间与初始化状态

DeepFlow 部署包含多个组件（Server、Agent、Database 等），首次部署需要较长的初始化时间：

• 数据库初始化
• Server 初始化
• Agent 连接 Server 完成注册

排查步骤：

1. 确认所有 Pod 状态正常：

kubectl get pods -n deepflow

所有 Pod 应处于 Running 状态。

2. 等待 5-6 分钟后检查 Agent 注册状态：

deepflow-ctl agent list

在 K8s 部署中，Agent Pod 的 ConfigMap 中 Server 地址配置为 Server Service Name。由于 Server 和 Agent 在同一集群内，网络连通性一般不会有问题。注册未完成通常是因为初始化未完成，等待即可。

3. 如果等待 5 分钟后仍未注册成功，尝试重启 Agent Pod：

kubectl delete pods -n deepflow -l app=deepflow-agent

注意事项：

• 确保 Agent 能够匹配到网卡的 interface_regex 配置，否则无法采集数据
• 网卡匹配正则配置参考

---

2.2.2 检查是否通过 LB 连接 Server

如果 Agent 通过负载均衡器（LB）连接 Server，可能导致注册失败。详见：

[3.1 通过 LB 连接 Server 导致的注册失败](#3.1 通过 LB 连接 Server 导致的注册失败)

---

数据同步问题排查

2.2.3 检查 K8s 集群资源同步

DeepFlow 对 K8s 资源的展示有特定规则，某些场景下资源会被过滤掉。

1. 当前资源没有请求/响应流量

DeepFlow 认为没有流量的资源没有展示意义。如果某个 Pod 从未接收或发送过请求，该资源可能不会在数据中展示。

排查方法：

• 检查该资源是否有业务流量
• 尝试发送测试请求到该资源

2. 没有上层/下层资源关联

DeepFlow 依赖资源的上下层关系进行展示，孤立资源可能被过滤：

资源类型	不展示的情况
Namespace	该 Namespace 下没有任何 Pod
Service	Service 没有关联任何 Pod
Pod	Pod 没有上层资源（如 Deployment、DaemonSet、StatefulSet），仅为单独的 Pod

DeepFlow 认为没有完整上下层关系的资源没有展示意义。

排查方法：

• 检查资源是否有关联的上下层资源
• 确认 Pod 是否通过控制器（Deployment/DS/STS）创建

3. 资源不是 K8s 原生资源

如果资源是通过自定义 Operator 创建的（非 K8s 原生 Kind），DeepFlow 可能无法正确识别其上层资源关系。

示例：kube-prometheus 项目中的 Prometheus Pod，其上层 Kind 为 Prometheus（自定义 CRD），而非 K8s 原生的 Deployment/StatefulSet。

排查方法：

• 检查资源的 ownerReferences 字段，确认是否为 K8s 原生资源
• 如果是自定义 CRD，目前 DeepFlow 无法识别

K8s 资源不展示的常见原因

原因	说明	解决方案
没有流量	资源从未有请求/响应	发送测试流量
没有上下层关系	孤立资源（单独的 Pod、未关联 Pod 的 Service 等）	确保资源有完整的层级关系
非原生资源	通过自定义 Operator 创建	目前可能无法完美支持

---

3. 通用排查案例

3.1 通过 LB 连接 Server 导致的注册失败

默认 server 会下发自己的节点 IP 给 agent 作为控制/数据面通信 IP。

当 Agent 无法直接连接 Server，必须通过 LB 时，需要配置以下四个参数：

参数	说明	文档链接
proxy_controller_ip	用于设置 agent 与 server 通信的控制面通信 IP	配置文档
proxy_controller_port	对应的端口号	配置文档
ingester_ip	用于设置 agent 与 server 通信的数据面通信 IP	配置文档
ingester_port	对应的端口号	配置文档

配置示例：

在 agent-group-config 中添加：

global:
  communication:
    proxy_controller_ip: "10.0.0.100"  # LB IP
    proxy_controller_port: 30035
    ingester_ip: "10.0.0.100"
    ingester_port: 30033

---

3.2 缺少协议数据

DeepFlow 支持多种应用层协议解析，但 v6.5 版本后，为了降低资源开销，Agent 默认仅解析以下协议：

• HTTP
• HTTP2/gRPC
• MySQL
• Redis
• Kafka
• DNS
• TLS

其他协议需要手动启用，例如：PostgreSQL、MongoDB、RabbitMQ 等。

开源版不支持 Oracle 协议。

完整协议支持列表

解决方案：

如果需要解析其他协议，通过 deepflow-ctl 添加：

在配置中添加需要启用的协议：

processors:
  request_log:
    application_protocol_inference:
      enabled_protocols:
        - HTTP
        - HTTP2
        - MySQL
        - Redis
        - Kafka
        - DNS
        - TLS
        - PostgreSQL    # 手动添加

---

3.3 eBPF 加载失败

典型错误日志：

[eBPF] WARN func load_obj__progs() [user/load.c:546] bcc_prog_load() failed. name: df_T_exit_write, Invalid argument errno: 22
[eBPF] WARN func ebpf_obj_load() [user/load.c:854] eBPF load programs failed. (errno 22)
[eBPF] INFO release object ("socket-trace-bpf-linux-common") ...
[eBPF] INFO release object done
[eBPF] WARN func tracer_bpf_load() [user/tracer.c:525] bpf load "socket-trace-bpf-linux-common" failed, error:Invalid argument (22).
[src/trident.rs:2339] ebpf collector error: EbpfRunningError

eBPF 加载失败是因为 DeepFlow 对当前使用的系统或内核版本不适配。

解决方案：

情况一：使用通用操作系统

如果你使用的是通用操作系统（Ubuntu、CentOS、Debian、Fedora 等），按以下步骤收集信息并反馈给社区：

1. 查看内核版本：

uname -a
hostnamectl

2. 运行内核结构偏移量检查工具：

使用 show-kernel-struct-offset 项目：

# 下载并编译工具
git clone https://github.com/deepflowio/show-kernel-struct-offset.git
cd show-kernel-struct-offset
make

3. 将结果发送到 DeepFlow 社区：

• 在 GitHub Issues 中提交
• 或发送到 DeepFlow 开源社区群

社区会根据提供的信息适配对应的内核版本。

情况二：使用自定义系统或内核

如果你使用的是自定义操作系统或内核，需要自行适配：

参考 PR 示例：自定义内核适配示例

前提条件检查：

在排查 eBPF 问题时，先确认环境满足要求：

运行权限及内核要求

---

3.4 配置识别异常

可能的原因：

1. 配置下发延迟或失败
2. Agent 未正确识别 Server 下发的配置
3. 配置格式错误导致解析失败
4. Agent 版本不支持该配置项

排查步骤：

1. 查看组件版本

# 查看 Agent commit 版本
deepflow-agent -v

# 查看 Server commit 版本
deepflow-server -v

2. 查看 Agent Group Config 配置

# 确认 Server 端配置是否更新
deepflow-ctl agent-group-config list $AGENT_GROUP_CONFIG_NAME -o yaml

3. 查看 Agent 实际识别的配置

deepflow-ctl trisolaris.agent-check config \
  --cip $AGENT_IP \
  --cmac $AGENT_MAC \
  --cid $DOMAIN_ID \
  --gid $AGENT_GROUP_ID

联系方式：

• GitHub Issues: https://github.com/deepflowio/deepflow/issues
• DeepFlow 开源社区群

---

常见问题

Q1: DeepFlow Agent 支持哪些操作系统？

DeepFlow Agent 支持主流的 Linux 发行版，包括：

• Ubuntu 18.04+（推荐 20.04+）
• CentOS 7+ / RHEL 7+
• Debian 10+
• Fedora 30+

内核要求：Linux 内核版本 ≥ 4.14，推荐 5.x 以上以获得更好的 eBPF 支持。

Q2: Agent 注册失败如何快速定位问题？

按以下顺序排查：

1. 等待 5 分钟以上（初始化需要时间）
2. 检查 Domain 和 Agent Group Config 是否创建（主机部署）
3. 检查 Agent IP 是否在 Server 的 local_ip_ranges 内
4. 检查主机名是否重复
5. 检查是否通过 LB 连接 Server

Q3: 为什么某些 IP 在 Metrics 中显示为 0.0.0.0？

当 IP 不在 Server 的 local_ip_ranges 配置中时，DeepFlow 会将其识别为广域网 IP，在 Metrics 中聚合为 0.0.0.0。将对应网段添加到 local_ip_ranges 配置中即可解决。

在 Request Log 中可以通过 is_internet=true tag 确认该 IP 是否被识别为广域网。

Q4: eBPF 加载失败怎么办？

eBPF 加载失败通常是因为内核版本不适配。请：

1. 确认内核版本 ≥ 4.14（推荐 5.x+）
2. 使用 show-kernel-struct-offset 工具收集信息
3. 将结果提交到 GitHub Issues 或 DeepFlow 社区群

Q5: 如何启用 PostgreSQL/MongoDB 等非默认协议的解析？

通过 agent-group-config 配置文件添加：

processors:
  request_log:
    application_protocol_inference:
      enabled_protocols:
        - PostgreSQL
        - MongoDB

保存后 Agent 会自动拉取新配置，无需重启。

Q6: K8s 集群中某些资源看不到是什么原因？

常见原因：

1. 没有流量：资源从未有请求/响应
2. 孤立资源：Pod 没有上层控制器（Deployment/DS/STS）
3. 非原生资源：通过自定义 CRD 创建，DeepFlow 无法识别

Q7: Agent 和 Server 版本有什么要求？

Agent 版本必须 ≤ Server 版本。建议使用 LTS 版本，非 LTS 版本请升级后再排查问题。

---

相关资源

• DeepFlow 官方文档
• DeepFlow GitHub
• 运行权限及内核要求
• 协议支持列表
• GitHub Issues

---

文档版本：v1.1

最后更新：2026-03-18

适用版本：DeepFlow Agent v6.5+