314 lines
17 KiB
Markdown
314 lines
17 KiB
Markdown
# 开发交接 —— 换一台开发机继续做（2026-11-02）
|
||
|
||
> **写给**：在新 Windows 机器上接手的人（或未来的 agent）
|
||
> **不涉及**：服务器 / 聚石塔 / SAE 都不用重建，云端资源全部现成可用
|
||
> **上一份**：[HANDOFF-2026-11-01.md](HANDOFF-2026-11-01.md)（那一轮只到「链路打通 + Java MVP」，UI 和真机测肤是这一轮做的）
|
||
|
||
---
|
||
|
||
## 0. 一句话状态
|
||
|
||
**真机全链路已跑通**：淘宝小程序 → 云网关（AppKey 35486228）→ 聚石塔云应用 1me-net → 私网 CLB → SAE `nnn`（只做透传）→ 聚石塔 NAT 出网（EIP `47.92.113.176`）→ `https://1me.xajuzi.com/tb/` → 现有 H5 的 Node 服务 → 旷视 Face++，**三视图拍摄后报告正常返回**。
|
||
|
||
小程序五个页面的 UI 已按 H5 重做（像素级对齐，见下）。剩下的是相机组件验证和一批工程化工作，清单在第 8 节。
|
||
|
||
---
|
||
|
||
## 1. 新机器准备
|
||
|
||
### 1.1 必装
|
||
|
||
| 工具 | 版本 | 用途 |
|
||
|---|---|---|
|
||
| Git | 任意近期版本 | 拉代码 |
|
||
| Node.js | **18+（推荐 20/22）** | `taobao/` 测试、`h5/` 本地跑、零依赖 |
|
||
| JDK | **17** | `backend-java/` 编译与测试 |
|
||
| Maven | 3.9.x | 同上 |
|
||
| 淘宝小程序开发者工具 | 最新 | 真机预览（**模拟器不支持云应用 SDK**） |
|
||
| PowerShell 7（可选） | 7.x | 仓库里的脚本按 pwsh 语法写 |
|
||
|
||
### 1.2 拉代码
|
||
|
||
```powershell
|
||
git clone https://git.xiangsilian.com/xsl/juzi.git
|
||
cd juzi
|
||
```
|
||
|
||
> 远端证书有效期到 2027-01-29；凭据失效时重新配置 Git 凭据管理器。
|
||
|
||
### 1.3 小程序依赖（必做，否则真机报 `Cannot find module`）
|
||
|
||
```powershell
|
||
cd taobao
|
||
npm ci
|
||
```
|
||
|
||
`@tbmp/mp-cloud-sdk` 固定 1.5.10，只有这一个运行期依赖。
|
||
|
||
### 1.4 工具链
|
||
|
||
仓库自带 `tools/env-java.ps1`，查找顺序：仓库内便携工具链 → 环境变量 → PATH。
|
||
|
||
```powershell
|
||
Set-ExecutionPolicy -Scope Process Bypass
|
||
. .\tools\env-java.ps1 # 输出 JAVA_HOME / MAVEN_HOME / java -version
|
||
```
|
||
|
||
- 用系统安装的 JDK 17 + Maven 即可，**不需要**再下便携版
|
||
- 想复原老机器的布局：把 JDK 放 `tools/jdk17/`、Maven 放 `tools/maven/apache-maven-3.9.9/`（这两个目录 gitignore）
|
||
|
||
### 1.5 机密文件 —— **已随仓库提交（测试阶段例外）**
|
||
|
||
> 2026-11-02 决定：测试验证阶段优先「换机不用手工拷贝」，下面两个文件**已入库**。
|
||
> 代价是密钥进入了 git 历史，正式上线前必须按本节末尾的清单清理。
|
||
|
||
| 文件（仓库内相对路径） | 内容 | 用途 | 缺了会怎样 |
|
||
|---|---|---|---|
|
||
| `backend-java/src/main/resources/application-local.yml` | 淘宝 AppKey/AppSecret + `verify-sign` + `mode: forward` + `forward-base` | 打 JAR 时把配置塞进包里（SAE 不需要环境变量） | JAR 没有 AppKey/Secret，`/session` 一定 401；只跑 `/ping`、不部署则不影响 |
|
||
| `reference/facepp-skinanalyze/credentials.env` | `FACEPP_API_KEY` / `FACEPP_API_SECRET` / `FACEPP_SKINANALYZE_URL` | `h5/server.js` 启动时读取旷视凭据 | 本机跑 H5 后端时启动即 `exit(1)`；只做小程序端开发不需要 |
|
||
|
||
克隆下来就都有了，**新机器不需要再手工拷这两个文件**。
|
||
|
||
**唯一还要自己配的是 SSH 密钥**（用于部署 Node 侧、看日志、跑 `deploy/` 里的脚本）：
|
||
|
||
```powershell
|
||
ssh-keygen -t ed25519 -C "dev@newmachine"
|
||
# 把 ~/.ssh/id_ed25519.pub 内容追加到服务器 ~/.ssh/authorized_keys
|
||
ssh ubuntu@1me.xajuzi.com "systemctl is-active juzi-taobao"
|
||
```
|
||
|
||
**共享仓库的约束**（`.gitignore` 里也写了）：
|
||
|
||
1. 仅限内网私有仓库 `git.xiangsilian.com/xsl/juzi`，**不要 fork 到公开仓库 / 推送到 GitHub**；
|
||
2. 不要把这些值复制到聊天、文档、工单、issue；
|
||
3. 正式上线前必须做三件事（列在待办第 6 项）：
|
||
- 在开放平台**重置** AppSecret、在旷视控制台**重置** API Key
|
||
- 用 `git filter-repo` 把这两个文件从历史里清除，并 `push --force`
|
||
- 改回「环境变量 / 保密字典 / KMS」注入（`application.yml` 里已经支持 `TAOBAO_*` 与 Spring 占位符）
|
||
|
||
|
||
### 1.6 淘宝 IDE 的一个已知坑（Windows）
|
||
|
||
老机器上 IDE 曾因 `wmic` 缺失打不开，用 `tools/fix-taobao-ide-wmic.ps1` 生成过一个 shim（`C:\Users\<你>\.local\bin\wmic.cmd`）。新机器如果 IDE 报 `install miniapp extension fail: ... wmic ...`，跑这个脚本。
|
||
|
||
---
|
||
|
||
## 2. 仓库地图
|
||
|
||
```
|
||
juzi/
|
||
├── taobao/ 淘宝小程序（当前主战场）
|
||
│ ├── config.js ★ 环境/传输配置（cloud+tower+test、assetBase）
|
||
│ ├── app.acss ★ 全局设计 token（对齐 H5 的 .btn-primary/.card/.chev/.popup）
|
||
│ ├── pages/
|
||
│ │ ├── splash/ 启动页（登录、隐私弹窗、开发版入口）
|
||
│ │ ├── profile/ 档案填写（出生/性别/地区/肤质轮播）
|
||
│ │ ├── camera/ 拍照页（蒙版取景 or 系统相机兜底）
|
||
│ │ ├── report/ 报告页（环形分、7 视角、叠加层、标记点）
|
||
│ │ ├── history/ 历史报告
|
||
│ │ ├── mvp/ 连通性调试页（ping/whoami/echo）
|
||
│ │ └── camtest/ ★ 相机组件冒烟页（只放 <camera>，判断组件是否可用）
|
||
│ ├── utils/
|
||
│ │ ├── transport.js 云网关/direct 两种传输 + 信封解包
|
||
│ │ ├── api.js 9 个接口封装（challenge/session/me/photo/skin-analyze/…）
|
||
│ │ ├── permissions.js ★ 权限（scope 前缀、诊断 diagnose()）
|
||
│ │ ├── image.js 1280 长边 + JPEG q0.88 压缩
|
||
│ │ ├── voice.js 语音播报（异常静默）
|
||
│ │ └── report-model.js payload → 报告页 data
|
||
│ └── test/ 20 个 node:test 用例
|
||
├── h5/ ★ 真正的测肤后端（Node，零依赖）
|
||
│ ├── server.js 入口：Face++ 调用、评分、报告、admin
|
||
│ ├── lib/taobao-*.js ★ 淘宝云网关路由/验签/会话（关键算法在这里）
|
||
│ ├── js/skin-score.js 评分引擎（6 类 → 3 维，4:3:3 加权）
|
||
│ └── test/ 一堆独立测试脚本（没有统一 runner）
|
||
├── backend-java/ SAE 上的透传层（Spring Boot 3.5.6 / Java 17）
|
||
│ ├── src/main/java/com/juzi/mvp/api/
|
||
│ │ ├── TaobaoForwardController.java ★ mode=forward 时字节级透传
|
||
│ │ ├── TaobaoEnvelope.java 客户端要的 data.ok + data.http_status
|
||
│ │ ├── TaobaoAuthController.java native 模式的登录接口（当前未启用）
|
||
│ │ └── TaobaoSessionService.java challenge + Bearer token
|
||
│ └── src/main/java/com/juzi/mvp/gateway/TaobaoSignatureVerifier.java 验签算法
|
||
├── deploy/ ★ 服务器侧配置（systemd / nginx / 安装脚本）
|
||
├── docs/ 交接与实施文档（本文件所在）
|
||
└── tools/ 构建与素材脚本
|
||
```
|
||
|
||
---
|
||
|
||
## 3. 三套测试
|
||
|
||
```powershell
|
||
# 1) 小程序：20 个用例
|
||
cd taobao ; npm test
|
||
|
||
# 2) Java：11 个用例（含验签向量的回归测试）
|
||
cd backend-java ; mvn test
|
||
|
||
# 3) H5 单测（独立脚本，逐个跑）
|
||
node h5/test/taobao-auth.js # 网关签名，必须 PASS
|
||
```
|
||
|
||
**改动提交前请保证**：`taobao` 20/20 + `backend-java` 11/11。老机器最后一次全绿是在 `fed5293`。
|
||
|
||
> `taobao/test/frontend.test.cjs` 会用 vm 真跑页面 JS，页面 data 字段改名要同步改测试。
|
||
|
||
---
|
||
|
||
## 4. 本地怎么跑
|
||
|
||
### 4.1 H5 后端（Node，测肤真正的实现）
|
||
|
||
```powershell
|
||
cd h5
|
||
$env:PORT=8099 ; $env:HOST='127.0.0.1' ; $env:JUZI_ENTRY_MODE='state'
|
||
$env:JUZI_DATA_ROOT='..\temp\h5-data'
|
||
node server.js
|
||
# http://127.0.0.1:8099/api/health → {"ok":true}
|
||
```
|
||
|
||
启动时缺旷视 key 会直接退出。只想调 UI/接口时给假值即可（真实检测会失败，但路由可用）：
|
||
|
||
```powershell
|
||
$env:SKIN_API_KEY='dummy' ; $env:SKIN_API_SECRET='dummy'
|
||
```
|
||
|
||
### 4.2 Java（SAE 那一层）
|
||
|
||
```powershell
|
||
. .\tools\env-java.ps1
|
||
cd backend-java
|
||
mvn spring-boot:run # 或 mvn -DskipTests package 后 java -jar target\*.jar
|
||
curl.exe -X POST -H "Content-Type: application/json" -d "{}" http://127.0.0.1:8080/api/taobao/ping
|
||
```
|
||
|
||
- 默认 `mode: native`（Java 自己实现登录，便于单独调接口）
|
||
- 部署用的 `application-local.yml` 里写的是 `mode: forward`
|
||
- 本地想看透传：`$env:TAOBAO_MODE='forward'` + `$env:TAOBAO_FORWARD_BASE='http://127.0.0.1:8099'`
|
||
|
||
### 4.3 小程序
|
||
|
||
1. 淘宝 IDE 导入仓库里的 `taobao/`（`mini.project.json` 的 `appid` 留空，以 IDE 账号为准）
|
||
2. **确认 IDE 当前小程序是 35486228（`1'me 肌肤状态检测`）**
|
||
3. `config.js` 保持 `transport: 'cloud'` / `cloudType: 'tower'` / `cloudEnv: 'test'`
|
||
4. 顶部「预览」→ **手机淘宝扫码**（模拟器不支持 `cloud.application.httpRequest`）
|
||
5. 启动页右上角有三个**开发版入口**（`environment !== 'production'` 时才显示）：
|
||
|
||
| 入口 | 作用 |
|
||
|---|---|
|
||
| 权限诊断 | 打印 `my.canIUse`、`getSetting` 的 authSetting、`authorize` 的原始返回（真机上唯一能看到这些的地方） |
|
||
| 相机组件测试 | 整页只有一个 `<camera>`，用来判断组件是否可用 |
|
||
| SAE MVP 连通性 | `ping/whoami/echo`，看 `transport:"gateway"`、`server:"java"` |
|
||
|
||
---
|
||
|
||
## 5. 云端资源（只读，无需重建）
|
||
|
||
| 资源 | 值 |
|
||
|---|---|
|
||
| 开放平台应用 | `1'me 肌肤状态检测`，AppKey **35486228** |
|
||
| 旧应用（废弃） | `1'me肌肤检测` 35479221 —— **不要再用它的 Secret** |
|
||
| 聚石塔云应用 | `1me-net`，ID **62829**，默认应用 |
|
||
| 私网 CLB | `lb-k2j324dwux1svaf2akwqx` / `192.168.65.185:80` |
|
||
| SAE 应用 | `nnn`，`cn-zhangjiakou:my-namespace` |
|
||
| 代码包 | `taobao-mvp-backend-0.0.4-forward.jar`（**环境变量全空**，配置都在包里） |
|
||
| VPC / vSwitch | `vpc-8vb5mcvenp8jwa1roqcsa` / `vsw-8vbna5zb2rq03gaeiymch`（可用区 A） |
|
||
| NAT 出口 EIP | **47.92.113.176**（nginx `/tb/` 白名单按它放行） |
|
||
| 服务器 | `ubuntu@1me.xajuzi.com`，Node v20.20.2 |
|
||
| 生产 H5 | `https://1me.xajuzi.com/state/` → `juzi-h5.service`（8080） |
|
||
| 红书渠道 | `https://1me.xajuzi.com/rednote/` → `juzi-rednote.service`（8081） |
|
||
| 淘宝专用 | `https://1me.xajuzi.com/tb/` → `juzi-taobao.service`（18081） |
|
||
|
||
---
|
||
|
||
## 6. 改完怎么上线
|
||
|
||
### 6.1 小程序
|
||
IDE 编译 → 预览（自测）→ 「上传」发版本。**不需要碰服务器。**
|
||
|
||
### 6.2 Java（SAE）
|
||
```powershell
|
||
. .\tools\env-java.ps1 ; cd backend-java
|
||
mvn clean package # 测试会自动跑
|
||
# 产物 target\taobao-mvp-backend-0.0.4-forward.jar
|
||
```
|
||
SAE 控制台 → `nnn` → 部署应用 → 代码包部署 → 上传 JAR（**版本号要和上次不同**，否则会被当成同一个版本）→ 环境变量保持全空。
|
||
|
||
### 6.3 Node（`/tb` 实例）
|
||
见 [deploy/README.md](../deploy/README.md) 第 1 节。核心三步：
|
||
|
||
```powershell
|
||
tar -czf temp/juzi-h5.tgz --exclude=h5/data --exclude=h5/test -C . h5
|
||
scp temp/juzi-h5.tgz ubuntu@1me.xajuzi.com:/tmp/
|
||
```
|
||
```bash
|
||
ssh ubuntu@1me.xajuzi.com "tar -xzf /tmp/juzi-h5.tgz -C /home/ubuntu/juzi-tb && sudo systemctl restart juzi-taobao"
|
||
```
|
||
|
||
> ⚠️ **不要动** `/home/ubuntu/juzi`（生产 H5）和 `/home/ubuntu/juzi-rednote`。我们那份是独立拷贝 `/home/ubuntu/juzi-tb`。
|
||
|
||
---
|
||
|
||
## 7. 这一轮的关键结论（踩过的坑，别重复踩）
|
||
|
||
1. **云网关签名算法**：真实请求**不带 `sign_method`**，缺省等价于 `MD5(secret + content + secret)`（`content` = 排序后的 `key+value` 拼接 + **原始 body 字节**）。之前按 `MD5(content + secret)` 实现，是 10 月底那个「signature mismatch」的真因。改在 [h5/lib/taobao-auth.js](../h5/lib/taobao-auth.js)。
|
||
2. **淘宝的 scope 是带前缀的** `scope.camera` / `scope.album`；传裸名 `camera` 返回 `{"errorCode":"5022","errorMessage":"Scope:camera信息不存在"}`。
|
||
3. **`<camera>` 组件在真机上会让整页崩溃**，且 `my.canIUse('camera')` 返回 `yes` 是**假阳性**。当前默认走系统相机（`config.nativeCamera = false`）。怀疑原因是相机里嵌了**微信专有的 `<cover-view>`**，已改成兄弟节点 + 普通 view 覆盖，并加了 `pages/camtest` 冒烟页——**这个还没在真机验证，是新机器的第一件事**。
|
||
4. **网关限制**：单请求 **10 秒 / 128KB**。所以 `skin-analyze` 必须 **202 + 1 秒轮询（最长 90 秒）**，不能同步等旷视。
|
||
5. **旷视 Face++**：正式 key 有并发窗口，必须**串行 + 4 秒间隔**；60 秒超时，失败/5xx/并发超限重试 1 次；返回值含 `face_maps`，4000px 素材时约 3.2MB（真实链路客户端压到 1280，约 200–300KB）。
|
||
6. **`/api/taobao/reports` 详情带 3 张 base64 照片**，历史报告页有超时风险（网关大响应未验证）。
|
||
7. **会话/任务全在内存**：SAE 只能单副本；`juzi-taobao` 重启后登录态与进行中的任务都会丢。
|
||
8. **没有任何清理策略**：每次检测在磁盘留 10–12MB，长期必须换 OSS。
|
||
9. **转发必须字节级透传**：签名覆盖原始 body 和 query，Java 一旦重新序列化 JSON 就会 401。
|
||
10. **生产那台 Node 是旧代码**，没有 `/api/taobao/*`；我们另外起 `/home/ubuntu/juzi-tb`（18081）跑新代码，用 nginx `/tb/` 分流。
|
||
11. **图片资源**走 `https://1me.xajuzi.com/state/assets/`（`config.assetBase`）。之前是 `127.0.0.1:18180`，真机上全部加载失败。
|
||
|
||
---
|
||
|
||
## 8. 待办（建议顺序）
|
||
|
||
| # | 事项 | 说明 |
|
||
|---|---|---|
|
||
| 1 | **真机验证 `pages/camtest`** | 能出实时画面 → 把 `config.nativeCamera` 改 `true`，拍照页立刻有蒙版取景；仍然崩 → 维持系统相机 |
|
||
| 2 | `/reports` 详情瘦身 | 现在透传 3 张 base64 原图（约 0.5MB+），改缩略图或 OSS URL |
|
||
| 3 | 存储工程化 | 照片/原始 JSON/记录 → OSS + RDS；现在全在容器/单机磁盘，无清理 |
|
||
| 4 | 旷视请求裁剪 | `return_maps` 请求 10 层但报告只用 6 层，可少传 4 层省带宽与落盘 |
|
||
| 5 | WebP 转码（可选） | 实测：6 层图 WebP q80 省 54%，叠 50% 缩放省 84%；**先真机验证 `<image>` 支持 WebP data URL** |
|
||
| 6 | 密钥治理（**上线前必做**） | 两个密钥文件目前随仓库提交（见 1.5）。上线前：重置 AppSecret 与旷视 Key → `git filter-repo` 从历史清除 → 改回环境变量/保密字典；服务器 `/etc/juzi/taobao.env` 与 JAR 内嵌 Secret 一并处理 |
|
||
| 7 | Java 端可选迁移 | `mode=native` 的登录接口已写好并测过（4 个用例），可把 auth 从 Node 搬到 Java；测肤仍留在 Node |
|
||
| 8 | 仓库收拾 | `sdk-java-35479221/`、三个 `.pptx`、`tools/build_taobao_proposal_*.py` 仍未跟踪，建议加 ignore 或删除 |
|
||
| 9 | 启用签名校验（Java 侧） | 当前 forward 模式下由 Node 验签；若切 `native` 或要 `/ping` 也验签，把 `verify-sign` 打开即可（算法已修复） |
|
||
|
||
---
|
||
|
||
## 9. 故障对照表
|
||
|
||
| 现象 | 原因 | 处理 |
|
||
|---|---|---|
|
||
| 真机 `cloud init failed` | IDE 当前 app 不是 35486228 / 云应用没设默认 | 确认 IDE 账号与 AppKey |
|
||
| `淘宝身份校验失败，请重新授权登录` | 云网关签名不匹配 | 检查服务器 `/etc/juzi/taobao.env` 的 AppSecret；算法见第 7 节第 1 条 |
|
||
| `请先配置淘宝云应用和 HTTPS 服务地址` | `cloudType` 不是 `tower` 或 `transport` 不是 `cloud` | 看 `config.js` |
|
||
| 页面一片灰没有图 | `assetBase` 指向 127.0.0.1 | 应为 `https://1me.xajuzi.com/state/assets/` |
|
||
| 点拍照整页崩（「系统遇到一点问题」） | `<camera>` 组件 | 保持 `nativeCamera: false`，用系统相机/相册 |
|
||
| 报告页白屏 | `payload` 为空或 `report-model` 抛错 | 看启动页「SAE MVP 连通性」是否 `server:"java"` |
|
||
| SAE 侧 `上游 403` | 容器出口 IP 不在 nginx `/tb/` 白名单 | `curl -s https://myip.ipip.net` 取新 IP，改 nginx 后 reload |
|
||
| `Cannot find module '@tbmp/mp-cloud-sdk'` | 没装依赖 / IDE 没构建 npm | `npm ci`，IDE「工具 → 构建 npm」 |
|
||
| Java 打包报找不到 `application-local.yml` | 机密文件没拷过来 | 见 1.5 |
|
||
|
||
---
|
||
|
||
## 10. 交接检查清单
|
||
|
||
- [ ] `npm ci`（taobao）跑过
|
||
- [ ] `tools/env-java.ps1` 能加载出 JDK17 + Maven
|
||
- [ ] `application-local.yml` 与 `credentials.env` 已在仓库里（clone 即有，无需手拷）
|
||
- [ ] `taobao` 20/20、`backend-java` 11/11、`node h5/test/taobao-auth.js` PASS
|
||
- [ ] IDE 打开 `taobao/` 并确认 AppKey 是 35486228
|
||
- [ ] 真机预览能看到图片（说明资产域名通）
|
||
- [ ] 真机点「权限诊断」→ `authorize(scope.camera)=ok`
|
||
- [ ] 真机点「相机组件测试」→ 记录结果，决定 `nativeCamera` 开关
|
||
- [ ] 能 `ssh ubuntu@1me.xajuzi.com`，`systemctl is-active juzi-taobao` 为 active
|
||
|
||
---
|
||
|
||
**给接手者的第一句话**：先按第 1 节把机器装好、把两个机密文件拷过来，跑通三套测试；然后去真机验 `camtest`——那是唯一还悬着的技术问题，也决定拍照页最终形态。
|