蜂信物联

简体中文

English

简体中文

English

主题

部署与升级 ​

部署和升级应先确认产品版本与部署方式，再按“容器/进程 → 配置 → 数据库与缓存 → MQTT → 页面 → 业务链路”的顺序验收。不要只以首页能打开作为部署成功标准。

1. 常见问题 ​

1.1. 推荐使用哪种部署方式，部署前需要准备什么？ ​

快速体验和小规模验证优先使用 Docker Compose；二次开发环境也可先用 Docker 跑通基础依赖，再分别替换后端 jar 与前端资源。

部署前至少准备：

  1. Linux 服务器、Docker 和 Docker Compose。
  2. 可用的域名或 IP、安全组/防火墙和业务端口。
  3. 与当前版本匹配的安装包、数据库脚本和配置文件。
  4. 商业版授权证书及安装所需信息。
  5. 数据备份、日志目录和后续升级/回滚方案。

完整步骤见 Docker 快速部署。

1.2. 如何使用一键脚本、docker-compose 或已有 Docker 镜像部署？ ​

  • 一键脚本：服务器安装 Docker 环境后，按官方页面提供的命令执行，不要在其他来源复制同名脚本。
  • docker-compose：将部署文件放到约定目录，检查配置后在 /var/data/ 执行 docker-compose up -d。
  • 已有镜像：使用 docker load -i <镜像文件> 导入，再按部署包的 compose 配置启动；镜像本身不包含可省略的业务配置和验收步骤。

启动后使用 docker-compose ps 和容器日志确认核心服务状态，详见 Docker 快速部署。

1.3. 部署后页面 404、菜单打不开或验证码不显示，如何排查？ ​

先区分静态资源、后端接口和登录依赖，不要同时修改多项配置：

  1. 检查 Nginx 容器/进程、前端部署目录和浏览器控制台是否有静态资源 404。
  2. 检查 /prod-api/ 反向代理、后端端口和接口前缀。
  3. 检查后端是否启动完成、MySQL 是否初始化完成、Redis 密码是否匹配。
  4. 查看后端日志中的验证码、Token、数据库或授权异常。
  5. 同一服务器部署多套系统时，确认端口、目录和代理没有互相覆盖。

参考 演示环境排错 和 Nginx 部署。

1.4. 后端容器反复重启或端口被占用怎么办？ ​

先看容器日志中的最早根因，不要只观察最后一次重启：

  • 检查 MySQL、Redis、时序库和 EMQX 是否可连接。
  • 检查授权证书名称、路径和配置格式。
  • 使用 ss -lntup 等命令确认端口占用，再调整宿主机端口映射或停止冲突服务。
  • 检查内存是否不足、挂载目录是否可写、YAML 是否有效。

日志查看与巡检命令见 运维监控。

1.5. 如何查看 Java、MySQL、EMQX 等容器日志？ ​

在部署目录执行：

shell
docker-compose ps
docker logs -n 300 java
docker logs -n 200 mysql
docker logs -n 200 redis
docker logs -n 200 emqx
docker logs -n 200 nginx

排错时保留发生时间、完整异常栈和最早根因；持续观察可将 -n 换成 -f，但不要只截取最后一行错误。更多命令见 Docker 快速部署。

1.6. 部署后前后端功能与当前代码不一致怎么办？ ​

一键部署包不一定包含最新源码。二次开发或升级后，应分别确认后端 jar、前端静态资源、可视化资源和数据库脚本是否来自同一目标版本。

Docker 部署通常需要替换 /var/data/java/ 中的后端 jar 和 /var/data/nginx/vue/ 中的前端内容，再重启对应服务并完成业务验收。不要只替换前端或只替换后端。详见 升级指南。

1.7. 后端提示缺表、Mapper/SQL 异常或升级后无法启动怎么办？ ​

优先按数据库初始化与升级链路排查：

  1. 确认当前代码版本和数据库中的实际表结构是否匹配。
  2. 新部署检查初始化 SQL；升级检查是否按版本顺序执行全部升级 SQL。
  3. 检查脚本是否执行失败、重复执行或部分执行，不要直接反复重跑。
  4. 核对 MySQL 版本、表名大小写、数据源连接和账号权限。
  5. 恢复备份或回滚前，先保留现场日志和数据库状态。

升级前备份与回滚步骤见 升级指南。

1.8. “内部客户端未启动”或 EMQX/Redis 启动异常如何排查？ ​

先确认当前使用内置 Netty Broker 还是外部 EMQX，两者不要混用：

  • 检查 Redis 地址、端口、密码和网络。
  • 使用 EMQX 时，检查监听器、HTTP 认证、Webhook、后端连接地址和认证账号。
  • 本地 Windows 运行后端而 EMQX 在容器或其他机器时，将回调地址改为 EMQX 实际可访问的后端地址，不能使用对当前网络无意义的 java 或 localhost。
  • 检查设备上下线和订阅事件是否进入后端日志。

配置示例见 EMQX 安装与配置。

1.9. 如何切换内置 Netty Broker 与 EMQX？ ​

