28. Усунення несправностей: коли кіт перестає муркотіти¶

Work in progress

Диск не підключається, колега не бачить учорашній рендер, а SSD раптом закінчився? Почнімо з того, що саме не працює. Перевстановити все завжди встигнемо. А от незавантажені зміни краще спершу зберегти.

Спочатку — три короткі перевірки¶

У прикладах myvolume — назва вашого тому. Замініть її на свою.

studiofs --version
studiofs settings
studiofs status myvolume --verbose

Перша команда показує версію клієнта, друга — збережені налаштування майбутніх підключень, третя — стан тому та доступні діагностичні показники. settings без параметрів нічого не змінює. Налаштування не обов’язково збігаються з чинним підключенням: параметри могли перевизначити під час запуску.

Якщо підключали том з окремим каталогом кешу, вкажіть той самий базовий каталог:

studiofs status myvolume --verbose --cache-dir D:\StudioFSCache

Не сприймайте порожню чергу чи відсутні показники як доказ завершеної синхронізації. Частина даних доступна лише від запущеного підключення; застарілий знімок не описує поточний стан.

Поки причина невідома, не видаляйте кеш і локальну базу та не створюйте том заново. Там можуть залишатися єдині копії змін, які ще не дійшли до сховища. destroy, ремонт метаданих і ручне прибирання службових каталогів — не перші кроки діагностики.

Диск узагалі не підключається¶

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

Невідома команда або параметр. Перевірте studiofs mount --help саме у встановленій версії. Поточна команда не має параметра --tray: на Windows і macOS StudioFS автоматично пробує показати індикатор, якщо доступне графічне середовище. Невдалий запуск індикатора сам по собі не зупиняє підключення.
Том не знайдено. Перевірте написання назви, обліковий запис ОС і STUDIOFS_CLIENT_ROOT. Щоб підключити вже наявний спільний том на іншому комп’ютері, виконайте discover, як описано в главі 16. Повідомлення status може радити init, але воно не доводить, що потрібно створювати новий том.
Зайнята літера або точка підключення. На Windows виберіть вільну літеру, наприклад Z:. На macOS і Linux перевірте каталог точки підключення та права доступу. Якщо там уже працює StudioFS, спершу закрийте програми й виконайте звичайне відключення за главою 17. Не видаляйте lock-файли, щоб обійти активне підключення.
Термінал не повертає запрошення. Це нормальна поведінка: звичайний mount працює в передньому плані. Не закривайте його як «завислий». Для фонового запуску є --detach.

Для повторного запуску з докладнішим журналом, після звичайного відключення попереднього підключення, можна використати:

studiofs --log-level debug mount myvolume Z:

На macOS або Linux замість Z: вкажіть свій каталог. --log-level стоїть перед mount. Якщо ви використовували окремий кеш чи інші параметри, збережіть їх і в цій команді.

Помилка WinFSP або FUSE¶

Windows¶

Перевірте, чи встановлено WinFSP, а не лише сам StudioFS. Далі звіртеся з інструкцією встановлення.

Під час першого підключення StudioFS може показати запит UAC для налаштування інтеграції WinFSP із менеджером підключень Windows. Якщо відхилити запит, початкове налаштування може не завершитися. У сеансі служби або CI-середовищі інтерактивний UAC недоступний — адміністратор має підготувати систему заздалегідь. Для наступних звичайних підключень постійні права адміністратора не потрібні.

macOS¶

Потрібен macFUSE і дозволи, яких вимагає його встановлення. Якщо система просить дозволити компонент або перезавантажитися, завершіть ці кроки за главою 11.

Linux¶

Поточний backend використовує FUSE3. Перевірте утиліту й пристрій ядра:

fusermount3 --version
ls -l /dev/fuse

Якщо під час збирання не вдається знайти бібліотеку, перевірте пакунки розробки FUSE3 за главою 12. Якщо /dev/fuse відсутній або недоступний, перевірте модуль ядра й дозволи. У контейнері також потрібен дозволений доступ до FUSE на хості: встановлення пакунка всередині контейнера цього не гарантує. Не починайте з запуску всього від root.

Помилка PostgreSQL або VPN¶

Timeout, connection refused, помилка DNS і password authentication failed означають різні речі.

Перевірте, чи підключено Tailscale або NetBird і чи сервер доступний у приватній мережі. Статус VPN «підключено» ще не гарантує дозвіл на PostgreSQL у правилах доступу.
Звірте адресу й порт із налаштуваннями сервера. Перевірте firewall, VPN ACL та стан самого PostgreSQL за главами 7 і 8.
Якщо мережа працює, перевірте користувача, пароль, назву бази й серверні правила автентифікації. Не відкривайте публічний порт PostgreSQL як спосіб «полагодити VPN».

