企业官网建设流程全解析

Apache Doris Web 管理控制台（ui）开发指南：从环境搭建到构建部署

【免费下载链接】dorisApache Doris is an easy-to-use, high performance and unified analytics database.项目地址: https://gitcode.com/gh_mirrors/dori/doris

本篇指南以 Apache Doris 仓库内 ui/README.md 为核心，系统讲解 Doris Web 管理控制台（Frontend UI）的依赖安装、开发调试、代码规范检查与生产构建全流程，并结合仓库中 ui/package.json、ui/webpack.config.js 及ui/config/、ui/src/下的源码，深入剖析其工程结构、路由组织、请求封装与 devServer 代理等实现细节。读完本文，你将能够独立搭建 Doris 前端开发环境、理解其模块划分，并将构建产物正确集成到 FE 服务中。

一、项目定位与总体概况

Apache Doris 的 Web 管理控制台位于仓库根目录的ui/子目录下，是一个独立的前端工程，负责为 FE（Frontend）提供可视化运维与 SQL 开发界面。该目录内主要包含：

• public/：静态资源目录，存放img/（如background.png、logo.png）、locales/（en-us.json、zh-cn.json国际化文案）等无需参与构建打包的公共文件；
• src/：前端开发主目录，包含页面（pages/）、通用组件（components/）、接口请求（api/）、工具函数（utils/）、路由（router/）与国际化（i18n.tsx）等；
• webpack.config.js：Webpack 配置入口，实际配置由config/目录下的webpack.common.js、webpack.dev.js、webpack.prod.js组合而成；
• package.json：工程元信息与依赖清单，声明了dev、build两个核心 npm script；
• tsconfig.json、postcss.config.js、prettier.config.js：TypeScript、PostCSS 与代码格式化相关配置。

工程采用 TypeScript + React 的技术栈，其核心技术栈约定在 ui/README.md 中有明确说明，详见下文第三节。

二、环境准备与依赖安装

2.1 前置条件

开发前需要确保本机已安装Node.js 与 npm（或全局安装 yarn）。从 ui/package.json 的依赖声明可以看出，工程基于 Webpack 4（webpack ^4.33.0）、React 16（react ^16.13.1）、TypeScript 3.9（typescript ^3.9.3）构建，建议使用与 Webpack 4 兼容的 Node 版本进行开发。

2.2 安装依赖

在ui/目录下执行 npm 安装依赖：

$ npm install

如果本机已安装 yarn，也可以使用 yarn 安装（README 中给出的方式）：

$ npm install -g yarn $ yarn install --pure-lockfile

--pure-lockfile表示不生成yarn.lock文件，仅依据现有 lockfile 精确安装依赖版本，适合在 CI 或已有锁文件的协作环境中使用。两种方式任选其一即可。

依赖清单中，运行时依赖（dependencies）主要包括：

开发依赖（devDependencies）则覆盖了构建工具链：webpack、webpack-dev-server、webpack-cli、webpack-merge、ts-loader、typescript、less/less-loader、eslint、clean-webpack-plugin、mini-css-extract-plugin、html-webpack-plugin等。

三、技术栈约定

ui/README.md 明确约定的技术栈为：

react + react-router-dom + ant-design + rxjs

这套技术栈在源码中有充分体现：

• react-router-dom：路由配置集中在 ui/src/router/index.ts，通过react-router-config风格的路由表统一管理，包含/login、/home、/Playground（含/Playground/import）、/System、/Log、/QueryProfile、/Session、/Configuration以及兜底的 404 页面；ui/src/App.tsx 使用BrowserRouter并设置basename以适配部署子路径；
• ant-design：全局引入antd/dist/antd.css，页面与组件大量使用 antd 的Table、Modal、notification等组件，例如 ui/src/utils/request.tsx 中的登录过期弹窗与成功/失败提示；
• rxjs：在 Playground（SQL 查询工作台）中使用响应式流管理查询上下文，参见ui/src/pages/playground/下的adhoc.context.ts、adhoc.data.ts、adhoc.subject.ts；
• 此外工程还使用TypeScript作为主要开发语言（入口 ui/src/index.tsx），配合ts-import-plugin实现 antd 与 lodash 的按需引入。

四、开发调试：启动 Dev Server

4.1 启动命令

在ui/目录下执行：

$ npm run dev

根据 ui/package.json 中的devscript 定义，实际执行的是：

cross-env NODE_ENV=dev webpack-dev-server --progress --profile --process.env.PRODUCT_MODEL='DEVELOP'

即通过cross-env注入NODE_ENV=dev环境变量，使用webpack-dev-server启动开发服务器。启动后访问：

http://localhost:8030

4.2 devServer 与代理配置

端口 8030 与开发服务器行为定义在 ui/config/webpack.dev.js 中，关键配置如下：