通过当前版本配置选择其中一种 MQTT 服务，并同步调整后端、前端 WebSocket、认证回调和部署端口。切换后不能只验证客户端能连接，还要验证设备上线、属性上报、指令下发和状态回传。

内置 Broker 与 EMQX 的配置说明见 平台介绍中的部署 FAQ 和 技术栈与模块。

1.10. 商业版证书从哪里安装，subject 和证书路径如何核对？ ​

商业版部署后需要先安装授权证书。未安装证书的新版本通常会进入证书安装页面；本地运行和 Docker/生产部署的证书路径不同。

重点检查：

  1. 前端已上传与当前部署匹配的证书和公钥文件。
  2. 对应环境的 application-dev.yml 或 application-prod.yml 已配置 license.subject。
  3. licensePath、publicKeysStorePath 与实际文件位置一致。
  4. Docker 部署已挂载证书目录，并使用生产配置。
  5. 重启后授权提示消失，商业功能可正常进入。

完整操作见 授权配置。

1.11. 证书提示区域不在授权范围或证书校验异常怎么办？ ​

证书与授权服务器/项目环境不匹配时，应先核对实际部署信息和证书内容，不要尝试绕过校验：

  • 检查证书名称、subject、路径和依赖版本是否一致。
  • 服务器地域、IP、MAC 或部署项目发生变化时，整理变化前后的信息并联系客服核对授权。
  • 更新后端或 fastbee-common 等依赖时，保持所有相关包与源码版本一致，并清理失败依赖缓存后重新拉取。
  • 保留完整异常栈，区分证书读取失败、依赖不匹配和业务接口自身鉴权失败。

证书配置见 授权配置。

1.12. 服务器配置如何选择？ ​

基础体验可从当前文档建议的 4 核 8G、100G 以上硬盘 起步；正式项目需要根据连接数、上报频率、历史数据和视频需求扩容。

已有压测报告使用 8 核 16G、10Mbps 作为单机稳定运行推荐配置，并给出特定场景下的连接/QPS 结果。该配置不是统一“最低配置”，也不构成任意业务下的容量保证。参考 技术栈与运行环境 和 压测报告。

1.13. 切换主数据库时需要准备什么？ ​

先确认当前版本已适配目标数据库，并准备对应初始化或升级 SQL、驱动、连接账号和字符集配置。商业版已适配的数据库包括 MySQL、PostgreSQL、Oracle、SQL Server、达梦和人大金仓等，但各数据库有各自测试版本和脚本；开源版支持范围以开源版总览为准，不直接套用这份商业版清单。

从 application-sql 的配置示例复制目标数据源到实际环境配置，再验证启动、核心页面和设备业务。不要只修改连接串而忽略 SQL 方言和表结构。详见 多数据源支持。

1.14. TDengine 连接超时或不需要时序库时如何处理？ ​

需要 TDengine 时，检查服务状态、数据源地址、客户端驱动、FQDN/DNS 和端口；服务器、客户端和驱动版本也要匹配。暂时不使用时，可按当前文档关闭对应时序库开关，使用 MySQL 保存规模较小的历史数据。

不要在未确认数据迁移和保留策略时直接切换或删除历史库。详见 时序数据库安装与启用。

1.15. 版本升级 SQL、前后端替换和回滚按什么顺序执行？ ​

推荐顺序为：确认当前/目标版本 → 进入维护窗口 → 备份数据库与部署包 → 阅读发布说明 → 按顺序执行升级 SQL → 替换后端 jar → 替换前端资源 → 按版本说明清理必要缓存 → 启动并验收。

升级后至少验证登录、产品设备、MQTT 上报下发、历史数据、规则告警、通知工单、视频和按需启用的 AI。失败时恢复旧版部署包与数据库备份，不要带损坏状态继续迭代升级。详见 升级指南。

1.16. 已做二次开发，如何升级到新版本？ ​

先在独立分支或测试环境合并目标版本，区分官方修复与本地业务修改，再处理代码冲突、数据库脚本、配置项和前端依赖变化。

升级前记录本地修改清单和接口契约，升级后重点回归自定义协议、权限、页面和业务链路。不要把生产环境直接覆盖作为第一步，也不要跳过中间版本 SQL。通用流程见 升级指南。

1.17. 集群节点提示 localAddress 非本机可绑定地址或看不到其他节点怎么办？ ​

检查每个 FMQ 节点的 application.yml：

  1. localAddress 必须是当前节点自己的可绑定内网 IP。
  2. static-ip-addresses 应包含全部集群节点地址，且各节点配置一致。
  3. 节点间内网端口、路由和防火墙必须互通。
  4. 修改后重启对应节点，并在 FMQ 可视化的节点页面验证。

容器或虚拟机环境中的地址必须以实际网络命名空间为准，不要直接照抄宿主机 IP。详见 FMQ 集群部署。

1.18. 最新版本和未发布版本信息在哪里查看？ ​

统一查看 发布说明，其中维护各版本新增功能、注意事项和发布状态。未发布版本的日期可能仍为待定，不将“近期发布”或聊天记录中的预测作为升级依据。