硬件云平台私有化部署说明

硬件云平台是软件和硬件联动的桥梁，长期以来，使用公有云还是自建私有云平台是备受大家关心的问题，随着物联设备的大量普及，将硬件融入到软件开发中是大势所趋，但硬件云平台大多不可控，只能调用别人的接口，一直是大家担忧的问题，为此，公司提供了一套硬件云系统，软件开发商可自行部署，采购硬件后，硬件自行运维管理，同时也可以在局域网等特殊网络环境部署，提升用户体验的同时提高竞争力。 支持的设备型号： - W70M 云喇叭 - W71M 空开断路器 - W763 门禁控制器 - W765 4G门禁面板机 - W766 4G门禁面板机 - W77 人脸识别门禁一体机 - W896 WiFi锁 - W896 4G锁

案例

演示服务器http://114.132.181.107:2828 （演示环境仅供查看，请勿修改配置；演示账号请联系技术支持获取。）

运行环境

Ubuntu 20.04 LTS、MySQL 8.0.24、Redis 7.4.1、进程守护管理器 3.0.5；推荐在宝塔面板上操作，方便维护。
需使用端口：1883、8883、2828

最新完整部署包下载

当前版本：zycloud v2.1.7（Linux amd64）

首次安装请下载：zycloud-2.1.7-linux-amd64-full.tar.gz 完整部署包

• 脱敏配置单独下载：app.toml 配置模板。已下载旧包但缺少配置时，将它放入部署目录的 web/config/app.toml，填写所有 CHANGE_ME 字段后启动；不要覆盖已经配置好的文件。
• v2.1.7 完整包：默认监听地址为 0.0.0.0，包含本机回环访问，避免在线更新探测被拒绝；已预置 web/config/app.toml 和环境变量模板。业务程序自身不会自动生成缺失配置。首次安装推荐在终端运行 python3 configure.py；交互终端运行 ./start.sh 时，未配置会自动进入配置向导。宝塔等非交互启动需先完成配置。
• v2.1.7 新增：设备列表的序列号、网络标识、app_id 支持点击复制，复制成功后显示提示；支持 HTTP 页面，保留前导零及完整长字符串。空值显示为“—”。
• 文件大小：115,198,435 字节（约 109.86 MiB）。
• SHA-256：9ba8e7511e9a7baf302ec8f472f20528b1f31f991d696f6d7e78aaec3869e6b9，也可下载 SHA-256 校验文件。
• 包内包含：deviceApi、完整管理端 web/admin、zycloud-launcher 1.0.0、release.json、EMQX 5.7.2 / Erlang 14.2.5、预置脱敏配置、配置生成工具、启动脚本及 README-DEPLOY.md。
• EMQX 和升级守护器直接复用长期验证的测试环境文件，保持 EMQX 5.7.2 / Erlang 14.2.5；业务程序和管理端为 v2.1.7。
• 运行环境仍需自行安装 MySQL、Redis、Python 3 及 EMQX 所需系统库。完整包不带演示环境的数据库、账号密码、日志及服务器证书；首次配置时生成本机独立密钥。

全新部署请解压到新目录，先运行 python3 configure.py 生成配置，再按包内 README-DEPLOY.md 配置 EMQX 管理 API 和启动方式。完整包用于新安装，已有部署请使用后台“在线更新”，由超级管理员手动确认下载安装；升级失败由守护器恢复上一版本。

已有服务器在线升级：稳定通道清单 latest.json 由后台在线更新功能使用，升级包只包含程序、管理端及版本信息。首次安装请使用上方完整包。 部署步骤：

1.准备运行环境、数据库和 Redis

可在宝塔面板安装 MySQL 8 和 Redis 7，并安装 Python 3。创建空数据库和专用数据库用户，设置 Redis 密码；EMQX 系统依赖请按包内 README-DEPLOY.md 安装。 Redis要进入性能调整里面设置密码

2.进入文件—wwwroot下—新建个zycloud文件夹，然后把下载的软件上传上去解压出来，如图所示。

3.生成配置并设置进程守护

进入解压后的 zycloud 根目录，执行 python3 configure.py，按提示设置服务器地址、MySQL、Redis 和管理员账号。完整包已带 web/config/app.toml 脱敏模板，工具会替换未修改的初始模板、生成 EMQX 认证配置及随机系统密钥，修改过的配置拒绝覆盖。

