• 后端
• 前端
• 企业应用
• MCP 服务

@gauzy/ui-auth是 Ever Gauzy 开源业务管理平台（ERP/CRM/HRM/ATS/PM，仓库地址 README.md）中负责认证场景的 Angular 前端库，集中提供登录、注册、找回密码、邀请接受、OAuth 授权、魔法登录（magic sign-in）等全套认证组件与路由守卫。本指南以 packages/ui-auth/README.md 为主体，结合该库在 packages/ui-auth/src 下的源码实现，系统讲解它的组件体系、路由结构、工作流原理，以及基于 Nx 工作区的构建、测试、发布与安装全流程。读完本文，你将掌握如何在 Gauzy 生态中复用它、如何理解其认证页面背后的工作流，并能直接运行命令完成该库的开发与发布。

库定位：Gauzy 平台专用的认证前端模块

根据 packages/ui-auth/README.md 的说明，@gauzy/ui-auth提供「为 Gauzy 平台量身定制的认证相关组件、服务与工具」，目标是实现「流式且安全的用户认证与用户管理」。它不是一个通用认证库，而是深度绑定 Gauzy 生态：

• 依赖@gauzy/ui-core/core（提供AuthService、NoAuthGuard、PageRouteRegistryService、Store等核心服务）、@gauzy/ui-core/theme、@gauzy/ui-core/shared、@gauzy/contracts、@gauzy/constants等仓库内部包（见 package.json）；
• 底层基于 Nebular 的@nebular/auth与@nebular/theme，因此多数组件（如NgxLoginComponent）直接继承自 Nebular 的NbLoginComponent，并在其上进行 Gauzy 特有能力的扩展。

从 index.ts 的公开 API 面看，该库对外只暴露 4 类内容：

export * from './lib/auth.module'; export * from './lib/auth.routes'; export * from './lib/sign-in-success/sign-in-success.component'; export * from './lib/sign-in-success/sign-in-success.module';

即：模块（NgxAuthModule）、路由工厂（createAuthRoutes）以及「登录成功」组件/模块（主要用于 OAuth 回跳场景）。

组件体系：覆盖完整认证生命周期的预构建组件

该库在 packages/ui-auth/src/lib/components 下组织了一整套认证组件，按功能划分如下：

从 auth.module.ts 的模块声明看，NgxAuthModule通过declarations: [...COMPONENTS]一次性注册了上述全部组件，并导入了 Nebular 的按钮、卡片、表单、对话框、图标、选择器等模块，以及TranslateModule.forChild()（国际化）和@gauzy/ui-core的主题、共享模块。

登录组件的三个扩展层次

登录是认证体系的核心，该库提供了三个层次互补的实现：

1. NgxLoginComponent（经典账号密码登录）：继承NbLoginComponent，在此基础上加入：

   • Remember Me 记忆功能：通过ngx-cookie-service读取rememberMeCookie 自动回填邮箱（见checkRememberdMe()）；
   • Demo 环境自动填充：读取@gauzy/ui-config的environment.DEMO等配置，在演示环境自动填充超级管理员账号，并支持autoLogin(role)按RolesEnum.SUPER_ADMIN / ADMIN / EMPLOYEE一键切换演示角色后直接提交表单（见 login.component.ts）；
   • 密码格式校验：复用@gauzy/constants中的patterns.passwordNoSpaceEdges正则，约束密码首尾不能有空格。

2. NgxLoginWorkspaceComponent（多工作区登录）：面向 Gauzy 多租户架构。提交邮箱密码后调用AuthService.findWorkspaces({ email, password })，后端返回该用户可访问的所有工作区（IWorkspaceResponse[]）。如果total_workspaces === 1会自动免选登录；否则弹出工作区选择器，用户选定后用signinWorkspaceByToken({ email, token })换取正式会话，并将user、token、refresh_token、tenantId等写入Store后跳转首页（见_handleLoginResponse）。它对应的注册路由为login-workspace。

