Kafka-UI React 前端：从零搭建 Apache Kafka 管理界面的开发环境实战指南

UI for Apache Kafka（即 kafka-ui）是一个开源的 Apache Kafka 管理 Web UI。本指南以仓库中 kafka-ui-react-app 子项目为主体，完整讲解其前端开发环境的搭建、依赖安装、OpenAPI 客户端生成、开发服务器启动，以及通过 Docker 方式对接真实 Kafka 集群的两种运行路径。读完本文，你将掌握 kafka-ui 前端在本地机器上的完整启动流程，理解 VITE_DEV_PROXY 代理机制与 gen:sources 代码生成管线的作用，并能独立搭建起可调试、可扩展的前端开发环境。

一、项目背景与整体结构

kafka-ui 采用「Java 后端 API + React 前端」的架构：后端（kafka-ui-api 模块）负责与 Kafka 集群、Schema Registry、Kafka Connect 等组件通信并提供 REST API；前端（kafka-ui-react-app 模块）是基于 React 18 + TypeScript + Vite 的单页应用，负责呈现 Dashboard、Topics、Consumer Groups、Schemas、Kafka Connect、KSQL DB 等全部管理功能。

从仓库结构看，前端子项目位于 kafka-ui-react-app，其内部关键目录包括：

• src/components/：按业务域组织的页面组件，如 Topics/、Schemas/、ConsumerGroups/、Connect/、Brokers/、KsqlDb/ 等；
• src/lib/hooks/api/：封装各领域 API 调用的 hooks（topics、brokers、clusters、consumers、kafkaConnect、ksqlDb 等）；
• src/redux/：基于 Redux Toolkit 的状态管理（loader、schemas、topicMessages）；
• src/generated-sources/：由 OpenAPI Generator 自动生成的 API 客户端代码（运行 pnpm gen:sources 后产生）。

前端通过 src/lib/api.ts 中导出的各类 *ApiClient（如 TopicsApi、BrokersApi、ClustersApi、MessagesApi、ConsumerGroupsApi、KafkaConnectApi、KsqlApi、SchemasApi、AclsApi、ApplicationConfigApi、AuthorizationApi）与后端交互，这些客户端类均来自生成目录 generated-sources，并由 lib/constants 中的 BASE_PARAMS 配置基础 URL。

二、环境要求

根据 kafka-ui-react-app/README.md，搭建前端开发环境需要满足以下条件：

依赖	用途	说明
Docker	运行「初始化应用」与一键启动完整 Kafka 环境	仅在需要使用 Docker 方式对接集群时需要
nvm + Node.js	运行前端开发服务器	Node 版本须与 .nvmrc 一致
pnpm	包管理器	通过 npm install -g pnpm 安装

Node.js 版本以 kafka-ui-react-app/.nvmrc 为准，其内容为 v18.17.1；同时 package.json 的 engines 字段声明了 node: v18.17.1、pnpm: ^8.6.12，建议使用 nvm use 切换到对应版本后再继续。

三、初始化：安装依赖并生成 API 客户端

进入前端子项目目录：

cd ./kafka-ui-react-app

全局安装 pnpm：

npm install -g pnpm

安装项目依赖：

pnpm install

安装完成后，执行代码生成命令，从 OpenAPI 文档生成 TypeScript API 客户端：

pnpm gen:sources

这一步是前端能正常编译的关键。该命令实际执行 rimraf src/generated-sources && openapi-generator-cli generate（见 package.json 的 scripts），其生成规则定义在 kafka-ui-react-app/openapitools.json：

• 生成器为 typescript-fetch，输出目录 src/generated-sources；
• 输入契约文件为 ../kafka-ui-contract/src/main/resources/swagger/kafka-ui-api.yaml，即后端模块 kafka-ui-contract 维护的 OpenAPI 规范，前后端接口契约由此统一；
• 额外属性启用 typescriptThreePlus、supportsES6、withInterfaces，并将 object 类型映射为 any。

从源码结构看，src/lib/api.ts 中所有 *ApiClient 均直接 import 自 generated-sources，因此首次克隆仓库后必须先生成该目录，否则项目无法通过类型检查与编译。

四、启动开发服务器

4.1 方式一：开发代理模式（推荐本地联调）

前端开发服务器（Vite，端口 3000）需要将 API 请求转发到后端。创建或更新项目根目录下的 .env.local 文件，写入你的 API 服务地址：

VITE_DEV_PROXY= https://api.server # your API server

然后启动：

pnpm dev

VITE_DEV_PROXY 的作用可以从 vite.config.ts 中得到印证：Vite 在 development 模式下读取该环境变量，并将 /api 与 /actuator/info 两个前缀的请求代理到目标地址（changeOrigin: true、secure: false），同时自动打开浏览器（open: true）。也就是说，前端代码中所有以 /api 开头的请求（经 BASE_PARAMS 配置的基础路径）都会被转发至你在 .env.local 中指定的后端服务，实现前后端分离开发。

