docs: README/部署指南/故障排查记录补全（ai-service、API、权限、踩坑合集）
This commit is contained in:
weijuesen
@@ -338,6 +338,21 @@ Authorization: Bearer <accessToken>
|
||||
| `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 <accessToken>
|
||||
| `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` 应包含：
|
||||
|
||||
@@ -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 安全与界面优化整改
|
||||
|
||||
|
||||
@@ -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`）。
|
||||
|
||||
+46
@@ -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 ... &` 启动。
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user