Debian/Ubuntu: как исправить stale file handle в NFS

Ошибка stale file handle в NFS редко возникает без причины. Обычно она появляется после вполне конкретного события: перезагрузки NFS-сервера, переэкспорта каталога, удаления и повторного создания директории, изменения inode на серверной стороне, отката snapshot или переключения хранилища.

На клиенте это выглядит неприятно: часть путей перестаёт открываться, команды зависают или сразу отвечают сообщением Stale file handle, а приложение получает ошибки чтения и записи. При этом сам mount может числиться активным, из-за чего проблема маскируется под «странный NFS», хотя реальная причина — устаревший файловый дескриптор.

Ключевой момент в том, что NFS-клиент работает не только с путями, но и с файловыми идентификаторами. Если объект на сервере был заменён, удалён, восстановлен из бэкапа или сервер после перезапуска начал отдавать другой handle, старые ссылки на клиенте становятся невалидными.

Ниже разберём безопасную схему диагностики, типовые сценарии, команды для Debian и Ubuntu, а также порядок действий, если mount занят процессами или частично подвис.

Что означает stale file handle в NFS

Если упростить, stale file handle означает: клиент NFS хранит ссылку на файловый объект, но сервер больше не может сопоставить эту ссылку с реальным файлом или каталогом. Имя пути может не измениться, но для NFS это уже другой объект.

Частые причины проблемы:

• каталог на сервере удалили и создали заново с тем же именем;
• данные восстановили из бэкапа или snapshot, из-за чего изменились inode;
• NFS-сервер перезагрузился или переключился на другую ноду;
• экспортируемый путь был перемонтирован на сервере;
• поверх старого дерева данных сделали bind mount или переключили storage;
• клиентские процессы держат старые дескрипторы на уже изменённые объекты.

Если после перезагрузки NFS-сервера ошибка появилась только у части процессов, проблема обычно не в сети, а в том, что приложения продолжают работать со старыми файловыми дескрипторами.

Из-за этого не всегда нужно сразу перемонтировать весь ресурс. Иногда достаточно остановить конкретный сервис, который держит устаревшие handle, и запустить его заново.

Как быстро подтвердить, что проблема именно в NFS

Начните с проверки типа файловой системы и параметров монтирования. Удобнее всего использовать findmnt.

findmnt -t nfs,nfs4

Для проверки конкретной точки монтирования:

findmnt /mnt/data

Если нужны источник и опции mount:

findmnt -no SOURCE,TARGET,FSTYPE,OPTIONS /mnt/data

Дальше проверьте сообщения ядра о stale handle, RPC и таймаутах:

dmesg -T | grep -Ei 'nfs|stale|rpc'

journalctl -k -b | grep -Ei 'nfs|stale|rpc'

Минимальная быстрая проверка самого каталога:

ls -la /mnt/data

stat /mnt/data

При stale handle одна команда может зависнуть, а другая вернуть ошибку сразу. Это нормальная картина для такого сбоя.

Проверка доступности сервера и экспорта

Следующий шаг — убедиться, что проблема не в банальной недоступности сервера или сломанном экспорте.

showmount -e nfs-server

rpcinfo -p nfs-server

Если сервер отвечает и экспорт виден, значит чаще всего проблема именно в устаревших файловых идентификаторах на клиенте.

Если у вас NFS используется как общее хранилище для приложений, полезно заранее понимать, где такая схема оправдана, а где лучше выбрать другой подход. На эту тему может пригодиться материал про сравнение NFS и SSHFS для сетевого хранилища.

Облачный VDS-сервер в России

Аренда виртуальных серверов с моментальным развертыванием инфраструктуры от 195₽ / мес

Подробнее

Для проектов, где важны предсказуемые ресурсы, контроль над системой и собственная схема хранения, чаще выбирают VDS. Это особенно актуально, если нужно отдельно управлять NFS-клиентами, systemd-юнитами и сетевыми параметрами без ограничений общего окружения.

Типовые сценарии, в которых возникает ошибка

Перезагрузка или failover NFS-сервера

Это самый частый случай. Сервер уже снова доступен, но часть long-running процессов на клиентах остаётся со старыми handle. Особенно заметно это у фоновых сервисов, очередей задач, медиасканеров, backup-агентов и приложений, которые долго держат открытые файлы.

