silk/README.md

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

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

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

> **最新进度**：AI 巡检闭环、知识库、分子检测、专家会诊、疫病溯源、天气预警、健康画像等已完成，详见根目录 `AGENTS.md`「已完成功能（截至 2026-08-13）」与 `开发交接记录.md`。

## 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`（养殖员）
- 36 个权限码：基础看板/蚕房/设备/阈值/告警/视频/能耗/日志/用户/审计，并扩展知识库、巡检、蚕匾批次、分子检测、耗材、会诊、溯源、天气、订阅等
- 后端 `RequirePermission` 中间件校验权限码，admin 自动放行
- 前端路由守卫 + 菜单动态过滤 + `<HasPermission>` 按钮级控制
- 新用户注册默认角色为 `viewer`

### 1.6 通知与实时推送

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

### 1.7 能耗管理

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

### 1.8 蚕匾 / 批次 / 饲养记录（计划 #7）

- 蚕匾（`trays`）、蚕种批次（`batches`，含品种/蚕种来源/批次号/检疫证明/龄期/入房/上蔟）、饲养记录（`rearing_records`）三表 + CRUD
- Web「批次管理」页（批次 + 蚕匾 + 饲养记录）；小程序蚕房详情展示蚕匾与当前批次

### 1.9 AI 拍照巡检闭环（计划 #5/#6/#8/#9）

- `ai-service/`：FastAPI + ONNX Runtime（默认 mock 模式；`POST /detect` 返回框/类别/置信度，`POST /stream-detect` 拉流抽帧骨架，`GET /metrics` 监控指标）
- 拍照上传 → AI 检测 → 风险评分（0-100 分，绿/黄/橙/红四级）→ 巡检记录（`inspection_records`，`Idempotency-Key` 幂等）
- 小程序「拍照巡检」页；Web「巡检记录」页（技术员复查）

### 1.10 知识库与阶段风险提示（计划 #10/#13）

- 蚕病百科（9 病种 + 「其它/未知」）、AI 风险分级解读、LAMP/SERS 教程、四季防控提醒
- 症状图谱图片上传（S3 `silk-images`）；饲养阶段风险提示（`/knowledge/stage-hints`）
- Web「知识库」页 + 小程序知识库（列表/详情/阶段选择）

### 1.11 分子检测与交叉验证（计划 #14/#15/#19/#20）

- LAMP 检测任务单 + 标准 5 步流程 + 结果照片 + 结果录入
- qPCR Ct 值自动判读（阈值可配）；SERS 光谱数据上传与光谱库；高光谱方式预留
- 交叉验证：AI 结果 vs 检测结果（一致→确认诊断；不一致→建议专家会诊）
- 多检测方式推荐引擎（设备条件/紧急程度/操作者水平/成本偏好）
- Web「分子检测」页 + 小程序 LAMP 录入

### 1.12 专家会诊（计划 #18）

- 会诊单 + 病例快照（照片/AI/检测/环境/批次/天气）+ 状态机（受理/出方案/归档）+ 专家意见与防控方案
- Web「专家会诊」页

### 1.13 疫病溯源与区域统计（计划 #21/#22）

- 三级溯源：一级自动（环境回溯/历史关联/传播推断→初报）、二级分病种排查清单（→分析报告）、三级专家/实验室记录
- 区域发病统计（按蚕房区域聚合，柱状图/饼图）与年度发病规律
- Web「疫病溯源」页

### 1.14 耗材管理（计划 #16）

- 耗材库存、低库存/临期预警、采购建议（补足安全阈值）
- Web「耗材管理」页

### 1.15 天气与高发病预警（计划 #12）

- 和风天气接入（实时 + 3 天预报）；按规格书 3.2.3 规则评估白僵病/核型多角体病/软化病风险
- 定时（30 分钟）评估写入 `weather_alerts`；Web 告警中心与小程序告警页展示

### 1.16 蚕房健康画像与年度发病规律（计划 #24）

- 单蚕房健康分（0-100）与评级（优/良/中/差）：聚合巡检风险、检测结果、会诊/溯源事件
- Web 蚕房「健康画像」抽屉 + 年度发病折线图

### 1.17 微信订阅消息（计划 #11，骨架）

