SkeyeVSS 管理平台前端 — 架构说明

本文档将描述skeyevss_backend前端的整体架构技术选型、目录职责、请求与路由、状态与构建部署。后端接口由独立服务提供 go-vss。项目源码地址https://github.com/openskeye/skeyevss_frontend_web1. 项目定位本仓库是视频监控类业务的管理后台提供设备与通道管理、配置中心、日志与告警、视频调阅、录像、电子地图等能力。当前为开发/演示版本完整商业版包含更多能力见 go-vss。2. 技术栈概览层级技术运行时React 18、TypeScript构建与开发服务器Vite 7、vitejs/plugin-react路由react-router-dom5.x react-router-config集中式路由表 renderRoutesUIAnt Design 5、Sass、animate.css全局状态RecoilRecoilRoot包裹应用根HTTPAxios封装为service 拦截器可视化与富内容ECharts、Leaflet、Markdown/Quill 编辑器等视频播放public下 Jessibuca / LivePlayer 等脚本业务侧通过组件封装3. 逻辑架构分层浏览器 └── React 应用 (Vite 打包) ├── 路由层 (#routers) — 登录 / 布局 / 各业务页 ├── 页面层 (#pages/*) — 按域划分通常含 index api model ├── 组件层 (#components/*) — 布局、表格、表单、视频等复用 UI ├── 数据与协议 (#repositories) — API 封装、类型、缓存、Recoil 模型 └── 基础设施 (#utils, #constants, #types) — Axios、Token、工具函数、全局变量 ↓ HTTP(S) / EventSource / WebSocket按功能 后端 go-vss及媒体/VSS 相关能力展示与交互页面与通用组件。领域数据访问repositories/apis中的函数通过统一 Axios 实例访问后端部分实时能力使用Server-Sent Events (EventSource)如文件下载进度、VSS 状态、SIP 日志等与 REST 并列存在。配置与权限启动后从后端拉取setting、conf等写入 Recoil 与全局变量如variables.showcase、权限树菜单与按钮随权限变化。4. 目录结构约定路径职责src/index.tsx入口BrowserRouter、RecoilRoot、renderRoutes、全局样式与 polyfill 提示src/routers/index.tsx顶层路由sites.tsx业务子路由constants.ts路径枚举与菜单树anchor.ts锚点相关src/pages/按业务域分子目录如devices/、configs/、logs/、system/常见文件index.tsx页面、api.ts、model.tssrc/components/layout布局与子路由渲染、table、form、video等src/repositories/apis/后端 API 封装src/repositories/types/请求/响应与领域类型src/repositories/models/Recoil atom 与状态类src/repositories/cache/本地缓存抽象src/utils/axios.tsx拦截器、proxy、route、token.ts、ws.ts、store.ts等src/constants/全局常量与运行时variables主题、弹窗等public/静态资源视频解码与播放器脚本体积较大独立存放路径别名与vite.config.js、tsconfig.json中一致、#指向src并有#pages、#components、#repositories等细粒度别名。5. 路由设计顶层/login独立登录页/由Layout承载内部再renderRoutes(sites)。业务路由集中在routers/sites.tsx路径与标题来源于routers/constants.ts中的树形routes及Path枚举便于菜单、面包屑与权限uniqueId对齐。列表类页面常使用pathParams/:page?/:limit?/:sort?/:filter?/:anchor?统一分页、排序、筛选与锚点。6. 网络层与后端对接6.1 RESTAxios单例servicebaseURL为空实际 URL 由proxy(route.backend | route.external, path)拼出前缀route.backend→/${VITE_BACKEND_PROXY}/...route.external→/${VITE_EXTERNAL_PROXY}/...开发环境下Vitedev server根据VITE_BACKEND_PROXY、VITE_BACKEND_API_URL及可选 external 代理做反向代理避免跨域。请求拦截附加Authorization、Version、Language、XProtocol可选 NProgress支持disabledLoading。响应拦截统一错误提示、token 续期、强制改密跳转、许可证/通道数等全局标志写入variables。6.2 实时与推送EventSource用于服务端推送类场景下载进度、服务状态、SIP 日志等URL 常指向带type...的events端点。WebSocket封装在utils/ws.ts如云台、流相关信令按页面需要使用。6.3 与媒体/VSS 的协作repositories/apis/base.ts中大量/internal/vss/...、/internal/ms/...接口体现前后端分工管理端负责配置与列表取流、回放控制、设备控制、ONVIF、预置位等由后端统一调度媒体服务。7. 状态管理Recoil用户身份Profile、主题Theme、系统设置与权限映射、字典/部门缓存、视频相关会话状态等集中在repositories/models/recoil-state.ts及关联类中。本地持久化通过utils/store与repositories/cache/ls等与 Token、主题、最后访问路由等配合。非全局状态各页model.ts可与 Recoil 并存用于页面级表格、表单状态。8. 构建与部署开发yarn start→vite --host 0.0.0.0读取.env/.env.*中的PORT、代理与VITE_*变量。生产构建vite build --mode production产物默认输出到build/非默认的dist并配置了分包React、Ant Design 按子模块、ECharts、xlsx 等与 gzip 相关选项。环境变量需配置与后端一致的代理路径与 API 基地址标题等使用import.meta.env.VITE_TITLE等。9. 安全与认证Token 存取与刷新逻辑在utils/token.ts与 Axios 响应联动。需登录路由依赖 Layout 与权限数据未授权时由拦截器或路由守卫取决于具体页面实现引导登录或提示。10. 扩展与维护建议新业务优先在pages下新增域目录在routers/sites.tsx与constants.ts中登记路径与菜单uniqueIdAPI 放入repositories/apis或按域拆文件。类型与后端契约放在repositories/types避免在页面中散落字符串。大体积依赖已通过manualChunks拆分新增重量级库时可继续调整 ViterollupOptions以控制首包体积。