从 0 到上线：NestJS 微服务 + Next.js 管理后台（AI全栈实战）

从 0 到上线：NestJS 微服务 + Next.js 管理后台全栈实战

项目仓库：后端 ai-nest-backend · 前端 nextjs-admin
线上地址：管理端 www.admin.chenchar.com

写在前面

这篇文章记录的是我借助AI能力 独立完成并部署上线的一套 B 端管理后台全栈项目：后端采用 NestJS Monorepo 微服务，前端基于 Next.js 16，最终在腾讯云轻量服务器上用 Docker Compose 跑通 HTTPS 与双域名。

如果你也在做「网关 + 多服务 + 管理端」这类架构，希望少走一些我踩过的坑（登录 Cookie、双库配置、数据库初始化、订单服务 503 等），这篇总结应该能帮到你。

一、项目是什么？

1.1 业务视角

这是一套可实际访问的后台系统，核心能力包括：

用户登录：邮箱 + 密码，JWT 鉴权
仪表盘：概览卡片、图表、渠道数据
商品管理：列表、上下架、库存调整
订单管理：列表、详情、异步通知（队列）

1.2 技术视角

层级	仓库	职责
前端	`web-nest`	页面、路由守卫、调用 API
网关	`gateway`	登录签发 JWT、统一入口、反向代理
用户服务	`user-service`	用户域 CRUD
订单服务	`order-service`	商品、订单、库存、BullMQ

前端不直连数据库 ，所有数据经 api.chenchar.com 进入网关，再转发到对应微服务。

二、整体架构

flowchart LR subgraph Browser FE[web-nest<br/>Next.js] end subgraph Server NG[Nginx HTTPS] GW[gateway :3010] US[user-service :3001] OS[order-service :3002] DB[(MySQL)] RD[(Redis)] end FE -->|admin 域名| NG --> FE FE -->|api 域名| NG --> GW GW --> US --> DB GW --> OS --> DB OS --> RD OS -.-> US

两个域名分工：

www.admin.chenchar.com → 前端静态/SSR 应用
api.chenchar.com → API 网关（登录 + 业务代理）

两个业务库分工（重要）：

服务	数据库
user-service	`nest_user_service`
order-service	`nest_order_service`

本地开发与线上都应保持「一服务一库」，不要两个服务共用一个 nest_db，否则容易出现「表在 A 库、服务连 B 库」的隐蔽问题。

三、技术栈一览

后端 ai-nest-backend

NestJS 11 + TypeScript + pnpm Monorepo
TypeORM + MySQL 8
Redis + BullMQ（订单异步通知）
Passport JWT（网关统一登录）
Swagger、限流、熔断降级
Docker Compose + Nginx

前端 nextjs-admin

Next.js 16（App Router）
React 19 + Tailwind + shadcn/ui
Axios + TanStack Query
Middleware 路由级鉴权
Cookie + Bearer 双通道传递登录态

四、后端设计亮点

4.1 API 网关：不只是转发

网关承担三件事：

POST /auth/login：调用 user-service 校验用户，签发 JWT
反向代理 ：/api/users → user-service，/api/orders、/api/products → order-service
横切能力 ：统一响应 { code, data, message }、Request ID、登录限流（5 次/分钟）、下游熔断

路由配置集中在 apps/gateway/src/config/proxy-routes.config.ts，扩展新服务时只需增加 prefix 映射。

4.2 订单服务：业务 + 队列

order-service 除了 CRUD，还包含：

库存调整日志 stock_adjustment_logs
BullMQ 异步通知 + Bull Board 可视化
跨服务 HTTP 查询 user-service 获取操作人信息

4.3 共享库

libs/common 提供全局异常过滤器与响应拦截器；libs/database 封装 TypeORM 连接，各服务通过 forFeature 注册实体，避免实体集中耦合。

五、前端设计亮点

5.1 登录链路（踩坑最多）

完整流程：

text 复制代码

1. 用户提交表单
2. POST api.chenchar.com/auth/login → 获得 access_token
3. POST /api/auth/session（Next Route Handler）→ Set-Cookie
4. 跳转首页 /
5. middleware 读取 cookie，校验 token 是否过期
6. 业务请求由 Axios 自动带 Authorization: Bearer <token>

关键认知：

浏览器里 document.cookie 能看到的 token，不等于 服务端 middleware 一定能收到（属性拼接错误、未走 Set-Cookie 等）。
JWT_SECRET 必须与网关一致，否则会出现「登录 200，但一进首页又被踢回登录页」。
Next.js 的 router.replace 偶发「软导航卡住」，需要 整页跳转兜底 （约 2 秒后若仍在 /auth 则 location.assign）。

5.2 路由守卫

middleware.ts 对非 /auth 路径校验 access_token；未登录则 302 到 /auth/sign-in?redirect=...，登录后可回到原目标页。

六、数据库：一键初始化（给协作者）

为降低「拉项目后不知道怎么建库」的成本，整理了 mysql/ 目录 + 一条命令：

text 复制代码

mysql/
├── 00-create-databases.sql
├── seeds/
│   ├── nest_user_service.sql
│   └── nest_order_service.sql
└── ...

bash 复制代码

cp .env.example .env
docker compose up -d mysql redis
pnpm db:init

脚本 scripts/db-init.sh 会：

自动检测 Docker MySQL 或本机 mysql 客户端
创建两个业务库
依次导入 seeds/*.sql（含表结构 + 演示数据）

git clone 后，一条 pnpm db:init 即可开工。

七、部署实战（腾讯云轻量）

7.1 编排一览

单机 Docker Compose 运行：

nginx（80/443）
gateway、user-service、order-service
web-nest（Next standalone）
mysql、redis

八、本地开发快速上手

bash 复制代码

# 后端
cd my-firstnest
pnpm install
cp .env.example .env
docker compose up -d mysql redis
pnpm db:init
pnpm dev          # 同时起 gateway / user / order

# 前端（新终端）
cd web-nest
npm install
# .env.local: NEXT_PUBLIC_API_BASE_URL=http://localhost:3010
npm run dev       # http://localhost:3000

网关 Swagger：http://localhost:3010/docs

九、总结

这个项目对我来说，价值不只在于「能跑起来」，而在于走完了一条完整的全栈交付链路：

领域拆分：用户库 / 订单库分离，网关统一出口
工程化：一键初始化 DB、Compose 编排、双域名 HTTPS
体验细节：登录态、Cookie、软导航、错误提示
运维现实：国内服务器拉 GitHub、Nginx 反代、容器重启排错

附录：仓库链接

后端 README：my-firstnest/README.md
前端 README：web-nest/README.md
MySQL 初始化说明：见后端 README「MySQL 数据初始化」章节

本文基于实际开发与上线过程整理，部署域名与仓库地址以当前环境为准。