一、注册失败类故障排查
注册失败是DeepFlow Agent部署初期最常见的问题，主要集中在网络连通性、配置匹配性与版本兼容性三个维度。
从网络层面看，需优先验证Agent与Server的基础连通性。可在Agent主机执行ping
确认IP可达性，通过telnet30033或nc -zv30033测试控制通信端口（30033、30034）与数据传输端口（30035）的连通性。若出现连接拒绝，需检查防火墙规则、云安全组策略及K8s Service端口暴露配置，确保流量未被拦截。
配置层面需重点核对三项关键参数：一是Agent配置文件/etc/deepflow-agent.yaml中controller-ips是否与Server实际监听地址一致；二是Server端local_ip_ranges白名单是否包含Agent所在网段，若使用特殊网段需在Server配置中新增对应网段规则；三是Agent部署在Serverless Pod场景时，需在values-custom.yaml中指定clusterNAME参数，否则会出现analyzer_ip not set错误。
版本兼容性问题常表现为gRPC接口不兼容，Server日志会出现unknown service agent.Synchronizer报错。此时需通过deepflow-agent --version与deepflow-server --version确认版本一致性，建议优先部署Server再安装同版本Agent。
二、协议解析类故障排查
协议解析异常会导致监控指标缺失，需分通用协议与私有协议两种场景处理。
通用协议解析失败时，首先启用调试模式定位问题：执行deepflow-agent --log-level debug --log-file /var/log/deepflow-agent/debug.log生成详细日志，同时用tcpdump -i any -w problem_traffic.pcap捕获异常流量包。若日志显示Tars parse failure等协议特定错误，需检查Agent是否支持该协议版本，必要时升级Agent至最新稳定版。
针对私有协议，需通过Wasm插件扩展解析能力。首先在Agent组配置中添加端口白名单与协议类型：
static_config:
ebpf:
kprobe-whitelist:
port-list: 9999
l7-protocol-enabled:
- Custom
wasm-plugins:
- wasm-demo-1
配置更新后Agent会自动重启，可通过kubectl logs-c deepflow-agent验证插件加载状态。
三、资源识别与配置类故障排查
资源识别异常表现为Grafana界面无法显示主机或流量数据，需从Agent状态、内核兼容性与安全策略三方面排查。
首先在Server端执行deepflow-ctl agent list检查Agent状态，若显示WAIT_FOR_APPROVAL，需确认Serverlocal_ip_ranges包含Agent网段，且Agent配置的vtap-group-id-request对应Group已正确创建。若状态为NORMAL但无数据，需检查Agent日志中是否有eBPF program load failed报错，这通常是内核版本过低导致（建议内核≥4.15），可通过uname -r验证内核版本。
部分安全强化系统会通过SELinux阻止eBPF程序运行，可临时执行setenforce 0测试，若恢复正常则需添加SELinux策略允许Agent的eBPF操作。此外，需确认Agent配置中tap_interface_regex是否正确匹配服务器网卡，避免因网卡选择错误导致流量采集失败。
四、标准化配置与故障预防
为降低故障发生率，需建立标准化配置流程：
预部署检查：提前验证网络连通性、内核版本兼容性与Server网段白名单配置；
版本管控：保持Server与Agent版本一致，优先使用官方推荐的稳定版本；
配置备份：对Agent组配置、Server网段规则等关键配置进行版本管理；
日志监控：通过journalctl -u deepflow-agent -f实时监控Agent运行状态，建立异常告警规则。