NextUI Identity Admin Platform 设计方案

1. 概述

1.1 目标

将 NextUI Workbench 扩展为统一的身份认证管理平台，提供：

  • SharedProfile 管理 - 管理跨应用的用户配置
  • Keycloak 管理 - 用户、角色、客户端、Realm 等管理
  • 应用权限管理 - 通过标准 API 管理应用内的角色和权限
  • 多服务器支持 - 动态添加和管理多个身份服务器

1.2 产品定位

┌─────────────────────────────────────────────────────────────────┐
│                    NextUI Identity Admin                         │
│                    (统一身份管理平台)                              │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ SharedProfile│  │   Keycloak   │  │  Application │          │
│  │   Manager    │  │   Manager    │  │   Manager    │          │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘          │
│         │                 │                 │                   │
│         ▼                 ▼                 ▼                   │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ Profile API  │  │ Keycloak API │  │ Standard API │          │
│  │ (REST)       │  │ (Admin REST) │  │ (NextUI Std) │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘

1.3 使用场景

  1. 开发环境 - 开发者本地管理 demo 身份服务
  2. 测试环境 - QA 团队管理测试用户和权限
  3. 生产运维 - 运维人员日常管理用户、角色、权限
  4. 第三方应用 - 使用 NextUI 构建的应用自动获得管理能力

2. 架构设计

2.1 整体架构

┌─────────────────────────────────────────────────────────────────┐
│                         Workbench UI                             │
├─────────────────────────────────────────────────────────────────┤
│  Servers    │  Users    │  Roles    │  Clients  │  Profiles    │
│  管理       │  管理     │  管理     │  管理     │  管理         │
├─────────────────────────────────────────────────────────────────┤
│                    Admin Service Layer                           │
│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐       │
│  │ ServerRegistry │ │ AdminContext   │ │ StandardAPI    │       │
│  │ (服务器注册)   │ │ (当前上下文)   │ │ (标准接口)     │       │
│  └────────────────┘ └────────────────┘ └────────────────┘       │
├─────────────────────────────────────────────────────────────────┤
│                    Provider Adapters                             │
│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐       │
│  │ Keycloak       │ │ SharedProfile  │ │ NextUI App     │       │
│  │ Adapter        │ │ Adapter        │ │ Adapter        │       │
│  └────────────────┘ └────────────────┘ └────────────────┘       │
├─────────────────────────────────────────────────────────────────┤
│                    External Services                             │
│  ┌────────────────┐ ┌────────────────┐ ┌────────────────┐       │
│  │ Keycloak       │ │ Profile API    │ │ App Admin API  │       │
│  │ Server         │ │ Server         │ │ Server         │       │
│  └────────────────┘ └────────────────┘ └────────────────┘       │
└─────────────────────────────────────────────────────────────────┘

2.2 核心概念

2.2.1 Server (服务器)

代表一个可管理的身份服务实例：

public class AdminServer
{
    public string Id { get; set; }           // 唯一标识
    public string Name { get; set; }         // 显示名称
    public ServerType Type { get; set; }     // Keycloak / SharedProfile / NextUIApp
    public string BaseUrl { get; set; }      // 服务地址
    public AuthConfig Auth { get; set; }     // 认证配置
    public bool IsDefault { get; set; }      // 是否默认
    public DateTime AddedAt { get; set; }    // 添加时间
}

public enum ServerType
{
    Keycloak,        // Keycloak 身份服务器
    SharedProfile,   // SharedProfile API 服务
    NextUIApp        // 符合标准的 NextUI 应用
}

public class AuthConfig
{
    public AuthMethod Method { get; set; }   // Bearer / Basic / ClientCredentials
    public string? Token { get; set; }
    public string? Username { get; set; }
    public string? Password { get; set; }
    public string? ClientId { get; set; }
    public string? ClientSecret { get; set; }
}

2.2.2 Admin Context (管理上下文)

当前选中的服务器和 Realm：

public class AdminContext
{
    public AdminServer? CurrentServer { get; set; }
    public string? CurrentRealm { get; set; }  // Keycloak 专用
    public string? CurrentClient { get; set; } // 当前客户端

