Слідкування за файлами в Docker ламається в контейнерах — надійно виправте гаряче перезавантаження

Гаряче перезавантаження працює аж до того моменту, коли ви запаковуєте додаток у контейнер, монтуєте код — і раптом ваш спостерігач тихо йде у відпустку. Ви зберігаєте файл. Нічого не перезбирається. Зберігаєте ще раз. І знову нічого. Потім перезапускаєте контейнер і — звісно — він «працює» десять хвилин і знову ламається, як ненадійний датчик диму.

Це не ваша вина. Це брудне перетинання API подій файлової системи, шарів віртуалізації, мережевих шарів, які видають себе за локальні диски, та інструментів розробки, що припускають, що хост — «звичайний Linux». Зробімо відстеження файлів знову нудним.

Що насправді ламається (і чому це непослідовно)

Більшість систем гарячого перезавантаження залежить від повідомлень про події файлової системи на рівні ядра:

• Linux: inotify (зазвичай через бібліотеки на кшталт chokidar, watchdog або fsnotify)
• macOS: FSEvents / kqueue
• Windows: ReadDirectoryChangesW

Ці API були спроектовані з простим припущенням: «процес, що спостерігає події, запускається на тій самій машині, яка володіє файловою системою». Розробка в Docker порушує це припущення кількома способами:

• Bind-mounts перетинають межі. Ваш контейнер може бути Linux, але фактичні файли можуть жити на macOS APFS, Windows NTFS, WSL2 VHDX або на мережевому шарі.
• Пересилання подій неповне. Події файлів можуть не поширюватися правильно через шари віртуалізації, і навіть коли вони поширюються, вони можуть затримуватися, об’єднуватися або губитися.
• Спостерігачі не дешеві. Багато інструментів спостерігають великі дерева директорій і досягають лімітів inotify, лімітів файлових дескрипторів або навантаження CPU. Всередині контейнерів ці ліміти можуть бути нижчими або їх легше перевищити.
• Редактори «творчі». Деякі редактори зберігають файли атомарно (запис тимчасового файлу, потім перейменування), що змінює шаблон подій. Деякі спостерігачі це коректно обробляють, деякі — ні.

Якщо взяти одне правило: відстеження файлів — це не одна «фіча». Це конвеєр. Будь-яка слабка ланка — файловий шар, драйвер монтовання, шар віртуалізації, ліміти ядра, реалізація спостерігача — робить гаряче перезавантаження ненадійним. Ваше завдання — ідентифікувати найслабше місце й перестати вірити, що воно само собою виправиться.

Жарт #1: Спостерігачі файлів схожі на малюків: якщо ви перестанете їх контролювати на 30 секунд, вони зроблять щось тривожне і відмовляться пояснити, чому.

Як виглядає «поламано» на практиці

Ці режими відмов з’являються регулярно:

• Ніяких подій взагалі. Ваш інструмент ніколи не перезбирається, якщо ви не перезапустите його.
• Події приходять із затримкою. Ви зберігаєте файл, а перезбірка відбувається через 5–30 секунд, інколи пачками.
• Часткове відстеження. Деякі директорії тригерять перезбірки, інші — ніколи.
• Високе навантаження CPU при опитуванні. Ви «вирішили» проблему опитуванням і тепер вентилятор ноутбука претендує на роботу дрону.
• Працює на Linux-хості, ламається на Docker Desktop. Класичний сюрприз при bind-mount на macOS/Windows.

Швидкий план діагностики

Коли гаряче перезавантаження відмовляє, не починайте з трьох змін налаштувань у надії. Почніть з швидких відповідей на три питання:

1) Чи доходять події файлів взагалі до контейнера?

Перевірка: inotify-події всередині контейнера за допомогою мінімального інструменту. Якщо ви не можете спостерігати події напряму, ви займаєтеся чутками.

Рішення:

• Якщо подій немає: це проблема пересилання через mount/віртуалізацію або ви насправді не редагуєте змонтований шлях.
• Якщо події є, але ваш інструмент не реагує: проблема в налаштуванні спостерігача або обмеженні конкретного інструменту.

2) Чи досягаєте ви лімітів inotify/watch або лімітів відкритих файлів?

Перевірка: sysctls inotify, відкриті файли, логи інструмента.

Рішення:

• Якщо ліміти низькі: підніміть їх на хості (а іноді й у контейнері) і звузьте область спостереження.
• Якщо ліміти в порядку: рухайтеся далі — не робіть sysctl-зміни за традицією без причини.

3) Чи настільки повільний mount, що ваш спостерігач «здається»?

Перевірка: продуктивність bind-mount; спостереження за CPU та I/O. На macOS/Windows mount може бути значно повільнішим за рідні Linux-файлові системи.