3. 魔法登录（无密码）：NgxLoginMagicComponent先用邮箱调用AuthService.sendSigninCode({ email })发送一次性验证码，输入 6 位（长度由@gauzy/constants的ALPHA_NUMERIC_CODE_LENGTH约束）验证码后跳转到auth/magic-sign-in；NgxMagicSignInWorkspaceComponent在该路由上用confirmSignInByCode({ email, code })校验并拉取工作区列表，同样支持单工作区自动登录；验证码输入错误时展示错误状态并在 5 秒后跳回auth/login-magic（见 magic-login-workspace.component.ts）。发送成功后邮箱输入框会被禁用，重发验证码带 30 秒倒计时（见startTimer()）。

认证外壳：路由分发与回跳处理

NgxAuthComponent是所有认证页面的父布局，继承自 Nebular 的NbAuthComponent。它有两个值得关注的职责：

• 按 URL 切换页面样式：updateAuthPageClasses(url)通过url.split('?')[0]去除查询串后判断当前是否为/auth/register或/auth/login，从而控制外壳的展示形态（例如注册页与登录页不同的侧栏布局）；
• returnUrl 回跳：goBack()读取路由快照中的returnUrl查询参数，若目标 URL 以当前window.location.origin开头则用 Angular 路由跳转，否则视为外部 URL 用window.location.href跳转，同时给出console.error('No return URL provided.')兜底（见 auth.component.ts）。

路由结构：认证子路由全图

认证路由由 auth.routes.ts 中的createAuthRoutes()工厂统一生成，在NgxAuthModule中通过依赖注入{ provide: ROUTES, useFactory: ... }动态注册。路由表如下：

路由源码中的注释揭示了一个安全设计细节：confirm-email刻意不使用NoAuthGuard。原因在于注册即登录，用户点击邮件中的确认链接时通常已是登录态；若加了守卫，用户会被提前重定向到仪表盘，导致 resolver 从未执行、邮箱地址永远得不到验证。这里的信任依据是链接中的一次性 token——API 只接受该 token 一次（见 auth.routes.ts 中confirm-email路由的注释）。

插件化路由：PageRouteRegistryService 机制

createAuthRoutes的最后一个子路由是..._pageRouteRegistryService.getPageLocationRoutes('auth-sections')，它把认证区域做成可插拔的。在 auth.module.ts 的构造函数中，NgxAuthModule通过PageRouteRegistryService.registerPageRoutes(...)注册了三个初始页面：login-workspace、login-magic、magic-sign-in，均使用canActivate: [NoAuthGuard]。模块用静态标志hasRegisteredPageRoutes保证这些页面只注册一次。这意味着 Gauzy 插件可以在不修改认证模块源码的前提下，向auth-sections位置追加新的认证页面。

登录成功与 OAuth 回跳

sign-in-success/sign-in-success.module.ts 定义了success与google两个子路由，都渲染SignInSuccessComponent，用于社交/OAuth 登录成功后的回跳落地页（搭配NbCardModule与NbSpinnerModule呈现加载态）。

守卫与拦截器：安全访问的基石

README 的 Features 中明确列出「Auth Guards & Interceptors（路由守卫与 HTTP 拦截器）」。路由层面最核心的是NoAuthGuard，它定义于 packages/ui-core/core/src/lib/auth/no-auth.guard.ts（@gauzy/ui-core/core是ui-auth的关键依赖），语义与常见的AuthGuard相反：已登录用户访问登录/注册等页面时，会被重定向走，避免已登录用户重复进入认证流程。上面的路由表中可以看到，除confirm-email、oauth-authorize、logout之外的所有认证页面都挂载了该守卫。

至于 HTTP 拦截器层，README 将其列为该库的组成部分，仓库中与认证相关的拦截器（如 token 注入、认证失败处理）统一实现在@gauzy/ui-core/core依赖包内，供ui-auth的组件与服务调用，实现「组件负责交互、服务与守卫负责安全」的分层设计。

