人脸门禁这个场景看起来简单——刷脸、开门、记录三件事。但真正落到项目里尤其是涉及国产化环境比如银河麒麟操作系统、OpenHarmony终端设备的时候通信链路怎么设计就成了一个绕不开的架构决策。我做过几个不同规模的门禁项目有单机离线的小型办公场景也有几十台设备联网的园区场景每次都会遇到同一个问题HTTP API 和 MQTT 到底该用哪个还是两个都用这个问题没有标准答案但有一套清晰的判断逻辑。我踩过的坑包括用 HTTP 轮询做实时开门指令导致延迟高到用户以为设备坏了、用 MQTT 传大尺寸人脸特征值把 broker 内存打满、在银河麒麟上跑 MQTT 客户端时遇到依赖库版本冲突等等。这篇文章就把这些经验完整梳理一遍从协议特性、场景匹配、实操配置到踩坑排查尽量把每个决策背后的为什么讲清楚。1. 先搞清楚门禁系统里数据到底分几类很多人一上来就纠结选 HTTP 还是 MQTT但这个问题本身就问错了。正确的问法是我的系统里有哪几种数据流每种数据流的特征是什么因为在一个完整的人脸门禁系统里数据流至少可以分成四类每类的通信需求完全不同。1.1 人脸特征值的下发与同步这是数据量最大的一类。一张人脸的特征值通常是 512 维或 1024 维的浮点向量也有量化成 int8 的版本大小在 1KB 到 4KB 之间加上人员信息、权限配置、有效期等元数据单条记录可能到 5KB 到 10KB。一个中型园区如果有 2000 人全量同步一次就是 10MB 到 20MB 的数据量。这类数据的特点是低频、大批量、要求可靠性高。你不需要每秒钟都同步人脸库但每次同步必须完整、准确不能丢包。这种特征天然适合 HTTP API——请求-响应模式有明确的成功/失败状态码支持分页拉取断点续传也好做。1.2 开门指令的下发这是实时性要求最高的一类。用户在门口站定人脸识别通过后系统需要在几百毫秒内把开门指令送到门锁控制器。如果超过 1 秒用户就会觉得怎么还没开体验直线下降。这类数据的特点是高频、小包、要求低延迟。每条指令可能只有几十个字节设备 ID 指令类型 时间戳但延迟必须控制在 500ms 以内。这种特征适合 MQTT——长连接、发布/订阅模式、消息直达不需要每次建立连接。1.3 通行记录的实时上报每次开门都会产生一条通行记录谁、什么时候、哪个门、识别方式、温度如果有测温模块等。这些记录需要实时上报到中心平台用于实时监控和后续统计分析。这类数据的特点是高频、小包、允许偶尔丢包但要求最终一致。MQTT 的 QoS 1 级别至少送达一次就很适合既保证了可靠性又不会像 QoS 2 那样带来额外的握手开销。1.4 设备状态与心跳设备的在线状态、CPU 温度、内存占用、网络质量、固件版本等信息需要定期上报。这类数据的特点是周期性、极小包、允许丢失。MQTT 的遗嘱消息Last Will and Testament机制天然适合做设备离线检测——设备断线时 broker 自动发布离线消息中心平台立刻知道。把这四类数据梳理清楚之后架构决策就清晰了数据类别数据量频率延迟要求推荐协议理由人脸特征值同步大KB~MB低秒级HTTP API请求-响应模式可靠性高支持分页开门指令下发小100B高500msMQTT长连接消息直达延迟低通行记录上报小1KB高秒级MQTTQoS 1 保证可靠异步不阻塞设备状态心跳极小100B周期分钟级MQTT遗嘱消息天然支持离线检测注意这个划分不是绝对的。如果你的系统只有几台设备全部用 HTTP 也能跑只是实时性会差一些。但如果设备数量超过 20 台或者对开门延迟有明确要求就建议按上面的方式拆分。2. HTTP API 在人脸门禁里的真实定位HTTP API 在门禁系统里扮演的角色更像是管理系统而不是控制系统。它负责的是那些对实时性不敏感、但对数据完整性要求高的操作。2.1 人脸库的增删改查为什么必须走 HTTP人脸库的管理操作包括新增人员、删除人员、修改权限、查询人员信息、批量导入导出。这些操作的共同特征是需要明确的成功/失败反馈且操作结果需要持久化。HTTP 的请求-响应模式天然适合这种场景。你发一个 POST 请求新增人员服务器返回 201 Created 就表示成功返回 409 Conflict 就表示人员已存在返回 400 Bad Request 就表示参数有问题。这种明确的语义是 MQTT 给不了的——MQTT 的发布是发出去就不管了虽然 QoS 1 能保证送达但你无法直接拿到处理结果。我在实际项目里见过有人用 MQTT 做人员新增结果设备端处理失败比如人脸质量不合格时中心平台完全不知道导致两边数据不一致。后来改成 HTTP API 做管理操作MQTT 只做指令下发问题就解决了。具体来说人脸库管理的典型 HTTP 接口设计如下# 新增人员 POST /api/v1/persons Content-Type: application/json { personId: P20240101001, name: 张三, department: 研发部, faceFeature: base64编码的特征值, validFrom: 2024-01-01T00:00:00Z, validTo: 2025-01-01T00:00:00Z, doorPermissions: [door-001, door-002] } # 响应 HTTP/1.1 201 Created { code: 0, message: success, data: { personId: P20240101001 } }# 分页查询人员 GET /api/v1/persons?page1pageSize100department研发部# 批量同步人脸库到指定设备 POST /api/v1/devices/{deviceId}/sync { fullSync: true, batchSize: 50 }2.2 批量同步时的分页与断点续传设计人脸库全量同步是一个容易出问题的环节。假设有 5000 人每人 5KB 特征值总共 25MB。如果一次性传输网络抖动就会导致整个同步失败而且失败后要从头再来效率极低。我的做法是分页 断点续传。具体设计中心平台提供分页接口每页 50 到 100 条记录设备端记录已同步的页码或最后一条记录的 ID同步中断后设备端从上次的位置继续拉取每页同步完成后设备端向中心平台确认ACK中心平台记录同步进度这个设计的核心思想是把大事务拆成小事务每个小事务独立确认。这样即使中途失败也只需要重传失败的那一页而不是全部重来。在银河麒麟操作系统上部署设备端同步程序时我遇到过一个问题系统的默认文件描述符限制是 1024当并发同步多台设备时HTTP 连接数会超过这个限制导致Too many open files错误。解决办法是修改/etc/security/limits.conf# 在 /etc/security/limits.conf 中添加 * soft nofile 65535 * hard nofile 65535然后重启会话或者执行ulimit -n 65535生效。这个坑在开发环境不容易发现因为开发时通常只连一两台设备但生产环境几十台设备同时同步时就会暴露。2.3 HTTP 轮询做实时指令的延迟实测有些团队为了图省事用 HTTP 轮询来做开门指令下发——设备每隔 1 秒向服务器请求一次有没有新的开门指令。这种做法在设备数量少、开门频率低的时候勉强能用但一旦并发上来问题就很明显。我做过一个实测设备端每 500ms 轮询一次服务器端有 30 台设备同时轮询。结果是平均开门延迟1.2 秒因为轮询间隔是 500ms平均要等半个周期加上网络往返和服务端处理时间服务器 QPS60 次/秒30 台设备 × 每秒 2 次轮询其中 99% 的请求返回无新指令网络带宽浪费每次轮询的请求响应约 500 字节每秒浪费 30KB 带宽这个延迟对于门禁场景来说是不可接受的。用户刷完脸等 1.2 秒才开门体验很差。而且大量的无效轮询浪费了服务器资源和带宽。后来改成 MQTT 之后开门延迟降到了80ms 到 150ms服务器压力也大幅降低。这个对比让我深刻认识到实时指令下发绝对不能用 HTTP 轮询。3. MQTT 在门禁场景中的不可替代性MQTT 的核心价值在于它的发布/订阅模型和长连接机制。这两点决定了它在实时指令下发和事件上报场景中的优势。3.1 发布/订阅模型如何解耦门禁系统的各个模块在传统的 HTTP 架构里中心平台要下发开门指令必须知道每台设备的 IP 地址和端口然后主动发起连接。这意味着中心平台需要维护一个设备地址表而且设备 IP 变化时要及时更新。更麻烦的是如果设备在 NAT 后面很多现场网络都是这样中心平台根本无法主动连接设备。MQTT 的发布/订阅模型解决了这个问题设备启动后主动连接到 MQTT Broker订阅自己的指令主题如door/device-001/command中心平台只需要向这个主题发布消息不需要知道设备的 IP 地址Broker 负责把消息推送给订阅了该主题的设备这种解耦带来的好处是设备可以在任何网络环境下工作只要能连上 Broker 就行。NAT 穿透、动态 IP、防火墙限制这些问题都不存在了。主题设计是 MQTT 落地的关键。我通常采用这样的层级结构{产品线}/{设备类型}/{设备ID}/{消息类型} 示例 door/access/device-001/command # 开门指令 door/access/device-001/event # 通行事件 door/access/device-001/status # 状态心跳 door/access/device-001/config # 配置下发中心平台订阅door/access//event就能收到所有设备的通行事件订阅door/access//status就能监控所有设备的在线状态。这种通配符订阅能力是 HTTP 给不了的。3.2 QoS 等级选择为什么开门指令用 QoS 1 而不是 QoS 2MQTT 有三个 QoS 等级QoS 0最多送达一次可能丢消息QoS 1至少送达一次可能重复QoS 2恰好送达一次不丢不重很多人觉得 QoS 2 最可靠就全部用 QoS 2。但在门禁场景里这是一个误区。开门指令用 QoS 1 就够了。原因是开门指令是幂等的。即使设备收到两次相同的开门指令结果也只是开一次门设备端可以做去重比如 1 秒内相同的指令只执行一次。QoS 2 需要四次握手PUBLISH → PUBREC → PUBREL → PUBCOMP延迟比 QoS 1 高出一倍以上对于要求低延迟的开门场景来说得不偿失。通行记录上报也用 QoS 1。记录重复上报比丢失好——重复的记录可以在服务端去重根据记录 ID但丢失的记录就永远找不回来了。设备状态心跳用 QoS 0 就行。心跳消息丢一两条无所谓下一个周期还会再发。消息类型推荐 QoS理由开门指令QoS 1幂等操作允许重复不允许丢失通行记录QoS 1允许重复服务端去重不允许丢失状态心跳QoS 0周期性发送丢一两条无影响配置下发QoS 1重要配置不能丢重复下发可覆盖3.3 遗嘱消息与设备离线检测的配合MQTT 的遗嘱消息Will Message是一个很实用的机制。设备在连接 Broker 时可以指定一条遗嘱消息当设备异常断线时Broker 会自动发布这条消息。在门禁场景里我通常这样配置import paho.mqtt.client as mqtt import json client mqtt.Client(client_iddevice-001) # 设置遗嘱消息 will_payload json.dumps({ deviceId: device-001, status: offline, timestamp: int(time.time()) }) client.will_set( topicdoor/access/device-001/status, payloadwill_payload, qos1, retainTrue ) client.connect(broker.example.com, 1883, 60) client.loop_forever()中心平台订阅door/access//status后就能实时感知设备上下线。配合retainTrue新订阅的客户端还能立刻拿到设备的最新状态。提示遗嘱消息的延迟取决于 Broker 的 keepalive 配置。如果 keepalive 设为 60 秒设备断线后最长可能要 90 秒1.5 倍 keepalive才会触发遗嘱消息。如果对离线检测的实时性要求高可以把 keepalive 调小比如 15 秒但会增加心跳包的频率。4. 混合架构的落地HTTP 管管理MQTT 管实时搞清楚两种协议各自的定位之后混合架构的设计就顺理成章了。核心原则是HTTP 负责管理面MQTT 负责数据面。4.1 中心平台的接口分层设计中心平台需要同时提供 HTTP API 和 MQTT 接入能力。我的做法是把平台分成两层管理层HTTP API人员管理增删改查、批量导入导出设备管理注册、配置、固件升级权限管理门禁权限分配、时间段配置报表查询通行记录查询、统计报表人脸库同步分页拉取、断点续传实时层MQTT开门指令下发通行记录实时上报设备状态心跳实时告警推送两层之间通过内部消息队列比如 Redis Pub/Sub 或者 RabbitMQ解耦。HTTP API 写入的数据变更通过消息队列通知 MQTT 层MQTT 层再推送给相关设备。4.2 设备端的双通道连接管理设备端需要同时维护 HTTP 客户端和 MQTT 客户端。这里有几个实操要点连接建立顺序先建立 MQTT 连接再初始化 HTTP 客户端。因为 MQTT 连接成功后设备才能接收指令而 HTTP 主要用于同步人脸库可以稍后执行。断线重连策略MQTT 客户端要配置自动重连重连间隔采用指数退避1s、2s、4s、8s...最大 60s。HTTP 客户端不需要长连接每次请求独立建立连接即可。资源占用在资源受限的设备上比如 512MB 内存的 OpenHarmony 终端MQTT 长连接会占用约 2MB 到 5MB 内存HTTP 客户端占用较少。如果内存紧张可以适当调大 MQTT 的 keepalive减少心跳频率。# 设备端双通道初始化示例 import paho.mqtt.client as mqtt import requests import time import threading class DeviceClient: def __init__(self, device_id, broker_host, api_base): self.device_id device_id self.api_base api_base self.mqtt_client mqtt.Client(client_iddevice_id) self.mqtt_client.on_connect self._on_connect self.mqtt_client.on_message self._on_message self.mqtt_client.on_disconnect self._on_disconnect self.broker_host broker_host self.reconnect_delay 1 def _on_connect(self, client, userdata, flags, rc): if rc 0: self.reconnect_delay 1 client.subscribe(fdoor/access/{self.device_id}/command, qos1) client.subscribe(fdoor/access/{self.device_id}/config, qos1) print(MQTT connected) else: print(fMQTT connect failed with code {rc}) def _on_disconnect(self, client, userdata, rc): print(fMQTT disconnected, will reconnect in {self.reconnect_delay}s) time.sleep(self.reconnect_delay) self.reconnect_delay min(self.reconnect_delay * 2, 60) self._connect_mqtt() def _connect_mqtt(self): try: self.mqtt_client.connect(self.broker_host, 1883, 30) self.mqtt_client.loop_start() except Exception as e: print(fMQTT connect error: {e}) time.sleep(self.reconnect_delay) self.reconnect_delay min(self.reconnect_delay * 2, 60) self._connect_mqtt() def _on_message(self, client, userdata, msg): topic msg.topic payload msg.payload.decode(utf-8) if topic.endswith(/command): self._handle_command(payload) elif topic.endswith(/config): self._handle_config(payload) def _handle_command(self, payload): # 处理开门指令 print(fReceived command: {payload}) # 执行开门动作... def _handle_config(self, payload): # 处理配置更新 print(fReceived config: {payload}) def sync_face_library(self): # 通过 HTTP API 分页同步人脸库 page 1 while True: resp requests.get( f{self.api_base}/api/v1/persons, params{page: page, pageSize: 50}, timeout30 ) if resp.status_code ! 200: print(fSync failed at page {page}) break data resp.json() persons data.get(data, {}).get(list, []) if not persons: break # 保存到本地数据库... print(fSynced page {page}, {len(persons)} persons) page 1 def start(self): self._connect_mqtt() # 在后台线程同步人脸库 threading.Thread(targetself.sync_face_library, daemonTrue).start()4.3 在银河麒麟上部署 MQTT 客户端的依赖处理银河麒麟 V10 是基于 Linux 内核的国产操作系统软件源和常见的 Ubuntu/CentOS 有些差异。在上面部署 MQTT 客户端时我遇到过几个典型问题问题一Python paho-mqtt 库安装失败。银河麒麟自带的 Python 版本可能是 3.7 或 3.8pip 源默认指向的仓库可能没有最新版的 paho-mqtt。解决办法是换用国内镜像源pip3 install paho-mqtt -i https://pypi.tuna.tsinghua.edu.cn/simple问题二SSL/TLS 证书验证失败。如果 MQTT Broker 启用了 TLS银河麒麟的 CA 证书库可能不完整。需要安装ca-certificates包sudo apt install ca-certificates sudo update-ca-certificates问题三系统时间不同步导致 TLS 握手失败。银河麒麟默认可能没有开启 NTP 时间同步如果系统时间偏差超过证书的有效期范围TLS 握手就会失败。需要配置 NTPsudo apt install ntpdate sudo ntpdate ntp.aliyun.com # 或者启用 systemd-timesyncd sudo timedatectl set-ntp true问题四防火墙拦截 MQTT 端口。银河麒麟默认的防火墙规则可能拦截 1883 或 8883 端口。需要放行sudo firewall-cmd --add-port1883/tcp --permanent sudo firewall-cmd --add-port8883/tcp --permanent sudo firewall-cmd --reload这些坑在开发环境通常是 Ubuntu 或 CentOS不会遇到但到了国产化环境就会暴露。建议在项目早期就在目标环境上做验证不要等到部署阶段才发现。5. 那些让我熬夜的踩坑记录5.1 MQTT Broker 内存被打满的排查过程有一次园区项目上线后运行了大约两周MQTT Broker 突然崩溃。重启后运行几个小时又崩溃。查看监控发现 Broker 的内存占用持续增长从初始的 200MB 涨到 4GB 然后 OOM。排查过程第一步确认是 Broker 问题还是客户端问题。查看 Broker 日志发现有大量客户端连接和断开的记录。用netstat查看连接数发现有几千个 ESTABLISHED 连接但实际设备只有 50 台。第二步定位异常连接来源。通过 Broker 的管理接口查看客户端列表发现大量 clientId 类似的连接格式是device-001、device-001-1、device-001-2... 这说明设备端在断线重连时没有复用原来的 clientId而是每次生成新的。第三步分析代码。查看设备端代码发现重连逻辑里每次调用mqtt.Client(client_idf{device_id}-{int(time.time())})导致每次重连都创建一个新的 clientId。旧连接因为 keepalive 还没超时Broker 认为它们还在线就保留着会话状态。时间一长会话堆积内存就爆了。修复方案clientId 必须固定不能带时间戳。同时设置clean_sessionTrue让 Broker 在连接断开后清理会话。如果业务需要保留会话比如 QoS 1 消息在设备离线期间要保留则设置clean_sessionFalse但要确保 clientId 固定。# 错误做法 client mqtt.Client(client_idfdevice-001-{int(time.time())}) # 正确做法 client mqtt.Client(client_iddevice-001, clean_sessionTrue)这个坑的教训是MQTT 的 clientId 是设备的唯一标识必须稳定。任何带随机数或时间戳的 clientId 都会导致会话泄漏。5.2 人脸特征值通过 MQTT 传输导致的包大小超限另一个项目里团队为了省事把人脸特征值的同步也走了 MQTT。结果发现部分设备同步失败Broker 日志显示packet too large。原因是 MQTT 协议默认的最大报文大小是 256MB理论上但实际 Broker 通常配置了更小的限制。Mosquitto 默认的message_size_limit是 0不限制但很多云服务商的 MQTT 服务会限制到 128KB 或 256KB。一条人脸记录如果包含高清照片的 base64 编码很容易超过这个限制。即使 Broker 不限制大包通过 MQTT 传输也不是好做法。因为 MQTT 是基于 TCP 的长连接大包会阻塞同一连接上的其他消息导致开门指令的延迟增加。正确的做法人脸特征值走 HTTP API 同步MQTT 只传指令和事件。如果确实需要通过 MQTT 传大文件可以先把文件上传到对象存储如 MinIO然后通过 MQTT 发送文件 URL设备端收到 URL 后再通过 HTTP 下载。5.3 设备时间不同步导致的消息乱序门禁系统里通行记录的时间戳非常重要。如果设备时间不准记录的时间就会错乱影响后续的考勤统计和轨迹分析。我遇到过一个案例部分设备的时间比标准时间慢了 3 分钟导致这些设备的通行记录在时间轴上滞后。当中心平台按时间排序展示记录时这些记录会出现在错误的位置。排查发现这些设备没有配置 NTP 同步而且设备长时间运行后晶振漂移导致时间偏差累积。解决办法是在设备端启动时强制同步一次 NTP并且每隔 24 小时再同步一次。# 在设备启动脚本中添加 ntpdate -s ntp.aliyun.com # 添加到 crontab 每天同步一次 echo 0 3 * * * /usr/sbin/ntpdate -s ntp.aliyun.com | crontab -另外MQTT 消息里最好带上设备端的本地时间戳和服务端的接收时间戳两者都记录下来。如果发现偏差超过阈值比如 10 秒中心平台可以下发时间校正指令。5.4 OpenHarmony 设备上 MQTT 库的兼容性问题OpenHarmony 的生态还在完善中MQTT 客户端库的选择不如 Linux 丰富。我试过几个方案paho-mqttPythonOpenHarmony 的标准系统支持 Python但需要确认 Python 版本和 paho-mqtt 的兼容性。实测在 OpenHarmony 3.2 上paho-mqtt 1.6.1 可以正常工作。Eclipse Paho C如果设备端用 C/C 开发可以用 Paho C 库。需要交叉编译配置稍复杂。自研 MQTT 客户端如果设备资源极度受限可以考虑实现 MQTT 3.1.1 的最小功能集CONNECT、PUBLISH、SUBSCRIBE、PINGREQ代码量大约 2000 行。在 OpenHarmony 上使用 paho-mqtt 时需要注意网络权限的配置。OpenHarmony 的应用需要在config.json中声明网络权限{ module: { reqPermissions: [ { name: ohos.permission.INTERNET } ] } }如果没有声明这个权限MQTT 连接会直接失败而且错误信息不明显容易误判为网络问题。6. 选型决策树与规模适配建议6.1 按设备数量选择架构不同规模的场景架构选择差异很大1 到 5 台设备小型办公全部用 HTTP API 就够了。设备数量少轮询的开销可以接受。如果对开门延迟有要求可以用 HTTP 长轮询Long Polling来降低延迟。5 到 50 台设备中型园区建议 HTTP MQTT 混合。HTTP 做管理MQTT 做实时。这个规模下 MQTT Broker 用单机 Mosquitto 或 EMQX 就能支撑。50 台以上设备大型园区或多个园区必须用 MQTT 集群。EMQX 或 HiveMQ 的集群方案可以支撑十万级连接。HTTP API 层需要做负载均衡。6.2 按网络环境选择架构设备与服务器在同一局域网HTTP 和 MQTT 都可以。如果网络稳定HTTP 轮询的延迟也可以接受。设备分布在多个网络跨公网必须用 MQTT。因为设备通常在 NAT 后面服务器无法主动连接设备只能靠 MQTT 的长连接实现双向通信。网络不稳定无线网络、4GMQTT 的自动重连和 QoS 机制更适合。HTTP 每次请求都要重新建立连接在网络抖动时体验很差。6.3 国产化环境下的额外考量在银河麒麟、OpenHarmony 等国产化环境下除了协议选择还需要考虑软件源可用性银河麒麟的软件源可能没有最新版的 MQTT Broker 或客户端库需要提前确认或自行编译。硬件兼容性某些国产化硬件平台如飞腾、鲲鹏的 ARM 架构可能需要专门编译的二进制包。安全合规国产化项目通常有安全合规要求MQTT 通信需要启用 TLSHTTP API 需要启用 HTTPS并且使用国密算法如 SM2、SM4替换国际算法。# 在银河麒麟上安装 EMQXARM64 版本 wget https://www.emqx.com/zh/downloads/broker/5.4.0/emqx-5.4.0-ubuntu22.04-arm64.deb sudo dpkg -i emqx-5.4.0-ubuntu22.04-arm64.deb sudo systemctl start emqx sudo systemctl enable emqx注意下载 EMQX 时一定要确认操作系统版本和 CPU 架构。银河麒麟 V10 SP1 基于 Ubuntu 22.04 的兼容性较好但如果是基于 CentOS 的版本需要下载对应的 RPM 包。7. 一些容易被忽略的细节7.1 MQTT 主题的权限控制在多租户或多项目场景下MQTT 主题的权限控制很重要。如果不做限制A 项目的设备可能订阅到 B 项目的主题造成数据泄漏。EMQX 支持基于 ACLAccess Control List的主题权限控制。可以配置每个客户端只能发布和订阅特定前缀的主题# EMQX ACL 配置示例 # 允许 device-001 订阅 door/access/device-001/# {allow, {clientid, device-001}, subscribe, [door/access/device-001/#]}. # 允许 device-001 发布到自己的事件主题 {allow, {clientid, device-001}, publish, [door/access/device-001/event, door/access/device-001/status]}. # 拒绝其他所有 {deny, all}.7.2 HTTP API 的幂等性设计人脸库同步接口需要支持幂等。也就是说同一个请求执行多次结果应该是一样的。这对于断点续传和失败重试很重要。实现幂等的方式有几种使用唯一业务 ID新增人员时如果 personId 已存在返回 200 而不是 409表示已存在无需重复创建。使用幂等键客户端每次请求带一个唯一的 requestId服务端记录已处理的 requestId重复的 requestId 直接返回上次的结果。使用版本号每次更新带一个版本号服务端只接受版本号比当前大的更新。7.3 消息去重与顺序保证MQTT 的 QoS 1 会导致消息重复设备端需要做去重。我的做法是在消息体里带一个唯一的 messageId可以用 UUID设备端维护一个最近处理过的 messageId 集合比如最近 1000 条收到重复的 messageId 就丢弃。顺序保证方面MQTT 不保证跨主题的消息顺序但同一主题、同一 QoS 级别的消息通常是有序的。如果业务对顺序敏感比如配置更新必须先于指令下发可以在消息体里带序列号设备端按序列号排序处理。7.4 日志与监控门禁系统的日志非常重要出问题时需要快速定位。我通常会在以下几个位置打日志设备端MQTT 连接状态、指令接收、开门执行结果、HTTP 同步进度Broker 端客户端连接/断开、消息发布/订阅、异常断开中心平台API 请求日志、消息处理日志、异常告警监控指标方面重点关注MQTT 连接数突增可能意味着设备重连风暴消息延迟P99 延迟超过 1 秒需要告警消息丢失率QoS 1 消息的丢失率应该接近 0HTTP API 的响应时间和错误率8. 最后说几句实操心得人脸门禁系统的通信架构设计核心就一句话让合适的协议做合适的事。HTTP API 适合管理面的增删改查和批量同步MQTT 适合数据面的实时指令和事件上报。两者不是二选一的关系而是互补的关系。我在实际项目中总结的几个原则第一不要用 HTTP 轮询做实时指令。延迟高、资源浪费大设备一多就撑不住。这是我最深刻的教训。第二不要用 MQTT 传大文件。人脸特征值、照片、固件包这些大文件走 HTTP 或对象存储MQTT 只传指令和元数据。第三clientId 必须稳定。这是 MQTT 会话管理的基础带随机数的 clientId 会导致会话泄漏和 Broker 内存暴涨。第四在目标环境上尽早验证。银河麒麟、OpenHarmony 这些国产化环境的软件生态和常见 Linux 发行版有差异很多在 Ubuntu 上跑得好好的东西到了麒麟上就出问题。提前验证比事后排查省事得多。第五日志和监控不能省。门禁系统出问题时用户就在门口等着排查时间窗口很短。完善的日志和监控能让你在几分钟内定位问题而不是花几个小时翻代码。这些经验都是一个个坑踩出来的希望能帮到正在做类似项目的朋友。如果你在国产化环境上遇到 MQTT 或 HTTP 相关的兼容性问题欢迎交流。 
长河君 · 2026/10/3 6:54:16 · 阅读 1.2k 人脸门禁通信架构选型：HTTP API与MQTT混合方案实战
人脸门禁这个场景看起来简单——刷脸、开门、记录三件事。但真正落到项目里尤其是涉及国产化环境比如银河麒麟操作系统、OpenHarmony终端设备的时候通信链路怎么设计就成了一个绕不开的架构决策。我做过几个不同规模的门禁项目有单机离线的小型办公场景也有几十台设备联网的园区场景每次都会遇到同一个问题HTTP API 和 MQTT 到底该用哪个还是两个都用这个问题没有标准答案但有一套清晰的判断逻辑。我踩过的坑包括用 HTTP 轮询做实时开门指令导致延迟高到用户以为设备坏了、用 MQTT 传大尺寸人脸特征值把 broker 内存打满、在银河麒麟上跑 MQTT 客户端时遇到依赖库版本冲突等等。这篇文章就把这些经验完整梳理一遍从协议特性、场景匹配、实操配置到踩坑排查尽量把每个决策背后的为什么讲清楚。1. 先搞清楚门禁系统里数据到底分几类很多人一上来就纠结选 HTTP 还是 MQTT但这个问题本身就问错了。正确的问法是我的系统里有哪几种数据流每种数据流的特征是什么因为在一个完整的人脸门禁系统里数据流至少可以分成四类每类的通信需求完全不同。1.1 人脸特征值的下发与同步这是数据量最大的一类。一张人脸的特征值通常是 512 维或 1024 维的浮点向量也有量化成 int8 的版本大小在 1KB 到 4KB 之间加上人员信息、权限配置、有效期等元数据单条记录可能到 5KB 到 10KB。一个中型园区如果有 2000 人全量同步一次就是 10MB 到 20MB 的数据量。这类数据的特点是低频、大批量、要求可靠性高。你不需要每秒钟都同步人脸库但每次同步必须完整、准确不能丢包。这种特征天然适合 HTTP API——请求-响应模式有明确的成功/失败状态码支持分页拉取断点续传也好做。1.2 开门指令的下发这是实时性要求最高的一类。用户在门口站定人脸识别通过后系统需要在几百毫秒内把开门指令送到门锁控制器。如果超过 1 秒用户就会觉得怎么还没开体验直线下降。这类数据的特点是高频、小包、要求低延迟。每条指令可能只有几十个字节设备 ID 指令类型 时间戳但延迟必须控制在 500ms 以内。这种特征适合 MQTT——长连接、发布/订阅模式、消息直达不需要每次建立连接。1.3 通行记录的实时上报每次开门都会产生一条通行记录谁、什么时候、哪个门、识别方式、温度如果有测温模块等。这些记录需要实时上报到中心平台用于实时监控和后续统计分析。这类数据的特点是高频、小包、允许偶尔丢包但要求最终一致。MQTT 的 QoS 1 级别至少送达一次就很适合既保证了可靠性又不会像 QoS 2 那样带来额外的握手开销。1.4 设备状态与心跳设备的在线状态、CPU 温度、内存占用、网络质量、固件版本等信息需要定期上报。这类数据的特点是周期性、极小包、允许丢失。MQTT 的遗嘱消息Last Will and Testament机制天然适合做设备离线检测——设备断线时 broker 自动发布离线消息中心平台立刻知道。把这四类数据梳理清楚之后架构决策就清晰了数据类别数据量频率延迟要求推荐协议理由人脸特征值同步大KB~MB低秒级HTTP API请求-响应模式可靠性高支持分页开门指令下发小100B高500msMQTT长连接消息直达延迟低通行记录上报小1KB高秒级MQTTQoS 1 保证可靠异步不阻塞设备状态心跳极小100B周期分钟级MQTT遗嘱消息天然支持离线检测注意这个划分不是绝对的。如果你的系统只有几台设备全部用 HTTP 也能跑只是实时性会差一些。但如果设备数量超过 20 台或者对开门延迟有明确要求就建议按上面的方式拆分。2. HTTP API 在人脸门禁里的真实定位HTTP API 在门禁系统里扮演的角色更像是管理系统而不是控制系统。它负责的是那些对实时性不敏感、但对数据完整性要求高的操作。2.1 人脸库的增删改查为什么必须走 HTTP人脸库的管理操作包括新增人员、删除人员、修改权限、查询人员信息、批量导入导出。这些操作的共同特征是需要明确的成功/失败反馈且操作结果需要持久化。HTTP 的请求-响应模式天然适合这种场景。你发一个 POST 请求新增人员服务器返回 201 Created 就表示成功返回 409 Conflict 就表示人员已存在返回 400 Bad Request 就表示参数有问题。这种明确的语义是 MQTT 给不了的——MQTT 的发布是发出去就不管了虽然 QoS 1 能保证送达但你无法直接拿到处理结果。我在实际项目里见过有人用 MQTT 做人员新增结果设备端处理失败比如人脸质量不合格时中心平台完全不知道导致两边数据不一致。后来改成 HTTP API 做管理操作MQTT 只做指令下发问题就解决了。具体来说人脸库管理的典型 HTTP 接口设计如下# 新增人员 POST /api/v1/persons Content-Type: application/json { personId: P20240101001, name: 张三, department: 研发部, faceFeature: base64编码的特征值, validFrom: 2024-01-01T00:00:00Z, validTo: 2025-01-01T00:00:00Z, doorPermissions: [door-001, door-002] } # 响应 HTTP/1.1 201 Created { code: 0, message: success, data: { personId: P20240101001 } }# 分页查询人员 GET /api/v1/persons?page1pageSize100department研发部# 批量同步人脸库到指定设备 POST /api/v1/devices/{deviceId}/sync { fullSync: true, batchSize: 50 }2.2 批量同步时的分页与断点续传设计人脸库全量同步是一个容易出问题的环节。假设有 5000 人每人 5KB 特征值总共 25MB。如果一次性传输网络抖动就会导致整个同步失败而且失败后要从头再来效率极低。我的做法是分页 断点续传。具体设计中心平台提供分页接口每页 50 到 100 条记录设备端记录已同步的页码或最后一条记录的 ID同步中断后设备端从上次的位置继续拉取每页同步完成后设备端向中心平台确认ACK中心平台记录同步进度这个设计的核心思想是把大事务拆成小事务每个小事务独立确认。这样即使中途失败也只需要重传失败的那一页而不是全部重来。在银河麒麟操作系统上部署设备端同步程序时我遇到过一个问题系统的默认文件描述符限制是 1024当并发同步多台设备时HTTP 连接数会超过这个限制导致Too many open files错误。解决办法是修改/etc/security/limits.conf# 在 /etc/security/limits.conf 中添加 * soft nofile 65535 * hard nofile 65535然后重启会话或者执行ulimit -n 65535生效。这个坑在开发环境不容易发现因为开发时通常只连一两台设备但生产环境几十台设备同时同步时就会暴露。2.3 HTTP 轮询做实时指令的延迟实测有些团队为了图省事用 HTTP 轮询来做开门指令下发——设备每隔 1 秒向服务器请求一次有没有新的开门指令。这种做法在设备数量少、开门频率低的时候勉强能用但一旦并发上来问题就很明显。我做过一个实测设备端每 500ms 轮询一次服务器端有 30 台设备同时轮询。结果是平均开门延迟1.2 秒因为轮询间隔是 500ms平均要等半个周期加上网络往返和服务端处理时间服务器 QPS60 次/秒30 台设备 × 每秒 2 次轮询其中 99% 的请求返回无新指令网络带宽浪费每次轮询的请求响应约 500 字节每秒浪费 30KB 带宽这个延迟对于门禁场景来说是不可接受的。用户刷完脸等 1.2 秒才开门体验很差。而且大量的无效轮询浪费了服务器资源和带宽。后来改成 MQTT 之后开门延迟降到了80ms 到 150ms服务器压力也大幅降低。这个对比让我深刻认识到实时指令下发绝对不能用 HTTP 轮询。3. MQTT 在门禁场景中的不可替代性MQTT 的核心价值在于它的发布/订阅模型和长连接机制。这两点决定了它在实时指令下发和事件上报场景中的优势。3.1 发布/订阅模型如何解耦门禁系统的各个模块在传统的 HTTP 架构里中心平台要下发开门指令必须知道每台设备的 IP 地址和端口然后主动发起连接。这意味着中心平台需要维护一个设备地址表而且设备 IP 变化时要及时更新。更麻烦的是如果设备在 NAT 后面很多现场网络都是这样中心平台根本无法主动连接设备。MQTT 的发布/订阅模型解决了这个问题设备启动后主动连接到 MQTT Broker订阅自己的指令主题如door/device-001/command中心平台只需要向这个主题发布消息不需要知道设备的 IP 地址Broker 负责把消息推送给订阅了该主题的设备这种解耦带来的好处是设备可以在任何网络环境下工作只要能连上 Broker 就行。NAT 穿透、动态 IP、防火墙限制这些问题都不存在了。主题设计是 MQTT 落地的关键。我通常采用这样的层级结构{产品线}/{设备类型}/{设备ID}/{消息类型} 示例 door/access/device-001/command # 开门指令 door/access/device-001/event # 通行事件 door/access/device-001/status # 状态心跳 door/access/device-001/config # 配置下发中心平台订阅door/access//event就能收到所有设备的通行事件订阅door/access//status就能监控所有设备的在线状态。这种通配符订阅能力是 HTTP 给不了的。3.2 QoS 等级选择为什么开门指令用 QoS 1 而不是 QoS 2MQTT 有三个 QoS 等级QoS 0最多送达一次可能丢消息QoS 1至少送达一次可能重复QoS 2恰好送达一次不丢不重很多人觉得 QoS 2 最可靠就全部用 QoS 2。但在门禁场景里这是一个误区。开门指令用 QoS 1 就够了。原因是开门指令是幂等的。即使设备收到两次相同的开门指令结果也只是开一次门设备端可以做去重比如 1 秒内相同的指令只执行一次。QoS 2 需要四次握手PUBLISH → PUBREC → PUBREL → PUBCOMP延迟比 QoS 1 高出一倍以上对于要求低延迟的开门场景来说得不偿失。通行记录上报也用 QoS 1。记录重复上报比丢失好——重复的记录可以在服务端去重根据记录 ID但丢失的记录就永远找不回来了。设备状态心跳用 QoS 0 就行。心跳消息丢一两条无所谓下一个周期还会再发。消息类型推荐 QoS理由开门指令QoS 1幂等操作允许重复不允许丢失通行记录QoS 1允许重复服务端去重不允许丢失状态心跳QoS 0周期性发送丢一两条无影响配置下发QoS 1重要配置不能丢重复下发可覆盖3.3 遗嘱消息与设备离线检测的配合MQTT 的遗嘱消息Will Message是一个很实用的机制。设备在连接 Broker 时可以指定一条遗嘱消息当设备异常断线时Broker 会自动发布这条消息。在门禁场景里我通常这样配置import paho.mqtt.client as mqtt import json client mqtt.Client(client_iddevice-001) # 设置遗嘱消息 will_payload json.dumps({ deviceId: device-001, status: offline, timestamp: int(time.time()) }) client.will_set( topicdoor/access/device-001/status, payloadwill_payload, qos1, retainTrue ) client.connect(broker.example.com, 1883, 60) client.loop_forever()中心平台订阅door/access//status后就能实时感知设备上下线。配合retainTrue新订阅的客户端还能立刻拿到设备的最新状态。提示遗嘱消息的延迟取决于 Broker 的 keepalive 配置。如果 keepalive 设为 60 秒设备断线后最长可能要 90 秒1.5 倍 keepalive才会触发遗嘱消息。如果对离线检测的实时性要求高可以把 keepalive 调小比如 15 秒但会增加心跳包的频率。4. 混合架构的落地HTTP 管管理MQTT 管实时搞清楚两种协议各自的定位之后混合架构的设计就顺理成章了。核心原则是HTTP 负责管理面MQTT 负责数据面。4.1 中心平台的接口分层设计中心平台需要同时提供 HTTP API 和 MQTT 接入能力。我的做法是把平台分成两层管理层HTTP API人员管理增删改查、批量导入导出设备管理注册、配置、固件升级权限管理门禁权限分配、时间段配置报表查询通行记录查询、统计报表人脸库同步分页拉取、断点续传实时层MQTT开门指令下发通行记录实时上报设备状态心跳实时告警推送两层之间通过内部消息队列比如 Redis Pub/Sub 或者 RabbitMQ解耦。HTTP API 写入的数据变更通过消息队列通知 MQTT 层MQTT 层再推送给相关设备。4.2 设备端的双通道连接管理设备端需要同时维护 HTTP 客户端和 MQTT 客户端。这里有几个实操要点连接建立顺序先建立 MQTT 连接再初始化 HTTP 客户端。因为 MQTT 连接成功后设备才能接收指令而 HTTP 主要用于同步人脸库可以稍后执行。断线重连策略MQTT 客户端要配置自动重连重连间隔采用指数退避1s、2s、4s、8s...最大 60s。HTTP 客户端不需要长连接每次请求独立建立连接即可。资源占用在资源受限的设备上比如 512MB 内存的 OpenHarmony 终端MQTT 长连接会占用约 2MB 到 5MB 内存HTTP 客户端占用较少。如果内存紧张可以适当调大 MQTT 的 keepalive减少心跳频率。# 设备端双通道初始化示例 import paho.mqtt.client as mqtt import requests import time import threading class DeviceClient: def __init__(self, device_id, broker_host, api_base): self.device_id device_id self.api_base api_base self.mqtt_client mqtt.Client(client_iddevice_id) self.mqtt_client.on_connect self._on_connect self.mqtt_client.on_message self._on_message self.mqtt_client.on_disconnect self._on_disconnect self.broker_host broker_host self.reconnect_delay 1 def _on_connect(self, client, userdata, flags, rc): if rc 0: self.reconnect_delay 1 client.subscribe(fdoor/access/{self.device_id}/command, qos1) client.subscribe(fdoor/access/{self.device_id}/config, qos1) print(MQTT connected) else: print(fMQTT connect failed with code {rc}) def _on_disconnect(self, client, userdata, rc): print(fMQTT disconnected, will reconnect in {self.reconnect_delay}s) time.sleep(self.reconnect_delay) self.reconnect_delay min(self.reconnect_delay * 2, 60) self._connect_mqtt() def _connect_mqtt(self): try: self.mqtt_client.connect(self.broker_host, 1883, 30) self.mqtt_client.loop_start() except Exception as e: print(fMQTT connect error: {e}) time.sleep(self.reconnect_delay) self.reconnect_delay min(self.reconnect_delay * 2, 60) self._connect_mqtt() def _on_message(self, client, userdata, msg): topic msg.topic payload msg.payload.decode(utf-8) if topic.endswith(/command): self._handle_command(payload) elif topic.endswith(/config): self._handle_config(payload) def _handle_command(self, payload): # 处理开门指令 print(fReceived command: {payload}) # 执行开门动作... def _handle_config(self, payload): # 处理配置更新 print(fReceived config: {payload}) def sync_face_library(self): # 通过 HTTP API 分页同步人脸库 page 1 while True: resp requests.get( f{self.api_base}/api/v1/persons, params{page: page, pageSize: 50}, timeout30 ) if resp.status_code ! 200: print(fSync failed at page {page}) break data resp.json() persons data.get(data, {}).get(list, []) if not persons: break # 保存到本地数据库... print(fSynced page {page}, {len(persons)} persons) page 1 def start(self): self._connect_mqtt() # 在后台线程同步人脸库 threading.Thread(targetself.sync_face_library, daemonTrue).start()4.3 在银河麒麟上部署 MQTT 客户端的依赖处理银河麒麟 V10 是基于 Linux 内核的国产操作系统软件源和常见的 Ubuntu/CentOS 有些差异。在上面部署 MQTT 客户端时我遇到过几个典型问题问题一Python paho-mqtt 库安装失败。银河麒麟自带的 Python 版本可能是 3.7 或 3.8pip 源默认指向的仓库可能没有最新版的 paho-mqtt。解决办法是换用国内镜像源pip3 install paho-mqtt -i https://pypi.tuna.tsinghua.edu.cn/simple问题二SSL/TLS 证书验证失败。如果 MQTT Broker 启用了 TLS银河麒麟的 CA 证书库可能不完整。需要安装ca-certificates包sudo apt install ca-certificates sudo update-ca-certificates问题三系统时间不同步导致 TLS 握手失败。银河麒麟默认可能没有开启 NTP 时间同步如果系统时间偏差超过证书的有效期范围TLS 握手就会失败。需要配置 NTPsudo apt install ntpdate sudo ntpdate ntp.aliyun.com # 或者启用 systemd-timesyncd sudo timedatectl set-ntp true问题四防火墙拦截 MQTT 端口。银河麒麟默认的防火墙规则可能拦截 1883 或 8883 端口。需要放行sudo firewall-cmd --add-port1883/tcp --permanent sudo firewall-cmd --add-port8883/tcp --permanent sudo firewall-cmd --reload这些坑在开发环境通常是 Ubuntu 或 CentOS不会遇到但到了国产化环境就会暴露。建议在项目早期就在目标环境上做验证不要等到部署阶段才发现。5. 那些让我熬夜的踩坑记录5.1 MQTT Broker 内存被打满的排查过程有一次园区项目上线后运行了大约两周MQTT Broker 突然崩溃。重启后运行几个小时又崩溃。查看监控发现 Broker 的内存占用持续增长从初始的 200MB 涨到 4GB 然后 OOM。排查过程第一步确认是 Broker 问题还是客户端问题。查看 Broker 日志发现有大量客户端连接和断开的记录。用netstat查看连接数发现有几千个 ESTABLISHED 连接但实际设备只有 50 台。第二步定位异常连接来源。通过 Broker 的管理接口查看客户端列表发现大量 clientId 类似的连接格式是device-001、device-001-1、device-001-2... 这说明设备端在断线重连时没有复用原来的 clientId而是每次生成新的。第三步分析代码。查看设备端代码发现重连逻辑里每次调用mqtt.Client(client_idf{device_id}-{int(time.time())})导致每次重连都创建一个新的 clientId。旧连接因为 keepalive 还没超时Broker 认为它们还在线就保留着会话状态。时间一长会话堆积内存就爆了。修复方案clientId 必须固定不能带时间戳。同时设置clean_sessionTrue让 Broker 在连接断开后清理会话。如果业务需要保留会话比如 QoS 1 消息在设备离线期间要保留则设置clean_sessionFalse但要确保 clientId 固定。# 错误做法 client mqtt.Client(client_idfdevice-001-{int(time.time())}) # 正确做法 client mqtt.Client(client_iddevice-001, clean_sessionTrue)这个坑的教训是MQTT 的 clientId 是设备的唯一标识必须稳定。任何带随机数或时间戳的 clientId 都会导致会话泄漏。5.2 人脸特征值通过 MQTT 传输导致的包大小超限另一个项目里团队为了省事把人脸特征值的同步也走了 MQTT。结果发现部分设备同步失败Broker 日志显示packet too large。原因是 MQTT 协议默认的最大报文大小是 256MB理论上但实际 Broker 通常配置了更小的限制。Mosquitto 默认的message_size_limit是 0不限制但很多云服务商的 MQTT 服务会限制到 128KB 或 256KB。一条人脸记录如果包含高清照片的 base64 编码很容易超过这个限制。即使 Broker 不限制大包通过 MQTT 传输也不是好做法。因为 MQTT 是基于 TCP 的长连接大包会阻塞同一连接上的其他消息导致开门指令的延迟增加。正确的做法人脸特征值走 HTTP API 同步MQTT 只传指令和事件。如果确实需要通过 MQTT 传大文件可以先把文件上传到对象存储如 MinIO然后通过 MQTT 发送文件 URL设备端收到 URL 后再通过 HTTP 下载。5.3 设备时间不同步导致的消息乱序门禁系统里通行记录的时间戳非常重要。如果设备时间不准记录的时间就会错乱影响后续的考勤统计和轨迹分析。我遇到过一个案例部分设备的时间比标准时间慢了 3 分钟导致这些设备的通行记录在时间轴上滞后。当中心平台按时间排序展示记录时这些记录会出现在错误的位置。排查发现这些设备没有配置 NTP 同步而且设备长时间运行后晶振漂移导致时间偏差累积。解决办法是在设备端启动时强制同步一次 NTP并且每隔 24 小时再同步一次。# 在设备启动脚本中添加 ntpdate -s ntp.aliyun.com # 添加到 crontab 每天同步一次 echo 0 3 * * * /usr/sbin/ntpdate -s ntp.aliyun.com | crontab -另外MQTT 消息里最好带上设备端的本地时间戳和服务端的接收时间戳两者都记录下来。如果发现偏差超过阈值比如 10 秒中心平台可以下发时间校正指令。5.4 OpenHarmony 设备上 MQTT 库的兼容性问题OpenHarmony 的生态还在完善中MQTT 客户端库的选择不如 Linux 丰富。我试过几个方案paho-mqttPythonOpenHarmony 的标准系统支持 Python但需要确认 Python 版本和 paho-mqtt 的兼容性。实测在 OpenHarmony 3.2 上paho-mqtt 1.6.1 可以正常工作。Eclipse Paho C如果设备端用 C/C 开发可以用 Paho C 库。需要交叉编译配置稍复杂。自研 MQTT 客户端如果设备资源极度受限可以考虑实现 MQTT 3.1.1 的最小功能集CONNECT、PUBLISH、SUBSCRIBE、PINGREQ代码量大约 2000 行。在 OpenHarmony 上使用 paho-mqtt 时需要注意网络权限的配置。OpenHarmony 的应用需要在config.json中声明网络权限{ module: { reqPermissions: [ { name: ohos.permission.INTERNET } ] } }如果没有声明这个权限MQTT 连接会直接失败而且错误信息不明显容易误判为网络问题。6. 选型决策树与规模适配建议6.1 按设备数量选择架构不同规模的场景架构选择差异很大1 到 5 台设备小型办公全部用 HTTP API 就够了。设备数量少轮询的开销可以接受。如果对开门延迟有要求可以用 HTTP 长轮询Long Polling来降低延迟。5 到 50 台设备中型园区建议 HTTP MQTT 混合。HTTP 做管理MQTT 做实时。这个规模下 MQTT Broker 用单机 Mosquitto 或 EMQX 就能支撑。50 台以上设备大型园区或多个园区必须用 MQTT 集群。EMQX 或 HiveMQ 的集群方案可以支撑十万级连接。HTTP API 层需要做负载均衡。6.2 按网络环境选择架构设备与服务器在同一局域网HTTP 和 MQTT 都可以。如果网络稳定HTTP 轮询的延迟也可以接受。设备分布在多个网络跨公网必须用 MQTT。因为设备通常在 NAT 后面服务器无法主动连接设备只能靠 MQTT 的长连接实现双向通信。网络不稳定无线网络、4GMQTT 的自动重连和 QoS 机制更适合。HTTP 每次请求都要重新建立连接在网络抖动时体验很差。6.3 国产化环境下的额外考量在银河麒麟、OpenHarmony 等国产化环境下除了协议选择还需要考虑软件源可用性银河麒麟的软件源可能没有最新版的 MQTT Broker 或客户端库需要提前确认或自行编译。硬件兼容性某些国产化硬件平台如飞腾、鲲鹏的 ARM 架构可能需要专门编译的二进制包。安全合规国产化项目通常有安全合规要求MQTT 通信需要启用 TLSHTTP API 需要启用 HTTPS并且使用国密算法如 SM2、SM4替换国际算法。# 在银河麒麟上安装 EMQXARM64 版本 wget https://www.emqx.com/zh/downloads/broker/5.4.0/emqx-5.4.0-ubuntu22.04-arm64.deb sudo dpkg -i emqx-5.4.0-ubuntu22.04-arm64.deb sudo systemctl start emqx sudo systemctl enable emqx注意下载 EMQX 时一定要确认操作系统版本和 CPU 架构。银河麒麟 V10 SP1 基于 Ubuntu 22.04 的兼容性较好但如果是基于 CentOS 的版本需要下载对应的 RPM 包。7. 一些容易被忽略的细节7.1 MQTT 主题的权限控制在多租户或多项目场景下MQTT 主题的权限控制很重要。如果不做限制A 项目的设备可能订阅到 B 项目的主题造成数据泄漏。EMQX 支持基于 ACLAccess Control List的主题权限控制。可以配置每个客户端只能发布和订阅特定前缀的主题# EMQX ACL 配置示例 # 允许 device-001 订阅 door/access/device-001/# {allow, {clientid, device-001}, subscribe, [door/access/device-001/#]}. # 允许 device-001 发布到自己的事件主题 {allow, {clientid, device-001}, publish, [door/access/device-001/event, door/access/device-001/status]}. # 拒绝其他所有 {deny, all}.7.2 HTTP API 的幂等性设计人脸库同步接口需要支持幂等。也就是说同一个请求执行多次结果应该是一样的。这对于断点续传和失败重试很重要。实现幂等的方式有几种使用唯一业务 ID新增人员时如果 personId 已存在返回 200 而不是 409表示已存在无需重复创建。使用幂等键客户端每次请求带一个唯一的 requestId服务端记录已处理的 requestId重复的 requestId 直接返回上次的结果。使用版本号每次更新带一个版本号服务端只接受版本号比当前大的更新。7.3 消息去重与顺序保证MQTT 的 QoS 1 会导致消息重复设备端需要做去重。我的做法是在消息体里带一个唯一的 messageId可以用 UUID设备端维护一个最近处理过的 messageId 集合比如最近 1000 条收到重复的 messageId 就丢弃。顺序保证方面MQTT 不保证跨主题的消息顺序但同一主题、同一 QoS 级别的消息通常是有序的。如果业务对顺序敏感比如配置更新必须先于指令下发可以在消息体里带序列号设备端按序列号排序处理。7.4 日志与监控门禁系统的日志非常重要出问题时需要快速定位。我通常会在以下几个位置打日志设备端MQTT 连接状态、指令接收、开门执行结果、HTTP 同步进度Broker 端客户端连接/断开、消息发布/订阅、异常断开中心平台API 请求日志、消息处理日志、异常告警监控指标方面重点关注MQTT 连接数突增可能意味着设备重连风暴消息延迟P99 延迟超过 1 秒需要告警消息丢失率QoS 1 消息的丢失率应该接近 0HTTP API 的响应时间和错误率8. 最后说几句实操心得人脸门禁系统的通信架构设计核心就一句话让合适的协议做合适的事。HTTP API 适合管理面的增删改查和批量同步MQTT 适合数据面的实时指令和事件上报。两者不是二选一的关系而是互补的关系。我在实际项目中总结的几个原则第一不要用 HTTP 轮询做实时指令。延迟高、资源浪费大设备一多就撑不住。这是我最深刻的教训。第二不要用 MQTT 传大文件。人脸特征值、照片、固件包这些大文件走 HTTP 或对象存储MQTT 只传指令和元数据。第三clientId 必须稳定。这是 MQTT 会话管理的基础带随机数的 clientId 会导致会话泄漏和 Broker 内存暴涨。第四在目标环境上尽早验证。银河麒麟、OpenHarmony 这些国产化环境的软件生态和常见 Linux 发行版有差异很多在 Ubuntu 上跑得好好的东西到了麒麟上就出问题。提前验证比事后排查省事得多。第五日志和监控不能省。门禁系统出问题时用户就在门口等着排查时间窗口很短。完善的日志和监控能让你在几分钟内定位问题而不是花几个小时翻代码。这些经验都是一个个坑踩出来的希望能帮到正在做类似项目的朋友。如果你在国产化环境上遇到 MQTT 或 HTTP 相关的兼容性问题欢迎交流。