Рішення:

• Якщо mount повільний: перемістіть важливі шляхи (node_modules, артефакти збірки) у volume-контейнера; розгляньте інструменти синхронізації; або перейдіть на опитування з розумними інтервалами.
• Якщо mount швидкий: зосередьтеся на налаштуванні інструмента та коректності подій.

Цікаві факти та історичний контекст

Відстеження файлів у контейнеризованому середовищі здається сучасним, але базові проблеми старші за більшість фронтенд-фреймворків. Ось кілька фактів, які допомагають пояснити сьогоднішню дивність:

1. inotify з’явився в Linux 2.6.13 (2005). До того багато інструментів використовували періодичне сканування. Опитування — старомодно, але й передбачувано.
2. inotify не є рекурсивним. Спостерігач повинен додавати спостереження для кожної директорії. Великі репозиторії можуть вимагати десятків тисяч watches.
3. Ранній Docker на macOS використовував osxfs. Він був відомий проблемами продуктивності й дивними подіями. Сучасний Docker Desktop пройшов через gRPC-FUSE та інші підходи, але крайові випадки залишилися.
4. Атомарні схеми збереження змінили правила гри. Редактори, що «пишуть тимчасовий файл + перейменування», генерують послідовності move/unlink/create; наївні спостерігачі трактують це як видалення і перестають відстежувати.
5. fs.watch у Node має платформні особливості. Багато екосистем стандартизувалися на chokidar, бо fs.watch був непослідовним між ОС, особливо для мережевих і віддалених монтувань.
6. WSL2 використовує віртуалізовану Linux-файлову систему. Доступ до Linux-файлів з Windows-шляхів і навпаки проходить через шар трансляції, що впливає і на швидкість, і на семантику подій.
7. Kubernetes популяризував шаблони синхронізації через sidecar. Робочі потоки розробки запозичили ці ідеї: тримати джерело на хості, синхронізувати в контейнер, відстежувати всередині контейнера на рідній файловій системі.
8. Watchman з’явився, бо великі дерева ламають наївні спостерігачі. Watchman від Meta існує заради продуктивності й коректності в масштабі; це нагадування, що «просто стежити за директорією» не тривіально.

Практичні завдання: команди, очікуваний вивід і рішення

Нижче — практичні завдання, які ви можете виконати. Кожне завдання містить: команду, що означає вивід, і рішення, які варто прийняти. Виконуйте їх на хості або всередині контейнера за зазначенням. Це має покласти край здогадкам.

Завдання 1: Підтвердіть, що ви редагуєте змонтований шлях, який вважаєте

cr0x@server:~$ docker compose exec app sh -lc 'pwd; ls -la; mount | head'
/app
total 48
drwxr-xr-x    1 root     root          4096 Jan  3 10:12 .
drwxr-xr-x    1 root     root          4096 Jan  3 10:12 ..
-rw-r--r--    1 root     root          1283 Jan  3 10:10 package.json
...
overlay on / type overlay (rw,relatime,lowerdir=...,upperdir=...,workdir=...)

Що це означає: Ви підтверджуєте робочу директорію контейнера та наявні файли. Якщо файл, який ви редагуєте на хості, тут відсутній — ви не тестуєте відстеження, а свої уявлення.

Рішення: Якщо директорія не відповідає очікуваному місцю монтування, виправте відповідність volumes: у Compose спочатку.

Завдання 2: Перегляньте mount-и контейнера і знайдіть bind mount

cr0x@server:~$ docker inspect app --format '{{json .Mounts}}'
[{"Type":"bind","Source":"/Users/alex/work/myapp","Destination":"/app","Mode":"rw","RW":true,"Propagation":"rprivate"}]

Що це означає: Ви бачите, чи це bind mount або іменований том. Bind mount-и — це місце, де живуть проблеми з пересиланням подій між ОС.

Рішення: Якщо ви на macOS/Windows і це bind mount, вважайте його «можливо втратним» для подій, поки не доведете зворотнє.

Завдання 3: Доведіть, що inotify-події видимі всередині контейнера

cr0x@server:~$ docker compose exec app sh -lc 'apk add --no-cache inotify-tools >/dev/null; inotifywait -m -e modify,create,delete,move /app'
Setting up watches.
Watches established.

Тепер відредагуйте файл на хості під цим монтуванням і спостерігайте вивід:

cr0x@server:~$ # (after saving /app/src/index.js on the host)
./ MODIFY src/index.js

Що це означає: Якщо ви бачите події, ядро всередині контейнера отримує щось, що виглядає як зміни файлів.

Рішення: Якщо нічого не видно, перестаньте звинувачувати додаток. Це пересилання mount/подій або ви редагуєте поза змонтованим деревом.

