对，继续把**后台管理系统**也定下来。后台管理系统和 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"
