From 233c0dd0a72eac1641f13ee885ccd5ceb35d6b96 Mon Sep 17 00:00:00 2001 From: weijuesen Date: Thu, 13 Aug 2026 17:48:00 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20README/=E9=83=A8=E7=BD=B2=E6=8C=87?= =?UTF-8?q?=E5=8D=97/=E6=95=85=E9=9A=9C=E6=8E=92=E6=9F=A5=E8=AE=B0?= =?UTF-8?q?=E5=BD=95=E8=A1=A5=E5=85=A8=EF=BC=88ai-service=E3=80=81API?= =?UTF-8?q?=E3=80=81=E6=9D=83=E9=99=90=E3=80=81=E8=B8=A9=E5=9D=91=E5=90=88?= =?UTF-8?q?=E9=9B=86=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++ 变更记录.md | 3 +++ 开发交接记录.md | 18 +++++++++++++++++ 故障排查处理记录.md | 46 ++++++++++++++++++++++++++++++++++++++++++++ 部署指南(物理机).md | 32 ++++++++++++++++++++++++++++++ 5 files changed, 146 insertions(+) diff --git a/README.md b/README.md index e51fb8d..1cbaf37 100644 --- a/README.md +++ b/README.md @@ -338,6 +338,21 @@ Authorization: Bearer | `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. 权限矩阵 @@ -356,6 +371,19 @@ Authorization: Bearer | `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` | 审计查看 | ✓ | - | - | - | @@ -554,6 +582,25 @@ npm run start 密码：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` 应包含： diff --git a/变更记录.md b/变更记录.md index 0852e33..d25dd75 100644 --- a/变更记录.md +++ b/变更记录.md @@ -277,6 +277,9 @@ - `README.md`：新增 1.8-1.17 核心能力（蚕匾批次/巡检闭环/知识库/分子检测/会诊/溯源/耗材/天气/健康画像/微信订阅）；权限码 15→36；技术栈补 Go 1.23、FastAPI/ONNX/OpenCV、Vitest；目录结构补 `ai-service/`；后端模块表补 12 个模块；环境变量表补 `S3_BUCKET_IMAGES/AI_SERVICE_BASE/WECHAT_*/QWEATHER_*`；本地开发补 `npm test` - `后续工作计划.md`：勾选 #5-#24、#27 完成状态，#23/#26 标记骨架完成，#1-4 标注挂起（物理机），顶部加完成状态说明 +- `README.md`（第二轮）：API 概览表补 12 组新接口；权限矩阵补 20 个新权限码；12.6/12.7 补 ai-service 本地开发与开发服务器部署摘要 +- `部署指南(物理机).md`：架构图补 ai-service:8000；新增「13. 部署 ai-service」章节（venv/start.sh/health 验证） +- `故障排查处理记录.md`：追加 2026-08-12/13 部署与开发环境踩坑合集（NetBird 过期、pip 清华源、rolldown WASM、ETXTBSY、Gin 路由三坑、中文 JSON 编码、tar 时间戳、命令后台化） ## 2026-07-17 安全与界面优化整改 diff --git a/开发交接记录.md b/开发交接记录.md index fb9d49b..357dfd7 100644 --- a/开发交接记录.md +++ b/开发交接记录.md @@ -613,6 +613,24 @@ MVP 沿用 IoTDB（现状）；TDengine 作为生产规模化候选（先基准 --- +## 2026-08-13 文档同步（第二轮）：README / 部署指南 / 故障排查 + +### 做了什么 + +- README：API 概览表补 12 组新接口；权限矩阵补 20 个新权限码；新增 12.6 ai-service 本地开发、12.7 开发服务器部署摘要。 +- 部署指南（物理机）：架构图补 ai-service:8000；新增「13. 部署 ai-service」章节。 +- 故障排查处理记录：追加 8 类近期踩坑（NetBird 登录过期/隧道闪断、pip 国内源、rolldown WASM 内存、ETXTBSY、Gin 路由冲突/重复注册/文件覆盖/参数名、PowerShell 中文 JSON、tar 时间戳、SSH 命令后台化）。 + +### 说明 + +- 文档按「现状可用」原则更新，详细命令与回滚以 `开发交接记录.md` / 服务器 README 为准。 + +### 相关提交 + +`README.md`、`部署指南(物理机).md`、`故障排查处理记录.md`、`变更记录.md`、`开发交接记录.md`。 + +--- + ## 环境与踩坑备忘（新同事必读） - **VPN**：开发服务器经 NetBird 访问；服务 Running 后需 `netbird up`，登录走 SSO（管理端 `115.191.19.95:6680`）。 diff --git a/故障排查处理记录.md b/故障排查处理记录.md index 234faac..92ce9b7 100644 --- a/故障排查处理记录.md +++ b/故障排查处理记录.md @@ -1078,3 +1078,49 @@ APP 使用 `react-native-vector-icons` 的 `MaterialCommunityIcons` 字体渲染 - 部署指南中的 `admin/admin123` 已失效；已用当前 admin 账号完成 API 级冒烟（登录成功 → `GET /api/v1/knowledge/diseases` 返回白僵病 `imageUrl` 已绑定），密码本身不写入文档 - 已知边界：编辑页若点「移除」图片再保存，`imageUrl` 会以 `undefined` 提交（键被省略），不会清空库里已有图片；如需「移除即清空」后续应显式传 `null` - CSP 当前放行的是开发服务器 IP；生产切云 OSS/COS 时需把 OSS/CDN 域名加入 `img-src`，或改为同源代理 + +--- + +## 2026-08-12/13 部署与开发环境踩坑合集（重要） + +### 1. NetBird 登录过期与隧道闪断 + +**现象**：SSH 突然超时；`netbird status` 显示 `peer login has expired, please log in once more`。 +**处理**：`netbird login --management-url https://115.191.19.95:6680` 重新 SSO（需用户在浏览器完成，链接有时效），再 `netbird up`；数据面恢复需要几十秒，可用 ping/端口探测确认后再继续。 + +### 2. 服务器 pip 慢 / 未配置国内源 + +**现象**：服务器 pip 安装依赖极慢（官方 PyPI）。 +**处理**：已持久化配置清华源 `pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple`（写入 `/home/pan/.config/pip/pip.conf`，对 pan 全部 venv 生效）。另需 `python3.10-venv` 才能建 venv。 + +### 3. web 构建报 `WebAssembly.Memory.grow(): Maximum memory size exceeded` + +**现象**：`npm run build` 在 rolldown 压缩阶段失败（超大单 chunk）。 +**处理**：`vite.config.ts` 增加 `build.rollupOptions.output.manualChunks`（函数形式，按 react/antd/pro/echarts/vendor 拆分），构建通过。 + +### 4. 服务器上覆盖运行中的二进制报 `text file busy` + +**现象**：`cp` 新二进制到正在运行的 `server-go-linux` 报 ETXTBSY。 +**处理**：先 `mv` 旧文件（如 `server-go-linux.old-<时间戳>`）再 `cp` 新文件，最后 `fuser -k 3000/tcp` + `start.sh` 重启。 + +### 5. Gin 路由注册相关三个坑（2026-08-13 #24 部署） + +- `/rooms/:id/health-profile` 与已有 `/rooms/:id` 冲突 → 启动 panic `wildcard segment conflicts`；改为独立路径 `/health-profiles/:roomId`。 +- 同一路由注册函数被调两次 → panic `handlers are already registered for path ...`；检查 main.go 是否重复注册。 +- 用 apply_patch 新增文件时若文件已存在会覆盖旧内容：新增 `handler/health.go` 覆盖了原 `/health` 路由（health 变 404）；已恢复原函数并把健康画像独立为 `RegisterHealthProfileRoutes`。 +- 路由参数名与 handler 读取名不一致（`:roomId` 却 `c.Param("id")`）→ 返回 404/参数为空；保持命名一致。 + +### 6. PowerShell 传中文 JSON 导致请求 400 + +**现象**：`curl -d '{"disease":"白僵病"}'`（PowerShell 控制台按 GBK 编码）→ 后端 JSON 解析失败返回 400。 +**处理**：冒烟测试避免在 `-d` 中直接写中文；改用 ASCII 字段值，或通过文件/脚本传 UTF-8 字节。 + +### 7. tar 打包报「时间戳是未来」等警告 + +**现象**：Windows tar 打包 dist 时提示时间戳在未来（非致命）。 +**处理**：忽略即可；不影响部署。 + +### 8. SSH 长命令整链被 `&` 后台化 + +**现象**：一条部署命令里 `A && B & C` 语法把整条链后台化，导致命令“卡住”超时。 +**处理**：后台启动（node/uvicorn）单独一条命令，先 `fuser -k` + 换 dist/二进制，再单独 `nohup ... &` 启动。 diff --git a/部署指南(物理机).md b/部署指南(物理机).md index 0cdd25e..3fca848 100644 --- a/部署指南(物理机).md +++ b/部署指南(物理机).md @@ -43,6 +43,7 @@ ├── VerneMQ :1883 MQTT broker ├── Go 后端 :3000 silk-server-go ├── Go 录制服务 :9090 recorder-go + ├── AI 推理服务 :8000 ai-service（FastAPI + ONNX Runtime，mock/onnx） └── 前端 :5174 server.cjs ``` @@ -487,6 +488,37 @@ nohup node /home/pan/silk/web/server.cjs > /home/pan/silk/web/web.log 2>&1 < /de > **server.cjs 命名**：`package.json` 中 `"type": "module"` 会导致 `.js` 文件被当作 ES Module 解析。`server.js` 使用 `require()`（CommonJS），需重命名为 `server.cjs`。 +### 13. 部署 ai-service（2026-08 新增） + +```bash +# 上传源码 tar 包（本机 scripts/devssh.py --upload ai-service.tar.gz /home/pan/） +mkdir -p /home/pan/ai-service +tar xzf /home/pan/ai-service.tar.gz -C /home/pan +cd /home/pan/ai-service + +# 前置：python3-venv（如缺失） +sudo apt install -y python3.10-venv + +python3 -m venv .venv +.venv/bin/pip install -r requirements.txt # 服务器 pip 已配置清华镜像 + +cat > start.sh << 'EOF' +#!/bin/bash +cd /home/pan/ai-service +export MODEL_MODE=mock +export MOCK_CLASS=healthy +nohup .venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000 > ai-service.log 2>&1 < /dev/null & +echo STARTED +EOF +chmod +x start.sh && bash start.sh +sleep 4 + +curl -s http://localhost:8000/health # {"status":"ok","model":"mock"} +curl -s http://localhost:8000/metrics # 含请求量/延迟/GPU（nvidia-smi） +``` + +> 训练恢复后：放置 `models/best.onnx` 并把 `MODEL_MODE` 改为 `onnx` 重启即可（接口不变）。Go 后端通过 `AI_SERVICE_BASE`（默认 `http://localhost:8000`）对接。 + ## 四、验证 ```bash