docs: README/部署指南/故障排查记录补全（ai-service、API、权限、踩坑合集）

部署指南(物理机).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