680 lines
11 KiB
Markdown
Raw Permalink Normal View History

对,继续把**后台管理系统**也定下来。后台管理系统和 C 端 Web 不一样,它不追求 Notion 那种沉浸编辑体验,核心是:
```text
高效率 CRUD
数据检索
用户/会员管理
知识库任务监控
AI 成本监控
问题排查
人工干预
权限审计
```
所以后台不要用 C 端那套 shadcn 风格,也不要追求“漂亮得像消费级产品”。后台要稳、快、表格强、表单强、权限清楚。
# 后台管理系统技术栈定版
```text
框架Vite + React + TypeScript
UIAnt Design
中后台增强组件Ant Design ProComponents
路由React Router
服务端状态TanStack Query
本地状态Zustand
API ClientOpenAPI + Orval
图表Apache ECharts
表单Ant Design Form + Zod
权限:后端 RBAC + 前端路由守卫
构建pnpm workspace + Turborepo
部署8核32G和生产后端同源或同内网
```
一句话:
```text
C端 WebVite + React + Tiptap + shadcn做高体验知识工作台
后台管理Vite + React + Ant Design + ProComponents做高效率运营控制台
```
---
# 一、为什么后台用 Ant Design
后台管理就是 Ant Design 的优势区。Ant Design 官方定位是面向 React 的高质量组件库,适合构建丰富、交互型用户界面;而 ProComponents 明确是为了降低中后台 CRUD 实现成本,尤其适合表格、筛选、表单、详情页这些场景。([Ant Design][1])
所以后台管理系统直接定:
```text
Ant Design
+
ProComponents
```
主要用:
```text
ProTable
ProForm
ProDescriptions
ProLayout
ModalForm
DrawerForm
StepsForm
```
后台里最常见的页面就是:
```text
用户列表
订单列表
文件列表
导入任务列表
AI 调用日志
额度使用记录
错误日志
备份任务
```
这些用 ProTable 做最快。
---
# 二、为什么后台不用 shadcn/ui
shadcn/ui 适合 C 端产品、官网、轻量 SaaS、漂亮的交互界面。
但后台管理系统主要是:
```text
密集表格
复杂筛选
批量操作
详情抽屉
高级搜索
权限按钮
状态标签
操作日志
```
Ant Design 在这些地方更省时间。
所以定:
```text
C端 Webshadcn/ui
后台管理Ant Design
```
不要强行统一 UI 栈。
---
# 三、为什么后台也用 Vite
后台不需要 SSR也不需要 SEO。Vite 构建产物本来就适合静态托管,官方文档也说明 `vite build` 会输出适合静态托管的生产包。([vitejs][2])
所以后台用:
```text
Vite + React + TypeScript
```
不要用 Next.js。
不要用 Umi/Ant Design Pro 全家桶起步。
我们只拿 Ant Design 和 ProComponents不把整个项目绑死到 Umi 上。
---
# 四、状态管理怎么定?
## 服务端状态
```text
TanStack Query
```
后台大部分数据都是服务端状态:
```text
用户列表
会员状态
知识库列表
文件列表
导入任务
AI 调用日志
消费统计
错误日志
备份记录
```
TanStack Query 官方定位就是处理 fetching、caching、同步和更新服务端状态。([GitHub][3])
后台不要自己手写一堆:
```text
loading
error
pagination
refetch
cache
mutation
```
直接交给 React Query。
---
## 本地状态
```text
Zustand
```
只管理这些轻量 UI 状态:
```text
侧边栏折叠
当前主题
当前选中的环境
全局搜索弹窗
当前打开的抽屉
管理员权限缓存
```
Zustand 官方定位是小型、快速、可扩展的 React 状态管理方案,适合这种轻量本地状态。([zustand.docs.pmnd.rs][4])
---
# 五、API 类型方案
后台继续用:
```text
OpenAPI + Orval
```
Orval 可以从 OpenAPI 生成类型安全的 TypeScript API client并支持 React Query。([orval.dev][5])
这样你的结构会很清楚:
```text
NestJS Swagger / OpenAPI
Orval 生成 admin-api-client
React Query hooks
Ant Design 页面
```
后台不要手写 axios 类型。
---
# 六、图表用什么?
后台图表定:
```text
Apache ECharts
```
后台需要看:
```text
DAU / MAU
注册趋势
付费趋势
AI 调用成本
OCR 页数
Vision 页数
Embedding 数量
知识库导入成功率
任务失败率
用户留存
模型调用分布
```
ECharts 官方说明它提供 20 多种图表类型,并支持 Canvas/SVG、渐进渲染和多维数据分析能力适合后台数据可视化。([echarts.apache.org][6])
不用 Recharts 做后台主图表。Recharts 可以做轻量卡片图,但后台完整数据分析还是 ECharts 更合适。
---
# 七、后台管理系统放哪里?
后台管理前端建议部署在:
```text
8核32G
```
原因是它操作生产数据,最好和生产后端同源或同内网,减少跨服务器、跨域和密钥暴露问题。
最终部署:
```text
8核32G
- admin.zhixi.xxx 静态前端
- /admin-api 后台接口
- MySQL
- Redis
- Qdrant
- RAG Worker
```
4核4G 继续放:
```text
产品官网
Gitea
n8n
agent
监控
```
不要把后台管理系统放 4核然后跨公网操作 8核的生产 API。可以做到但没必要增加复杂度。
---
# 八、后台后端怎么做?
后台不是单独起一个后端项目,而是在现有 NestJS 里加:
```text
AdminModule
```
接口前缀:
```text
/admin-api/*
```
普通 C 端 API
```text
/api/*
```
内部 Worker API
```text
/internal/*
```
也就是:
```text
/api 用户端接口
/admin-api 后台管理接口
/internal Worker / 内部服务接口
```
后台不能直接连数据库。
所有操作必须经过 NestJS 后端,统一权限、日志、审计。
---
# 九、后台权限系统
后台必须独立于普通用户系统。
不要让普通 `users` 表里的用户直接登录后台。
新增:
```text
admin_users
admin_roles
admin_permissions
admin_role_permissions
admin_user_roles
admin_sessions
admin_audit_logs
```
权限模型:
```text
SUPER_ADMIN
OPERATIONS
CUSTOMER_SUPPORT
CONTENT_REVIEWER
FINANCE
DEVELOPER
READONLY
```
高危操作必须写审计日志:
```text
修改会员
重置额度
删除知识库
重试导入任务
清理 COS 文件
重建 Qdrant 索引
修改模型路由
修改系统 Prompt
退款/订单处理
封禁用户
```
审计日志至少记录:
```text
adminUserId
action
resourceType
resourceId
beforeJson
afterJson
ip
userAgent
createdAt
```
---
# 十、后台安全策略
后台管理系统要比 C 端更严格。
第一版至少做:
```text
独立管理员账号
强密码
登录限流
HttpOnly Cookie
CSRF 保护
RBAC 权限
操作审计
敏感操作二次确认
后台域名单独配置
```
后面补:
```text
TOTP 双因素认证
IP 白名单
登录通知
设备管理
只读管理员
紧急冻结开关
```
不要让后台用普通用户 JWT 直接访问。
---
# 十一、后台页面清单
后台第一批页面要这样定,不要只做一个用户列表。
## 1. 总览 Dashboard
```text
今日注册
今日活跃
今日付费
AI 调用次数
AI 成本
OCR 页数
Vision 页数
导入成功率
失败任务数
系统告警
```
## 2. 用户管理
```text
用户列表
用户详情
登录记录
会员状态
额度使用
知识库数量
文件占用
学习记录概览
封禁 / 解封
备注
```
## 3. 会员与额度
```text
会员方案
订阅状态
额度配置
额度使用明细
手动补额度
手动扣额度
订单记录
退款记录
```
## 4. 知识库管理
```text
知识库列表
知识源列表
文件详情
parsed.md 查看
chunk 数量
Qdrant 索引状态
导入任务状态
重试 / 取消 / 标记失败
```
## 5. 文档导入任务
```text
DocumentImport 队列
当前 step
progress
workerId
heartbeatAt
retryCount
errorCode
errorMessage
任务重试
任务取消
任务详情
```
## 6. AI 调用与成本
```text
DeepSeek 调用记录
硅基流动调用记录
百度 OCR 调用记录
embedding 调用数量
rerank 调用数量
按用户统计成本
按模型统计成本
失败率
平均耗时
```
## 7. Prompt / 模型路由配置
```text
任务类型
默认模型
备用模型
temperature
max_tokens
是否 thinking
Prompt 版本
灰度开关
```
这一块非常重要。你后面一定会调模型策略,不能每次都改代码。
## 8. 文件与 COS 管理
```text
文件列表
objectKey
文件大小
文件用途
上传状态
引用关系
孤儿文件扫描
清理队列
```
## 9. Qdrant 管理
```text
collection 状态
points 数量
索引状态
snapshot 记录
重建索引任务
按 sourceId 删除向量
按 kbId 标记 deleted
```
## 10. 备份管理
```text
MySQL backup_jobs
Qdrant snapshots
COS 同步状态
备份失败重试
备份下载
恢复演练记录
```
## 11. 反馈与工单
```text
用户反馈
截图
设备信息
App 版本
处理状态
内部备注
```
## 12. 系统审计
```text
管理员操作日志
登录日志
敏感操作
失败操作
权限变更记录
```
---
# 十二、项目结构
放到 monorepo
```text
startup/
apps/
landing/
web/
admin/
backend/
rag-worker/
packages/
ui/
admin-ui/
api-client/
shared/
config/
```
`apps/admin` 技术栈:
```text
Vite
React
TypeScript
React Router
Ant Design
ProComponents
TanStack Query
Zustand
Orval
ECharts
```
---
# 十三、不要选这些
后台管理系统不建议:
```text
不用 Next.js
不用 shadcn/ui 做后台主 UI
不用 Dify 做后台
不用 Strapi / Directus 接管生产数据
不用让后台前端直连数据库
不用让 n8n 直接操作生产库
不用把后台部署在 4核工具服务器上跨公网操作生产
```
低代码后台可以后面用来做内部小工具,但**知习正式后台管理系统必须自己做**。原因是你有大量业务特定操作:
```text
额度调整
AI 成本追踪
知识库导入重试
Qdrant 重建
Prompt 版本
模型路由
COS 清理
学习记录排查
```
这些不是普通 CRUD 能完整覆盖的。
---
# 最终拍板
```text
后台管理系统:
Vite + React + TypeScript
Ant Design + ProComponents
React Router
TanStack Query
Zustand
OpenAPI + Orval
Apache ECharts
Ant Design Form + Zod
NestJS AdminModule
MySQL RBAC + admin_audit_logs
部署在 8核32G
```
最终分工:
```text
C端 Web体验优先像 Notion / 知识工作台
后台 Admin效率优先像运营控制台 / 系统控制台
iOS移动学习体验优先
8核32G生产核心
4核4G官网、Gitea、n8n、agent、监控
```
[1]: https://ant.design/docs/react/introduce/?utm_source=chatgpt.com "Ant Design of React"
[2]: https://vite.dev/guide/build?utm_source=chatgpt.com "Building for Production"
[3]: https://github.com/tanstack/query?utm_source=chatgpt.com "TanStack/query"
[4]: https://zustand.docs.pmnd.rs/?utm_source=chatgpt.com "Zustand: Introduction"
[5]: https://orval.dev/?utm_source=chatgpt.com "Orval - Generate type-safe API clients from OpenAPI"
[6]: https://echarts.apache.org/?utm_source=chatgpt.com "Apache ECharts"