Linux 文件描述符耗尽排查实战:从 EMFILE、inotify 到 systemd 与 Docker 限额验收 原创

温馨提示:
本文最后更新于 2026-11-22,已超过 0 天没有更新。 若文章内的图片失效(无法正常加载),请留言反馈或直接 联系我。

服务报 OSError: [Errno 24] Too many open files 时,直接把 ulimit -n 从 1024 调到 65535,往往只能延后下一次故障。真正需要先回答的是:耗尽的是哪个资源、由哪个进程持有、FD 是否持续增长,以及新限额是否真正传到了目标进程。

本文给出一套可复现、可回退的排查路径:先用错误码区分进程级与系统级限制,再从 /proc 找到文件、Socket 或 inotify 的增长点,最后分别验证 systemd、Docker 与代码修复。所有复现命令只改变临时子进程的限额,不需要在生产环境做压测。

一、先分清 EMFILE、ENFILE 和 inotify 的 ENOSPC

文件描述符(FD)不仅指向普通文件。TCP/UDP Socket、管道、eventfd、epoll 和 inotify 实例也会占用 FD。进程每打开一个文件并不保证及时归还;连接池失控、异常分支漏关、子进程继承,都可能让数量只增不减。

现象/错误 优先检查 常见根因 不要误判为
EMFILE(errno 24) 进程的 RLIMIT_NOFILE 与 /proc/PID/fd/ FD 泄漏,或软限额低于正常连接峰值 磁盘空间不足
ENFILE(errno 23) fs.file-nr、fs.file-max 与全局句柄分配 系统级文件句柄表达到上限 仅当前进程超限
inotify_init 返回 EMFILE,或返回 ENOMEM fs.inotify.max_user_instances 同一 real UID 创建的 inotify 实例过多 单纯 watch 目录太多
inotify_add_watch 返回 ENOSPC fs.inotify.max_user_watches 与 fdinfo 同一 real UID 的 watch 总数达到上限;也可能是内核无法分配空间 一定还有磁盘配额问题
IN_Q_OVERFLOW 事件 fs.inotify.max_queued_events 与消费速度 事件生产快于应用读取,队列发生溢出 FD 数量达到上限

关键点:FD 上限、inotify 实例数、watch 数和事件队列长度是不同资源。尤其是 max_user_instances 与 max_user_watches 按 real UID 统计,不是简单地“每个进程各有一份”。共享宿主机 UID 的容器也可能互相影响;使用 user namespace 时则应结合实际 UID 映射判断。

先看错误日志与全局数据,但不要拿单机固定阈值生搬硬套:

cat /proc/sys/fs/file-nr
cat /proc/sys/fs/file-max
cat /proc/sys/fs/nr_open
sysctl fs.inotify.max_user_instances \
       fs.inotify.max_user_watches \
       fs.inotify.max_queued_events

file-nr 的三列依次是已分配文件句柄数、未使用句柄数(现代内核通常为 0)和系统最大值。第一列不能直接替代“某进程当前打开的 FD 数”。nr_open 则限制进程可设置的 FD 上限;即使管理员想继续提高 RLIMIT_NOFILE,也不能越过它。很多新系统的 file-max 非常大,此时看到 EMFILE 更应先查进程软限额,而不是继续加全局值。

二、确认目标进程的真实限额,而不是当前 Shell 的限额

下面用服务名 api.service 举例。先取主 PID,再读取内核实际应用的值:

systemctl show api.service \
  -p MainPID -p LimitNOFILE -p LimitNOFILESoft

PID=$(systemctl show api.service -p MainPID --value)
grep '^Max open files' "/proc/$PID/limits"
find "/proc/$PID/fd" -mindepth 1 -maxdepth 1 -printf '.' | wc -c

/proc/PID/limits 中 Max open files 的两列分别是 soft limit 和 hard limit。普通 open() 触及软限额就会返回 EMFILE,所以监控不应只看 hard limit。systemd 多进程服务还要检查工作进程;MainPID 只是入口,不代表所有 worker 都经过了手工调参。

检查方式 能证明什么 常见误区
ulimit -Sn 当前 Shell 的软限额 误以为 systemd 服务继承同一个 Shell
/proc/PID/limits 运行中进程的 soft/hard 限额 只看配置,没有核对进程
/proc/PID/fd/ 进程当前 FD 及其指向 把 lsof 输出的全部行数当作 FD 数
/etc/security/limits.conf 经 PAM 应用限制的登录会话 以为修改后所有守护进程自动生效

调整运行中 PID 可以使用 prlimit,但它只适合作为受控的临时处置:

# 需要相应权限;只改这个进程,重启后不会保留
sudo prlimit --pid "$PID" --nofile=32768:65536

# 再次读取,而不是仅凭命令退出码判断成功
grep '^Max open files' "/proc/$PID/limits"

