680 lines
11 KiB
Markdown
680 lines
11 KiB
Markdown
对，继续把**后台管理系统**也定下来。后台管理系统和 C 端 Web 不一样，它不追求 Notion 那种沉浸编辑体验，核心是：
|
||
|
||
```text
|
||
高效率 CRUD
|
||
数据检索
|
||
用户/会员管理
|
||
知识库任务监控
|
||
AI 成本监控
|
||
问题排查
|
||
人工干预
|
||
权限审计
|
||
```
|
||
|
||
所以后台不要用 C 端那套 shadcn 风格，也不要追求“漂亮得像消费级产品”。后台要稳、快、表格强、表单强、权限清楚。
|
||
|
||
# 后台管理系统技术栈定版
|
||
|
||
```text
|
||
框架：Vite + React + TypeScript
|
||
UI：Ant Design
|
||
中后台增强组件：Ant Design ProComponents
|
||
路由：React Router
|
||
服务端状态：TanStack Query
|
||
本地状态：Zustand
|
||
API Client：OpenAPI + Orval
|
||
图表：Apache ECharts
|
||
表单：Ant Design Form + Zod
|
||
权限：后端 RBAC + 前端路由守卫
|
||
构建：pnpm workspace + Turborepo
|
||
部署：8核32G，和生产后端同源或同内网
|
||
```
|
||
|
||
一句话：
|
||
|
||
```text
|
||
C端 Web：Vite + 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端 Web：shadcn/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"
|