构建、测试与发布：Nx 工作区下的标准流程

README 给出了完整的开发命令，均基于仓库根目录的 Nx 工作区（nx.json）执行：

构建库

yarn nx build ui-auth

该命令会触发@gauzy/ui-auth的 Nx project 构建。若要按开发/生产模式区分，package.json 还预置了以下脚本：

"lib:build": "yarn nx build ui-auth --configuration=development", "lib:build:prod": "yarn nx build ui-auth --configuration=production", "lib:watch": "yarn nx build ui-auth --watch --configuration=development"

其中lib:watch适合开发期间持续增量构建；产物默认输出到dist/packages/ui-auth。注意该库"sideEffects": false，声明为纯模块，便于摇树优化（tree-shaking）。

运行单元测试

yarn nx test ui-auth

测试环境基于jest-preset-angular与@types/jest（见 package.json 的 devDependencies），仓库中已有的测试用例可作参考，例如 login-magic.component.spec.ts、magic-login-workspace.component.spec.ts、social-links.component.spec.ts、whats-new.component.spec.ts。

发布到 npm

yarn nx build ui-auth cd dist/packages/ui-auth npm publish

先构建、再进入dist/packages/ui-auth目录执行npm publish，即可把库发布为 npm 包。需要留意的是，package.json 当前标记为"private": true，即仓库默认不对外发布该包；正式发布前需要先移除该私有标记，并确认@gauzy/ui-core、@gauzy/ui-config等内部依赖已可被安装方解析。

安装使用

在已配置好的 Gauzy 项目中，按 README 执行以下任一命令安装：

npm install @gauzy/ui-auth # 或 yarn add @gauzy/ui-auth

安装后引入NgxAuthModule即可获得整套认证页面。由于该库面向 Gauzy 生态（README 明确说明「intended to be used within the Gauzy ecosystem」），安装前需要先具备完整的 Gauzy 工作区并安装好全部依赖；它的 peerDependencies 要求 Angular 21（@angular/common、@angular/core均为21.0.7），运行环境要求 Node>=22、Yarn>=1.22。

集成要点速览

把@gauzy/ui-auth接入 Gauzy 应用时，关键动作如下：

1. 导入模块：在应用路由模块中引入NgxAuthModule，其构造器会自动通过PageRouteRegistryService注册登录工作区、魔法登录等页面路由；
2. 挂载认证父路由：应用级路由需把createAuthRoutes()返回的路由数组挂到/auth前缀之下（源码中NgxAuthComponent通过updateAuthPageClasses按/auth/login、/auth/register判断布局，说明认证页面默认部署在/auth路径下）；
3. 依赖准备：确保@gauzy/ui-core/core提供的AuthService、Store、NoAuthGuard、ErrorHandlingService、PageRouteRegistryService已就绪，它们承担了实际的登录请求、会话持久化与安全校验；
4. 环境配置：@gauzy/ui-config中的DEMO、DEMO_SUPER_ADMIN_EMAIL、DEMO_EMPLOYEE_PASSWORD等字段控制演示模式的一键登录行为；
5. 发布前检查：移除private: true、确认 Angular 21 依赖兼容、先跑yarn nx test ui-auth与yarn nx build ui-auth验证通过。

综上所述，@gauzy/ui-auth并非简单的登录页集合，而是围绕 Gauzy 多租户业务模型构建的完整认证前端方案：从经典密码登录、工作区选择登录、魔法验证码登录，到注册、找回密码、邮件确认、邀请接受与 OAuth 授权，配合NoAuthGuard路由守卫与插件化的页面注册机制，构成了 Gauzy 平台安全、可扩展的认证基础设施。读者既可以按 README 的命令直接构建、测试、发布与安装该库，也可以深入 auth.routes.ts 与 auth.module.ts 理解其路由设计与插件机制，为在自身 Gauzy 应用中定制认证流程打下基础。

• 后端
• 前端
• 企业应用
• MCP 服务