From 0c3e07e660cd4f9dc7d244e1e46b3c2e291d32ed Mon Sep 17 00:00:00 2001 From: xiangsilian Date: Sat, 15 Aug 2026 00:40:05 +0800 Subject: [PATCH] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E6=9C=AC=E5=9C=B0=E8=81=94?= =?UTF-8?q?=E8=B0=83=E6=8C=87=E5=8D=97=EF=BC=88App=E2=86=94=E5=90=8E?= =?UTF-8?q?=E7=AB=AF=EF=BC=9B=E7=AB=AF=E5=8F=A3=E5=86=B2=E7=AA=81=E6=8F=90?= =?UTF-8?q?=E9=86=92=E4=B8=8E=E7=9C=9F=E6=9C=BA=20baseUrl=20=E9=85=8D?= =?UTF-8?q?=E7=BD=AE=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/本地联调指南.md | 53 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) create mode 100644 docs/本地联调指南.md diff --git a/docs/本地联调指南.md b/docs/本地联调指南.md new file mode 100644 index 0000000..63e395e --- /dev/null +++ b/docs/本地联调指南.md @@ -0,0 +1,53 @@ +# 本地联调指南（App ↔ 后端） + +> 2026-08-15 ｜ 适用：FE 第一批（F1~F4）交付后的真机/模拟器联调 + +## ⚠️ 先看：端口冲突 + +App 的默认 baseUrl 是 `http://127.0.0.1:8000`，但**你这台机器的 8000 端口已被 AutoVideo（voxcpm-tts）长期占用**。因此本地联调请让美搭后端用 **8666** 端口，并在 App 登录页「高级设置」里把服务器地址改成对应值（F1 交付的设置入口）。 + +## 一、启动后端（WSL） + +```bash +wsl -d Ubuntu-22.04 -e bash -c "cd /home/xsl/meida_backend && \ + (nohup .venv/bin/uvicorn apps.api.main:app --host 0.0.0.0 --port 8666 > /tmp/meida-api.log 2>&1 &) && \ + (nohup .venv/bin/celery -A apps.worker.celery_app worker -Q cpu,io --loglevel WARNING > /tmp/meida-worker.log 2>&1 &) && sleep 3 && \ + curl -s http://127.0.0.1:8666/healthz" +``` + +- `--host 0.0.0.0`：真机（USB）需要开发机局域网 IP 可达 +- worker 必须起：报告生成是异步任务，不起 worker 会一直 RUNNING +- 依赖容器：PG(55432)/Redis(56379) 应已在跑（`docker ps` 确认） +- 停止：`wsl -d Ubuntu-22.04 -e bash -c "pkill -f 'uvicorn apps.api'; pkill -f 'celery -A apps.worker'"` + +## 二、App 侧（DevEco Studio） + +1. 打开工程 `G:\meida\app`，点 Run（模拟器或真机） +2. 登录页「高级设置」： + - **模拟器**：`http://127.0.0.1:8666`（WSL2 端口自动转发到 Windows localhost） + - **真机（USB）**：`http://<开发机局域网IP>:8666`（`ipconfig` 查，手机与电脑同 WiFi；防火墙首次会弹允许） +3. 设备标识随便填（记住它——同标识=同账号，配额/报告都挂它下面） + +## 三、可体验的闭环（对齐 FE 第一批） + +1. 登录 → 四 Tab 主界面 +2. 首页「生成我的形象报告」→ 填问卷 → 提交 → 看进度轮询 → **32 维结果页**（约 10~30 秒，含一次真实 LLM 调用） +3. 首页「AI 穿搭顾问」→ 对话（真实 DeepSeek） +4. 「我的」→ 配额卡片（对话/试穿/报告）+ 流水（消耗/退还/奖励） +5. 重复生成报告 → 40920 提示；报告重生成 → 视觉阶段复用（秒出诊断） + +## 四、已知边界（设计使然，不是 bug） + +- 照片是"模拟对象键"输入框——COS 直传等云端开通后替换 +- 空知识库时报告文案会**降级为规则直出**（结果页有黄条标识）——等规则库录入后消失 +- 华为账号/短信登录未接（等 AGC/签名审核）；当前是 dev-token 通道，仅限本地 +- 未配置签名 → 只能模拟器/调试真机跑，发布包要等证书指纹双套配置 + +## 五、快速排障 + +| 症状 | 原因/处理 | +|---|---| +| 登录一直转圈/网络错误 | baseUrl 不对；或后端没起；模拟器记得用 127.0.0.1 | +| 报告一直 RUNNING | worker 没起（第二步的两条 nohup 都要） | +| 401 反复跳登录 | 旧 token 过期属正常自动刷新；若持续，`hdc shell` 清 App 数据重登 | +| 真机连不上 | 防火墙放行 8666；确认手机电脑同网段；后端必须 `--host 0.0.0.0` |