- 用户 openid 绑定与订阅授权（`/wechat/bind|subscribe`）；巡检风险非绿异步触发
- 真实推送需配置 `WECHAT_APPID/SECRET/TEMPLATE_*` 并申请订阅消息模板

## 2. 技术架构

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

## 3. 技术栈

| 层级 | 技术 |
|---|---|
| Go 后端 | Go 1.23、Gin、GORM、JWT、slog、WebSocket |
| 录制服务 | Go、AWS SDK v2（S3）、HTTP 拉流 |
| Web 前端 | React 18、Vite、Ant Design、Ant Design Pro、Axios、ECharts、Vitest |
| 移动端 APP | React Native 0.74、React Navigation、React Native Paper、Zustand |
| 微信小程序 | Taro 4、React、TypeScript、SCSS |
| 业务数据库 | PostgreSQL（开发服务器为 14） |
| 时序数据库 | Apache IoTDB 2.0.8（REST API） |
| AI 推理服务 | Python 3.10+、FastAPI、ONNX Runtime、OpenCV（`ai-service/`） |
| 缓存/通知 | Redis / 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
├─ ai-service/                     # Python AI 推理服务（FastAPI + ONNX Runtime，端口 8000）
│  ├─ app/                         # main.py（/health、/detect、/stream-detect、/metrics）
│  ├─ tests/                       # pytest 用例
│  └─ requirements.txt
├─ 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 健康检查 |
| Knowledge | `handler/knowledge.go` | 知识库（蚕病百科/文章/阶段提示/图片上传） |
| Inspection | `handler/inspection.go` | AI 巡检记录（上传→检测→评分，幂等） |
| TrayBatch | `handler/tray_batch.go` | 蚕匾/批次/饲养记录 CRUD |
| Lamp | `handler/lamp.go` | 分子检测（LAMP/qPCR/SERS）、步骤、光谱库 |
| Weather | `handler/weather.go` | 和风天气与高发病天气预警 |
| Wechat | `handler/wechat.go` | 微信订阅消息绑定与授权 |
| Consultation | `handler/consultation.go` | 专家会诊（病例快照/意见/方案） |
| Trace | `handler/trace.go` | 疫病溯源（三级）、区域/月度发病统计 |
| HealthProfile | `handler/health.go` | 蚕房健康画像（健康分/评级） |
| DetectionMethod | `handler/detection_method.go` | 多检测方式推荐 |
| Consumable | `handler/consumable.go` | 耗材库存、预警与采购建议 |
| 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`） |
| `GET /knowledge/diseases` / `GET/POST/PATCH/DELETE /knowledge/diseases/:id` | 蚕病百科 |
| `GET /knowledge/articles` / `GET/POST/PATCH/DELETE /knowledge/articles/:id` | 知识文章（AI 解读/LAMP/SERS/季节提醒） |
| `GET /knowledge/stage-hints` | 饲养阶段风险提示 |
| `POST /knowledge/images` | 知识库图片上传（`knowledge:write`） |
| `POST/GET /inspections` | AI 巡检创建/列表（`Idempotency-Key` 幂等） |
| `GET/POST/PATCH/DELETE /trays`、`/batches`、`/rearing-records` | 蚕匾/批次/饲养记录 |
| `GET/POST/PATCH/DELETE /lamp-tests(/:id)` | 分子检测任务单（含步骤/结果照片/judge-qpcr/spectrum/cross-validation） |
| `GET/POST/DELETE /spectrum-entries` | SERS 光谱库 |
| `GET /weather/now`、`GET /weather/alerts` | 天气与高发病预警 |
| `GET/POST /wechat/binding`、`/wechat/bind`、`/wechat/subscribe` | 微信订阅绑定/授权 |
| `GET/POST/PATCH /consultations(/:id)`、`/:id/resolve`、`/:id/archive` | 专家会诊 |
| `GET/POST/PATCH/DELETE /trace-records(/:id)`、`/:id/auto`、`/:id/checklist`、`/region-stats`、`/monthly-stats` | 疫病溯源与区域/月度统计 |
| `GET /health-profiles/:roomId` | 蚕房健康画像 |
| `GET /detection-methods/recommend` | 多检测方式推荐 |
| `GET/POST/PATCH/DELETE /consumables`、`/consumables/alerts`、`/consumables/purchase-suggestions` | 耗材管理 |

## 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` | 日志查看 | ✓ | ✓ | - | - |
| `knowledge:read` | 知识库查看 | ✓ | ✓ | ✓ | ✓ |
| `knowledge:write` | 知识库管理 | ✓ | ✓ | - | - |
| `inspection:create` | 巡检创建 | ✓ | ✓ | - | ✓ |
| `inspection:read` | 巡检查看 | ✓ | ✓ | ✓ | ✓ |
| `tray:read/write` | 蚕匾查看/管理 | ✓ | ✓ | 读 | 读 |
| `batch:read/write` | 批次查看/管理 | ✓ | ✓ | 读 | 读 |
| `rearing:read/write` | 饲养记录查看/管理 | ✓ | ✓ | 读 | 读 |
| `notification:read/write` | 订阅查看/管理 | ✓ | ✓ | 读 | 读写 |
| `weather:read` | 天气查看 | ✓ | ✓ | ✓ | ✓ |
| `lamp:read/write` | LAMP 检测查看/管理 | ✓ | ✓ | 读 | 读 |
| `consumable:read/write` | 耗材查看/管理 | ✓ | ✓ | 读 | 读 |
| `consultation:read/write` | 会诊查看/管理 | ✓ | ✓ | 读 | 读 |
| `trace:read/write` | 溯源查看/管理 | ✓ | ✓ | 读 | 读 |
| `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（业务数据）

保存用户、蚕房、设备、传感器、阈值、告警、摄像头、录像片段、审计日志、权限等业务数据。系统启动时先执行 `server-go/migrations/` 下的版本化 SQL 迁移，再初始化权限种子数据；生产环境禁用 AutoMigrate。

```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 连接串 |
| `APP_ENV` | `development` | 运行环境；生产环境应设为 `production` |
| `ALLOW_DEV_AUTOMIGRATE` | `false` | 仅开发环境可显式开启 AutoMigrate，生产忽略此开关 |
| `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 |
| `S3_BUCKET_IMAGES` | `silk-images` | 知识库/巡检/检测图片桶（对象公开读） |
| `AI_SERVICE_BASE` | `http://localhost:8000` | AI 推理服务地址 |
| `WECHAT_APPID` | （空） | 微信小程序 AppID（订阅消息，占位） |
| `WECHAT_SECRET` | （空） | 微信小程序 AppSecret（占位） |
| `WECHAT_TEMPLATE_ALARM` / `WECHAT_TEMPLATE_INSPECTION` | （空） | 订阅消息模板 ID（占位） |
| `QWEATHER_API_KEY` / `QWEATHER_LOCATION` | （空） | 和风天气 Key 与位置（经纬度或 LocationID，占位） |
| `QWEATHER_INTERVAL_MIN` | `30` | 天气预警定时评估间隔（分钟） |
| `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    # 生产构建
npm test         # Vitest 单元测试
```

