Що таке QZ Tray Lite?

QZ Tray Lite це локальний сервер друку, який повністю емулює протокол QZ Tray, але без його масивної інфраструктури. Це дозволяє друкувати квитанції на термопринтерах безпосередньо з вашого браузера за допомогою qz-tray.js — і ваш зовнішній код вимагає нуль змін.

Якщо ви коли-небудь налаштовували оригінальний лоток QZ для безшумного друку, ви знаєте, у чому проблема: генеруйте пари ключів, розповсюджуйте сертифікати, налаштовуйте кінцеву точку підпису на сервері, збирайте {виклик, параметри, позначка часу}, обчисліть шістнадцятковий код SHA-256, підпишіть його закритим ключем RSA, поверніть base64 у браузер і моліться. Будь-яка помилка — і замість квитанції ваш користувач бачить «Дозволити?» діалог.

QZ Tray Lite усуває все це.

• The підпис і signAlgorithm поля є ігнорується. Ваш клієнт надсилає підписи, як зазвичай, і отримує успішні відповіді — він ніколи не знає, що спілкується з іншою реалізацією.

• Кінцева точка підпису на сервері не потрібна. Ланцюг довіри зводиться лише до двох сторін: браузер ↔ локальний процес.

• Повторно використовує існуючі сертифікати — наприклад, із встановленого лотка QZ (Windows уже довіряє CN=localhost), або ви можете надати власний PKCS#12.

Ключові переваги

Як це працює

Браузер підключається через WebSocket до localhost (wss://8181 або ws://8182). QZ Tray Lite відповідає на ті ж виклики, що й оригінальний:

• getVersion — звіти 2.2.6 (сумісний із сучасними qz-tray.js);

• сертифікат — приймає сертифікат клієнта та підтверджує;

• принтери.знайти / printers.getDefault — перераховує системні принтери через win32print;

• друкувати — ставить завдання в чергу для друку.

A послідовна черга для кожного принтера гарантує, що копії не чергуються, а довгі завдання не блокують WebSocket.

Підтримувані режими друку

1. Необроблений ESC/POS

• Текст із вибором кодування (CP1250–CP1258, IBM8xx, ISO-8859-x, GBK, Big5, Shift_JIS, UTF-8).

• кирилиця: CP1251 + ESC t команда в квитанції (номер сторінки залежить від прошивки).

• Зображення: повна підтримка ESC * (одиночні/двомісні/тримісні, включаючи спадок) і GS v 0. Квантування: luma, альфа, чорний.

• Активовано через тип: "сирий" з options.language: "escpos".

2. Піксельний (GDI) друк

• Растровий друк через драйвер принтера з scaleContent, поля, одиниць (дюйми або мм).

• немає options.language потрібно — ідеально підходить для логотипів, штрих-кодів, етикеток.

• Активовано через тип: "піксель".

Міркування безпеки

Важливо: QZ Tray Lite призначений для довірені робочі станції касира в локальних мережах. Це робить навмисно ні перевірити:

• запит підписів (підпис, signAlgorithm);

• клієнтські сертифікати та ланцюжки довіри;

• позначки часу (вікно ±15 хвилин в оригіналі);

• дозволено.dat / заблоковано.dat контроль доступу.

Практичне значення: можна роздрукувати будь-яку сторінку, відкриту в браузері на цій машині. Це прийнятний компроміс для спеціального POS-комп’ютера. однак, не робити виставити сервер на 0.0.0.0 або використовуйте його на машинах, де користувачі переглядають довільні веб-сайти.

Усі дії реєструються — кожен запит, кожен байт, кожна URL-адреса, завантажена через формат: "зображення" без явного аромат.

Встановлення та швидкий старт

Вимоги: Windows 10/11, Python 3.12+

git clone <репозиторій>
cd qz-tray-lite
пітон -м піп установ -r вимоги.txt

запустити:

python main.py

Сервер автоматично:

• знаходить вільний порт (якщо 8181 зайнятий, пробує 8282 тощо);

• використовує сертифікат з оригінального лотка QZ, якщо його встановлено, або дозволяє налаштувати --сховище ключів / --storepass;

• запускає як WSS, так і WS слухачі для сумісності.

Робота у фоновому режимі: включені tools/service.ps1 встановлює QZ Tray Lite як службу Windows або заплановане завдання (вибирається автоматично на основі середовища). Підтримує ротацію журналів, моніторинг працездатності та політики перезапуску.

Що НЕ реалізовано

Ми навмисно опустили функції, які рідко використовуються в сценаріях POS:

• серіал, USB, сховався, файл, мережі;

• принтери.подробиці, почати слухати / getStatus;

• піксельний друк із pdf і html;

• Кодування зображення: GS_L, квантування: дизер, обертання / орієнтація.

Виклики до них повертають чіткі помилки, а не мовчазні збої.

Тестування та налагодження

The tools/probe.py утиліта:

• виконує рукостискання QZ Tray;

• надсилає тестові завдання друку (шаховий логотип визначає зміщення бітів, кадр визначає обрізання країв);

• демонструє, що підписи не перевіряються — навіть недійсні підписи проходять.

python tools/probe.py --друк XP-58          # тестова квитанція
python tools/probe.py --друк XP-58 --піксель  # піксельний режим

65 модульних тестів для конвертера зображень ESC/POS (831 рядок) — очікувані байти, розраховані вручну відповідно до специфікації Epson.

Для кого це?

• Розробники POS-систем які хочуть усунути громіздкий лоток QZ і спростити розгортання на сотнях робочих станцій.

• Інтегратори набридло налаштовувати сертифікати та підписувати серверні частини для кожного магазину.

• Власники бізнесу які мають сайт с qz-tray.js але потрібен стабільний, швидкий локальний сервер друку для 58-міліметрових термоквитанцій.

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

Ліцензія

Ліцензія MIT © 2026 IDNK Софт

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

Сумісність протоколу QZ Tray базується на оригіналі qzind/лоток проекту (LGPL-2.1). QZ Tray Lite — це незалежна реалізація серверного протоколу на Python.

Виберіть QZ Tray Lite — легка альтернатива, яка робить саме те, що потрібно вашій POS, і нічого більше.