4.2 方式二：Docker 一键启动完整环境

若本地没有现成的后端与 Kafka 集群，可使用仓库提供的 Docker Compose 一键拉起全套依赖。该方式必须从仓库根目录执行：

docker-compose -f ./documentation/compose/kafka-ui.yaml up

documentation/compose/kafka-ui.yaml 定义的服务包括：

• kafka-ui：直接以 provectuslabs/kafka-ui:latest 镜像运行，映射 8080:8080；
• kafka0、kafka1：两个单节点 KRaft 模式的 Confluent Kafka 7.2.1 broker，分别暴露 9092、9093 端口并开启 JMX（9997/9998）；
• schemaregistry0、schemaregistry1：两个 Schema Registry 实例；
• kafka-connect0：Kafka Connect 服务（8083）；
• kafka-init-topics：自动创建 second.users、second.messages、first.messages 等示例主题，并向 second.users 写入 ./data/message.json 中的示例消息。

UI 容器通过环境变量注入了两个集群的 KAFKA_CLUSTERS_0_NAME: local / KAFKA_CLUSTERS_1_NAME: secondLocal、bootstrap servers、metrics 端口、Schema Registry 地址及 Kafka Connect 地址，并开启 DYNAMIC_CONFIG_ENABLED: 'true' 支持动态配置集群。

需要注意的是：采用 Docker 方式时，请确保没有任何 .env* 文件包含 DEV_PROXY 变量（README 中明确要求 none of the .env* files contain DEV_PROXY），以免开发代理与 Docker 环境产生冲突。之后仍从 kafka-ui-react-app 目录执行：

pnpm dev

此时前端开发服务器（http://localhost:3000）会通过 VITE_DEV_PROXY 指向的 API 地址，或直接访问 Docker 中运行于 8080 端口的 kafka-ui 后端完成数据交互。

4.3 两种方式的选择建议

对比项	开发代理模式	Docker 方式
适用场景	已有独立后端 API 服务，需前后端联调	需要一套完整的 Kafka + Schema Registry + Connect 环境
配置要点	在 .env.local 写入 VITE_DEV_PROXY	从根目录执行 compose，且 .env* 中不得有 DEV_PROXY
依赖	Node/pnpm + 后端服务	Docker + Node/pnpm

五、常用脚本与质量保障

package.json 中定义的 scripts 覆盖了开发全流程：

• pnpm dev / pnpm start：启动 Vite 开发服务器；
• pnpm build：执行 vite build 生产构建，产物输出到 build 目录（见 vite.config.ts）；
• pnpm preview：本地预览生产构建产物；
• pnpm gen:sources：重新生成 OpenAPI 客户端；
• pnpm lint / pnpm lint:fix / pnpm lint:CI：ESLint 检查，CI 模式要求 --max-warnings=0；
• pnpm tsc：TypeScript 类型检查（--pretty --noEmit）；
• pnpm test / pnpm test:coverage / pnpm test:CI：Jest 单元测试，CI 模式输出 Sonar 报告并收集覆盖率；
• pnpm deadcode：使用 ts-prune 查找未使用代码（排除 src/generated-sources）。

测试配置见 jest.config.ts：测试根目录为 src，匹配 src/**/__{test,tests}__/**/*.{spec,test}.{js,jsx,ts,tsx}，使用 @swc/jest 转换 TS/TSX，环境为 jsdom，覆盖率统计排除 generated-sources 与 src/lib/fixtures 等目录。仓库中各页面组件（如 Topics/List/__tests__/ListPage.spec.tsx、Connect/List/__tests__/ListPage.spec.tsx 等）均配有相应测试，可作为编写新功能测试的参考范式。

六、常见问题排查

• generated-sources 目录缺失导致编译失败：重新执行 pnpm gen:sources，并确认 kafka-ui-contract 模块下的 OpenAPI 文件存在且后端接口契约未变动；
• Node 版本不匹配：使用 nvm 切换到 .nvmrc 指定的 v18.17.1，否则依赖安装或 Vite 启动可能报错；
• 接口请求 404 / 无法连接后端：确认 .env.local 中 VITE_DEV_PROXY 指向的后端地址正确，且后端（Docker 中的 kafka-ui 或独立 API 服务）已启动、端口可达；
• Docker 方式启动异常：检查是否在根目录执行 compose 命令，并确认脚本文件 documentation/compose/scripts/update_run.sh 随 compose 卷挂载正常。

七、参考链接

• 前端子项目说明：kafka-ui-react-app/README.md
• 构建工具：Vite（README 原链接，本仓库使用的构建工具）
• Docker 一键环境：documentation/compose/kafka-ui.yaml
• 前端构建配置：kafka-ui-react-app/vite.config.ts