# 智慧蚕房环境监测与智能调控系统

面向养蚕场景的环境实时监测、告警通知、设备联动控制与视频监控平台。系统通过 MQTT 接收蚕房传感器/网关上报的温度、湿度、光照、CO₂ 等环境参数，支持阈值配置、异常告警、设备控制、GB28181 视频监控、连续录制与历史回放、RBAC 权限管理与审计日志。

系统提供 **Web 后台**、**React Native 移动端 APP**、**微信小程序** 三端界面，后端统一由 **Go 服务**提供 API。

## 1. 核心能力

### 1.1 环境实时监测

- 通过 MQTT 订阅遥测 Topic，接收设备上报数据
- 支持温度、湿度、光照、CO₂ 等指标
- 遥测数据优先写入 Apache IoTDB，IoTDB 不可用时降级写入 PostgreSQL
- 后端提供遥测列表、设备最新值、指标列表、历史聚合趋势 API
- 设备离线检测：5 分钟无数据自动标记离线，下发 info 命令作心跳唤醒

### 1.2 阈值配置与告警

- 支持按传感器配置上下限阈值、严重等级和防抖时间
- MQTT 入站遥测自动匹配设备、传感器和阈值规则
- 超限触发告警事件，恢复正常后发送恢复事件
- 支持告警列表、详情、确认、解除及告警关联视频片段查询

### 1.3 设备控制

- 支持单设备控制和批量控制，命令通过 MQTT 下行 Topic 发布
- 默认下行 Topic 格式：`silk/{deviceKey}/down/cmd`
- 支持红外设备控制（短连接、命令驱动型，需下发命令触发响应）
- 红外设备主题持久化存储，防止后端重启丢失

### 1.4 视频监控（GB28181）

- 基于 WVP-PRO + ZLMediaKit 实现 GB28181 摄像头注册与信令控制
- 摄像头配置管理（GB 设备 ID、通道 ID、流地址）
- 实时点播：摄像头 → ZLMediaKit → FLV 流 → Web/APP/小程序播放
- Go 后端 `/live/proxy` 接口直接代理 ZLM FLV 流，解决移动端跨域问题
- 连续录制：`recorder-go` 拉取 ZLM FLV 流，按 5 分钟分段落 Ceph S3
- 历史回看：按日期查询录像片段，支持播放、下载
- 设备状态同步：后端每 30 秒查询 WVP 设备在线状态

### 1.5 RBAC 权限管理

- 4 个角色：`admin`（管理员）、`operator`（操作员）、`viewer`（查看者）、`farmer`（养殖员）
- 15 个权限码：涵盖看板、蚕房、设备、阈值、告警、视频、能耗、日志、用户、审计
- 后端 `RequirePermission` 中间件校验权限码，admin 自动放行
- 前端路由守卫 + 菜单动态过滤 + `<HasPermission>` 按钮级控制
- 新用户注册默认角色为 `viewer`

### 1.6 通知与实时推送

- WebSocket 网关位于 `/ws`，使用 JWT 鉴权
- 广播事件：`telemetry.all`、`telemetry`、`alarm`、`alarm.recovery`
- Web/APP/小程序均接入 WebSocket 实时订阅
- 登录后自动连接 WebSocket，登出自动断开

### 1.7 能耗管理

- 设备能耗数据采集与统计
- 能耗趋势图表展示

## 2. 技术架构

```text
┌──────────────┐       MQTT        ┌──────────────┐
│ 传感器/模拟器 │ ───────────────▶ │ VerneMQ:1883  │
└──────────────┘                   └──────┬───────┘
                                          │
                    ┌─────────────────────┼─────────────────────┐
                    ▼                     ▼                     ▼
           ┌────────────────┐   ┌──────────────────┐   ┌──────────────┐
           │  Go 后端 :3000  │   │ recorder-go :9090 │   │  WVP :18080  │
           │  (Gin + GORM)   │   │  (连续录制服务)    │   │ ZLM :8081    │
           └───┬────┬───┬───┘   └────────┬─────────┘   └──────┬───────┘
               │    │   │                │                     │
       ┌───────┘    │   └──────┐         │                     │
       ▼            ▼          ▼         ▼                     ▼
  PostgreSQL    IoTDB      Valkey     Ceph S3            GB28181 摄像头
  :5432         :18081     :6379      :7480
  业务数据      时序遥测    缓存/通知   录像存储
                    │
       ┌────────────┼────────────┐
       ▼            ▼            ▼
  ┌──────────┐ ┌──────────┐ ┌──────────────┐
  │ Web 后台  │ │ 安卓 APP  │ │ 微信小程序    │
  │ React    │ │ RN 0.74  │ │ Taro         │
  │ :5174    │ │          │ │              │
  └──────────┘ └──────────┘ └──────────────┘
```