Каталог удалили и создали заново

Для администратора путь может выглядеть прежним, например /export/data/uploads. Но с точки зрения NFS это уже другой объект, потому что inode и file handle изменились. Все клиенты, которые держали старую ссылку, начинают получать stale.

Восстановление из snapshot или backup

После отката файловой системы структура каталогов может казаться прежней, но внутренние идентификаторы файлов меняются. Если клиенты не были перезапущены или не перемонтировали экспорт, вероятность stale резко возрастает.

Неудачное обновление приложения

Иногда ошибка появляется после деплоя, когда релизный каталог заменяют целиком, а не обновляют содержимое внутри него. На локальной файловой системе такой подход часто проходит безболезненно, а на NFS бьёт по уже открытым дескрипторам.

Пошаговая диагностика на клиенте Debian/Ubuntu

Ниже — рабочий порядок действий, который удобно держать в runbook дежурного администратора.

1. Посмотреть текущее состояние mount

mount | grep nfs

findmnt -t nfs,nfs4 -o TARGET,SOURCE,FSTYPE,OPTIONS

Сразу запишите точку монтирования, адрес сервера, версию протокола и опции. Это пригодится, если mount придётся собирать вручную.

2. Найти процессы, использующие проблемный путь

Для этого удобны lsof и fuser. На проблемном NFS некоторые проверки сами могут подвисать, поэтому лучше начинать с наиболее точечного варианта.

lsof /mnt/data

lsof +D /mnt/data

fuser -vm /mnt/data

На этом этапе важно понять, держит ли каталог веб-сервер, worker, rsync, backup-задача, shell-сессия или контейнерный runtime.

3. Проверить процессы в D-state

Если unmount не проходит, причиной могут быть процессы в непрерываемом ожидании ввода-вывода.

ps -eo pid,stat,comm,wchan:32,args | awk '$2 ~ /^D/ {print}'

Если такие процессы есть, сначала оцените последствия их остановки. Иногда безопаснее перезапустить приложение, чем немедленно ломать mount.

4. Проверить базовые операции внутри каталога

cd /mnt/data

pwd

stat .

ls -lid .

Если текущий каталог stale, даже простые команды начинают вести себя нестабильно. Чаще всего это быстро видно по stat.

Как безопасно исправить stale file handle

На практике почти всегда помогает один из трёх подходов: перезапуск процессов, перемонтирование NFS или сочетание обоих.

Вариант 1. Перезапустить только использующие NFS процессы

Если проблема локализована в конкретном приложении, а сам mount ещё отвечает, начните с перезапуска сервиса.

systemctl stop myapp.service

fuser -vm /mnt/data

systemctl start myapp.service

Это хороший вариант для stateless-сервисов и worker-процессов, когда не хочется трогать весь mount.

Вариант 2. Сделать unmount и mount заново

Когда stale затронул саму точку монтирования или несколько процессов сразу, обычно нужен полный цикл отмонтирования и нового mount.

Сначала попробуйте обычный umount:

umount /mnt/data

Если mount занят, ещё раз проверьте процессы и остановите всё, что активно пишет в ресурс. После этого повторите:

umount /mnt/data

Затем смонтируйте ресурс заново:

mount /mnt/data

Или явно укажите источник:

mount -t nfs4 nfs-server:/export/data /mnt/data

Если обычный unmount не проходит, можно использовать ленивое отмонтирование:

umount -l /mnt/data

umount -l — аварийный инструмент. Он убирает mount из пространства имён сразу, но не решает корневую причину и не отменяет необходимость разобраться с процессами, которые держали старые дескрипторы.

Вариант 3. Перемонтировать после восстановления сервера

Если первопричина была на стороне NFS-сервера, сначала убедитесь, что экспорт снова стабильно доступен, и только потом перемонтируйте ресурс на клиентах. Иначе можно получить повтор ошибки или зависшие процессы при попытке доступа к ещё неготовому storage.

1. Убедиться, что сервер отвечает.
2. Проверить экспорт.
3. Остановить приложения, активно работающие с mount.
4. Сделать unmount.
5. Смонтировать ресурс заново.
6. Проверить findmnt, stat и тестовую запись.
7. Вернуть приложения в работу.

