|
|
@@ -0,0 +1,293 @@
|
|
|
+# 平台侧待办需求(3 项)
|
|
|
+
|
|
|
+> 2026-11-18 整理。**每一项都含可复现证据、根因、修改点、验收命令。**
|
|
|
+> 后台推送经用户裁决**暂不做**,仅记录在案。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 一、多值 CORS:`/api/apig/message` 对 `https://localhost` 返回两个 ACAO 头
|
|
|
+
|
|
|
+### 严重度与状态
|
|
|
+
|
|
|
+| 项 | 内容 |
|
|
|
+|---|---|
|
|
|
+| 严重度 | 🟡 中(App 已用云函数代理绕过,但浏览器直连时失败) |
|
|
|
+| 责任方 | **平台**(网关 / nginx / Express 三者之一重复加头) |
|
|
|
+| 状态 | ❌ **未修复,约 50% 概率触发** |
|
|
|
+
|
|
|
+### 复现(100% 可复现)
|
|
|
+
|
|
|
+```bash
|
|
|
+# 连续请求,约一半会返回 2 个 ACAO 头
|
|
|
+for i in $(seq 1 10); do
|
|
|
+ n=$(curl -sS -I -H "Origin: https://localhost" \
|
|
|
+ "https://server.fmode.cn/api/apig/message" 2>/dev/null \
|
|
|
+ | grep -ci "^access-control-allow-origin")
|
|
|
+ echo "第 $i 次: $n 个"
|
|
|
+done
|
|
|
+```
|
|
|
+
|
|
|
+实测输出(2026-11-18):
|
|
|
+```
|
|
|
+第1次: 1 第2次: 2 ❌ 第3次: 1 第4次: 2 ❌ 第5次: 1
|
|
|
+第6次: 1 第7次: 2 ❌ 第8次: 1 第9次: 2 ❌ 第10次: 2 ❌
|
|
|
+→ 10 次中 5 次异常
|
|
|
+```
|
|
|
+
|
|
|
+### 异常时的完整响应头
|
|
|
+
|
|
|
+```http
|
|
|
+HTTP/1.1 200 OK
|
|
|
+server: nginx
|
|
|
+x-powered-by: Express
|
|
|
+access-control-allow-origin: https://localhost ← ① 某层回显了具体 origin
|
|
|
+x-content-type-options: nosniff
|
|
|
+access-control-allow-origin: * ← ② 另一层又加了 *
|
|
|
+```
|
|
|
+
|
|
|
+**正常时**只有 `access-control-allow-origin: *`。
|
|
|
+
|
|
|
+### 触发条件(重要)
|
|
|
+
|
|
|
+| Origin | 结果 |
|
|
|
+|---|---|
|
|
|
+| `https://ai.fmode.cn` | ✅ 1 个(正常) |
|
|
|
+| `https://fmode.cn` | ✅ 1 个(正常) |
|
|
|
+| **`https://localhost`(App 内 WebView)** | ❌ **约 50% 返回 2 个** |
|
|
|
+
|
|
|
+说明:**某个中间层对「不在白名单的 origin」做了动态回显**,而下游又无条件加了 `*`。
|
|
|
+
|
|
|
+### 根因推断
|
|
|
+
|
|
|
+典型的两层叠加:
|
|
|
+
|
|
|
+```
|
|
|
+nginx / 网关层: if origin not in whitelist → add_header ACAO $http_origin
|
|
|
+Express 层: res.setHeader('Access-Control-Allow-Origin', '*')
|
|
|
+ ↓
|
|
|
+ 两者都输出 → 两个头
|
|
|
+```
|
|
|
+
|
|
|
+### 修改点(二选一)
|
|
|
+
|
|
|
+**方案 A(推荐):把 `https://localhost` 纳入白名单**
|
|
|
+
|
|
|
+在网关/nginx 的 CORS 白名单里加上 `https://localhost`(App 的固定 origin,
|
|
|
+见 `capacitor.config.ts` 锁定 `hostname: localhost` + `scheme: https`)。
|
|
|
+
|
|
|
+但**仍要确保只输出一次** —— 白名单命中后就不应再叠加 `*`。
|
|
|
+
|
|
|
+**方案 B:下游不再无条件加 `*`**
|
|
|
+
|
|
|
+让 Express 信任上游已设置的头,只在**未设置时**才补:
|
|
|
+
|
|
|
+```js
|
|
|
+if (!res.getHeader('Access-Control-Allow-Origin')) {
|
|
|
+ res.setHeader('Access-Control-Allow-Origin', '*');
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+### 验收标准
|
|
|
+
|
|
|
+```bash
|
|
|
+# 期望:10 次全部输出 1
|
|
|
+for i in $(seq 1 10); do
|
|
|
+ n=$(curl -sS -I -H "Origin: https://localhost" \
|
|
|
+ "https://server.fmode.cn/api/apig/message" 2>/dev/null \
|
|
|
+ | grep -ci "^access-control-allow-origin")
|
|
|
+ [ "$n" -eq 1 ] || echo "❌ 第 $i 次: $n 个"
|
|
|
+done
|
|
|
+echo "全部通过(无 ❌ 输出)"
|
|
|
+```
|
|
|
+
|
|
|
+同时用 AI 平台域名验证不受影响:
|
|
|
+```bash
|
|
|
+curl -sS -I -H "Origin: https://ai.fmode.cn" "https://server.fmode.cn/api/apig/message" \
|
|
|
+ | grep -ci "^access-control-allow-origin" # 应为 1
|
|
|
+```
|
|
|
+
|
|
|
+### App 侧现状
|
|
|
+
|
|
|
+`fmode-login-proxy` 云函数(`zpus2KjtFH`)已代理登录链路,绕过该问题。
|
|
|
+**平台修复后可以去掉这层代理**,减少一次中转。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 二、`ai.fmode.cn` 缺少 `/api-platform/**` 反向代理
|
|
|
+
|
|
|
+### 严重度与状态
|
|
|
+
|
|
|
+| 项 | 内容 |
|
|
|
+|---|---|
|
|
|
+| 严重度 | 🟢 低(**有回落机制,功能不中断**) |
|
|
|
+| 责任方 | 平台/运维(CDN 回源或 nginx 配置) |
|
|
|
+| 状态 | ❌ 未配置 |
|
|
|
+
|
|
|
+### 现象
|
|
|
+
|
|
|
+浏览器控制台每次打开都出现:
|
|
|
+```
|
|
|
+[PlatformProxy] /api-platform/ 未转发到平台(x-powered-by=空),回落直连 server.fmode.cn
|
|
|
+GET https://ai.fmode.cn/api-platform/api/zzz-fmode-probe 404 (Not Found)
|
|
|
+```
|
|
|
+
|
|
|
+### 判断方法(看 404 的 Server 头)
|
|
|
+
|
|
|
+```bash
|
|
|
+# 未转发 → Server: openresty + X-CCDN-*(落在 OBS 静态托管上)
|
|
|
+curl -sS -I https://ai.fmode.cn/api-platform/api/probe-xyz | grep -iE "server|x-powered-by"
|
|
|
+
|
|
|
+# 转发正常 → Server: nginx + x-powered-by: Express
|
|
|
+curl -sS -I https://server.fmode.cn/api/probe-xyz | grep -iE "server|x-powered-by"
|
|
|
+```
|
|
|
+
|
|
|
+实测(2026-11-18):
|
|
|
+
|
|
|
+| 请求 | Server 头 | 结论 |
|
|
|
+|---|---|---|
|
|
|
+| `ai.fmode.cn/api-platform/...` | `openresty` + `X-CCDN-*` | ❌ 落在 OBS |
|
|
|
+| `server.fmode.cn/api/...` | `nginx` + `x-powered-by: Express` | ✅ 平台真实响应 |
|
|
|
+
|
|
|
+### 影响
|
|
|
+
|
|
|
+| 方面 | 影响 |
|
|
|
+|---|---|
|
|
|
+| **功能** | ⚠️ 不中断。`platform-proxy.service.ts` 探测失败后回落直连 `server.fmode.cn` |
|
|
|
+| **控制台** | 每次多一个 404,干扰排查真问题 |
|
|
|
+| **CORS** | 回落直连时仍会撞上一、的多值 CORS |
|
|
|
+| **App** | 无影响(`isNativeApp()` 分支直接跳过探测) |
|
|
|
+
|
|
|
+### 修改点
|
|
|
+
|
|
|
+在 `ai.fmode.cn` 的**回源层**(华为云 CDN 的「动态加速」或源站 nginx)加:
|
|
|
+
|
|
|
+```nginx
|
|
|
+location /api-platform/ {
|
|
|
+ proxy_pass https://server.fmode.cn/api/;
|
|
|
+ proxy_set_header Host server.fmode.cn;
|
|
|
+ proxy_ssl_server_name on;
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+> ⚠️ **不要在这里再加 `Access-Control-Allow-Origin`**。
|
|
|
+> 同源代理后浏览器不再做跨域检查,重复添加会产生**多值 ACAO**,
|
|
|
+> 反而被浏览器整体拒绝(正是问题一的成因)。
|
|
|
+
|
|
|
+### 验收标准
|
|
|
+
|
|
|
+```bash
|
|
|
+curl -sS -I https://ai.fmode.cn/api-platform/api/probe-xyz | grep -i "x-powered-by"
|
|
|
+# 期望输出:x-powered-by: Express
|
|
|
+```
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 三、容器侧:`MEDIA:` 标记未全部生成 `m.file` 事件
|
|
|
+
|
|
|
+### 严重度与状态
|
|
|
+
|
|
|
+| 项 | 内容 |
|
|
|
+|---|---|
|
|
|
+| 严重度 | 🟡 中(用户看不到全部文件卡片) |
|
|
|
+| 责任方 | **容器 / Matrix 适配器** |
|
|
|
+| 状态 | ❌ 未修复(App 已加对账提示兜底) |
|
|
|
+
|
|
|
+### 现象
|
|
|
+
|
|
|
+一个回合里,正文列出了 3 个文件链接,但 App 只渲染出 2 张卡片。
|
|
|
+
|
|
|
+### 容器原话(2026-11-16 直接询问 `agent-node-lj-test` 所得)
|
|
|
+
|
|
|
+> **(a)** 我用的是 `MEDIA:` 标记。在正文里写 `MEDIA:/绝对路径`,由 Matrix 适配器解析后
|
|
|
+> 以 `m.file` 附件事件发出,同时正文保留文本。
|
|
|
+>
|
|
|
+> **(b)** 不区分。单个和多个都是同一套:正文里出现几处就逐个解析并作为独立附件事件发出。
|
|
|
+>
|
|
|
+> **(c)** 那是我在一次多文件交付里,正文里的 `MEDIA:` 行没能让每个文件都落地成附件事件,
|
|
|
+> 实际只到了部分文件 —— 我当时的说法是「两条 MEDIA 没送达」。
|
|
|
+> 原因是**标记存在但适配器没有为它们生成对应的事件**(不是文件不存在、也不是路径写错)。
|
|
|
+
|
|
|
+### 交叉验证
|
|
|
+
|
|
|
+独立的两条排查线得出一致结论:
|
|
|
+
|
|
|
+- `docs/00-tracking/2026-11-17-容器文件返回问题诊断.md`:
|
|
|
+ 附件投递**本身失败**(容器原文 `⚠️ Couldn't deliver the file attachment (…)`)
|
|
|
+- 2026-11-16 直接询问容器:**适配器没生成事件**
|
|
|
+
|
|
|
+### 修改点
|
|
|
+
|
|
|
+1. **修复适配器**:确保正文里每个 `MEDIA:` 标记都产出对应的 `m.file` 事件,
|
|
|
+ 失败时也要有明确的错误回执(而不是静默丢弃)
|
|
|
+2. **建议增强**:在消息内容里带一个**自描述文件清单**(容器自己也建议过):
|
|
|
+
|
|
|
+ ```json
|
|
|
+ {
|
|
|
+ "msgtype": "m.text",
|
|
|
+ "body": "……",
|
|
|
+ "fmode_files": ["a.html", "b.docx", "c.pdf"],
|
|
|
+ "fmode_file_count": 3
|
|
|
+ }
|
|
|
+ ```
|
|
|
+
|
|
|
+ App 可用它做**精确对账**(当前 App 只能从正文文本里推断)。
|
|
|
+
|
|
|
+### App 侧已做的兜底
|
|
|
+
|
|
|
+`assistant-turn.ts::countMissingFiles()`:
|
|
|
+
|
|
|
+- 统计正文里明确的文件声明(`MEDIA:` 标记 + 本项目云盘链接),按文件名去重
|
|
|
+- 与实际卡片数比较,差额在卡片下方提示:
|
|
|
+ > ⓘ 还有 N 个文件未收到(正文已列出,点击正文链接可直接打开)
|
|
|
+
|
|
|
+**只提示、不伪造卡片** —— 卡片必须以真实的 `m.file` 事件为准。
|
|
|
+
|
|
|
+### 验收标准
|
|
|
+
|
|
|
+让容器一次输出 3 个文件,App 应看到:
|
|
|
+- 3 张卡片
|
|
|
+- **没有**「还有 N 个文件未收到」提示
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 四、后台推送(用户裁决:暂不做,仅记录)
|
|
|
+
|
|
|
+### 决策
|
|
|
+
|
|
|
+**用户 2026-11-18 明确裁决:后台推送先记录,暂不实施。**
|
|
|
+
|
|
|
+### 现状
|
|
|
+
|
|
|
+JPush 代码已完整实现但默认关闭(`fmodeJpushEnabled=false`),
|
|
|
+当前 APK 内不含 JPush 类,权限清单干净。
|
|
|
+
|
|
|
+### 完整链路缺口(共 4 项)
|
|
|
+
|
|
|
+| # | 缺什么 | 谁提供 | 预估 |
|
|
|
+|---|---|---|---|
|
|
|
+| 1 | 极光 AppKey | 需注册极光应用 | 1 天 |
|
|
|
+| 2 | 厂商通道证书 | 华为/小米/OPPO/vivo 开发者后台 | **华为需企业认证,1-2 周** |
|
|
|
+| 3 | 别名签发后台 | 平台开发(用户登录 → 绑 userId↔设备) | 3-5 天 |
|
|
|
+| 4 | **服务端触发链路** | 平台开发(监听 Matrix → 调推送 API) | 5-10 天 |
|
|
|
+
|
|
|
+### 不做的影响
|
|
|
+
|
|
|
+| 场景 | 能否收到通知 |
|
|
|
+|---|---|
|
|
|
+| App 在前台 | ✅ |
|
|
|
+| 切走后几秒内 | ⚠️ 不稳定 |
|
|
|
+| 后台超过 1-2 分钟 | ❌ |
|
|
|
+| App 被杀 | ❌ |
|
|
|
+
|
|
|
+产品上应明确告知用户:**通知需 App 保持运行**。
|
|
|
+
|
|
|
+---
|
|
|
+
|
|
|
+## 汇总
|
|
|
+
|
|
|
+| # | 问题 | 责任方 | 优先级 | 状态 |
|
|
|
+|---|---|---|---|---|
|
|
|
+| 一 | 多值 CORS | 平台 | 🟡 中 | 待修复 |
|
|
|
+| 二 | `/api-platform/` 反代 | 平台 | 🟢 低 | 待配置 |
|
|
|
+| 三 | `MEDIA:` 漏生成事件 | 容器 | 🟡 中 | 待修复 |
|
|
|
+| 四 | 后台推送 | 产品+平台 | — | **暂不做** |
|