chore: 初始化仓库基线（AGENTS.md、git 规范、敏感文件排除）

2026-08-10 22:30:53 +08:00
commit 84abf4454c
358 changed files with 75993 additions and 0 deletions
@@ -0,0 +1,493 @@
+# 智慧蚕房环境监测与智能调控系统
+
+面向养蚕场景的环境实时监测、告警通知、设备联动控制与视频监控平台。系统通过 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
+```