第七部分：部署与运维文档
7.1 部署方案
7.1.1 软件部署架构
- 负载均衡：Nginx（HTTPS卸载）
- 后端服务：Spring Boot（jar包），systemd管理，3节点集群
- 前端：Vue打包静态文件，Nginx托管
- 数据库：MySQL主从+读写分离，InfluxDB集群
- 消息中间件：Kafka（数据采集缓冲）
- MQTT Broker：EMQX集群（3节点）
7.1.2 部署步骤（摘要）
- 安装Docker及docker-compose（或K8s）
- 拉取镜像：MySQL, InfluxDB, EMQX, Redis, Kafka, 后端服务镜像
- 配置环境变量：数据库连接、JWT密钥、MQTT地址
- 执行数据库初始化脚本（schema.sql，seed.sql）
- 启动所有容器，验证健康检查
- 配置Nginx反向代理与SSL证书（Let's Encrypt）
- 硬件设备配置：烧录固件，配置平台域名
7.1.3 硬件部署指导
- 温湿度传感器：室内壁挂，离地1.5米，避免阳光直射
- 控制终端：靠近被控设备，确保Wi-Fi信号强度≥-70dBm
- 通信模块天线竖直向上，远离金属遮挡
7.2 运维手册
7.2.1 日常巡检项
- 每日：检查服务进程、磁盘使用率、数据库连接数
- 每周：查看错误日志，清理过期数据
- 每月：安全补丁更新，性能容量评估
7.2.2 常见问题处理
| 问题现象 | 可能原因 | 处理步骤 |
|---|---|---|
| 设备无法接入 | Broker挂掉 | docker ps 检查EMQX，重启容器 |
| 数据显示延迟 | Kafka积压 | 增加消费者实例或扩容 |
| 控制指令超时 | 设备网络差 | 检查设备RSSI，建议移近路由器 |
7.2.3 备份与恢复
- 数据库每日全量备份脚本（mysqldump + influx backup）
- 备份保留到OSS，保留30天
- 恢复：停止服务 → 恢复备份 → 重启验证
7.3 当前 MVP 部署（2026-09-12 补充）
7.1 描述生产目标架构；本节描述仓库中已经实现的 Node.js MVP，两者不可混作已上线能力。
7.3.1 环境要求与启动
- Windows/Linux/macOS，Node.js 20 或更高版本。
- 运行时无第三方 npm 依赖，不需要执行
npm install。
cd E:\_1\notes\项目规划\物联网项目文档\iot-platform-mvp
npm test
$env:TOKEN_SECRET='请替换为至少32字节随机值'
$env:DATA_FILE='E:\iot-data\db.json'
$env:PORT=3000
npm start
验证项：
Invoke-RestMethod http://127.0.0.1:3000/api/health
Start-Process http://127.0.0.1:3000/admin/
健康响应中 data.status 必须为 up；后台静态资源和 API 由同一进程提供，不需要额外处理 CORS。
7.3.2 数据文件
默认数据路径为 iot-platform-mvp/backend/data/db.json。服务首次启动会生成演示数据；写入时先创建临时文件再同卷重命名，避免进程中断留下半个 JSON。JSON 存储只能运行一个写进程，不支持共享磁盘多实例。
备份：停止写入或停止服务，复制数据文件并计算 SHA-256。恢复：停止服务，校验备份 JSON 可解析和哈希正确，用备份替换数据文件，启动后执行 npm test（独立临时库）和健康/登录/关键数据抽查。
7.3.3 进程管理示例
Windows 可使用 NSSM/任务计划程序，Linux 可使用 systemd。进程账户只需要读取代码和读写 DATA_FILE 所在目录，不应使用管理员/root 身份。服务异常退出自动重启，但连续失败应退避并告警，避免覆盖诊断日志。
反向代理应完成 HTTPS、请求体上限、访问日志和超时。/api/device/telemetry 请求体当前上限 1MB；生产应按业务进一步收紧。公网部署必须禁用默认密钥、修改演示密码并限制管理后台来源。
7.4 生产化运行手册
7.4.1 关键 SLI
| 链路 | 指标 | 初始告警建议 |
|---|---|---|
| HTTP API | 请求量、P50/P95/P99、5xx、鉴权失败 | 5 分钟 5xx > 2% |
| MQTT | 连接数、连接失败、上下行消息、丢弃数 | 连接失败率 > 5% |
| Kafka | consumer lag、重试/死信 | lag 持续 10 分钟增长 |
| 指令 | pending 时长、成功/失败/超时率 | 10 分钟超时率 > 3% |
| 数据库 | 连接、慢查询、磁盘、复制延迟 | 磁盘 > 75%，复制延迟 > 60s |
| 设备 | 在线率、离线时长、固件分布 | 关键设备离线立即告警 |
7.4.2 故障定位顺序
- 用 requestId/commandId/deviceId 确认单个请求和影响范围。
- 检查 API、数据库、Broker、Kafka 和消费者健康，不立即重启全部组件。
- 控制超时依次核对指令记录、Outbox、发布结果、设备订阅、设备日志和 ACK。
- 遥测缺失依次核对连接、ACL、Broker 入站、Kafka lag、校验死信和时序库写入。
- 先止损（暂停发布/限流/切只读/回滚），保留日志和时间线，再恢复和复盘。
7.4.3 备份恢复目标
业务关系库目标 RPO≤15 分钟、RTO≤60 分钟；遥测按成本和客户合同独立设定。每季度至少一次恢复演练，必须恢复到隔离环境并验证用户数、设备数、绑定关系、最近指令和随机遥测，而不只验证备份文件存在。