按包内 README-DEPLOY.md 检查并启动 EMQX，创建管理 API Key 后填入 runtime.env。EMQX 管理端默认仅允许本机访问，随机管理密码保存在本机 deployment-secrets.txt，请勿公开。

在宝塔、systemd 或 Supervisor 中托管 start.sh，工作目录设置为 zycloud 根目录，使用与文件所有者一致的运行用户。该脚本加载环境变量后启动升级守护器，由守护器启动业务程序；项目服务端口为 2828。

4.按实际使用配置防火墙

按需放通 2828、1883。完整包默认关闭 MQTT TLS 8883，配置自己的正式证书并开启后才开放 8883。MySQL、Redis 和 EMQX 管理端口仅允许可信管理来源访问。

5.核对配置并启动服务

确认前面生成的数据库、Redis 及管理员配置正确后启动服务。程序会初始化业务表，无需导入演示数据库。以下配置截图为旧版示意，实际以包内说明为准。 修改好配置文件后去启动服务，若报错，多半是数据用户名密码，redis密码等错误。 启动后如下图所示：

6.访问你的IP+端口号/admin/#/login，如演示服务器的http://114.132.181.107:2828/admin/#/login：

进入超管登录界面后，请使用部署时设置或由管理员分配的账号登录；首次登录后请立即确认账号与密码策略。 登录后可以看到如下界面： 从mysql配置保存一次数据库配置，将数据库信息同步给EMQ： 在系统配置可以配置短信验证码参数，邮件验证码参数，等信息，服务器IP修改成自己的。 服务器地址，devkey，appkey，sm4key，sm4offset，这五个信息写入硬件，硬件就可以连接该服务器了。

在线更新提示本机 2828 端口连接被拒绝

若错误包含 127.0.0.1:2828 和 connect: connection refused，表示升级守护器还没有连到平台健康接口。先检查服务监听地址与端口，不要跳过升级健康检查。

旧完整包配置工具曾把公网 IP 同时写入监听地址，只监听公网 IP 时，本机回环地址可能无法连接。客户可先备份自己的 web/config/app.toml，将其中的监听配置改为：

[web]
ip = "0.0.0.0"
port = "2828"

只修改 [web] 下的 ip；port 保留实际服务端口，[system].serverurl 保留客户自己的公网 IP 或域名。不要用整份模板覆盖现有数据库、密码及设备密钥。随后在维护窗口通过进程管理器重启平台守护器对应的进程，再回到“在线更新”检查并手动安装；EMQX 不需要重启。

如果实际端口不是 2828，还需把守护器的 ZYCLOUD_UPDATE_HEALTH_URL 设置为实际端口的本机地址，如 http://127.0.0.1:实际端口/internal/update/health，并在修改环境变量后重启守护器。如果已经监听 0.0.0.0 且端口正确仍被拒绝，应进一步检查平台进程是否退出、端口是否启动，以及守护器和平台是否在同一网络环境中。

新版完整包已修正默认监听配置。当前业务程序版本为 v2.1.7，签名校验、健康检查和失败回退机制保留。

MySQL 配置保存成功，但同步 EMQX 提示认证器不存在

如果出现 Authenticator 'password_based:mysql' does not exist，表示当前 EMQX 中还没有 MySQL 认证器。旧版只更新已有认证器，因此首次部署会同步失败。

请由管理员手动升级到 v2.1.7（包含 v2.1.6 的修复），然后在“配置 → MySQL”中再次保存。新版会在认证器缺失时创建，已有时更新；API 鉴权、地址或服务错误仍会明确提示失败。

已部署环境优先从后台“在线更新”检查并手动安装。若健康检查不通过而拒绝升级，请先处理故障，或由管理员备份后在维护窗口手动替换升级包内的程序及管理端，保留数据库、EMQX 数据和现有配置。完整包用于全新部署，勿直接覆盖客户目录。

新部署的认证项放在 emqx/data/configs/cluster.hocon 中，支持后台修改及重启后保留。如果原有环境在 emqx/etc/emqx.conf 或环境变量中另设了 authentication，请先核对配置优先级，避免重启后覆盖后台保存的认证设置。程序升级不会自动改写客户的 EMQX 配置。

硬件端配置方法：

1.在蓝牙配网界面点击硬件云配置： 2.填入上面的5个参数，连接设备写入：

如云喇叭：长按配网按键30秒，初始化设备，进入配网模式，配置硬件云参数，配置wifi即可连接上。 详细视频教程地址（旧版本，可参考）：点击前往

业务或技术咨询

电话：0851-82218221 微信：defineworld