资讯详情

深入了解 · 专业解读

Linux下Milvus向量数据库故障的系统化排查Shell脚本

发布时间：2026/7/13 8:41:54
Linux下Milvus向量数据库故障的系统化排查Shell脚本 #!/bin/bash# # 脚本名称: milvus_diagnose_native.sh# 描述: 哲学优化 Milvus 向量数据库故障排查脚本【Linux原生安装 无Docker版】# 适配Systemd托管 / 二进制手动启动 Milvus 单机分布式组件# 特性# 1. 代码分段可单独复制终端逐句执行# 2. 自动缓存进程PID、服务名、日志路径、配置路径高亮可复制# 3. 完整故障现场自动打包归档# 4. 无任何Docker、K8s相关逻辑# 用法: chmod x milvus_diagnose_native.sh sudo ./milvus_diagnose_native.sh# 依赖: ps/top/vmstat/free/df/journalctl/grep/awk/systemctl# 哲学体系:# 本体论 - 先识别所有Milvus进程实体奥卡姆剃刀 - 最少命令定位根因# 辩证法 - 区分内存/IO/磁盘/网络核心矛盾实用主义 - 过滤致命错误日志# 整体论 - 校验etcd/MinIO存储依赖连通道家无为 - 给出监控自愈方案。# set-opipefail# 【单段独立执行】全局颜色、工具函数、缓存初始化 # 颜色定义RED\033[0;31mGREEN\033[0;32mYELLOW\033[1;33mCYAN\033[0;36mWHITE\033[1;37mNC\033[0m# 分割线打印print_section(){echo-e\n${CYAN}$1${NC}}print_ok(){echo-e${GREEN}[✓]${NC}$1;}print_warn(){echo-e${YELLOW}[⚠]${NC}$1;}print_error(){echo-e${RED}[✗]${NC}$1;}# 手工提示manual_hint(){echo-e${YELLOW} 手工检验步骤:${NC}$1;}# 打印可复制变量并写入缓存print_copy(){locallabel$1localval$2echo-e${WHITE}【可复制参数$label】${RED}$val${NC}echo$label$val$CACHE_FILE}# 输出预填充快捷命令自动带入缓存参数quick_cmd(){echo-e${YELLOW}[一键复制执行命令]$1${NC}echo快捷命令$1$CACHE_FILE}# 采集日志持久化collect_file(){localcmd$1localsave_path$2echo采集数据$cmd$DIAG_SUMMARYeval$cmd$save_path21}# 初始化取证缓存目录所有分段共享TIMESTAMP$(date%Y%m%d_%H%M%S)DIAG_ROOT/tmp/milvus_native_diag_${TIMESTAMP}CACHE_FILE${DIAG_ROOT}/cache_param.txtDIAG_SUMMARY${DIAG_ROOT}/diagnose_record.logmkdir-p$DIAG_ROOT$CACHE_FILE$DIAG_SUMMARYechoMilvus故障取证时间$(date)$DIAG_SUMMARY# 全局缓存变量MILVUS_ALL_PIDSMILVUS_PROXY_PIDMILVUS_CONFIG_PATHMILVUS_LOG_BASEETCD_ENDPOINTMINIO_DATA_PATH# # 【单段独立执行】前置环境校验 全局Milvus实体参数预采集 print_section前置校验 Milvus全组件实体参数采集全部存入缓存可复制# 1. 校验核心系统命令CMD_LIST(psdffreevmstatsystemctljournalctl)forcmdin${CMD_LIST[]};doif!command-v$cmd/dev/null;thenprint_warn系统缺失命令$cmd部分检测功能失效fidone# 2. 抓取所有Milvus进程PID区分所有分布式组件MILVUS_ALL_PIDS$(pgrep-fmilvus|tr\n )if[-z$MILVUS_ALL_PIDS];thenprint_error未检测到任何Milvus运行进程manual_hint手动查询全部相关进程ps aux | grep milvusmanual_hint查看systemd服务状态systemctl list-units | grep milvuselseprint_copyMilvus全部进程PID$MILVUS_ALL_PIDS# 单独提取proxy进程高频故障点MILVUS_PROXY_PID$(pgrep-fmilvus-proxy|head-1)print_copymilvus-proxy进程PID$MILVUS_PROXY_PIDfi# 3. 自动识别Milvus配置文件路径通用默认路径if[-f/etc/milvus/milvus.yaml];thenMILVUS_CONFIG_PATH/etc/milvus/milvus.yamlelif[-f/usr/local/milvus/conf/milvus.yaml];thenMILVUS_CONFIG_PATH/usr/local/milvus/conf/milvus.yamlelif[-f$HOME/milvus/conf/milvus.yaml];thenMILVUS_CONFIG_PATH$HOME/milvus/conf/milvus.yamlfiprint_copyMilvus主配置文件路径$MILVUS_CONFIG_PATH# 4. 从配置提取日志根目录、etcd地址、minio存储路径if[-n$MILVUS_CONFIG_PATH][-f$MILVUS_CONFIG_PATH];thenMILVUS_LOG_BASE$(greppath:$MILVUS_CONFIG_PATH|greplog|awk{print $2}|head-1)ETCD_ENDPOINT$(grependpoints:$MILVUS_CONFIG_PATH|grepetcd|awk{print $2}|head-1)MINIO_DATA_PATH$(greprootPath:$MILVUS_CONFIG_PATH|grepminio|awk{print $2}|head-1)fiprint_copyMilvus日志根目录$MILVUS_LOG_BASEprint_copyETCD连接地址$ETCD_ENDPOINTprint_copyMinIO本地数据存储目录$MINIO_DATA_PATH# 预填充高频快捷命令quick_cmdsystemctl status milvusquick_cmdcat${MILVUS_CONFIG_PATH}quick_cmdtail -f${MILVUS_LOG_BASE}/milvus-proxy.logquick_cmdps aux --sort-%mem | grep milvusquick_cmdtar -czf${DIAG_ROOT}.tar.gz -C /tmp milvus_native_diag_${TIMESTAMP}# # 【单段独立执行】1.本体论识别Milvus所有分布式实体状态 print_section1. 本体论检查Milvus全组件进程实体存活状态echoMilvus完整进程列表组件名/PID/CPU/内存/启动命令collect_fileps aux | grep -E milvus-(rootcoord|querycoord|datacoord|proxy|indexnode|querynode|datanode) | grep -v grep${DIAG_ROOT}/milvus_process_list.logcat${DIAG_ROOT}/milvus_process_list.log# 统计异常终止进程systemd托管场景ifcommand-vsystemctl/dev/null;thenecho-e\nSystemd Milvus服务运行状态collect_filesystemctl list-units --all | grep milvus${DIAG_ROOT}/milvus_systemd_service.logcat${DIAG_ROOT}/milvus_systemd_service.logcollect_filesystemctl status milvus --no-pager -l${DIAG_ROOT}/milvus_service_status.logfi# 判定实体完整性STOP_PROC_COUNT$(journalctl-umilvus --no-pager|grep-iEterminated|killed|exit|wc-l)if[$STOP_PROC_COUNT-gt0]||[-z$MILVUS_ALL_PIDS];thenprint_warn检测到Milvus组件进程异常终止实体缺失优先排查崩溃根因elseprint_ok所有Milvus分布式组件进程正常运行实体完整排查业务卡顿问题fiecho-e\n${CYAN} 哲学提示(本体论)${NC}Milvus由7类微服务进程组成任一组件崩溃都会导致向量读写失败manual_hint单独查看单个组件日志tail -200${MILVUS_LOG_BASE}/milvus-rootcoord.log# # 【单段独立执行】2.奥卡姆剃刀三问存在性/因果/环境内核 print_section2.1 奥卡姆之问一进程存活校验存在性if[-n$MILVUS_ALL_PIDS];thenprint_okMilvus进程PID$MILVUS_ALL_PIDS处于运行状态故障为业务不可用/超时# 检查端口监听19530默认proxy端口echoMilvus Proxy端口19530监听状态ss-tlnp|grep19530||print_warn19530端口无监听客户端无法连接elseprint_error无Milvus进程运行故障为服务完全崩溃fimanual_hint检查全部监听端口ss -tlnp | grep milvusprint_section2.2 奥卡姆之问二崩溃致命日志提取因果性只抓崩溃关键词# 致命错误过滤规则LOG_FILTERpanic|fatal|OOM|out of memory|no space left|too many open files|segment fault|killed|disk full|etcd connect failed|minio io error|index build failedecho遍历所有Milvus日志提取致命崩溃日志if[-n$MILVUS_LOG_BASE][-d$MILVUS_LOG_BASE];thencollect_filegrep -rniE $LOG_FILTER${MILVUS_LOG_BASE}--include*.log | tail -50${DIAG_ROOT}/milvus_fatal_error.logcat${DIAG_ROOT}/milvus_fatal_error.logelseprint_warn未识别日志目录读取systemd服务日志替代collect_filejournalctl -u milvus --no-pager | grep -iE $LOG_FILTER | tail -50${DIAG_ROOT}/milvus_journal_error.logcat${DIAG_ROOT}/milvus_journal_error.logfimanual_hint查看完整proxy日志less${MILVUS_LOG_BASE}/milvus-proxy.logprint_section2.3 奥卡姆之问三内核裁决日志OOM/IO崩溃echo内核环形缓冲区Milvus进程被杀死、磁盘IO异常记录collect_filedmesg -T | tail -40 | grep -iE out of memory|killed process|I/O error|ext4 read-only${DIAG_ROOT}/host_kernel_oom.logcat${DIAG_ROOT}/host_kernel_oom.logmanual_hint完整内核日志检索OOMdmesg -T | grep -i killed process# # 【单段独立执行】3.辩证法识别系统资源核心矛盾 print_section3. 辩证法检查CPU/内存/IO 瓶颈快速区分echovmstat 2次采样wa高磁盘瓶颈so高内存OOM风险r高CPU耗尽collect_filevmstat 1 2${DIAG_ROOT}/vmstat_snapshot.logcat${DIAG_ROOT}/vmstat_snapshot.log# 资源矛盾解读提示print_warnwa(IO等待)20向量存储/MinIO磁盘IO瓶颈print_warnso(交换输出)0内存不足索引加载触发OOM杀死进程print_warnr运行队列CPU核数批量插入/向量检索耗尽CPUmanual_hint持续监控资源vmstat 1# # 【单段独立执行】4.细分资源专项深度排查 print_section4.1 内存资源深度检测Milvus向量索引内存占用重灾区collect_filefree -h; swapon --show${DIAG_ROOT}/host_memory.logcat${DIAG_ROOT}/host_memory.log# 排序Milvus进程内存占用echoMilvus进程内存占用倒序collect_fileps aux --sort-%mem | grep milvus | grep -v grep${DIAG_ROOT}/milvus_mem_rank.logcat${DIAG_ROOT}/milvus_mem_rank.log# Swap风险判定SWAP_USED$(free|grepSwap|awk{print $3})SWAP_TOTAL$(free|grepSwap|awk{print $2})if[$SWAP_TOTAL-gt0][$SWAP_USED-gt$((SWAP_TOTAL/2))];thenprint_errorSwap占用超50%内存严重不足易触发OOM杀死Milvusfiquick_cmdcat /proc/${MILVUS_PROXY_PID}/status | grep VmRSSprint_section4.2 磁盘空间 Inode 只读文件系统检测collect_filedf -h${DIAG_ROOT}/disk_usage.logawk{if(NR1 || $5080) print}${DIAG_ROOT}/disk_usage.logecho-e\nInode占用向量分段文件多易耗尽inodecollect_filedf -i${DIAG_ROOT}/inode_usage.logawk{if(NR1 || $5080) print}${DIAG_ROOT}/inode_usage.log# 检测只读磁盘mount|grepro,print_error存在只读文件系统Milvus写入Segment/索引失败manual_hint统计MinIO数据目录大小du -sh${MINIO_DATA_PATH}print_section4.3 文件句柄专项Milvus海量Segment文件极易超限if[-n$MILVUS_PROXY_PID];thenechoProxy进程PID:${MILVUS_PROXY_PID}collect_filels /proc/${MILVUS_PROXY_PID}/fd 2/dev/null | wc -l${DIAG_ROOT}/proxy_fd_count.logFD_COUNT$(cat${DIAG_ROOT}/proxy_fd_count.log)echo当前打开文件句柄数$FD_COUNTcollect_filecat /proc/${MILVUS_PROXY_PID}/limits | grep Max open files${DIAG_ROOT}/fd_limit.logcat${DIAG_ROOT}/fd_limit.log# 句柄风险判定FD_LIMIT$(cat${DIAG_ROOT}/fd_limit.log|awk{print $4})if[$FD_COUNT-gt$((FD_LIMIT*8/10))];thenprint_error文件句柄占用超过限制80%即将触发too many open files崩溃fifimanual_hint全局调整ulimitvim /etc/security/limits.conf# # 【单段独立执行】5.整体论依赖服务连通性全链路校验 print_section5. 整体论ETCD元数据服务 MinIO存储连通校验# 5.1 ETCD连通健康检测if[-n$ETCD_ENDPOINT];thenecho检测ETCD地址$ETCD_ENDPOINTcollect_fileetcdctl --endpoints$ETCD_ENDPOINTendpoint health${DIAG_ROOT}/etcd_health.logcat${DIAG_ROOT}/etcd_health.logifgrep-qunhealthy${DIAG_ROOT}/etcd_health.log;thenprint_errorETCD元数据服务异常Milvus无法加载集合、索引元信息fielseprint_warn未自动识别ETCD地址请手动核对milvus.yaml配置fimanual_hint手动测试etcd连通etcdctl put test_key test_val# 5.2 MinIO本地存储目录读写权限校验if[-n$MINIO_DATA_PATH][-d$MINIO_DATA_PATH];thenechoMinIO向量存储目录权限检查$MINIO_DATA_PATHls-ld$MINIO_DATA_PATH# 测试写入权限touch${MINIO_DATA_PATH}/.milvus_write_test2/dev/nullrm-f${MINIO_DATA_PATH}/.milvus_write_testprint_ok存储目录读写正常||print_errorMinIO存储目录无写入权限fi# 5.3 全链路业务提示echo-e\n${CYAN} 哲学提示(整体论)${NC}echo1. ETCD宕机所有集合无法加载服务启动直接panicecho2. MinIO磁盘满/权限不足插入向量、构建索引全部失败echo3. 网络延迟过高跨节点分布式Coord组件超时阻塞manual_hint客户端连接全链路排查使用pymilvus建立测试连接捕获完整报错堆栈# # 【单段独立执行】6.道家无为长期监控自愈优化方案 print_section6. 道家无为前置监控告警被动故障转为主动预警catEOF # Milvus生产环境必备监控告警项避免事后紧急排查 1. 进程存活告警7类milvus组件任一进程消失触发告警 2. 致命日志告警监控panic/OOM/no space/etcd failed关键词 3. 资源阈值告警 - 磁盘使用率80% / Inode80% - 内存Swap占用30% - Proxy文件句柄超过限制80% 4. 依赖健康告警ETCD endpoint health失败、MinIO目录不可写 5. 业务指标告警向量插入失败率0、索引构建任务堆积 # 系统配置优化规避高频故障 1. 调大系统ulimit nofile 65535Milvus海量Segment文件 2. 分配独立磁盘给MinIO向量存储隔离系统日志IO竞争 3. 设置milvus进程OOM优先级防止内核优先杀死向量服务 4. 日志轮转配置避免日志持续打满磁盘 EOF# # 【单段独立执行】收尾故障现场打包归档、缓存查看指引 print_section诊断收尾全量取证打包 可复制参数查看# 打包所有采集的故障数据tar-czf${DIAG_ROOT}.tar.gz-C/tmpmilvus_native_diag_${TIMESTAMP}2/dev/null print_ok✅ Milvus完整故障取证包生成完成print_copy取证压缩包完整路径${DIAG_ROOT}.tar.gzecho-e\n${WHITE}【查看全部缓存PID/路径参数】执行命令${RED}cat${CACHE_FILE}${NC}echo-e\n${GREEN}Milvus Linux原生故障系统化排查全部执行完毕${NC}echo-e${YELLOW}根因定位顺序建议致命日志 OOM内核记录 磁盘空间 ETCD连通 内存/句柄限制${NC}#

相关新闻