### 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
```

### 12.6 ai-service（AI 推理服务）

```powershell
cd e:\silk\ai-service
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt   # Linux: .venv/bin/pip install -r requirements.txt
.venv\Scripts\python -m pytest tests -q          # 单元测试
MODEL_MODE=mock .venv\Scripts\python -m uvicorn app.main:app --host 0.0.0.0 --port 8000
```

- 接口：`GET /health`、`POST /detect`（multipart 图片）、`POST /stream-detect`（摄像头流拉帧骨架）、`GET /metrics`（含 GPU 信息）
- 默认 mock 模式；训练恢复后放 `models/best.onnx` 并设 `MODEL_MODE=onnx`（`MODEL_LABELS` 可配类别）
- 开发服务器部署：`/home/pan/ai-service`（venv + `start.sh`，:8000），服务器 pip 源已配置清华镜像

### 12.7 开发服务器部署摘要

- 部署规则（备份/回滚/冒烟）见根目录 `AGENTS.md`「部署到开发服务器」；SSH/SFTP 工具为 `scripts/devssh.py`（`PAN_SSH_PASS` 环境变量传密码）
- 服务清单：Go 后端 :3000、Web :5174、ai-service :8000、recorder-go :9090、PostgreSQL :5432、IoTDB :18081、VerneMQ :1883、Ceph RGW :7480、WVP :18080、ZLM :8081

## 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
```