|
|
# 后端联调指南
|
|
|
|
|
|
## 环境与代理
|
|
|
|
|
|
- 前端目录：`frontend-vue`
|
|
|
- 开发代理：`frontend-vue/vite.config.ts:25-30` 将前端的 `/api` 代理到后端 `VITE_API_TARGET`
|
|
|
- 环境变量：
|
|
|
- `frontend-vue/.env.development` 示例：`VITE_API_TARGET=https://your-backend.example.com`
|
|
|
- 可选：`VITE_DEV_HOST`、`VITE_ALLOWED_HOSTS` 控制本地开发主机与允许的外网访问
|
|
|
- 启动与构建：
|
|
|
- 开发：`cd frontend-vue && npm i && npm run dev`
|
|
|
- 预览：`npm run preview`
|
|
|
|
|
|
## 鉴权与凭证
|
|
|
|
|
|
- 认证头：`Authorization: Bearer <token>`
|
|
|
- 前端存储：
|
|
|
- `localStorage` 键名：`cm_user`、`cm_token`
|
|
|
- 应用启动恢复：`frontend-vue/src/app/main.ts:10-12`
|
|
|
- 路由守卫：`frontend-vue/src/app/router/index.ts:23-30` 未登录重定向到登录页；基于 `meta.roles` 进行角色校验
|
|
|
|
|
|
## 关键接口规范
|
|
|
|
|
|
- 健康检查：`GET /v1/health`
|
|
|
- 登录：`POST /v1/user/login`
|
|
|
- 请求体：`{ username, password }`
|
|
|
- 响应体：`{ token, user: { username, role, email? } }`
|
|
|
- 注册：`POST /v1/user/register`
|
|
|
- 请求体：`{ username, email, password, fullName }`
|
|
|
- 响应体：`{ token?, user: { username, role, email? } }`
|
|
|
- 用户列表：`GET /api/v1/users`
|
|
|
- 响应体：`{ users: Array<{ username, role, email }> }` 或 `Array<{ username, role, email }>`
|
|
|
- 前端选择逻辑：仅匹配当前登录用户名；未匹配则显示错误提示
|
|
|
- 权限不足（例如操作员 403）：页面显示权限提示
|
|
|
- 角色值规范化：后端返回的 `role` 会统一转为小写并支持常见别名（如 `administrator`→`admin`、`ops`→`operator`）
|
|
|
- 集群与节点：
|
|
|
- `GET /v1/clusters` → `[{ uuid, host, ip, count, health }]`
|
|
|
- `POST /v1/clusters`、`DELETE /v1/clusters/:id`、`POST /v1/clusters/:id/start|stop`
|
|
|
- `GET /v1/nodes?cluster=<uuid>` → `[{ name, ip, status, cpu, mem, updated }]`
|
|
|
- `POST /v1/nodes/:name/start|stop`、`DELETE /v1/nodes/:name`
|
|
|
- 指标：
|
|
|
- CPU 趋势：`GET /v1/metrics/cpu_trend?cluster=<uuid>` → `{ times: string[], values: number[] }`
|
|
|
- 内存使用：`GET /v1/metrics/memory_usage?cluster=<uuid>` → `{ used: number, free: number }`
|
|
|
- 诊断：
|
|
|
- 故障摘要：`GET /v1/faults/summary?node=<name>|cluster=<host>` → `{ code, time, scope }`
|
|
|
- AI 对话历史：`GET /v1/ai/history?sessionId=<id>` → `{ messages: Array<{ role, content, reasoning? }> }`
|
|
|
- AI 对话：`POST /v1/ai/chat` → `{ reply, reasoning? }`
|
|
|
|
|
|
## 前端数据绑定要点
|
|
|
|
|
|
- 个人主页：`frontend-vue/src/app/views/Profile.vue`
|
|
|
- 仅使用后端数据；加载中与错误态可视化
|
|
|
- 角色标签映射：`frontend-vue/src/app/constants/roles.ts`
|
|
|
- 角色来源：
|
|
|
- 登录/注册优先采用后端返回的 `user.role` 或 `role`（`frontend-vue/src/app/stores/auth.ts:55-72,74-91`）
|
|
|
- 诊断页与导航：
|
|
|
- 路由授权：`diagnosis` 允许 `admin/operator`（`frontend-vue/src/app/router/index.ts:12`）
|
|
|
- 侧边栏入口基于角色显示（`frontend-vue/src/app/components/Sidebar.vue:7`）
|
|
|
|
|
|
## 联调步骤
|
|
|
|
|
|
- 设置 `VITE_API_TARGET` 指向后端地址，确保后端允许来自前端的 CORS 与 Host
|
|
|
- 启动前端后检查 `GET /v1/health` 返回正常
|
|
|
- 使用真实账号登录，确认：
|
|
|
- `GET /v1/user/me` 返回用户信息，个人主页字段显示为后端数据
|
|
|
- 侧边栏与页面访问受角色控制
|
|
|
- 仪表板与诊断页数据来自后端接口
|
|
|
- 常见问题：
|
|
|
- Token 无效或过期 → 返回 `401`，需要重新登录
|
|
|
- 代理失败 → 检查 `VITE_API_TARGET` 与后端协议/端口
|
|
|
- 外网访问本地开发 → 配置 `VITE_ALLOWED_HOSTS`，参考 `Cloudflare-Tunnel-Guide.md`
|
|
|
|
|
|
## 参考文件
|
|
|
|
|
|
- `frontend-vue/vite.config.ts`
|
|
|
- `frontend-vue/src/app/main.ts`
|
|
|
- `frontend-vue/src/app/router/index.ts`
|
|
|
- `frontend-vue/src/app/stores/auth.ts`
|
|
|
- `frontend-vue/src/app/views/Profile.vue`
|
|
|
- `frontend-vue/src/app/components/Sidebar.vue`
|
|
|
- `frontend-vue/src/app/constants/roles.ts`
|