Завдання 4: Якщо події відсутні, порівняйте з змінами, зробленими всередині контейнера

cr0x@server:~$ docker compose exec app sh -lc 'echo "# test" >> /app/src/index.js'

cr0x@server:~$ # inotifywait output
./ MODIFY src/index.js

Що це означає: Якщо правки всередині контейнера створюють події, а правки з хоста — ні, шар монтування відкидає або не пересилає події.

Рішення: Рухайтеся в бік workflow-ів типу sync-into-container або використовуйте polling-спостерігачі на macOS/Windows.

Завдання 5: Перевірте ліміти inotify (хост і контейнер)

cr0x@server:~$ docker compose exec app sh -lc 'cat /proc/sys/fs/inotify/max_user_watches; cat /proc/sys/fs/inotify/max_user_instances'
8192
128

Що це означає: 8192 watches часто замало для сучасних JS-репозиторіїв, монореп, або чогось із глибокими деревами залежностей.

Рішення: Якщо ваш проект нетривіальний, підніміть ці ліміти на хості (і переконайтеся, що контейнер їх бачить, якщо це релевантно). На Linux-хості ліміти inotify — це налаштування ядра хоста.

Завдання 6: Підвищення лімітів inotify на Linux-хості (тимчасово й постійно)

cr0x@server:~$ sudo sysctl -w fs.inotify.max_user_watches=524288
fs.inotify.max_user_watches = 524288

cr0x@server:~$ sudo sh -lc 'printf "fs.inotify.max_user_watches=524288\nfs.inotify.max_user_instances=1024\n" >/etc/sysctl.d/99-inotify.conf && sysctl --system | tail -n 3'
* Applying /etc/sysctl.d/99-inotify.conf ...
fs.inotify.max_user_watches = 524288
fs.inotify.max_user_instances = 1024

Що це означає: Ви прибрали звичайну межу, що змушує спостерігачів помирати мовчки або працювати частково.

Рішення: Якщо це вирішує проблему, збережіть постійні налаштування; потім звузьте область спостереження, щоб ви не стежили за всесвітом.

Завдання 7: Виявлення помилок «виснаження watch» у типових інструментах розробки

cr0x@server:~$ docker compose logs -f app | egrep -i 'ENOSPC|inotify|watch|too many|EMFILE' || true
Error: ENOSPC: System limit for number of file watchers reached, watch '/app/src'

Що це означає: ENOSPC у цьому контексті не «закінчився диск». Це «немає вільних дескрипторів для спостереження». EMFILE — «занадто багато відкритих файлів».

Рішення: Підніміть ліміти і звузьте область спостереження; не переходьте просто на агресивне опитування і називайте це вирішенням.

Завдання 8: Підтвердіть ліміти відкритих файлів всередині контейнера

cr0x@server:~$ docker compose exec app sh -lc 'ulimit -n; cat /proc/self/limits | grep "Max open files"'
1048576
Max open files            1048576              1048576              files

Що це означає: Ліміти файлових дескрипторів, ймовірно, не є вузьким місцем, якщо вони такі високі, але не припускайте — перевірте.

Рішення: Якщо ulimit -n низький (1024/4096), підніміть його через налаштування Docker/Compose або середовище вашої оболонки.

Завдання 9: Виміряйте затримку bind-mount за допомогою грубої, але ефективної fs-тесту

cr0x@server:~$ docker compose exec app sh -lc 'time sh -c "for i in $(seq 1 2000); do echo $i >> /app/.watchtest; done"'
real    0m3.421s
user    0m0.041s
sys     0m0.734s

Що це означає: Це не бенчмарк, а smoke test. На повільних монтуваннях прості повторні додавання можуть бути несподівано дорогими.

Рішення: Якщо це повільно (секунди для невеликих циклів), ваш інструмент спостереження може запізнюватися, а опитування може плавити CPU. Розгляньте підхід синхронізації або перемістіть важкі директорії з монтування.

Завдання 10: Розділіть «монтування коду» від «залежностей/артефактів збірки»

cr0x@server:~$ cat docker-compose.yml | sed -n '1,120p'
services:
  app:
    volumes:
      - ./:/app
      - node_modules:/app/node_modules
volumes:
  node_modules:

Що це означає: Ви тримаєте вихідний код на bind mount (редагований), але залежності живуть у volume, яким керує контейнер (швидко, послідовно, менше подій).

Рішення: Якщо ваші інструменти спостерігають node_modules (не повинні), це зменшить шум і навантаження на події.

Завдання 11: Переконайтеся, що ваш спостерігач випадково не стежить за зайвим сміттям

