GitHub - zeeklog/Nuct.js: Full-stack enterprise-level development framework based on Nest, supporting tenant isolation, RBAC, role-menu permission configuration, etc., suitable for rapid development of small and medium-sized applications. 基于Nest的全栈企业级开发框架，支持租户隔离、RBAC、角色菜单权限配置等，适用于快速开发中小型应用；

Focus on business. Let Nuct handle the infrastructure.

Enterprise-grade full-stack scaffold with NestJS + Vue3. Multi-tenant, RBAC, AI-assisted development via Cursor Rules & Skills.

English · 简体中文 · 繁體中文 · 日本語 · Русский

Rapid development scaffold for small-to-medium applications
Pre-configured Cursor Rules & Skills for AI-assisted development

Screenshots 📸

Overview ✨

Default account: admin / a123456 🔑
Multi-tenant isolation, RBAC, SSO support — suitable for admin dashboards and SaaS platforms

Project Structure 🧱

nuct/
├── backend/          # Admin backend (NestJS, port 7001)
├── backend-user/     # C-end user API (NestJS, port 8001)
├── frontend/         # Admin frontend (Vue3, port 8088)
└── README.md

Tech Stack 🛠

Layer	Technologies
Backend	NestJS, TypeScript, TypeORM, Redis, MySQL, JWT, Swagger, Bull
Frontend	Vue3, Vite5, Ant Design Vue4, TypeScript5, Pinia, UnoCSS

Technical Architecture 🏗

Overall Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                           Client Layer                                   │
├─────────────────────────────────────────────────────────────────────────┤
│  Admin Frontend (Vue3) :8088    │    C-end App (可接入 H5/小程序/App)     │
└──────────────┬─────────────────┴──────────────────┬────────────────────┘
               │                                     │
               ▼                                     ▼
┌──────────────────────────────┐    ┌──────────────────────────────────────┐
│  backend (Admin API) :7001   │    │  backend-user (C-end API) :8001      │
│  - 平台管理、RBAC、租户管理   │    │  - 登录/注册、菜单、租户配置          │
│  - 系统配置、任务、网盘等     │    │  - 与 backend 共用 DB + Redis         │
└──────────────┬───────────────┘    └──────────────────┬───────────────────┘
               │                                      │
               └──────────────────┬───────────────────┘
                                  ▼
               ┌──────────────────────────────────────┐
               │  MySQL 8.x  │  Redis  │  OSS (可选)   │
               └──────────────────────────────────────┘

Backend (Admin) — `backend/`

层级	组件	说明
HTTP	Fastify	高性能 HTTP 适配器
Auth	JWT + Passport	LocalStrategy、JwtStrategy，RSA 密码加密
ORM	TypeORM	MySQL 持久化
Cache	Redis	会话、限流、Bull 队列
Queue	Bull	定时任务、异步任务
Realtime	Socket.io + SSE	WebSocket 双网关、Server-Sent Events
Global	Throttler、CLS、EventEmitter	限流、请求上下文、事件总线

模块结构：

模块	路由前缀	说明
AuthModule	`/auth`, `/account`	登录、注册、验证码、登出、改密
TenantModule	`/system/tenants`	租户管理
SystemModule	`/system`	用户、角色、菜单、部门、字典、参数、日志、任务、在线、服务监控
ToolsModule	-	上传、存储、邮件
NetdiskModule	-	网盘管理
SseModule	`/sse`	SSE 推送
HealthModule	`/health`	健康检查
TasksModule	-	Bull 定时任务
SocketModule	-	WebSocket (AdminEventsGateway, WebEventsGateway)

Backend-user (C-end) — `backend-user/`

C 端专用 API，与 Admin 分离部署，仅保留 C 端所需接口：

