基于 ESP8266 MQTT 的智能门禁系统一个完整的物联网门禁项目实现远程开门、状态监控、设备管理等功能项目源码github.com/DoLovya/door-clicker〇、项目背景为什么做这个我住的是老式单元楼开单元门一直很麻烦从外面回来必须带单元门钥匙 / 门卡出门散步、跑步、拿快递手上拎东西时掏钥匙掏门卡很麻烦忘带单元门钥匙时只能站在单元门口等同楼栋的邻居进出跟着才能进门。门铃响了要跑到室内对讲分机去按单元门开锁键朋友来访、外卖/快递到了按楼下门口机玄关旁的室内对讲分机类似电话的面板会响不管我在沙发上吃饭还是在书桌前工作都得放下手里的事跑到玄关去按单元门开锁按钮楼下的人才能拉开单元门进来很麻烦。既然本质上只是按一下室内分机的单元门开锁键为什么不能让舵机来代替于是想到用SG90 舵机 ESP8266 MQTT的方案舵机用胶带固定在室内对讲分机的单元门开锁按键旁转动拨片就能精准按压到按键效果和手动按完全一致ESP8266 通过家中 WiFi 连接公网 MQTT Broker手机浏览器打开开门页点击开门按钮就会把指令发过去。现在回来不用等邻居、门铃响了不用跑到门口坐在沙发上点一下手机就行。一、项目简介Door Clicker 是一个基于 ESP8266 的智能门禁控制系统通过 MQTT 协议实现远程开门。用户可以通过手机浏览器一键开门支持设备在线状态监控、舵机角度可调、管理员权限管理等功能。核心特性极简开门界面手机端一键开门操作简单️Web 管理后台MQTT 配置、舵机参数调整、实时日志查看MQTT 协议通信天然支持内网穿透公网可控制内网设备心跳机制设备定期上报状态90 秒超时判定在线/离线自动重连MQTT 断线自动恢复开门指令失败自动重试️舵机参数可调开门角度、延时均可配置实时日志系统操作日志、错误日志分类查看配置页认证配置页面需登录访问二、系统架构数据流说明Web 浏览器 → Web Server通过 HTTP API 发送开门请求Web Server → MQTT Broker将命令发布到指定 TopicMQTT Broker → ESP8266推送到订阅该 Topic 的设备ESP8266 → 舵机控制 GPIO 信号执行开门动作为什么用 MQTTMQTT 协议实现了内网穿透的效果ESP8266 主动连接 MQTT Broker出站连接无需公网 IPWeb Server 作为 MQTT 客户端通过 Broker 转发命令设备可以在任何网络环境下工作三、硬件准备所需组件组件型号说明主控ESP8266 (Huzzah)WiFi 通信 舵机控制舵机SG90/MG996R门锁驱动MQTT BrokerEMQX/Mosquitto消息中转硬件安装舵机固定在室内对讲分机的单元门开锁按键旁后只需将三根线VCC、GND、SIGNAL插入 ESP8266 的排针即可。安装细节图舵机拨片按压按键位置 舵机线直插 ESP8266接线说明ESP8266 引脚连接3V3舵机 VCC建议外部 5V 供电G舵机 GNDD4 (GPIO2)舵机 SIGNAL SG90 舵机的三根线红/棕/橙对应 VCC/GND/SIGNAL。在 ESP8266 Huzzah 开发板上3V3 / G / D4 三个引脚连续排列正好对应舵机 3Pin 公头的针距可直接将舵机线插到排针上无需杜邦线分线接线非常方便。⚠️ 舵机启动电流较大可达 500mA建议使用外部 5V 供电以避免 ESP8266 重启。四、快速开始4.1 搭建 MQTT Broker推荐使用 Mosquitto轻量、开源# Docker 快速部署 Mosquitto允许匿名连接适合本地快速验证dockerrun-d--namemosquitto\-p1883:1883\-p9001:9001\eclipse-mosquitto:latest\mosquitto-c/mosquitto-no-auth.confmosquitto-no-auth.conf是镜像内置的无需认证配置适用于快速体验。生产环境建议自行挂载配置文件开启账号密码 TLS。4.2 烧录固件先在 VSCode 中安装PlatformIO IDE 插件打开 VSCode左侧扩展商店搜索PlatformIO IDE并安装安装完成后左侧会出现 PlatformIO 图标等待初始化完成首次安装会自动下载 PlatformIO Core在 VSCode 中打开项目里的door-clicker-firmware文件夹然后点击左下角的 PlatformIO 专用终端图标️ 形状打开 PlatformIO CLI 专用终端在打开的 PlatformIO 终端中执行以下命令ESP8266 开发板通过 USB 连接电脑cddoor-clicker-firmware# 编译pio run# 烧录pio run--targetupload# 查看串口日志pio device monitor 也可以直接点击 VSCode 底部状态栏的 PlatformIO 快捷按钮✓编译、→上传、插头图标串口监视。4.3 启动 Web 服务cddoor-clicker-web# 创建虚拟环境首次使用python3-mvenv venvsourcevenv/bin/activate# 安装依赖pipinstall-rrequirements.txt# 启动服务python run.py4.4 访问系统页面URL说明开门页http://host:5000/极简开门按钮配置页http://host:5000/configMQTT 配置、舵机参数、日志登录页http://host:5000/login管理员登录4.5 默认账号用户名admin密码admin⚠️ 首次登录后请立即修改密码Web 界面效果五、功能详解Web 管理后台配置页总览MQTT 连接、舵机参数、密码管理、通信日志集中管理5.1 固件配网ESP8266 端固件烧录后第一次启动ESP8266 会进入AP STA 双模式一边开放 WiFi 热点供你设置参数一边尝试连接上次配置的路由器首次为空则跳过。步骤 1连接设备热点参数值WiFi 名称SSIDDoorClickerWiFi 密码door1234 SSID 与密码在door-clicker-firmware/src/main.cpp中定义可自行修改。步骤 2访问 ESP8266 配置页手机/电脑连上DoorClicker热点后浏览器访问http://192.168.4.1/自动重定向到http://192.168.4.1/config配置页。页面包含 WiFi 配置、MQTT 配置、舵机参数和舵机测试四大分区分区字段说明WiFi 配置SSID / 密码家中路由器的 WiFi 凭据MQTT 配置Server / Port / 用户 / 密码 / TopicMQTT Broker 地址、端口和开门主题默认door/芯片ID_HEX8舵机参数GPIO 引脚默认2即 D4舵机测试GPIO 引脚 / 测试按钮填入引脚后点「▶ 测试舵机」验证 0°→90°→0° 旋转是否正常✅ 填写后点「保存配置」ESP8266 会重启并尝试连接路由器。截图中的测试按钮▶ 测试舵机不会写入配置可放心点击验证接线。步骤 3恢复正常联网保存配置并重启后ESP8266 会连接到你设置的路由器 WiFi此时DoorClicker热点仍保留AP 模式常驻但 STA 模式已连接公网你可以把手机/电脑重新连回家用路由器即可正常上网ESP8266 通过 MQTT 定期上报心跳到 BrokerWeb 服务端通过心跳判定设备在线/离线步骤 4部署 Web 服务并测试开门# 1. 部署 door-clicker-web参考 4.3 节与第八章cddoor-clicker-web pipinstall-rrequirements.txt python run.py# 2. 在 Web 配置页/config填入相同的 MQTT Broker 与开门 Topic# 若连接成功页面会显示「MQTT 已连接 · 设备在线」# 3. 回到开门页/点击中间的「开门」按钮# 舵机应按配置的角度执行开门 → 延时 → 关门动作至此完成「烧录 → 配网 → 联网 → 开门」全链路后续管理全部通过 Web 端进行。5.2 开门协议Web 端通过 MQTT 发送 JSON 指令到door/{chip_id}[{angle:90,duration:200},{angle:0,duration:200}]字段类型说明angleint目标角度0-180durationint动作持续时间毫秒舵机控制器支持多步命令队列开门→关门依次执行。5.3 心跳机制设备每 30 秒发布心跳消息到door/{chip_id}/status{event:heartbeat,clientId:door_3FF12345,uptime:3600}在线判定规则Web 端 90 秒内收到心跳 → 设备在线Web 端超过 90 秒未收到 → 设备离线5.4 舵机配置在配置页可以调整舵机参数参数说明默认值开门角度开门时舵机转到的角度90°开门延时开门动作持续时间200ms关门角度关门时舵机转到的角度0°关门延时关门动作持续时间200ms5.5 MQTT 连接管理系统提供完整的 MQTT 连接管理能力自动重连MQTT 断线后自动恢复连接开门重试发送开门指令时若检测到未连接自动重连后重试连接测试配置页一键测试 MQTT Broker 连通性5 秒超时手动重连配置页可手动触发 MQTT 重连5.6 主题订阅管理除了默认的设备状态主题还支持手动订阅/取消订阅额外主题# 默认订阅 door/{chip_id}/status # 设备心跳状态 # 可手动添加 door/{chip_id}/custom # 自定义主题5.7 实时日志系统系统内置日志管理支持分类查看日志类型说明info操作记录开门、配置变更等error错误日志MQTT 连接失败等sendMQTT 发送记录receiveMQTT 接收记录日志存储在data/logs/目录可通过配置页查看和清空。5.8 配置页认证配置页面需登录后才能访问密码使用 SHA-256 加密存储importhashlib password_hashhashlib.sha256(password.encode(utf-8)).hexdigest()配置文件中只存储 hash 值即使泄露也无法还原明文密码。六、API 接口方法路径认证说明GET/-开门页面POST/api/open/door-发送开门指令GET/api/mqtt/status-获取 MQTT 连接和设备状态GET/api/device/status-获取设备在线状态GET/config登录配置页面GET/api/config登录获取当前配置PUT/api/config登录更新配置支持密码修改POST/api/mqtt/test登录测试 MQTT 连接POST/api/mqtt/reconnect登录手动重连 MQTTGET/api/topics登录获取已订阅主题列表POST/api/topics登录订阅新主题DELETE/api/topics/topic登录取消订阅GET/api/logs登录获取日志DELETE/api/logs登录清空日志GET/api/health-健康检查七、部署上线7.1 服务器要求Linux 服务器推荐 CentOS/UbuntuPython 3.9NginxMQTT BrokerEMQX 推荐7.2 自动化部署项目使用 GitHub Actions 实现 CI/CD包含三个工作流工作流触发条件说明web-ci.ymlpush to mainWeb 服务单元测试firmware-ci.ymlpush to main固件编译检查deploy.yamlpush to main自动部署到服务器部署流程代码推送到 main 分支GitHub Actions 运行测试通过 SSH 连接服务器拉取最新代码并安装依赖重启 systemd 服务7.3 Nginx 配置server { listen 80; server_name your-domain; location / { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }7.4 systemd 服务[Unit] DescriptionDoor Clicker Web Service Afternetwork.target [Service] Typesimple Userdoor-clicker WorkingDirectory/opt/door-clicker/door-clicker-web ExecStart/opt/door-clicker/door-clicker-web/venv/bin/python run.py Restartalways RestartSec5 [Install] WantedBymulti-user.target八、技术栈固件技术版本用途PlatformIO6.0开发环境Arduino Framework-ESP8266 SDKPubSubClient2.8MQTT 客户端ArduinoJson7.3JSON 解析Web 服务技术版本用途Python3.9编程语言Flask3.0Web 框架Flask-SocketIO5.3WebSocket 支持Paho-MQTT2.1MQTT 客户端websockets13.0WebSocket 库SHA-256-密码加密九、常见问题Q1: 舵机不动作确认 GPIO2 (D4) 接线正确检查舵机是否已初始化使用配置页面的测试功能验证Q2: MQTT 连接失败确认 MQTT Broker 地址和端口检查 WiFi 连接是否正常查看配置页的连接测试功能查看日志中的错误信息Q3: ESP8266 不断重启检查供电是否充足舵机启动电流可达 500mA舵机建议使用外部 5V 供电Q4: 设备显示离线检查 MQTT Broker 是否正常运行确认设备 WiFi 连接状态查看日志中的心跳发送情况设备状态以 90 秒超时判定Q5: 如何修改密码登录后进入配置页在密码区域输入新密码保存密码使用 SHA-256 加密存储十、总结Door Clicker 项目展示了如何使用 ESP8266 MQTT 构建一个完整的物联网门禁系统。通过 MQTT 协议实现了内网穿透使得公网可以控制内网设备。项目包含了固件开发、Web 服务、自动化部署等完整的技术栈适合作为物联网入门学习项目。