cr0x@server:~$ docker compose exec app sh -lc 'node -p "process.cwd()"; node -p "require(\"chokidar\").watch(\"/app\", {ignored: [/node_modules/, /dist/] }).getWatched ? \"ok\" : \"unknown\""' 
/app
ok

Що це означає: Багато інструментів для спостереження можна налаштувати на ігнорування важких шляхів. Якщо ви не ігноруєте вихідні збірки, можете створити петлі перезбірки і вибухи спостереження.

Рішення: Додайте явні ігнорування для node_modules, dist, .next, target, build тощо, залежно від вашого стеку.

Завдання 12: Примусово включіть опитування як контрольний експеримент (не як релігію)

cr0x@server:~$ docker compose exec app sh -lc 'CHOKIDAR_USEPOLLING=true CHOKIDAR_INTERVAL=250 npm run dev'
> dev
> vite
[vite] hot reload enabled (polling)

Що це означає: Опитування усуває залежність від пересилань подій на кшталт inotify. Якщо опитування працює стабільно, шар пересилання подій — слабка ланка.

Рішення: Якщо опитування виправляє коректність, але CPU підіймається — рухайтеся до sync-into-container або до швидшого бекенду для шарів файлообміну, замість того щоб зменшувати інтервали до 50ms як гримучий троль.

Завдання 13: Перевірте, чи зміни засновані на перейменуванні (atomic save) і чи інструмент це обробляє

cr0x@server:~$ docker compose exec app sh -lc 'inotifywait -m -e close_write,move,create,delete /app/src'
Setting up watches.
Watches established.
./ MOVED_TO index.js
./ MOVED_FROM .index.js.swp
./ CLOSE_WRITE,CLOSE index.js

Що це означає: Ви можете бачити патерни move/rename замість простого MODIFY. Деякі спостерігачі не вміють повторно прив’язуватися до переміщених файлів, якщо вони відстежують файли замість директорій.

Рішення: Налаштуйте інструмент на відстеження директорій, а не окремих файлів, і переконайтеся, що він обробляє події перейменування. Або змініть налаштування редактора щодо «safe write» для цього репозиторію.

Завдання 14: Визначте, чи ваш проект знаходиться на «неправильній» файловій системі у WSL2

cr0x@server:~$ docker compose exec app sh -lc 'df -T /app | tail -n 1'
/dev/sdb        ext4   25151404  8123456  15789012  34% /app

Що це означає: У WSL2 краща продуктивність і поведінка подій зазвичай досягається, якщо код зберігати у Linux-файловій системі (ext4 у віртуальній машині), а не на Windows-монтуванні.

Рішення: Якщо ви бачите щось на кшталт drvfs або шлях, змонтований із Windows, розгляньте перенесення репозиторію в Linux-файлову систему.

Кореневі причини за платформами: Linux, macOS, Windows/WSL2

Linux-хост (рідний Docker Engine): «відносно адекватна» базова ситуація

Якщо ваш хост — Linux і ви використовуєте Docker Engine напряму, відстеження файлів зазвичай працює. Коли не працює, то зазвичай через одне з наступного:

• ліміти inotify занадто низькі для великих репозиторіїв
• зона спостереження занадто широка (відстеження node_modules, директорій збірки, vendor)
• дивні випадки з overlayfs + bind mount
• інструменти відстежують файли, а не директорії і пропускають атомарні збереження

Хороша новина: більшість із цього можна виправити через sysctl, ігнорування та розумні патерни монтування.

macOS (Docker Desktop): поділ файлів — податок, який ви сплачуєте

На macOS Docker запускає Linux-контейнери у VM. Ваш bind mount перетинає APFS і ту VM через шар файлового обміну. Цей шар намагається транслювати події macOS у щось, що Linux-контейнери можуть споживати. «Намагається» — це багато сказано.

Найпоширеніші реалії macOS:

• Події можуть об’єднуватися або затримуватися. Ваш інструмент бачить вибухи замість реального часу.
• Деякі типи подій погано транслюються. Патерни move/rename можуть плутати спостерігачів.
• Продуктивність може бути справжньою проблемою. Спостереження працює, але його задушують повільні операції з метаданими.

На macOS «правильна» відповідь для серйозних команд часто така: тримайте робочу файлову систему контейнера нативною (volume) і синхронізуйте код у неї.

Windows + Docker Desktop: обирайте поле бою уважно

Windows додає ще один шар трансляції: семантика NTFS, Windows API повідомлень файлів та Linux VM Docker. Якщо додати WSL2, ви отримаєте матрьошку файлових систем.

Практичні поради:

• Найкращий варіант для WSL2: тримайте репозиторій у Linux-файловій системі (не на змонтованому Windows-диску), запускайте Docker/Compose звідти.
• Найгірший варіант: редагувати файли у Windows, монтувати їх у контейнер у Linux-VM і очікувати ідеальної семантики inotify. Цей шлях закінчується опитуванням.

