Перейти до змісту

Вирішення проблем

Рішення для поширених проблем з BamDude.

Стани принтерів повільно з'являються при відкритті сторінки

Картки можуть показувати live-стан із WebSocket, поки REST-запит статусу ще очікує відповіді. REST додає відомості про архів і платформу та залишається резервним джерелом, якщо WebSocket недоступний. Одночасні запити станів об'єднуються в обмежений пакет; повернення у вкладку оновлює лише активні запити. Завислий WebSocket-клієнт від'єднується, щоб не затримувати інших глядачів.

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

  • WebSocket bootstrap timing: перевірка доступу, прийняття з'єднання та підготовка черги початкових станів, включно з очікуванням вільного місця від writer цього клієнта.
  • WebSocket bootstrap applied: браузер застосував початкові стани до кешу запитів. Зіставляйте id із попереднім записом. client_connect_ms включає отримання токена, підключення й отримання станів; server_elapsed також включає зворотну доставку підтвердження. Це не вимір першого намальованого кадру.
  • Slow WebSocket send, WebSocket send timed out або WebSocket outbox overflow: браузерне з'єднання не встигає приймати вихідні дані.

Відсутність підтвердження сама по собі не доводить збій сервера: причиною може бути старий код у браузері, закрита вкладка або обрив мережі. Ці таймінги не включають завантаження JavaScript застосунку та списку принтерів.

Проблеми з підключенням принтера

Принтер не підключається

Симптоми: принтер показується як відключений, червоний індикатор.

Рішення:

  1. Переконайтесь, що Developer Mode увімкнено
  2. Settings > Network > LAN Only Mode (ON)
  3. Потім увімкніть Developer Mode

  4. Вимкніть/увімкніть, щоб отримати свіжий код доступу

  5. Перевірте IP-адресу

  6. Перевірте IP у мережевих налаштуваннях принтера

  7. Використовуйте статичну IP або резервацію DHCP

  8. Перевірте код доступу

  9. Код доступу змінюється при перемиканні Developer Mode

  10. Скопіюйте код точно (з урахуванням регістру)

  11. Перевірте мережеве з'єднання 

    ping YOUR_PRINTER_IP

  12. Переконайтесь, що порти доступні

  13. MQTT: порт 8883

  14. FTPS: порт 990

  15. Перевірте правила фаєрвола

З'єднання часто обривається

  1. Перевірте рівень WiFi-сигналу на картці принтера
  2. Перевантаження мережі -- спробуйте виділену мережу/VLAN
  3. Проблеми з роутером -- перезавантажте, перевірте прошивку, вимкніть "розумні" функції
  4. Перевірте логи BamDude: 
    tail -f logs/bamdude.log

Відпалий принтер тепер піднімається сам

BamDude щохвилини перевіряє, чи є принтер, який працював, мовчить уже п'ять хвилин, і чий порт усе ще відповідає, — і перебудовує з'єднання сам, а не чекає, поки до цього дійде мережева бібліотека. В одному зі звітів принтер був офлайн із 02:19 до 11:24 при відкритій сторінці; стара перевірка дивилася лише на з'єднання, які ще живі, але замовкли, тож повністю відпале в неї не потрапляло.

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

Принтер виглядає підключеним і вільним, але ігнорує кожну команду

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

Причина. Деякі прошивки (серія P1, 01.08.03 і новіші) можуть почати відхиляти керівні команди, які не можуть верифікувати. Принтер увесь цей час повідомляє про це — HMS 0500-0500-0001-0007, MQTT command verification failed.

Як полагодити — на принтері:

  1. На екрані принтера увімкни Developer Mode (LAN Mode / Developer options — залежно від прошивки).
  2. Перезавантаж принтер.

BamDude тепер розпізнає цей код, показує його в тій самій формі з чотирьох груп, що й екран самого принтера, і несе саме цю пораду. (Власна порада Bambu для цього коду — оновити Bambu Studio чи Handy, що ніяк не допомагає друку, надісланому з BamDude.)

Що змінилося разом із цим

  • Постановка друку в чергу на такий принтер зупиняється з першої спроби й називає причину, замість витрачати чотири з половиною хвилини і три завантаження, щоб упасти з недоречним повідомленням про SD-карту.
  • Перевірка Developer Mode у support-бандлі й діагностиці принтера має третю відповідь — undetermined, а не зараховує будь-яку відповідь, що не є прямою відмовою, як успіх.
  • Здоровому принтеру більше не радять піти перевірити свій серійний номер у мить одразу після перепідключення.

Проблеми з камерою

Потік не запускається

  1. Принтер увімкнено?
  2. Камера увімкнена в налаштуваннях принтера?
  3. ffmpeg встановлено? (включений у Docker-образ)
  4. Developer Mode увімкнено?
  5. Користувачі Docker: спробуйте network_mode: host

