交付说明

一、排查手册（6 场景 × 五段式）

场景 1：Java 连接池 socket fd 泄漏

• 症状：jstack 显示大量 BLOCKED 线程，ss -s 中 TIME_WAIT 数飙升，应用日志报 java.io.IOException: Too many open files
• 快速定位：

  ss -tnp | grep java | awk '{print $1}' | sort | uniq -c | sort -rn | head
  ls /proc/$(pgrep -f java)/fd | wc -l
  lsof -p $(pgrep -f java) | awk '{print $5}' | sort | uniq -c | sort -rn | head
  

• 根因：HikariCP/Druid 连接池 maximumPoolSize 配置过大或 connectionTimeout 过短导致连接未归还即新建；Druid 的 removeAbandoned 未开启
• 修复：
  • HikariCP：maximumPoolSize 调至 CPU核数*2+磁盘数；connectionTimeout=30000；idleTimeout=600000
  • Druid：开启 removeAbandoned=true; removeAbandonedTimeout=1800
  • 应用层：确保 finally 块关闭 ResultSet/Statement
• 验证：

  watch -n 5 'ss -tn | grep TIME_WAIT | wc -l'
  ls /proc/$(pgrep -f java)/fd | wc -l  # 应稳定不再增长
  

场景 2：Nginx worker_connections 与 ulimit 不匹配

• 症状：nginx: error while loading config 或运行时 worker_connections exceed
• 快速定位：

  grep -E "worker_connections|worker_rlimit_nofile" /etc/nginx/nginx.conf
  cat /proc/$(pgrep -n nginx)/limits | grep "open files"
  ss -s
  

• 根因：worker_connections 4096 但 ulimit -n 1024，nginx 启动时 rlimit 被系统默认值覆盖
• 修复：
  • nginx.conf：加 worker_rlimit_nofile 65536;（需 master 以 root 启动）
  • systemd override：LimitNOFILE=65536
  • 或 /etc/security/limits.d/90-nginx.conf：nginx soft nofile 65536
• 验证：

  nginx -t && systemctl reload nginx
  cat /proc/$(pgrep -n nginx)/limits | grep "open files"
  

场景 3：Docker 容器 nofile=1024

• 症状：容器内 ulimit -n 显示 1024，Java/Go 应用频繁 OOM 或 fd 报错
• 快速定位：

  docker inspect $(docker ps -q | head -1) | grep -i nofile
  docker exec $(docker ps -q | head -1) cat /proc/self/limits
  

• 根因：Docker daemon 默认 Default-ulimits 未设 nofile；docker run 未加 --ulimit nofile=65536:65536
• 修复：
  • /etc/docker/daemon.json：{"default-ulimits": {"nofile": {"Name": "nofile", "Hard": 1048576, "Max": 1048576}}}
  • 或 compose：ulimits: nofile: {soft: 65536, hard: 65536}
  • 重启 daemon：systemctl restart docker
• 验证：

  docker exec <container> bash -c 'ulimit -n; cat /proc/self/limits | grep files'
  

场景 4：inotify max_user_watches 耗尽

• 症状：inotify_add_watch() failed: No space left on device，filebeat/inotifywait 停止工作
• 快速定位：

  cat /proc/sys/fs/inotify/max_user_watches
  for p in /proc/*/fdinfo; do grep -l inotify "$p" 2>/dev/null; done | while read f; do echo "$f: $(grep -c inotify_watch "$f")"; done
  

• 根因：大量文件监控工具各自创建 inotify instance，总 watches 超过 max_user_watches（默认 8192）
• 修复：
  • sysctl -w fs.inotify/max_user_watches=524288
  • 持久化：echo "fs.inotify/max_user_watches=524288" >> /etc/sysctl.conf && sysctl -p
  • 减少冗余：合并 filebeat 与 inotifywait 的监控范围
• 验证：

  cat /proc/sys/fs/inotify/max_user_watches
  find /proc/*/fdinfo -exec grep -l inotify {} \; | wc -l
  

场景 5：systemd LimitNOFILE 未继承

• 症状：ulimit -n 显示 1048576，但 systemctl status 下进程实际 limits 仍为 4096
• 快速定位：

  systemctl show <service> | grep -i limit
  cat /proc/$(systemctl show -p MainPID --value <service>)/limits | grep files
  ls /etc/systemd/system/<service>.service.d/  # 检查 override
  

