Nacos Console UI 升级 - 实施进度文档

项目概述

将 Nacos 控制台前端从 React 16 + Webpack 升级到 React 18 + Vite + Shadcn/ui，保留全部原有功能并改善用户体验。

技术栈

分类	技术选型
框架	React 18 + TypeScript
构建工具	Vite 7
样式	Tailwind CSS 4（oklch 色彩系统，蓝白主题）
UI 组件库	Shadcn/ui（基于 Radix UI）
状态管理	Zustand v5（stores: auth, server, namespace, app, config, history, service）
路由	React Router v7（HashRouter, 懒加载, AuthGuard/AdminGuard/GuestGuard）
国际化	react-i18next（zh-CN / en-US）
HTTP 客户端	Axios（请求/响应拦截器, Token 处理）
代码编辑器	@monaco-editor/react

后端架构

端口 8848（主服务器）：Admin/认证端点（/nacos/v3/auth/*），有 /nacos 上下文路径
端口 8080（控制台服务器）：控制台 API 端点，无 /nacos 上下文路径前缀
- 命名空间：/v3/console/core/namespace/*
- 配置管理：/v3/console/cs/config/*
- 历史记录：/v3/console/cs/history/*
- 服务器状态：/v3/console/server/*
端口 9080（MCP 注册中心）：AI MCP 注册服务器

实施计划与进度

阶段 0：项目基础 [已完成]

阶段 1：配置管理 - 核心增删改查 [已完成]

阶段 2：配置管理 - 历史版本与回滚 [已完成]

ConfigHistory 类型扩展（添加 srcIp, extInfo 字段）
history-store.ts 状态管理（Zustand store，含分页、加载、详情获取）
DiffEditor.tsx 差异对比组件（基于 @monaco-editor/react DiffEditor）
i18n 翻译（history 模块 19 个 key，中英文）
历史版本列表页（src/pages/historyRollback/）- 搜索、分页、差异对比弹窗
历史版本详情页（src/pages/historyDetail/）- 元数据展示、灰度规则解析
版本差异对比（Monaco DiffEditor，左侧选中版本 vs 右侧当前版本）
回滚确认页（src/pages/configRollback/）- 按 opType 区分回滚逻辑与警告提示
分页切换防闪烁优化（historyRollback + configurationManagement 两个列表页）

阶段 3：配置管理 - 批量操作与导入导出 [已完成]

阶段 4：配置管理 - 灰度发布与监听查询 [已完成]

类型扩展（ConfigListenerInfo 监听查询响应、ConfigBetaInfo 灰度配置信息）
API 层扩展（getBeta 获取灰度配置、publishBeta 灰度发布、stopBeta 停止灰度）
i18n 翻译（listener 模块 7 个 key + beta 发布 10 个 key，中英文）
监听查询页面重写（src/pages/listeningToQuery/）
- ToggleGroup 切换查询模式（按配置查询 / 按 IP 查询）
- 条件表单：按配置查询（DataId + Group）/ 按 IP 查询（IP 地址）
- 结果表格：按配置查询显示（IP, MD5）/ 按 IP 查询显示（DataId, Group, MD5）
- 客户端分页（API 返回全量结果，前端分页展示）
- URL 参数预填充（从配置列表页跳转时自动填充 DataId 和 Group）
- 搜索栏重置按钮（清空输入框 + 清除查询结果）
配置编辑器灰度发布标签页（src/pages/configeditor/）
- Tabs 组件（正式版 / Beta 版），Beta 标签页仅在编辑模式下显示
- Beta 标签页切换时通过 getBeta API 加载现有灰度配置
- Beta 发布：IP 输入框（逗号分隔）+ 内容编辑器 + 发布按钮
- 停止灰度：确认对话框 + 调用 stopBeta API + 清除灰度状态
- 页脚按钮根据当前标签页自适应（正式版：发布；Beta 版：灰度发布 + 停止灰度）

阶段 5：服务管理 [已完成]

类型定义（src/types/service.ts）- ServiceView, ServiceDetailInfo, Instance, ClusterInfo, Selector, HealthChecker, SubscriberInfo 等
API 层（src/api/service.ts）- 10 个方法：listServices, getService, createService, updateService, deleteService, getSelectorTypes, updateCluster, listInstances, updateInstance, listSubscribers
Zustand Store（src/stores/service-store.ts）- 服务列表/搜索/分页/详情/选择器类型状态管理
i18n 翻译（service 模块 ~45 个 key，中英文）
服务列表页（src/pages/serviceManagement/）
- 搜索过滤（服务名、分组名、隐藏空服务 Switch）
- 表格展示（服务名、分组名、集群数、IP 数、健康实例数、触发保护阈值）
- 行背景色：健康实例数为 0 时红色高亮
- 行操作：详情、订阅者、删除（确认对话框）
- 创建服务对话框（服务名、分组名、保护阈值、临时服务、选择器类型/表达式、元数据）
- 服务端分页
服务详情页（src/pages/serviceDetail/）
- 服务信息卡片（网格布局只读展示 + 编辑按钮）
- 集群卡片（按 clusterMap 遍历，每个集群一个 Card）
- 实例数据通过独立 API 获取（v3/console/ns/instance/list），不依赖服务详情响应的 cluster.hosts 字段
- 实例表格（IP、端口、临时、权重、健康 Badge、元数据 Badge、操作）
- 实例行背景色：健康绿色、不健康红色
- 实例快捷上线/下线（直接切换 enabled，无需对话框）
- 编辑服务对话框（保护阈值、临时服务、选择器、元数据）
- 编辑集群对话框（健康检查类型 TCP/HTTP/NONE、检查端口、使用实例端口、HTTP 路径/请求头、元数据）
- 编辑实例对话框（IP/端口只读、权重、启用、元数据）
- 每个集群独立的服务端分页（分页变更触发 API 重新获取）
订阅者列表页（src/pages/subscriberList/）
- 搜索过滤（服务名、分组名 + 搜索/重置按钮）
- URL 参数预填充（从服务列表页跳转时自动填充）
- 表格展示（分组名、服务名、订阅者地址、订阅数、集群）
- 服务端分页

阶段 6：AI 注册中心 [进行中]

MCP 服务器管理 [进行中]

MCP 类型定义（src/types/mcp.ts）- McpServerBasicInfo, McpServerDetailInfo, McpToolSpecification, McpVersionDetail, McpSecurityScheme 等
MCP API 层（src/api/mcp.ts）- listMcpServers, getMcpServer, createMcpServer, updateMcpServer, deleteMcpServer, importMcpTools, verifyMcpImport 等
MCP Zustand Store（src/stores/mcp-store.ts）- 列表/搜索/分页/详情/版本选择状态管理
MCP 服务器列表页（src/pages/mcpServerManagement/）- 搜索、分页、启用/禁用、删除
MCP 服务器详情页（src/pages/mcpServerDetail/）
- Hero Header：渐变背景 + 大图标 + 协议/版本徽章 + 操作栏（版本切换、启用/禁用、复制、新版本、编辑）
- Card 统一样式：overflow-hidden py-0 gap-0 + 自定义 header（px-5 py-3.5 border-b bg-muted/30）+ 语义图标
- 基本信息卡片：双列 InfoCell 网格布局
- 端点信息卡片：前后端端点分栏展示
- 安全方案卡片：Table 展示安全认证配置，左间距对齐修复
- 工具列表组件（McpToolList）：树形参数层级展示（递归 SchemaTreeNode）+ 请求/响应模版 + 标注信息
- 版本下拉 Latest 绿色徽章（is_latest 字段映射修复）
- Hero Header Latest 徽章（emerald 绿色，查看最新版本时显示）
MCP 服务器编辑页（src/pages/newMcpServer/）
- Hero Header：渐变背景 + 大图标，协议/版本徽章动态联动
- Card 统一样式：与详情页一致的 py-0 gap-0 + 自定义 header + 语义图标（Server/Terminal/Globe/Shield/Wrench）
- 协议选择器：卡片式 Radio 按钮，三色方案（stdio=purple, SSE=blue, Streamable=cyan）+ 选中态 ring 高亮
- 表单间距统一：space-y-5 + space-y-2.5（Label-Input）
- 安全方案编辑：Shield 图标（rose）+ 计数 Badge + 默认上下游安全配置
- 工具管理卡片（tool-manager/）：Wrench 图标（amber）+ 计数 Badge + 左侧列表 bg-muted/20 + 选中态 bg-primary/10 ring-1
- 发布策略弹窗：点击发布按钮弹出 Dialog，三选项 Radio（发布新版本/设为最新版本/更新当前版本），根据版本号动态计算可用性
  - 发布新版本（emerald）：以新版本号发布，但不设为默认版本。latest=false, overrideExisting=false
  - 设为最新版本（blue）：设为默认版本，客户端未指定版本时自动使用。latest=true, overrideExisting=true
  - 更新当前版本（orange）：覆盖当前版本配置，版本号和最新标记不变。latest=isCurrentLatest, overrideExisting=true
  - 不可用选项灰化 + 原因提示
  - useEffect 自动切换：当前策略不可用时切换到第一个可用策略
- 工具导入模式限制（importMode prop）：HTTP 转换仅支持 OpenAPI 导入，SSE/Streamable 支持 MCP 实例导入，Stdio 不支持导入
- 提交按钮文案改为"发布"
- Sticky 底部提交栏：backdrop-blur-sm 毛玻璃效果
- 编辑页缓存优化：从详情页进入时优先使用 Zustand store 中的 currentMcp 缓存数据填充表单，避免重复 API 请求和 skeleton 闪烁
HTTP 转换标识（列表页 + 详情页）
- McpCard 列表卡片：当 protocol === 'http' || 'https' 时显示琥珀色 "HTTP 转换" 徽章 + RefreshCw 图标
- 详情页基本信息：协议 InfoCell 旁显示双色徽章（协议类型 + HTTP 转换指示器）
页面切换闪烁优化
- Store 层优化（mcp-store.ts）：fetchMcpServers 和 fetchMcpDetail 仅在无缓存数据时设置 loading=true，有数据时保持 UI 可见
- 详情页清理（mcpServerDetail）：组件卸载时不再调用 clearCurrentMcp()，保留缓存数据供编辑页复用
- 路由 Suspense fallback（routes.tsx）：PageLoading 从全屏 min-h-screen 缩小为 py-32，减少视觉跳动
- 编辑页缓存命中：检测 store 中 currentMcp.name === editMcpName 时跳过 API 请求，initLoading 初始为 false
MCP 服务器列表页视觉重设计（对齐详情页风格）

Agent 管理 [进行中]

其他 AI 模块 [待开发]

Prompt 管理（发布、版本管理、标签绑定、回滚）
Skill 管理（增删改查 + 文件上传）

阶段 7：平台管理 [待开发]

命名空间管理
集群节点管理
插件管理
权限与角色管理（RBAC）

遇到的问题与解决方案

问题 1：登录提示"用户名密码错误"

现象：登录始终返回错误，同时弹出两个错误提示。

根因：

Vite 代理将所有 /nacos/* 转发到 8080 端口，但登录接口（/nacos/v3/auth/user/login）实际在 8848 端口。
Axios 响应拦截器已经做了 return response.data（解包 HTTP body），但 auth-store 又做了一次 response.data（双重解包）。

修复：

为 /nacos/v1/auth 和 /nacos/v3/auth 添加单独的代理规则，指向 8848 端口。
修复 auth-store，使用 response as unknown as TokenData 代替 response.data。

问题 2：配置列表页无数据

现象：配置管理页面加载成功但表格显示"暂无数据"。

根因（3 个 bug）：

Vite 代理路径不匹配：控制台服务器（8080 端口）的 contextPath 为空（nacos.console.contextPath=），API 路径是 /v3/console/* 而非 /nacos/v3/console/*。代理原样转发导致 8080 将请求当作静态资源处理，返回 "No static resource" 错误。
namespace-store 双重解包：拦截器已返回 HTTP body，store 还做了 response.data?.data（多了一层 .data），导致 namespaces = []，命名空间始终为空。
server-store 类型不匹配：服务器状态 API 返回字符串值（如 "true", "30"）而非布尔/数字类型，store 直接使用导致类型判断失败。

修复：

在 Vite 代理规则中为 8080 端口添加 rewrite: (path) => path.replace(/^\/nacos/, '')，去掉 /nacos 前缀。
修改 namespace-store 为 const body = response as unknown as { code: number; data: Namespace[] }; const namespaces = body.data || []。
修改 server-store，使用 String(val) === 'true' 做布尔转换，Number(val) 做数值转换。

问题 3：Shadcn/ui 组件安装失败

现象：npx shadcn@latest add 因 TLS 证书错误失败。

修复：手动创建组件文件（textarea.tsx, radio-group.tsx, skeleton.tsx），按照 Shadcn/ui 规范使用 @radix-ui 原语实现。

问题 4：配置列表页 UI 问题（用户 review 反馈）

现象（4 项）：

搜索栏上方有不明空白。
列表页左右元素紧贴边缘，无留白。
每页 10 条翻到后面，切换为每页 50 条时超出页数范围，显示无数据且无法回退。
没有命名空间切换入口。

根因：

Card 组件默认 py-6 + CardContent pt-6 = 双重 top padding（48px）；同时 AppLayout <main p-6> 和页面自身 p-6 也是双重 padding。
表格 Card 使用 p-0 移除了所有内边距，表头和数据行紧贴卡片边缘。
切换 pageSize 时传入当前 pageNo（可能已超出新的总页数），且分页器仅在 configs.length > 0 时显示。
Header 组件左侧为空，未放置命名空间选择器。

修复：

搜索 Card 改为 py-0 + CardContent py-4；移除所有页面级 p-6（由 AppLayout 统一提供）。
表格首列增加 pl-6，尾列增加 pr-6（表头和数据行均添加）。
切换 pageSize 时强制 setPage(1, newSize) 重置到第 1 页；分页器显示条件改为 total > 0。
在 Header 左侧添加命名空间 Select 选择器 + "命名空间" 文字标签，切换后触发配置列表重新加载。

问题 5：列表页分页切换闪烁

现象：配置列表页和历史版本列表页切换每页条数时，整个表格区域闪烁（先显示 Skeleton 再显示数据）。

根因：加载状态触发了条件渲染，将整个表格替换为 Skeleton 组件，导致布局位移。

修复：

仅在 loading && list.length === 0（首次加载无数据）时显示 Skeleton。
分页加载时保持表格可见，通过 opacity-50 pointer-events-none 表示加载中状态。
分页器显示条件改为 total > 0（不再受 loading 状态影响）。
该修复同时应用于 configurationManagement 和 historyRollback 两个列表页。

问题 6：服务详情页实例不显示

现象：服务列表页显示 IP 数 = 1，但点进详情页后集群卡片中无实例数据。

根因：初始实现直接使用服务详情 API 响应的 cluster.hosts 字段渲染实例，但该字段可能为空或不完整。旧版代码中每个集群的实例是通过独立的 InstanceTable 组件单独调用 v3/console/ns/instance/list API 获取的。

修复：

新增 instancesByCluster 状态，独立存储每个集群的实例数据。
新增 fetchClusterInstances() 回调，按集群名调用 serviceApi.listInstances() 获取实例列表（带分页参数）。
useEffect 监听 currentService 变化，服务详情加载后自动为每个集群发起实例获取请求。
ClusterCard 组件改为接收 instances、instanceTotal、instanceLoading props，不再使用 cluster.hosts。
分页切换时直接将新分页参数传给 fetchClusterInstances()，避免 setTimeout hack。

问题 7：McpVersionDetail 字段名不匹配导致 Latest 标记不显示

现象：详情页版本下拉和 Hero Header 中的 Latest 徽章始终不显示。

根因：后端 Java 类 ServerVersionDetail 的字段名为 is_latest（snake_case），Jackson 序列化后 JSON 也是 is_latest。但前端 TypeScript McpVersionDetail 接口定义为 isLatest（camelCase），导致字段永远为 undefined。

修复：将 McpVersionDetail 接口的字段名从 isLatest 改为 is_latest，同步更新详情页和编辑页所有引用（4 处）。

已知限制：非持久化实例删除

后端 ConsoleInstanceController（/v3/console/ns/instance）目前仅提供 list 和 update 两个端点，没有 DELETE 方法。Admin API（/v3/admin/ns/instance）有 deregister 端点，但属于内部/SDK 接口，Console 前端不应直接调用。

待办：后端在 ConsoleInstanceController 中添加 DELETE 端点后，前端再实现非持久化实例删除功能（删除按钮 + 确认对话框）。

响应拦截器模式：Axios 拦截器执行 return response.data，所有 API 调用结果已经是 HTTP body。Store 层必须正确类型转换：对于标准包装响应（{ code, data }）使用 response as unknown as { code: number; data: T }，对于扁平响应（如服务器状态）使用 response as unknown as T。
命名空间 ID 约定：Nacos v3 使用 "public" 作为公共命名空间 ID（不是空字符串）。namespace store 初始化时默认为 ""，从 API 获取后更新为 "public"。
双端口代理策略：认证端点 → 8848（保留 /nacos 前缀），控制台端点 → 8080（通过 rewrite 去掉 /nacos 前缀）。
旧代码调研原则：实现每个模块前，充分调研旧版 console-ui/ React 16 代码库，了解 API 结构、数据流和 UI 交互模式。

项目文件结构

console-ui-next/
├── src/
│   ├── api/           # API 层（client.ts, auth.ts, config.ts, namespace.ts, server.ts, service.ts）
│   ├── components/
│   │   ├── config/    # 配置相关组件（MonacoEditor.tsx, DiffEditor.tsx）
│   │   ├── layout/    # 布局组件（sidebar.tsx, header.tsx）
│   │   └── ui/        # Shadcn/ui 组件（21+ 个）
│   ├── layouts/       # 应用布局（AppLayout.tsx）
│   ├── locales/       # 国际化 JSON 文件（zh-CN.json, en-US.json）
│   ├── pages/         # 页面组件
│   │   ├── configurationManagement/  # 配置列表
│   │   ├── newconfig/                # 新建配置
│   │   ├── configdetail/             # 配置详情
│   │   ├── configeditor/             # 编辑配置
│   │   ├── historyRollback/          # 历史版本列表 + 差异对比
│   │   ├── historyDetail/            # 历史版本详情
│   │   ├── configRollback/           # 回滚确认
│   │   ├── listeningToQuery/          # 监听查询（按配置/按 IP）
│   │   ├── serviceManagement/          # 服务列表
│   │   ├── serviceDetail/              # 服务详情（集群卡片 + 实例表格）
│   │   ├── subscriberList/             # 订阅者列表
│   │   ├── login/                    # 登录页
│   │   ├── register/                 # 注册页
│   │   └── welcome/                  # 欢迎/首页
│   ├── router/        # 路由与守卫
│   ├── stores/        # Zustand stores（auth, server, namespace, app, config, history, service）
│   └── types/         # TypeScript 类型定义
├── vite.config.ts     # Vite 配置（含双端口代理）
├── tailwind.config.ts
└── package.json

代码与 UI 风格规范

组件模式

全部使用函数式组件 + Hooks，export default 导出页面主组件
局部状态用 useState，副作用用 useEffect，回调优化用 useCallback
从 Zustand store 中解构获取状态和 action

样式系统

色彩体系：Tailwind CSS 4 + oklch 格式，CSS 变量定义在 globals.css
- 主色（Primary）：蓝色 oklch(0.55 0.18 240)
- 辅色（Secondary）：oklch(0.95 0.01 230)
- 破坏性操作（Destructive）：红色 oklch(0.6 0.22 20)
- 侧边栏专用色：--sidebar-background, --sidebar-primary 等
圆角半径：--radius: 0.75rem（12px），衍生 -sm, -md, -lg, -xl
整体风格：蓝白主色调，现代简洁，充分留白，微妙动画

布局模式

顶部固定导航（含命名空间切换 + 商业化引流链接）+ 可折叠侧边栏
AppLayout 的 <main p-6> 统一提供页面内边距，页面组件不再重复添加 padding
Card 组件包装主要内容区域，搜索区域用 py-0 紧凑样式，表格区域首尾列加 pl-6/pr-6
响应式使用 grid grid-cols-1 md:grid-cols-2 等

表单模式

结构：<div className="space-y-2"><Label /><Input /></div>
必填字段：红色星号 <span className="text-destructive ml-1">*</span>
Button 变体：default（主操作）、outline（次要）、ghost（文字）、destructive（删除）
搜索区域：flex flex-wrap items-end gap-4

Zustand Store 模式

分离 State 和 Actions 接口定义，合并为 Store = State & Actions
set() 更新状态，get() 读取当前状态
API 调用在 action 中完成，loading/error 统一管理
响应处理：response as unknown as { code: number; data: T } 正确类型转换

API 调用模式

统一定义在 src/api/ 下，对象字面量风格：export const xxxApi = { list, get, create, ... }
POST 数据自动序列化为 application/x-www-form-urlencoded（通过 qs 库）
错误处理：拦截器中 toast 提示，401/403 跳转登录

国际化模式

const { t } = useTranslation()，键名格式 domain.key（如 config.dataId）
所有用户可见文本必须通过 t() 翻译

图标与 UI 组件

图标：lucide-react（Plus, Search, MoreHorizontal, ChevronLeft 等）
Toast 通知：sonner 库（toast.error(), toast.success()）
代码编辑器：@monaco-editor/react，自定义封装支持语言切换和只读模式
Dialog：Shadcn/ui Dialog 用于确认操作
DropdownMenu：Shadcn/ui DropdownMenu 用于表格行操作菜单

命名规范

文件名：kebab-case（config-store.ts），组件文件用 PascalCase（MonacoEditor.tsx）
组件名：PascalCase，常量：UPPER_SNAKE_CASE
导入别名：@/ 指向 src/（如 @/components, @/stores, @/api）

当前状态

阶段 6（AI 注册中心）MCP 服务器管理与 Agent 管理进行中。

MCP 服务器列表、详情、编辑/创建页面已完成核心功能与视觉重设计。详情页包含 Hero Header、基本信息、端点、安全方案、工具列表（树形参数+模版）、HTTP 转换标识等完整展示。编辑页包含协议选择器（卡片式三色方案）、发布策略弹窗（点击发布按钮触发 Dialog 选择策略）、工具管理（按协议类型限制导入方式）、安全方案编辑等完整编辑功能。

Agent 管理已完成列表、详情、编辑/创建页面核心功能。列表卡片展示名称、版本、描述、能力标签、Skill 数量，支持 iconUrl 图片渲染（白色背景 + 加载失败回退）。编辑页发布逻辑已统一为与 MCP Server 一致的底部工具栏 + 三选项策略 Dialog 模式。TypeScript 类型已对齐后端 Java 模型（AgentBasicInfo 对应 AgentCardVersionInfo，AgentDetailInfo 对应 AgentCardDetailInfo）。

版本管理统一支持发布新版本、设为最新版本、更新当前版本三种语义清晰的操作。页面切换和命名空间切换已优化为无闪烁体验（store 缓存 + 按需 loading）。侧边栏收起态交互已重设计，用 Popover flyout 替代 Tooltip 实现可交互的子菜单面板。

Nacos Console UI 升级 - 实施进度文档

Nacos Console UI 升级 - 实施进度文档

项目概述

技术栈

后端架构

实施计划与进度

阶段 0：项目基础 [已完成]

阶段 1：配置管理 - 核心增删改查 [已完成]

阶段 2：配置管理 - 历史版本与回滚 [已完成]

阶段 3：配置管理 - 批量操作与导入导出 [已完成]

阶段 4：配置管理 - 灰度发布与监听查询 [已完成]

阶段 5：服务管理 [已完成]

阶段 6：AI 注册中心 [进行中]

MCP 服务器管理 [进行中]

Agent 管理 [进行中]

其他 AI 模块 [待开发]

阶段 7：平台管理 [待开发]

遇到的问题与解决方案

问题 1：登录提示"用户名密码错误"

问题 2：配置列表页无数据

问题 3：Shadcn/ui 组件安装失败

问题 4：配置列表页 UI 问题（用户 review 反馈）

问题 5：列表页分页切换闪烁

问题 6：服务详情页实例不显示

问题 7：McpVersionDetail 字段名不匹配导致 Latest 标记不显示

已知限制：非持久化实例删除

项目文件结构

代码与 UI 风格规范

组件模式

样式系统

布局模式

表单模式

Zustand Store 模式

API 调用模式

国际化模式

图标与 UI 组件

命名规范

当前状态

UI / 品牌优化 [已完成]