Потік зависає

  • Перевірте рівень WiFi-сигналу
  • Спробуйте зменшити FPS
  • Використовуйте режим знімків замість потоку

Проблеми з архівуванням

Друки не архівуються

  1. SD-карта вставлена? Потрібна для завантаження файлів
  2. Developer Mode увімкнено? Потрібен для доступу через FTP
  3. Автоархівування увімкнено? Перевірте налаштування принтера
  4. Калібрувальні друки автоматично пропускаються

Проблеми з чергою

Друки не починаються

  1. Принтер підключений? Має показувати зелений індикатор
  2. Стіл очищений? Перевірте, чи показується кнопка "Очистити стіл та почати наступний"
  3. Заплановано на майбутнє? Перевірте, чи має друк запланований час у майбутньому
  4. Режим Queue Only? Перевірте наявність фіолетового бейджа "Staged"

Другий принтер чекає кілька секунд перед стартом

Це не баг — але діагностика змінилася. Починаючи з c485db1, dispatch BamDude виконується паралельно по принтерах; тільки коротка DB-insert фаза обгорнута в startup-lock. Два принтери справді отримують свої завдання одночасно, і dispatch-тост показує два FTP-progress-бари поряд. Тимчасовий "одне за раз по всій фермі" gate, що приземлився в середині 0.4.1, прибрали, як тільки startup-lock у диспатчер заїхав. Див. Per-Printer Queues → Поведінка диспатчу.

Проблеми з кнопкою Skip-Objects

Кнопка skip-objects неактивна для файлів OrcaSlicer

OrcaSlicer постачається з вимкненими Label objects та Exclude objects у профілі друку, тому його 3MF потрапляють у BamDude без метаданих, потрібних прошивці для адресації окремих об'єктів. Bambu Studio вмикає обидва за замовчуванням, тому файли, нарізані там, працюють із коробки.

Виправлення для одного файлу:

  1. Print Settings > Others > "Label objects" -- видає на друк per-object ID (M624/M625), які потрібні прошивці.
  2. Print Settings > Others > "Exclude objects" -- вмикає метадані на стороні slicer-а, які зчитує BamDude.
  3. Обидва мають бути увімкнені до нарізання. Повторне надсилання старого 3MF без цих прапорців не допоможе -- наріжте заново з обома увімкненими, перезавантажте, і кнопка стане активною.

Прапорці зберігаються у Metadata/project_settings.config вихідного 3MF; BamDude витягує їх під час завантаження (а існуючі файли поповнюються через міграцію m022).

Кнопка skip-objects "вмирає" через 5 хвилин після старту друку (стара поведінка)

Виправлено в 0.4.1, дія не потрібна. Раніші версії періодично замінювали MQTT-клієнта принтера на свіжий екземпляр кожні ~5 хвилин, що стирало in-memory стан printable_objects. Тепер кнопка перезаповнюється щоразу, коли спрацьовує гілка duplicate-guard у on_print_start, тому залишається живою впродовж усього друку. Стійка до перезапусків також -- fallback-друки, запущені з принтера, отримують такий самий догляд через archive_download_retry.

Зависання під час оновлення

"Сервер піднімається кілька хвилин" при першому старті після 0.4.1

Міграції m022 і m023 обидві відкривають кожен наявний 3MF на диску, щоб поповнити метадані. m022 витягує прапорці gcode_label_objects / exclude_object; m023 витягує повний per-plate breakdown, що живить per-plate gallery у File Manager. Приблизно 50-200 мс на файл кожна, біжать послідовно — інсталяція з тисячами архівів може провести кілька хвилин на цьому кроці до того, як API почне відповідати. Слідкуй за рядками m022 library_files: progress, m022 print_archives: progress, потім за відповідними m023 — якщо вони рухаються пакетами по 100, міграції здорові і просто мають закінчитися.

Обидві one-shot — наступні старти пропускають їх через таблицю _migrations.

Консоль браузера флудить 401-ми після довго-idle вкладки

Виправлено в dd1d9eb, ніяких дій на 0.4.1+ не треба. Раніші версії чекали 401, щоб реактивно вистрелити /auth/refresh; коли backgrounded-tab повертався з п'ятьма React-Query ключами одночасно — network panel коротко логав 20–40 401-х до того, як перший refresh-response розблокує. Тепер клієнт декодує exp claim JWT, ставить one-shot refresh ~60 с до експірації, а near-expiry pre-flight чекає той самий coalesced-refresh promise. Результат: access-токен свіжий до моменту, коли visibility-sync інвалідує queries, і жодного 401 з браузера не йде. Реактивний шлях лишається як fallback для binary / streaming ендпоінтів.

