zkteco-lan-portal

A local web portal that runs on your computer (or any machine inside the same LAN as the biometric device) and lets you:

• Scan & discover ZKTeco time-attendance devices on your LAN (or connect by manually entering IP)
• View Employees / Users
• View Attendance logs

No port forwarding needed, because the portal talks to the device locally over LAN.

Why this works (no port forwarding)

Your cloud/Laravel app can’t directly reach the device when it sits behind NAT/firewall.
This package runs inside the same LAN as the device, so it can connect to the device’s ZK protocol port locally.

This package uses zk-attendance-sdk under the hood (TCP first, falls back to UDP).
See its API reference / quick start in their README.
(Methods like createSocket(), getUsers(), getAttendances(), etc.)

Install

Option A) Run once with npx (recommended)

npx zkteco-lan-portal

Option B) Install globally

npm i -g zkteco-lan-portal
zkteco-lan

Usage

Start the portal

zkteco-lan

By default it:

• starts on http://127.0.0.1:3717
• opens your browser automatically

Useful options

zkteco-lan --port 5000
zkteco-lan --host 0.0.0.0     # access from other devices in same LAN (phone, other PC)
zkteco-lan --no-open          # do not auto-open browser

Web UI

Open the web UI in your browser:

• http://127.0.0.1:3717

Tabs:

1. Discover: scan subnet, or enter IP manually
2. Employees: fetch & display users
3. Attendance: fetch & display attendance logs (with optional date filter)

API (if you want to integrate with Laravel)

The UI is built on these endpoints (you can call them from Laravel too):

• GET /api/network → local IPv4 suggestions
• POST /api/scan → scan subnet and return discovered devices
• POST /api/connect → validate IP:port and return basic info
• GET /api/users?ip=...&port=... → users
• GET /api/attendances?ip=...&port=...&from=YYYY-MM-DD&to=YYYY-MM-DD → logs

Example:

curl "http://127.0.0.1:3717/api/users?ip=192.168.1.106&port=4370"

Notes / Troubleshooting

• Attendance fields vary by device firmware. This portal normalizes logs to:

  • userId_norm, timestamp_iso, state_norm, type_norm, rawTime If your table looks empty, open “Raw sample (first log)” to see the device’s actual keys and we can map them.

• Ensure the PC running this tool is on the same LAN/VLAN as the device.

• Ensure device port is reachable (typically 4370).

• Some networks block broadcast/multicast; manual IP entry will still work.

• If your device has a different port or is configured differently, use manual connect.

Roadmap ideas (optional)

• CSV export, pagination, caching, and scheduled sync to a cloud endpoint
• Multi-device dashboard & real-time log streaming

License

MIT