ChatGPT-Admin-Web架构设计揭秘自托管AI平台从单体到微服务的完整指南【免费下载链接】AChat AChat - An open-source/self-hosted/local-first AI platform, designed for enterprises and teams, perfectly combining powerful local processing capabilities with seamless remote synchronization.项目地址: https://gitcode.com/gh_mirrors/ch/AChatChatGPT-Admin-WebCAW是一款自托管 AI 平台让团队和组织能够一站式共享使用 AI Chat开箱即用地提供用户管理、付费套餐配置、支付接口对接和文本安全过滤。很多新手会误以为它只是一个简单的单体应用但深入 V3 版本后可以发现它采用pnpm monorepo 模块化微服务化设计前端后端职责彻底分离契约通过共享包统一。本文将带你拆解这套架构的每一层设计理解它为什么既简单易用又具备可拓展性。30秒看懂CAW 的技术选型层级技术说明前端Next.js双端管理端 用户端一体化 Web 应用后端Nest.js模块化后端Fastify 高性能适配数据库PostgreSQL Redis关系型数据 高速缓存数据建模Prisma类型安全的 ORM 与迁移管理值得一提的是官方在 README 中给出了清晰的版本演进路线V1 版本基于 Redis 数据库可拓展性较差V3 版本使用全新技术栈重构引入 PostgreSQL 承担核心业务数据。这正是从单体走向模块化最直观的体现 第一步Monorepo 骨架——四个包如何分工整个仓库通过 pnpm workspaces turbo 组织目录结构一目了然packages/backend/—— 后端服务Nest.js 应用packages/frontend/—— 前端应用Next.js 应用packages/shared/—— 前后端共享的契约包DTO、类型、统一错误码prisma/—— 数据库模型与迁移脚本这种布局的核心价值在于前端和后端各自独立构建部署但共享同一份契约。修改接口字段时shared包中的类型定义会同时约束两端编译器直接帮你发现不一致而不是等到线上报错。后端NestJS 模块化像微服务一样组织单体后端代码按业务模块 能力库 公共设施三层组织这是本项目最值得学习的架构模式业务模块modules/auth认证、chat对话、order订单、product商品、user用户、dashboard仪表盘每个模块都是 Controller Service 的独立单元能力库libs/jwt、email、sms、payment、content-safe把邮件、短信、支付、内容安全等第三方能力封装为可插拔服务公共设施common/全局守卫、异常过滤器、校验管道保证所有模块行为一致。统一认证与角色权限RBAC全局AuthGuard在packages/backend/src/common/guards/auth.guard.ts中实现每个请求默认需要携带 JWT Token路由可通过Public()装饰器声明为公开接口用Roles()声明所需角色Admin / User。认证逻辑只写一遍所有模块自动生效——这就是模块化架构下认证一次处处复用的最佳实践 聊天接口SSE 流式输出packages/backend/src/modules/chat/chat.controller.ts中使用Sse装饰器实现 Server-Sent Events 流式响应AI 的回答逐字推送到前端同时ChatService内置了基于套餐的用量限额检查limitCheck根据用户当前订单对应的套餐模型限额统计时间窗口内的消息数实现细粒度的配额控制。第三方服务模块化支付、邮件、短信支付对接被封装在packages/backend/src/libs/payment/中官方文档提供了迅虎等支付渠道的完整配置截图邮件能力同样以独立模块libs/email/存在支持 Mailgun、Elastic Email、企业微信等多种渠道切换渠道只需改配置不动业务代码 这种业务模块稳定、能力库可替换的分层正是微服务化的核心思想——只是先在一个进程内完成解耦将来需要时可以平滑拆分为独立服务。数据层Prisma PostgreSQL Redis数据模型定义在prisma/schema.prisma中核心模型清晰对应业务域用户域User、OAuth多平台登录商品域Product套餐、ModelAI 模型、ModelInProduct套餐-模型限额关系、Category订单域Order订阅/一次性两种订单类型带完整状态机AI 域OpenAIKey支持多 Key 权重、限流配置、ChatSession、ChatMessageV1 时代把会话数据存在 Redis 里扩容和备份都受限V3 改为 PostgreSQL 存储业务数据、Redis 承担缓存读写路径清晰、水平扩容友好——这是从单体走向可扩展架构的关键一步。共享包 shared前后端契约的单一事实来源packages/shared/src/index.ts统一导出了 DTO、类型定义和BaseResponse响应结构。所有接口都遵循同一约定成功返回{ success: true, data }失败返回{ success: false, code, message }错误码集中在ErrorCodeEnum中如AuthFail、OutOfQuota、ValidationError。前端甚至基于这份契约写了一个 SWR 中间件packages/frontend/src/app/provider/auth-middleware.ts任何请求返回AuthFail时自动清除 Token 并跳转登录页。一份错误码定义两端自动联动这就是共享契约包的魅力 ✨性能亮点内容安全的 Worker 池文本安全过滤敏感词过滤/替换是 CPU 密集型任务。packages/backend/src/libs/content-safe/workerPool.ts基于 Node.js 的worker_threads实现了线程池按 CPU 核数启动多个 Worker每个 Worker 内部用mint-filter维护敏感词 Trie 树主线程通过消息队列分发过滤任务。管理端配置内容安全策略如接入百度内容安全时只需调用setKeys批量下发关键词主线程不再被同步计算阻塞接口吞吐量得到保障——这是单体应用中引入并发微服务思维的典型案例。前端Next.js 路由分组的双端体验前端用 Next.js App Router 的路由组天然隔离了两个世界(admin-end)/dashboard/—— 管理端后台对话管理、模型管理、订单、商品、用户、系统设置(user-end)/—— 用户端AI 对话、套餐购买、个人中心、公告。两者共享components/、store/zustand 状态管理和hooks/但路由和布局完全独立管理端与用户端互不干扰又复用同一套 UI 体系。架构最佳实践清单 Monorepo 分治前后端独立包 turbo 统一构建共享shared契约包消灭接口不一致模块化单体NestJS 模块划分业务能力库封装第三方依赖为日后拆分微服务预留边界全局守卫统一认证JWT Public()/Roles()装饰器一套 RBAC 覆盖所有接口数据分层PostgreSQL 存业务数据、Redis 做缓存告别Redis 当数据库的单体陷阱契约驱动的前端统一BaseResponse 错误码枚举SWR 中间件自动处理鉴权失败并发意识CPU 密集任务丢进 Worker 池主线程始终保持高响应。这套架构证明了中小团队完全不必一开始就上重型微服务先在一个仓库里把边界划清楚就是微服务化的最佳起点。需要部署自己的 AI 平台时可直接克隆仓库git clone https://gitcode.com/gh_mirrors/ch/ChatGPT-Admin-Web按 README 指引完成 PostgreSQL 与 Redis 配置即可体验这套架构的完整能力。【免费下载链接】AChat AChat - An open-source/self-hosted/local-first AI platform, designed for enterprises and teams, perfectly combining powerful local processing capabilities with seamless remote synchronization.项目地址: https://gitcode.com/gh_mirrors/ch/AChat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考