# open-nestjs-server

**Repository Path**: yncykj/open-nestjs-server

## Basic Information

- **Project Name**: open-nestjs-server
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: LGPL-2.1
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Open NestJS Server

企业级 NestJS 微服务后端，提供完整的用户管理、RBAC 权限控制、系统配置、通知、审计、开放 API 与报表分析能力。

> 本文档是**使用文档的入口**。详细的安装、配置、认证、权限、API、部署与开发说明请见 [`docs/usage/`](docs/usage/) 目录。

---

## 技术栈

| 领域 | 选型 |
|------|------|
| 后端框架 | NestJS 11 |
| 语言 | TypeORM + PostgreSQL（推荐 14+；Docker 默认 `postgres:16`） |
| 服务间通信 | TCP（微服务）+ HTTP（API 网关） |
| 消息队列 | RabbitMQ（事件驱动，可选） |
| 缓存 | Redis（版本键失效模式） |
| 认证 | JWT（`@nestjs/jwt`）+ API Key |
| 包管理 | pnpm |
| 容器化 | Docker Compose |

---

## 架构总览

```mermaid
flowchart LR
  Client[客户端 / 前端] -->|HTTP :3000| GW[API 网关<br/>api-gateway]
  GW -->|TCP :3001| US[用户服务<br/>user-service]
  GW -->|TCP :3002| SS[系统服务<br/>system-service]
  US --> DB[(PostgreSQL)]
  SS --> DB
  US --> Redis[(Redis)]
  SS --> Redis
  SS --> RMQ[(RabbitMQ)]
```

- **api-gateway**：唯一 HTTP 入口，负责认证、路由、限流、WebSocket。默认端口 `3000`。
- **user-service**：用户 / 角色 / 权限 / 部门 / 用户组 / OAuth / API Key / 会话。TCP `3001`。
- **system-service**：健康检查、系统配置、缓存、审计、通知、任务队列、限流、存储、指标、告警、聚合分析。TCP `3002`。

项目布局：

```
open-nestjs-services
├── apps/
│   ├── api-gateway/      # HTTP 网关（对外）
│   ├── user-service/     # 用户域微服务（TCP）
│   └── system-service/   # 系统域微服务（TCP + RMQ）
├── libs/
│   ├── common/           # 守卫 / 拦截器 / 装饰器 / 异常过滤
│   ├── contracts/        # DTO 与跨服务接口契约
│   └── database/         # 实体与数据库迁移
├── docker/               # SQL 初始化脚本
├── docs/                 # 设计文档与本文档子集（usage/）
├── documents/            # PRD / 健康度 / 调试指南等
├── reports/              # 代码审查与修复报告
├── scripts/              # 种子脚本等工具
└── test/                 # 测试文件
```

---

## 核心能力

| 模块 | 说明 | 详细文档 |
|------|------|----------|
| 认证与授权 | JWT 登录/刷新、密码重置、邮箱验证、API Key、OAuth | [认证指南](docs/usage/03-authentication.md) |
| RBAC 权限 | 角色层级继承、权限隐含传播、SOD 互斥约束 | [RBAC 指南](docs/usage/04-rbac.md) |
| 用户管理 | 用户 CRUD、角色分配、部门、用户组、标签、自定义字段 | [API 参考](docs/usage/05-api-reference.md) |
| 系统管理 | 配置版本化、缓存、审计日志、限流、任务队列、存储 | [API 参考](docs/usage/05-api-reference.md) |
| 通知 | 邮件/短信/站内信/推送，消息中心已读未读，免打扰 | [功能总览](docs/usage/06-features.md) |
| 开放 API | API Key 配额限流、Webhook 出站、开发者门户 | [功能总览](docs/usage/06-features.md) |
| 报表 / BI | 聚合引擎、看板、CSV/Excel 导出 | [功能总览](docs/usage/06-features.md) |
| 账户自助恢复 | 找回密码、邮箱验证、真实 SMTP 发信 | [功能总览](docs/usage/06-features.md) |

---

## 快速开始

```bash
# 1. 安装依赖（需 Node >= 18, pnpm >= 8）
pnpm install

# 2. 准备环境变量
cp .env.example .env
# 编辑 .env：至少设置 JWT_SECRET、ENCRYPTION_KEY、STORAGE_SECRET、DB_*

# 3. 启动依赖（PostgreSQL / Redis / RabbitMQ）
docker-compose up -d postgres redis rabbitmq

# 4. 启动全部服务（开发模式，热重载）
pnpm start:all:dev

# 5. 初始化种子数据（角色/权限/部门/默认用户）
pnpm db:seed
```

启动后：

- API 网关：http://localhost:3000
- Swagger 交互式文档：**http://localhost:3000/api/docs**
- 健康检查：`GET /system/health`

默认管理员账号（种子数据）：`admin@example.com` / `Admin123!`

完整步骤见 [使用文档 · 快速开始](docs/usage/01-getting-started.md)。

---

## 使用文档导航

| 文档 | 内容 |
|------|------|
| [01 · 快速开始](docs/usage/01-getting-started.md) | 环境要求、安装、启动、种子数据与默认账号、首次登录 |
| [02 · 配置参考](docs/usage/02-configuration.md) | 全部环境变量说明、生产环境注意事项 |
| [03 · 认证指南](docs/usage/03-authentication.md) | JWT、刷新令牌、密码重置、邮箱验证、API Key、OAuth 与调用示例 |
| [04 · RBAC 权限指南](docs/usage/04-rbac.md) | 角色层级、权限传播、SOD 互斥、分配接口与示例 |
| [05 · API 参考](docs/usage/05-api-reference.md) | 全部 HTTP 端点目录（按域分组、标注鉴权方式） |
| [06 · 功能总览](docs/usage/06-features.md) | 账户恢复 / 开放 API / 通知 / 报表 BI 能力说明与详细设计链接 |
| [07 · 部署](docs/usage/07-deployment.md) | Docker Compose 部署、健康检查、生产清单 |
| [08 · 开发指南](docs/usage/08-development.md) | 脚本、数据库迁移、测试、调试入口 |

---

## 更多参考

- 架构与设计：[`docs/system_design.md`](docs/system_design.md)、[`docs/tech-architecture-extensibility.md`](docs/tech-architecture-extensibility.md)
- 扩展路线：[`docs/extension-directions.md`](docs/extension-directions.md)
- 调试指南：[`documents/debugging-guide.md`](documents/debugging-guide.md)
- 代码审查报告：[`reports/`](reports/)

---

## 许可证

MIT License