Це одноразово -- наступні старти пропустять міграцію через таблицю _migrations.

Проблеми з Docker

Контейнер не запускається

docker compose logs bamdude

Не вдається підключитися до принтера

docker compose exec bamdude ping YOUR_PRINTER_IP

Спробуйте network_mode: host на Linux.

macOS / Windows Docker

Docker Desktop запускає контейнери у віртуальній машині. Використовуйте прокидання портів замість host mode та додавайте принтери вручну за IP.

Проблеми з Telegram-ботом

Бот не відповідає

  1. Перевірте, що провайдер Telegram увімкнено в Налаштування > Сповіщення
  2. Переконайтесь, що токен бота правильний
  3. Перевірте логи BamDude на помилки polling-у
  4. Переконайтесь, що ваш чат авторизовано

Команди не працюють

  1. Перевірте, що ваш чат має необхідні права
  2. Перевірте призначення групи чату у веб-інтерфейсі
  3. Спробуйте /start для повторної реєстрації чату

Проблеми з базою даних

Скидання бази даних

Втрата даних

Це видалить всю вашу історію друку та налаштування!

docker compose down
# Remove the database file from the data volume
docker compose up -d

Trace ID в логах

Кожен HTTP-запит крізь BamDude отримує унікальний trace ID. Той самий ID:

  • Повертається у відповіді як X-Trace-Id-заголовок (тож curl / browser DevTools / log-dump бачать його).
  • Прив'язаний до кожного log-рядка, що відпрацював у цьому запиті — bamdude.log, плюс child-логери (bambu_mqtt, print_scheduler, background_dispatch, archive_download_retry, …).
  • Переживає async-хопи — якщо запит запустив fire-and-forget task (наприклад, archive 3MF retry-download), логи цього task'а несуть оригінальний trace ID.

При репорті бага найзручніший шлях віддати нам правильний шматок лога:

  1. Відтвори проблему в браузері. DevTools → Network → клік на запит, що фейлиться → Response Headers → копіюй X-Trace-Id.
  2. Знайди цей ID в bamdude.log: 
    grep <trace-id> logs/bamdude.log
  3. Вставляй знайдений кластер у GitHub-issue. Це корелює HTTP-вхід → службова робота → MQTT / scheduler побічні ефекти разом, замість "вгадай, що відбувалось о 14:32:17 у N компонентах".

Формат короткий (8 hex-символів, [trace=abc12345] у log-рядках), тож логи лишаються читабельними. Trace IDs не стабільні через рестарти — це per-request, не per-session.

Що саме гальмує

Коли ферма «гальмує», причин рівно дві і вони протилежні: або повільний запит до бази, або сервер зайнятий чимось іншим, а база при цьому простоює. Уся справа в тому, щоб їх розрізнити — BamDude вміє виміряти обидві. За замовчуванням обидва вимикачі вимкнені; вмикайте лише на час розслідування.

Налаштування → Загальні:

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

Обидва застосовуються одразу після збереження — без перезапуску — і працюють однаково на SQLite і на PostgreSQL. Розумний старт для завантаженої ферми: 500 для запитів до бази і 3000 для запитів до API. Коли розібралися — поверніть 0.

Як читати рядок про запит

slow request 1830ms GET /api/v1/inventory/spools (db 41 queries, 1620ms) [a1b2c3d4]

[a1b2c3d4] у кінці — це trace ID з розділу вище, тож увесь журнал цього запиту дістається одним grep. А ось дужки перед ним і є те, заради чого рядок читають:

  • Більшість часу в базі, багато запитів (db 41 queries, 1620ms) — ендпоїнт питає базу надто часто. Зазвичай це один запит на рядок там, де вистачило б одного на всі.
  • Більшість часу в базі, один-два запити — бракує індексу або запит читає більше рядків, ніж потрібно. Журнал повільних запитів назве конкретний запит.
  • У базі майже нічого (db 3 queries, 12ms з 1830 мс) — з базою все гаразд, сервер був зайнятий іншим: обходом великої теки, роботою із зображеннями, або просто надто багатьом одночасно.

Не вмикаючи нічого

Кожна відповідь і так несе стандартний заголовок Server-Timing:

Server-Timing: db;dur=1620.4, total;dur=1830.2

Браузер показує його в DevTools → Network → запит → Timing, тож той самий розподіл доступний в один клік для всього, що вдається відтворити в інтерфейсі.

Що потрапляє в журнал, а що ні

Журнал повільних запитів записує текст запиту — скорочений, із замаскованими креденшелами, якщо вони там трапляться. Значення, підставлені в запит, не записуються ніколи: це назви ваших файлів, котушок і серійні номери принтерів, а bamdude.log люди чіпляють до публічних ішюсів. Для запитів до API записуються лише метод і шлях, ніколи не рядок параметрів.

