当前位置：首页 > news >正文

pyzk完整指南：5步轻松掌握ZKTeco考勤机Python自动化管理

news 2026/6/5 7:19:31

pyzk完整指南：5步轻松掌握ZKTeco考勤机Python自动化管理

【免费下载链接】pyzkUnofficial library of zkteco fingerprint attendance machine项目地址: https://gitcode.com/gh_mirrors/py/pyzk

还在为手动管理ZKTeco考勤机而烦恼吗？pyzk是专为ZKTeco指纹考勤机设计的非官方Python库，让你通过简单的Python代码就能实现设备连接、用户管理、考勤数据获取等自动化操作。无论你是系统集成商、企业IT管理员还是开发者，pyzk都能显著提升你的工作效率，减少人工操作错误。😊

为什么选择pyzk进行考勤机管理？

传统的考勤机管理通常需要手动在设备上操作，或者使用厂商提供的专用软件，这些方法存在诸多限制：

操作繁琐：需要现场操作设备或安装特定软件
扩展性差：难以集成到现有系统中
自动化程度低：批量操作困难，容易出错

pyzk通过Python API解决了这些问题，让你能够：

远程管理：通过网络连接远程控制设备
批量操作：一键处理大量用户和考勤数据
系统集成：轻松集成到HR系统、OA系统或自定义应用中
脚本自动化：编写脚本实现定期同步和备份

第一步：快速开始 - 安装与基础连接

安装pyzk库

开始之前，你需要先安装pyzk。最简单的方式是使用pip：

pip install -U pyzk

如果你遇到系统权限问题，可以创建一个虚拟环境：

python3 -m venv venv source venv/bin/activate pip install pyzk

建立设备连接

连接考勤机只需要3行代码：

from zk import ZK # 创建ZK实例 zk = ZK('192.168.1.201', port=4370, password=0) # 建立连接 conn = zk.connect() # 执行操作... # 断开连接 conn.disconnect()

重要提示：在实际使用中，建议使用异常处理确保连接正确关闭：

conn = None try: zk = ZK('192.168.1.201', port=4370) conn = zk.connect() # 你的业务逻辑 except Exception as e: print(f"操作失败: {e}") finally: if conn: conn.disconnect()

第二步：设备信息获取与状态监控

了解设备状态是有效管理的基础。pyzk提供了丰富的设备信息获取方法：

基础设备信息

# 获取固件版本 firmware = conn.get_firmware_version() print(f"固件版本: {firmware}") # 获取设备序列号 serial = conn.get_serialnumber() print(f"序列号: {serial}") # 获取MAC地址 mac = conn.get_mac() print(f"MAC地址: {mac}") # 获取设备名称 device_name = conn.get_device_name() print(f"设备名称: {device_name}")

设备容量监控

通过read_sizes()方法，你可以了解设备的存储使用情况：

# 读取设备容量信息 conn.read_sizes() print(f"用户数量: {conn.users}/{conn.users_cap}") print(f"指纹模板数量: {conn.fingers}/{conn.fingers_cap}") print(f"考勤记录数量: {conn.records}")

这些信息对于容量规划和维护非常重要，可以帮助你及时清理数据或扩容。

第三步：用户与权限管理模块

用户管理是考勤系统的核心功能。pyzk提供了完整的用户CRUD操作。

用户增删改查

添加新用户：

from zk import const # 添加普通用户 conn.set_user( uid=1, name="张三", privilege=const.USER_DEFAULT, password="123456", user_id="001" ) # 添加管理员用户 conn.set_user( uid=2, name="管理员", privilege=const.USER_ADMIN, password="admin123", user_id="admin" )

查询用户列表：

users = conn.get_users() for user in users: privilege = "普通用户" if user.privilege == const.USER_DEFAULT else "管理员" print(f"用户ID: {user.uid}, 姓名: {user.name}, 权限: {privilege}")

删除用户：

# 根据UID删除用户 conn.delete_user(uid=1) # 或者根据用户编号删除 conn.delete_user(user_id="001")

批量用户操作

对于需要处理大量用户的情况，pyzk支持批量操作：

# 批量添加用户 users_to_add = [ {"uid": 1, "name": "张三", "user_id": "001"}, {"uid": 2, "name": "李四", "user_id": "002"}, {"uid": 3, "name": "王五", "user_id": "003"} ] for user_data in users_to_add: conn.set_user(**user_data)

第四步：指纹模板与考勤记录管理

指纹模板管理