## 3. 技术栈

| 层级 | 技术 |
|---|---|
| Go 后端 | Go 1.22+、Gin、GORM、JWT、slog、WebSocket |
| 录制服务 | Go、AWS SDK v2（S3）、HTTP 拉流 |
| Web 前端 | React 18、Vite、Ant Design、Ant Design Pro、Axios、ECharts |
| 移动端 APP | React Native 0.74、React Navigation、React Native Paper、Zustand |
| 微信小程序 | Taro 4、React、TypeScript、SCSS |
| 业务数据库 | PostgreSQL 16 |
| 时序数据库 | Apache IoTDB 2.0.8（REST API） |
| 缓存/通知 | Valkey（Redis 兼容） |
| 设备通信 | VerneMQ（MQTT 3.1.1） |
| 视频流媒体 | WVP-PRO 2.7.4、ZLMediaKit（GB28181） |
| 对象存储 | Ceph RGW（S3 兼容） |
| 编译工具 | Go（交叉编译 Linux amd64） |

## 4. 目录结构

```text
silk/
├─ server-go/                      # Go 后端服务（端口 3000）
│  ├─ cmd/server/main.go           # 入口
│  ├─ internal/
│  │  ├─ config/                   # 环境变量配置
│  │  ├─ database/                 # GORM 数据库连接与自动迁移
│  │  ├─ handler/                  # HTTP handler（auth/device/alarm/video 等）
│  │  ├─ middleware/               # JWT 鉴权、RBAC 权限、CORS、限流、安全头
│  │  ├─ model/                    # GORM 数据模型 + 权限种子数据
│  │  ├─ service/                  # MQTT、IoTDB、S3、Media、Transcode 服务
│  │  └─ ws/                       # WebSocket 网关
│  ├─ go.mod
│  └─ start.sh                     # 服务器启动脚本
├─ wvp/
│  ├─ recorder-go/                 # Go 录制服务（端口 9090）
│  │  ├─ main.go                   # 拉流录制 + S3 上传
│  │  └─ go.mod
│  ├─ docker-compose.yml           # WVP + ZLMediaKit + MySQL + Redis 容器
│  └─ server.env                   # WVP 配置
├─ web/                            # React Web 后台（端口 5174）
│  ├─ src/
│  │  ├─ pages/                    # 登录、仪表盘、蚕房、设备、控制、红外、
│  │  │                            # 阈值、告警、视频、能耗、日志
│  │  ├─ components/               # HasPermission、StatCard、VideoPlayer
│  │  ├─ dal/                      # 数据访问层
│  │  ├─ api/http.ts               # Axios 实例与 JWT 注入
│  │  ├─ layout/BasicLayout.tsx    # 布局 + 菜单权限过滤
│  │  └─ router.tsx                # 路由守卫 + 权限控制
│  ├─ server.cjs                   # 生产环境静态服务 + API 代理
│  └─ vite.config.ts
├─ app/                            # React Native 移动端 APP
│  ├─ src/
│  │  ├─ api/                      # API 客户端（auth/device/alarm/video 等）
│  │  ├─ screens/                  # 登录、仪表盘、蚕房、设备、告警、视频、设置
│  │  ├─ navigation/               # 底部 Tab 导航
│  │  ├─ store/                    # Zustand 状态管理（auth + app）
│  │  ├─ components/               # StatCard、MiniChart
│  │  └─ utils/                    # WebSocket、格式化
│  ├─ android/                     # Android 原生工程
│  ├─ .env                         # API_BASE_URL 配置
│  └─ package.json
├─ miniapp/                        # 微信小程序（Taro）
│  ├─ src/
│  │  ├─ pages/                    # 登录、仪表盘、蚕房、设备、告警、视频、设置
│  │  ├─ api/                      # API 客户端
│  │  ├─ store/                    # Zustand 状态管理
│  │  ├─ components/               # StatCard、MiniChart
│  │  └─ app.config.ts             # 小程序配置（页面、TabBar）
│  └─ package.json
├─ tools/
│  ├─ simulator/                   # MQTT 设备模拟器
│  └─ iotdb/                       # 本地 Apache IoTDB 部署
├─ 变更记录.md                      # 项目变更记录
├─ 故障排查处理记录.md               # 故障排查与处理记录
├─ 部署指南(物理机).md              # 服务器部署指南
└─ 物联网设备接口和数据格式.md       # 设备接口文档
```

