Cos'è QZ Tray Lite?

Vassoio QZ Lite è un server di stampa locale che emula completamente il protocollo QZ Tray ma senza la sua massiccia infrastruttura. Consente la stampa di ricevute su stampanti termiche direttamente dal browser utilizzando qz-tray.js - e il tuo codice frontend richiede zero cambiamenti.

Se hai mai configurato il vassoio QZ originale per la stampa silenziosa, conosci il problema: genera coppie di chiavi, distribuisci certificati, imposta un endpoint di firma backend, raccogli {chiamata, parametri, timestamp}, calcola SHA-256 esadecimale, firmalo con la chiave privata RSA, restituisci base64 al browser e prega. Qualsiasi errore - e invece di una ricevuta, il tuo utente vede un "Consenti?" dialogo.

QZ Tray Lite rimuove tutto questo.

• IL firma E segnoAlgoritmo i campi sono ignorato. Il tuo client invia firme come al solito e riceve risposte positive: non sa mai che sta parlando con un'implementazione diversa.

• Non è richiesto alcun endpoint di firma backend. La catena di fiducia si riduce a sole due parti: browser ↔ processo locale.

• Riutilizza i certificati esistenti, ad esempio da un vassoio QZ installato (Windows considera già attendibile CN=hostlocale), oppure puoi fornire il tuo PKCS#12.

Vantaggi principali

Come funziona

Il browser si connette tramite WebSocket a localhost (wss://8181 O ws://8182). QZ Tray Lite risponde alle stesse chiamate dell'originale:

• getVersion — riporta 2.2.6 (compatibile con modern qz-tray.js);

• certificato — accetta il certificato del cliente e conferma;

• stampanti.find / stampanti.getDefault — enumera le stampanti di sistema tramite win32print;

• stampa — mette in coda i lavori per la stampa.

A coda sequenziale per stampante garantisce che le copie non si intercalino e che i lavori lunghi non blocchino il WebSocket.

Modalità di stampa supportate

1. ESC/POS grezzo

• Testo con selezione della codifica (CP1250–CP1258, IBM8xx, ISO-8859-x, GBK, Big5, Shift_JIS, UTF-8).

• Cirillico: CP1251 + ESCt comando nella ricevuta (il numero di pagina dipende dal firmware).

• Immagini: supporto completo per ESC* (singolo/doppio/triplo, compreso legacy) e GS v0. Quantizzazione: luma, alfa, nero.

• Attivato tramite tipo: "crudo" con opzioni.lingua: "escpos".

2. Stampa pixel (GDI).

• Stampa raster tramite driver della stampante con scalaContenuto, margini, unità (pollici o mm).

• NO opzioni.lingua richiesto: ideale per loghi, codici a barre, etichette.

• Attivato tramite tipo: "pixel".

Considerazioni sulla sicurezza

Importante: QZ Tray Lite è progettato per postazioni di lavoro di cassiere affidabili nelle reti locali. Lo fa deliberatamente non convalidare:

• richiedere firme (firma, segnoAlgoritmo);

• certificati client e catene di fiducia;

• timestamp (intervallo di ±15 minuti nell'originale);

• consentito.dat / bloccato.dat controllo degli accessi.

Implicazione pratica: è possibile stampare qualsiasi pagina aperta nel browser su questa macchina. Questo è un compromesso accettabile per un computer POS dedicato. Tuttavia, non farlo esporre il server su 0.0.0.0 o utilizzarlo su macchine in cui gli utenti navigano in siti Web arbitrari.

Tutte le azioni vengono registrate: ogni richiesta, ogni byte, ogni URL caricato tramite formato: "immagine" senza esplicito gusto.

Installazione e avvio rapido

Requisiti: Windows 10/11, Python 3.12+

git clone <repositorio>
cd qz-tray-lite
pitone -installazione pip -requisiti.TXT

Correre:

pitone principale.pi

Il server automaticamente:

• trova una porta libera (se 8181 è occupata prova con 8282, ecc.);

• utilizza il certificato del vassoio QZ originale se installato o consente la personalizzazione --archivio chiavi / --storepass;

• avvia sia i listener WSS che quelli WS per compatibilità.

Operazione in background: incluso strumenti/servizio.ps1 installa QZ Tray Lite come servizio Windows o attività pianificata (selezionata automaticamente in base all'ambiente). Supporta la rotazione dei registri, il monitoraggio dello stato e le policy di riavvio.

Cosa NON è implementato

Abbiamo intenzionalmente omesso funzionalità utilizzate raramente negli scenari POS:

• seriale, USB, nascosto, file, rete;

• stampanti.dettaglio, iniziareAscoltare / getStatus;

• stampa pixel da pdf E html;

• Codifica immagine: GS_L, quantizzazione: dithering, rotazione / orientamento.

Le chiamate a questi restituiscono errori chiari anziché fallire silenziosamente.

Test e debug

IL strumenti/probe.py utilità:

• esegue l'handshake del vassoio QZ;

• invia lavori di stampa di prova (il logo a scacchiera rileva gli spostamenti di bit, la cornice rileva il ritaglio dei bordi);

• dimostra che le firme non vengono convalidate: passano anche le firme non valide.

strumenti/sonda Python.pi --stampare XP-58          # ricevuta di prova
strumenti/sonda Python.pi --stampare XP-58 --pixel  # modalità pixel

65 test unitari per il convertitore di immagini ESC/POS (831 linee): byte previsti calcolati manualmente rispetto alle specifiche Epson.

Per chi è questo?

• Sviluppatori di sistemi POS che desiderano eliminare l'ingombrante QZ Tray e semplificare l'implementazione su centinaia di workstation.

• Integratori stanco di configurare certificati e firmare backend per ogni negozio.

• Proprietari di imprese con cui hai un sito qz-tray.js ma necessitano di un server di stampa locale stabile e veloce per ricevute termiche da 58 mm.

• Hobbisti che apprezzano il codice trasparente e vogliono vedere esattamente cosa viene inviato alla stampante (i log mostrano ogni byte e parametro di conversione).

Licenza

Licenza del MIT ©2026 Non so morbido

Gratuito per uso commerciale, modifica, incorporamento: è sufficiente conservare il testo della licenza e l'avviso sul copyright.

La compatibilità del protocollo del vassoio QZ si basa sull'originale qzind/vassoio progetto (LGPL-2.1). QZ Tray Lite è un'implementazione Python indipendente del protocollo lato server.

Scegliere Vassoio QZ Lite — l'alternativa leggera che fa esattamente ciò di cui ha bisogno il tuo POS e niente di più.