# @ackplus/nest-auth 中文文档

规范地址：https://npmcn.com/package/%40ackplus/nest-auth/

版本：2\.18\.0
npm 元数据更新时间：2026-11-03T08:05:33.794Z
中文译文更新时间：2026-11-06T16:23:28.116Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ackplus/nest-auth
原文对照：https://npmcn.com/package/%40ackplus/nest-auth/?lang=original
项目主页：https://github.com/ack-solutions/nest-auth#readme
源码仓库：https://github.com/ack-solutions/nest-auth

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8 MB，904 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：10 个
- peer 依赖：rxjs ^7\.8\.0，express ^4 \|\| ^5，typeorm ^0\.3\.21，@nestjs/core ^10 \|\| ^11，@nestjs/common ^10 \|\| ^11，@nestjs/swagger ^10 \|\| ^11，@nestjs/typeorm ^10 \|\| ^11，class-validator ^0\.14\.1，reflect-metadata ^0\.1\.13 \|\| ^0\.2\.0，class-transformer ^0\.5\.1，@nestjs/event-emitter ^2 \|\| ^3，@nestjs/platform-express ^10 \|\| ^11
- 首次发布：2025-05-05T06:16:12.408Z
- 最新版本发布：2026-11-03T08:05:33.577Z
- 近 30 天下载量：2752（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：215（近 12 个月 138 个）

## 中文简介

NestJS的认证和授权——JWT/cookie会话,刷新-token旋转,RBAC,多租期,MFA,OAuth/社会登录,无密码,API密钥,以及内置的管理员控制台.

## 安装

```sh
npm install @ackplus/nest-auth
```

也可以使用：`pnpm add @ackplus/nest-auth`、`yarn add @ackplus/nest-auth`、`bun add @ackplus/nest-auth`

## README

# @ackplus/nest-auth (英语)