Виправлення, що працюють: від «достатньо» до «робочого досвіду для продакшен-розробки»

Цей розділ суб’єктивний, тому що вам треба доставити код, а не проводити симпозіум з теорії файлових систем.

Рівень виправлення 1: Зробіть inotify успішним на Linux (ліміти + область)

Якщо ви на Linux-хості і все ще маєте проблеми, зробіть це в порядку:

1. Підніміть ліміти inotify (Завдання 5/6).
2. Припиніть спостерігати сміття: ігноруйте node_modules, вихідні збірки, кеші.
3. Відстежуйте директорії, а не окремі файли, щоби пережити атомарні збереження.
4. Не монтуйте залежності з хоста: використовуйте volume для node_modules, vendor тощо.

Якщо зробите ці чотири кроки, більшість Linux-хостованих dev-контейнерів поводяться як звичайне дев-середовище.

Рівень виправлення 2: Контрольоване опитування (коли пересилання подій непевне)

Опитування не ганебне. Воно детерміноване. Воно також причина, чому акумулятор вашого ноутбука подає скаргу в HR.

Використовуйте опитування, коли:

• inotify-події не з’являються для правок з хоста (Завдання 4 показує невідповідність)
• платформа — macOS/Windows і потрібно швидке надійне рішення сьогодні

Як зробити опитування терпимим:

• Опитуйте лише потрібні директорії джерела.
• Використовуйте розумні інтервали (200–1000ms залежно від розміру репозиторію).
• Вимкніть спостереження для великих згенерованих дерев.

Приклади, які ви побачите в реальності:

• Інструменти на базі Chokidar: CHOKIDAR_USEPOLLING=true, інколи з CHOKIDAR_INTERVAL.
• Webpack: watchOptions.poll
• Python watchdog: WATCHDOG_USE_POLLING=true (залежить від інструмента)
• Rails: перейдіть на polling file watcher або змініть бекенд у listen gem

Рівень виправлення 3: Синхронізуйте код у контейнерну нативну файлову систему («нудно правильний» підхід)

Якщо ви хочете, щоб гаряче перезавантаження поводилося як у Linux, дайте контейнеру Linux-файлову систему для спостереження. Це означає:

• Помістіть робоче дерево в іменований volume (швидко, нативно у VM).
• Синхронізуйте вихідний код з хоста → volume (односторонньо або двосторонньо) за допомогою інструмента синхронізації.
• Запускайте спостерігачі всередині контейнера проти шляху volume.

Це зменшує або усуває проблеми з пересиланням подій, бо відстеження відбувається на справжній Linux-файловій системі, а не на віддалому монтуванні, що вдає із себе таку.

Є кілька способів реалізувати синхронізацію:

• Інструментальна синхронізація (поширена у серйозних командах)
• Compose-фічі «develop» / watch залежно від версії Docker і підтримки у вашому середовищі
• Ручний rsync-цикл якщо потрібно щось просте і контрольоване

Рівень виправлення 4: Розділіть обов’язки: збирайте на хості, запускайте в контейнері

Для деяких організацій це є єрессією, для інших — здоровим глуздом. Якщо головна причина контейнеризованого деву — «збіг з продакшен-рантаймом», ви все ще можете збирати артефакти на хості і монтувати лише результати збірки в контейнер чи проксувати запити.

Коли це працює добре:

• Фронтенд-інструменти запускаються на хості (швидкі нативні файлові події), контейнер слугує API/бекендом.
• Або бекенд запускається на хості, а залежності типу БД — у контейнерах.

Коли це стає проблемою:

• Коли команда хоче одну команду для підняття всього, і мережеві політики ускладнюють localhost-зв’язок.

Рівень виправлення 5: Зменшіть площу спостереження (ваш репозиторій занадто великий)

Монорепозиторії і великі поліглотні репозиторії не просто «стежать». Вони потребують стратегії:

• Стежте тільки за пакетом, над яким активно працюєте.
• Використовуйте посилання на проекти та інкрементальні збірки.
• Агресивно виключайте .git, кеші, vendored-залежності та згенеровані артефакти.
• Розгляньте виділені сервіси для спостереження (watchman), якщо ваш стек це підтримує.

Цитата

Парафразована ідея (приписують): Gene Kim підкреслює, що надійність приходить від роблення роботи видимою і зменшення сюрпризів, а не від героїчних дій у моменті.

Три корпоративні міні-історії з практики

Міні-історія #1: Інцидент, спричинений хибним припущенням