Якщо у вас є клієнт psql, перевірте підключення до бази з робочого комп’ютера. Замініть адресу та ім’я користувача на свої; пароль введіть у запиті:

psql -h VPN_SERVER_ADDRESS -p 5432 -U studiofs -d studiofs -W -c "SELECT 1;"

Відповідь 1 підтверджує доступ цього користувача до цієї бази. Вона не перевіряє доступ до S3 і не гарантує наявності всіх прав, потрібних для ініціалізації тому.

Втрата PostgreSQL не обов’язково миттєво зупинить уже підключений диск: StudioFS працює з локальними метаданими. Однак для обміну змінами між клієнтами зв’язок із PostgreSQL має відновитися.

Папки видно, але файл не відкривається¶

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

Звірте endpoint, bucket, регіон і чинність ключів. У журналі шукайте помилки DNS, TLS, timeout або AccessDenied. Перевірте також стан сховища, квоту й проксі-сервера перед ним. Несправність S3 можлива навіть за справного VPN-з’єднання з PostgreSQL: це окремі маршрути доступу.

Не вимикайте перевірку сертифікатів і не перемикайте HTTPS на HTTP навмання. Якщо серверна адреса змінилася, погодьте нову адресу з адміністратором. Докладніше про налаштування — у главі 6.

Помилка Permission denied може також стосуватися прав на сам файл. Звірте користувача й параметр --principal, якщо команда використовує ACL. Наявність прав на bucket не скасовує прав усередині тому.

Збереження завершилося, а колега бачить старий файл¶

У StudioFS збереження на одному комп’ютері та публікація для інших користувачів — різні етапи. Закриття файлу не підтверджує, що всі колеги вже отримали нову версію.

Спершу перевірте комп’ютер автора змін: чи він увімкнений, чи працює підключення, чи доступні S3 та PostgreSQL. Перегляньте status --verbose і журнал на наявність повторних спроб завантаження або публікації. Потім перевірте зв’язок на комп’ютері колеги.

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

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

Про затримки й спільну роботу докладніше — у главах 19 та 21.

Кеш заповнився або закінчилося місце на SSD¶

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

За замовчуванням клієнтський корінь — ~/.studiofs (на Windows — у домашньому каталозі користувача). Локальні метадані лежать у meta/<назва>, типовий базовий каталог кешу — meta/<назва>/cache, а всередині дані розділено за UUID тому. STUDIOFS_CLIENT_ROOT змінює клієнтський корінь; --cache-dir або збережене cache_dir можуть спрямувати кеш на інший диск.

StudioFS автоматично видаляє кешовані дані, які можна витіснити. Незавершені зміни — інша справа: ручне видалення кешу може їх знищити. Припиніть нові великі записи, відновіть доступ до S3 і мережі та звільніть місце, видаливши інші файли, які точно не потрібні.

Зміну ліміту або розташування кешу плануйте за главою 20. Нове значення studiofs settings не переносить поточний кеш і не змінює вже запущене підключення. Не спрямовуйте клієнт на порожній кеш, поки старий містить незавершені зміни.

Файл зник або папка виявилася порожньою¶

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

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

Якщо підозрюєте видалення або конфлікт, припиніть зміни в цій папці та збережіть доступні незалежні копії. Не запускайте повторний init, не відновлюйте дані поверх чинного тому й не копіюйте файли масово, доки не з’ясуєте причину. Перевірте резервні копії разом з адміністратором. У StudioFS немає універсального кошика, який поверне все одним кліком.

Коли потрібна допомога¶

Пам’ятайте головне правило автостопника Галактикою: «Не панікуй».

StudioFS — не комерційний сервіс, і платна технічна підтримка не планується. Якщо причина не стала зрозумілою, підготуйте версію StudioFS, ОС, час події із зазначенням часового поясу, команду запуску без секретів, точний текст помилки й короткий опис: що очікували та що сталося. Додайте результат status --verbose і відповідний фрагмент журналу. Для фонового підключення журнали зберігаються в <клієнтський корінь>/logs; для звичайного запуску перевірте термінал.

Перш ніж надсилати матеріали, перевірте їх і замаскуйте паролі, ключі S3, токени та секретні частини DSN. Не надсилайте весь config.toml або локальну базу без окремої потреби. У наступній главі розберемо, як зібрати корисний діагностичний звіт. Кіт може мовчати з багатьох причин; точний текст помилки допоможе звузити коло підозрюваних краще, ніж перевстановлення.

Зміст · English · ← Попередня · Наступна →