    public event Action? Changed;
}

2.3 标准管理 API 规范

为了让 NextUI 应用都能被管理，定义标准 API：

# NextUI Identity Admin API Specification v1.0

openapi: 3.0.0
info:
  title: NextUI Identity Admin API
  version: 1.0.0

paths:
  # 用户管理
  /admin/users:
    get:
      summary: 获取用户列表
      parameters:
        - name: search
        - name: page
        - name: pageSize
    post:
      summary: 创建用户

  /admin/users/{userId}:
    get:
      summary: 获取用户详情
    put:
      summary: 更新用户
    delete:
      summary: 删除用户

  /admin/users/{userId}/roles:
    get:
      summary: 获取用户角色
    put:
      summary: 设置用户角色

  # 角色管理
  /admin/roles:
    get:
      summary: 获取角色列表
    post:
      summary: 创建角色

  /admin/roles/{roleId}:
    get:
      summary: 获取角色详情
    put:
      summary: 更新角色
    delete:
      summary: 删除角色

  /admin/roles/{roleId}/permissions:
    get:
      summary: 获取角色权限
    put:
      summary: 设置角色权限

  # 权限管理
  /admin/permissions:
    get:
      summary: 获取权限列表

  # 组织/租户管理
  /admin/tenants:
    get:
      summary: 获取租户列表
    post:
      summary: 创建租户

  /admin/tenants/{tenantId}/members:
    get:
      summary: 获取租户成员
    put:
      summary: 设置租户成员

3. 功能模块设计

3.1 服务器管理 (Server Management)

3.1.1 功能

  • 添加/编辑/删除服务器配置
  • 测试服务器连接
  • 服务器健康检查
  • 切换当前服务器

3.1.2 UI 设计

┌─────────────────────────────────────────────────────────────────┐
│  Identity Admin > Servers                                        │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ + Add Server                              🔄 Refresh    │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 🔑 Local Keycloak                          ✅ Connected │    │
│  │    http://localhost:5088                   [Default]    │    │
│  │    Type: Keycloak | Realm: master                       │    │
│  │    [Select] [Edit] [Test] [Delete]                      │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 📋 SharedProfile API                       ✅ Connected │    │
│  │    http://localhost:5100                                │    │
│  │    Type: SharedProfile                                  │    │
│  │    [Select] [Edit] [Test] [Delete]                      │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 🌐 Production Keycloak                     ⚠️ Auth Req  │    │
│  │    https://auth.example.com                             │    │
│  │    Type: Keycloak | Realm: production                   │    │
│  │    [Select] [Edit] [Test] [Delete]                      │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

3.2 用户管理 (User Management)

3.2.1 Keycloak 用户管理功能

  • 用户列表（搜索、分页、筛选）
  • 创建/编辑/删除用户
  • 启用/禁用用户
  • 重置密码
  • 管理用户角色
  • 管理用户组
  • 查看用户会话
  • 强制登出

3.2.2 UI 设计

┌─────────────────────────────────────────────────────────────────┐
│  Identity Admin > Users                    Server: Local KC ▼   │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ 🔍 Search users...          Realm: master ▼  + Add User │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ ☐ │ Avatar │ Username    │ Email           │ Status    │    │
│  ├───┼────────┼─────────────┼─────────────────┼───────────┤    │
│  │ ☐ │  👤    │ admin       │ admin@demo.com  │ ✅ Active │    │
│  │ ☐ │  👤    │ john.doe    │ john@demo.com   │ ✅ Active │    │
│  │ ☐ │  👤    │ jane.smith  │ jane@demo.com   │ ⛔ Disabled│    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  Selected: 0  │  Page 1 of 5  │  < 1 2 3 4 5 >  │ 20/page ▼    │
└─────────────────────────────────────────────────────────────────┘

3.3 角色管理 (Role Management)

3.3.1 功能

  • Realm 角色管理
  • Client 角色管理
  • 角色组合（Composite Roles）
  • 角色权限映射

3.3.2 UI 设计

