Ringkasan Utama
Printer TM berjaringan mendengarkan di TCP port 9100 dan hanya menerima satu sesi cetak mentah pada satu waktu. Sebagian besar kegagalan di lapangan adalah klien kedua yang menahan sesi itu, soket setengah terbuka setelah listrik padam, atau sewa DHCP yang memindahkan alamat printer — semuanya bisa didiagnosis di bawah satu menit dengan netcat dan ss.
Memindahkan printer struk ke jaringan memecahkan masalah nyata: satu printer, beberapa kasir, tanpa kabel melintang di meja. Ia juga mengganti kabel yang bisa Anda lihat dengan sekumpulan mode kegagalan yang tidak bisa Anda lihat, dan saat pertama kali toko menelepon mengatakan pencetakan berhenti, tidak satu pun naluri debugging web yang biasa terpakai.
Ini urutan troubleshooting yang kini saya pakai, dari lapisan yang paling sering gagal ke yang paling jarang, ditambah desain antrean yang membuat kegagalan itu bisa dilewati alih-alih memalukan.
Port 9100 itu sebenarnya apa
Printer TM berjaringan membuka port cetak mentah di TCP 9100 — konvensi yang sama yang dimulai HP dengan JetDirect dan kini diikuti hampir semua printer jaringan. Tidak ada protokol di atasnya: Anda membuka koneksi TCP, menulis byte ESC/POS, printer mencetaknya, dan menutup koneksi menandakan akhir pekerjaan. Kesederhanaan itu adalah daya tariknya sekaligus jebakannya.
Jebakannya, port mentah tidak punya sesi, tidak punya autentikasi, dan pada sebagian besar firmware tidak punya antrean. Printer melayani satu koneksi; klien kedua yang mencoba mencetak pada saat yang sama entah ditolak atau dibiarkan menunggu, dan aplikasi Anda melihat koneksi yang menggantung, bukan error yang menjelaskan dirinya.

Empat pemeriksaan yang menemukan sebagian besar gangguan
Sebelum menyentuh aplikasi, buktikan lapisan mana yang rusak. Setiap pemeriksaan berikut hanya butuh beberapa detik dan menyingkirkan satu kategori penyebab utuh.
- Apakah printernya terjangkau sama sekali? Entri ARP membuktikan ia ada di subnet ini; tidak ada entri biasanya berarti alamatnya berubah atau printer berada di jaringan tamu.
- Apakah portnya terbuka? Probe netcat tiga detik membedakan printer yang mati, printer yang sibuk, dan aturan firewall.
- Bisakah ia mencetak tanpa perangkat lunak Anda? Mengalirkan sedikit byte plus perintah potong langsung ke port memberi tahu apakah gangguannya di atas atau di bawah aplikasi Anda.
- Siapa lagi yang sedang terkoneksi? Satu koneksi established dari host tak terduga menjelaskan hampir semua hang yang muncul sesekali, dan biasanya itu antrean cetak lama di PC manajer yang tak seorang pun ingat pernah dikonfigurasi.
# Is the print port even open? Three seconds of truth.
nc -vz -w 3 192.168.1.50 9100
# Print a line without any application in the way.
printf 'NETWORK TEST\n\n\n\n\x1dVB\x00' | nc -w 5 192.168.1.50 9100
# Who else is holding the single print session open?
ss -tnp | grep ':9100'
# Is the printer answering ARP, i.e. is it on this subnet at all?
arp -n | grep 192.168.1.50Dalam pengalaman saya, pemeriksaan keempat menemukan masalah lebih sering daripada tiga lainnya digabung. Toko mengakumulasi konfigurasi cetak: kasir cadangan, laptop yang disiapkan saat masa uji coba, antrean Windows yang mencoba ulang selamanya. Salah satunya saja bisa menahan sesi yang dibutuhkan POS Anda.
Jangan pernah membiarkan printer struk jaringan memakai DHCP. Pembaruan sewa setelah listrik padam memindahkan printer ke alamat baru, semua kasir gagal serentak, dan gejalanya tidak bisa dibedakan dari printer mati. Pesan alamatnya di router atau setel statis, lalu tulis alamat itu di label yang ditempel pada printer.
Soket setengah terbuka, dan kenapa penulisan berhasil ke ketiadaan
Kegagalan paling membingungkan adalah ketika kode Anda melaporkan sukses dan kertas tidak bergerak. Ini terjadi saat printer menghilang — tercabut, dimatikan, switch di-reboot — sementara proses Anda masih memegang koneksi TCP. Tidak ada yang memberi tahu sistem operasi, jadi penulisan masuk ke buffer kirim dan kembali dengan gembira sampai koneksinya akhirnya timeout, beberapa menit kemudian.
// A half-open socket is the classic ghost failure: the printer was
// unplugged, the switch never told us, and write() happily succeeds
// into a dead connection. Bound every stage.
const CONNECT_TIMEOUT_MS = 3000;
const WRITE_TIMEOUT_MS = 8000;
const KEEPALIVE_DELAY_MS = 1000;
socket.setNoDelay(true); // receipts are small; do not Nagle them
socket.setKeepAlive(true, KEEPALIVE_DELAY_MS);
socket.setTimeout(WRITE_TIMEOUT_MS);
// Never reuse a socket across receipts. One job, one connection,
// one close — the close is what tells the printer the job ended.Dua kebiasaan menghapusnya. Buka koneksi per struk alih-alih menahan satu koneksi tetap terbuka, sehingga koneksi mati dibuang dalam satu transaksi, bukan bertahan sepanjang hari. Dan setel timeout serta keepalive secara eksplisit pada soket, agar kernel menyelidiki lawan bicaranya alih-alih memercayai tautan yang sudah tidak ada.
Urutan troubleshooting yang mengerucut
Ketika toko menelepon, urutan ini sampai ke penyebab dalam sekitar lima menit tanpa perlu datang ke lokasi.
- Pastikan alamatnya. Minta seseorang membaca labelnya, lalu periksa halaman status jaringan atau self test printer untuk melihat alamat yang ia yakini miliknya.
- Probe portnya dari kasir yang gagal, bukan dari laptop Anda. VLAN berbeda, hasil berbeda — dan perbedaan itu sendiri sudah merupakan diagnosis.
- Cetak string uji langsung ke port. Kalau kertas bergerak, printer dan jaringan baik-baik saja dan bug-nya ada di aplikasi atau antreannya.
- Daftar koneksi established ke port 9100 dari setiap mesin di toko. Matikan yang asing.
- Baru setelah itu baca log aplikasi Anda, yang kini menjadi tersangka terakhir alih-alih tempat pertama untuk menebak.
Menuliskan urutan ini ke dalam runbook dukungan lebih berjasa bagi keandalan cetak kami daripada perubahan kode mana pun, karena ia menghentikan refleks merestart perangkat lunak POS sebagai respons pertama terhadap gangguan jaringan.