• 根因：LimitNOFILE 写在 unit 文件但被 override.conf 覆盖，或 systemd 版本 < 226 不支持 LimitNOFILE=infinity
• 修复：
  • 确认 systemctl cat <service> 无冲突；systemctl edit <service> 写 override
  • daemon-reload 后 systemctl restart <service>
  • 若仍不生效：检查 /etc/security/limits.conf 是否被 PAM 模块覆盖
• 验证：

  systemctl restart <service>
  cat /proc/$(systemctl show -p MainPID --value <service>)/limits
  

场景 6：内核 fs.file-max / fs.nr_open 与 ulimit 不匹配

• 症状：ulimit -n 1048576 设了但 cat /proc/self/limits 显示 hard 仍为 1048576 而 fs.file-max=9223372036854775807，实际进程 fd 上限仍被 fs.nr_open 卡住
• 快速定位：

  cat /proc/sys/fs/file-max
  cat /proc/sys/fs/nr_open
  cat /proc/sys/fs/file-nr
  

• 根因：fs.nr_open 是 per-process 的绝对上限，即使 ulimit 设高，若 nr_open 未同步调大则无效
• 修复：
  • sysctl -w fs.nr_open=1048576
  • sysctl -w fs.file-max=2097152
  • 持久化到 /etc/sysctl.conf
• 验证：

  ulimit -n; cat /proc/self/limits | grep files; cat /proc/sys/fs/nr_open
  

二、一键诊断脚本 fd_diagnose.sh

#!/usr/bin/env bash
# fd_diagnose.sh - Linux 文件句柄耗尽一键诊断
# 用法: bash fd_diagnose.sh [--verbose]
# 兼容: RHEL8 / CentOS7 / Ubuntu20.04+ (Bash 4.2+)
set -euo pipefail
VERBOSE="${1:-}"
RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
log() { echo -e "$1"; }
header() { log "\n${YELLOW}===== $1 =====${NC}"; }
check() { local ok="$1" msg="$2"; if [[ "$ok" == "0" ]]; then log "  ${GREEN}[OK]${NC} $msg"; else log "  ${RED}[WARN]${NC} $msg"; fi; }

header "1. 系统级 fd 总览"
FILE_NR=$(awk '{print $1"/"$2" (max="$3")"}' /proc/sys/fs/file-nr)
log "  file-nr: $FILE_NR"
log "  fs.file-max: $(cat /proc/sys/fs/file-max)"
log "  fs.nr_open:  $(cat /proc/sys/fs/nr_open)"
log "  当前 shell ulimit: $(ulimit -n)"

header "2. Top 10 fd 持有进程"
log "  PID  PPID  CMD  FD_COUNT"
for pid in $(ls /proc | grep -E '^[0-9]+$' | head -200); do
  cnt=$(ls /proc/$pid/fd 2>/dev/null | wc -l)
  cmd=$(cat /proc/$pid/comm 2>/dev/null || echo "?")
  ppid=$(awk '{print $4}' /proc/$pid/stat 2>/dev/null || echo "?")
  echo "$cnt $pid $ppid $cmd"
done 2>/dev/null | sort -rn | head -10 | awk '{printf "  %-5s %-5s %-10s %s\n",$2,$3,$4,$1}'

header "3. 场景检查：Java 连接池 fd 泄漏"
JAVA_PIDS=$(pgrep -f java 2>/dev/null || true)
if [[ -n "$JAVA_PIDS" ]]; then
  for jp in $JAVA_PIDS; do
    jcnt=$(ls /proc/$jp/fd 2>/dev/null | wc -l)
    jtype=$(ls -la /proc/$jp/fd 2>/dev/null | awk '{print $9}' | grep -oE 'socket|pipe|/dev|anon_inode' | sort | uniq -c | sort -rn | head -3 | tr '\n' ' ')
    log "  PID=$jp fd=$jcnt 类型分布: $jtype"
    [[ "$jcnt" -gt 50000 ]] && log "  ${RED}[WARN] fd 数异常偏高，疑似连接池泄漏${NC}"
  done
else
  log "  未检测到 Java 进程"
fi