## 5. 后端模块

| 模块 | 路径 | 功能 |
|---|---|---|
| Auth | `handler/auth.go` | 注册、登录、JWT、修改密码 |
| Users | `handler/user.go` | 用户管理（权限码 `user:manage`） |
| Rooms | `handler/room.go` | 蚕房增删改查 |
| Devices | `handler/device.go` | 设备增删改查、状态同步 |
| Sensors | `handler/sensor.go` | 传感器增删改查 |
| Thresholds | `handler/threshold.go` | 阈值规则配置 |
| Telemetry | `handler/telemetry.go` | 遥测列表、指标、最新值、历史趋势 |
| Alarms | `handler/alarm.go` | 告警生成、确认、解除、查询 |
| AlarmClip | `handler/alarm_clip.go` | 告警关联视频片段 |
| Control | `handler/control.go` | MQTT 控制命令下发 |
| Notification | `handler/notification.go` | Redis 站内通知 |
| Video Camera | `handler/video_camera.go` | 摄像头管理、WVP 状态同步 |
| Video Stream | `handler/video_stream.go` | 实时点播、FLV 代理 |
| Video Record | `handler/video_record.go` | 录制启停、活跃录制查询 |
| Video Clip | `handler/video_clip.go` | 历史录像片段查询、播放、下载 |
| Storage | `handler/storage.go` | S3 存储管理 |
| Permission | `handler/permission.go` | 权限码查询、角色权限查询 |
| Audit | `handler/audit.go` | 审计日志（权限码 `audit:read`） |
| Health | `handler/health.go` | PostgreSQL、Redis、IoTDB 健康检查 |
| WebSocket | `ws/gateway.go` | `/ws` 实时通道，广播遥测与告警 |

## 6. 前端页面

### 6.1 Web 后台

| 路由 | 页面 | 权限码 |
|---|---|---|
| `/login` | 登录 | - |
| `/dashboard` | 仪表盘 | `dashboard:view` |
| `/houses` | 蚕房管理 | `room:read` |
| `/devices` | 设备管理 | `device:read` |
| `/energy` | 能耗管理 | `energy:view` |
| `/control` | 设备控制 | `device:control` |
| `/ir` | 红外遥控 | `device:control` |
| `/thresholds` | 阈值配置 | `threshold:read` |
| `/alerts` | 告警中心 | `alarm:read` |
| `/videos` | 视频监控 | `video:read` |
| `/logs` | 控制日志 | `log:read` |

### 6.2 移动端 APP / 微信小程序

底部 Tab：仪表盘、蚕房、设备、告警、视频

| 页面 | 功能 |
|---|---|
| 登录 | 用户登录，JWT 持久化 |
| 仪表盘 | 环境概览、趋势图、告警概况 |
| 蚕房 | 蚕房列表与详情 |
| 设备 | 设备列表、状态、控制命令下发 |
| 告警 | 告警列表、确认、解除 |
| 视频 | 摄像头列表、实时播放、历史回看 |
| 设置 | 用户信息、服务器配置、退出登录 |

## 7. 主要 API

后端地址：`http://<服务器IP>:3000/api/v1`

鉴权：除 `GET /health`、`POST /auth/login`、`POST /auth/register` 外，所有接口需 JWT：

```text
Authorization: Bearer <accessToken>
```

| API | 说明 |
|---|---|
| `GET /health` | 健康检查 |
| `POST /auth/register` | 用户注册（默认 viewer） |
| `POST /auth/login` | 用户登录 |
| `GET /auth/me` | 当前用户信息与权限 |
| `GET /permissions` | 全部权限码列表 |
| `GET /permissions/roles` | 角色及权限映射 |
| `GET /users` | 用户列表（`user:manage`） |
| `GET /rooms` / `POST /rooms` / `PATCH /rooms/:id` / `DELETE /rooms/:id` | 蚕房管理 |
| `GET /devices` / `POST /devices` / `PATCH /devices/:id` | 设备管理 |
| `GET /sensors` / `POST /sensors` / `PATCH /sensors/:id` | 传感器管理 |
| `GET /thresholds` / `POST /thresholds` / `PATCH /thresholds/:id` | 阈值管理 |
| `GET /telemetry` | 遥测数据列表 |
| `GET /telemetry/:deviceKey/latest` | 设备最新遥测 |
| `GET /telemetry/:deviceKey/metrics` | 设备可用指标 |
| `GET /telemetry/:deviceKey/:metric/history` | 历史聚合趋势 |
| `GET /alarms` / `GET /alarms/:id` | 告警列表/详情 |
| `POST /alarms/:id/ack` | 确认告警（`alarm:ack`） |
| `POST /alarms/:id/resolve` | 解除告警（`alarm:ack`） |
| `POST /control/send` | 单设备控制（`device:control`） |
| `POST /control/batch` | 批量控制（`device:control`） |
| `GET /video/cameras` / `POST /video/cameras` | 摄像头列表/新增 |
| `GET /video/cameras/:id/live/proxy` | 实时 FLV 流代理 |
| `GET /video/cameras/:id/playback` | 历史录像片段查询 |
| `POST /video/cameras/:id/record/start` | 启动录制（`video:record`） |
| `POST /video/cameras/:id/record/stop` | 停止录制（`video:record`） |
| `GET /video/recordings/active` | 活跃录制列表 |
| `GET /notifications` | 站内通知列表 |
| `GET /audit-logs` | 审计日志（`audit:read`） |

