简介这是一份晨晖智能一卡通管理系统的完整用户手册面向物业管理部门和相关技术人员用于指导基于 Windows XP/7 的水电一卡通收费管理软件的安装、配置与日常使用。资源包仅含 1 个 doc 文档压缩后大小约 2.13MB内容为逐章展开的操作文本目前已有 288 人学习下载。手册先介绍系统先进性、功能完备性、结构严密性与界面美观性等特点再说明自解压安装和登录方式并给出默认管理员工号 sa 与密码 888888 的初始化提示。随后详述系统启用前的 10 个关键设置步骤定义使用单位、增加住址、设置操作员组与权限、定义操作员、水电价格、表型、用户类型、读写卡器连接、数据备份及票据打印选项同时配有 IC 卡发卡/回收、读任意卡、制作清零卡和换表卡等专项操作说明。该文档对初次部署或维护同类智能一卡通系统的用户具有较强实用参考价值。1. 晨晖智能一卡通管理系统资料全先抓住数据主线拿到一份名为「晨晖智能一卡通管理系统1资料全.doc」的资料包时你会发现里面常常塞满了设备说明书、数据库脚本和部署截图。但真正上线时卡发不出去、门禁控制器不响应、消费流水对不上账通常不是资料少而是没把「卡号、设备、流水、权限」这条数据主线理清楚。晨晖这类一卡通系统本质是一套以卡号为索引、以流水为证据链的实时数据平台门禁、考勤、消费、水控都围绕同一条主线运行。我会按系统集成的顺序把设备接入、数据库建模、Web API 对接和上线排坑这四段讲透适合负责实施、运维或二次开发的 IT 工程师。2. 一卡通设备接入从 RS485 读卡器到门禁控制器的数据链路2.1 设备类型与通信接口选型先明确设备层怎么分。晨晖这类一卡通系统底层设备通常包括发卡器、门禁读卡器、门禁控制器、消费机、水控器和考勤机。不同设备的接口差异很大选型时先看这张表| 设备类型 | 常用接口 | 数据方向 | 核心内容 | | 发卡器 | USB / RS232 | 后台 - 卡片 | 卡号、扇区密钥 | | 门禁读卡器 | 韦根 26/34 | 读卡器 - 控制器 | 卡号 奇偶校验 | | 门禁控制器 | RS485 / 以太网 | 控制器 - 后台 | 权限白名单、事件上报 | | 消费机 | RS485 / CAN / 以太网 | 消费机 - 后台 | 扣款流水、黑名单 | | 水控器 | RS485 / M-Bus | 水控器 - 后台 | 计量脉冲、扣费 |韦根接口只能单向传卡号适合读卡器到控制器这一段RS485 是半双工总线适合控制器到后台的批量数据同步。一个 RS485 总线一般最多挂接 32 到 128 个节点波特率常用 9600超过数量就要分路或用以太网控制器。我处理过的项目里门禁和消费机混用的场景最稳妥的做法是门禁用 RS485 分线消费机用独立总线避免高峰期报文互相干扰。接线时还要注意 A/B 极性不能反总线首尾各接一个 120 欧终端电阻。上电前先量一下设备拨码地址有没有冲突否则后台轮询时会收到两个设备同时应答的错乱帧。Linux 主机接入串口服务器后先用dmesg | grep tty确认节点再用python -m serial.tools.list_ports列出可用串口。# 查看内核分配给 USB 转串口芯片的设备节点 sudo dmesg | grep -i ttyUSB | tail -10 # 列出 python 可识别的串口 python3 -m serial.tools.list_ports -v这里ttyUSB*是 USB 转 485 的常见设备节点如果插入后没有出现大概率是 CP210x/CH340 驱动没装或者线材质量不好。命令输出里会带 USB 转串口的芯片型号方便确认驱动状态。2.2 串口通讯的轮询与主动上报控制器的消息模式分为被动轮询和主动上报两种。被动轮询由后台按设备地址依次发送查询命令设备应答这段时间内的流水优点是协议简单、调试方便缺点是设备多了以后一轮下来可能要几十秒门禁开门的实时性差。主动上报则由控制器在事件发生时主动把数据帧拖到后台实时性好但后台需要处理粘包和丢包重传。实际项目里我一般选择「主动上报为主后台定时补拉兜底」。补拉周期设成 5 分钟一次只拿上一次成功游标之后的数据这样即使网络抖动也不会漏账。下面是串口收包的基本骨架按帧头0xAA、长度字段切包把完整帧放入队列后续由解析线程按设备地址分发。import serial from queue import Queue ser serial.Serial( port/dev/ttyUSB0, baudrate9600, bytesize8, parityN, stopbits1, timeout0.5 ) frame_q Queue() def read_frames(): buf bytearray() while True: chunk ser.read(32) if not chunk: continue buf.extend(chunk) # 逐字节找帧头避免粘包后丢帧 while len(buf) 4: if buf[0] ! 0xAA: buf.pop(0) continue length buf[1] if len(buf) length 4: break frame_q.put(bytes(buf[:length 4])) del buf[:length 4]baudrate必须和设备拨码一致常见的 9600、19200、57600 都有timeout设 0.5 秒是为了在读不到数据时释放 CPU避免死循环。这里的length代表数据长度完整的帧开销是帧头 长度 数据 校验 帧尾所以buf[1]等于多少就取多少字节加 4 字节额外字段。2.3 韦根卡号与数据帧解析门禁读卡器输出的是韦根 26/34 信号控制器把高低电平组合解成卡号后再按 RS485 帧转发给后台。调试时最需要在串口抓一帧看卡号是否和卡面印刷号一致。以常见 Wiegand 26 帧为例1 位偶校验、8 位设施代码、16 位卡号、1 位奇校验共 26 比特。后台解析时不要直接拿二进制转十进制很多控制器会按字节高低位反转再输出。拿到数据帧后关键字段是设备地址、卡号、事件类型、时间戳和余额。先按设备地址拆到对应缓冲再按事件类型路由到不同业务流程。项目交付时我会要求厂商提供一份「帧字段偏移表」放在资料包第一页避免后期靠猜。曾经遇到一次消费机返回的金额是 BCD 码直接用十六进制转整数导致每笔都翻了几十倍这就是解析协议没走通的代价。提示串口调试严格使用二进制文件描述符不要用文本模式否则0x0A0x0D会被操作系统转换帧长永远对不齐。3. 建好消费与门禁流水表一卡通数据库的 6 张核心表3.1 为什么流水表不能只存一张大表一卡通系统每天产生的刷卡事件很多但消费、门禁、考勤三种事件的字段差异很大。消费记录需要金额、余额和消费机编号门禁记录需要进出方向和验证方式考勤记录需要关联班次。如果全塞进一张 event 表会产生大量 null 字段索引也做不细。但完全不建统一流水表对账又会很痛苦。所以常见的做法是「明细分表、汇总统一」底层按事件类型拆表对外查询统一走视图或在接口层聚合。这里我用的 6 张核心表分别是组织表、员工表、卡片表、设备表、事件流水表和权限下发任务表。组织表和员工表用来支撑权限继承卡片表保存卡号与人的关系及余额设备表保存设备地址、通讯参数和状态流水表存所有刷卡事件权限下发表记录每台设备收到过哪个版本的权限。后两张表是排查线上问题时的关键。职责一览如下| 表名 | 职责 | 关键点 | | t_org | 部门/区域结构 | 权限继承 | | t_employee | 员工基本信息 | 组织关联 | | t_card | 卡片与余额 | 卡号唯一 | | t_device | 设备通讯参数 | 地址/端口 | | t_transaction | 全部刷卡流水 | 对账依据 | | t_download_task | 权限下发记录 | 数据版本控制 |3.2 员工表和卡片表的结构员工表和卡片表的建表语句如下。注意员工编号和卡号都要加唯一索引一卡通系统里这两个字段一旦重复后面所有的权限下发和流水归属都会错乱。CREATE TABLE t_employee ( emp_id INT UNSIGNED PRIMARY KEY AUTO_INCREMENT, org_id INT UNSIGNED NOT NULL, emp_no VARCHAR(32) NOT NULL, emp_name VARCHAR(64) NOT NULL, status TINYINT NOT NULL DEFAULT 1, updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, UNIQUE KEY uk_emp_no (emp_no), KEY idx_org (org_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT员工表; CREATE TABLE t_card ( card_id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, emp_id INT UNSIGNED NOT NULL, physical_no CHAR(16) NOT NULL, card_no CHAR(8) NOT NULL, card_type TINYINT NOT NULL DEFAULT 0, balance DECIMAL(10,2) NOT NULL DEFAULT 0, status TINYINT NOT NULL DEFAULT 1, expire_date DATE DEFAULT NULL, UNIQUE KEY uk_physical_no (physical_no), UNIQUE KEY uk_card_no (card_no), KEY idx_emp (emp_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT卡片表;代码里的card_no是逻辑卡号设备上报时用的是这个号physical_no是卡身印刷号发卡时扫印刷号写入卡片避免两者混淆。status字段我习惯用 1 表示正常、2 表示挂失、3 表示注销四个状态以上就容易出乱。余额存在卡片表里是为了查询快真正的扣款流水只依赖流水表不能靠余额做对账。3.3 统一流水表与权限下发表流水表是所有刷卡记录的落点。我建议保留原始报文帧即使应用逻辑有 bug也能用原始报文重放排查。建表语句如下CREATE TABLE t_transaction ( tx_id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, card_no CHAR(8) NOT NULL, device_id INT UNSIGNED NOT NULL, evt_type TINYINT NOT NULL COMMENT 1消费 2门禁 3考勤, amount DECIMAL(10,2) NOT NULL DEFAULT 0, balance_after DECIMAL(10,2) NOT NULL DEFAULT 0, trans_time DATETIME NOT NULL, raw_frame VARCHAR(512) NOT NULL, create_time TIMESTAMP DEFAULT CURRENT_TIMESTAMP, KEY idx_card_time (card_no, trans_time), KEY idx_dev_time (device_id, trans_time) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT事件流水表;联合索引(card_no, trans_time)服务「某个人某一天刷了多少次」这类查询(device_id, trans_time)服务「某台设备某段时间的流水对账」。流水表的数据量增长很快生产环境建议按月份做 MySQL 分区或者按月归档到单独的历史表。raw_frame长度设 512 已经能覆盖常见的一帧 64 字节报文长报文可以存到文件后只留文件名。权限下发任务表用来追踪后台发给控制器的权限版本。控制器只能接受版本号比当前大的任务否则网络抖动导致旧任务后到会把新权限覆盖掉。CREATE TABLE t_download_task ( task_id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT, device_id INT UNSIGNED NOT NULL, data_version INT UNSIGNED NOT NULL, status TINYINT NOT NULL DEFAULT 0, retry_count TINYINT NOT NULL DEFAULT 0, create_time DATETIME NOT NULL, finish_time DATETIME DEFAULT NULL, KEY idx_dev_status (device_id, status) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT权限下发表;data_version每次批量下发时取当前时间戳下发完成后回填finish_time。这样在控制器侧可以用一个ack_version字段做比对就知道后台有没有发到最新版本。很多项目掉权限不是卡的问题而是控制器里旧版本没被覆盖。4. 用 Web API 把晨晖智能一卡通管理系统对接给 OA 与薪资系统4.1 接口设计原则与签名OA、薪资系统需要访问一卡通时不建议直接把数据库账号暴露给它们常见做法是封装一层 REST API。接口路径、方法和用途先定下来| 接口 | 方法 | 路径 | 用途 | | 查询卡片余额 | GET | /api/v1/cards/{card_no}/balance | OA 展示余额 | | 查询事件流水 | GET | /api/v1/transactions | 对账、考勤统计 | | 挂失卡片 | POST | /api/v1/cards/{card_no}/block | 安全中心远程锁卡 |接口不能裸奔至少要做签名校验。每个请求带app_key、timestamp、sign防止重放。签名生成顺序将非空的 query 参数按 key 排序拼接成keyvalue字符串再拼上secret做 SHA256。这样即使流量被截获没有secret也伪造不出合法签名。# 生成签名的通用函数服务端保存相同的 secret import hashlib def make_sign(params: dict, secret: str) - str: raw .join(f{k}{v} for k, v in sorted(params.items())) raw fsecret{secret} return hashlib.sha256(raw.encode()).hexdigest()params需要包含所有非空 query 参数但不要把sign本身放进去。secret只保存在服务端环境变量和后台配置里客户端拿到明文 secret 就等于签名失效。4.2 实现一个带签名校验的流水查询用 FastAPI 写一个查询接口接收卡号、时间范围、分页大小和签名返回统一格式的 JSON。这里使用pymysql直接操作数据库方便改造成现有项目。from fastapi import FastAPI from fastapi.responses import JSONResponse import pymysql app FastAPI() SECRET change-me-in-prod # 生产环境从环境变量读取 def verify_sign(params: dict, sign: str) - bool: expected make_sign(params, SECRET) return expected sign app.get(/api/v1/transactions) def list_transactions(card_no: str , start: str , end: str , limit: int 100, sign: str ): params {card_no: card_no, start: start, end: end, limit: str(limit)} if not verify_sign(params, sign): return JSONResponse({code: 401, msg: bad sign}, status_code401) limit min(limit, 200) # 防止一次拉取过多 conn pymysql.connect(host127.0.0.1, usericcard, passwordiccard, databaseiccard) try: with conn.cursor(pymysql.cursors.DictCursor) as cur: sql SELECT tx_id, card_no, device_id, evt_type, amount, balance_after, trans_time FROM t_transaction WHERE 11 args [] if card_no: sql AND card_no%s args.append(card_no) if start: sql AND trans_time%s args.append(start) if end: sql AND trans_time%s args.append(end) sql ORDER BY trans_time DESC LIMIT %s args.append(limit) cur.execute(sql, args) rows cur.fetchall() finally: conn.close() return {code: 0, data: rows}代码逻辑不复杂先验签再拼 SQL最后返回结果。注意pymysql的%s占位符必须参数化不能直接拼接用户输入limit min(limit, 200)是硬上限避免对账程序一次拉走全表拖垮数据库。启动服务用uvicorn iccard_api:app --host 0.0.0.0 --port 8000 --workers 4workers数量一般和 CPU 核心数一致但要注意SECRET从环境变量读取时每个 worker 进程会各自加载一次改配置后必须重启所有 worker。4.3 对账分页的游标策略对账程序拉流水时如果按页码分页新增数据会导致某页数据重复或跳过。常见做法是记录游标第一次查询取时间范围内的前 100 条记录最后一条trans_time和tx_id下一次查询把时间起点设为本批次最后一条时间并加上tx_id 上一批次末尾 tx_id作为补充条件。这样任何时间点重启对账都能从断点继续。具体到 SQL 上是把原来LIMIT offset, size的写法改成WHERE trans_time %s AND tx_id %s ORDER BY trans_time, tx_id LIMIT %s。开发同事如果已经用了页码分页建议尽快改掉否则对账越往后偏差越大。5. 上线的最后一公里校时、密钥与流水对账5.1 统一校时设备时间不一致流水排序和按时间对账会错得离谱。上线时在管理后台配好 NTP 服务器地址设备每天凌晨 3 点自动校时。内网环境的服务器可以自己跑时间源# 安装 chrony 并指定内网时间源 apt install -y chrony echo server 192.168.100.1 iburst /etc/chrony/chrony.conf systemctl restart chrony如果不方便改设备配置至少要在后台程序里记录设备上报时间和服务器接收时间两个字段差值超过 2 分钟就告警。5.2 卡片密钥与发卡安全默认出厂的 Mifare 卡密钥通常是全FF上线前必须重发。密钥要按扇区分组不要所有扇区用同一个密钥。CPU 卡则要由发卡母卡分散出子密钥分散因子用卡号。资料包里看到密钥文件时先确认它的加密方式明文密钥文件放在生产服务器上等于没设防。导入密钥时用加密机或离线工具完成发卡器所在电脑不连外网。5.3 流水对账验证方法上线前先做小流量验证选三台设备每台刷 50 次覆盖消费、门禁和考勤三种事件。然后用下面的 SQL 统计数据库计数SELECT device_id, COUNT(*) AS db_cnt, SUM(CASE WHEN evt_type1 THEN 1 ELSE 0 END) AS pay_cnt, SUM(CASE WHEN evt_type2 THEN 1 ELSE 0 END) AS door_cnt FROM t_transaction WHERE trans_time BETWEEN 2025-03-01 00:00:00 AND 2025-03-01 23:59:59 GROUP BY device_id;再和设备管理软件导出的流水计数对比如果差值不为 0优先查raw_frame里有没有解析失败被丢弃的帧。计数器对上了再抽查几笔金额。都通过后开放全量。上生产前先随机选三台设备各刷 50 次比对计数和金额再放量。本文还有配套的精品资源点击获取