Середня продуктова команда розгорнула «dev-контейнери для всіх» після важкого кварталу з онбордингом. У них був чистий стек Compose: API, worker, база даних і фронтенд dev-сервер. На Linux-ноутбуках усе працювало чудово. На macOS деякі розробники почали повідомляти, що збереження файлу інколи не викликає перезбирання, але лише «інколи». Лід команди припустив, що це фреймворк. Звісно.

Вони шукали причину на рівні додатка тиждень. Перемикали HMR-налаштування, змінювали бандлери, фіксували залежності й навіть переписали частину dev-скрипта. Проблема залишалась, і довіра падала. Нові співробітники тихо вирішили, що контейнерна конфігурація «крихка», і почали запускати сервіси безпосередньо на своїх машинах, підриваючи всю ініціативу.

Справжня проблема була простішою і більш незручною: хибне припущення, що bind-mount-и на Docker Desktop поводяться як на Linux. Їхні спостерігачі покладалися на inotify-події, що приходять швидко й послідовно. На macOS шар трансляції подій інколи об’єднував події під час сплесків записів (особливо коли редактор зберігав кілька файлів підряд).

Виправлення не було магічним. Вони підтвердили збій за допомогою inotifywait всередині контейнера і побачили відсутні послідовності. Потім перемістили робоче дерево в нативний volume контейнера і синхронізували джерело. Раптом той самий інструмент спостереження поводився ідеально, бо він відстежував справжню Linux-файлову систему. Команда винесла урок: «крос-ОС монтування — це шар сумісності, а не гарантія».

Міні-історія #2: Оптимізація, що підвела

Одна enterprise-команда вирішила прискорити дев, змонтувавши все з хоста: корінь репозиторію, кеші залежностей, вихідні збірки, навіть кеші мовних пакетів. Вони хотіли, щоб перевантаження контейнера було миттєвим і щоб залежності зберігалися між перезапусками. На папері — виграш продуктивності.

На практиці це породило петлю зворотного зв’язку. Спостерігачі бачили зміни у вихідних збірках і кешах, тривігали перезбірки, що змінювали артефакти, які знову тригерували перезбірки. Використання CPU не просто зросло — воно стабілізувалося на «завжди високо», що є ввічливим способом сказати, що ноутбуки стали обігрівачами.

Гірше, система почала пропускати реальні зміни коду, бо тонула в непотрібних подіях. Розробники скаржилися, що «гаряче перезавантаження ненадійне», але корінь проблеми був у перевантаженні подіями та патологічній зоні спостереження. Команда «вирішила» це, включивши опитування з малим інтервалом. Це зробило проблему вентилятора ще кращою — у тому сенсі, як бензин покращує багаття.

Нудне виправлення: припинити монтувати кеші і вихідні збірки з хоста, і припинити їх відстежувати. Вони перемістили node_modules і директорії збірки у іменовані volume, оновили шаблони ігнорування і явно звузили область спостереження. Система заспокоїлась. Гаряче перезавантаження стало надійним. «Оптимізація» була відвернута, бо оптимізувала не те: вона оптимізувала швидкість rebuild-у в контейнері ціною стабільності рантайму.

Міні-історія #3: Нудна, але правильна практика, що врятувала день

Фінансово орієнтована компанія з суворою культурою комплаєнсу мала політику дев-оточення: кожен репозиторій має діагностичний скрипт, який друкує припущення про середовище. Це не було блискучим. Це дратувало деяких інженерів. Але це неодноразово їх виручало.

Коли відстеження файлів перестало працювати після оновлення Docker Desktop, команда не сперечалася про фреймворки. Вони запустили скрипт. Він перевірив: тип монтування, тип файлової системи, ліміти inotify і чи з’являються inotify-події при редагуванні з хоста проти всередині контейнера. По суті, це були Завдання 1–6 в одній команді.

За кілька хвилин вони отримали чіткий висновок: правки з хоста не породжували inotify-подій всередині контейнера, тоді як внутрішні правки — так. Це звузило проблему до шару файлообміну, а не коду. Вони перевели прапорець у своїй dev-настройці: користувачі macOS автоматично переходили на workflow синхронізації в volume, а Linux-користувачі залишалися на bind-mount.

Результат був нудно кращий: менше запитів у підтримку, менше «працює на моїй машині» аргументів і документоване дерево рішень. Практика не була хитрою; вона була дисциплінованою. В термінах ops, вони зменшили середній час для з’ясування винуватця додатка.

Поширені помилки: симптом → корінь проблеми → виправлення

1) Симптом: «Гаряче перезавантаження працює тільки після перезапуску контейнера»

Корінь проблеми: спостерігач упав або мовчки зупинився після досягнення лімітів watch (ENOSPC) або зіткнувся з патернами перейменувань, які він не обробляє.