## 8. 权限矩阵

| 权限码 | 说明 | admin | operator | viewer | farmer |
|---|---|:---:|:---:|:---:|:---:|
| `dashboard:view` | 看板查看 | ✓ | ✓ | ✓ | ✓ |
| `room:read` | 蚕房查看 | ✓ | ✓ | ✓ | ✓ |
| `room:write` | 蚕房管理 | ✓ | ✓ | - | - |
| `device:read` | 设备查看 | ✓ | ✓ | ✓ | ✓ |
| `device:control` | 设备控制 | ✓ | ✓ | - | ✓ |
| `threshold:read` | 阈值查看 | ✓ | ✓ | ✓ | - |
| `threshold:write` | 阈值管理 | ✓ | ✓ | - | - |
| `alarm:read` | 告警查看 | ✓ | ✓ | ✓ | ✓ |
| `alarm:ack` | 告警确认 | ✓ | ✓ | - | ✓ |
| `video:read` | 视频查看 | ✓ | ✓ | ✓ | ✓ |
| `video:record` | 视频录制 | ✓ | ✓ | - | - |
| `energy:view` | 能耗查看 | ✓ | ✓ | ✓ | ✓ |
| `log:read` | 日志查看 | ✓ | ✓ | - | - |
| `user:manage` | 用户管理 | ✓ | - | - | - |
| `audit:read` | 审计查看 | ✓ | - | - | - |

## 9. MQTT 接口

### 9.1 遥测上行

订阅 Topic：`silk/+/+/+/up/telemetry`

Payload 示例：

```json
{
  "msgId": "msg-1782833925818-1",
  "ts": 1782833925818,
  "metrics": {
    "temperature": 26.8,
    "humidity": 75.2,
    "lux": 320,
    "co2": 820
  }
}
```

### 9.2 控制下行

下行 Topic：`silk/{deviceKey}/down/cmd`

Payload 示例：

```json
{
  "action": "on",
  "value": true,
  "ts": "2026-06-30T10:00:00.000Z"
}
```

## 10. 数据存储

### 10.1 PostgreSQL（业务数据）

保存用户、蚕房、设备、传感器、阈值、告警、摄像头、录像片段、审计日志、权限等业务数据。GORM 自动迁移建表，系统启动时自动初始化权限种子数据。

```env
PG=postgresql://postgres:pan@localhost:5432/silk
```

### 10.2 Apache IoTDB（时序遥测）

保存高频时序遥测数据，后端通过 REST API 写入和查询。

```env
IOTDB_URL=http://localhost:18081
```

IoTDB 路径示例：`root.silk.telemetry.`sensor-001`.temperature`

### 10.3 Valkey/Redis（缓存与通知）

用于权限缓存（5 分钟有效期）、站内通知列表。

### 10.4 Ceph S3（录像存储）

录制片段按 5 分钟分段，每段独立 S3 对象 + DB 记录。

```env
S3_ENDPOINT=http://100.83.103.1:7480
S3_ACCESS_KEY=silk-app
S3_SECRET_KEY=Silk-App-Secret-2026!
S3_BUCKET=silk-video-events
```

## 11. 服务器部署

详细部署流程参见 [部署指南(物理机).md](部署指南(物理机).md)。

### 11.1 服务架构