接口	需登录	说明
`POST /auth/login`	否	登录（需传 `domain`、`tenantId`）
`POST /auth/register`	否	注册（需传 `tenantId`）
`GET /auth/captcha/img`	否	图形验证码
`GET /user/tenant?domain=xxx`	否	按域名获取租户列表
`POST /account/logout`	是	登出
`PATCH /account/password`	是	修改密码
`GET /user/menus?code=xxx`	是	按 Code 获取菜单树
`GET /user/config/:key`	是	按 key 获取租户参数配置

Frontend — `frontend/`

层级	技术	说明
框架	Vue 3 + Vite 5	SPA
UI	Ant Design Vue 4	组件库
状态	Pinia	状态管理
路由	Vue Router	动态路由（由后端菜单生成）
样式	UnoCSS + Less	原子化 + 变量
i18n	vue-i18n	多语言

Deployment

Docker Compose：MySQL、Redis、nest-admin-server、nest-admin-web
Monorepo：pnpm workspace，backend、backend-user、frontend 独立构建

Business Architecture 📋

Multi-tenant 多租户

概念	说明
租户表	`sys_tenant`（name, code, domain, status）
隔离方式	实体 `tenant_id` 字段，`TenantInterceptor` 自动过滤
域名匹配	同一域名可匹配多个租户，C 端登录需传 `domain` + `tenantId`
租户参数	`sys_tenant_param_config` 租户级配置

RBAC 权限模型

User ──► Role ──► Menu (Permission)

表	说明
sys_user	用户
sys_role	角色
sys_menu	菜单/权限（树形，type: 0=目录、1=菜单、2=按钮）
sys_user_roles	用户-角色多对多
sys_role_menus	角色-菜单多对多

权限格式：module:resource:action，如 system:user:list、system:user:create

动作约定：list、read/info、create、update、delete

核心数据表

表名	说明
sys_user	用户
sys_role	角色
sys_menu	菜单/权限
sys_dept	部门（树形，mpath）
sys_dict_type / sys_dict_item	字典类型/字典项
sys_config	系统参数
sys_task / sys_task_log	定时任务及日志
sys_login_log	登录日志
user_access_tokens / user_refresh_tokens	JWT 令牌
tool_storage	文件存储

业务模块划分

领域	模块	功能
认证	Auth	登录、注册、验证码、JWT、RSA 加密、邮件验证
租户	Tenant	租户 CRUD、域名配置、租户初始化
系统	System	用户、角色、菜单、部门、字典、参数、日志、任务、在线用户、服务监控
工具	Tools	文件上传、存储、邮件发送
网盘	Netdisk	网盘管理、概览
实时	SSE / Socket	服务端推送、WebSocket 双网关
任务	Tasks	Bull 定时任务调度

统一响应与异常

成功码：code = 200
业务错误：HTTP 200 + body.code 为业务码（见 error-code.constant.ts）
分页格式：{ items, meta: { itemCount, totalItems, itemsPerPage, totalPages, currentPage } }

Quick Links 🔗

Live demo: https://nuct.cn
GitHub: https://github.com/zeeklog/nuct
Gitee: https://gitee.com/zeeklog/nuct
Swagger API docs(admin): http://localhost:7001/api-docs/ (after backend starts)
Swagger API docs(client): http://localhost:8001/api-docs/ (after backend starts)

Requirements 📦

Node.js 20+
Docker 20.x+ (docker compose 2.17.0+)
MySQL 8.x+
pnpm package manager

Quick Start 🚀

Docker

cd backend
pnpm docker:up
# or
docker compose --env-file .env --env-file .env.production up -d --no-build

After startup:

Swagger(admin): http://localhost:7001/api-docs/
Swagger(client): http://localhost:8001/api-docs/

Stop containers:

cd backend
pnpm docker:down

Local Development

1. Clone

git clone https://github.com/zeeklog/nuct
cd nuct

2. Setup