Виправлення: перевірте логи на ENOSPC/EMFILE (Завдання 7), підніміть ліміти inotify (Завдання 6) і налаштуйте спостерігач на відстеження директорій + обробку атомарних збережень (Завдання 13).

2) Симптом: «Немає перезбірок на macOS/Windows, але працює на Linux-хості»

Корінь проблеми: пересилання подій bind-mount через Docker Desktop VM ненадійне для ваших шаблонів змін.

Виправлення: підтвердьте через inotifywait (Завдання 3/4). Потім або увімкніть опитування з розумними інтервалами (Завдання 12), або перейдіть на синхронізацію в volume.

3) Симптом: «Перезбірки відбуваються великими вибухами»

Корінь проблеми: об’єднання подій або затримане пересилання шаром файлообміну; іноді посилюється тим, що редактори пишуть кілька файлів або форматують при збереженні.

Виправлення: зменшіть дерево спостереження; уникайте відстеження вихідних збірок; розгляньте синхронізацію в файлову систему контейнера. Опитування може допомогти, якщо вибухи прийнятні.

4) Симптом: «CPU висить після включення опитування»

Корінь проблеми: інтервал опитування занадто малий; зона спостереження занадто велика; сканування повільних bind-mount шляхів.

Виправлення: збільшіть інтервал, звужте область спостереження і видаліть важкі шляхи з bind-mount (Завдання 10). Якщо вам потрібні низькі затримки перезбірки — віддавайте перевагу синхронізації в volume.

5) Симптом: «Деякі директорії тригерять перезбірку, інші ніколи»

Корінь проблеми: нерекурсивна поведінка спостереження (inotify), баги інструментів при додаванні watch-ів, або часткове виснаження watch під час ініціалізації.

Виправлення: підніміть ліміти watch і підтвердіть, що спостерігач звітує повний набір watched; ігноруйте важкі директорії і явно включайте потрібні.

6) Симптом: «Зміни в змонтованому коді відображаються, але інструмент все ще не перезбирає»

Корінь проблеми: інструмент відстежує інший шлях, ніж змонтований (поширено, коли workdir відрізняється), або він налаштований використовувати інший бекенд спостереження.

Виправлення: виведіть шляхи, які відстежуються у конфігурації інструмента; підтвердіть workdir (Завдання 1); запустіть мінімальний inotifywait проти тієї самої директорії.

7) Симптом: «Петля перезбірки: збереження тригерить перезбірку тригерить збереження…»

Корінь проблеми: спостерігач включає директорію виходу; форматер або генератор пише у відстежуване дерево; процес збірки торкається вихідного коду.

Виправлення: виключіть виходи, перемістіть артефакти у окрему директорію, яку не відстежують, і тримайте артефакти збірки поза bind-mount якщо можливо.

8) Симптом: «Монтування Docker volume вирішує проблему, але тепер я не можу редагувати код»

Корінь проблеми: ви перемістили робоче дерево у volume, але не додали механізм синхронізації.

Виправлення: застосуйте інструмент синхронізації або скрипт rsync-циклу; редагуйте на хості, синхронізуйте у volume і відстежуйте всередині контейнера.

Жарт #2: Опитування — це «ви пробували вимкнути та увімкнути» у світі відстеження файлів, за винятком того, що воно ніколи не вимикається — лише ваша батарея.

Контрольні списки / покроковий план

Покроково: добитися надійного гарячого перезавантаження за годину

1. Доведіть, що монтування правильне (Завдання 1 і Завдання 2). Якщо контейнер не бачить файли, які ви редагуєте — зупиніться.
2. Доведіть, що події існують за допомогою inotifywait (Завдання 3). Редагуйте з хоста і спостерігайте.
3. Розрізніть пересилання подій і поведінку інструмента (Завдання 4). Якщо правки всередині контейнера створюють події, а з хоста — ні, це не фреймворк.
4. Перевірте виснаження watch-ів (Завдання 5 і Завдання 7). Виправте ліміти і область.
5. Приберіть важкі директорії з bind-mount (Завдання 10). Помістіть залежності у іменований volume.
6. Явно ігноруйте зайві шляхи у конфігурації спостерігача (Завдання 11). Не покладайтеся на налаштування за замовчуванням.
7. Спробуйте контрольоване опитування (Завдання 12). Якщо працює, у вас є шлях до надійності сьогодні.
8. Якщо на macOS/Windows і все ще нестабільно: прийміть sync-into-volume для робочого дерева.
9. Документуйте рішення для команди: «Linux — inotify; macOS — sync або polling; ось чому.»

Контрольний список: «Зробіть bind-mount-и менш болючими»