```text
服务器 (100.83.103.1)
  ├── Go 后端       :3000   API 后端 (Gin)
  ├── 前端静态服务   :5174   Node.js server.cjs
  ├── Go 录制服务    :9090   recorder-go
  ├── PostgreSQL 16  :5432   业务数据库
  ├── IoTDB 2.0.8    :18081  时序数据库
  ├── Valkey         :6379   缓存
  ├── VerneMQ        :1883   MQTT broker
  ├── Ceph RGW       :7480   S3 对象存储
  └── Docker
      ├── WVP        :18080  GB28181 信令
      ├── ZLMediaKit :8081   流媒体
      ├── MySQL      :3306   WVP 数据库
      └── Redis      :6379   WVP 缓存
```

### 11.2 Go 后端编译部署

```powershell
# 交叉编译
cd e:\silk\server-go
$env:GOOS="linux"; $env:GOARCH="amd64"
go build -o server-go-linux ./cmd/server
$env:GOOS=""; $env:GOARCH=""

# 上传 + 启动（使用 sshpass + ConnectTimeout 避免卡死）
C:\msys64\usr\bin\sshpass.exe -p "pan" C:\msys64\usr\bin\scp.exe -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR -o ConnectTimeout=10 e:\silk\server-go\server-go-linux pan@100.83.103.1:/home/pan/silk/server-go/
C:\msys64\usr\bin\sshpass.exe -p "pan" C:\msys64\usr\bin\ssh.exe -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR -o ConnectTimeout=10 pan@100.83.103.1 "fuser -n tcp -k 3000 2>/dev/null; sleep 1; chmod +x /home/pan/silk/server-go/server-go-linux; setsid bash /home/pan/silk/server-go/start.sh </dev/null >/home/pan/silk/server-go/server-go.log 2>&1 &"
```

### 11.3 Go 后端环境变量

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `PG` | `postgresql://postgres:pan@localhost:5432/silk` | PostgreSQL 连接串 |
| `REDIS` | `redis://:pan@localhost:6379` | Valkey/Redis 连接串 |
| `JWT_SECRET` | `silk-secret-please-change-me` | JWT 签名密钥 |
| `JWT_EXPIRES_IN` | `2h` | JWT 有效期 |
| `MQTT` | `mqtt://pan:pan@localhost:1883` | MQTT 连接串 |
| `IOTDB_URL` | `http://127.0.0.1:18081` | IoTDB REST API |
| `WVP_API_BASE` | `http://localhost:18978` | WVP API 地址（生产应为 18080） |
| `ZLM_API_BASE` | `http://100.83.103.1:8081` | ZLMediaKit API |
| `RECORDER_API_BASE` | `http://localhost:9090` | 录制服务地址 |
| `S3_ENDPOINT` | `http://100.83.103.1:7480` | Ceph S3 端点 |
| `S3_ACCESS_KEY` | `silk-app` | S3 Access Key |
| `S3_SECRET_KEY` | `Silk-App-Secret-2026!` | S3 Secret Key |
| `S3_BUCKET` | `silk-video-events` | S3 Bucket |
| `PORT` | `3000` | 监听端口 |
| `DEFAULT_ADMIN_USERNAME` | `admin` | 默认管理员 |
| `DEFAULT_ADMIN_PASSWORD` | `silk@123` | 默认密码 |

## 12. 本地开发

### 12.1 Web 前端

```powershell
cd e:\silk\web
npm install
npm run dev      # 开发模式，端口 5173，代理 /api 到 :3000
npm run build    # 生产构建
```

### 12.2 React Native APP

```powershell
cd e:\silk\app
npm install

# 配置后端地址（.env 文件）
# API_BASE_URL=http://<服务器IP>:3000/api/v1

# 启动 Metro
npx react-native start

# 编译安装 Debug APK
npx react-native run-android

# 编译 Release APK
cd android
.\gradlew.bat assembleRelease
# 输出：android/app/build/outputs/apk/release/app-release.apk
```

### 12.3 微信小程序

```powershell
cd e:\silk\miniapp
npm install

npm run dev:weapp     # 微信小程序开发模式
npm run build:weapp   # 生产构建
npm run dev:h5        # H5 开发模式
npm run build:h5      # H5 生产构建
```

### 12.4 设备模拟器

```powershell
cd e:\silk\tools\simulator
npm install
npm run start
```

### 12.5 默认管理员

```text
用户名：admin
密码：silk@123
```

## 13. Git 注意事项

不要提交依赖目录和本地运行产物。`.gitignore` 应包含：

```gitignore
node_modules/
dist/
*.log
.env
server-go-linux
recorder-go-linux
*.apk
android/app/build/
ios/Pods/
```

如误将 `node_modules` 加入索引：

```powershell
git rm -r --cached server-go web app miniapp tools/simulator
```