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

2026-08-13 17:48:00 +08:00
parent 0c67c2d428
commit 233c0dd0a7
5 changed files with 146 additions and 0 deletions
@@ -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 ... &` 启动。