[![npm version](https://img.shields.io/npm/v/@ackplus/nest-auth.svg)](https://www.npmjs.com/package/@ackplus/nest-auth) [![npm downloads](https://img.shields.io/npm/dm/@ackplus/nest-auth.svg)](https://www.npmjs.com/package/@ackplus/nest-auth) [![license](https://img.shields.io/npm/l/@ackplus/nest-auth.svg)](https://www.npmjs.com/package/@ackplus/nest-auth)

NestJS.Sessions,MFA,OAuth,无密码,多租,RBAC,审计记录,以及嵌入式管理控制台的全功能认证模块——所有类型安全端到结束.

> 📚 **完整文档: [ack-solutions.github.io/nst-auth (英语)](https://ack-solutions.github.io/nest-auth/)**

* * *

## 为什么

现代认证有一个长的清单:电子邮件+密码,OAuth,MFA,刷新-托肯旋转,RBAC,多租,审计日志,一个管理员控制台. 大多数团队将5个库(并拥有集成风险)粘合在一起,或购买主机供应商(并失去数据所有权). `@ackplus/nest-auth` 选择第三个路径 : **在自己的 NestJS 应用程序中安装的单一模块化库, 由自己的数据库支持**。 。 。 .

## 安装

```bash
pnpm add @ackplus/nest-auth @ackplus/nest-auth-contracts
```

必要的同伴依赖性 :

```bash
pnpm add @nestjs/common @nestjs/core @nestjs/typeorm @nestjs/swagger \
  @nestjs/event-emitter @nestjs/platform-express \
  typeorm class-validator class-transformer reflect-metadata rxjs
```

可选, 只有在您启用匹配功能时 :

| 特性 | 添加 |
| --- | --- |
| Cookie- 模式会议 | `cookie-parser` |
| 重写会话 | `ioredis` |
| 谷歌 OAuth( 谷歌 OAuth) | `google-auth-library` |
| 脸书 OAuth | `fb` |
| 苹果奥特 | `apple-auth` |
| 限制费率 | `@nestjs/throttler` |

[完整安装指南 −](https://ack-solutions.github.io/nest-auth/docs/getting-started/installation/)

## AI 编码代理

使用 Claude 代码, Codex, Cursor 或者另一个 AI 编码代理? 安装 Nest Auth 技能使其知道 SDK 的真实 API :

```bash
npx @ackplus/nest-auth-skill
```

它检测你的堆栈( 或通过) `--stack backend`),并且只添加代理指令文件;您的应用程序不会被更改.

## 包括什么

| 能力 | 页:1 |
| --- | --- |
| **9个登录方法** | 电子邮件 + 密码 + 密码 + 密码 无密码 OTP / 魔法链接 Google / Facebook 苹果 GitHub + API 键+自定义 OAuth 提供商 |
| **外交部** | TOTP 电子邮件 OTP 短信 OTP 寻回代码 被信任的设备代号 |
| **会议** | 数据库( 默认), Redis, 或 in- memory \\ 自动重现 \\ 刷新键旋转 \\ 密码- hash- prefix 无效 |
| **多重租赁** | `disabled` 编号 : `shared` 编号 : `isolated` \* 租户意识装饰者 |
| **非洲区域局** | 角色 + 每个守护命名空间的权限(网络、api、移动) 外部境内流离失所者友好化 |
| **嵌入式管理控制台** | 用于用户、角色、权限、租户、 API 密钥的内建 React UI |
| **钩子事件( E)** | 每个生命周期的时刻都是压倒一切的 `EventEmitter2` 融合 |
| **审计记录** | 合规结构化事件钩 |
| **打开API** | 自动生成 `@nestjs/swagger` 每个端点的 spec |

## 最小示例

```ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { EventEmitterModule } from '@nestjs/event-emitter';
import { NestAuthModule, NestAuthEntities } from '@ackplus/nest-auth';

@Module({
  imports: [
    EventEmitterModule.forRoot(),
    TypeOrmModule.forRoot({
      type: 'postgres',
      url: process.env.DATABASE_URL,
      entities: [...NestAuthEntities],
      synchronize: process.env.NODE_ENV === 'development',
    }),
    TypeOrmModule.forFeature([...NestAuthEntities]),

    NestAuthModule.forRoot({
      appName: 'My App',
      session: { jwt: { secret: process.env.JWT_SECRET! } },
      // emailAuth: { enabled: true },        // default
      // google: { clientId, clientSecret },  // opt-in OAuth
      // mfa: { enabled: true, required: true },
      // tenant: { enabled: true, mode: TenantModeEnum.SHARED },
    }),
  ],
})
export class AppModule {}
```

就是这样,你立刻得到 `POST /auth/signup`, (中文(简体) ), `POST /auth/login`, (中文(简体) ), `/auth/refresh-token`,密码重置,MFA,OAuth调用,其余API. 线 `EventEmitterModule.forRoot()`, (中文(简体) ), `cookie-parser`,则 `AuthExceptionFilter` 从 [设置清单](https://ack-solutions.github.io/nest-auth/docs/getting-started/setup-checklist/) 还有船.

## 文档

| 节次 | 这是什么 |
| --- | --- |
| [开始](https://ack-solutions.github.io/nest-auth/docs/getting-started/) | 安装、 数据库设置( 3个路径) , env vars, 快速启动后端 / react / Next.js / vanilla |
| [核心概念](https://ack-solutions.github.io/nest-auth/docs/concepts/) | 会议、用户模式、多租期、非洲区域局、外交部、活动、审计 |
| [认证](https://ack-solutions.github.io/nest-auth/docs/authentication/) | 每个登录方法一页 |
| [后端引用](https://ack-solutions.github.io/nest-auth/docs/backend/) | 模块配置, 实体, 装饰者, 守卫, 服务, 钩子, 事件, 错误代码, 管理员控制台 |
| [生产](https://ack-solutions.github.io/nest-auth/docs/production/) | 电子邮件/短信接线、JWT定制、缩放、CORS和安全、测试 |
| [食谱](https://ack-solutions.github.io/nest-auth/docs/recipes/) | 20个复制相贴解决方案——转介代码,定制OAuth,租户切换器等. |
| [API 参考](https://ack-solutions.github.io/nest-auth/docs/api-reference/) | 自动生成的 REST + 类型脚本类型 |
| [FAQ 解决问题( T)](https://ack-solutions.github.io/nest-auth/docs/faq/) | 错误代码 – 可能造成 – 修正 |

## 配套软件包

| 软件包 | 使用时间 |
| --- | --- |
| [`@ackplus/nest-auth-client`](https://www.npmjs.com/package/@ackplus/nest-auth-client) | Vanilla JS / Vue / Angular / Svelte / 反应土著客户端 |
| [`@ackplus/nest-auth-react`](https://www.npmjs.com/package/@ackplus/nest-auth-react) | 反应提供者、钩子、卫士和Next.js App路由器帮助器 |
| [`@ackplus/nest-auth-contracts`](https://www.npmjs.com/package/@ackplus/nest-auth-contracts) | 共有的TS类型——全部由这三类人消费 |

所有4个包都与同版本号一起放出. 把它们绑在同一个版本.

## 链接

-   📚 [文档](https://ack-solutions.github.io/nest-auth/)
-   💬 [问题跟踪器](https://github.com/ack-solutions/nest-auth/issues)
-   📦 [GitHub 仓库](https://github.com/ack-solutions/nest-auth)

## 许可证

[麻省理工学院](https://github.com/ack-solutions/nest-auth/blob/main/LICENSE)

## 常见问题

### @ackplus/nest-auth 是什么？

NestJS的认证和授权——JWT/cookie会话,刷新-token旋转,RBAC,多租期,MFA,OAuth/社会登录,无密码,API密钥,以及内置的管理员控制台\.

### 如何安装 @ackplus/nest-auth？

在项目目录运行 npm install @ackplus/nest-auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：rxjs（^7\.8\.0）、express（^4 \|\| ^5）、typeorm（^0\.3\.21）、@nestjs/core（^10 \|\| ^11）、@nestjs/common（^10 \|\| ^11）、@nestjs/swagger（^10 \|\| ^11）、@nestjs/typeorm（^10 \|\| ^11）、class-validator（^0\.14\.1）、reflect-metadata（^0\.1\.13 \|\| ^0\.2\.0）、class-transformer（^0\.5\.1）、@nestjs/event-emitter（^2 \|\| ^3）、@nestjs/platform-express（^10 \|\| ^11）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @ackplus/nest-auth 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @ackplus/nest-auth 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @ackplus/nest-auth 可以商用吗？

@ackplus/nest-auth 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @ackplus/nest-auth 的下载量有多少？

根据 npm 官方下载统计，@ackplus/nest-auth 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,752 次，日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ackplus/nest-auth 还在维护吗？

最新版本 2\.18\.0 发布于 2026/11/03（4 天前）；至今共发布 215 个版本，其中过去 12 个月发布了 138 个；首次发布于 2025/05/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。