135 lines
6.1 KiB
Markdown
135 lines
6.1 KiB
Markdown
# 前端功能失效问题排查报告
|
||
|
||
> 排查时间：2026-07-30
|
||
> 环境：前端（Windows）`localhost:16801` → Vite 代理 `/modelTF` → 后端（WSL）`localhost:17861`
|
||
> 方法：抓取后端 openapi 路由表 + 实测 curl 比对前端真实请求路径
|
||
|
||
## 一、现象
|
||
|
||
页面可以打开（app 能正常加载、仪表盘等模块正常），但**大量功能点击无响应或报"请求失败"**。
|
||
经排查，故障集中在"路由前缀叠加导致后端 404"，并非前端崩溃。
|
||
|
||
## 二、已验证正常的部分（排除法）
|
||
|
||
| 模块 | 接口 | 实测结果 |
|
||
|------|------|----------|
|
||
| 仪表盘 | `GET /modelTF/dashboard/stats` | ✅ 返回真实数据 |
|
||
| 登录 | `/modelTF/login` | ✅ 正常 |
|
||
| 健康检查 | `/modelTF/health` | ✅ 正常 |
|
||
| 其余 83 个后端路由 | 各 `/modelTF/xxx` | ✅ 均为正确的单层前缀 |
|
||
|
||
后端共 111 个路由，**仅 28 个 `data-process` 路由异常（双重前缀）**，其余均正确。
|
||
|
||
## 三、问题清单
|
||
|
||
### 问题 1（严重，根因）：数据处理模块整体 404
|
||
|
||
**链路（前缀被叠加了两次 `/modelTF`）：**
|
||
|
||
1. `backend/app/main.py:22`：`app.include_router(api_router, prefix=settings.route_prefix)`
|
||
- `route_prefix` 来自 `config.py`，默认值为 `"/modelTF"`
|
||
2. `backend/app/api/v1/router.py`：`api_router.include_router(data_process_router, prefix="/modelTF", ...)`
|
||
- 这里又额外加了一次 `prefix="/modelTF"`
|
||
3. `backend/app/api/v1/endpoints/data_process.py`：`router = APIRouter(prefix="/data-process")`
|
||
|
||
**结果**：实际注册路径变成 `/modelTF/modelTF/data-process/...`（双层前缀）。
|
||
|
||
**影响**：整个"数据处理"模块（列表 / 详情 / 创建任务 / 上传源文件 / 预览 / 生成 / 结果编辑 / 发布 / 重新生成 / 外部拉取测试 等）共 **28 个接口全部 404**。
|
||
|
||
**前端请求路径**：`baseURL('/modelTF')` + `get('/data-process')` → 实际请求 `/modelTF/data-process/...` → 与后端真实路径不匹配 → 404。
|
||
|
||
**实测证据**：
|
||
|
||
```
|
||
前端真实请求 GET /modelTF/data-process
|
||
-> {"detail":"Not Found"} (404)
|
||
|
||
后端真实路径 GET /modelTF/modelTF/data-process
|
||
-> {"code":0,"message":"ok","data":{...有"测试"任务}} (路径存在，有数据)
|
||
```
|
||
|
||
---
|
||
|
||
### 问题 2：数据集下载 / 预览 双重前缀 404
|
||
|
||
`frontend/src/api/request.ts:16` 的 `baseURL: '/modelTF'`，而
|
||
`frontend/src/api/modules/dataset.ts:92` 与 `:98` 的下载地址直接写了**绝对前缀**：
|
||
|
||
```ts
|
||
const baseUrl = `/modelTF/dataset-manage/download/${datasetId}/${fileId}`
|
||
```
|
||
|
||
axios 会把 `baseURL('/modelTF')` 与以 `/` 开头的 url 拼接成 `/modelTF/modelTF/dataset-manage/download/...`，导致 404。
|
||
|
||
**注意**：后端 `dataset-manage` 是**正确的单层** `/modelTF/dataset-manage/...`（实测真实路径返回 500 = 路径存在但资源参数无效，而非 404）。
|
||
|
||
**实测证据**：
|
||
|
||
```
|
||
前端实际发出 GET /modelTF/modelTF/dataset-manage/download/x/y -> 404 Not Found
|
||
后端真实路径 GET /modelTF/dataset-manage/download/x/y -> 500 (路径存在)
|
||
```
|
||
|
||
**影响**：数据集的下载、预览功能不可用。
|
||
|
||
---
|
||
|
||
### 问题 3：模型导出 双重前缀 + 后端无此端点
|
||
|
||
`frontend/src/api/modules/model.ts:48` 导出地址同样写了绝对前缀：
|
||
|
||
```ts
|
||
`/modelTF/model-manage/trained-models/${encodeURIComponent(modelName)}/export`
|
||
```
|
||
|
||
- 经 axios 拼接 → `/modelTF/modelTF/model-manage/trained-models/.../export` → 404（双重前缀）。
|
||
- **进一步**：openapi 中 `model-manage/trained-models` 仅有 `GET` 列表与 `GET {model_id}` 详情，**并不存在 `/export` 端点**。因此即使修掉双前缀，导出仍会 404，需后端补充该接口或确认正确路径。
|
||
|
||
**影响**：模型导出功能不可用（两个独立原因叠加）。
|
||
|
||
---
|
||
|
||
### 问题 4（次生隐患，修复问题 1 后会暴露）：data-process 源文件 raw 链接
|
||
|
||
`frontend/src/api/modules/dataProcess.ts:162`：
|
||
|
||
```ts
|
||
`/modelTF/data-process/${taskId}/source-files/${fileId}/raw`
|
||
```
|
||
|
||
当前被 axios 拼成 `/modelTF/modelTF/data-process/.../raw`，**恰好命中后端双前缀**，暂时可用。
|
||
**一旦修复问题 1（后端改为单层 `/modelTF/data-process/...`）**，此处会反向变成 404，必须同步去掉多余的 `/modelTF`。
|
||
|
||
## 四、前端其他使用绝对 `/modelTF` 前缀的位置（汇总）
|
||
|
||
| 文件:行 | 接口 | 当前状态 |
|
||
|---------|------|----------|
|
||
| `dataProcess.ts:162` | 源文件 raw 下载 | 靠后端双前缀"侥幸"命中，修复问题 1 后失效 |
|
||
| `dataset.ts:92` `:98` | 数据集下载/预览 | 双重前缀 → 404（问题 2） |
|
||
| `model.ts:48` | 模型导出 | 双重前缀 + 后端无端点 → 404（问题 3） |
|
||
|
||
其余模块（`compare / fineTune / project / eval / model(其他) / dataset(其他)`）均使用相对路径 `/xxx`，正常。
|
||
|
||
## 五、修复建议（未实施，待确认）
|
||
|
||
1. **后端** `backend/app/api/v1/router.py`：去掉 `data_process_router` 的 `prefix="/modelTF"`
|
||
（`api_router` 已挂 `/modelTF`，`data_process` 自身已有 `/data-process`，无需再叠加）。
|
||
改后 data-process 路径变为 `/modelTF/data-process/...`，与前端请求一致。
|
||
|
||
2. **前端** `dataProcess.ts:162`：raw url 去掉 `/modelTF`，改为 `/data-process/.../raw`。
|
||
|
||
3. **前端** `dataset.ts:92/:98`：download url 去掉 `/modelTF`，改为 `/dataset-manage/download/...`。
|
||
|
||
4. **前端** `model.ts:48`：export url 去掉 `/modelTF`，改为 `/model-manage/trained-models/${name}/export`；
|
||
同时**与后端确认 `/export` 端点是否存在**（openapi 显示无），需后端补实现或给出正确路径。
|
||
|
||
5. 重启后端 + 前端，对"数据处理 / 数据集下载 / 模型导出"三个模块做回归。
|
||
|
||
## 六、根因归类
|
||
|
||
上述问题是一次改动/合并引入的**路由前缀叠加 bug**：
|
||
- 后端在 `api_router` 已统一挂 `/modelTF` 的前提下，又对 `data_process` 多挂了一次 `/modelTF`；
|
||
- 前端部分下载/导出接口误用了绝对 `/modelTF` 前缀，与 `request.ts` 的 `baseURL` 再次叠加。
|
||
|
||
修复核心是"前后端前缀只保留一层 `/modelTF`"。
|