|
|
9c6e9c66ad
|
跨端: 修复: 鸿蒙客户端"连不上服务器"—— 地址补 /api/v1 + 失败分类成人话（含网络白名单固化）
症状
鸿蒙客户端（client/harmony）连不上服务端，界面只显示"无法连接"，用户无法自助；
而服务端 HTTPS 完全正常：https://mail.jianfgit.xyz/health → 200、
/api/v1/auth/me → 401、/api/v1/events/stream → 401（Let's Encrypt *.jianfgit.xyz，
TLS 校验通过；代理与直连 http://127.0.0.1:8180 行为一致）。
根因（两条，逐条核实过，其中一条**推翻了原判断**）
① apiBase 是"API 前缀本身"（ApiClient 里拼的是 '/auth/login' 这类相对路径），
而 Ui 只做 trim+去尾斜杠：用户若只填 `https://mail.jianfgit.xyz/`，请求就打到
`https://mail.jianfgit.xyz/auth/login` ⇒ 404，客户端再把它压成"无法连接"。
**这是本次故障最可能的直接原因。**
② 默认值 `http://192.168.2.60:8180/api/v1` 是明文 + 写死内网 IP：手机不在同网段
就永远不通（mail.jianfgit.xyz 解析到的就是这台内网机）。
★ 但"鸿蒙默认禁止明文 HTTP"这条**不成立**，已按本机离线官方文档核实：
`devecocli docs read .../使用HTTP访问网络/http-request` 的《明文HTTP访问权限配置说明》
写明 cleartextTrafficPermitted "默认为 true"，Network Kit 默认允许明文；
另有 FAQ《Stage模型如何配置支持http明文传输》："无需配置，支持HTTP明文传输数据"。
⇒ network_config.json 按"显式固化意图"处理（照文档形状写对，但**不冒充**它是修复）。
本机 SDK @ohos.net.http.d.ts 里确实有 2300997 Cleartext traffic not permitted（since 18），
所以那条错误码在客户端被建成一条可读提示，而不是被忽略。
改法
· 新增 model/ApiBase.ts（纯逻辑，无 @ohos，判据能用 node 直接跑）：
normalizeApiBase（去尾斜杠**但不咬协议 //**、末尾没有 /api/v1 就补、已有的一字不动）、
validateApiBase（自带修法的中文提示 + "公网明文才告警、内网明文不误报"）、
describeFailure（404 自己写文案并点名 /api/v1；其它状态码让服务端文案说话；
网络层按 2300006/2300007/2300028/2300997/2300998/2300058-60-77 分类成人话）。
· Config.ets：DEFAULT_API_BASE → https://mail.jianfgit.xyz/api/v1。
· ApiClient.ets：setBase/init **都**过 normalizeApiBase（唯一闸口 ⇒ 老装机里已经存下的
坏地址在读回时就治好，光改默认值救不了它）；ApiError 带 nativeCode；错误路径改走
describeFailure；404 的提示指向"地址少了 /api/v1"。
· LoginPage.ets：地址先校验后持久化（不合法**不落库**、给可执行提示），明文警告常驻渲染；
SettingsPage.ets：添加账号同样校验（多账号库直接喂 SseService，坏地址会让该账号的实时
通道永久连不上）；AccountManager/SseService 落库与建连时各自再归一化一次。
· 新增 resources/base/profile/network_config.json：按官方文档形状把内网明文
（192.168.2.60 / 10.0.2.2 / localhost）显式列进 domain-config 白名单。
文档给的就是这个**固定路径与文件名**，不需要在 module.json5 里写引用
（仓库里既有的 HomeAgent 工程同样是这么放的）。
· 新增判据 test/harmony-apibase.test.mjs（13 条）并接进 run-all.mjs 的 SUITE：
值判据**直接跑** model/ApiBase.ts；.ets 那几条是**静态**接线判据（本机无设备）。
验证（都真跑过）
· cd client/harmony && devecocli build clean && devecocli build
→ BUILD SUCCESSFUL in 7 s 186 ms；entry/build/default/outputs/default/entry-default-signed.hap
存在（1214592 B，15:14）。
· 解包 HAP：resources/base/profile/network_config.json 在包里、JSON 可解析、
cleartextTrafficPermitted=true 且白名单含 192.168.2.60/10.0.2.2/localhost；
bundleName 仍是 com.jianf.agentmail，module.json 没有多余的 metadata/securityConfiguration。
· devecocli check lint → 0 error；我改过的文件**零发现**（总工性从 8 降到 7，
顺带修掉 LoginPage 一条既有的 await-thenable）。
· node --experimental-strip-types --no-warnings --test test/harmony-apibase.test.mjs
→ ℹ tests 13 / pass 13 / fail 0。
· 变异验证 11/11 全红且**红在对应那条**（在 /tmp 的独立 worktree 里做的，不碰共享树）：
归一化不补后缀、去斜杠咬掉协议、404 用通用文案、401 拿通用文案顶掉服务端原因、
网络码不再分类、默认地址退回明文内网、setBase 直接赋值、登录页去掉守卫、
内网白名单关掉明文、出现第二处自己拼 /api/v1、守卫变成空壳。
（M8 第一次是**假绿**——只判了方法声明、没判调用点；改成切出 doLogin 方法体后再判才红。）
未验到（别把"编译过了"读成"连通了"）
· **没有**在真机/模拟器上点过一次登录：本机当前无设备在线，所以"真的连上了服务端"
这件事本轮**未被验证**；已验证的只是"地址会被补成带 /api/v1 的形态""构建产物正确"。
· network_config.json 的**实际效果**未验：按官方文档明文默认就允许，这份文件是显式固化，
没有做"关掉它再对比"的实验（也无法在无设备时做）。
· DNS/超时/证书这几条分类的文案是按 SDK 错误码写的，**没有构造真人故障去实测**
（即没有真的把 DNS 打坏、把证书换成自签来看提示）。
· 登录页那条"未 /api/v1 会 404"的因果链是从服务端路由 + 客户端拼接方式推出的，
没有用 curl 对 `https://mail.jianfgit.xyz/auth/login` 实打一次取证。
· test/run-all.mjs 在本机（node v24.14.1）**本来就是红的**：它只认 `# pass N`，
而 node 24 打的是 `ℹ pass N` ⇒ 25 个文件里 21 个被记成"没自报条数"。
这是既有环境漂移（已在 HEAD 的 worktree 里复现同样的红），**本次没有动它**，
所以新判据虽然已登记进 SUITE，要等 runner 的 marker 解析修好才会被套件真正计数。
|
2026-09-15 15:15:17 +08:00 |
|