┌─────────────────────────────────────────────────────────────────┐
│  Identity Admin > Roles                    Server: Local KC ▼   │
├─────────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ Realm Roles │ Client Roles                  + Add Role  │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                  │
│  Client: role-set-devtools ▼                                    │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │ Role Name       │ Description              │ Users      │    │
│  ├─────────────────┼──────────────────────────┼────────────┤    │
│  │ 📋 editor       │ Can edit content         │ 12         │    │
│  │ 📋 viewer       │ Read-only access         │ 45         │    │
│  │ 📋 publisher    │ Can publish content      │ 5          │    │
│  │ 📋 task-manager │ Can manage tasks         │ 8          │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘

3.4 客户端管理 (Client Management)

3.4.1 功能

  • 客户端列表
  • 创建/编辑客户端
  • 客户端角色管理
  • 客户端范围管理
  • 服务账户配置

3.5 SharedProfile 管理

3.5.1 功能

  • 用户配置列表
  • 查看/编辑配置
  • 批量操作
  • 配置同步状态

3.6 配置持久化

3.6.1 存储方案

public interface IAdminConfigStorage
{
    Task<List<AdminServer>> GetServersAsync();
    Task SaveServerAsync(AdminServer server);
    Task DeleteServerAsync(string serverId);
    Task<AdminServer?> GetDefaultServerAsync();
    Task SetDefaultServerAsync(string serverId);
}

// 浏览器存储实现
public class BrowserAdminConfigStorage : IAdminConfigStorage
{
    private const string StorageKey = "nextui_admin_servers";
    // 使用 localStorage 存储配置
}

// 本地文件存储实现 (用于独立应用)
public class FileAdminConfigStorage : IAdminConfigStorage
{
    // 存储到 ~/.nextui/admin-config.json
}

4. Keycloak 集成详细设计

4.1 Keycloak Admin API 封装

public interface IKeycloakAdminClient
{
    // Realm 管理
    Task<List<RealmRepresentation>> GetRealmsAsync();
    Task<RealmRepresentation> GetRealmAsync(string realm);

    // 用户管理
    Task<List<UserRepresentation>> GetUsersAsync(string realm, UserQuery query);
    Task<UserRepresentation> GetUserAsync(string realm, string userId);
    Task<string> CreateUserAsync(string realm, UserRepresentation user);
    Task UpdateUserAsync(string realm, string userId, UserRepresentation user);
    Task DeleteUserAsync(string realm, string userId);
    Task ResetPasswordAsync(string realm, string userId, string newPassword);
    Task<List<RoleRepresentation>> GetUserRolesAsync(string realm, string userId);
    Task AssignUserRolesAsync(string realm, string userId, List<RoleRepresentation> roles);

    // 角色管理
    Task<List<RoleRepresentation>> GetRealmRolesAsync(string realm);
    Task<List<RoleRepresentation>> GetClientRolesAsync(string realm, string clientId);
    Task<RoleRepresentation> CreateRoleAsync(string realm, RoleRepresentation role);
    Task UpdateRoleAsync(string realm, string roleName, RoleRepresentation role);
    Task DeleteRoleAsync(string realm, string roleName);

    // 客户端管理
    Task<List<ClientRepresentation>> GetClientsAsync(string realm);
    Task<ClientRepresentation> GetClientAsync(string realm, string clientId);
    Task<string> CreateClientAsync(string realm, ClientRepresentation client);
    Task UpdateClientAsync(string realm, string clientId, ClientRepresentation client);

    // 组管理
    Task<List<GroupRepresentation>> GetGroupsAsync(string realm);
    Task<List<UserRepresentation>> GetGroupMembersAsync(string realm, string groupId);

    // 会话管理
    Task<List<UserSessionRepresentation>> GetUserSessionsAsync(string realm, string userId);
    Task LogoutUserAsync(string realm, string userId);
}

4.2 认证方式

支持多种认证方式连接 Keycloak：

public class KeycloakAuthProvider
{
    // 1. 使用管理员账号密码
    public async Task<string> AuthenticateWithPasswordAsync(
        string baseUrl, string realm, string username, string password);

    // 2. 使用 Client Credentials
    public async Task<string> AuthenticateWithClientCredentialsAsync(
        string baseUrl, string realm, string clientId, string clientSecret);