Если на NFS лежат PHP-сессии или временные данные веб-приложения, отдельно проверьте поведение после restart. Здесь может быть полезен материал про хранение PHP-сессий на NFS и работу garbage collection.

Что делать, если umount не удаётся

Самая частая причина — процессы удерживают текущий каталог, открытые файлы или рабочие дескрипторы. Иногда это не приложение, а обычная shell-сессия администратора, которая стоит внутри проблемного пути.

Быстрый минимум проверки:

pwd

fuser -vm /mnt/data

При необходимости завершайте процессы корректно:

kill -TERM 1234

Если сервисом управляет systemd, лучше останавливать его через systemctl, а не вручную убивать дочерние процессы.

Действовать лучше по нарастающей: остановка приложения, обычный umount, затем при необходимости umount -l. Попытка силой разрушить mount без понимания, шли ли записи, может закончиться потерей данных на уровне приложения.

Для небольших сайтов и сервисов, где NFS не нужен как отдельный слой инфраструктуры, иногда рациональнее упростить схему и использовать виртуальный хостинг или пересмотреть архитектуру хранения. Чем меньше лишних точек отказа, тем проще сопровождение.

Виртуальный хостинг для сайтов

Универсальное решение для создания и размещения сайтов любой сложности в Интернете от 95₽ / мес

Подробнее

Проверка после восстановления

После перемонтирования важно убедиться не только в том, что команда mount отработала без ошибки, но и в том, что файловая система реально работает.

findmnt /mnt/data

stat /mnt/data

touch /mnt/data/.nfs-healthcheck

ls -la /mnt/data/.nfs-healthcheck

rm -f /mnt/data/.nfs-healthcheck

Если mount используется приложением, дополнительно проверьте его типичный сценарий: чтение файла, создание временного файла, переименование и запись небольшого объекта.

Как снизить риск повторения stale file handle

Не пересоздавайте экспортируемые каталоги без необходимости

Если нужно обновить содержимое, по возможности меняйте файлы внутри каталога, а не удаляйте и не создавайте заново сам корневой путь экспорта.

Осторожнее со snapshot и rollback

Любой откат на стороне NFS-сервера стоит сопровождать понятным runbook для клиентов: что останавливаем, что перемонтируем, что проверяем после возврата сервиса.

Используйте штатные процедуры обслуживания

Перед работами на NFS полезно остановить чувствительные клиентские приложения, особенно те, что долго держат открытые файлы: индексацию, фоновую обработку, backup, sync и медиасканеры.

Следите за архитектурой приложения

Если сервис болезненно переживает любой restart storage и регулярно держит массу файловых дескрипторов, проблема может быть не только в NFS. Иногда правильнее вынести часть данных на локальный кеш, в объектное хранилище или на отдельный сервис хранения.

Чем дольше живёт процесс и чем активнее он держит открытые файлы на NFS, тем выше шанс встретить stale file handle сразу после серверных работ или failover.

Краткий runbook для дежурного администратора

1. Проверить findmnt -t nfs,nfs4 и определить проблемную точку монтирования.
2. Посмотреть dmesg и journalctl -k на сообщения NFS, RPC и stale.
3. Проверить доступность сервера и экспорта.
4. Найти процессы через fuser -vm и lsof.
5. Остановить сервисы, работающие с проблемным mount.
6. Сделать umount, при необходимости umount -l.
7. Смонтировать ресурс заново.
8. Проверить stat, тестовое чтение и запись.
9. Вернуть приложения в работу и убедиться, что старые дескрипторы исчезли.

Итог

Ошибка stale file handle в Debian и Ubuntu почти всегда означает не «сломанный Linux», а рассинхронизацию между файловым объектом, который помнит клиент, и тем, что реально осталось на стороне NFS-сервера.

Практически лучший подход такой: проверить mount через findmnt, посмотреть логи ядра, убедиться в доступности экспорта, найти процессы через lsof и fuser, затем аккуратно остановить затронутые сервисы и перемонтировать ресурс. В большинстве инцидентов этого достаточно, чтобы вернуть систему в рабочее состояние без хаотичных действий.

А если stale file handle появляется регулярно, уже стоит смотреть глубже: как устроен экспорт, не пересоздаются ли каталоги во время деплоя, как приложения переживают failover и не пора ли обновить внутренний runbook обслуживания NFS.