devServer: { historyApiFallback: true, // SPA 路由回退，刷新任意路径都返回 index.html disableHostCheck: true, stats: 'minimal', compress: true, // 开启 gzip 压缩 overlay: true, // 编译错误以遮罩层形式显示在页面 hot: false, host: 'localhost', open: true, // 启动后自动打开浏览器 contentBase: path.join(__dirname, 'dist'), port: 8030, proxy: { '/api': { target: 'http://127.0.0.1:8030', changeOrigin: true, secure: false }, '/rest': { target: 'http://127.0.0.1:8030', changeOrigin: true, secure: false } } }

proxy配置非常关键：开发模式下前端页面与后端 FE 服务分别运行，/api与/rest前缀的请求都会被代理转发到本机8030端口上的 FE HTTP 服务，从而让前端可以直接调用后端接口（如/rest/v1/login、/rest/v1/system、/api/query/internal/...，见 ui/src/api/api.ts）。因此本地开发时通常需要同时启动一个运行在 8030 端口的 FE 进程，才能正常完成登录与数据请求。

4.3 Webpack 配置的分环境组合

ui/webpack.config.js 是配置的组装入口，根据NODE_ENV选择合并后的配置，并用speed-measure-webpack-plugin包裹以输出各模块构建耗时：

switch (process.env.NODE_ENV) { case 'prod': case 'production': config = prodConfig; // webpack.prod.js break; default: config = devConfig; // webpack.dev.js }

公共配置 ui/config/webpack.common.js 包含以下要点：

• 入口与输出：入口为src/index.tsx（见 ui/config/paths.js 的entryApp），输出到dist/目录，文件名为[name].[hash].js；
• 路径别名：通过resolve.alias将Components、Src、Utils、Constants等映射到src/下对应目录，源码中大量使用import request from 'Utils/request'、import {API_BASE} from 'Constants'即依赖此别名；
• TypeScript 处理：.ts/.tsx文件依次经过cache-loader、ts-loader（开启transpileOnly跳过类型检查以提速，并通过ts-import-plugin实现 antd 与 lodash 按需加载）、thread-loader（双 worker 并行编译）；
• 样式处理：.css使用style-loader（dev）/MiniCssExtractPlugin（prod）+css-loader+postcss-loader（autoprefixer、cssnano）；.less区分node_modules内外，对业务代码开启 CSS Modules；
• 拆包优化：splitChunks针对lodash、moment、codemirror及公共node_modules依赖做了独立 chunk 拆分，并单独抽取样式 chunk；
• 插件：HtmlWebpackPlugin（以src/index.html为模板注入脚本与 favicon）、MiniCssExtractPlugin（生产环境抽取 CSS）、CleanWebpackPlugin（每次构建前清理dist/）。

生产配置 ui/config/webpack.prod.js 仅将mode切换为production，交由 Webpack 自动开启压缩与 Tree Shaking。

五、代码规范检查

ui/README.md 中提到，执行git commit时会自动运行 lint 进行语法规则检查。这一机制由package.json中的lint-staged与项目使用的 husky/git hooks 配合实现：

"lint-staged": { "src/**/*.js": ["eslint --fix", "git add"], "*.ts": ["eslint --fix"] }

即提交时对暂存的.js、.ts文件自动执行eslint --fix修复可自动处理的问题并重新git add。这意味着：

• 提交前请确保改动位于src/下且通过 ESLint 检查；
• 无法自动修复的规范问题会阻止提交，需要手动修正后再提交；
• 仓库还提供了 ui/prettier.config.js 统一代码格式化风格。

六、生产构建：Build

6.1 构建命令

执行：

$ npm run build

对应的实际命令为：

cross-env NODE_ENV=prod webpack

构建完成后，产物输出到ui/dist/目录（path: helpers.root('/dist')，见 ui/config/paths.js）。生产模式下 Webpack 会启用mode: production，自动进行代码压缩、混淆与 Tree Shaking，同时MiniCssExtractPlugin将 CSS 抽离为独立文件，配合[name].[hash].js的 hash 文件名实现长效缓存。

6.2 与 FE 服务的集成

构建产物ui/dist/需要被 FE 的 HTTP 服务托管后，才能通过浏览器访问。仓库中webroot/目录（webroot/be/等）即承担了类似静态资源托管的职责；在实际部署中，前端资源会被部署到 FE 对应目录，并配合utils.getBasePath()（见 ui/src/utils/utils.ts）处理多级路径部署场景——getBasePath会从location.pathname中截取最多前 5 段作为 base path，ui/src/App.tsx 将其作为BrowserRouter的basename，ui/src/utils/request.tsx 也会在请求 URL 前拼接该 base path，从而保证前端路由与接口请求在子路径部署时都能正确解析。

七、前端工程目录结构详解

ui/README.md 的 "File introduction" 一节给出了顶层目录职责，结合仓库实际文件可进一步细化：

ui/ ├── public/ # 静态资源（不参与构建） │ ├── img/ # 背景图、Logo 等 │ └── locales/ # en-us.json / zh-cn.json 国际化文案 ├── src/ # 开发主目录 │ ├── api/ # 后端接口封装（api.ts：login、system、log、query 等） │ ├── assets/ # 静态资源（图片等，经 webpack 处理） │ ├── components/ # 通用组件 │ │ ├── codemirror-with-fullscreen/ # 全屏 SQL 编辑器组件 │ │ ├── flatbtn/ # 扁平按钮 │ │ ├── iconfont/ # 图标字体 │ │ ├── loadingwrapper/ # 加载状态包装 │ │ ├── table/ # 通用表格 │ │ └── text-with-icon/ # 带图标文本 │ ├── pages/ # 页面（可含子组件） │ │ ├── 404/ # 404 页面 │ │ ├── backend/ # BE 节点信息（路由中暂被注释） │ │ ├── configuration/ # FE 配置查看 │ │ ├── ha/ help/ # 高可用 / 帮助（路由中暂被注释） │ │ ├── home/ # 首页（硬件信息概览） │ │ ├── layout/ # 整体布局框架 │ │ ├── login/ # 登录页 │ │ ├── playground/ # SQL 查询工作台（含树形库表、查询编辑、数据导入） │ │ ├── query-profile/ # 查询 Profile 查看 │ │ ├── session/ # Session 管理 │ │ └── system/ # 系统信息 │ ├── router/ # 路由表与渲染（index.ts / renderRouter.tsx） │ ├── utils/ # 公共方法（request 封装、工具函数） │ ├── interfaces/ # TypeScript 接口定义（http.interface.ts） │ ├── less/ # 全局样式变量 │ ├── App.tsx # 应用根组件 │ ├── constants.ts # 常量（API_BASE 等） │ ├── i18n.tsx # 国际化初始化 │ ├── index.html / index.tsx # HTML 模板与 JS 入口 │ └── global.d.ts # 全局类型声明 ├── config/ # webpack 配置（common / dev / prod / paths / helpers） ├── webpack.config.js # webpack 配置入口 ├── package.json # 依赖与脚本 ├── tsconfig.json # TypeScript 配置 └── postcss.config.js # PostCSS 配置

各目录职责遵循 README 的约定：src/assets存放经 webpack 处理的静态资源；src/components存放可复用通用组件；src/pages存放各子页面，页面内部可再拆分组件（如playground/下即有content/、data-import/、page-side/、tree/等子模块）；src/utils存放公共方法。

7.1 接口层与请求封装

所有后端调用统一收敛在 ui/src/api/api.ts 中，大致分为两类：

• /rest/v1/*运维接口：login/logOut（Basic Auth）、getHardwareInfo（首页硬件信息）、getSystem、getLog、queryProfile、getSession、getConfig等；
• /api/*查询与导入接口：getDatabaseList（基于API_BASE，见 ui/src/constants.ts 的/api/meta/namespaces/）、doQuery（/api/query/internal/）、doUp（数据上传）等。

请求统一走 ui/src/utils/request.tsx 封装：携带 cookie 凭证（credentials: 'include'）、自动序列化 JSON body、统一处理 401 登录过期（弹出确认框并跳转/login）、根据code/msg字段展示成功或失败提示，并支持tipSuccess、tipError、fullResponse、download等可选行为。

八、常见问题与排障思路

1. npm run dev后页面能打开但请求全部失败：检查本机 8030 端口是否有 FE 服务在运行。devServer 的/api、/rest代理指向http://127.0.0.1:8030，没有后端时所有接口请求都会报错，登录页也无法正常认证。
2. 提交代码被 lint 拦截：lint-staged会在 commit 时对src/**/*.js与*.ts运行eslint --fix，请先本地手动执行 ESLint 检查并修复未自动修复的规范问题，或确认改动文件是否在检查范围内。
3. 构建产物 hash 频繁变化导致缓存失效：这是开发模式的正常现象；生产构建使用[name].[hash].js文件名，业务代码不变时 hash 保持稳定，配合 HTTP 缓存策略即可。
4. 部署到子路径后页面空白或接口 404：需要保证前端资源部署路径与getBasePath()解析规则（取路径前 5 段）一致，前端路由basename与请求 URL 前缀会自动拼接 base path，若部署路径层级过深需重新评估该规则。

九、总结

Apache Doris 的 Web 管理控制台是一个基于React + React Router + Ant Design + RxJS + TypeScript的标准前端工程，通过 Webpack 4 完成开发调试与生产构建。开发流程为：npm install安装依赖 →npm run dev启动 8030 端口开发服务器（配合 FE 后端联调）→ 提交代码时自动执行 ESLint 检查 →npm run build产出dist/静态资源并交由 FE 托管。理解ui/config/下的分环境 Webpack 配置、ui/src/的目录职责划分以及request.tsx/api.ts的请求体系，是二次开发与问题排查的关键。相关配置与源码可继续在仓库中查阅：ui/package.json、ui/config/webpack.common.js、ui/config/webpack.dev.js、ui/src/router/index.ts 与 ui/src/utils/request.tsx。

【免费下载链接】dorisApache Doris is an easy-to-use, high performance and unified analytics database.项目地址: https://gitcode.com/gh_mirrors/dori/doris