指纹模板管理位于zk/finger.py模块中：

获取指纹模板：

# 获取单个用户的指纹模板 template = conn.get_user_template(uid=1, temp_id=0) # temp_id为手指编号0~9 # 获取所有指纹模板 fingers = conn.get_templates() for finger in fingers: print(f"用户ID: {finger.uid}, 手指编号: {finger.fid}")

指纹录入（远程）：

# 远程指纹录入 conn.enroll_user(uid=1)

批量保存指纹模板：

# 准备用户和指纹数据 usertemplates = [ [user_1, [finger1, finger2]], [user_2, [finger3]], # ... 更多用户 ] # 高速保存 conn.HR_save_usertemplates(usertemplates)

考勤记录处理

考勤记录管理位于zk/attendance.py模块中：

获取考勤记录：

attendances = conn.get_attendance() for att in attendances: print(f"用户ID: {att.user_id}, 时间: {att.timestamp}, 状态: {att.status}")

实时考勤监控：

# 实时捕获考勤事件（10秒超时） for attendance in conn.live_capture(): if attendance is None: # 超时处理逻辑 print("等待考勤事件...") else: print(f"新考勤记录: {attendance}")

清理考勤数据：

# 清空考勤记录 conn.clear_attendance()

第五步：高级功能与设备控制

设备维护操作

设备重启与关机：

# 重启设备 conn.restart() # 关闭设备 conn.poweroff() # 锁定设备（3秒） conn.unlock(time=3) # 清除LCD显示 conn.clear_lcd()

数据清理（谨慎使用）：

# 警告：此操作会清除所有数据（用户、考勤记录、指纹） conn.clear_data()

语音测试功能

考勤机支持多种语音提示，你可以测试不同的语音效果：

# 测试语音提示 conn.test_voice(index=0) # 说"谢谢" conn.test_voice(index=1) # 说"密码错误" conn.test_voice(index=30) # 说"无效用户"

完整的语音索引列表可以在example/test_voice.py中找到。

时间同步

确保设备时间准确对考勤系统至关重要：

from datetime import datetime # 获取设备当前时间 device_time = conn.get_time() print(f"设备时间: {device_time}") # 同步服务器时间到设备 current_time = datetime.now() conn.set_time(current_time) print(f"已同步时间: {current_time}")

实际应用场景与最佳实践

场景一：每日考勤数据同步

def daily_attendance_sync(device_ip): """每日考勤数据同步脚本""" conn = None try: zk = ZK(device_ip, port=4370) conn = zk.connect() # 获取当天考勤记录 attendances = conn.get_attendance() today = datetime.now().date() today_records = [] for att in attendances: if att.timestamp.date() == today: today_records.append(att) # 保存到数据库或文件 save_to_database(today_records) print(f"成功同步{len(today_records)}条考勤记录") except Exception as e: print(f"同步失败: {e}") finally: if conn: conn.disconnect()

场景二：批量用户导入

def batch_user_import(device_ip, user_list): """批量导入用户""" conn = None try: zk = ZK(device_ip, port=4370) conn = zk.connect() success_count = 0 for user_data in user_list: try: conn.set_user(**user_data) success_count += 1 print(f"成功导入用户: {user_data['name']}") except Exception as e: print(f"导入用户{user_data['name']}失败: {e}") print(f"批量导入完成，成功{success_count}/{len(user_list)}") except Exception as e: print(f"连接失败: {e}") finally: if conn: conn.disconnect()

场景三：设备健康检查

def device_health_check(device_ip): """设备健康检查""" conn = None try: zk = ZK(device_ip, port=4370) conn = zk.connect() # 检查连接状态 print("✓ 设备连接正常") # 检查设备信息 firmware = conn.get_firmware_version() print(f"✓ 固件版本: {firmware}") # 检查存储容量 conn.read_sizes() usage_percent = (conn.users / conn.users_cap) * 100 print(f"✓ 用户容量: {conn.users}/{conn.users_cap} ({usage_percent:.1f}%)") # 检查时间同步 device_time = conn.get_time() server_time = datetime.now() time_diff = abs((device_time - server_time).total_seconds()) if time_diff > 60: # 超过1分钟差异 print(f"⚠ 时间不同步: 设备时间{device_time}, 服务器时间{server_time}") conn.set_time(server_time) print("✓ 已同步时间") else: print("✓ 时间同步正常") return True except Exception as e: print(f"✗ 健康检查失败: {e}") return False finally: if conn: conn.disconnect()