    // 3. 使用已有的 Access Token
    public void SetAccessToken(string token);
}

4.3 功能覆盖范围

功能 优先级 Phase
用户列表/搜索 高 1
用户 CRUD 高 1
用户角色管理 高 1
Realm 角色管理 高 1
Client 角色管理 高 1
客户端列表 中 2
客户端 CRUD 中 2
用户组管理 中 2
会话管理 中 2
Realm 配置 低 3
身份提供者配置 低 3
事件日志 低 3

5. 项目结构

5.1 新增项目/文件

src/
├── NextUI.Identity.Admin/                    # 新项目：管理服务层
│   ├── NextUI.Identity.Admin.csproj
│   ├── Models/
│   │   ├── AdminServer.cs
│   │   ├── AdminContext.cs
│   │   ├── UserQuery.cs
│   │   └── ...
│   ├── Services/
│   │   ├── IAdminConfigStorage.cs
│   │   ├── IServerRegistry.cs
│   │   ├── ServerRegistry.cs
│   │   └── AdminContextService.cs
│   ├── Providers/
│   │   ├── IAdminProvider.cs              # 统一管理接口
│   │   ├── KeycloakAdminProvider.cs       # Keycloak 实现
│   │   ├── SharedProfileAdminProvider.cs  # SharedProfile 实现
│   │   └── NextUIAppAdminProvider.cs      # 标准 App 实现
│   ├── Keycloak/
│   │   ├── IKeycloakAdminClient.cs
│   │   ├── KeycloakAdminClient.cs
│   │   ├── KeycloakAuthProvider.cs
│   │   └── Models/                        # Keycloak API 模型
│   │       ├── UserRepresentation.cs
│   │       ├── RoleRepresentation.cs
│   │       ├── ClientRepresentation.cs
│   │       └── ...
│   └── ServiceCollectionExtensions.cs

src/NextUI.Blazor/Components/Admin/          # UI 组件
│   ├── SxAdminServerList.razor             # 服务器列表
│   ├── SxAdminServerEditor.razor           # 服务器编辑
│   ├── SxAdminUserList.razor               # 用户列表
│   ├── SxAdminUserEditor.razor             # 用户编辑
│   ├── SxAdminRoleList.razor               # 角色列表
│   ├── SxAdminRoleEditor.razor             # 角色编辑
│   ├── SxAdminClientList.razor             # 客户端列表
│   └── SxAdminServerSelector.razor         # 服务器选择器

workbench/NextUI.Workbench/Pages/Admin/      # Workbench 页面
│   ├── AdminOverviewPage.razor             # 管理总览
│   ├── AdminServersPage.razor              # 服务器管理
│   ├── AdminUsersPage.razor                # 用户管理
│   ├── AdminRolesPage.razor                # 角色管理
│   ├── AdminClientsPage.razor              # 客户端管理
│   └── AdminProfilesPage.razor             # Profile 管理

5.2 依赖关系

NextUI.Identity.Admin
    └── NextUI.Core
    └── NextUI.Identity (可选，共享模型)

NextUI.Blazor
    └── NextUI.Identity.Admin

NextUI.Workbench
    └── NextUI.Blazor
    └── NextUI.Identity.Admin

6. 实施计划

Phase 1: 基础框架 (1-2 周)

目标: 建立基础架构和服务器管理

  1. 创建 NextUI.Identity.Admin 项目
  2. 实现 AdminServer 和 AdminContext 模型
  3. 实现 IAdminConfigStorage (浏览器存储)
  4. 实现 ServerRegistry 服务
  5. 创建服务器管理 UI (SxAdminServerList, SxAdminServerEditor)
  6. 添加 Workbench 导航和页面框架

交付物:

  • 可以添加、编辑、删除服务器配置
  • 服务器配置持久化到 localStorage
  • 可以测试服务器连接

Phase 2: Keycloak 用户管理 (2-3 周)

目标: 实现 Keycloak 用户和角色管理

  1. 实现 IKeycloakAdminClient
  2. 实现 Keycloak 认证 (KeycloakAuthProvider)
  3. 实现用户列表/搜索 UI
  4. 实现用户 CRUD 功能
  5. 实现用户角色管理
  6. 实现 Realm/Client 角色管理

