Linux 文件描述符耗尽排查实战:从 EMFILE、inotify 到 systemd 与 Docker 限额验收 原创
服务报 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 只是把故障推迟。
参考文档: