简介这份《Kylin 3.3 探针软件安装调试手册》面向麒麟操作系统运维人员、安全监测实施工程师及需要部署探针组件的技术人员用于解决探针软件从安装、配置到卸载全流程缺少规范指引的问题。资源包内共1个docx文档压缩包约1002KB文档结构完整涵盖适用范围、总体目标与原则、作业前提条件、网络安全监测装置、程序安装、图形化界面配置、命令行配置、告警测试及程序卸载等章节并配有系统版本信息、agent升级组件与程序、产品认证、麒麟内网监控配置工具、主机通讯地址、网络白名单、关键目录文件等图示说明。读者可据此掌握探针安装要求与前提条件、图形化与命令行两种配置方式、告警测试方法、agent升级流程以及卸载前的准备与具体步骤适合作为现场实施与日常维护的操作参考。目前已有1570人学习下载。1. 探针软件在国产化环境里的真实定位第一次在国产化服务器上部署探针软件的人大概率会经历一个反直觉的时刻安装脚本一路绿灯服务也起来了但采集面板上就是没有数据。这不是软件坏了而是探针类工具在国产化操作系统上的运行逻辑和通用 Linux 发行版有本质差异——依赖库版本、内核模块签名策略、服务管理方式都可能成为数据链路断掉的节点。kylin 3.3 探针软件安装调试手册这个标题核心讲的是在国产化操作系统环境下如何把一套探针程序从零部署到稳定采集数据的完整过程。探针软件的本质是一个常驻的轻量级采集代理它负责从目标进程、系统调用或网络流量中提取运行时信息再通过本地缓存或消息通道上报给分析端。这类工具在性能诊断、安全审计、链路追踪场景里都是基础设施级别的存在。适合读这篇的人有三类一是需要在国产化平台上搭建可观测性体系的运维工程师二是做信创适配的中间件开发者三是负责交付验收、需要一份可复现部署流程的技术负责人。下面按实际落地顺序把安装、配置、调试、排错整条链路拆开讲。2. 安装前的环境确认与依赖梳理2.1 为什么国产化平台的依赖检查不能照搬通用清单通用 Linux 发行版上装探针很多人习惯直接apt install或yum install一把梭。但在 kylin 3.3 这类国产化系统上软件源里的包版本和命名规则都有调整直接套用通用发行版的依赖清单轻则版本冲突重则把系统自带的底层库覆盖掉导致桌面环境或系统服务异常。我一般会先做三件事确认系统版本和内核版本、确认 CPU 架构、确认现有运行时环境。这三项决定了后续所有二进制包的选型。# 确认系统版本信息 cat /etc/os-release # 确认内核版本和架构 uname -r uname -m # 确认已安装的运行时依赖以常见探针依赖为例 rpm -qa | grep -E glibc|libstdc|openssl|zlib逻辑说明/etc/os-release里的VERSION_ID决定后续软件源配置uname -m输出aarch64还是x86_64决定二进制包选型rpm -qa过滤出的基础库版本决定探针编译时的链接策略。参数说明如果glibc版本低于探针要求的最低版本不要强行升级系统glibc正确做法是找对应低版本glibc编译的探针包或者用静态编译版本。openssl版本尤其要注意1.1.x 和 3.x 的 ABI 不兼容探针如果动态链接了错误的版本启动时会直接报symbol lookup error。2.2 依赖安装的推荐顺序与验证方法依赖安装顺序错了后面排查成本会成倍增加。推荐按「基础 C 库 → 网络与加密库 → 采集相关库 → 探针主程序」的顺序推进。# 第一步确认基础 C 库和 C 运行时 ldd --version strings /usr/lib64/libstdc.so.6 | grep GLIBCXX | tail -5 # 第二步安装网络与加密依赖以本地源为例 # 注意包名以实际源中为准不要硬编码版本号 yum install -y openssl-devel zlib-devel libcurl-devel # 第三步验证关键库是否可被动态链接器找到 ldconfig -p | grep -E libssl|libcrypto|libcurl逻辑说明ldd --version确认动态链接器版本strings查看libstdc支持的GLIBCXX符号版本这决定了探针二进制能否加载ldconfig -p确认动态链接缓存里有没有目标库。参数说明yum install时不要指定具体版本号让包管理器从本地源解析。如果本地源里没有libcurl-devel优先找同版本curl的运行时包很多探针只需要运行时库不需要开发头文件。注意在国产化平台上/usr/lib64和/usr/lib的库搜索路径优先级可能和通用发行版不同安装完依赖后务必执行一次ldconfig否则探针启动时可能报「找不到共享库」。2.3 探针安装包的解构与安装路径规划拿到探针安装包后先别急着执行安装脚本。我习惯先把包解开看清楚目录结构和安装脚本里到底做了什么。# 查看安装包结构以 tar.gz 为例 tar -tzf probe-agent-*.tar.gz | head -30 # 解压到临时目录审查 mkdir -p /tmp/probe-inspect tar -xzf probe-agent-*.tar.gz -C /tmp/probe-inspect # 查看安装脚本的关键动作 grep -nE cp|mv|systemctl|chmod|chown|sed /tmp/probe-inspect/install.sh逻辑说明tar -tzf先看包内文件列表确认有没有覆盖系统目录的风险grep过滤安装脚本里的文件操作和服务注册动作判断安装行为是否可控。参数说明如果安装脚本里有cp -f直接覆盖/usr/lib64下已有库的行为必须手动改成安装到独立目录再通过LD_LIBRARY_PATH或rpath指定加载路径。探针类软件的最佳实践是全部文件收敛到/opt/probe-agent/下不污染系统目录。3. 探针核心配置文件的参数拆解3.1 采集目标与采集频率的配置逻辑探针装好之后能不能采到数据、采得准不准八成取决于配置文件。以常见的进程级探针为例核心配置项通常分三块采集目标、采集频率、上报通道。# probe-config.yaml 核心配置示例 collector: # 采集目标按进程名或 PID 匹配 targets: - type: process match: nginx|java|python exclude: probe-agent # 采集频率单位秒生产环境不建议低于 5s interval: 10 # 单次采集超时防止卡死主循环 timeout: 3 reporter: # 上报通道本地文件或远端接口 mode: file file: path: /var/log/probe/metrics.log rotate_size_mb: 100 rotate_keep: 5 # 批量上报条数攒批可降低 IO 压力 batch_size: 50逻辑说明targets里的match支持正则exclude用来排除探针自身避免自采集死循环interval控制采集节奏timeout是防止某个采集目标卡住整个采集线程的保险丝reporter的batch_size决定攒多少条数据写一次盘或发一次网络请求。参数说明interval设太小比如 1s会导致 CPU 占用飙升尤其在采集目标多的时候设太大比如 60s会丢失短时毛刺排查性能抖动时基本没用。生产环境我一般设 10s压测或专项排查时临时调到 5s。timeout必须小于interval否则会出现采集任务堆积。3.2 上报通道的选型与连通性验证上报通道选本地文件还是远端接口取决于分析端的位置和网络策略。本地文件模式适合分析端和探针同机部署或者有日志采集器统一收发的场景远端接口模式适合探针分散、分析端集中的场景。# 本地文件模式确认目录权限和磁盘空间 mkdir -p /var/log/probe chown -R probe:probe /var/log/probe df -h /var/log/probe # 远端接口模式先用 curl 验证连通性 curl -X POST -H Content-Type: application/json \ -d {test:connectivity} \ --connect-timeout 3 \ http://analysis-endpoint:8080/api/v1/metrics逻辑说明本地文件模式最容易翻车的地方是权限和磁盘满chown确保探针进程有写权限df确认分区余量远端接口模式先用curl手动打一次排除网络策略和接口路径问题。参数说明--connect-timeout设 3 秒足够探针内部的上报超时也应该设在这个量级。如果curl通但探针上报失败检查探针配置里的接口地址是否带了多余的路径前缀以及请求头里的Content-Type是否和分析端要求一致。3.3 服务注册与开机自启的配置方式探针作为常驻服务必须注册到系统服务管理器里否则重启后不会自动拉起。国产化系统上systemd是标配但 unit 文件的写法有几个细节要注意。# /etc/systemd/system/probe-agent.service [Unit] DescriptionProbe Agent Service Afternetwork.target Wantsnetwork.target [Service] Typesimple Userprobe Groupprobe EnvironmentLD_LIBRARY_PATH/opt/probe-agent/lib ExecStart/opt/probe-agent/bin/probe-agent -c /opt/probe-agent/conf/probe-config.yaml Restarton-failure RestartSec5 LimitNOFILE65536 [Install] WantedBymulti-user.target逻辑说明After和Wants确保网络就绪后再启动Environment指定独立库路径避免和系统库冲突Restarton-failure让探针异常退出后自动拉起LimitNOFILE提高文件描述符上限采集目标多的时候默认值不够用。参数说明RestartSec设 5 秒是折中值太短会在探针持续崩溃时疯狂重启刷日志太长会影响故障恢复速度。User和Group不要用 root探针只需要读权限和写日志目录的权限用独立低权限账号更安全。# 重载服务配置并启动 systemctl daemon-reload systemctl enable probe-agent systemctl start probe-agent # 确认服务状态和日志 systemctl status probe-agent journalctl -u probe-agent -n 50 --no-pager逻辑说明daemon-reload让 systemd 重新读取 unit 文件enable注册开机自启status和journalctl确认启动结果和早期日志。参数说明如果status显示active (running)但日志里有permission denied检查User指定的账号对配置文件和日志目录是否有读权限。如果显示failed优先看journalctl里最后 20 行通常是库加载失败或配置解析错误。4. 调试阶段的数据链路排查4.1 从探针进程到采集目标的链路确认探针启动成功不等于采集成功。数据链路是「探针进程 → 采集目标 → 数据缓冲 → 上报通道」任何一环断了面板上都是空的。排查顺序应该从探针进程自身开始逐段往下游走。# 确认探针进程存活且线程正常 ps -ef | grep probe-agent | grep -v grep top -H -p $(pgrep -f probe-agent) -n 1 | head -20 # 确认探针能读到采集目标 cat /proc/$(pgrep -f nginx: master)/status | grep -E Name|Pid|Threads # 确认探针日志里有没有采集动作 tail -f /var/log/probe/probe-agent.log | grep -E collect|target|error逻辑说明ps确认进程存活top -H看线程级 CPU 占用判断采集线程是否在正常工作cat /proc/.../status确认探针有权限读取目标进程信息tail -f实时观察采集日志。参数说明如果top -H显示某个线程 CPU 占用持续 100%大概率是采集逻辑里有死循环或正则匹配回溯爆炸。如果/proc/.../status报Permission denied说明探针运行账号权限不足需要把探针账号加入目标进程所属的组或者调整/proc挂载选项。4.2 采集数据为空的三层排查法采集数据为空是最常见的调试场景。我一般按「配置层 → 权限层 → 逻辑层」三层往下查。第一层配置层确认targets里的匹配规则能不能命中目标进程。用pgrep手动验证正则是否写对了。# 用探针配置里的正则手动匹配 pgrep -f nginx|java|python # 如果匹配不到检查进程名是否被截断 ps -eo comm,args | grep -E nginx|java|python逻辑说明pgrep -f匹配完整命令行ps -eo comm匹配进程名。探针配置里的match字段如果用的是进程名匹配但实际进程名被截断Linux 进程名默认最多 15 字符就会漏采。第二层权限层确认探针账号能读到目标进程的/proc信息。不同用户启动的进程/proc/pid/下的部分文件对其他用户不可读。# 切换到探针账号尝试读取目标进程信息 su -s /bin/bash probe -c cat /proc/$(pgrep -f nginx | head -1)/status逻辑说明用su切换到探针运行账号模拟探针的实际读取行为。如果报权限错误说明需要调整账号组或/proc挂载参数。第三层逻辑层如果配置和权限都没问题但数据还是空就要看探针自身的采集逻辑日志。把日志级别临时调到debug观察采集函数有没有被调用、返回值是什么。# 临时调整日志级别 log: level: debug file: /var/log/probe/probe-agent-debug.log逻辑说明debug级别会输出采集函数的入参和返回值能直接看到是匹配阶段没命中还是采集阶段返回了空数据。参数说明调试完记得把级别调回infodebug级别在高频采集下会产生大量日志磁盘写入压力不小。4.3 上报失败的常见错误码与应对上报失败时探针日志里通常会带错误码。不同错误码指向不同环节的问题对照处理能省很多时间。错误码含义常见原因处理方式401认证失败token 过期或配置错误检查上报配置里的认证字段403权限不足接口路径无权限确认分析端接口的访问控制策略413请求体过大单批数据超过限制调小batch_size429请求过频上报频率超限增大上报间隔或降低采集频率502/504网关或超时分析端不可达或响应慢检查网络链路和分析端负载逻辑说明401 和 403 是认证授权问题优先查配置413 和 429 是流量控制问题优先调参数502 和 504 是链路问题优先查网络和分析端状态。参数说明batch_size调小会增加请求次数但能降低单次请求失败的影响面。如果分析端有频率限制batch_size和上报间隔要配合调整保证单位时间内的请求数不超限。5. 避坑与常见问题排查5.1 探针启动即退出且无日志现象systemctl start后状态立刻变成failedjournalctl里只有一行Main process exited没有更多信息。原因探针在初始化阶段就崩了日志系统还没完成初始化所以没有日志输出。最常见的是动态库加载失败或配置文件路径错误。解决先用ldd检查探针二进制的库依赖是否全部可解析再手动前台运行一次让错误直接打到终端。# 检查库依赖 ldd /opt/probe-agent/bin/probe-agent | grep not found # 前台手动运行观察终端输出 sudo -u probe /opt/probe-agent/bin/probe-agent -c /opt/probe-agent/conf/probe-config.yaml逻辑说明ldd的not found直接指出缺失的库前台运行绕过 systemd 的日志封装错误信息直接可见。参数说明如果ldd显示某个库not found但ldconfig -p里明明有说明库路径不在动态链接器的搜索范围内需要在 unit 文件里补LD_LIBRARY_PATH或用patchelf给二进制加rpath。5.2 采集数据时间戳错乱现象上报的数据在分析端按时间排序后顺序混乱或者时间戳和实际采集时间差了几个小时。原因探针所在服务器的时区设置和分析端不一致或者探针内部用了本地时间而非 UTC 时间做时间戳。解决统一探针和分析端的时区配置探针内部时间戳建议统一用 UTC展示层再做时区转换。# 确认系统时区 timedatectl status | grep Time zone # 确认探针配置里的时区设置 grep -i timezone\|tz /opt/probe-agent/conf/probe-config.yaml逻辑说明timedatectl确认系统时区探针配置里如果有独立的时区字段要和分析端对齐。参数说明如果分析端和探针端都用了本地时间跨时区部署时必然错乱。最稳妥的做法是探针输出 UTC 时间戳分析端按需转换。5.3 高频采集导致目标进程性能下降现象探针开启后被采集的业务进程响应变慢CPU 占用上升。原因采集频率过高或者采集方式对目标进程有侵入性比如频繁读取/proc下的统计文件、频繁 attach/detach。解决降低采集频率改用批量读取方式或者把采集方式从主动拉取改成被动接收。collector: interval: 30 batch_read: true batch_size: 100逻辑说明interval从 10s 调到 30s 能显著降低采集开销batch_read让探针一次性读取多个指标减少系统调用次数。参数说明batch_size不是越大越好单次读取数据量过大会导致内存峰值上升。一般设 50 到 100 之间根据目标进程数量和指标数量调整。5.4 日志文件写满磁盘导致服务异常现象探针运行一段时间后突然停止上报df -h显示日志分区 100%。原因日志轮转配置没生效或者轮转策略不合理单个文件过大。解决配置日志轮转限制单文件大小和保留数量同时给日志分区设置监控告警。# 确认日志轮转配置 cat /etc/logrotate.d/probe-agent # 手动触发一次轮转测试 logrotate -f /etc/logrotate.d/probe-agent逻辑说明logrotate配置里要明确size、rotate、compress三个参数-f强制轮转一次验证配置是否生效。参数说明size建议设 100Mrotate设 5 到 10compress开启。如果日志写入速度极快size要相应调小避免两次轮转检查之间就写满分区。5.5 升级探针后配置不兼容现象探针升级后启动失败日志报配置解析错误。原因新版本探针的配置 schema 有变化旧配置文件里的字段被重命名或废弃。解决升级前备份旧配置升级后对照新版本的配置模板逐项迁移不要直接覆盖。# 备份旧配置 cp /opt/probe-agent/conf/probe-config.yaml /opt/probe-agent/conf/probe-config.yaml.bak # 对比新旧配置模板差异 diff /opt/probe-agent/conf/probe-config.yaml.bak /opt/probe-agent/conf/probe-config.yaml.new逻辑说明diff能直观看出哪些字段被增删改迁移时以新模板为准把旧配置里的值填进去。参数说明如果新版本废弃了某个字段但业务上确实需要该功能查新版本的替代配置项不要强行保留旧字段。6. 让探针长期稳定运行的几个习惯探针部署完只是开始真正考验人的是长期运行中的稳定性。我自己的习惯是给每套探针配三个东西一个资源监控看板、一个日志轮转策略、一个配置版本管理。资源监控看板盯三个指标探针进程的 CPU 和内存占用、日志分区使用率、上报成功率。这三个指标任何一个异常都能提前暴露问题。CPU 和内存持续上涨大概率是采集逻辑有内存泄漏日志分区使用率超过 80%就该检查轮转策略了上报成功率跌破 99%先查网络再查分析端。日志轮转策略前面提过这里补一个细节轮转后的日志不要直接删保留最近 5 到 10 个压缩包。排查历史问题时这些日志就是后悔药。我见过太多人为了省磁盘把轮转日志删干净结果出问题时连现场都没了。配置版本管理用 Git 就够了。每次改配置前先提交一次改完再提交一次diff 一目了然。探针配置里那些采集频率、批量大小、超时时间都是调优时反复改的参数没有版本管理改乱了根本回不去。最后一个习惯每次升级探针版本前先在测试环境跑一遍完整的数据链路验证从采集到上报到分析端展示全链路走通再上生产。探针这类基础设施升级翻车的代价比业务服务还大因为它是观测手段本身它挂了你就瞎了。希望帮到你。本文还有配套的精品资源点击获取