Database: Run backend/deploy/sql/nest_admin.sql
Config: Copy .env.example → .env, .env.development.example → .env.development
RSA key (for password encryption):
```
cd backend
mkdir -p RSA_PRIVATE_KEY
openssl genrsa -out RSA_PRIVATE_KEY/rsa-private.pem 2048
```
Set RSA_PRIVATE_KEY_PATH=RSA_PRIVATE_KEY/rsa-private.pem in .env.

Optional — run MySQL/Redis via Docker:

cd backend
docker compose --env-file .env --env-file .env.development run -d --service-ports mysql
docker compose --env-file .env --env-file .env.development run -d --service-ports redis

3. Install & Run

pnpm install
pnpm migration:run   # in backend
pnpm dev

4. Access

Frontend: http://localhost:8088/
Swagger: http://localhost:7001/api-docs/

Subprojects 📁

Directory	Description	Port
backend/	Admin backend (NestJS)	7001
backend-user/	C-end user API (NestJS)	8001
frontend/	Admin frontend (Vue3)	8088

Database Migration 🗄

From project root:

pnpm migration:run      # Apply migrations
pnpm migration:generate # Generate migration
pnpm migration:revert   # Revert last migration

Run pnpm build in backend before migration if entities or DB config changed.

Cursor AI Rules 🤖

Pre-configured rules and skills in .cursor/ for AI-assisted development.

Rules

File	Description	Scope
`rules/00-project.mdc`	Project architecture & conventions	Always
`rules/01-frontend-style.mdc`	Frontend CSS & naming	Frontend
`rules/01-data-design.mdc`	DB design & RBAC model	Backend
`rules/02-backend.mdc`	NestJS backend conventions	`backend/*/.ts`
`rules/03-frontend.mdc`	Vue3 frontend conventions	`frontend/*/.{ts,vue}`
`rules/04-backend-docs.mdc`	Backend API reference	Backend
`rules/tenant-init.mdc`	Tenant initialization	`tenant/*/.ts`

Skills

Skill	Path	Use case
nest-admin-backend	`skills/nest-admin-backend/SKILL.md`	Backend APIs, controllers, services, migrations
nest-admin-crud	`skills/nest-admin-crud/SKILL.md`	Full CRUD module (entity, DTO, service, controller, menu, frontend)
nest-admin-permission	`skills/nest-admin-permission/SKILL.md`	RBAC, menus, `definePermission`, `sys_menu`

Contributing 🤝

Stars and PRs welcome.

Acknowledgments 🙏

Built on top of:

vue3-antdv-admin — Frontend template
sf-nest-admin — Backend base

License

BSL 1.1

Name		Name	Last commit message	Last commit date
Latest commit History 86 Commits
.cursor		.cursor
.nx		.nx
assets		assets
backend-user		backend-user
backend		backend
docs		docs
examples		examples
frontend		frontend
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
PROMOTION.md		PROMOTION.md
README.ja.md		README.ja.md
README.md		README.md
README.ru.md		README.ru.md
README.zh-CN.md		README.zh-CN.md
README.zh-TW.md		README.zh-TW.md
nx.json		nx.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Folders and files

Latest commit

History

Repository files navigation

Screenshots 📸

Table of Contents 📚

Overview ✨

Project Structure 🧱

Tech Stack 🛠

Technical Architecture 🏗

Overall Architecture

Backend (Admin) — backend/

Backend-user (C-end) — backend-user/

Frontend — frontend/

Deployment

Business Architecture 📋

Multi-tenant 多租户

RBAC 权限模型

核心数据表

业务模块划分

统一响应与异常

Quick Links 🔗

Requirements 📦

Quick Start 🚀

Docker

Local Development

1. Clone

2. Setup

3. Install & Run

4. Access

Subprojects 📁

Database Migration 🗄

Cursor AI Rules 🤖

Rules

Skills

Contributing 🤝

Acknowledgments 🙏

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Backend (Admin) — `backend/`

Backend-user (C-end) — `backend-user/`

Frontend — `frontend/`

Packages