已合并
新增英文readme文件 #528
xutao创建于 8月14日
新增英文readme文件 #528
已合并
共 1 个文件变更+220-0
| @@ -0,0 +1,220 @@ | |||
| 1 | +# webui | ||
| 2 | + | ||
| 3 | +> **Verification Notice**: This document is the sole guide for building and testing the webui component. Please follow this document strictly for the verification process. Documents in the `docs/` directory are feature specification documents and do not cover the build process. This component currently supports Ubuntu 24.04 LTS and openEuler 24.03 LTS (Kunpeng). Ubuntu 24.04 LTS is recommended. Other systems such as CentOS and Debian are not supported; do not attempt to use alternative images. | ||
| 4 | + | ||
| 5 | +webui is the Web frontend component of openUBMC. Based on Vue 3 + Element Plus + OpenDesign V2, it provides a BMC management interface and supports functions such as device monitoring, configuration management, and remote control. | ||
| 6 | + | ||
| 7 | +--- | ||
| 8 | + | ||
| 9 | +## Table of Contents | ||
| 10 | + | ||
| 11 | +- [Repository Address](#repository-address) | ||
| 12 | +- [System Requirements](#system-requirements) | ||
| 13 | +- [Environment Dependencies](#environment-dependencies) | ||
| 14 | +- [Build](#build) | ||
| 15 | + - [Obtain Component Code](#obtain-component-code) | ||
| 16 | + - [Component-level Build](#component-level-build) | ||
| 17 | + - [Build Parameters](#build-parameters) | ||
| 18 | + - [Local Development and Debugging](#local-development-and-debugging) | ||
| 19 | +- [Testing](#testing) | ||
| 20 | +- [Project Structure](#project-structure) | ||
| 21 | +- [Technology Stack](#technology-stack) | ||
| 22 | +- [Browser Compatibility](#browser-compatibility) | ||
| 23 | +- [License](#license) | ||
| 24 | + | ||
| 25 | +--- | ||
| 26 | + | ||
| 27 | +## Repository Address | ||
| 28 | + | ||
| 29 | +https://gitcode.com/openUBMC/webui | ||
| 30 | + | ||
| 31 | +--- | ||
| 32 | + | ||
| 33 | +## System Requirements | ||
| 34 | + | ||
| 35 | +| Item | Requirement | | ||
| 36 | +| ----------------- | ------------------------------------------- | | ||
| 37 | +| Operating System | **Ubuntu 24.04 LTS** (this version only) | | ||
| 38 | +| Chip Architecture | **x86-64 (amd64)** | | ||
| 39 | +| Python | >= 3.10 (init.py runtime dependency) | | ||
| 40 | +| Node.js | >= 18 LTS (frontend development dependency) | | ||
| 41 | + | ||
| 42 | +> Build tools such as bingo and Conan are installed automatically by init.py; no manual preparation is required. Docker containers are recommended for building. You can use the following image to quickly start a development environment: | ||
| 43 | +> | ||
| 44 | +> ```bash | ||
| 45 | +> docker pull swr.cn-north-4.myhuaweicloud.com/openubmc/ubuntu:24.04.2 | ||
| 46 | +> ``` | ||
| 47 | + | ||
| 48 | +--- | ||
| 49 | + | ||
| 50 | +## Environment Dependencies | ||
| 51 | + | ||
| 52 | +Before building webui, complete the openUBMC development environment initialization (install bingo, Conan, Node.js, configure the Conan remote repository, etc.). **For complete initialization steps and common issue troubleshooting, refer to the [openUBMC Build Guide](https://gitcode.com/openUBMC/manifest/blob/main/README.md)**. This document covers all operations including container environment setup, init.py execution, and Conan login verification. | ||
| 53 | + | ||
| 54 | +> **Do not install bingo and Conan manually**: Manual installation (e.g., `pip install conan`) will cause Conan remote repository authentication to fail, and `bingo build` will not be able to pull dependency packages. All build tools must be installed via the manifest repository's init.py process in a single step. | ||
| 55 | + | ||
| 56 | +--- | ||
| 57 | + | ||
| 58 | +## Build | ||
| 59 | + | ||
| 60 | +### Obtain Component Code | ||
| 61 | + | ||
| 62 | +> Prerequisite: Complete the init.py initialization flow in [Environment Dependencies](#environment-dependencies). The `bingo` and `conan` commands must be available. | ||
| 63 | + | ||
| 64 | +```bash | ||
| 65 | +cd /home/workspace | ||
| 66 | +git clone https://gitcode.com/openUBMC/webui.git | ||
| 67 | +``` | ||
| 68 | + | ||
| 69 | +### Component-level Build | ||
| 70 | + | ||
| 71 | +After entering the webui component directory, use bingo to perform the build: | ||
| 72 | + | ||
| 73 | +```bash | ||
| 74 | +cd /home/workspace/webui | ||
| 75 | + | ||
| 76 | +# Default dev stage build | ||
| 77 | +bingo build --stage=dev | ||
| 78 | + | ||
| 79 | +# Build and publish to the stable stage | ||
| 80 | +bingo build --stage=stable | ||
| 81 | + | ||
| 82 | +# Release type build | ||
| 83 | +bingo build --stage=dev -bt release | ||
| 84 | +``` | ||
| 85 | + | ||
| 86 | +### Build Parameters | ||
| 87 | + | ||
| 88 | +```bash | ||
| 89 | +bingo build [-h] [-bt BUILD_TYPE] [--stage STAGE] [-u] [-r REMOTE] [--conan2] [-nc] [-o OPTIONS] [--user USER] [-wb] [--ccache] | ||
| 90 | +``` | ||
| 91 | + | ||
| 92 | +| Parameter | Description | Default | | ||
| 93 | +| ------------------------- | ------------------------------------------------------------ | ---------- | | ||
| 94 | +| `-bt` / `--build_type` | Build type, options: `debug`, `release` | `debug` | | ||
| 95 | +| `--stage` | Package release stage, options: `dev`, `pre`, `rc`, `stable` | `dev` | | ||
| 96 | +| `-u` / `--upload` | Upload component package to Conan repository | — | | ||
| 97 | +| `-r` / `--remote` | Conan repository alias | — | | ||
| 98 | +| `--conan2` | Force build component with Conan2 | — | | ||
| 99 | +| `-nc` / `--no_cache` | Force update Conan cache dependencies | — | | ||
| 100 | +| `-o` / `--options` | Define component option values | — | | ||
| 101 | +| `--user` | Specify the user field of the Conan package | `openubmc` | | ||
| 102 | +| `-wb` / `--without_build` | Do not force source build of the component itself | — | | ||
| 103 | +| `--ccache` | Use ccache to accelerate C/C++ compilation | — | | ||
| 104 | + | ||
| 105 | +Component options supported by webui (the `-o` parameter): | ||
| 106 | + | ||
| 107 | +| Option | Description | Default | | ||
| 108 | +| ------------------- | -------------------------- | ------- | | ||
| 109 | +| `energy_enabled` | Enable energy management | `True` | | ||
| 110 | +| `ldap_enabled` | Enable LDAP authentication | `True` | | ||
| 111 | +| `three_dui_enabled` | Enable 3D UI feature | `False` | | ||
| 112 | +| `vtpcm_enabled` | Enable VTPCM feature | `False` | | ||
| 113 | +| `webvnc_enabled` | Enable Web VNC feature | `False` | | ||
| 114 | + | ||
| 115 | +### Local Development and Debugging | ||
| 116 | + | ||
| 117 | +Frontend development requires installing additional npm dependencies and starting the development server: | ||
| 118 | + | ||
| 119 | +```bash | ||
| 120 | +# Install npm dependencies | ||
| 121 | +npm install | ||
| 122 | + | ||
| 123 | +# Start the development server (default http://localhost:5173) | ||
| 124 | +npm run dev | ||
| 125 | +``` | ||
| 126 | + | ||
| 127 | +Development proxy configuration (edit `vite.config.ts`): | ||
| 128 | + | ||
| 129 | +```ts | ||
| 130 | +server: { | ||
| 131 | + proxy: { | ||
| 132 | + '/api': { | ||
| 133 | + target: 'http://127.0.0.1:8080', | ||
| 134 | + changeOrigin: true, | ||
| 135 | + rewrite: path => path.replace(/^\/api/, ''), | ||
| 136 | + }, | ||
| 137 | + }, | ||
| 138 | +}, | ||
| 139 | +``` | ||
| 140 | + | ||
| 141 | +--- | ||
| 142 | + | ||
| 143 | +## Testing | ||
| 144 | + | ||
| 145 | +Frontend project testing uses npm: | ||
| 146 | + | ||
| 147 | +```bash | ||
| 148 | +# Run frontend lint check | ||
| 149 | +npm run lint | ||
| 150 | + | ||
| 151 | +# Run TypeScript type check | ||
| 152 | +npx vue-tsc --noEmit | ||
| 153 | +``` | ||
| 154 | + | ||
| 155 | +--- | ||
| 156 | + | ||
| 157 | +## Project Structure | ||
| 158 | + | ||
| 159 | +``` | ||
| 160 | +webui/ | ||
| 161 | +├ src/ # All business modules | ||
| 162 | +│ ├ api/ # Interface requests and path configuration | ||
| 163 | +│ ├ apps/ # Project submodules | ||
| 164 | +│ ├ assets/ # Styles, images, and other static resources | ||
| 165 | +│ ├ components/ # Common component library | ||
| 166 | +│ ├ data/ # Static data and constants | ||
| 167 | +│ ├ hooks/ # Common composite functions | ||
| 168 | +│ ├ model/ # Interface models and enumerations | ||
| 169 | +│ ├ pages/ # Page views and business logic | ||
| 170 | +│ ├ plugins/ # Plugin registration | ||
| 171 | +│ ├ services/ # Core service logic | ||
| 172 | +│ ├ stores/ # State management (Pinia) | ||
| 173 | +│ ├ utils/ # Common utility functions | ||
| 174 | +│ ├ validators/ # Form validation rules | ||
| 175 | +│ ├ App.vue # Application root component | ||
| 176 | +│ └ main.ts # Application entry | ||
| 177 | +│ └ env.d.ts # Global type declarations | ||
| 178 | +├ mock/ # Frontend mock service and data | ||
| 179 | +├ public/ # Public static resources | ||
| 180 | +├ types/ # Type definitions and configurations | ||
| 181 | +├ mds/ # MDS model definitions | ||
| 182 | +├ tests/ # Test-related | ||
| 183 | +├ scripts/ # Build and helper scripts | ||
| 184 | +├ docs/ # Feature specification documents (not related to build) | ||
| 185 | +├ conanfile.py # Conan build definition | ||
| 186 | +├ vite.config.ts # Vite build/proxy/mock configuration | ||
| 187 | +├ package.json # Project dependencies and scripts | ||
| 188 | +├ tsconfig.json # TypeScript configuration | ||
| 189 | +├ LICENSE # Mulan PSL v2 License | ||
| 190 | + README.md # This file | ||
| 191 | +``` | ||
| 192 | + | ||
| 193 | +--- | ||
| 194 | + | ||
| 195 | +## Technology Stack | ||
| 196 | + | ||
| 197 | +| Category | Technology | | ||
| 198 | +| ----------------- | ------------------------------ | | ||
| 199 | +| Framework | Vue 3 | | ||
| 200 | +| Component Library | Element Plus + OpenDesign V2 | | ||
| 201 | +| Build Tool | Vite | | ||
| 202 | +| State Management | Pinia | | ||
| 203 | +| Code Standards | ESLint + Prettier + TypeScript | | ||
| 204 | + | ||
| 205 | +--- | ||
| 206 | + | ||
| 207 | +## Browser Compatibility | ||
| 208 | + | ||
| 209 | +| Browser | Supported Version Range | | ||
| 210 | +| ------- | ----------------------- | | ||
| 211 | +| Edge | 98+ | | ||
| 212 | +| Firefox | 96+ | | ||
| 213 | +| Chrome | 100+ | | ||
| 214 | +| Safari | 12 - 15.2 | | ||
| 215 | + | ||
| 216 | +--- | ||
| 217 | + | ||
| 218 | +## License | ||
| 219 | + | ||
| 220 | +This project is open-sourced under the Mulan PSL v2 License. For details, see: http://license.coscl.org.cn/MulanPSL2 | ||