Самодіагностика

BamDude може сам діагностувати більшість проблем налаштування. На сторінці Система розділ Діагностика підключення перевіряє кожен принтер (порти, режим розробника LAN, мережевий режим Docker, підмережа, облікові дані), а розділ Стан системи сканує нещодавні логи за каталогом відомих проблем нижче. Вбудований репортер багів запускає обидві перевірки при відкритті, тож проблему, яку можна виправити, видно ще до надсилання звіту. Посилання «Як виправити» на кожній знахідці ведуть до відповідного розділу тут.

Неправильний код доступу

Принтер відхилив вхід для передачі файлів. Код доступу неправильний або змінився після перемикання режиму розробника. Скопіюйте код доступу знову з екрана принтера (налаштування LAN) і оновіть його в налаштуваннях принтера в BamDude. Зверніть увагу: серійний номер чутливий до регістру — BamDude тепер автоматично переводить його у верхній регістр при збереженні.

Порт FTPS 990 заблоковано

BamDude не зміг дістатися порту передачі файлів принтера (FTPS 990). Порт заблоковано, або принтер вимкнено чи він в іншій підмережі. Переконайтеся, що ніщо (фаєрвол, Docker bridge-мережа) не блокує порт 990 між BamDude і принтером, і що обидва в одній мережі.

Збій TLS FTPS

Рукостискання TLS із сервером передачі файлів принтера не вдалося — часто це фаєрвол/проксі, що перехоплює з'єднання, або застаріла прошивка. Оновіть прошивку принтера й перевірте, що ніщо не перехоплює порт 990.

Нестабільне підключення MQTT

Керуюче з'єднання (MQTT 8883) постійно розривається й перепідключається — зазвичай слабкий мережевий шлях або частково заблокований порт. Перевірте сигнал Wi-Fi біля принтера, надайте перевагу дротовому з'єднанню й переконайтеся, що порт 8883 стабільно доступний.

Камера RTSPS порт 322

Не вдалося дістатися камери на порту RTSPS 322. Порт заблоковано, або камеру / LAN-перегляд вимкнено на принтері. Увімкніть камеру й LAN-перегляд на принтері та переконайтеся, що порт 322 не заблоковано. Це не впливає на друк.

Зберігання надісланих файлів на зовнішньому носії

BamDude прочитав власний звіт принтера про налаштування Store sent files on external storage (крок 4 встановлення) і побачив, що воно вимкнене. Без нього принтер не зберігає нарізаний .gcode.3mf, тож у кожного архівованого друку відсутні прев'ю та метадані слайсера. Увімкніть це налаштування у слайсері, щоб кожне завдання зберігалося на принтері. Зверніть увагу: на деяких старіших зв'язках прошивки/слайсера це суто слайсерна опція, про яку принтер не повідомляє — цей варіант діагностика не бачить, але сторінка Архіви показує банер, коли друки надходять без прев'ю.

На деяких моделях ця перевірка пропускається, а не позначається помилкою: P1P, P1S, A2L та X1E мають слот для SD-картки, але не мають доступного способу увімкнути опцію — вони не повідомляють про її підтримку, тож Bambu Studio / OrcaSlicer не показують перемикач, а в серії P1 немає й екрана, щоб задати її там. Оскільки виправляти нічого, діагностика пояснює це замість того, щоб показувати постійну помилку. Якщо оновлення прошивки почне надавати цю опцію, перевірка увімкнеться сама.

Принтер публікує статус

MQTT-брокер прийняв з'єднання, але жодного звіту про статус від принтера не надійшло. Брокер приймає з'єднання навіть коли серійний номер неправильний або в неправильному регістрі — report-топік принтера чутливий до регістру — тож керування виглядає підключеним, а на боці слайсера порожній AMS, немає філаментів і K-профілів. Діагностика чекає до 10 секунд на перший звіт про статус від принтера й показує живий лічильник секунд, щоб очікування не виглядало зависанням. Якщо перевірка не проходить, перевірте серійний номер на одруки й регістр (BamDude тепер переводить його у верхній регістр при збереженні) та переконайтеся, що принтер увімкнений і доступний.

База даних заблокована

База даних SQLite отримує помилки "database is locked" під навантаженням — типово при роботі кількох принтерів одночасно. Переведіть BamDude на зовнішню базу даних PostgreSQL (див. посібник із PostgreSQL).

Отримання допомоги

При створенні звіту про проблему вкажіть:

  • Версію BamDude
  • Модель принтера та версію прошивки
  • Операційну систему
  • Кроки для відтворення
  • Повідомлення про помилки з логів
  • Конфігурацію Docker compose (якщо застосовно)

Створюйте Issues на github.com/kainpl/bamdude/issues.

Початково базується на документації Bambuddy.