# 栖梧 Qiwu > Node 全栈管理后台模板：NestJS + Vue 3 + Element Plus，MIT 开源 ## 目录 ### 开始 - [介绍](https://qiwuadmin.com/guide/introduction.md): 栖梧（Qiwu）是基于 NestJS 和 Vue 3 的 Node 全栈管理后台模板：在线演示账号、适合人群、技术栈、与 RuoYi 等 Java 模板的区别和完整功能清单。 - [项目由来](https://qiwuadmin.com/guide/story.md): 作者讲述做栖梧的原因：Node 缺少功能齐全、默认安全的开源后台，小项目用 Node 的人力、服务器和开发成本更低；以及面向谁、为什么用 MIT 开源。 - [快速开始](https://qiwuadmin.com/guide/getting-started.md): 在本机 10 分钟跑起栖梧：Node.js、pnpm、MySQL 和 Redis 的版本要求，建库、配置 .env.local、初始化数据库并启动，再用新项目脚本创建自己的项目。 - [目录结构](https://qiwuadmin.com/guide/structure.md): 单仓库的目录结构：后端 apps/server 的分层规则和模块组成，前端 apps/web 的页面、接口与样式目录，以及前后端共享包 packages/shared 里放什么。 ### 开发 - [新增业务模块](https://qiwuadmin.com/guide/new-module.md): 以 CRM 客户表为例，从建菜单分组、写迁移建表、导入并配置代码生成器，到粘贴注册代码、执行种子和给角色授权，完整新增一个业务模块。 - [部署](https://qiwuadmin.com/guide/deploy.md): 把栖梧部署到生产服务器：构建与生产环境变量、迁移和种子数据、nginx 反向代理与 CSP、PM2 守护进程、S3 存储、OAuth2、演示模式和多实例部署要求。 ### 写给前端开发者 - [先看这里：写给前端开发者](https://qiwuadmin.com/backend.md): 写给只写过 Vue 的前端开发者的后端入门：后端负责什么，用前端概念类比控制器、服务、守卫和迁移，推荐的学习路线和几条最重要的后端规矩。 - [一个请求的一生](https://qiwuadmin.com/backend/request-lifecycle.md): 跟着一次岗位列表查询，从页面、axios 拦截器、Vite 代理走到 NestJS 的中间件、守卫、管道、控制器、服务和 SQL，再回到页面，建立对后端的整体印象。 ### 基础概念 - [NestJS 基础](https://qiwuadmin.com/backend/nestjs.md): 以岗位模块为例讲 NestJS 基础：装饰器、控制器路由、服务与 BaseCrudService、依赖注入、模块注册，守卫、管道、拦截器、过滤器的分工，以及抛出业务错误。 - [数据库基础](https://qiwuadmin.com/backend/database.md): 给前端开发者的 MySQL 入门：表与列类型、常用 SQL、TypeORM 实体与 QueryBuilder、防止 SQL 注入、索引、事务与行锁、迁移、逻辑删除和时区处理。 - [Redis 是做什么的](https://qiwuadmin.com/backend/redis.md): 用 localStorage 类比理解 Redis：项目用它存令牌、验证码、缓存、限流和任务锁，键名统一生成，写库时让缓存失效，以及怎样用命令行查看数据。 - [登录是怎么回事](https://qiwuadmin.com/backend/auth.md): 面向前端开发者讲解后端登录机制：访问令牌与刷新令牌的分工、为什么令牌放在内存和 HttpOnly cookie 而不是 localStorage、服务端会话存储与自动刷新流程。 ### 动手 - [手把手：加一个自定义操作](https://qiwuadmin.com/backend/tutorial.md): 从迁移、实体、共享包、错误码、服务、控制器、种子到前端按钮、翻译和 e2e 测试，完整实现客户“升级为 VIP”操作，演示事务加锁与权限检查的标准写法。 - [写测试](https://qiwuadmin.com/backend/testing.md): 后端 e2e 测试入门：单元测试与 e2e 测试的区别，用 Vitest 和 supertest 测接口的完整示例，每个接口至少要测的状态码，运行单个测试文件和独立测试库。 - [排查问题](https://qiwuadmin.com/backend/debugging.md): 后端排查问题：用 traceId 对照日志、用 Swagger 绕开前端调接口、直接查数据库，以及 404、403、400、依赖注入失败、pnpm verify 不通过的常见原因。 ### 准备 - [先看这里：写给学生和编程新手](https://qiwuadmin.com/beginner.md): 写给在校学生和编程新手的从零入门教程导读：学完能收获什么、各部分大约耗时、怎样按顺序阅读、遇到报错如何处理，以及对 Mac 和 Windows 电脑的要求。 - [网站是怎么工作的](https://qiwuadmin.com/beginner/how-web-works.md): 用餐厅打比方讲清网站如何工作：一次请求从浏览器到后端再到数据库的全过程，URL 结构、HTTP 方法与状态码、JSON 和数据表，附小测验，适合零基础新手。 - [终端入门](https://qiwuadmin.com/beginner/terminal.md): 写给新手的终端入门：在 Mac 终端和 Windows PowerShell 里用 pwd、ls、cd 等常用命令，理解提示符和路径，处理 command not found。 - [安装开发环境（Mac）](https://qiwuadmin.com/beginner/install-mac.md): 在 Mac 上依次安装 Xcode 命令行工具、Homebrew、Node.js 22、pnpm、MySQL、Redis 和 VS Code，每一步都用命令确认装好。 - [安装开发环境（Windows）](https://qiwuadmin.com/beginner/install-windows.md): 在 Windows 上用 PowerShell 5.1 安装 Git、Node.js 22、pnpm、MySQL、Memurai 和 VS Code，设置执行策略并排查常见问题。 ### 上手 - [第一次把项目跑起来](https://qiwuadmin.com/beginner/first-run.md): 在 macOS 或 Windows 上第一次运行栖梧的 7 个步骤：克隆代码、安装依赖、创建 MySQL 数据库和用户、配置环境变量文件、初始化数据库、启动并登录，附常见报错。 - [逛一逛后台](https://qiwuadmin.com/beginner/admin-tour.md): 第一次进入栖梧后台：了解界面布局和各组菜单的用途，再动手创建只读角色和用户，体验按钮级权限、实时生效的授权、强制下线和操作日志。 - [第一次改代码](https://qiwuadmin.com/beginner/first-change.md): 新手的第一次改代码练习：修改菜单翻译文字、默认隐藏表格列、给共享校验规则加正则让前后端同时生效，读懂控制器装饰器，最后用 Git 撤销修改。 - [做第一个模块：课程管理](https://qiwuadmin.com/beginner/first-module.md): 跟着做一个完整的课程管理模块：设计数据表、写迁移建表、用代码生成器配置并写入代码、手动注册并执行种子，得到带权限、日志、导入导出和测试的增删改查页面。 - [用 Git 保存进度](https://qiwuadmin.com/beginner/git.md): 面向新手的 Git 入门：用 status、add、commit 保存进度，用 diff 和 log 查看修改，按约定格式写提交说明，改坏后用 checkout 恢复。 ### 遇到问题 - [看不懂报错怎么办](https://qiwuadmin.com/beginner/errors.md): 教新手读懂报错：从调用栈里找出关键的一行、常见英文词的含义，安装启动和写代码时的常见报错与 HTTP 状态码速查，以及怎样提问更容易得到帮助。 - [术语表](https://qiwuadmin.com/beginner/glossary.md): 编程新手术语表：前端、后端、端口、HTTP 状态码、JSON、Git、pnpm、数据库迁移、Redis 缓存，以及权限点、数据范围、字典等项目概念的通俗解释。 - [接下来学什么](https://qiwuadmin.com/beginner/next.md): 完成新手教程后的进阶路线：在课程管理里练习字典下拉框、业务规则、自定义按钮、树表和主子表，延伸阅读项目文档，并附 Vue 3、NestJS、SQL、Git 等学习资料。 ### 写给 Java 开发者 - [先看这里：写给 Java 开发者](https://qiwuadmin.com/java.md): 写给 Spring Boot 和 RuoYi 开发者的入门：要补哪些运行时、TypeScript 和前端知识，推荐的学习顺序，Java 概念总对照表，以及选 Node 的得与失。 - [Node.js 和 JVM 的差异](https://qiwuadmin.com/java/node-runtime.md): 写给 Java 开发者的 Node.js 运行模型：单线程事件循环、漏写 await 的坑、避免阻塞主线程、用 CLS 代替 ThreadLocal、并发与锁、数字精度和部署。 - [TypeScript 速成](https://qiwuadmin.com/java/typescript.md): TypeScript 与 Java 的不同之处：类型运行时被擦除需用 zod 校验、结构类型、null 与 undefined、相等比较、字面量联合代替枚举、ESM 导入和装饰器。 - [Spring Boot 对照 NestJS](https://qiwuadmin.com/java/spring-to-nest.md): Spring Boot 与 NestJS 并排对照：控制器、依赖注入和模块、zod 校验、全局异常、事务、MyBatis 与 TypeORM、配置、拦截器、定时任务、日志和测试。 - [从 RuoYi 过来](https://qiwuadmin.com/java/from-ruoyi.md): 给 RuoYi、芋道用户的对照：权限、数据范围、返回格式、操作日志、登录令牌、字典、定时任务、代码生成和工作流在这里怎么写，以及迁移老项目的建议。 - [前端速成：Vue 3](https://qiwuadmin.com/java/vue-primer.md): 帮后端开发者看懂、改动生成页面的 Vue 3 速成：script setup、响应式变量、模板语法、props 与事件、组合式函数、Element Plus、接口调用和菜单路由。 ### 总览 - [开发指南总览](https://qiwuadmin.com/core.md): 栖梧开发指南总览：按后端核心、后端功能、前端核心和移动端列出各参考页，帮你快速找到控制器、服务、查询、权限、定时任务、Excel 等用法所在的页面。 ### 后端核心 - [模块结构与注册](https://qiwuadmin.com/core/module.md): 模块在后端、共享包和前端的固定文件结构，从表名推导领域和业务名的规则、各层之间的依赖限制、跨模块注入服务，以及新模块要在哪 4 个地方注册。 - [控制器](https://qiwuadmin.com/core/controller.md): NestJS 控制器写法详解：路由与固定路径顺序、生成的标准增删改查接口、zod 校验查询参数与请求体、文件上传与下载、返回值包装和状态码、权限日志与 Swagger 装饰器一览。 - [服务](https://qiwuadmin.com/core/service.md): 后端服务层写法：继承 BaseCrudService 并覆写 filter 和增删改方法，按 id 修改时加锁、事务与提交后的操作、树形数据、主子表、多对多关系和原生 SQL。 - [实体与数据库](https://qiwuadmin.com/core/entity.md): TypeORM 实体的写法：基类和审计列、MySQL 列类型对照、只读关联、用 referencedBy 代替外键、数据范围声明，以及迁移的建表约定和执行回退。 - [查询](https://qiwuadmin.com/core/query.md): 后端查询的三种方式：带数据范围的 scopedQb 和 QueryBuilder、参数化条件、pageQuery 分页排序、联表和子查询、原生 SQL 的规则、行锁和性能建议。 - [参数校验](https://qiwuadmin.com/core/validation.md): 用 zod 在共享包里定义前后端共用的校验规则：常用写法、blankAsNull、错误提示和字段名的翻译、校验失败的 400 返回格式，以及依赖运行时配置的规则。 - [异常处理](https://qiwuadmin.com/core/errors.md): 服务端抛出 BizError 和 NestJS 异常、新增带中英文翻译的错误码、号段划分、统一的错误响应格式和 traceId，以及前端按错误码处理和排查问题。 - [种子与菜单](https://qiwuadmin.com/core/seed.md): 用幂等的种子预置菜单、按钮权限、字典和参数：upsert 三段参数的含义、菜单字段、项目菜单分组、隐藏页面、注册种子，以及首次执行时打印的密码。 ### 后端功能 - [在代码中使用权限与数据范围](https://qiwuadmin.com/core/permission.md): 服务端功能权限和数据范围的写法：权限点格式、@RequirePerm、在实体上声明数据范围、scopedQb 和 lockScopedIds、范围外一律返回 404 和防越权授予。 - [缓存](https://qiwuadmin.com/core/cache.md): 后端 Redis 缓存的规范写法：登记命名空间，用 redisKey() 生成键并读写，先提交事务再删缓存，以及带版本号的 readThrough 进阶写法。 - [防重复提交、限流与锁](https://qiwuadmin.com/core/guards.md): @Idempotent 防重复提交、@RateLimit 按 IP 限流和 RedisLock 分布式锁：各自的判断依据、何时返回 429、锁的自动续期，以及该用哪一个。 - [定时任务开发](https://qiwuadmin.com/core/job.md): 用 @JobHandler 写定时任务处理器：zod 参数规则、signal 和 log、用种子预置任务、支持的 Cron 写法，并发、错过策略、超时和重试配置，以及内置处理器。 - [消息通知](https://qiwuadmin.com/core/notify.md): 用 Notifier.send() 发站内信、邮件和短信：收件人和参数的写法、按收件人的语言和时区渲染、用种子预置多语言模板，以及事务提交后才发送和失败补发。 - [在代码中推送实时消息](https://qiwuadmin.com/core/realtime.md): 用 RealtimeService 经 Socket.IO 推送实时消息、前端用 onRealtime 订阅，涵盖新增推送类型、事务提交后推送、断线兜底、移动端和多实例部署。 - [文件上传](https://qiwuadmin.com/core/upload.md): 在表单里用 ImageUpload、FileUpload 和 uploadField 上传图片与附件：公开和私有业务标签、大小上限、服务端检查，以及私有文件的显示和下载权限。 - [Excel 导入导出](https://qiwuadmin.com/core/excel.md): Excel 导出、导入模板和导入的代码说明：列定义的各个字段、分批导出与公式转义、insert 和 upsert 导入模式、失败行的错误报告和导入限制。 - [富文本](https://qiwuadmin.com/core/richtext.md): 富文本的 XSS 防护：RichEditor 编辑器的用法，服务端保存时按白名单清洗 HTML 的规则，以及只有清洗过的内容才能用 v-html 显示。 - [字典](https://qiwuadmin.com/core/dict.md): 字典的开发写法：用种子预置字典、重新执行种子时哪些不覆盖、用数据迁移改已有文字，以及 DictSelect、DictTag、useDict 和 DictService 的用法。 - [参数设置](https://qiwuadmin.com/core/param.md): 用 ParamService 读取管理员能在后台修改的参数：int() 等兜底读取、键名和默认值放在共享包、用种子新增参数、敏感参数，以及 Redis 缓存何时失效。 - [操作日志](https://qiwuadmin.com/core/action-log.md): 用 @ActionLog 为接口记录操作日志：domain、verb、bizId 选项，何时用 @SkipActionLog，记录内容、敏感字段脱敏、API 访问日志和保留时间。 - [在代码中使用国际化](https://qiwuadmin.com/core/i18n.md): 后端、共享包和数据库内容怎么做国际化：翻译文件的位置与合并规则、请求语言的判定、错误信息和种子名称的翻译、*_i18n 列、i18n:check 检查，以及增加一种语言。 ### 前端核心 - [接口请求](https://qiwuadmin.com/core/web-request.md): 前端请求层 http.ts 的用法：按模块写接口文件和 crudApi，令牌过期自动刷新重发，错误提示规则，ApiError 与 silent，文件上传下载和开发代理配置。 - [路由与菜单](https://qiwuadmin.com/core/web-router.md): 后端按权限下发菜单生成前端路由：菜单类型、无权限时显示 404、keep-alive 页面缓存、隐藏页面的跳转与传参、固定路由和保留名，以及路由守卫的流程。 - [列表页](https://qiwuadmin.com/core/crud-list.md): 后台标准列表页：useCrudList 管理查询、分页、排序、删除和导出，QwTable 列定义与用户列设置，TableToolbar、Pagination、时间显示和行内开关。 - [表单弹框](https://qiwuadmin.com/core/crud-form.md): 新增和编辑共用的表单弹框：useCrudForm 用共享 zod 规则校验、加载和提交，openDialog 以 Promise 方式打开弹框，以及只在新增时显示的字段。 - [权限与翻译](https://qiwuadmin.com/core/web-perm-i18n.md): 前端页面里按权限显示按钮（v-perm 指令和 usePerm），用 vue-i18n 的 t() 和 tx() 翻译文字，翻译文件的存放与命名规则，以及切换界面语言。 - [常用组件](https://qiwuadmin.com/core/web-components.md): 前端自带组件速查：表格与左侧树、可编辑明细表、字典和部门等表单输入、openDialog 弹框、组合式函数、Pinia 状态、Lucide 图标以及 --qw-* 样式变量的用法。 ### 移动端 - [移动端开发](https://qiwuadmin.com/core/mobile.md): uni-app 移动端开发手册：H5、微信小程序和 App 的运行调试，基础层和常用组件，新增页面、构建打包、微信登录、App 更新、发布清单，以及只要电脑端时怎么删除。 ### 总览 - [功能总览](https://qiwuadmin.com/features.md): 按菜单列出栖梧的功能：系统管理、登录、单点登录、权限、监控、定时任务、消息、文件、代码生成、表单设计、工作流、移动端、国际化和安全基线。 ### 系统 - [系统管理](https://qiwuadmin.com/features/system.md): 系统管理各页面的用法：用户、角色、菜单、部门、岗位、字典和参数设置，App 版本发布与更新检查，地区与 IP 归属地查询，OAuth2 客户端和个人中心。 - [登录与账号](https://qiwuadmin.com/features/login.md): 账号密码、短信和微信小程序登录，滑块与图形验证码、注册、找回密码、密码策略、失败锁定、会话时长、在线用户强退和个人中心的规则与参数。 - [单点登录（OAuth2）](https://qiwuadmin.com/features/oauth.md): 把栖梧用作 OAuth2 授权服务器：登记客户端与密钥、授权同意页、记住授权、第三方会话和令牌有效期，以及 PKCE、不支持 OIDC 等接入限制。 - [权限与数据范围](https://qiwuadmin.com/features/permission.md): 功能权限与数据范围两层授权：权限点、给角色授权、五种数据范围、多个角色时怎样合并、超出范围返回 404、防越权授予规则和超级管理员的保护。 - [监控与日志](https://qiwuadmin.com/features/monitor.md): 在线用户与强制下线，服务器、Redis 和 MySQL 的监控页面，缓存列表与清理，操作、登录、API 访问和错误日志的查询，追踪 ID 与日志保留清理。 - [定时任务](https://qiwuadmin.com/features/job.md): 定时任务的新增与配置：Cron 表达式写法、超时、失败重试、并发与错过策略，调度日志、内置任务，以及多实例部署时任务只执行一次的规则。 - [消息中心](https://qiwuadmin.com/features/messaging.md): 通知公告、站内信、邮件、短信和微信订阅消息的配置：模板占位符与多语言、SMTP 账号、阿里云和腾讯云短信渠道与回执、发送记录和失败补发。 - [文件管理](https://qiwuadmin.com/features/storage.md): 文件存储与上传：本地磁盘和 S3 兼容存储的配置、访问密钥加密与 SSRF 限制、公开和私有文件、上传检查规则、浏览器直传 S3，以及删除和清理。 ### 开发工具 - [代码生成器](https://qiwuadmin.com/features/codegen.md): 代码生成器按表名生成后端、前端、zod 规则、菜单权限和 e2e 测试，支持单表、树表、主子表及可选的移动端页面，并说明数字精度和零手改模块。 - [表单设计器](https://qiwuadmin.com/features/formkit.md): 拖拽设计表单：可用的基础、业务和计算组件，天数与明细表合计的计算规则，导出 JSON 和 Vue 代码，以及保存时的安全白名单检查。 ### 审批 - [工作流](https://qiwuadmin.com/features/workflow.md): 栖梧自研的树形审批流程引擎：零代码新建审批、树形与 BPMN 设计器、审批人与分支、审批动作、超时自动处理、动态表单字段权限和审批数据查询。 ### 移动端 - [移动端](https://qiwuadmin.com/features/mobile.md): 栖梧的员工移动端基于 uni-app，同时支持微信小程序和安卓、iOS App：登录、工作台、审批与动态表单、消息、实时推送、App 更新和后台需要的配置。 ### 全局能力 - [国际化](https://qiwuadmin.com/features/i18n.md): 栖梧内置简体中文和英文，界面、错误信息、校验提示、菜单、字典、消息模板和 Excel 都随语言切换；含语言判断顺序、时区、自动检查和新增语言步骤。 - [实时推送](https://qiwuadmin.com/features/realtime.md): 基于 WebSocket 和 Socket.IO 的实时推送：哪些事件即时送达、断线重连、连接安全、推送示例页，以及反向代理、多实例和移动端的部署要点。 - [安全基线](https://qiwuadmin.com/features/security.md): 默认开启的安全措施：随机令牌会话、登录限流与锁定、微信与 OAuth2 登录规则、防越权、参数化 SQL、XSS 防护、文件上传和 SSRF 限制，以及漏洞报告方式。 ### 参考 - [API 约定](https://qiwuadmin.com/reference/api.md): 后端接口约定速查：路径与资源命名、标准增删改查路由、分页参数、统一响应和错误格式、HTTP 状态码、业务错误码分段、时间与时区规则，以及 OAuth2 接口的例外。 - [命令](https://qiwuadmin.com/reference/commands.md): 仓库根目录的 pnpm 命令速查：日常开发、数据库迁移与种子、代码生成及一致性检查、verify 和 ci:local 等检查与测试命令，以及在 Windows 上的验证情况。 - [环境变量](https://qiwuadmin.com/reference/env.md): 服务端 .env、.env.local 等配置文件的分工和加载顺序，账号密钥该放在哪里，以及服务、数据库与 Redis、安全、功能、前端各项环境变量的默认值和说明。 - [OAuth2 接入指南](https://qiwuadmin.com/reference/oauth2.md): 第三方系统接入 OAuth2 的指南：登记客户端、授权码 + PKCE、刷新令牌、userinfo、introspect、revoke 和客户端凭证，附命令示例、错误码与限流说明。 ### Other - [更新日志](https://qiwuadmin.com/changelog.md): 栖梧各正式版本的更新日志：1.0.0 版包含的权限、多语言、代码生成、工作流、OAuth2、移动端、安全与部署等功能，以及多租户、OIDC、Docker 等已知限制。