header "4. 场景检查：Nginx worker_connections"
if pgrep -x nginx >/dev/null 2>&1; then
  NGINX_PID=$(pgrep -n nginx)
  log "  nginx PID=$NGINX_PID limits: $(cat /proc/$NGINX_PID/limits 2>/dev/null | grep 'open files')"
  log "  配置: $(grep -E 'worker_connections|worker_rlimit' /etc/nginx/nginx.conf 2>/dev/null | tr '\n' ' ')"
  SS_COUNT=$(ss -tn 2>/dev/null | wc -l)
  log "  当前 TCP 连接数: $SS_COUNT"
else
  log "  未检测到 Nginx"
fi

header "5. 场景检查：Docker 容器 nofile"
if command -v docker >/dev/null 2>&1; then
  for cid in $(docker ps -q 2>/dev/null | head -5); do
    cname=$(docker inspect --format '{{.Name}}' "$cid" 2>/dev/null)
    climit=$(docker exec "$cid" cat /proc/self/limits 2>/dev/null | grep 'open files' | awk '{print $4"-"$5}')
    log "  容器 $cname: nofile=$climit"
  done
  log "  daemon.json ulimits: $(cat /etc/docker/daemon.json 2>/dev/null | grep -o 'nofile[^}]*' || echo '未配置')"
else
  log "  未检测到 Docker"
fi