交付物:

  • 完整的 Keycloak 用户管理功能
  • 角色管理功能
  • 与 demo Keycloak 集成验证

Phase 3: SharedProfile 集成 (1 周)

目标: 集成 SharedProfile 管理

  1. 实现 SharedProfileAdminProvider
  2. 复用/增强现有 SxSharedProfileAdminPanel
  3. 添加到统一管理界面

交付物:

  • SharedProfile 在统一界面中管理
  • 支持多 Profile API 服务器

Phase 4: 客户端和高级功能 (2 周)

目标: 完善管理功能

  1. 实现客户端管理
  2. 实现用户组管理
  3. 实现会话管理
  4. 添加批量操作功能
  5. 优化 UI/UX

交付物:

  • 完整的客户端管理
  • 用户组管理
  • 会话管理和强制登出

Phase 5: 标准 API 和扩展 (2 周)

目标: 定义标准 API，支持第三方应用

  1. 定义并文档化标准 Admin API
  2. 实现 NextUIAppAdminProvider
  3. 在示例应用中实现标准 API
  4. 编写集成指南

交付物:

  • 标准 Admin API 规范文档
  • 参考实现
  • 集成指南

7. 默认配置

7.1 开发环境默认服务器

当运行 nx identity demo start 后，自动配置：

{
  "servers": [
    {
      "id": "demo-keycloak",
      "name": "Demo Keycloak",
      "type": "Keycloak",
      "baseUrl": "http://localhost:5088",
      "auth": {
        "method": "Password",
        "username": "admin",
        "password": "admin"
      },
      "defaultRealm": "nextui-demo",
      "isDefault": true
    },
    {
      "id": "demo-profile-api",
      "name": "Demo SharedProfile API",
      "type": "SharedProfile",
      "baseUrl": "http://localhost:5100",
      "auth": {
        "method": "None"
      }
    }
  ]
}

7.2 配置存储位置

环境 存储位置
Workbench (WASM) localStorage['nextui_admin_servers']
独立应用 ~/.nextui/admin-config.json

8. 安全考虑

8.1 凭证存储

  • 开发环境: 允许明文存储在 localStorage (仅限本地)
  • 生产环境:
    • 不存储密码，每次需要输入
    • 支持 Client Credentials 方式
    • Token 有过期时间

8.2 访问控制

  • 管理平台本身需要管理员权限
  • 使用 SxAuthGuard 保护管理页面
  • 支持配置只读模式

8.3 审计日志

  • 记录所有管理操作
  • 支持导出审计日志

9. 用户体验设计

9.1 导航结构

Identity Admin
├── Overview (总览仪表板)
├── Servers (服务器管理)
├── Users (用户管理)
│   ├── User List
│   ├── User Detail
│   └── User Roles
├── Roles (角色管理)
│   ├── Realm Roles
│   └── Client Roles
├── Clients (客户端管理)
├── Groups (组管理)
├── Profiles (SharedProfile 管理)
└── Settings (设置)

9.2 快捷操作

  • 服务器快速切换下拉框 (始终显示在顶部)
  • 常用操作快捷键
  • 最近访问的用户/角色

10. 测试策略

10.1 单元测试

  • KeycloakAdminClient 的 API 调用测试
  • ServerRegistry 的配置管理测试
  • Provider 的数据转换测试

10.2 集成测试

  • 与真实 Keycloak 的集成测试
  • 使用 Testcontainers 运行测试用 Keycloak

10.3 E2E 测试

  • 使用 Playwright 测试管理 UI 流程
  • 服务器添加 → 用户管理 → 角色分配 完整流程

11. 总结

本方案将 NextUI Workbench 扩展为统一的身份管理平台，具有以下特点：

  1. 渐进式实现 - 分 5 个 Phase，每个 Phase 都有独立交付价值
  2. 可扩展架构 - Provider 模式支持多种身份服务
  3. 开发体验优先 - 默认配置让开发者零配置启动
  4. 产品化潜力 - 可以作为独立产品或 NextUI 应用的内置功能

建议从 Phase 1 开始，建立基础框架后逐步完善功能。