• Монтуйте лише вихідний код; тримайте залежності і виходи у іменованих volume.
• Використовуйте явні шаблони ігнорування для інструментів спостереження.
• Тримайте дерева спостереження маленькими і передбачуваними.
• Уникайте петель watch-ів, розділяючи вхідні і вихідні дані.
• Віддавайте перевагу відстеженню директорій замість файлів.

Контрольний список: «Коли припинити боротися і перейти на синхронізацію»

• inotifywait показує відсутні події для правок з хоста.
• Опитування працює, але спалює CPU або занадто повільне при прийнятних інтервалах.
• Розмір репозиторію вимагає великого набору watch-ів і ви часто досягаєте лімітів.
• Ваша команда — змішана ОС і вам потрібна узгоджена поведінка на всіх ноутбуках.

Поширені питання (FAQ)

1) Чому відстеження файлів працює на Linux-ноутбуці колеги, але не на macOS?

На Linux контейнери ділять ядро хоста і inotify поводиться нормально на bind-mount. На macOS зміни файлів мають пройти через шар файлообміну у VM, і пересилання подій може бути затриманим або неповним.

2) Чи безпечно завжди збільшувати fs.inotify.max_user_watches?

Зазвичай це безпечно на дев-машинах, але це збільшує споживання пам’яті ядра для обліку watch-ів. Піднімайте його тому, що вам це потрібно, а не тому, що якась стаття так порадила. Потім звужуйте область спостереження.

3) Чому я бачу ENOSPC, якщо в мене ще достатньо місця на диску?

Тому що ENOSPC має перевантажене значення: у цьому контексті воно означає «немає місця для дескрипторів watch», а не вільних блоків диска. Перевірте логи (Завдання 7) і sysctls inotify (Завдання 5/6).

4) Який найшвидший обхідний шлях, якщо мені потрібна надійність сьогодні?

Увімкніть опитування для вашого спостерігача (Завдання 12), збільшіть інтервал, поки CPU не буде розумним, і звузьте область спостереження. Потім сплануйте довготермінове рішення (синхронізація в volume), якщо ви на macOS/Windows.

5) Чому відстеження node_modules створює стільки проблем?

Тому що воно велике, воно часто змінюється і містить глибокі дерева директорій. Відстеження node_modules споживає inotify-watch-и і породжує шум. Більшість інструментів не потребують його відстеження; їм потрібне лише розв’язування залежностей.

6) Чи можуть функції «watch» у Docker Compose замінити спостерігач вашого інструмента?

Іноді так. Вони можуть синхронізувати зміни і тригерити rebuild/restart дії, що може уникнути inotify повністю. Але це ще одна частина, що рухається; перевірте, чи підходить це під ваш робочий процес і чи не приховує латентність.

7) Чому атомарні збереження ламають деякі спостерігачі?

Атомарне збереження часто — «запис тимчасового файлу, потім перейменування». Якщо спостерігач стежить за inode файлу занадто буквально, він може пропустити, що «новий» файл замінив старий. Відстеження директорій у цьому випадку працює краще.

8) Чи варто запускати dev-сервер на хості і лише контейнеризувати залежності?

Якщо ваша головна проблема — відстеження файлів і ваш додаток не потребує ядрового паритету з продом, так, це прагматичний варіант. Просто будьте явні щодо того, яку «сумісність з продом» ви відмовляєтеся.

9) Чому перенесення репозиторію в іменований volume допомагає?

Бо контейнер відстежує нативну Linux-файлову систему всередині VM/хоста, уникаючи крос-ОС семантики файлообміну. Ви готові пожертвувати прямою редагованістю заради коректності, а потім повернути можливість редагувати через синхронізацію.

Висновок: наступні кроки, які ви можете випустити сьогодні

Гаряче перезавантаження в контейнерах не «ламалося» однаково для всіх. Воно ламається специфічними, відтворюваними способами — пересилання подій, ліміти watch-ів, продуктивність і припущення інструментів. Ставтеся до цього як до задачі SRE: спочатку вимірюйте, потім змінюйте, потім документуйте.

1. Запустіть inotifywait всередині контейнера і доведіть, чи приходять події від правок з хоста.
2. Якщо ви досягаєте лімітів, підніміть inotify-watches і звузьте область спостереження.
3. Якщо ви на macOS/Windows і події ненадійні, оберіть: контрольоване опитування сьогодні, синхронізація в volume для довготермінової стабільності.
4. Розділяйте монтування: bind-mount для коду, volume для залежностей і артефактів.
5. Напишіть невеликий скрипт для команди, який виконує ключові перевірки, щоб це не перетворилось на племінні знання.

Зробіть відстеження файлів нудним. Ваше майбутнє «я» вам за це подякує.