header "6. 场景检查：inotify 使用量"
MAX_WATCH=$(cat /proc/sys/fs/inotify/max_user_watches)
CUR_WATCH=$(find /proc/*/fdinfo -exec grep -l 'inotify' {} \; 2>/dev/null | wc -l)
log "  max_user_watches: $MAX_WATCH"
log "  当前 inotify instance 数: $CUR_WATCH"
if [[ "$CUR_WATCH" -gt "$((MAX_WATCH * 80 / 100))" ]]; then
  log "  ${RED}[WARN] inotify 使用率 >80%${NC}"
fi

header "7. 场景检查：systemd LimitNOFILE"
SERVICES_WITH_LIMIT=$(systemctl list-units --type=service --state=running 2>/dev/null | grep -vE 'PID|systemd-' | awk '{print $1}' | while read svc; do
  lim=$(systemctl show "$svc" -p LimitNOFILE 2>/dev/null | cut -d= -f2)
  [[ -n "$lim" && "$lim" != "infinity" && "$lim" != "0" ]] && echo "$svc=$lim"
done)
if [[ -n "$SERVICES_WITH_LIMIT" ]]; then
  log "  以下服务设置了显式 LimitNOFILE:"
  echo "$SERVICES_WITH_LIMIT" | while read line; do log "    $line"; done
else
  log "  无服务显式设置 LimitNOFILE（继承系统默认）"
fi

header "8. 场景检查：fs.nr_open vs ulimit 一致性"
NR_OPEN=$(cat /proc/sys/fs/nr_open)
SHELL_ULIMIT=$(ulimit -n)
if [[ "$SHELL_ULIMIT" -gt "$NR_OPEN" ]]; then
  log "  ${RED}[WARN] ulimit($SHELL_ULIMIT) > fs.nr_open($NR_OPEN)，实际生效上限为 nr_open${NC}"
else
  log "  ${GREEN}[OK]${NC} ulimit($SHELL_ULIMIT) <= fs.nr_open($NR_OPEN)"
fi

header "9. 建议动作清单"
log "  1. 若 Top10 中某进程 fd > 50000，优先排查其连接池配置或文件句柄泄漏"
log "  2. Docker 容器 nofile=1024 的，立即在 daemon.json 或 compose ulimits 中调高至 65536+"
log "  3. inotify 使用率 >80% 的，执行 sysctl -w fs.inotify/max_user_watches=524288"
log "  4. fs.nr_open < 业务所需 ulimit 的，执行 sysctl -w fs.nr_open=1048576 并持久化"
log "  5. 所有修改后 systemctl restart 对应服务，用 /proc/<pid>/limits 验证实际生效值"
log ""
log "  ${GREEN}诊断完成。${NC}"

三、踩坑清单（10 条）

1. 现象：ulimit -n 1048576 设了但应用仍报 Too many open files 误判：以为 ulimit 没生效 根因：fs.nr_open 仍为 1048576 但 PAM 模块 pam_limits.so 在 session 层覆盖了硬限制 正确做法：cat /proc/sys/fs/nr_open 确认内核层上限；检查 /etc/pam.d/system-auth 中 pam_limits 顺序

2. 现象：Docker 容器内 ulimit -n 显示 1024，改 daemon.json 后 docker restart 无效 误判：以为配置没保存 根因：docker restart 只重启容器不重启 daemon；旧容器的 limit 已固化 正确做法：systemctl restart docker 后 docker rm -f 旧容器再 docker run 重建

3. 现象：Nginx 配置了 worker_rlimit_nofile 65536 但 worker 进程 limits 仍是 4096 误判：以为 nginx 配置优先级不够 根因：master 进程非 root 启动（如用 nginx -g 手动起），setrlimit 系统调用被拒 正确做法：确认 master 以 root 运行；ps aux | grep nginx 看 UID；用 systemd 管理

4. 现象：Java 应用 fd 数缓慢增长，重启后恢复，监控看不出异常 误判：以为是正常 TIME_WAIT 堆积 根因：Druid 连接池 maxActive=50 但 removeAbandoned 未开启，异常连接不归还 正确做法：开 removeAbandoned=true; logAbandoned=true；用 jcmd <pid> VM.native_memory 看 socket 对象数

5. 现象：filebeat 报 inotify_add_watch failed，调大 max_user_watches 后仍报错 误判：以为 watches 数不够 根因：filebeat 自身有 inotify.max_user_watches 上限参数（默认 512），独立于内核参数 正确做法：filebeat.yml 中设 inotify.max_user_watches: 524288；重启 filebeat

6. 现象：systemd override.conf 设了 LimitNOFILE=1048576，systemctl show 显示正确，但进程实际 limits 是 4096 误判：以为 systemd 没生效 根因：unit 文件中 LimitNOFILE 写在 [Unit] 段（应为 [Service] 段），被静默忽略 正确做法：systemctl cat <svc> 检查段归属；systemd-analyze verify <unit> 验证语法

7. 现象：fs.file-max 已设 2097152，但 cat /proc/sys/fs/file-nr 显示 allocated 逼近上限 误判：以为是某个进程泄漏 根因：file-max 是系统全局上限，多个进程 fd 总和逼近它；需看 per-process 分布 正确做法：遍历 /proc/*/fd | wc -l 找 top 进程；区分"单进程泄漏"vs"多进程正常累积"

8. 现象：K8s Pod 内 Java 应用报 Too many open files，kubectl exec 进 Pod 看 ulimit 正常 误判：以为 Pod limit 配了 根因：K8s resources.limits 不控制 nofile；需 DaemonSet 设 securityContext 或 node 级 docker daemon 配置 正确做法：node 级改 docker daemon.json；或 Pod spec 加 ulimits（K8s 1.25+）；或 sidecar 用 prlimit 动态改

9. 现象：lsof 命令卡死不返回，生产环境不敢用 误判：以为是 lsof bug 根因：lsof 遍历所有进程所有 fd，大进程（fd>100000）时 I/O 密集 正确做法：用 ls /proc/<pid>/fd | wc -l 替代；或 lsof -p <pid> -n -P 限定单进程；避免 lsof +D /

10. 现象：prlimit --pid <pid> --nofile=65536:65536 执行成功，但过几秒又回到 1024 误判：以为 prlimit 不持久 根因：应用内部有 setrlimit 调用（如 Go runtime 或 Docker entrypoint），把 limit 改回去了 正确做法：strace -e setrlimit -p <pid> 抓谁在改；修改应用启动脚本或 entrypoint 中的 ulimit 逻辑

四、README

# fd_exhaustion 诊断工具包

## 文件
- fd_exhaustion_handbook.md  — 排查手册（6 场景 × 五段式）
- fd_diagnose.sh             — 一键诊断脚本

## 运行
```bash
# 1. 拷贝到目标服务器
scp fd_diagnose.sh user@example.com:~/

# 2. 执行（无交互，约 10 秒完成）
bash fd_diagnose.sh

# 详细模式（输出更多中间数据）
bash fd_diagnose.sh --verbose

# 3. 查看输出
# 末尾"建议动作清单"给出 5 条可执行修复建议

依赖

• Bash 4.2+（RHEL8/CentOS7/Ubuntu20.04 均满足）
• 系统命令：ss、lsof、pgrep、systemctl、docker（可选）
• 无第三方库、无网络依赖

注意

• 脚本为只读诊断，不修改任何系统配置
• 生产环境执行安全，但 lsof 部分在大进程上可能耗时（已优化为 /proc 读取）