Antrean yang membuat kegagalan bisa dilewati
Mengingat jaringan pasti kadang gagal, tujuan desainnya bukan mencegah kegagalan melainkan memastikan cetak yang gagal tidak pernah menghilangkan penjualan dan tidak pernah mencetak dua kali. Itu masalah basis data, bukan masalah pencetakan, dan skema di bawah adalah seluruh idenya.
-- The print queue that makes a timeout survivable.
create table print_jobs (
id uuid primary key,
payment_id uuid not null unique, -- one receipt per payment, ever
printer_host text not null,
payload bytea not null,
attempts int not null default 0,
state text not null default 'queued',
last_error text,
created_at timestamptz not null default now(),
printed_at timestamptz
);
-- The unique constraint on payment_id is the whole idempotency story:
-- a retried API call cannot enqueue a second receipt, and a worker
-- crash between "sent" and "printed_at" leaves a row a human can see.Batasan unik pada pengenal pembayaran adalah bagian yang menanggung beban. Ia membuat percobaan ulang aman, yang pada gilirannya membuat percobaan ulang agresif aman, dan itulah yang memungkinkan toko terus berjualan melewati gangguan jaringan dua menit lalu menerima semua struknya setelah itu.
Ekspos kedalaman antrean dan umur pekerjaan tercetak tertua sebagai metrik kesehatan, lalu pasang alarm pada umurnya, bukan kedalamannya. Toko dengan dua belas struk mengantre saat tutup itu wajar; toko dengan satu struk yang sudah mengantre enam menit berarti punya printer yang offline tanpa disadari siapa pun.
Memilih antara jaringan dan lokal
Cetak jaringan tidak otomatis pilihan yang lebih baik. Ada tiga situasi di mana saya masih sengaja memakai USB atau serial.
- Satu kasir, satu printer, berjarak satu meter. Sebuah kabel menghapus satu kelas kegagalan utuh dengan harga sebuah kabel.
- Toko yang jaringannya adalah router konsumen yang dibagi dengan wifi pelanggan. Lalu lintas cetaknya sepele, tetapi perilaku DHCP router itu di bawah beban tidak sepele.
- Printer dapur di lingkungan panas dan lembap, di mana switch jaringan menjadi satu benda lagi yang bisa rusak. Serial memang tidak keren dan sangat sulit dimatikan.
Port 9100 adalah antarmuka yang indah karena sederhana dengan satu aturan keras — satu sesi pada satu waktu — dan sebagian besar insiden cetak jaringan adalah aturan itu dilanggar oleh sesuatu yang tak seorang pun ingat pernah memasangnya. Diagnosis dari jaringan ke atas, bukan dari aplikasi ke bawah, pakai koneksi per struk dengan timeout sungguhan, dan taruh antrean idempoten di belakangnya agar kasus terburuknya adalah penundaan, bukan struk yang hilang.