提高运行中限额不能关闭已经泄漏的 FD,也不能修复代码。应同时保存快照并安排根因修复;不要为了“立刻恢复”而无上限调大,因为 FD 背后的 Socket、内存与连接对端也有成本。

三、给 FD 分类:找增长趋势,而不是只看一次总数

对目标进程采样两次,中间相隔一段正常业务窗口。下面命令只读取 procfs,不重启服务:

PID=12345   # 换成实际工作进程 PID
for round in 1 2 3; do
    date -Is
    find "/proc/$PID/fd" -mindepth 1 -maxdepth 1 -printf '.' | wc -c
    sleep 60
done

# 将具体目标归并为类型,先判断大头在哪里
for fd in /proc/$PID/fd/*; do
    sudo readlink "$fd"
done | sed -E \
  -e 's#^socket:\[[0-9]+\]$#socket#' \
  -e 's#^pipe:\[[0-9]+\]$#pipe#' \
  -e 's#^anon_inode:#anon_inode:#' \
  -e 's# \(deleted\)$# (deleted)#' \
  | sort | uniq -c | sort -nr | head -30

不同症状对应不同下一步:

  • Socket 持续增长:用 ss -tanp 找 TCP 状态和对端,再用 ss -xap 查 Unix Socket。若大量连接到同一个上游,优先检查 HTTP client/数据库连接池是否每次请求都新建而未复用,以及响应 body 是否完整关闭。
  • 普通文件或 (deleted) 项持续增长:检查日志滚动、临时文件和异常分支。已删除文件被进程持有时,磁盘空间也不会随 unlink 立即释放;这与“目录里还有同名文件”不是一回事。
  • pipe、eventfd、epoll 增长:排查子进程/线程任务是否反复创建而未回收。它们不会表现为普通的磁盘文件泄漏。
  • 总数稳定但业务仍报错:检查是否多个 worker 各自接近软限额、是否发生在新 fork/exec 的子进程,或错误其实来自 inotify watch/实例限制。

需要保留原始证据时,可以在变更前记录:

sudo ls -l "/proc/$PID/fd" > "/tmp/fd-$PID-before.txt"
sudo lsof -nP -p "$PID" > "/tmp/lsof-$PID-before.txt"
sudo ls -l "/proc/$PID/fd" | grep '(deleted)'

procfs 读取可能受权限与 hidepid 限制;失败时应在有授权的运维账户下执行,而不是把业务进程降权防护关掉。对高并发进程而言,读取期间列表也会变化,所以采样结果用于判断趋势,不应追求微秒级一致快照。

四、inotify 泄漏:用 fdinfo 看实例里到底有多少 watch

IDE 热重载、日志采集器、文件同步程序常使用 inotify。如果每次配置 reload 都创建一个新实例,旧实例却没有关闭,就可能先撞到 max_user_instances;如果递归监听不断增长或反复添加目录,则可能撞到 max_user_watches。

将下面脚本保存为 inotify-fds.py,以有权限的账户执行 python3 inotify-fds.py PID:

import os
import sys

pid = int(sys.argv[1])
fd_dir = f"/proc/{pid}/fd"
info_dir = f"/proc/{pid}/fdinfo"
instance_count = 0

for name in sorted(os.listdir(fd_dir), key=lambda x: int(x)):
    if not name.isdigit():
        continue
    try:
        target = os.readlink(os.path.join(fd_dir, name))
        if target != "anon_inode:inotify":
            continue
        with open(os.path.join(info_dir, name), encoding="utf-8") as f:
            lines = f.readlines()
    except (FileNotFoundError, PermissionError) as exc:
        print(f"fd={name}: {exc}")
        continue

    watches = sum(line.startswith("inotify wd:") for line in lines)
    inode = next((line.split()[1] for line in lines
                  if line.startswith("ino:")), "unknown")
    instance_count += 1
    print(f"fd={name} inode={inode} watches={watches}")

print(f"inotify fd count: {instance_count}")

一次已验证的采样中,创建实例后 readlink 返回 anon_inode:inotify,添加一个 watch 后 fdinfo 出现如下记录:

inotify wd:1 ino:1 sdev:2e mask:100 ignored_mask:0 ...

若多个 FD 指向同一实例(例如 dup 或 fork 继承),其 watch 列表可能重复出现,因此不能把所有 fdinfo 行简单相加,声称得到精确的 UID 全局 watch 数。上面脚本的用途是定位目标进程的实例与增长来源;跨进程汇总时还要去重,并检查同一 UID 的其他进程。

修复时不要只在“正常退出”路径释放资源。下面的 Python 封装保证创建 watch 失败或业务代码抛异常时也关闭实例。关闭最后一个引用该 inotify 实例的 FD 后,内核会释放关联 watch:

import ctypes
import os
from contextlib import contextmanager

libc = ctypes.CDLL(None, use_errno=True)

@contextmanager
def inotify_watch(path):
    fd = libc.inotify_init1(os.O_CLOEXEC)
    if fd < 0:
        err = ctypes.get_errno()
        raise OSError(err, os.strerror(err))
    try:
        wd = libc.inotify_add_watch(
            fd, os.fsencode(path), 0x00000100  # IN_CREATE
        )
        if wd < 0:
            err = ctypes.get_errno()
            raise OSError(err, os.strerror(err))
        yield fd, wd
    finally:
        os.close(fd)

# 用 with 约束生命周期;异常也会进入 finally
# with inotify_watch("/srv/app/uploads") as (fd, wd):
#     events = os.read(fd, 4096)  # 再按 struct inotify_event 解析

C/C++ 对应地使用 RAII,并在 open、socket、inotify_init1 等调用中使用 O_CLOEXEC、SOCK_CLOEXEC、IN_CLOEXEC,防止 fork+exec 意外继承。注意:O_CLOEXEC 解决的是跨 exec 继承,不会代替业务路径中的 close()。

五、systemd 与 Docker:让配置真正进入目标进程

systemd:用 drop-in 修改,不覆盖发行版 unit

sudo systemctl edit api.service

写入:

[Service]
# 左为 soft,右为 hard;数值应来自连接峰值与资源预算
LimitNOFILE=32768:65536

然后在维护窗口重启并验收。FD 限制在进程启动时继承,普通 reload 不能替代重启:

sudo systemctl daemon-reload
sudo systemctl restart api.service
systemctl show api.service -p LimitNOFILE -p LimitNOFILESoft
PID=$(systemctl show api.service -p MainPID --value)
grep '^Max open files' "/proc/$PID/limits"

回退时删除对应 drop-in 中的设置,再 daemon-reload 和重启。不要为了方便同时修改全局 DefaultLimitNOFILE,否则本来不受影响的系统服务也会改变资源边界。

Docker/Compose:ulimit 属于容器配置,不是业务镜像环境变量

启动容器时可以设置:

docker run -d --name api \
  --ulimit nofile=32768:65536 \
  your-registry/api:stable

Compose 对应写法:

services:
  api:
    image: your-registry/api:stable
    ulimits:
      nofile:
        soft: 32768
        hard: 65536

修改 Compose 后需要重建容器,并在容器内部验证。假设容器内目标进程为 PID 1:

docker compose up -d --force-recreate api
docker exec api sh -c 'ulimit -Sn; ulimit -Hn'
docker exec api sh -c "grep '^Max open files' /proc/1/limits"

Kubernetes 的 resources.limits 管理 CPU、内存等资源,并不提供跨运行时通用的 nofile 字段。不要把它误写成 Docker Compose 的 ulimits;应针对实际容器运行时与发行版设计节点级配置,再进入 Pod 验证目标进程限额。

六、隔离复现 EMFILE,并定义修复验收条件

下面的实验只把新启动的 Python 子进程限制为 64 个 FD,不修改宿主机 sysctl、当前 Shell 或其他服务:

prlimit --nofile=64:64 -- python3 - <<'PY'
import errno
import os

fds = []
try:
    while True:
        fds.append(os.open('/dev/null', os.O_RDONLY))
except OSError as exc:
    assert exc.errno == errno.EMFILE, exc
    print(f'EMFILE confirmed; opened before failure={len(fds)}')
finally:
    for fd in fds:
        os.close(fd)

probe = os.open('/dev/null', os.O_RDONLY)
os.close(probe)
print('close() released descriptors; open recovered')
PY

在本次 Linux 验证中,子进程打开 61 个 /dev/null 后得到 EMFILE,关闭后能重新打开。61 不是通用常数:标准输入/输出/错误等已占用的 FD 也计入同一个 64 限额。这个实验还解释了为什么在故障现场执行新的诊断命令也可能失败,以及为什么先保存证据比盲目扩大数值更重要。

验收项 通过条件
错误码与资源匹配 能区分普通 FD、inotify instance、watch 和 event queue,不再统一归因于 ulimit
限额生效 配置值与目标 PID 的 /proc/PID/limits 一致;容器内在容器命名空间验证
泄漏修复 相同业务负载与多轮 reload 后,FD/inotify 数量回落或稳定在可解释区间,而不是换个更大的上限继续增长
连接质量 上游连接数、TCP 状态、延迟与内存同步正常,没有将 FD 泄漏转移成上游连接耗尽
回退可行 保留原配置和变更前快照;明确 drop-in、Compose 重建与代码版本的回退步骤

最终原则只有一句:先修复持有与释放的生命周期,再按可观测的业务峰值配置限额。没有增长趋势和分类证据时,单纯调大 nofile 只是把故障推迟。

参考文档: